Decree.Decision.Rule behaviour (decree v0.1.0)

Copy Markdown View Source

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
end

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

The route is per command, so the aggregate's other commands stay plain. See "Two declarations" for the store's half.

Callbacks

  • query/2 names 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:

  1. Call query/2. Its error is the answer. Refuse an item naming no types, a replay: true item, 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.
  2. Call followup_query/3 if 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's after stands for both. More matched events than max_events, both reads together, refuses.
  3. Check the index as "Index facts" in Decree.Decision says, on the facts' tags the reads returned, with no command requirement: a family the rule's items require with no enabled index answers {:error, :tag_index_not_enabled}, before execute/2. Keep the events the rule's own items matched, and decrypt the ones it lists.
  4. Call execute/2 with 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.
  5. 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 its after is 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: 8

max_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]
end

A 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/1 answers {: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:

  • :read fires once per attempt that read anything and passed the index check, and fold_time is what step 3 took after it.
  • :retry fires 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.
  • attempt counts 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

item()

@type item() :: Decree.Decision.item()

An item of Decree.Decision, which has what one may hold.

Callbacks

followup_query(command, t, list)

(optional)
@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.

index_families()

(optional)
@callback index_families() :: %{required(String.t()) => :digest | :plain}

Which tag kinds hold digests. See "Digest tags" in Decree.Decision. Defaults to none.

query(command, t)

@callback query(command :: struct(), Decree.Event.TagContext.t()) ::
  [item()] | {:error, term()}

The items to read for a command, [] for nothing to check.