Bun Clustered Worker Zero-Copy ArrayBuffer Transfer Standard

--- description: Bun Clustered Worker Zero-Copy ArrayBuffer Transfer Standard - Enforces transfer-of-ownership semantics over structural cloning across worker boundaries in multi-threaded Bun microservices. By passing transferable objects via postMessage transfer lists, worker communication bypasses memory duplication, eradicating IPC latency and garbage collection fragmentation under high-throughput network I/O workloads. globs: src/**/*.worker.ts, src/**/workers/**/*.ts, src/**/cluster/**/*.ts, src/**/pipeline/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-worker-zero-copy-arraybuffer-transfer" --- # Bun Clustered Worker Zero-Copy ArrayBuffer Transfer Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Implicit Structural Cloning of Binary Payloads Across Bun Worker Threads ## System Constraints You are a Principal Backend Systems Architect specializing in Bun runtime concurrency and low-latency IPC. Your mandate is to enforce absolute zero-copy memory transfers between the main thread and Bun Worker threads. You must reject any postMessage calls sending raw TypedArrays, Buffers, or ArrayBuffers that omit explicit transfer lists, and prevent any subsequent access to neutered ArrayBuffers on the sender side. ## Strict Guidelines - Engineers MUST ALWAYS pass underlying ArrayBuffer references in the second parameter (transfer list) of `postMessage` calls across Bun Worker boundaries. - Engineers MUST NOT send Node.js `Buffer` instances directly via `postMessage` without extracting and transferring their underlying `ArrayBuffer` slice, as Buffers undergo structural cloning by default. - Engineers MUST ensure that any transferred `ArrayBuffer` is treated as detached (neutered) immediately after dispatch, preventing read or write attempts on the originating thread. - Services MUST allocate pinned `Uint8Array` or custom `ArrayBuffer` slabs outside message serialization loops to avoid heap fragmentation during rapid message passing. - Worker inbound handlers MUST validate `byteLength > 0` on incoming `ArrayBuffer` instances before processing to guard against accidentally received pre-detached buffers. ## Bad vs Good Implementations ### Disaster: Structural Cloning via Implicit Buffer/Object Passing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting the transfer list forces the JavaScript engine to recursively serialize and duplicate the memory allocation into the target worker's heap. Under sustained I/O, this duplicates multi-gigabyte streams, destroys L3 cache residency, and causes massive GC pauses. ```typescript import { Worker } from "bun"; const worker = new Worker(new URL("./processor.worker.ts", import.meta.url)); export function dispatchChunk(chunk: Uint8Array): void { // ANTI-PATTERN: Passing chunk inside an object without transferList. // Bun falls back to structured cloning, copying every byte over IPC // and triggering severe GC pressure and thread stalls under high throughput. worker.postMessage({ type: "PROCESS_CHUNK", payload: chunk }); } ``` #### Production Standard (Correct) > **Standard**: By explicitly extracting the target slice and declaring `[buffer]` in the transfer list, the memory ownership moves atomically to the target worker thread with O(1) pointer updates. The buffer becomes detached in the sender, eliminating IPC overhead and GC spikes. ```typescript import { Worker } from "bun"; const worker = new Worker(new URL("./processor.worker.ts", import.meta.url)); export function dispatchChunk(chunk: Uint8Array): void { // Extract underlying ArrayBuffer or copy to an isolated ArrayBuffer if shared const buffer: ArrayBuffer = chunk.buffer.slice( chunk.byteOffset, chunk.byteOffset + chunk.byteLength ); // INVARIANT: Transfer ownership of the buffer slice. // Memory is unmapped from current thread and re-mapped in worker instantly (O(1)). worker.postMessage( { type: "PROCESS_CHUNK", payload: buffer }, [buffer] ); // buffer.byteLength is now 0 (neutered/detached); source thread cannot access it. } ``` ### Worker Inbound: Safe Handling and Bidirectional Zero-Copy Echo #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The worker receives a copied or transferred buffer, mutates it, and echoes it back via structured cloning, once again incurring allocation and serialization costs. ```typescript declare const self: Worker; self.onmessage = (event: MessageEvent) => { const { payload } = event.data; // ANTI-PATTERN: Sending back processed TypedArray without transfer list const result = new Uint8Array(payload); result[0] ^= 0xff; self.postMessage({ type: "DONE", result }); }; ``` #### Production Standard (Correct) > **Standard**: The worker strictly asserts buffer integrity (non-zero byteLength) and completes all modifications in-place. It then moves ownership back to the caller using a transfer list, ensuring zero allocations in the IPC loop. ```typescript declare const self: Worker; interface InboundMessage { type: "PROCESS_CHUNK"; payload: ArrayBuffer; } self.onmessage = (event: MessageEvent<InboundMessage>) => { const { type, payload } = event.data; if (type !== "PROCESS_CHUNK" || payload.byteLength === 0) { throw new Error("Protocol violation: Received neutered or invalid ArrayBuffer"); } const view = new Uint8Array(payload); view[0] ^= 0xff; // In-place processing // INVARIANT: Return zero-copy buffer back to supervisor thread self.postMessage( { type: "DONE", result: payload }, [payload] ); }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun Clustered Worker Zero-Copy ArrayBuffer Transfer Standard

Bun Clustered Worker Zero-Copy ArrayBuffer Transfer Standard defines an industrial-grade behavioral standard for backend engineering. Enforces transfer-of-ownership semantics over structural cloning across worker boundaries in multi-threaded Bun microservices. By passing transferable objects via postMessage transfer lists, worker communication bypasses memory duplication, eradicating IPC latency and garbage collection fragmentation under high-throughput network I/O workloads. 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: Implicit Structural Cloning of Binary Payloads Across Bun Worker Threads 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	Implicit Structural Cloning of Binary Payloads Across Bun Worker Threads	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 pass underlying ArrayBuffer references in the second parameter (transfer list) of `postMessage` calls across Bun Worker boundaries.

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.