Fact.CatchUpSubscription behaviour (Fact v0.2.0)

Behaviour and helper implementation for catch-up subscriptions.

A catch-up subscription replays historical events from a source up to the current high-water mark, delivers them to a subscriber, and then switches into live mode to stream new events as they arrive.

This module defines the callback contract and provides a __using__/1 macro that implements the common GenServer lifecycle:

• :init phase — the subscriber is monitored and the implementation

subscribes to the event source.

• The high-water mark is read and a replay is performed from the

starting position up to that point.

• Any events that arrive during replay are buffered and delivered

after replay completes.

• When catch-up finishes, the subscriber receives :caught_up and the

subscription transitions to live mode.

Implementations provide the mechanics for subscription and replay by defining the required callbacks, while optional hooks allow customization of state and position handling.

Summary

Callbacks

get_position(state, message)

high_water_mark(state)

on_init(state)

replay(state, from, to, deliver_fun)

subscribe(state)

Callbacks

get_position(state, message)

@callback get_position(state :: term(), message :: term()) :: Fact.event_position()

high_water_mark(state)

@callback high_water_mark(state :: term()) :: Fact.event_position()

on_init(state)

@callback on_init(state :: term()) :: term()

replay(state, from, to, deliver_fun)

@callback replay(
  state :: term(),
  from :: Fact.read_position_option(),
  to :: Fact.event_position(),
  deliver_fun :: (term() -> any())
) :: :ok