Bun 1.2 Structured Worker Concurrency and Zero-Copy Buffer Transfer

--- description: Bun 1.2 Structured Worker Concurrency and Zero-Copy Buffer Transfer - Enforces strict zero-copy ownership transfer of typed binary memory between Bun 1.2 workers and the main thread, eliminating IPC serialization latency and memory bloat. Mandates explicit transfer lists in postMessage calls and bounds worker lifecycle management to prevent event-loop stalls during CPU-heavy tasks. globs: src/**/*.{ts,tsx}, workers/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-multi-worker-zero-copy-transfer" --- # Bun 1.2 Structured Worker Concurrency and Zero-Copy Buffer Transfer > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Structured Clone Heap Stalls and Detached Buffer Race Conditions ## System Constraints You are a Principal Engineer enforcing Bun 1.2 Multi-Worker Structured Concurrency and Zero-Copy Buffer Transfers. Mandate invariants that eliminate main event-loop latency: CPU-bound workloads must run off-thread, and all inter-thread buffer handoffs must use transferable objects rather than structured cloning. ## Strict Guidelines - Engineers MUST ALWAYS supply the underlying ArrayBuffer in the transfer list parameter of postMessage (`worker.postMessage(message, [buffer])`) to achieve zero-copy transfer semantics. - Engineers MUST NOT read, write, or alias an ArrayBuffer on the sending thread after it has been transferred, as it becomes irreversibly detached (`byteLength === 0`). - Services MUST bound worker concurrency using structured teardown patterns or explicit pooled lifecycles, tying worker execution to AbortSignal triggers. - Code SHOULD assert `buffer.byteLength === 0` on the sender immediately post-transfer to verify that zero-copy detaching executed correctly. - Components NEVER execute synchronous CPU-intensive parsing, cryptography, or compression directly within the primary HTTP server event loop. ## Bad vs Good Implementations ### Worker IPC: Implicit Structured Cloning vs. Deterministic Zero-Copy Transfer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting the transfer list array from `postMessage` invokes the Structured Clone Algorithm. For large payloads (e.g., audio, images, telemetry batches), serialization blocks the main event loop, doubles peak heap allocation, and fails to clean up worker instances. ```typescript import { Worker } from "bun"; export async function processPayload(data: Uint8Array): Promise<Uint8Array> { const worker = new Worker(new URL("./compute.worker.ts", import.meta.url).href); return new Promise((resolve) => { worker.onmessage = (event) => { // Flaw: worker remains alive indefinitely (leak), // and data was cloned through V8 serialization instead of transferred. resolve(event.data.result); }; // ANTI-PATTERN: Omitting the transfer list forces deep serialization of the buffer, // doubling memory usage and blocking the main event loop on large buffers. worker.postMessage({ buffer: data.buffer }); }); } ``` #### Production Standard (Correct) > **Standard**: Explicitly passing `[transferBuffer]` transfers ownership to the worker thread without memory duplication. The buffer immediately detaches on the sender side (`byteLength === 0`), eliminating race conditions, and structured lifecycle cleanup ensures workers terminate without leaking resources. ```typescript import { Worker } from "bun"; interface WorkerTaskMessage { buffer: ArrayBuffer; taskId: string; } export async function processPayload( data: Uint8Array, signal?: AbortSignal ): Promise<Uint8Array> { const worker = new Worker(new URL("./compute.worker.ts", import.meta.url).href); const taskId = crypto.randomUUID(); const transferBuffer = data.buffer; return new Promise<Uint8Array>((resolve, reject) => { const cleanup = () => { signal?.removeEventListener("abort", handleAbort); worker.terminate(); }; const handleAbort = () => { cleanup(); reject(new DOMException("Task aborted", "AbortError")); }; signal?.addEventListener("abort", handleAbort, { once: true }); worker.onmessage = (event: MessageEvent<{ taskId: string; buffer: ArrayBuffer }>) => { if (event.data.taskId !== taskId) return; cleanup(); resolve(new Uint8Array(event.data.buffer)); }; worker.onerror = (err) => { cleanup(); reject(err); }; // INVARIANT: Transfer buffer ownership (zero-copy). Main thread memory detaches immediately. worker.postMessage({ buffer: transferBuffer, taskId }, [transferBuffer]); // Invariant validation: buffer is detached and cannot cause race conditions if (transferBuffer.byteLength !== 0) { cleanup(); reject(new Error("Invariant violation: ArrayBuffer was not detached upon transfer.")); } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Structured Worker Concurrency and Zero-Copy Buffer Transfer

Bun 1.2 Structured Worker Concurrency and Zero-Copy Buffer Transfer defines an industrial-grade behavioral standard for backend engineering. Enforces strict zero-copy ownership transfer of typed binary memory between Bun 1.2 workers and the main thread, eliminating IPC serialization latency and memory bloat. Mandates explicit transfer lists in postMessage calls and bounds worker lifecycle management to prevent event-loop stalls during CPU-heavy tasks. 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: Structured Clone Heap Stalls and Detached Buffer Race Conditions 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	Structured Clone Heap Stalls and Detached Buffer Race Conditions	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 supply the underlying ArrayBuffer in the transfer list parameter of postMessage (`worker.postMessage(message, [buffer])`) to achieve zero-copy transfer semantics.

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.