Bun 1.2 Zero-Copy WebSocket Slab Allocation & Off-Heap Ring Buffers

--- description: Bun 1.2 Zero-Copy WebSocket Slab Allocation & Off-Heap Ring Buffers - Enforces zero-copy slab allocation patterns and pre-allocated ring buffers for Bun 1.2 WebSocket handlers under saturated bidirectional streaming. Eliminates JavaScriptCore GC thrashing and RSS explosion by strictly prohibiting transient buffer instantiation, per-message string encoding, and unbounded in-memory broadcast queues. globs: src/**/*.ts, server/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-websocket-slab-allocation-guardrail" --- # Bun 1.2 Zero-Copy WebSocket Slab Allocation & Off-Heap Ring Buffers > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Allocating Per-Message Buffers and Unbounded Transient Strings Under Saturated WebSocket Throughput ## System Constraints You are a Principal Backend Systems Engineer specializing in high-throughput network architectures on Bun 1.2. Mandate the strict use of pre-allocated slab buffers, zero-copy binary views, and ring-buffer ring topologies for all WebSocket stream handling. Reject any patterns causing ephemeral buffer allocations, per-packet string serialization, or GC heap pressure. ## Strict Guidelines - Engineers MUST ALWAYS pre-allocate fixed-size slab memory (e.g., SharedArrayBuffer or persistent Uint8Array) outside request and message lifecycles. - Engineers MUST NOT call Buffer.from(), Buffer.alloc(), or String.prototype operations inside hot WebSocket 'message', 'open', or broadcast loops. - Code SHOULD leverage binary encoding (TypeArrays, DataView, FlatBuffers, or Protobuf) and write into existing slab partitions using sub-views instead of allocating slices. - Services MUST monitor WebSocket backpressure via ws.getBufferedAmount() and drop or throttle frames when backpressure thresholds are breached to prevent RSS blowup. - Components NEVER store incoming message references asynchronously without explicitly copying them into a reserved slab slot, as Bun's underlying socket buffers are ephemeral. ## Bad vs Good Implementations ### Slab Allocation vs. Per-Frame Buffer Allocation in Bun WebSocket Server #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Allocates transient strings and Buffer instances inside the hot message handler. At high throughput (100k+ msg/s), this causes severe JavaScriptCore Garbage Collector latency spikes and uncontrolled RSS growth. ```typescript import { serve } from "bun"; interface MarketData { symbol: string; price: number; timestamp: number; } // ANTI-PATTERN: Serializing JSON to string and allocating a new Buffer for every message // across thousands of concurrent connections generates continuous GC heap churn. serve({ port: 3000, websocket: { message(ws, message) { const payload = JSON.parse(message.toString()) as MarketData; // Allocates new strings and Uint8Array buffers on every single frame const response = JSON.stringify({ symbol: payload.symbol, price: payload.price * 1.01, processedAt: Date.now() }); const buffer = Buffer.from(response); ws.send(buffer); } }, fetch(req, server) { if (server.upgrade(req)) return; return new Response("Upgrade failed", { status: 400 }); } }); ``` #### Production Standard (Correct) > **Standard**: Employs an off-heap ring buffer slab using ArrayBuffer and DataView. Messages are read and written using typed sub-arrays without transient allocations, zero string parsing, and with explicit socket backpressure protection. ```typescript import { serve, type ServerWebSocket } from "bun"; // PRODUCTION FIX: Pre-allocated slab memory layout // Struct layout: symbolId (uint16 = 2B), price (float64 = 8B), timestamp (float64 = 8B) = 18 bytes const PACKET_SIZE = 18; const SLAB_CAPACITY = 65536; // 64KB slab const slab = new ArrayBuffer(SLAB_CAPACITY); const slabBytes = new Uint8Array(slab); const slabDataView = new DataView(slab); let slabOffset = 0; function writePacketToSlab(symbolId: number, price: number, timestamp: number): Uint8Array { if (slabOffset + PACKET_SIZE > SLAB_CAPACITY) { slabOffset = 0; // Wrap ring buffer pointer } const offset = slabOffset; slabDataView.setUint16(offset, symbolId, true); slabDataView.setFloat64(offset + 2, price, true); slabDataView.setFloat64(offset + 10, timestamp, true); slabOffset += PACKET_SIZE; // Zero-copy subarray view (no heap allocation of backing ArrayBuffer) return slabBytes.subarray(offset, offset + PACKET_SIZE); } serve({ port: 3000, websocket: { // Receive binary directly without string conversion binaryType: "uint8array", message(ws: ServerWebSocket<unknown>, message) { if (!(message instanceof Uint8Array) || message.byteLength < PACKET_SIZE) { return; } // Check native backpressure before pushing down socket if (ws.getBufferedAmount() > 1024 * 64) { return; // Drop or throttle frame to preserve memory invariants } const view = new DataView(message.buffer, message.byteOffset, message.byteLength); const symbolId = view.getUint16(0, true); const price = view.getFloat64(2, true) * 1.01; const timestamp = performance.now(); const outboundFrame = writePacketToSlab(symbolId, price, timestamp); ws.send(outboundFrame, true); } }, fetch(req, server) { if (server.upgrade(req)) return; return new Response("Upgrade failed", { status: 400 }); } }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Zero-Copy WebSocket Slab Allocation & Off-Heap Ring Buffers

Bun 1.2 Zero-Copy WebSocket Slab Allocation & Off-Heap Ring Buffers defines an industrial-grade behavioral standard for backend engineering. Enforces zero-copy slab allocation patterns and pre-allocated ring buffers for Bun 1.2 WebSocket handlers under saturated bidirectional streaming. Eliminates JavaScriptCore GC thrashing and RSS explosion by strictly prohibiting transient buffer instantiation, per-message string encoding, and unbounded in-memory broadcast queues. 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: Allocating Per-Message Buffers and Unbounded Transient Strings Under Saturated WebSocket Throughput 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	Allocating Per-Message Buffers and Unbounded Transient Strings Under Saturated WebSocket Throughput	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 pre-allocate fixed-size slab memory (e.g., SharedArrayBuffer or persistent Uint8Array) outside request and message lifecycles.

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.