Bun 1.2 Zero-Copy WebSocket Backpressure and Buffer Ring Invariant

--- description: Bun 1.2 Zero-Copy WebSocket Backpressure and Buffer Ring Invariant - Enforces non-blocking WebSocket I/O through strict backpressure monitoring using ws.bufferedAmount, the drain lifecycle hook, and zero-copy circular buffer pools in Bun 1.2. Prevents catastrophic native memory leaks, unmonitored TCP socket buffer ballooning, and heap exhaustion under high-throughput broadcast fan-out workloads. globs: src/**/*.{ts,tsx}, server/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-websocket-backpressure-buffer-ring-invariant" --- # Bun 1.2 Zero-Copy WebSocket Backpressure and Buffer Ring Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unchecked ws.send() Broadcasting and Ephemeral Buffer Allocations Causing Native Heap Exhaustion ## System Constraints You are a Principal Engineer enforcing Bun 1.2 Zero-Copy WebSocket Backpressure and Buffer Ring Invariants. You must ensure all WebSocket broadcast mechanisms monitor ws.bufferedAmount against a strict high-water mark, respect the drain lifecycle handler, and reuse pre-allocated circular ArrayBuffer/Uint8Array pools to prevent GC pauses and native memory exhaustion. ## Strict Guidelines - Engineers MUST ALWAYS check ws.bufferedAmount against a configured high-water mark (e.g., 64KB) prior to calling ws.send(). - Engineers MUST ALWAYS implement the drain(ws) callback in Bun.serve WebSocket options to resume transmission for throttled connections. - Engineers MUST NOT call ws.send() unconditionally inside loops or broadcast iterators without verifying socket queue pressure. - Services MUST allocate broadcast frames from a bounded circular buffer pool (ArrayBuffer/SharedArrayBuffer) rather than instantiating new Uint8Array or JSON string allocations per connection. - Services MUST drop or terminate slow consumers whose ws.bufferedAmount exceeds an absolute maximum threshold (e.g., 1MB) to protect server stability. ## Bad vs Good Implementations ### Unchecked WebSocket Broadcasting vs Backpressure-Gated Ring Buffer Pool #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Iterating over connected clients and immediately dispatching newly serialized JSON strings ignores ws.bufferedAmount. Slow consumers silently accumulate unbounded bytes in the native C++ transport queue, driving native memory beyond container limits and causing silent process termination without triggering GC. ```typescript import { serve } from "bun"; const clients = new Set<any>(); serve({ port: 8080, websocket: { open(ws) { clients.add(ws); }, close(ws) { clients.delete(ws); }, message(ws, message) {} }, fetch(req, server) { if (server.upgrade(req)) return; return new Response("Upgrade failed", { status: 400 }); } }); // Anti-pattern: Unbounded allocations & zero backpressure checks function broadcastTelemetry(data: object) { const payload = JSON.stringify(data); for (const client of clients) { // Allocates new strings, ignores client socket buffer depth, // and forces native libuv/uSockets buffer ballooning to crash the process. client.send(payload); } } ``` #### Production Standard (Correct) > **Standard**: Implements strict backpressure management: evaluates ws.bufferedAmount against a high-water mark, disconnects pathologically slow clients exceeding 1MB, leverages the native drain callback to resume transmission, and uses a pre-allocated typed buffer ring to avoid V8 heap churn. ```typescript import { serve, type ServerWebSocket } from "bun"; interface ClientData { isThrottled: boolean; } const HWM_BYTES = 64 * 1024; // 64 KiB High-Water Mark const DROP_BYTES = 1024 * 1024; // 1 MiB Hard Limit const RING_BUFFER_SIZE = 4096; class BroadcastBufferRing { private pool: Uint8Array = new Uint8Array(RING_BUFFER_SIZE); write(data: Uint8Array): Uint8Array { if (data.byteLength > RING_BUFFER_SIZE) { throw new Error("Frame exceeds ring buffer capacity"); } this.pool.set(data, 0); return this.pool.subarray(0, data.byteLength); } } const ringBuffer = new BroadcastBufferRing(); const clients = new Set<ServerWebSocket<ClientData>>(); serve<ClientData>({ port: 8080, websocket: { open(ws) { ws.data = { isThrottled: false }; clients.add(ws); }, close(ws) { clients.delete(ws); }, drain(ws) { // Socket drained below low-water mark; clear throttled flag if (ws.bufferedAmount < HWM_BYTES) { ws.data.isThrottled = false; } }, message(ws, msg) {} }, fetch(req, server) { if (server.upgrade(req, { data: { isThrottled: false } })) return; return new Response("Upgrade failed", { status: 400 }); } }); export function safeBroadcast(payload: Uint8Array) { const view = ringBuffer.write(payload); for (const client of clients) { if (client.bufferedAmount > DROP_BYTES) { client.close(1008, "Exceeded max buffer capacity"); clients.delete(client); continue; } if (client.bufferedAmount >= HWM_BYTES) { client.data.isThrottled = true; continue; // Skip until drain callback executes } client.send(view); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Zero-Copy WebSocket Backpressure and Buffer Ring Invariant

Bun 1.2 Zero-Copy WebSocket Backpressure and Buffer Ring Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces non-blocking WebSocket I/O through strict backpressure monitoring using ws.bufferedAmount, the drain lifecycle hook, and zero-copy circular buffer pools in Bun 1.2. Prevents catastrophic native memory leaks, unmonitored TCP socket buffer ballooning, and heap exhaustion under high-throughput broadcast fan-out 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: Unchecked ws.send() Broadcasting and Ephemeral Buffer Allocations Causing Native Heap Exhaustion 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	Unchecked ws.send() Broadcasting and Ephemeral Buffer Allocations Causing Native Heap Exhaustion	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 check ws.bufferedAmount against a configured high-water mark (e.g., 64KB) prior to calling ws.send().

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.