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.
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, reason}
. {:eos, :closed}
is
currently the only implemented end-of-stream reason and it occurs when
the connection is severed between Spear and the EventStoreDB. 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.
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, :closed}