Envelope
此内容尚不支持你的语言。
Envelope<
T> =object
Defined in: src/internal/Mailbox.ts:6
Type Parameters
Section titled “Type Parameters”T = unknown
Properties
Section titled “Properties”context?
Section titled “context?”
readonlyoptionalcontext?:LogContextData
Defined in: src/internal/Mailbox.ts:15
Optional MDC snapshot captured at tell time. Propagated
through the actor’s onReceive so log lines emitted while
handling this message (and any tells issued from inside it)
carry the originating context. See LogContext.
enqueuedAtMs?
Section titled “enqueuedAtMs?”
readonlyoptionalenqueuedAtMs?:number
Defined in: src/internal/Mailbox.ts:43
Wall clock at first enqueue, stamped while the receiving actor has an
explain plan enabled or the system has metrics enabled — the two
consumers of it (ActorContext.enableExplainPlan and
actor_mailbox_wait_seconds). Absent otherwise, because a stamp is a
clock read on the framework’s hottest path and #411 removed exactly
these when nothing reads them.
A stashed message keeps its original stamp when replayed (prependUser
does not restamp), so the explain plan’s mailbox wait measures the whole
time from arrival to handling — stash residency included, which is what
a per-actor debugging view wants beside the stashed outcome that
explains it. The metric deliberately reads it differently; see
replayed.
Resolution is one millisecond (Date.now()), which is why the wait
histogram’s finest bucket is 1 ms rather than something sub-millisecond
that the clock could never distinguish.
message
Section titled “message”
readonlymessage:T
Defined in: src/internal/Mailbox.ts:7
replayed?
Section titled “replayed?”
readonlyoptionalreplayed?:boolean
Defined in: src/internal/Mailbox.ts:63
Set when this envelope re-entered the queue from the stash rather than arriving fresh, so enqueuedAtMs no longer marks the start of its current queue residency.
actor_mailbox_wait_seconds skips these. The aggregate has no labels
and no outcome column, so one actor stashing for thirty seconds while it
waits on a resource would land a thirty-second observation in the top
bucket and drown the queueing signal every other actor contributes —
where the explain plan shows the same message beside the stashed
entry that accounts for it. Stash residency is application semantics;
mailbox wait is meant to be backlog.
The other replay path, ActorCell.prependUserMessages, needs no marker:
it builds envelopes with no stamp at all, so it is already excluded.
Throttle re-parking is deliberately not marked — a throttled message
really is waiting in the queue for an actor that cannot keep up, which
is precisely what the metric is asking about.
sender
Section titled “sender”
readonlysender:ActorRef|null
Defined in: src/internal/Mailbox.ts:8
trace?
Section titled “trace?”
readonlyoptionaltrace?:SpanContext
Defined in: src/internal/Mailbox.ts:23
Optional active-span context captured at tell time. If the
tracing extension is enabled and the receiver also has it
enabled, the receiver’s actor.receive span links back to this
one as its parent — producing one coherent trace across actor
hops and cluster nodes. See Tracer.
undroppable?
Section titled “undroppable?”
readonlyoptionalundroppable?:boolean
Defined in: src/internal/Mailbox.ts:157
This envelope carries something the framework cannot send again, so no load-shedding policy may discard it (#729).
Four envelopes take it today, and the test for admitting a fifth is the property they share, not their subject: it is sent once, nothing on the framework’s side still holds what it would take to send it again, and what is lost when it is dropped is not a message but a piece of state outside the mailbox that no one else will correct. So the caller who set the bound was not choosing to lose it — it is not the traffic they were shedding, and the loss does not surface where they would look for it.
The Terminated a death-watch delivers. The watch was installed through
context.watch, the framework promised to answer it, and the answer
happens once — there is no retry, no sender to back off, and the dying
cell has already cleared its watcher set by the time the queue decides.
A bounded mailbox that evicted it left the watcher believing a dead actor
was alive, with nothing but an actor_mailbox_dropped_total increment to
say so.
The websocket-accept a completed HTTP upgrade hands its hub (#717). The
wiring layer closed the only reference to a freshly-upgraded socket into
the per-connection actor’s factory and returned; there is no timer and no
second copy. A bounded hub that evicted it kept a socket nobody would
ever attach listeners to — buffering inbound frames with nothing to drain
them and holding its maxConnections slot — for the same one increment.
The close a WebsocketConnection sends its own actor (#985). This one
is application-initiated, unlike the two above, and admitting it widens
the rule on purpose rather than by stretching it: what a dropped close
loses is a decision about a socket, not a message. There is no retry and
no sender to back off, nothing else in the process holds that socket, and
a closeAll(1008, 'rate limited') that returns normally while the peers
stay connected is a control that failed open — a security outcome, from a
bound the operator set to cap frames.
The DistributedDataChanged a DistributedData replicator posts to an actor
subscribed to one of its keys (#1468). It passes the same test, and again
what a dropped one loses is not a message. The replicator keeps a
latest-value slot per subscriber and key: at most one notification queued,
its value overwritten in place while it waits, the next one posted only
once the subscriber has been handed it — the release the door carries says
when. An evicted notification is never handed over, so its slot stays in
flight for ever: every later change lands in a message nobody will read,
nothing is posted again, and the subscriber goes on acting on the last value
it saw. That mark lives in the replicator, outside the mailbox, and no one
corrects it. Admitting it costs a bounded overshoot, as the Terminated
does — one notification per subscribed key, never more — and it is queued at
the tail like any message, keeping that place while later changes overwrite
its value.
Set by ActorCell.postSignalEnvelope, which is the only door that
sets it, and read at three seams: Mailbox.removeOldest and
Mailbox.removeNewest, so an eviction from either end steps over
it; the replay overrides — BoundedMailbox.prependUser,
PriorityMailbox.prependUser and ControlAwareMailbox.prependUser —
so a bound that now applies to the replay path admits it rather than
shedding it (#772); and the cell’s throttle gate, so onExcess: 'drop'
does not silently consume it either.
Every replay override is named because listing one of them was the last
hole (#729). The bounds reach the same rule by different routes —
BoundedMailbox tests the marker per envelope before it consults its
capacity, PriorityMailbox hands the envelope to enqueueSignal, and
ControlAwareMailbox tests it per envelope in the ordinary half of a
replay, the only half its bound applies to — and a reader who took “the
replay path” to mean “whichever mailbox the list happened to name” would
have re-derived exactly the omission: the priority bound re-entered its
own enqueue, whose capacity check does not read this field at all.
ControlAwareMailbox reads it nowhere else — its evictions are the
inherited pair above — and the position it gives a signal comes from its
predicate, never from this field (see Mailbox.enqueueSignal).
It travels with the envelope rather than being remembered by the mailbox
because the envelope outlives any one queue position: ActorContext.stash()
parks the envelope the cell is holding, so unstashAll() hands the queue
back the very object the exempt door built, and the prependUser replay it
takes then meets a bound that would otherwise get a second chance to shed
it.
The typed stash is the exception, and it is an open gap (#1319).
Behaviors.withStash cannot park an envelope — StashBuffer.stash(message)
takes an arbitrary value where the cell can only park what it is currently
handling — so the buffer keeps bare messages, and its replay half,
ActorCell.prependUserMessages, rebuilds them as message-plus-null-sender.
Nothing envelope-level survives that trip: no context, no trace, no
enqueuedAtMs, and no marker. So a typed actor that stashes its own
Terminated hands a droppable envelope back to its own bound, and the
guarantee the paragraph above states does not reach it. The fix belongs on
the typed side rather than here — a buffer that parks envelopes, or a replay
door told which of them were exempt — because every reader of this field
already does the right thing with an envelope that still carries it.
