Skip to content

[Feature] Dead-letter policies: persistent DLQ with inspection + replay #433

Description

@pathosDev

Rationale

Dead letters today go to DeadLetterRef and are only logged — in production, undeliverable messages are a signal (crashed entity, wrong path, race during rebalance) and sometimes need to be replayed. Erlang/Akka operators routinely wire dead-letter capture; we can make it a battery.

Scope

  • Pluggable dead-letter policy via DeadLetterQueueOptions (options family; HOCON actor-ts.dead-letters.*): log-only (today's behavior, default) | metrics (counters per recipient) | persistent (journal-backed ring with retention + max-entries).
  • Inspection + replay API: list captured letters (filter by recipient/time), replay to the original or an alternate recipient.
  • Prometheus counters per recipient path (mind cardinality, [Security] Prometheus cardinality attack via user-controlled label values #131).
actor-ts.dead-letters {
  policy      = persistent     # log-only | metrics | persistent
  retention   = 7d
  max-entries = 10000
}
const deadLetters = DeadLetterQueue.get(system);
const stuck = await deadLetters.list({ recipient: 'user/payments' });
await deadLetters.replay(stuck[0].id);

Documentation

Operations docs page (EN + DE); config reference; JSDoc; CHANGELOG.

Acceptance

  • Captured letters survive restart (persistent policy); replay redelivers with original payload; retention/max-entries enforced; default behavior unchanged.

Non-goals

Automatic replay heuristics; cross-system DLQ export (brokers can consume the journal).

Relates

#222 (poison-pill quarantine — complementary), #131 (label cardinality). Improvement program M5.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestpriority: mediumUseful, not urgentproduction-goalBlocks or defines the path to production readiness

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions