@cqrs-ddd/pipeline-deadletter
Captures a failed operation as a dead letter: its request, error, tenant and correlation
id, sent to a transport (BullMQ, RabbitMQ or PostgreSQL). By default only events are
captured, since the caller of a command or a query already receives the error.
DeadLetterRedriver runs a captured request again later.
Installation
Section titled “Installation”Each transport takes a client of its broker or database (bullmq queue, amqplib
confirm channel, pg pool), which the application installs.
The behavior’s constructor takes the transport, optional defaults for every operation and an optional logger.
Transports
Section titled “Transports”| Transport | Notes |
|---|---|
BullMqDeadLetterTransport |
adds each dead letter as a job of a BullMQ queue (job name dead-letter by default) |
RabbitMqDeadLetterTransport |
publishes to RabbitMQ through a confirm channel |
PostgresDeadLetterTransport |
inserts into a table, dead_letters by default; it is also a DeadLetterStore, which the redriver needs |
Another backend implements DeadLetterTransport: send(record).
Options
Section titled “Options”| Option | Meaning | Default |
|---|---|---|
captureKinds |
request kinds that are captured | ['event'] |
rethrow |
rethrow the error after capturing it; false swallows it, on events only |
true |
ignoreErrors |
error classes, or a predicate, that are rethrown without being captured, such as validation errors | none |
redactKeys |
field names masked in the captured payload | none |
redact |
a function that replaces the payload redaction | none |
metadata |
a function that returns extra fields for the record | none |
includeStack |
include the stack trace | true |
ignoreErrors and redactKeys given both as constructor defaults and per operation are
combined; the other options are merged shallowly.
Ordering
Section titled “Ordering”Place the behavior outside retries, so it captures a failure only once the retries are exhausted, and inside validation, so expected validation errors are not captured.
Redriving
Section titled “Redriving”The redriver rebuilds the request from the record, matching record.requestName against
the class names in requestTypes, dispatches it, and marks the record resolved. When the
handling fails again, it counts the attempt and rethrows. A record whose payload was
redacted needs a rebuild function that restores the redacted values. During a redrive,
the behavior neither captures the failure again nor swallows it.
Before it dispatches, the redriver claims the record in the store. A second redrive of the
same record, from this process or from another one, is refused with
DeadLetterRedriveError and dispatches nothing. The claim ends when the redrive ends. If
the process stops during the handling, the claim ends after leaseMs, five minutes by
default; set leaseMs longer than the slowest handling.
When the handling fails again and the store cannot record the attempt, redrive still
throws the handling error. The store error goes to the logger option, console by
default.
PostgresDeadLetterTransport keeps the claim in the column claimed_until and the tenant
of the failed request in the column tenant_id. Run createDeadLetterTableSql() again to
add the columns to a table that does not have them. list({ tenantId }) returns the
records of one tenant.
A dispatch function runs in the context of the caller of redrive. When the handling reads
the tenant, restore record.tenantId in the dispatch function before the handling starts.