DropReportingMailbox
Defined in: src/internal/Mailbox.ts:149
A mailbox that discards messages and is willing to say so.
Implement it on a Mailbox subclass of your own and the cell counts
its drops in actor_mailbox_dropped_total, with the same {class, reason}
labels the built-in bound produces. BoundedMailbox implements it; nothing
else needs to.
Those labels identify a class, not an actor — the stock family carries no
path (#658). If you need to know which instance is shedding, observe it
yourself: registration is additive, so your own observer runs alongside the
framework’s and you choose that series’ cardinality.
The cell probes for this method rather than testing
instanceof BoundedMailbox on purpose. Since #661 the base Mailbox is
public and subclassing it is a supported thing to do, so a queue that drops
for its own reasons should not be second-class in the telemetry.
A report carries the envelope as well as the reason since #773, and a mailbox that sets deadLetterDrops also gets each dropped envelope turned into a DeadLetter — so overflow stops being the one loss path in the framework with no forensic record.
Type Parameters
Section titled “Type Parameters”T = unknown
Properties
Section titled “Properties”deadLetterDrops?
Section titled “deadLetterDrops?”
readonlyoptionaldeadLetterDrops?:boolean
Defined in: src/internal/Mailbox.ts:183
Should the cell turn each drop this mailbox reports into a DeadLetter on the system’s dead-letter path (#773)?
The mailbox owns the switch, the cell owns the routing, and the split
is why this sits on the interface rather than in ActorOptions. A
withMailbox mailbox is configured where it is constructed and the cell
never sees its options; a cell-side flag would therefore reach exactly
the shape that already reports and miss the one that #1149 had to add a
structural probe for.
Absent or false means no, and the default is deliberate rather than
timid. enqueue runs on the sender’s stack, and DeadLetterRef.tell
runs the durable capture sink and a synchronous event-stream publish, so
routing every shed envelope converts load shedding into per-message work
under exactly the pressure the bound exists to absorb. Rate-limiting the
dead-letter stream itself is #1179 and belongs downstream of the capture,
not here.
The envelope reaches the observers either way — a drop report has always
been free to carry what it lost, and an onDrop of your own may want it
without wanting the framework’s fan-out.
Methods
Section titled “Methods”observeDrops()
Section titled “observeDrops()”observeDrops(
observer):void
Defined in: src/internal/Mailbox.ts:159
Register a drop observer. Called by the cell once, before the mailbox receives anything.
Additive, not a setter. Whatever the mailbox already reports —
BoundedMailboxOptions.onDrop, a previously registered observer — has to
keep firing. A caller who wired their own metric does not lose it
because the framework wired the stock one.
Parameters
Section titled “Parameters”observer
Section titled “observer”Returns
Section titled “Returns”void