Spear.subscribe

You're seeing just the function subscribe, go back to Spear module for more information.
Link to this function

subscribe(conn, subscriber, stream_name, opts \\ [])

View Source (since 0.1.0)

Specs

subscribe(
  connection :: Spear.Connection.t(),
  subscriber :: pid() | GenServer.name(),
  stream_name :: String.t() | :all,
  opts :: Keyword.t()
) :: {:ok, subscription_reference :: reference()} | {:error, any()}

Subscribes a process to an EventStoreDB stream

Unlike read_stream/3 or stream!/3, this function does not return an enumerable. Instead the subscriber process is signed up to receive messages for subscription events. Events are emitted in order as info messages with the signature

Spear.Event.t() | Spear.Filter.Checkpoint.t()

or if the raw?: true option is provided, Spear.Records.Streams.read_resp/0 records will be returned in the shape of

{subscription :: reference(), Spear.Records.Streams.read_resp()}

This function will block the caller until the subscription has been confirmed by the EventStoreDB.

When the subscription is terminated, the subscription process will receive a message in the form of {:eos, subscription, reason}. {:eos, subscription, :closed} is emitted when the connection between EventStoreDB and subscriber is severed and {:eos, subscription, :dropped} is emitted when the EventStoreDB explicitly drops a subscription. If this message is received, the subscription is considered to be concluded and the subscription process must re-subscribe from the last received event or checkpoint to resume the subscription. subscription is the reference returned by this function.

Events can be correlated to their subscription via the subscription reference returned by this function. The subscription reference is included in Spear.Event.metadata.subscription, Spear.Filter.Checkpoint.subscription, and in the {:eos, subscription, reason} tuples as noted above.

Subscriptions can be gracefully shut down with Spear.cancel_subscription/3. The subscription will be cancelled by the connection process if the subscriber process exits.

Options

  • :from - (default: :start) the EventStoreDB stream revision from which to read. Valid values include :start, :end, any non-negative integer representing the event number revision in the stream and events. Event numbers are exclusive (e.g. reading from 0 will first return the event numbered 1 in the stream, if one exists). :start and :end are treated as inclusive (e.g. :start will return the first event in the stream). Events and checkpoints (Spear.Event.t/0, ReadResp records, or Spear.Filter.Checkpoint.t/0) can also be supplied and will be treated as exclusive.
  • :filter - (default: nil) the server-side filter to apply. This option is only valid if the stream_name is :all. See Spear.Filter for more information.
  • :resolve_links? - (default: true) whether or not to request that link references be resolved. See the moduledocs for more information about link resolution.
  • :timeout - (default: 5_000) the time to wait for the EventStoreDB to confirm the subscription request.
  • :raw? - (default: false) controls whether the events are sent as raw ReadResp records or decoded into Spear.Event.t/0s
  • :credentials - (default: nil) a two-tuple {username, password} to use as credentials for the request. This option overrides any credentials set in the connection configuration, if present. See the Security guide for more details.

Examples

# say there are 3 events in the EventStoreDB stream "my_stream"
iex> {:ok, sub} = Spear.subscribe(conn, self(), "my_stream", from: 0)
{:ok, #Reference<0.1160763861.3015180291.51238>}
iex> flush
%Spear.Event{} # second event
%Spear.Event{} # third event
:ok
iex> Spear.cancel_subscription(conn, sub)
:ok

iex> {:ok, sub} = Spear.subscribe(conn, self(), :all, filter: Spear.Filter.exclude_system_events())
iex> flush
%Spear.Filter.Checkpoint{}
%Spear.Filter.Checkpoint{}
%Spear.Event{}
%Spear.Event{}
%Spear.Filter.Checkpoint{}
%Spear.Event{}
%Spear.Filter.Checkpoint{}
:ok
iex> GenServer.call(conn, :close)
{:ok, :closed}
iex> flush
{:eos, #Reference<0.1160763861.3015180291.51238>, :closed}