What an aggregate module declares about itself, read where the aggregate is defined.
Snapshots
defmodule MyApp.ExampleAggregate do
use Decree.Aggregate, snapshot: [every: 10, version: 1]
defstruct [:id, items: []]
# execute/2 and apply/2 as for any aggregate
endevery is how many events the aggregate takes between two snapshots, a positive integer.
version is the version of the snapshot's shape, a non-negative integer, 1 when left out.
Both are integer literals, checked when the module compiles: a missing or bad every, a
bad version, an unknown key under snapshot: or an unknown option fails the build.
use Decree.Aggregate with no snapshot: declares nothing.
A module that declares snapshot: takes its options from here and not from the
application's snapshotting: config, which remains the fallback for a module that does
not, until a later release removes it. A module in both logs a warning when the
application starts, and its config entry is ignored. snapshot_options/2 answers the
options in force. See "Snapshotting" in Decree.Aggregates.Aggregate for how a snapshot
is taken and read.
Snapshot versions
The store keeps one row per stream and snapshot version. Code at version 1 and code at
version 2 read and write their own rows, so during a rollout neither overwrites the
other's, and a version bump folds the stream from its events for the new version until a
row exists for it. warm_snapshot/3 records that row ahead of the first command.
prune_snapshots/2 deletes the rows of the versions below the declared one: run it once
no running code reads an older version.
Command window
defmodule MyApp.Account do
use Decree.Aggregate, command_window: [ms: 300_000]
defstruct [:account_id, :owner]
def authorize(%__MODULE__{owner: owner}, %{actor: actor}) when actor != owner,
do: {:error, :unauthorized}
def authorize(%__MODULE__{}, _command), do: :ok
# execute/2 and apply/2 as for any aggregate
endAn aggregate that declares a command window answers a repeat of a command_id from the
store's command index, as a Decree.Decision does, and not from its state. ms is the
window's length in milliseconds, a positive integer literal, checked when the module
compiles: a missing or bad ms, an unknown key under command_window:, or a module with no
public authorize/2 fails the build. The length lives on the definition alone: no config is
read and there is no default. command_window_ms/1 answers it. A module with no
command_window: has no window: none of what follows runs for it, and authorize/2 is never
called.
authorize/2 holds the aggregate's admission, ownership and authorization guards, and
answers :ok or {:error, reason}. In the aggregate's process each attempt at a command runs,
in this order:
- The route's
before_execute, as on any route. authorize/2on the state, only when the stream is not empty. Its refusal is the answer as it stands, with nothing read: an actor who may not ask never learns that acommand_idis live. An empty stream has nothing to own yet: a create's own guards stay inexecute/2. The emptiness is this process's state, so a process that has not yet received an event another pod appended to its stream reads the window beforeauthorize/2, and can answer a duplicate or a reused id ahead of a refusal, appending nothing. An append on that stale state loses its expected version and appends nothing: after a rebuild that succeeds, and while attempts remain, the next attempt runsauthorize/2; otherwise the dispatch answers the rebuild's or the retry's error.- One read of the command item (
command:<command_id>) and the tag index item, with the route's rule's items in the same read when the route has a rule, and the classification of a decision's step 7 with this window, on an empty stream too: a reuse on another stream needs no state to see. execute/2, only for a command the window found open.- The append, always under the condition the read built, whose
targetis the aggregate.
The answers:
{:error, :duplicate_command}- a match inside the window, from this command's kind on this stream. Nothing is appended andexecute/2is not called.{:error, :reused_command_id}- a match inside the window from another command kind, or on another stream (the route's stream tag is the scope). Nothing is appended.{:error, :tag_index_not_enabled}- thecommandfamily, or a family the route's rule requires, is not enabled by the tag index facts, as "Index facts" inDecree.Decisionsays: a resend refuses as a new command does.{:error, :command_id_required},{:error, :invalid_command_id}or{:error, :invalid_aggregate_identity}for a direct call that bypassed the router and carries no usablecommand_idor stream tag.- otherwise what the command answers on any route.
The window's semantics are a decision's: the stamp and read_at are both the database's
clock, the edge is outside, a negative age is inside, and after the window the same id is a
new command and appends. Two writers racing one command_id both read the window open, and
one commits: on the same stream the other loses its expected version, rebuilds and reads
again, and is the duplicate; on another stream of the same kind its condition fails, it reads
again, and the id is reused. Neither answers a store's atom while attempts remain. A route
with a rule counts the command item against the rule's max_items; a route with none takes a
rule's default bounds (16 items, 48 probes, 1,000 matched events, 100 new events per batch).
A host moving an aggregate onto this window from one timed by its own pods' clocks runs both
through a rolling deploy. A new pod refuses every resend an old pod would when ms is at
least the old window plus twice the largest offset between a pod's clock and the database's:
the old pod stamps before its commit, so the time between only shortens the age the database
measures. The host knows the old window, so the host's test holds that floor.
An application checks a windowed aggregate as it starts: every one it routes must be a target
of its event store's conditional_appends: [targets: [...]], and every route to one must
give its stream an entity tag, so an opaque identity, or a function identity with no
stream_tag:, raises an ArgumentError and the application does not start. A declared
target that declares a window draws no warning. A router outside the application is not
checked, and its dispatch answers the store's {:error, :undeclared_conditional_target}.
check_command_window/2 is the same read and classification for a host's facade, before its
business proofs: the probe reads the index, and the dispatch's condition still decides under
the store's lock.
[:decree, :decision, :read] fires once per attempt that read and passed the index check, and
[:decree, :decision, :retry] for a failed condition or a command match only a rule's second
read has (:new_command_match), as on a rule route. Their decision is
the route's rule, or the aggregate's module on a route with none. See
Decree.Decision.Rule.
Summary
Callbacks
An aggregate's admission, ownership and authorization guards, required of a module that
declares command_window:. See "Command window". Called on an existing stream only, before
the window is read, and never for a module that declares no window.
Functions
What a dispatch of command would answer from its aggregate's command window now, read before
a host's own business proofs: :ok, {:error, :duplicate_command},
{:error, :reused_command_id}, {:error, :tag_index_not_enabled}, or the refusal a dispatch
gives first, such as {:error, :command_id_required}, {:error, :invalid_command_id} or
{:error, :invalid_aggregate_identity}.
The length of aggregate_module's command window in milliseconds, as its definition declares
it (use Decree.Aggregate, command_window: [ms: n]), or nil for a module that declares none
or does not use Decree.Aggregate. No config is read, and there is no default length. See
"Command window".
Deletes the module's snapshot rows whose version is below its declared one.
The snapshot options in force for aggregate_module in application.
Records a snapshot of an aggregate's stream at its head, for the declared version.
Callbacks
An aggregate's admission, ownership and authorization guards, required of a module that
declares command_window:. See "Command window". Called on an existing stream only, before
the window is read, and never for a module that declares no window.
Functions
@spec check_command_window(Decree.Application.t(), struct()) :: :ok | {:error, term()}
What a dispatch of command would answer from its aggregate's command window now, read before
a host's own business proofs: :ok, {:error, :duplicate_command},
{:error, :reused_command_id}, {:error, :tag_index_not_enabled}, or the refusal a dispatch
gives first, such as {:error, :command_id_required}, {:error, :invalid_command_id} or
{:error, :invalid_aggregate_identity}.
It resolves the command's route through the application's router, computes the stream tag
as that route's dispatch does, and reads and classifies through the code the aggregate's
process runs, the window's items alone: on a rule route the rule's items are the dispatch's.
It reads the command index only. It does not fold the aggregate's state or call
authorize/2: a host that needs that order runs its own fold and authorize/2 first. And it
decides nothing: the dispatch's condition still decides under the store's lock, so a racing
writer can commit between the probe and the dispatch.
The command is read as sent, before any middleware of the router's own. Raises an
ArgumentError for a command the application routes nowhere, and for one whose route reaches
a decision, or an aggregate that declares no command_window:: a probe that sees no window is
a wiring bug.
@spec command_window_ms(module()) :: pos_integer() | nil
The length of aggregate_module's command window in milliseconds, as its definition declares
it (use Decree.Aggregate, command_window: [ms: n]), or nil for a module that declares none
or does not use Decree.Aggregate. No config is read, and there is no default length. See
"Command window".
@spec prune_snapshots(Decree.Application.t(), module()) :: {:ok, non_neg_integer()} | {:error, term()}
Deletes the module's snapshot rows whose version is below its declared one.
The rows are found by the module's source type, as the configured
Decree.EventStore.TypeProvider names its state. Run it once no running code reads an
older version: a pod still at an older version would fold from events on every start.
Answers {:ok, count}, or {:error, :snapshotting_not_configured} when snapshots are not
enabled for the module.
@spec snapshot_options(Decree.Application.t(), module()) :: keyword()
The snapshot options in force for aggregate_module in application.
The definition's (use Decree.Aggregate, snapshot: ...) when the module declares them;
otherwise the application's snapshotting: config entry for the module; [] when neither
enables snapshots. Answers [snapshot_every: every, snapshot_version: version], with the
version 1 when the config entry leaves it out.
@spec warm_snapshot(Decree.Application.t(), module(), String.t()) :: {:ok, :recorded | :current | :empty} | {:error, term()}
Records a snapshot of an aggregate's stream at its head, for the declared version.
Folds the stream as an aggregate starting would (from this version's row, if there is one, and the events after it) without starting an aggregate process, then:
{:ok, :empty}- the stream has no events, and nothing is recorded;{:ok, :current}- this version's row is already at the head;{:ok, :recorded}- a row at the head is recorded, through the same path an aggregate's own snapshot takes, so personal state is encrypted.
It records whatever every says: the caller chooses which streams to warm. Answers
{:error, :snapshotting_not_configured} when snapshots are not enabled for the module,
{:error, :key_unknown} or {:error, :unknown_event_type} when the fold refuses (see
Decree.Aggregates.Aggregate), or the error that stopped the record.