コンテンツにスキップ
日本語

Envelope

このコンテンツはまだ日本語訳がありません。

Envelope<T> = object

Defined in: src/internal/Mailbox.ts:6

T = unknown

readonly optional context?: 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.


readonly optional enqueuedAtMs?: 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.


readonly message: T

Defined in: src/internal/Mailbox.ts:7


readonly optional replayed?: 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.


readonly sender: ActorRef | null

Defined in: src/internal/Mailbox.ts:8


readonly optional trace?: 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.


readonly optional undroppable?: 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.