What an aggregate's append has to check beyond its own stream.
An aggregate decides over its stream, and a rule such as one holder per address spans many.
A rule names what to read. The aggregate reads it for one command, execute/2 sees what the
read answered, and the append goes in on the aggregate's own stream under a condition: it
fails if anything the rule read about has appeared since. The aggregate keeps its process,
its stream, its expected version and its state.
defmodule EmailRule do
use Decree.Decision.Rule
def query(%RegisterUser{digest: nil}, _tag_context), do: []
def query(%RegisterUser{digest: digest}, _tag_context) do
[[types: ["Elixir.UserRegistered"], tags: ["email:" <> digest]]]
end
def followup_query(%RegisterUser{}, _tag_context, registrations) do
for %UserRegistered{user_id: user_id} <- registrations do
[types: ["Elixir.UserErased"], tags: ["user:" <> user_id]]
end
end
endA route names the rule, and the command names a place for what the read answers:
defmodule RegisterUser do
defstruct [:command_id, :user_id, :digest, :rule_result]
end
dispatch RegisterUser, to: User, identity: :user_id, rule: EmailRule
def execute(%User{}, %RegisterUser{rule_result: %Result{events: events}} = command) do
case holders(events) do
[] -> %UserRegistered{user_id: command.user_id, digest: command.digest}
[_holder | _] -> {:error, :email_taken}
end
endThe route is per command, so the aggregate's other commands stay plain. See "Two declarations" for the store's half.
Callbacks
query/2names what to read: a list of items,[]for nothing to check, or{:error, reason}.followup_query/3, optional, names a second read that depends on what the first found: a list of items,[]to skip it, or{:error, reason}.index_families/0, optional, says which tag kinds hold digests. See "Required tags".
Items are those of Decree.Decision, with two differences. replay: true answers
{:error, :invalid_query}, because a rule has no scope to hold one to. And a rule's item may
name key:, any term, once: it says which item matched an event (see "What rides"). A second
key: in one item answers {:error, :invalid_query}, with no statement. Both callbacks may run
several times for one dispatch, so they must have no side effects. They run in the aggregate's
process and hold up its mailbox, as a rebuild does.
The build fails on anything a rule does not have: evolve/2, decide/2, admit/2,
scope_tags/1, initial_state/0, command_window_ms/0, handle/2, create: and
activation:.
What a dispatch does
In the aggregate's process, after before_execute, on each attempt:
- Call
query/2. Its error is the answer. Refuse an item naming no types, areplay: trueitem, and more items or probes than the bounds allow. Read the items with the index item.[]skips to step 4 with no statement and no index check, and step 5 is then the batch bound and a plain append. - Call
followup_query/3if it is defined, with the events the first read matched, those the rule lists decrypted. Check both bounds again across both reads, read the items with the index item, and merge by position. The first read'safterstands for both. More matched events thanmax_events, both reads together, refuses. - Check the index as "Index facts" in
Decree.Decisionsays, on the facts' tags the reads returned, with nocommandrequirement: a family the rule's items require with no enabled index answers{:error, :tag_index_not_enabled}, beforeexecute/2. Keep the events the rule's own items matched, and decrypt the ones it lists. - Call
execute/2with those events on a local copy of the command. Everything after that is the aggregate's as on any other route:apply/2, preparing, tags. - Refuse more new events than
max_batch_events, compare the digests and require the tags, as "Required tags" says, and append at the expected version under the condition. Its items are the rule's own from both reads and the index item, and itsafteris the first read's: the store's head at that read, and never 0 on an empty store. After[]there is no condition: past the bound, the append is the one a route with no rule makes, with no digest comparison and no required tags but the event's own.
So an event committed after the first read, the gap between the two reads included, fails
the append if it matches. An after taken from the second read would miss what landed in
that gap.
Fold, admit/2, classification, the command window and scope checks do not run: those are a
decision's. A rule's reads have no command item, and an aggregate keeps its own "already
exists" guard, so a command_id reused across two streams behaves as it does on any
aggregate route. On an aggregate that declares a command window, the command item joins the
rule's items in the same read and condition, and the window classifies: see "Command window"
in Decree.Aggregate. A [] from query/2 there still reads the window. A rule reads through a decision's path, with its compiled bounds, so a query
naming something deletable answers {:error, :query_names_deletable}.
What rides
execute/2 stays pure and of arity 2. The command is its only added input, because what a
read answers is never aggregate state.
The command's :rule_result field holds a Decree.Decision.Rule.Result, its events being
the data of the events the rule's own items matched, both reads', in position order. A caller's
value there is overwritten. A route with no rule leaves the field as sent.
Its matched_keys is parallel to events: for each event, the keys of the rule's own items
that matched it, each once, in item order, the first read's before the follow-up's. An item
with no key: adds none, so an event only unkeyed items matched has []. A key never reaches
the store, the condition or telemetry: it is taken off the item before the read. So a key may
name an id. followup_query/3 gets the first read's events alone, with no keys.
It is set on a copy, for one call. Decree.Aggregates.ExecutionContext keeps the plain
command, so nothing the framework does after the call holds a read: no reply, no metadata, no
state, no snapshot. execute/2 is the application's own code, and the framework does not
look inside what it returns. So it must not copy the result, or anything in it, into an
event, or into the state it seeds a Decree.Aggregate.Multi with: either would keep it.
Inspect shows nothing of a result. With the JSON serializer, an event whose encoder hands a
result to Jason raises before it is stored. An encoder of the event's own can leave the
field out or unpack its events, and another serializer has no such fence at all.
[] from query/2 means this command has nothing to check, as a registration with no
address has not. execute/2 gets an empty result, and the append is the plain one a route
with no rule makes, once the batch is within max_batch_events. A decision refuses [],
because a decision that reads nothing has nothing to decide on, and a rule decides nothing.
Required tags
A condition finds an event by its tags, so a rule's conditional append requires of every event
what a decision's does, through the same code, opted in or not: always/0 of
Decree.Event.RequiredTags, the kinds of the tags on the condition's items naming the event's
type, less the module's __conditional_tag_kinds__/0, and the event's own answer. All the
condition's items count, since a rule has no fact item. So a kind a query names is required
here though the same event on a plain route is not refused, and a command with no usable
command_id cannot append on a rule route.
query/2 answering [] makes a plain append, with no condition to take kinds from, so an
event there gets its own answer only.
index_families/0 works as "Digest tags" in Decree.Decision says, on the condition's items
from both reads, and fails the build on the same bad answers. The refusals are
{:error, :missing_required_tag} and {:error, :digest_tag_mismatch}, an atom with no digest
in it. Each answers with nothing appended, before any statement, and never retries.
Retries
A failed condition runs the command again from before_execute, on the state the aggregate
has, and spends one of the attempts retry_attempts gives it. So does a lost expected
version, which rebuilds the state first, from a budget of its own: neither spends the other's,
and one dispatch runs execute/2 at most 2 * retry_attempts + 1 times. Each attempt reads
afresh, with a fresh after. A condition spent answers {:error, :too_many_attempts},
with the state unchanged, and never a success or a duplicate. retry_attempts: 0 tries
once. An aggregate stopped under a dispatch restarts the dispatch, bounded by retry_attempts
as it is on any route, and the condition's budget starts again.
Bounds
use Decree.Decision.Rule, max_items: 8max_items, max_probes, max_events, max_batch_events and bound_reason: are those of
"Bounds" in Decree.Decision, with the same defaults, the same rule for raising one, and the
same answers: :decision_query_too_large and :decision_batch_too_large. max_items counts
the index item, so 15 of a rule's own make 16, and max_events does not count the facts it
matches: they come by position, with no event (see "Index facts" in Decree.Decision).
max_batch_events holds on every append a rule route makes, a plain one after [] included.
A condition's items run under the $all lock on an aggregate route as on a decision's, so
lead each item with its narrowest tag.
Leaks
A rule route is redacted whether or not the aggregate uses Decree.PersonalFields.Aggregate,
because a read can bring in another subject's plaintext. A raise from a callback, from
execute/2, apply/2 or before_execute, from preparing, or from reading an event the rule
reads, in the store's deserializing, the mapping or an upcaster, reaches logs,
telemetry, after_failure and the answer as a
Decree.PersonalFields.RedactedError with a scrubbed stacktrace. An exit leaves reduced by
Decree.PersonalFields.RedactedError.reduce/1. A throw is reduced the same way and leaves as
an exit, {:nocatch, reduced}, because gen_server reads a term thrown from a callback as its
return, and a reduced {:noreply, _} is a valid one. Either takes the aggregate with it, and
the caller gets {:error, :aggregate_execution_failed}. An {:error, reason} from
followup_query/3 is reduced the same way. query/2 has read nothing, so its reason
stands.
None of these reaches the read's [:decree, :event_store, :read_query] span. The store's
deserializing and the mapping run inside it, and its exception event never fires:
a failure there stops it with error set to its kind alone, :error, :exit or :throw,
and is raised again after. The upcast runs after it stops. Each reaches the boundary above.
An {:error, reason} from execute/2 is not reduced. It goes back to the caller, to
after_failure and to telemetry as it stands, as on any aggregate route. So execute/2 answers
an atom or a tuple of its own, never a value it read.
An item's tag goes to the store and to telemetry as it is, so followup_query/3 names an id
or a digest, never a value it decrypted.
Personal fields
A rule lists the events it reads as a decision does:
defmodule EmailRule do
use Decree.Decision.Rule
use Decree.PersonalFields.Aggregate
@personal_fold [UserRegistered]
endA listed event reaches followup_query/3 and execute/2 with its body decrypted, and an
erased subject's field nil. An unlisted one reaches them as stored. One no key can read
answers {:error, :key_unknown}, with nothing appended, no retry, and the aggregate's state
still good. @personal_state and @personal_state_subject mean nothing on a rule.
Two declarations
A route's rule: says which commands a rule covers. The store's conditional_appends
says which conditions it will run, because a condition takes time under $all:
conditional_appends: [targets: [User]]The condition's target is the route's aggregate module, and only targets: declares it: a
stream_prefixes: entry covering the aggregate's streams does not. The two must agree. An
application with a rule route checks them as it starts, right after its store has started,
against the config the running store parsed:
- A rule route's aggregate with no store target raises an
ArgumentError, naming both, and the application does not start:start_link/1answers{:error, {:shutdown, {:failed_to_start_child, _id, _reason}}}. - A store target no route declares logs a warning. It is not refused: a store can be shared, and a direct store caller may use a target.
- A router outside the application is not checked at start, so a dispatch through it
answers the store's
{:error, :undeclared_conditional_target}, with nothing written, even when its streams start with a declared prefix.
An application with no rule route and no windowed aggregate checks nothing and asks its store
nothing, so a target its store declares draws no warning there. A windowed aggregate is a
target too: see "Command window" in Decree.Aggregate.
What declaring leaves alone
A target is compared on a conditional append and nowhere else, and everything below goes by a stream's prefix. So a declared aggregate's stream takes, exactly as before, plain appends from its other commands, a hard delete of it and a snapshot of it. Hard deleting such a stream removes what a rule reads there, which is a release: a rule must not hang anything on those events staying.
The aggregate's own prefix should not be one of conditional_appends' stream_prefixes, which
would refuse its plain commands.
The appender map
Decree.Decision.AppenderMap audits a rule as it does a decision. List it as
{{:rule, EmailRule}, items}, which is no create and covers no row, with the row
{RegisterUser, User} and each command its route decides in conditional:, here
[RegisterUser]. An {:aggregate, User} key has its items checked and certifies none of
its own commands, so it never stands in for conditional:.
Telemetry
An aggregate's span runs as on any route. There is no [:decree, :decision, :execute] span,
and [:decree, :decision, :read], [:decree, :decision, :retry] and
[:decree, :decision, :refused] are those of Decree.Decision, with decision being the rule:
:readfires once per attempt that read anything and passed the index check, andfold_timeis what step 3 took after it.:retryfires for:append_condition_failed, and on an aggregate that declares a command window also for:new_command_match, a command match only the rule's second read has. A lost expected version has no event of its own, on this route as on a plain one.attemptcounts every run of the command in this dispatch, for either reason.
A route with no rule fires none of them, unless its aggregate declares a command window, whose
read and retries fire :read and :retry with the aggregate's module as decision. The reads' [:decree, :event_store, :read_query]
span never fires its exception event, and its stop names a failure's kind in error: see
"Leaks".
Summary
Types
An item of Decree.Decision, which has what one may hold.
Callbacks
The items of a second read, given the events the first read's own items matched. []
skips it.
Which tag kinds hold digests. See "Digest tags" in Decree.Decision. Defaults to none.
The items to read for a command, [] for nothing to check.
Types
@type item() :: Decree.Decision.item()
An item of Decree.Decision, which has what one may hold.
Callbacks
@callback followup_query(command :: struct(), Decree.Event.TagContext.t(), [struct()]) :: [item()] | {:error, term()}
The items of a second read, given the events the first read's own items matched. []
skips it.
@callback index_families() :: %{required(String.t()) => :digest | :plain}
Which tag kinds hold digests. See "Digest tags" in Decree.Decision. Defaults to none.
@callback query(command :: struct(), Decree.Event.TagContext.t()) :: [item()] | {:error, term()}
The items to read for a command, [] for nothing to check.