Bun 1.2 Native Worker PostMessage Queue Backpressure & Memory Bounds

--- description: Bun 1.2 Native Worker PostMessage Queue Backpressure & Memory Bounds - Enforces bounded queue depths and explicit bidirectional backpressure on Bun 1.2 Worker thread message dispatching. Prevents silent native heap and RSS ballooning caused by unacknowledged postMessage queues during high-throughput CPU-bound processing bursts. globs: src/**/*.worker.ts, src/**/workers/**/*.ts, src/**/thread-pool/**/*.ts, src/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-worker-postmessage-backpressure-guardrail" --- # Bun 1.2 Native Worker PostMessage Queue Backpressure & Memory Bounds > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded postMessage Fire-and-Forget Dispatch Leading to Silent Native Heap Exhaustion and OOM Crashes ## System Constraints You are a Principal Engineer enforcing Bun 1.2 Worker Thread PostMessage Queue Backpressure Guardrails. Mandate bounded in-flight message processing, explicit credit-based or watermark-driven acknowledgement protocols, and memory-safe thread communication across all Bun worker thread pools. ## Strict Guidelines - Engineers MUST ALWAYS enforce bounded in-flight message constraints (high/low watermarks or semaphore tokens) prior to invoking worker.postMessage() in Bun. - Engineers MUST NOT dispatch unthrottled fire-and-forget postMessage payloads from high-frequency event loops or streams into native Bun Workers. - Code SHOULD leverage ArrayBuffer transfer lists or SharedArrayBuffer with Atomics when passing large data structures to bypass Structured Clone Native Heap allocations. - Services MUST monitor inflight task depth and suspend source stream intake or pause producer execution when the high watermark threshold is breached. - Components NEVER assume Worker garbage collection frees pending postMessage queue payloads before native RSS reaches host memory limits. ## Bad vs Good Implementations ### Unbounded Worker Dispatch vs. Watermark Backpressure Queue #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Pushing unconstrained payloads into a worker thread overruns the native C++ message queue. Bun's JavaScriptCore thread cannot process tasks fast enough, resulting in runaway native RSS memory growth and SIGKILL terminations under load. ```typescript import { Worker } from 'bun'; const worker = new Worker(new URL('./compute.worker.ts', import.meta.url)); // ANTI-PATTERN: Rapidly pushing unbounded items into Bun's native message queue. // Structured Clone serialization accumulates in native RSS without JSC GC reclamation. export async function processBatch(items: Uint8Array[]): Promise<void> { for (const item of items) { worker.postMessage({ type: 'PROCESS', data: item }); } } ``` #### Production Standard (Correct) > **Standard**: Implements an explicit credit-based acknowledgement and drain cycle with strict high and low watermarks. Suspends the producer before native postMessage queues saturate Bun's thread memory, and leverages Transferables to minimize RSS clone footprints. ```typescript import { Worker } from 'bun'; const worker = new Worker(new URL('./compute.worker.ts', import.meta.url)); const HIGH_WATERMARK = 64; const LOW_WATERMARK = 16; let inflightCount = 0; let drainResolver: (() => void) | null = null; worker.onmessage = (event: MessageEvent) => { if (event.data.type === 'ACK') { inflightCount--; if (drainResolver && inflightCount <= LOW_WATERMARK) { const resolve = drainResolver; drainResolver = null; resolve(); } } }; export async function processBatch(items: Uint8Array[]): Promise<void> { for (const item of items) { if (inflightCount >= HIGH_WATERMARK) { await new Promise<void>((resolve) => { drainResolver = resolve; }); } inflightCount++; // Pass transferable buffers where possible to eliminate serialization heap clones worker.postMessage({ type: 'PROCESS', buffer: item.buffer }, [item.buffer]); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native Worker PostMessage Queue Backpressure & Memory Bounds

Bun 1.2 Native Worker PostMessage Queue Backpressure & Memory Bounds defines an industrial-grade behavioral standard for backend engineering. Enforces bounded queue depths and explicit bidirectional backpressure on Bun 1.2 Worker thread message dispatching. Prevents silent native heap and RSS ballooning caused by unacknowledged postMessage queues during high-throughput CPU-bound processing bursts. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unbounded postMessage Fire-and-Forget Dispatch Leading to Silent Native Heap Exhaustion and OOM Crashes Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unbounded postMessage Fire-and-Forget Dispatch Leading to Silent Native Heap Exhaustion and OOM Crashes	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS enforce bounded in-flight message constraints (high/low watermarks or semaphore tokens) prior to invoking worker.postMessage() in Bun.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.