Bun 1.2 WebSocket Backpressure High-Water Mark and Drain Invariant

--- description: Bun 1.2 WebSocket Backpressure High-Water Mark and Drain Invariant - Enforces non-blocking backpressure checks and per-socket buffer boundaries on Bun WebSocket connections using Bun.serve. Mandates tracking ws.send() return byte counts, monitoring ws.readyState, registering drain() callbacks, and enforcing high-water mark buffer ceilings to prevent slow-client buffer inflation and fatal Node/Bun process OOM termination. globs: src/**/*.{ts,js}, server/**/*.{ts,js}, apps/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-websocket-backpressure-drain-invariant-bun-1-2-websocke-621" --- # Bun 1.2 WebSocket Backpressure High-Water Mark and Drain Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unchecked Fire-and-Forget ws.send() Loops Inducing Unbounded C++ Heap Growth and Slow-Client OOM ## System Constraints You are a Principal Backend Systems Engineer enforcing Bun 1.2 WebSocket Backpressure Drain Invariants. Mandate strict backpressure inspection across all Bun.serve WebSocket implementations. Never allow fire-and-forget ws.send() calls during high-throughput broadcasts or streaming loops. Enforce explicit handling of partial/queued byte counts returned by ws.send(), verify ws.isPaused / ws.readyState, maintain per-socket high-water marks, implement the native websocket.drain hook, and aggressively terminate slow loris clients exceeding memory bounds. ## Strict Guidelines - Engineers MUST ALWAYS inspect the numeric return value of `ws.send()`, which indicates the number of bytes queued or sent to the underlying kernel buffer. - Engineers MUST pause producer subscriptions (`ws.cork()`, unsubscribing, or pausing data streams) whenever the queued buffer exceeds the designated per-socket high-water mark (e.g., 64 KiB to 1 MiB). - Services MUST implement the `drain(ws)` lifecycle handler in the `Bun.serve({ websocket: { ... } })` configuration to resume downstream writes or unpause upstream data producers. - Engineers MUST NOT maintain an unbounded application-level queue in JavaScript memory as a fallback when `ws.send()` reports saturated buffers. - Code MUST explicitly drop slow clients with `ws.close(1008, 'Policy Violation: Backpressure Exceeded')` or `ws.terminate()` if a connection exceeds the absolute maximum backpressure threshold. - Components NEVER execute raw iterative broadcasts without checking client buffer depths or leveraging Bun's native topic subscription publishing engine (`server.publish`). ## Bad vs Good Implementations ### Unchecked Broadcast Loop Leading to Process OOM vs Backpressure-Safe Drain Pattern #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Iterating over large collections and invoking `ws.send()` without inspecting its return value or checking whether the kernel socket buffer is full causes Bun's internal memory buffer to scale indefinitely. A single slow consumer will absorb hundreds of megabytes in the native runtime, exposing the entire server to Slow Loris attacks and sudden out-of-memory crashes. ```typescript import type { ServerWebSocket } from 'bun'; interface ClientData { id: string; } Bun.serve<ClientData>({ port: 3000, fetch(req, server) { if (server.upgrade(req, { data: { id: crypto.randomUUID() } })) return; return new Response('Expected WebSocket upgrade', { status: 400 }); }, websocket: { open(ws) { console.log(`Connected: ${ws.data.id}`); }, message(ws, message) { // CRITICAL BUG: Blind loop over thousands of items. // Ignores ws.send return code. Sockets on slow 3G will buffer indefinitely // in the underlying C++ WebKit WebSocket layer until process crashes from OOM. const streamData = getHighThroughputTelemetry(); for (const chunk of streamData) { ws.send(JSON.stringify(chunk)); } }, close(ws) {} } }); function getHighThroughputTelemetry(): Array<{ id: number; data: string }> { return Array.from({ length: 50_000 }, (_, i) => ({ id: i, data: 'x'.repeat(1024) })); } ``` #### Production Standard (Correct) > **Standard**: The good pattern enforces the drain lifecycle invariant. It tracks the return value of `ws.send()`, compares it to a calibrated high-water mark, yields processing if the OS/native buffer is saturated, relies on the `drain(ws)` hook to resume streaming, and terminates predatory or unresponsive slow clients before they exhaust process memory. ```typescript import type { ServerWebSocket } from 'bun'; interface SocketState { id: string; pendingChunks: string[]; paused: boolean; } const HIGH_WATER_MARK_BYTES = 1024 * 512; // 512 KiB per socket const CRITICAL_DROP_BYTES = 1024 * 1024 * 2; // 2 MiB hard limit Bun.serve<SocketState>({ port: 3000, fetch(req, server) { const state: SocketState = { id: crypto.randomUUID(), pendingChunks: [], paused: false }; if (server.upgrade(req, { data: state })) return; return new Response('Upgrade failed', { status: 400 }); }, websocket: { open(ws: ServerWebSocket<SocketState>) { console.log(`Client connected: ${ws.data.id}`); }, message(ws: ServerWebSocket<SocketState>, message) { // Ingest generator or paginated buffer const chunks = Array.from({ length: 10_000 }, (_, i) => `chunk-${i}-${'y'.repeat(512)}`); ws.data.pendingChunks.push(...chunks); flushBufferedChunks(ws); }, drain(ws: ServerWebSocket<SocketState>) { // Invariant: Native drain event triggers when socket buffer falls below low-water mark ws.data.paused = false; flushBufferedChunks(ws); }, close(ws: ServerWebSocket<SocketState>, code, reason) { ws.data.pendingChunks.length = 0; } } }); function flushBufferedChunks(ws: ServerWebSocket<SocketState>): void { while (ws.data.pendingChunks.length > 0) { const nextChunk = ws.data.pendingChunks[0]; // ws.send returns: -1 on error, 0 if dropped, or number of queued bytes const sendResult = ws.send(nextChunk); if (sendResult === -1) { ws.close(1011, 'Send failure'); return; } // Check queued byte size against critical boundaries if (sendResult > CRITICAL_DROP_BYTES) { console.error(`Terminating slow client ${ws.data.id}: backpressure exceeded ${sendResult} bytes`); ws.data.pendingChunks.length = 0; ws.close(1008, 'Backpressure threshold exceeded'); return; } // Successfully handed off to network layer ws.data.pendingChunks.shift(); // If sendResult exceeds high water mark, yield thread and wait for drain() if (sendResult > HIGH_WATER_MARK_BYTES) { ws.data.paused = true; break; } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 WebSocket Backpressure High-Water Mark and Drain Invariant

Bun 1.2 WebSocket Backpressure High-Water Mark and Drain Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces non-blocking backpressure checks and per-socket buffer boundaries on Bun WebSocket connections using Bun.serve. Mandates tracking ws.send() return byte counts, monitoring ws.readyState, registering drain() callbacks, and enforcing high-water mark buffer ceilings to prevent slow-client buffer inflation and fatal Node/Bun process OOM termination. 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() Loops Inducing Unbounded C++ Heap Growth and Slow-Client 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	Unchecked Fire-and-Forget ws.send() Loops Inducing Unbounded C++ Heap Growth and Slow-Client 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 the numeric return value of `ws.send()`, which indicates the number of bytes queued or sent to the underlying kernel buffer.

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.