Decree.Event.Append (decree v0.1.0)

Copy Markdown View Source

The one function that runs just before the store append.

Summary

Functions

Answers a copy of event_data ready for the store.

Maps events to event data for the dispatch context describes, and answers them through prepare/4. Every path that appends a command's events calls this one function, per stream. No events prepare to {:ok, []}.

Functions

prepare(application, stream_uuid, event_data, context)

Answers a copy of event_data ready for the store.

Every framework append path reaches this one function, through prepare_events/4, with the application's name and the stream's. Each event takes these steps, on copies:

  1. Lookup. One Decree.PersonalFields.KeySource lookup per subject, for each declared value that is not nil.

  2. Resolve. An unknown key fails the whole append. An erased one removes the value: a field becomes nil and a metadata key goes. A missing subject, a value that is already an envelope and metadata the application fences also stop here.

  3. Tags. Decree.Event.Tags.tags/2, followed by the framework's. An implementation sees the plaintext that will be stored, so an erased subject gets no tag derived from its value, and no tag holds ciphertext. Then the kinds the event requires, from Decree.Event.RequiredTags.required/2, on the same copy and the same tag context, so an erased value reads as absent. They go in required_tag_kinds, for the store to refuse. An event that requires kinds, on a command with no command: tag of its own, stops here with {:error, :missing_required_tag}, whatever tags the implementation answered.

  4. Encrypt. Declared fields and metadata entries become envelopes.

An event that declares nothing takes step 3 alone, and comes out as it went in, with tags.

It writes nothing, and ExecutionContext.metadata is untouched, so a :wrong_expected_version retry derives afresh from plaintext. It runs once per attempt. A lookup aside, it is deterministic: the same event and context give the same tags.

The first {:error, reason} stops and is returned. A raise from an implementation is not rescued here: the aggregate or the decision answers it, having written nothing. On an event with a declaration anything leaving an implementation can carry the value it failed on, so its error reason, exit and throw are reduced by Decree.PersonalFields.RedactedError.reduce/1, a throw leaving as the exit {:nocatch, reduced}, and a raise becomes a Decree.PersonalFields.RedactedError. An event's __required_tag_kinds__/2 is treated the same way, because it sees the same plaintext.

Framework tags

  • command:<command_id>, from the command's command_id field when that is a non-empty binary. There is no fallback, default or derived id: a command with none gets no command: tag.

  • command_kind:<module>, the command's module in inspect/1 form. Always present.

  • correlation:<key>, from the command's correlation_id field when that is a non-empty binary. ExecutionContext.correlation_id is a different value, by default a fresh UUID per dispatch, and is never read.

  • <kind>:<id>, the stream's entity tag, when ExecutionContext.aggregate_identity, the identity the stream was routed by, is a lowercase canonical UUID (Decree.UUID.canonical?/1). It is never read from the command again, and never the prefixed stream name. See Decree.Commands.Router.dispatch/2 for its kind.

The store removes a repeat, so a domain tag equal to a framework tag is stored once.

prepare_events(application, stream_uuid, events, context)

@spec prepare_events(
  Decree.Application.t(),
  String.t(),
  [struct()],
  Decree.Aggregates.ExecutionContext.t()
) :: {:ok, [Decree.EventStore.EventData.t()]} | {:error, term()}

Maps events to event data for the dispatch context describes, and answers them through prepare/4. Every path that appends a command's events calls this one function, per stream. No events prepare to {:ok, []}.