Scriba.DeadLetter (Scriba v0.1.0)

Copy Markdown View Source

Helpers for the scriba_dead_letters table — failed events recorded for later inspection or replay.

An event arrives here in two ways (§9), both after retry exhaustion:

  1. The handler returned {:error, reason}.
  2. The handler raised — the engine catches it and tags it {:exception, exception, stacktrace}.

Both end up routed to a row in scriba_dead_letters with a serialized copy of the event and an error description. Per §9.2, the projection's position advances past the dead-lettered event — the projection does not block. Replaying dead-letters is a v0.2 concern.

A failure of the target's atomic commit (e.g. Repo.transaction/1) is not a dead-letter path: the whole batch is marked failed and its events are redelivered. See Scriba.Target.

This module exposes raw helpers; the routing decision (when to insert) lives in the Pipeline, which partitions failure-shape handler results out of the batch and passes them to the target as dead_letters.

Summary

Types

error()
projection()

Functions

build_row(map, event, error)

Builds a row map for the scriba_dead_letters table from a failing event and an error tuple/exception.

insert(repo, projection, event, error)

Inserts a single dead-letter row directly via repo. Used by callers that manage their own transaction (e.g. retry-then-dead-letter flows).

multi(multi, projection, event, error)

Appends a dead-letter insert to an Ecto.Multi. Useful for the Pipeline's "dead-letter and advance position" transaction after a target apply_batch has already failed and rolled back.

Types

error()

@type error() :: %{
  kind: String.t(),
  message: String.t() | nil,
  stacktrace: String.t() | nil
}

projection()

@type projection() :: %{name: String.t(), version: pos_integer()}

Functions

build_row(map, event, error)

@spec build_row(projection(), Scriba.Event.t(), term()) :: map()

Builds a row map for the scriba_dead_letters table from a failing event and an error tuple/exception.

Accepts:

  • {:error, reason} — kind = "error", message = inspect(reason)
  • {:exception, exception, stacktrace} — kind = exception.__struct__, message + formatted stacktrace

insert(repo, projection, event, error)

@spec insert(module(), projection(), Scriba.Event.t(), term()) ::
  {:ok, term()} | {:error, term()}

Inserts a single dead-letter row directly via repo. Used by callers that manage their own transaction (e.g. retry-then-dead-letter flows).

multi(multi, projection, event, error)

@spec multi(Ecto.Multi.t(), projection(), Scriba.Event.t(), term()) :: Ecto.Multi.t()

Appends a dead-letter insert to an Ecto.Multi. Useful for the Pipeline's "dead-letter and advance position" transaction after a target apply_batch has already failed and rolled back.