Bun 1.2 Native Cluster WebSocket Zero-Copy Socket Handoff & Backpressure Architecture

--- description: Bun 1.2 Native Cluster WebSocket Zero-Copy Socket Handoff & Backpressure Architecture - Enforces deterministic, memory-safe WebSocket socket handoff and worker load distribution across multi-core Bun cluster architectures. Prevents intermediate heap buffer cloning, frame desynchronization, and silent frame drops during cross-worker migration under saturation by mandating zero-copy transfer lists and native backpressure drain lifecycle hooks. globs: src/**/*.ts, server/**/*.ts, workers/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-cluster-websocket-zero-copy-handoff-production-standard" --- # Bun 1.2 Native Cluster WebSocket Zero-Copy Socket Handoff & Backpressure Architecture > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Heap-Cloned WebSocket IPC Handoff Without Backpressure Drain Synchronization ## System Constraints You are a Principal Software Architect enforcing the Bun 1.2 Native Cluster WebSocket Zero-Copy Handoff Standard. You must reject any architecture that re-buffers WebSocket frames through standard JSON-serialized IPC, fails to inspect TCP backpressure prior to worker handoff, or performs duplicate allocations on payload migrations across worker threads. Ensure strict compliance with Bun's native socket handles, zero-copy ArrayBuffer transferables, and backpressured drain synchronization. ## Strict Guidelines - Engineers MUST ALWAYS verify backpressure states via `ws.getBufferedAmount()` before triggering worker migration or frame relay to prevent unmonitored memory ballooning. - Engineers MUST NOT serialize binary WebSocket frames into Node.js Buffers or JSON payloads across IPC boundaries; zero-copy ArrayBuffer transfer lists or native handle transfers must be utilized exclusively. - Code SHOULD implement native `drain(ws)` handlers in `Bun.serve` to resume throttled pipelines when cross-worker channel saturation drops below the configured low-water mark. - Services MUST isolate connection state metadata from payload buffers during worker handoff, executing atomic handshakes to avoid duplicate socket ownership across processes. - Components NEVER drop or close active client sockets during cluster rebalancing; worker nodes must complete socket handoff or cleanly backpressure clients using WebSocket close code 1013 (Try Again Later) under absolute queue saturation. ## Bad vs Good Implementations ### Cross-Worker Socket Handoff and Frame Relay #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Converting binary buffers into JS arrays and serializing over standard IPC creates high garbage collection pressure, causes frame re-buffering, and ignores socket backpressure, resulting in OOM crashes under cluster saturation. ```typescript import { type ServerWebSocket } from 'bun'; // ANTI-PATTERN: Heap-cloning payloads, JSON IPC re-buffering, and ignoring backpressure export function relayToWorker(ws: ServerWebSocket<any>, worker: Worker, payload: Uint8Array) { // Incurring deep copy into V8/JSC heap via standard object packaging const message = { clientId: ws.data.id, // Serializing array causes massive heap allocations under high throughput data: Array.from(payload), }; // No check on ws.getBufferedAmount() or worker queue pressure worker.postMessage(message); // Blind transmission ignores client-side socket saturation ws.send(payload); } ``` #### Production Standard (Correct) > **Standard**: Transfers ArrayBuffer ownership directly across threads using transfer lists, eliminating heap allocations, and strictly enforces backpressure checking via getBufferedAmount() before queuing work. ```typescript import { type ServerWebSocket } from 'bun'; interface SocketState { id: string; isMigrating: boolean; } const HIGH_WATER_MARK_BYTES = 1024 * 1024; // 1MB // PRODUCTION PATTERN: Zero-copy transferables, explicit backpressure verification export function relayToWorkerZeroCopy( ws: ServerWebSocket<SocketState>, worker: Worker, payload: Uint8Array ): boolean { // 1. Guard against local TCP socket backpressure if (ws.getBufferedAmount() > HIGH_WATER_MARK_BYTES) { return false; // Backpressure active: caller must wait for drain } // 2. Extract underlying ArrayBuffer for zero-copy ownership transfer const buffer = payload.buffer.slice( payload.byteOffset, payload.byteOffset + payload.byteLength ); // 3. Dispatch to worker transferring buffer ownership without heap duplication worker.postMessage( { type: 'SOCKET_FRAME', clientId: ws.data.id, byteLength: buffer.byteLength, payload: buffer }, [buffer] // Zero-copy transfer list: memory is detached from caller thread ); return true; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native Cluster WebSocket Zero-Copy Socket Handoff & Backpressure Architecture

Bun 1.2 Native Cluster WebSocket Zero-Copy Socket Handoff & Backpressure Architecture defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic, memory-safe WebSocket socket handoff and worker load distribution across multi-core Bun cluster architectures. Prevents intermediate heap buffer cloning, frame desynchronization, and silent frame drops during cross-worker migration under saturation by mandating zero-copy transfer lists and native backpressure drain lifecycle hooks. 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: Heap-Cloned WebSocket IPC Handoff Without Backpressure Drain Synchronization 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	Heap-Cloned WebSocket IPC Handoff Without Backpressure Drain Synchronization	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 verify backpressure states via `ws.getBufferedAmount()` before triggering worker migration or frame relay to prevent unmonitored memory ballooning.

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.