Jido.Messaging.DeadLetter (Jido Messaging v1.0.0)

Dead-letter storage and replay control plane for terminal outbound failures.

Dead-letter records are written when outbound gateway work reaches terminal failure paths (including explicit load shedding). Replay execution is partitioned by dead-letter id via Jido.Messaging.DeadLetter.ReplayWorker.

Summary

Types

record()

record_status()

replay_metadata()

replay_response()

replay_status()

state()

Functions

archive(instance_module, dead_letter_id)

Archive a dead-letter record.

capture_outbound_failure(instance_module, request, error, diagnostics \\ %{})

Capture a terminal outbound failure into dead-letter storage.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

config(instance_module)

Returns dead-letter configuration for a messaging instance.

get(instance_module, dead_letter_id)

Get a dead-letter record by id.

list(instance_module, opts \\ [])

List dead-letter records.

purge(instance_module, opts \\ [])

Purge dead-letter records.

replay(instance_module, dead_letter_id, opts \\ [])

Replay a dead-letter record through partitioned replay workers.

replay_registry_name(instance_module)

Returns the registry used by replay workers for an instance module.

replay_supervisor_name(instance_module)

Returns the registered replay supervisor name for an instance module.

server_name(instance_module)

Returns the registered dead-letter server name for an instance module.

Types

record()

@type record() :: %{
  id: String.t(),
  instance_module: module(),
  status: record_status(),
  source: :outbound_gateway,
  inserted_at: DateTime.t(),
  updated_at: DateTime.t(),
  category: Jido.Messaging.OutboundGateway.error_category(),
  disposition: :retry | :terminal,
  reason: term(),
  retryable: boolean(),
  attempt: pos_integer() | nil,
  max_attempts: pos_integer() | nil,
  partition: non_neg_integer() | nil,
  routing_key: String.t() | nil,
  correlation_id: term(),
  idempotency_key: String.t() | nil,
  request: map(),
  diagnostics: map(),
  replay: replay_metadata()
}

record_status()

@type record_status() :: :active | :archived

replay_metadata()

@type replay_metadata() :: %{
  status: replay_status(),
  attempts: non_neg_integer(),
  last_attempt_at: DateTime.t() | nil,
  last_outcome: :ok | :error | nil,
  last_result: term() | nil
}

replay_response()

@type replay_response() ::
  %{status: :already_replayed, record: record()}
  | %{
      status: :replayed,
      response: Jido.Messaging.OutboundGateway.success_response(),
      record: record()
    }

replay_status()

@type replay_status() :: :never | :running | :succeeded | :failed

state()

@type state() :: %{
  instance_module: module(),
  max_records: pos_integer(),
  records: %{optional(String.t()) => record()},
  order: [String.t()]
}

Functions

archive(instance_module, dead_letter_id)

@spec archive(module(), String.t()) :: :ok | {:error, :not_found | :unavailable}

Archive a dead-letter record.

capture_outbound_failure(instance_module, request, error, diagnostics \\ %{})

@spec capture_outbound_failure(module(), map(), map(), map()) ::
  {:ok, record()} | {:error, :unavailable}

Capture a terminal outbound failure into dead-letter storage.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

config(instance_module)

@spec config(module()) :: keyword()

Returns dead-letter configuration for a messaging instance.

get(instance_module, dead_letter_id)

@spec get(module(), String.t()) ::
  {:ok, record()} | {:error, :not_found | :unavailable}

Get a dead-letter record by id.

list(instance_module, opts \\ [])

@spec list(
  module(),
  keyword()
) :: {:ok, [record()]} | {:error, :unavailable}

List dead-letter records.

Options:

:status - :active, :archived, or :all (default: :all)
:limit - positive integer limit

purge(instance_module, opts \\ [])

@spec purge(
  module(),
  keyword()
) :: {:ok, non_neg_integer()} | {:error, :unavailable}

Purge dead-letter records.

Options:

:status - :active, :archived, or :all (default: :archived)
:older_than_ms - only purge records older than this age

replay(instance_module, dead_letter_id, opts \\ [])

@spec replay(module(), String.t(), keyword()) ::
  {:ok, replay_response()} | {:error, term()}

Replay a dead-letter record through partitioned replay workers.

replay_registry_name(instance_module)

@spec replay_registry_name(module()) :: atom()

Returns the registry used by replay workers for an instance module.

replay_supervisor_name(instance_module)

@spec replay_supervisor_name(module()) :: atom()

Returns the registered replay supervisor name for an instance module.

server_name(instance_module)

@spec server_name(module()) :: atom()

Returns the registered dead-letter server name for an instance module.