Spear.subscribe
subscribe
, go back to Spear module for more information.
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 from0
will first return the event numbered1
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, orSpear.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 thestream_name
is:all
. SeeSpear.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 rawReadResp
records or decoded intoSpear.Event.t/0
s: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}