# `Decree.Store.AppendError`
[🔗](https://github.com/sparkle-space/decree/blob/v0.1.0/lib/decree/store/append_error.ex#L1)

An append that the database did not accept, classified by what a caller can
do about it.

`append_to_stream/4` returns five failures of the
appender's statements as plain atoms, because they are domain answers:
`{:error, :wrong_expected_version}`, `{:error, :duplicate_event}`,
`{:error, :not_found}`, `{:error, :append_condition_failed}` and (retried once
outside a caller's transaction, see below) `{:error, :duplicate_stream_uuid}`.
Every other failure of those statements is returned as
`{:error, %Decree.Store.AppendError{}}`, with these fields:

  - `class` — what a caller can do:
    - `:unavailable` — the database could not be reached, stopped serving, or
      cannot say whether the statement took effect. Retry after a wait, if the
      append is safe to retry (see below).
    - `:retryable` — the same request may succeed if sent again.
    - `:rejected` — the request itself was refused. Retrying the same request
      will not help.
  - `code` — the Postgres error code name (`Postgrex.Error`'s
    `postgres.code`, such as `:serialization_failure`), or `nil` when the
    error carries no SQLSTATE.
  - `reason` — the original error term, kept for callers. The store never
    logs it whole: `message/1` reduces it with `Decree.Store.LogTerms.reduce/1`,
    as it can carry the failing row's values.

## Classes

| class | SQLSTATE classes | SQLSTATE codes | other errors |
|---|---|---|---|
| `:unavailable` | 08 (connection exception), 53 (insufficient resources), 57 (operator intervention) | 25P03 `idle_in_transaction_session_timeout`, 25006 `read_only_sql_transaction`, 40003 `statement_completion_unknown`, 58000 `system_error`, 58030 `io_error` | `DBConnection.ConnectionError`; a `Postgrex.Error` without SQLSTATE fields (Postgrex's disconnect when the connection breaks mid-query) |
| `:retryable` | 40 (transaction rollback), 55 (object not in prerequisite state) | | |
| `:rejected` | any other | 40002 `transaction_integrity_constraint_violation` | `Postgrex.QueryError`, `DBConnection.OwnershipError`, any other term |

A code listed in the codes column overrides its class. Notes on some entries:

  - class 57 includes `query_canceled` (57014), which a `statement_timeout`
    also raises, and `admin_shutdown`, `crash_shutdown`, `cannot_connect_now`,
    `idle_session_timeout`, `database_dropped`;
  - `read_only_sql_transaction` is a write that reached a primary a failover
    has demoted;
  - `idle_in_transaction_session_timeout` means the server ended the session;
  - `statement_completion_unknown` leaves the outcome unknown, as a lost
    connection does;
  - `transaction_integrity_constraint_violation` is a deferred constraint
    failure, which fails again on a retry;
  - `58P01` `undefined_file` and `58P02` `duplicate_file` stay `:rejected`.

## Retrying

An `:unavailable` failure does not say whether the events were written. A
retry is safe only when the append is idempotent: the events have pinned
event ids (a retry of a written append then answers
`{:error, :duplicate_event}`), or the append names an expected version that a
committed earlier attempt has moved past (it then answers
`{:error, :wrong_expected_version}`). An event without an `event_id` gets a
fresh one on every call, so a retry with `:any_version` can write the events
twice.

A `:retryable` failure rolled back. `append_to_stream/4` retries
`deadlock_detected` (40P01) once itself, from its stream-info read, and answers
the `%AppendError{}` if it comes back. It does not retry inside a caller's
transaction (`:conn` given a transaction): that transaction is aborted, and what
happens next is the caller's decision. Every other `:retryable` failure is the
caller's to retry.

## Aggregates

An aggregate whose append answers an `:unavailable` error stops (exit reason
`{:shutdown, :append_outcome_unknown}`), whatever its lifespan says: the
events may have been written while its state is still the one before the
append, so the next command opens a fresh aggregate that rebuilds its state
from the stream. A command already queued for the stopped aggregate is
retried on the fresh one. A `:retryable` or `:rejected` error is a statement
Postgres rolled back, so the aggregate's state is still the stream's and it
keeps running; `AppendError` is a plain struct, not an exception, so
`Decree.Aggregates.DefaultLifespan` answers `:infinity` for it.

`{:error, :duplicate_stream_uuid}` means two writers raced to create the same
stream. `append_to_stream/4` retries it once and then answers
`{:error, {:already_retried_once, :duplicate_stream_uuid}}`. It does not retry
inside a caller's transaction, which the race aborted: it answers
`{:error, :duplicate_stream_uuid}`.

# `class`

```elixir
@type class() :: :unavailable | :retryable | :rejected
```

# `t`

```elixir
@type t() :: %Decree.Store.AppendError{
  class: class(),
  code: atom() | nil,
  reason: term()
}
```

# `from_error`

```elixir
@spec from_error(term()) :: t()
```

Classify an error the appender's statement returned.

# `message`

```elixir
@spec message(t()) :: String.t()
```

A one-line description for a log line: the class, the code, and the original
error reduced to its type and its code or reason (`Decree.Store.LogTerms.reduce/1`),
never its message, which can carry the values of the row it failed on.

---

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