Bun 1.2 Native WebSocket Zero-Loss Backpressure Drain Protocol

--- description: Bun 1.2 Native WebSocket Zero-Loss Backpressure Drain Protocol - Guarantees process resilience under high-concurrency event bursts by wiring kernel socket drain readiness directly to async iterator flow-control. Prevents silent message drops and memory bloat caused by unmonitored uWebSockets buffers in Bun.serve. 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-drain-protocol" --- # Bun 1.2 Native WebSocket Zero-Loss Backpressure Drain Protocol > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Fire-and-forget ws.send in unthrottled loops triggering uSockets buffer overflow and process OOM. ## System Constraints You are a Principal Software Architect enforcing Bun 1.2 Native WebSocket backpressure safety standards. Mandate zero-loss flow-control by coupling upstream async iterators to Bun's native drain hooks, monitoring buffered amounts, and preventing unbounded memory growth during high-throughput event spikes. ## Strict Guidelines - Engineers MUST ALWAYS inspect ws.getBufferedAmount() or the return code of ws.send() before pulling subsequent events from async producers. - Engineers MUST NOT stream data across WebSockets using unthrottled for-await loops without a drain-synchronized pausing mechanism. - Code SHOULD establish distinct HIGH_WATER_MARK (e.g., 64 KiB) and LOW_WATER_MARK (e.g., 16 KiB) boundaries to eliminate buffer flapping under load. - Services MUST define the native drain(ws) callback inside Bun.serve({ websocket: { drain(ws) { ... } } }) to resume paused producers when kernel buffers clear. - Components NEVER swallow WebSocket close events during paused states; deferred drain promises MUST be rejected or resolved on socket termination to prevent iterator deadlock. ## Bad vs Good Implementations ### Unthrottled Stream Consumption into Native Bun WebSocket #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Iterating through the stream without evaluating ws.getBufferedAmount() causes fast producers to flood Bun's internal uSockets send queue when the client socket is saturated. Memory expands unboundedly, ending in dropped frames or a process-wide OOM crash. ```typescript import { serve } from "bun"; serve<{ clientId: string; }>({ fetch(req, server) { server.upgrade(req, { data: { clientId: "client-1" } }); return undefined; }, websocket: { async open(ws) { const producer = getEventStream(); // AsyncIterable<Uint8Array> // CRITICAL VIOLATION: Loop ignores kernel send buffer limits. // Slow consumer causes unbounded uSockets heap growth and process OOM. for await (const chunk of producer) { ws.send(chunk); } }, message(ws, msg) {}, close(ws) {} } }); ``` #### Production Standard (Correct) > **Standard**: Implements an asynchronous backpressure gate. Upstream iteration suspends when ws.getBufferedAmount() hits HIGH_WATER_MARK. Bun's native drain hook resolves the gate when the buffer clears below LOW_WATER_MARK, assuring zero message loss and deterministic memory bounds. ```typescript import { serve, type ServerWebSocket } from "bun"; const HIGH_WATER_MARK = 64 * 1024; // 64 KiB const LOW_WATER_MARK = 16 * 1024; // 16 KiB interface WsContext { clientId: string; drainResolver: (() => void) | null; } serve<WsContext>({ fetch(req, server) { server.upgrade(req, { data: { clientId: crypto.randomUUID(), drainResolver: null } }); return undefined; }, websocket: { async open(ws: ServerWebSocket<WsContext>) { const producer = getEventStream(); try { for await (const chunk of producer) { if (ws.readyState !== 1) break; // Halt producer if uSockets buffer exceeds safe limit if (ws.getBufferedAmount() >= HIGH_WATER_MARK) { await new Promise<void>((resolve) => { ws.data.drainResolver = resolve; }); } ws.send(chunk); } } catch (err) { ws.close(1011, "Stream processing aborted"); } }, drain(ws: ServerWebSocket<WsContext>) { // Resume upstream consumption when buffer drains below low-water mark if (ws.data.drainResolver && ws.getBufferedAmount() <= LOW_WATER_MARK) { const unblock = ws.data.drainResolver; ws.data.drainResolver = null; unblock(); } }, message(ws, msg) {}, close(ws: ServerWebSocket<WsContext>) { // Clear suspended promises to avoid resource leaks if (ws.data.drainResolver) { ws.data.drainResolver(); ws.data.drainResolver = null; } } } }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native WebSocket Zero-Loss Backpressure Drain Protocol

Bun 1.2 Native WebSocket Zero-Loss Backpressure Drain Protocol defines an industrial-grade behavioral standard for backend engineering. Guarantees process resilience under high-concurrency event bursts by wiring kernel socket drain readiness directly to async iterator flow-control. Prevents silent message drops and memory bloat caused by unmonitored uWebSockets buffers in Bun.serve. 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: Fire-and-forget ws.send in unthrottled loops triggering uSockets buffer overflow and process OOM. 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	Fire-and-forget ws.send in unthrottled loops triggering uSockets buffer overflow and process OOM.	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 ws.getBufferedAmount() or the return code of ws.send() before pulling subsequent events from async producers.

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.