# `Decree.Event.Tags`
[🔗](https://github.com/sparkle-space/decree/blob/v0.1.0/lib/decree/event/tags.ex#L1)

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

## Failing 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

  1. Implement the protocol, or `@derive` it, for every event a command can append.
  2. Call `Decree.Event.TagCoverage.verify!/1` with those event modules from a build
     check of its own. Nothing in decree calls it.
  3. Give each command a `command_id` field, holding a lowercase canonical UUID its
     requester mints (`Decree.Command`), and a `correlation_id` field 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 canonical `command_id`
     (`Decree.Middleware.CommandId`); a command without a `correlation_id` gets no tag
     of that kind.
  4. Route each stream by an identity that is a lowercase canonical UUID, and name its
     kind with `stream_tag:` on `dispatch` where 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 a `by:` function answered, before the prefix, and
     decree converts nothing: any other answers `{:error, :invalid_aggregate_identity}`,
     unless the route declares `opaque: true` for an identity that is another system's.
     See `Decree.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`.

# `t`

```elixir
@type t() :: term()
```

All the types that implement this protocol.

# `tags`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
