Bun Native WebSocket Backpressure & High-Watermark Memory Guardrail

--- description: Bun Native WebSocket Backpressure & High-Watermark Memory Guardrail - Enforces deterministic backpressure handling in Bun 1.2+ native WebSockets by tracking socket kernel send buffers via ws.bufferedAmount and integrating the native drain lifecycle hook. Prevents catastrophic native and engine heap bloat caused by fast streaming producers overwhelming slow TCP consumers. 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-highwatermark-guardrail" --- # Bun Native WebSocket Backpressure & High-Watermark Memory Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded WebSocket Message Dispatching Without Native Drain Suspension Causing Silent OOM Crashes ## System Constraints You are a Principal Backend Architect specializing in high-throughput network runtimes. In Bun 1.2+, WebSockets utilize uWebSockets bindings where unmanaged ws.send calls accumulate unacknowledged payloads in native C++ buffers outside standard GC collection, leading to rapid process termination via the OS OOM killer. You must mandate strict backpressure checks against ws.bufferedAmount, pause upstream data consumers when high-watermark thresholds are tripped, utilize Bun's native websocket.drain hook to resume pulling, and immediately terminate connections exceeding critical hard memory caps. ## Strict Guidelines - Engineers MUST ALWAYS inspect ws.bufferedAmount before dispatching payloads to determine if backpressure thresholds have been reached. - Engineers MUST implement the native drain(ws) callback in Bun.serve websocket definitions to resume paused upstream stream consumers. - Engineers MUST NOT invoke ws.send() inside unbounded async loops or event listeners without explicitly awaiting socket drain availability. - Code SHOULD enforce a two-tier watermark strategy: a High-Watermark (e.g., 64 KiB - 512 KiB) to pause ingress, and a Critical Kill Limit (e.g., 8 MiB - 16 MiB) to disconnect pathological or intentionally stalled clients. - Services MUST attach custom backpressure controllers or deferred promises to the WebSocket ws.data context to coordinate flow control across modules. - Components NEVER buffer messages in unbound JavaScript arrays when the native socket is blocked; upstream producers must be paused at the source. ## Bad vs Good Implementations ### Unthrottled Stream Dispatch vs. High-Watermark Controlled WebSocket Streaming #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The loop pulls from the upstream async generator continuously without checking ws.bufferedAmount. Bun's underlying uWebSockets library will queue every chunk into native C++ memory buffers, bypassing standard garbage collection and triggering an uncatchable OS OOM process kill. ```typescript import { serve } from "bun"; interface SocketData { streamId: string; } serve<SocketData>({ port: 3000, websocket: { async message(ws, message) { const req = JSON.parse(message.toString()); const upstreamStream = getStreamSource(req.streamId); // CRITICAL FLAW: Blindly pumps chunks without checking socket buffer // If client throttles TCP ACK or has low bandwidth, native memory balloons. for await (const chunk of upstreamStream) { ws.send(chunk); } }, open(ws) {}, close(ws) {} }, fetch(req, server) { if (server.upgrade(req, { data: { streamId: "" } })) return; return new Response("Upgrade failed", { status: 400 }); } }); function getStreamSource(id: string): AsyncIterable<Uint8Array> { return {} as any; } ``` #### Production Standard (Correct) > **Standard**: Implements a deterministic high-watermark and hard-kill threshold. If the client experiences network latency and ws.bufferedAmount exceeds 256 KiB, the async iterator pauses by awaiting a promise. Bun's native drain(ws) hook resolves the promise once the kernel buffer drains, resuming the upstream producer without native memory inflation. ```typescript import { serve, type ServerWebSocket } from "bun"; const HIGH_WATERMARK_BYTES = 256 * 1024; // 256 KiB const CRITICAL_LIMIT_BYTES = 8 * 1024 * 1024; // 8 MiB interface SocketData { streamId: string; drainPromise: Promise<void> | null; resolveDrain: (() => void) | null; } serve<SocketData>({ port: 3000, websocket: { open(ws) { ws.data = { streamId: "", drainPromise: null, resolveDrain: null }; }, async message(ws, message) { const req = JSON.parse(message.toString()); ws.data.streamId = req.streamId; const upstreamStream = getStreamSource(req.streamId); for await (const chunk of upstreamStream) { // Guardrail: Disconnect rogue or dead TCP consumers exceeding the hard cap if (ws.bufferedAmount >= CRITICAL_LIMIT_BYTES) { ws.close(1008, "Backpressure buffer limit exceeded"); return; } // Guardrail: Pause pull if buffer exceeds high-watermark if (ws.bufferedAmount >= HIGH_WATERMARK_BYTES) { if (!ws.data.drainPromise) { ws.data.drainPromise = new Promise<void>((resolve) => { ws.data.resolveDrain = resolve; }); } await ws.data.drainPromise; } // Native send returns bytes sent or buffered ws.send(chunk); } }, drain(ws) { // Native callback triggered when kernel buffer drains below low threshold if (ws.data.resolveDrain) { const resolve = ws.data.resolveDrain; ws.data.drainPromise = null; ws.data.resolveDrain = null; resolve(); } }, close(ws) { if (ws.data.resolveDrain) { ws.data.resolveDrain(); } } }, fetch(req, server) { if (server.upgrade(req, { data: { streamId: "", drainPromise: null, resolveDrain: null } })) { return; } return new Response("Upgrade failed", { status: 400 }); } }); function getStreamSource(id: string): AsyncIterable<Uint8Array> { return {} as any; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun Native WebSocket Backpressure & High-Watermark Memory Guardrail

Bun Native WebSocket Backpressure & High-Watermark Memory Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic backpressure handling in Bun 1.2+ native WebSockets by tracking socket kernel send buffers via ws.bufferedAmount and integrating the native drain lifecycle hook. Prevents catastrophic native and engine heap bloat caused by fast streaming producers overwhelming slow TCP consumers. 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: Unbounded WebSocket Message Dispatching Without Native Drain Suspension Causing Silent OOM Crashes 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	Unbounded WebSocket Message Dispatching Without Native Drain Suspension Causing Silent OOM Crashes	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.bufferedAmount before dispatching payloads to determine if backpressure thresholds have been reached.

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.