Decree.Event.RequiredTags (decree v0.1.0)

Copy Markdown View Source

The tag kinds an event may not be appended without.

A condition finds an event by its tags, so an event that should carry a tag and does not is an event the condition misses, and nothing fails. An event opts in to having that refused, in its own module, by exporting three functions:

defmodule AddressChanged do
  @derive Jason.Encoder
  defstruct [:user_id, :address]

  def __required_tag_kinds__(%AddressChanged{address: nil}, _tag_context), do: []
  def __required_tag_kinds__(%AddressChanged{}, _tag_context), do: ["address"]

  def __conditional_tag_kinds__, do: ["address"]

  def __tag_kinds__, do: ["address"]
end
  • __required_tag_kinds__(event, tag_context) answers the kinds this event must carry. It is called where Decree.Event.Tags.tags/2 is, with the same plaintext and the same Decree.Event.TagContext, so an erased subject's dropped value reads as absent, and fails as tags/2 fails, redactions included. Answering {:error, reason} fails the append, and anything else that is not a list fails it with {:error, :invalid_required_tag_kinds}.
  • __conditional_tag_kinds__() lists the kinds an event of this module can lack. A condition naming one requires nothing of itself: the tag is required when __required_tag_kinds__/2 answers its kind, and only then. So a tag is present if and only if what it comes from is.
  • __tag_kinds__() lists every kind the module's Decree.Event.Tags implementation can produce. A kind that comes only from the route, as the stream's entity tag does, is listed here too, because a build check cannot know a route. Nothing reads it at runtime. Decree.Decision.AppenderMap does.

An event is opted in by exporting __required_tag_kinds__/2, and its list is always/0 followed by its answer. So a command with no usable command_id cannot append one, on any route. The stream's entity tag is not among them: a stream whose id is not a UUID gets none. Off a decision route or a rule's conditional append, an event without the export has an empty list, and the store checks nothing for it.

The store refuses, before any statement: {:error, :missing_required_tag} for an event lacking a kind on its list, and {:error, :invalid_required_tag_kinds} for a list that is not kinds, an improper one included. A kind is carried by a tag equal to it, or by <kind>:<value> with a value.

The command kind is carried by the framework's own tag and no other. A Decree.Event.Tags implementation answering command:forged or a bare command does not satisfy it, so Decree.Event.Append.prepare/4 answers {:error, :missing_required_tag} for an opted-in event on a command with no usable command_id, ahead of the store. Such a tag is not dropped: one equal to the framework's is stored once. command_kind needs no such rule, because the framework always writes it.

On a decision

A decision's own append requires more, of every event it appends, opted in or not: always/0, and the kinds of the tags on the condition's items naming the event's type, less the module's __conditional_tag_kinds__/0. That takes kinds from what the items ask and from nothing else, so a conditional kind __required_tag_kinds__/2 answers stays required. See step 8 of Decree.Decision. A create's fact item is left out: the decision never wrote it, so a declared type on another member is not asked the route's kind. Every item the decision wrote naming the type counts, so a kind only some events of a type carry, one member's stream kind on a batch for example, belongs in that list.

A Decree.Decision.Rule's conditional append requires the same, with no fact item to leave out. See "Required tags" there.

That holds on those two appends and nowhere else. A plain aggregate appending a type a decision queries has no condition to take kinds from, so it gets only what the event itself answers. Decree.Decision.AppenderMap is what flags that aggregate.

Summary

Functions

The kinds every opted-in event requires, and every event a decision or a rule's conditional append appends.

The kinds an event of this module can lack. None for a module without the export.

The kinds an event of this module can carry: its __tag_kinds__/0, and command, command_kind and correlation, which need no listing. Those three alone for a module without the export.

The kinds this event asks for itself: always/0 and its answer, or none for an event without the export. A decision's append and a rule's conditional one add to that, opted in or not. An answer that is not a list is {:error, :invalid_required_tag_kinds}, here. What a list holds is the store's to check.

Functions

always()

@spec always() :: [String.t(), ...]

The kinds every opted-in event requires, and every event a decision or a rule's conditional append appends.

conditional_kinds(module)

@spec conditional_kinds(module()) :: [String.t()]

The kinds an event of this module can lack. None for a module without the export.

producible_kinds(module)

@spec producible_kinds(module()) :: [String.t()]

The kinds an event of this module can carry: its __tag_kinds__/0, and command, command_kind and correlation, which need no listing. Those three alone for a module without the export.

required(event, context)

@spec required(struct(), Decree.Event.TagContext.t()) ::
  {:ok, list()} | {:error, term()}

The kinds this event asks for itself: always/0 and its answer, or none for an event without the export. A decision's append and a rule's conditional one add to that, opted in or not. An answer that is not a list is {:error, :invalid_required_tag_kinds}, here. What a list holds is the store's to check.