Bun 1.2 Native WebSocket Backpressure Ring-Buffer Guardrail

--- description: Bun 1.2 Native WebSocket Backpressure Ring-Buffer Guardrail - Enforces bounded memory allocations and native TCP backpressure handling in high-throughput Bun WebSocket streaming services. Mandates coupling Bun's native `ws.cork()`, `ws.send()`, and `ws.drain()` lifecycle hooks with pre-allocated circular ring-buffers to prevent catastrophic V8/JSC heap exhaustion caused by slow-consumer egress bloat. globs: src/**/*.{ts,js}, server/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-websocket-backpressure-ring-buffer-guardrail" --- # Bun 1.2 Native WebSocket Backpressure Ring-Buffer Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unchecked Fire-and-Forget ws.send() Overrunning Native Kernel Buffers and V8 Heap ## System Constraints You are a Principal Backend Systems Architect enforcing strict Bun 1.2 WebSocket backpressure guardrails. In high-concurrency streaming servers, failing to evaluate the byte return value of `ws.send()` leads to unbounded native heap buffering and out-of-memory crashes when consumers slow down. Mandate that all high-throughput broadcast and streaming loops check return codes, implement fixed-capacity ring buffers, register native `drain` handlers, and drop or throttle frames rather than permitting unbounded heap accumulation. ## Strict Guidelines - Engineers MUST ALWAYS inspect the numerical return code of Bun's `ws.send(data)` (which returns `-1` on drop, `0` on kernel queue saturation, or bytes queued/sent) rather than assuming synchronous delivery. - Engineers MUST NOT append egress frames to unbounded JavaScript arrays when native sockets enter saturated backpressure states. - Services MUST implement a bounded RingBuffer with explicit overwrite or drop strategies (e.g., dropping least-critical ephemeral telemetry or disconnecting persistently lagging consumers) when the buffer exceeds high watermarks. - Code MUST wire the `drain(ws)` socket handler in `Bun.serve` to resume pumping buffered frames from the client ring-buffer until drained or re-saturated. - Code SHOULD leverage `ws.cork(cb)` when dispatching multiple sequential writes to reduce TCP framing overhead and minimize syscall transitions. ## Bad vs Good Implementations ### Unbounded Egress Buffering vs Native Backpressure Ring-Buffer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Ignoring the backpressure return value of ws.send() or pushing unacknowledged buffers into an unbounded JS array causes catastrophic heap bloat when clients experience high latency or packet loss. Without a bounded capacity, slow consumers monopolize the JSC heap and crash the entire node. ```typescript import { ServerWebSocket } from 'bun'; interface ClientState { queue: Uint8Array[]; } // ANTI-PATTERN: Fire-and-forget sending with an unbounded JS array fallback export function broadcastMetric(ws: ServerWebSocket<ClientState>, metric: Uint8Array) { const bytesQueued = ws.send(metric); // If socket is congested, queuing into an unbounded array guarantees an eventual OOM if (bytesQueued <= 0) { ws.data.queue.push(metric); } } Bun.serve<ClientState>({ fetch(req, server) { if (server.upgrade(req, { data: { queue: [] } })) return; return new Response('Upgrade failed', { status: 400 }); }, websocket: { message(ws, message) {}, // Drain handler is omitted or does not drain safely drain(ws) {} } }); ``` #### Production Standard (Correct) > **Standard**: The production solution enforces a fixed pre-allocated ring buffer. When backpressure is encountered (ws.send returns <= 0), the socket enters a backpressured state and enqueues to the ring buffer. If capacity is exceeded, an explicit drop strategy prevents heap blowups. When the native socket drains, Bun triggers the drain event to pump queued items in a single corked cycle. ```typescript import { ServerWebSocket } from 'bun'; const BUFFER_CAPACITY = 256; export class BoundedFrameRing { private buffer: (Uint8Array | null)[] = new Array(BUFFER_CAPACITY).fill(null); private head = 0; private tail = 0; private count = 0; push(frame: Uint8Array): boolean { if (this.count === BUFFER_CAPACITY) { // Explicit drop-oldest policy to prevent heap exhaustion this.head = (this.head + 1) % BUFFER_CAPACITY; this.count--; } this.buffer[this.tail] = frame; this.tail = (this.tail + 1) % BUFFER_CAPACITY; this.count++; return true; } pop(): Uint8Array | null { if (this.count === 0) return null; const item = this.buffer[this.head]; this.buffer[this.head] = null; this.head = (this.head + 1) % BUFFER_CAPACITY; this.count--; return item; } get length(): number { return this.count; } } interface ClientData { ring: BoundedFrameRing; isBackpressured: boolean; } export function pumpClientQueue(ws: ServerWebSocket<ClientData>): void { while (ws.data.ring.length > 0) { const next = ws.data.ring.pop(); if (!next) break; // ws.send returns bytes sent; <= 0 signals backpressure saturation const sent = ws.send(next); if (sent <= 0) { ws.data.isBackpressured = true; return; } } ws.data.isBackpressured = false; } export function dispatchFrame(ws: ServerWebSocket<ClientData>, frame: Uint8Array): void { if (ws.data.isBackpressured) { ws.data.ring.push(frame); return; } const sent = ws.send(frame); if (sent <= 0) { ws.data.isBackpressured = true; ws.data.ring.push(frame); } } Bun.serve<ClientData>({ fetch(req, server) { const success = server.upgrade(req, { data: { ring: new BoundedFrameRing(), isBackpressured: false } }); return success ? undefined : new Response('WebSocket upgrade failed', { status: 400 }); }, websocket: { message(ws, msg) {}, drain(ws) { // Native TCP buffer ready: pump buffered frames within corked transaction ws.cork(() => { pumpClientQueue(ws); }); } } }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native WebSocket Backpressure Ring-Buffer Guardrail

Bun 1.2 Native WebSocket Backpressure Ring-Buffer Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces bounded memory allocations and native TCP backpressure handling in high-throughput Bun WebSocket streaming services. Mandates coupling Bun's native `ws.cork()`, `ws.send()`, and `ws.drain()` lifecycle hooks with pre-allocated circular ring-buffers to prevent catastrophic V8/JSC heap exhaustion caused by slow-consumer egress bloat. 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 Fire-and-Forget ws.send() Overrunning Native Kernel Buffers and V8 Heap 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 Fire-and-Forget ws.send() Overrunning Native Kernel Buffers and V8 Heap	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 inspect the numerical return code of Bun's `ws.send(data)` (which returns `-1` on drop, `0` on kernel queue saturation, or bytes queued/sent) rather than assuming synchronous delivery.

Engineers MUST ALWAYS inspect the numerical return code of Bun's `ws.send(data)` (which returns `-1` on drop, `0` on kernel queue saturation, or bytes queued/sent) rather than assuming synchronous delivery.

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.