Skip to content

[Feature] Bounded PriorityMailbox — choosing priority silently disables the default mailbox bound #647

Description

@pathosDev

Problem

Since #310 the default mailbox is bounded (src/internal/ActorCell.ts:154-165 + DEFAULT_MAILBOX_CAPACITY) — but PriorityMailbox extends the unbounded base and holds its own ordered array (src/mailbox/PriorityMailbox.ts:17-71). Props.withMailbox(() => new PriorityMailbox(...)) therefore silently reverts to the pre-#310 OOM-or-bust shape. BoundedMailbox and PriorityMailbox are siblings that cannot be combined.

Also:

  • No PriorityMailboxOptionsValidator exists (while BoundedMailboxOptionsValidator does). A missing priorityFor — which the Partial<> union permits (src/mailbox/PriorityMailboxOptions.ts:32-34) — fails as this.priorityFor is not a function on first enqueue.
  • PriorityMailbox.hasMessages() carries a copy-pasted "Peek at the next message…" JSDoc (line 67).

Proposed behaviour

Add capacity + overflow policy to PriorityMailbox (or ship a BoundedPriorityMailbox), plus a validator asserting priorityFor. Report drops through the same onDrop metric hook as BoundedMailbox.

Acceptance criteria

  • A priority mailbox at capacity applies drop-head/drop-new/reject and reports drops.
  • A missing/invalid priorityFor throws OptionsError at construction.

Related: #408 (ring-buffer mailbox), #310

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