The tags an event carries in the store, beyond the ones the framework adds.
tags/2 receives the event and a Decree.Event.TagContext and answers
{:ok, tags} or {:error, reason}. It runs once per event per append attempt, inside
the aggregate, so it must be deterministic: the same event and context give the same
tags. It must read no database, clock or process state a retry could see differently.
Decree.Event.Append.prepare/4 calls it for every event a command appends, then adds
the framework's tags: command:, command_kind:, correlation: and the stream's
entity tag. Those need nothing from this protocol. It calls it on the plaintext that will be
stored: a declared value erased at append is already gone, and none is encrypted yet.
An event with no implementation
The protocol falls back to Any, which answers {:ok, []}. So an event with no
implementation still appends, with the framework's tags. A struct with no implementation
is not refused at runtime: an application that has not opted in keeps working, and so
does every event a library or test defines.
"A struct with no implementation fails the build" is met at build time instead, by
Decree.Event.TagCoverage, which an application calls from its own build check.
An event with no domain tags
@derive Decree.Event.Tags is the explicit way to say an event has none. It answers
{:ok, []} as the fallback does, and it counts as implemented for
Decree.Event.TagCoverage:
defmodule AccountClosed do
@derive [Jason.Encoder, Decree.Event.Tags]
defstruct [:account_id]
endFailing an append
{:error, reason} fails the append and is the command's answer, as it stands. Nothing is
appended and the aggregate's state is unchanged. A raise is answered the same way, as a
raise from execute/2 is.
An event declaring personal fields is in plaintext here, and what leaves an implementation
can carry its value. So on such an event the command's answer is {:error, reduced}, by
Decree.PersonalFields.RedactedError.reduce/1: an atom reason stands, and a tuple with an
atom head keeps that head. An exit or a throw is reduced the same way, and a raise becomes a
Decree.PersonalFields.RedactedError. An event with no declaration is not touched.
Every event is prepared before the event store is called, so an implementation's error
never reads as the store's: :wrong_expected_version is answered with no retry. reason
still leaves the aggregate as a command's answer, and two reasons are acted on there, as
they are from execute/2. An :unavailable Decree.Store.AppendError stops the
aggregate, which is harmless: the next command rebuilds it from the stream.
:remote_node_down makes the dispatcher try the command again. Neither is a reason an
implementation has cause to answer.
What an application must do to adopt it
- Implement the protocol, or
@deriveit, for every event a command can append. - Call
Decree.Event.TagCoverage.verify!/1with those event modules from a build check of its own. Nothing in decree calls it. - Give each command a
command_idfield, holding a lowercase canonical UUID its requester mints (Decree.Command), and acorrelation_idfield where it carries a key. The framework reads those two names from the command, and from nowhere else. A dispatch refuses a command without a canonicalcommand_id(Decree.Middleware.CommandId); a command without acorrelation_idgets no tag of that kind. - Route each stream by an identity that is a lowercase canonical UUID, and name its
kind with
stream_tag:ondispatchwhere the field's name does not give it. The identity is checked as the route resolves it, the command's field after the router's own middleware or what aby:function answered, before the prefix, and decree converts nothing: any other answers{:error, :invalid_aggregate_identity}, unless the route declaresopaque: truefor an identity that is another system's. SeeDecree.Commands.Router.dispatch/2.
A tag must be a string of valid UTF-8 with no NUL byte, 512 bytes at most. The store
answers {:error, :invalid_tag} or {:error, :tag_too_long} otherwise. See
Decree.Store.EventData.
Required tags
A forgotten tag is an event a condition misses. An event can opt in to having that refused
by exporting three functions from its own module, none of them on this protocol. See
Decree.Event.RequiredTags.
Summary
Functions
Answers the event's own tags, or an error that fails the append.
Types
@type t() :: term()
All the types that implement this protocol.
Functions
@spec tags(t(), Decree.Event.TagContext.t()) :: {:ok, [String.t()]} | {:error, term()}
Answers the event's own tags, or an error that fails the append.