Bun 1.2 Lock-Free SharedArrayBuffer Ring Buffer for Clustered Ingestion

--- description: Bun 1.2 Lock-Free SharedArrayBuffer Ring Buffer for Clustered Ingestion - Mandates lock-free ring buffers backed by SharedArrayBuffer and typed Atomics for high-throughput inter-worker messaging in Bun 1.2 clusters. Eliminates event-loop stalls and garbage collection thrashing caused by structured clone serialization during sustained WebSocket ingestion (>10k msg/sec). globs: src/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-sharedarraybuffer-zero-copy-cluster-routing" --- # Bun 1.2 Lock-Free SharedArrayBuffer Ring Buffer for Clustered Ingestion > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Structured Clone Worker postMessage Flooding in High-Throughput Ingestion Pipelines ## System Constraints You are a Principal Systems Architect enforcing memory invariants in Bun 1.2 clustered microservices. Enforce lock-free SharedArrayBuffer ring buffers and typed Atomics over default postMessage structured clone serialization for WebSocket data distribution across worker threads. Reject any worker design passing serialized JSON or non-transferred payload buffers across worker boundaries under high throughput. ## Strict Guidelines - Engineers MUST ALWAYS allocate a single SharedArrayBuffer structured into a power-of-two circular ring buffer for worker cross-talk in high-throughput pipelines. - Engineers MUST synchronize ring buffer head and tail pointers using Atomics (Atomics.load, Atomics.store, Atomics.compareExchange, Atomics.wait, Atomics.notify) with explicit memory ordering on Int32Array views. - Engineers MUST NOT invoke worker.postMessage(data) with structured clone objects or ArrayBuffers on per-message WebSocket frame reception paths. - Buffer capacity MUST be sized to a power of two to permit bitwise masking operations (index & (CAPACITY - 1)) instead of modulo arithmetic. - Payload descriptors MUST be written before atomic head update using Atomics.store(..., 'release' semantics) to guarantee memory visibility to the consumer worker. - Components NEVER re-instantiate or reallocate Uint8Array views per incoming packet; pre-allocate contiguous memory slices within the SharedArrayBuffer. ## Bad vs Good Implementations ### Zero-Copy Lock-Free Ring Buffer vs. Structured Clone postMessage #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Sending rich objects or non-shared memory buffers via worker.postMessage forces Bun to execute structured clone serialization on every frame. At 50k+ messages/sec, this triggers massive GC pressure, CPU saturation, and micro-stalls in the WebSocket ingress thread. ```typescript import { Worker } from 'bun'; const worker = new Worker('./worker.ts'); // ANTI-PATTERN: Serializing JSON objects and copying binary buffers via postMessage // triggers the V8/JSC structured clone algorithm on every frame, choking the event loop. Bun.serve({ port: 3000, websocket: { message(ws, message) { const payload = typeof message === 'string' ? JSON.parse(message) : message; worker.postMessage({ clientId: ws.data.id, timestamp: Date.now(), payload }); } } }); ``` #### Production Standard (Correct) > **Standard**: Memory is allocated upfront in a single SharedArrayBuffer. Writing uses atomic pointer operations and in-place memory copies, avoiding structured clone serialization entirely and decoupling ingest rate from the V8/JSC GC cycle. ```typescript import { Worker } from 'bun'; const RING_BUFFER_SIZE = 1024 * 1024; // 1MB power-of-two ring const HEADER_SIZE = 16; // [head: Int32, tail: Int32, reserved1: Int32, reserved2: Int32] const sab = new SharedArrayBuffer(HEADER_SIZE + RING_BUFFER_SIZE); const control = new Int32Array(sab, 0, 4); const storage = new Uint8Array(sab, HEADER_SIZE, RING_BUFFER_SIZE); const worker = new Worker('./worker.ts'); worker.postMessage({ type: 'INIT_RING', sharedBuffer: sab }); Bun.serve({ port: 3000, websocket: { message(ws, rawData) { const bytes = typeof rawData === 'string' ? Buffer.from(rawData) : new Uint8Array(rawData); const length = bytes.byteLength; const packetSize = 4 + length; // 4-byte length prefix + payload const head = Atomics.load(control, 0); const tail = Atomics.load(control, 1); const available = (tail <= head) ? RING_BUFFER_SIZE - (head - tail) : tail - head; if (available <= packetSize) { // Ring buffer overflow: drop packet or apply backpressure return; } let writeIdx = head & (RING_BUFFER_SIZE - 1); new DataView(storage.buffer, HEADER_SIZE + writeIdx, 4).setUint32(0, length, true); writeIdx = (writeIdx + 4) & (RING_BUFFER_SIZE - 1); storage.set(bytes, writeIdx); Atomics.store(control, 0, head + packetSize); Atomics.notify(control, 0, 1); } } }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Lock-Free SharedArrayBuffer Ring Buffer for Clustered Ingestion

Bun 1.2 Lock-Free SharedArrayBuffer Ring Buffer for Clustered Ingestion defines an industrial-grade behavioral standard for backend engineering. Mandates lock-free ring buffers backed by SharedArrayBuffer and typed Atomics for high-throughput inter-worker messaging in Bun 1.2 clusters. Eliminates event-loop stalls and garbage collection thrashing caused by structured clone serialization during sustained WebSocket ingestion (>10k msg/sec). 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 Worker postMessage Flooding in High-Throughput Ingestion Pipelines 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 Worker postMessage Flooding in High-Throughput Ingestion Pipelines	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 allocate a single SharedArrayBuffer structured into a power-of-two circular ring buffer for worker cross-talk in high-throughput pipelines.

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.