Decree.Aggregate behaviour (decree v0.1.0)

Copy Markdown View Source

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
end

every 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
end

An 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:

  1. The route's before_execute, as on any route.
  2. authorize/2 on 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 a command_id is live. An empty stream has nothing to own yet: a create's own guards stay in execute/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 before authorize/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 runs authorize/2; otherwise the dispatch answers the rebuild's or the retry's error.
  3. 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.
  4. execute/2, only for a command the window found open.
  5. The append, always under the condition the read built, whose target is the aggregate.

The answers:

  • {:error, :duplicate_command} - a match inside the window, from this command's kind on this stream. Nothing is appended and execute/2 is 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} - the command family, or a family the route's rule requires, is not enabled by the tag index facts, as "Index facts" in Decree.Decision says: 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 usable command_id or 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

authorize(state, command)

(optional)
@callback authorize(state :: struct(), command :: struct()) :: :ok | {:error, term()}

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

check_command_window(application, command)

@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.

command_window_ms(aggregate_module)

@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".

prune_snapshots(application, aggregate_module)

@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.

snapshot_options(application, aggregate_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.

warm_snapshot(application, aggregate_module, aggregate_uuid)

@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.