Use the event store configured for a Decree application: the Decree.Store module named by
event_store: [event_store: MyApp.EventStore] in its config, called with the store process's
name:. The framework's Decree.EventStore.EventData, RecordedEvent and SnapshotData are
mapped to the store's structs and back here.
Telemetry Events
Adds telemetry events for the following functions. Events are emitted in the form
[:decree, :event_store, event] with their spannable postfixes (start, stop, exception)
- ack_event/3
- append_to_stream/4
- append_to_streams/3
- delete_snapshot/2
- delete_subscription/3
- prune_snapshots/3
- read_query/3
- read_snapshot/3
- read_tags/3
- record_snapshot/2
- stream_forward/2
- stream_forward/3
- stream_forward/4
- subscribe/2
- subscribe_to/5
- subscribe_to/6
- unsubscribe/2
read_query/3's span never fires exception, and a failure stops it with error: its doc
says why.
Summary
Functions
Acknowledge receipt and successful processing of the given event received from a subscription to an event stream. If the event is part of a batch, every event that precedes it in the batch is acknowledged as well.
Append one or more events to a stream atomically.
Append events to several streams atomically, in one statement.
Appends one or more events to a stream atomically, as append_to_stream/5 does, with no
telemetry event.
The targets the application's running event store's conditional_appends declares, or []
if it declares none.
The stream prefixes the application's event store declares as deletable.
Delete a previously recorded snapshot for a given source, at every snapshot version.
Delete an existing subscription.
Delete the snapshots of a source type whose snapshot version is below the given one.
See Decree.Aggregate.prune_snapshots/2.
Reads the events matching a query across every stream, in one statement, each upcast as
stream_forward/4 upcasts it.
Read a snapshot, if available, for a given source at a snapshot version.
Reads the last event of the given stream, upcast as stream_forward/4 upcasts.
Reads the tags of the events at the given $all positions, in one statement.
Record a snapshot of the data and metadata for a given source
Streams events from the given stream, in the order in which they were originally written.
Create a transient subscription to a single event stream.
Create a persistent subscription to an event stream.
Unsubscribe an existing subscriber from event notifications.
Types
@type application() :: Decree.Application.t()
@type config() :: Keyword.t()
@type error() :: term()
@type expected_version() :: :any_version | :no_stream | :stream_exists | non_neg_integer()
@type source_uuid() :: String.t()
@type start_from() :: :origin | :current | integer()
@type stream_uuid() :: String.t()
@type subscriber() :: pid()
@type subscription() :: any()
@type subscription_name() :: String.t()
Functions
Acknowledge receipt and successful processing of the given event received from a subscription to an event stream. If the event is part of a batch, every event that precedes it in the batch is acknowledged as well.
Append one or more events to a stream atomically.
The store's answers come back unchanged (see Decree.Store.append_to_stream/4).
{:error, :wrong_expected_version} makes an aggregate rebuild its state and retry the
command while it has attempts left. A failure of the append statement other than its domain
answers is {:error, %Decree.Store.AppendError{}}, classified :unavailable, :retryable
or :rejected, and the aggregate returns it as the command's error. After an
:unavailable one the aggregate stops, so the next command rebuilds its state from the
stream (see Decree.Store.AppendError).
With returning: :append_result in opts, success answers
{:ok, %Decree.Store.AppendResult{}} instead of :ok.
Append events to several streams atomically, in one statement.
appends is a list of {stream_uuid, expected_version, events}, one per stream. The
options and answers are those of Decree.Store.append_to_streams/2: with condition: an
event past its after matching its items answers {:error, :append_condition_failed}, and
with returning: :append_result success answers {:ok, %Decree.Store.AppendResult{}}.
Appends one or more events to a stream atomically, as append_to_stream/5 does, with no
telemetry event.
It answers what append_to_stream/5 answers, and a raise, an exit or a throw reaches the
caller as it would there.
The targets the application's running event store's conditional_appends declares, or []
if it declares none.
It answers from the config the store parsed as it started, so it agrees with what the store
refuses. An application with a rule route or a windowed aggregate calls this as it starts,
right after its store has, and an application with neither never calls it. See "Two
declarations" in Decree.Decision.Rule.
The stream prefixes the application's event store declares as deletable.
A store without enable_hard_deletes answers [], whatever it declares: no delete can reach
a stream there.
Delete a previously recorded snapshot for a given source, at every snapshot version.
Delete an existing subscription.
Example
:ok = Decree.EventStore.delete_subscription(MyApp, :all, "Example")
Delete the snapshots of a source type whose snapshot version is below the given one.
See Decree.Aggregate.prune_snapshots/2.
Reads the events matching a query across every stream, in one statement, each upcast as
stream_forward/4 upcasts it.
See Decree.Store.read_query/2 for the items, options and answers. The result's
events are Decree.EventStore.RecordedEvents.
Its span covers the store's answer, and the upcast runs after it stops. A raise, an exit or
a throw from either, the store's deserializing and the mapping included, reaches
the caller as it was raised, and no telemetry event holds it. The span never fires its
exception event. A failure inside it stops it with error in the stop metadata, the kind
alone: :error, :exit or :throw. A read that answered stops with no error.
Read a snapshot, if available, for a given source at a snapshot version.
A source has one row per snapshot version, so code at another version never reads or
overwrites this one's. A nil snapshot_version is refused with
{:error, :invalid_snapshot_version}.
Reads the last event of the given stream, upcast as stream_forward/4 upcasts.
Answers {:ok, recorded_event}, or {:error, :stream_not_found} for a stream that never
existed and for one hard-deleted, which nothing tells apart, or {:error, reason} for a read
that failed. A failed read is never :stream_not_found.
Its cost does not grow with the stream.
Reads the tags of the events at the given $all positions, in one statement.
Answers as Decree.Store.read_tags/2 does: a position with no row is absent, and so are
tags of a kind the store declares deletable and every tag of an event of a type it declares.
Record a snapshot of the data and metadata for a given source
Streams events from the given stream, in the order in which they were originally written.
Create a transient subscription to a single event stream.
The event store will publish any events appended to the given stream to the
subscriber process as an {:events, events} message.
The subscriber does not need to acknowledge receipt of the events.
Create a persistent subscription to an event stream.
To subscribe to all events appended to any stream use :all as the stream
when subscribing.
The event store will remember the subscribers last acknowledged event. Restarting the named subscription will resume from the next event following the last seen.
Once subscribed, the subscriber process should be sent a
{:subscribed, subscription} message to allow it to defer initialisation
until the subscription has started.
The subscriber process will be sent all events persisted to the stream. It
will receive a {:events, events} message for each batch of events persisted
for a single aggregate.
The subscriber must ack each received, and successfully processed event, using
Decree.EventStore.ack_event/3.
Examples
Subscribe to all streams:
{:ok, subscription} =
Decree.EventStore.subscribe_to(MyApp, :all, "Example", self(), :current)Subscribe to a single stream:
{:ok, subscription} =
Decree.EventStore.subscribe_to(MyApp, "stream1", "Example", self(), :origin)
Unsubscribe an existing subscriber from event notifications.
This will not delete the subscription.
Example
:ok = Decree.EventStore.unsubscribe(MyApp, subscription)