Bun 1.2 Native WebSocket Backpressure Memory Ceiling and Drain Governor

--- description: Bun 1.2 Native WebSocket Backpressure Memory Ceiling and Drain Governor - Enforces strict socket backpressure management using Bun's native WebSocket return values and drain lifecycle hook. Prevents unbounded native C++ heap accumulation and catastrophic OOM crashes during asymmetric client slow-drain conditions. 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-ceiling" --- # Bun 1.2 Native WebSocket Backpressure Memory Ceiling and Drain Governor > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unchecked ws.send() flooding in async loops without evaluating socket bufferedAmount or implementing the drain lifecycle hook. ## System Constraints You are a Principal Engineer enforcing Bun 1.2 Native WebSocket Backpressure Memory Ceiling. Mandate invariants around ws.send() backpressure feedback, ws.getBufferedAmount(), high-water/low-water mark thresholds, and the drain(ws) callback to eliminate native heap OOM panics caused by slow client consumption. ## Strict Guidelines - Engineers MUST ALWAYS inspect ws.getBufferedAmount() or the byte count returned by ws.send() before or immediately after dispatching outbound frames. - Engineers MUST implement the native websocket.drain(ws) callback in Bun.serve to resume suspended streams or paused producers when the kernel buffer recedes below the low-water mark. - Services MUST enforce a deterministic per-socket high-water mark (e.g., 1MB to 4MB ceiling) and terminate slow-reading consumers with close code 1008 (Policy Violation) if the ceiling is exceeded. - Components NEVER execute unthrottled async iterations, event listeners, or ticker loops that invoke ws.send() blindly without awaiting backpressure resolution or stream pause. - Code SHOULD leverage custom per-connection state inside ws.data (e.g., isPaused, pendingQueue) to manage producer lifecycle state in zero-allocation native memory. ## Bad vs Good Implementations ### Naive Unthrottled WebSocket Stream vs. Backpressure-Governed Stream with Drain Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling ws.send() in a fast interval or data loop without inspecting the return value or ws.getBufferedAmount() causes outbound buffers to accumulate in Bun's internal uSockets/C++ memory. A single slow or stalled client connection will rapidly balloon RAM and trigger an unrecoverable process OOM panic. ```typescript import { serve } from "bun"; serve({ port: 3000, fetch(req, server) { if (server.upgrade(req)) return; return new Response("Upgrade failed", { status: 400 }); }, websocket: { open(ws) { // CRITICAL BUG: Pushing unbounded high-frequency market data to slow client // ws.send() buffers invisibly in native memory until Bun runs out of memory (OOM) const interval = setInterval(() => { const heavyPayload = Buffer.alloc(64 * 1024, 1); ws.send(heavyPayload); }, 1); (ws as any).interval = interval; }, message(ws, message) {}, close(ws) { clearInterval((ws as any).interval); } } }); ``` #### Production Standard (Correct) > **Standard**: Tracks native socket backpressure with ws.getBufferedAmount() and inspects the return of ws.send(). Enforces a 1MB pause threshold and a 4MB eviction ceiling using close code 1008. Uses the Bun native websocket.drain hook to safely unpause the producer only when the kernel buffer recedes. ```typescript import { serve, type ServerWebSocket } from "bun"; interface SocketData { isPaused: boolean; producerTimer?: Timer; } const HIGH_WATER_MARK_BYTES = 1024 * 1024; // 1MB native buffer ceiling const MAX_TOLERATED_BUFFER_BYTES = 4 * 1024 * 1024; // 4MB eviction threshold serve<SocketData>({ port: 3000, fetch(req, server) { if (server.upgrade(req, { data: { isPaused: false } })) return; return new Response("Upgrade failed", { status: 400 }); }, websocket: { open(ws: ServerWebSocket<SocketData>) { ws.data.producerTimer = setInterval(() => { if (ws.data.isPaused) return; const buffered = ws.getBufferedAmount(); if (buffered > MAX_TOLERATED_BUFFER_BYTES) { // Evict pathological slow clients ws.close(1008, "Backpressure buffer ceiling exceeded"); clearInterval(ws.data.producerTimer); return; } if (buffered > HIGH_WATER_MARK_BYTES) { ws.data.isPaused = true; return; } const payload = Buffer.alloc(64 * 1024, 1); const bytesQueuedOrSent = ws.send(payload); if (bytesQueuedOrSent < 0 || ws.getBufferedAmount() > HIGH_WATER_MARK_BYTES) { ws.data.isPaused = true; } }, 1); }, drain(ws: ServerWebSocket<SocketData>) { // Kernel drained buffer below low-water mark; resume producer if (ws.data.isPaused && ws.getBufferedAmount() < HIGH_WATER_MARK_BYTES / 2) { ws.data.isPaused = false; } }, close(ws: ServerWebSocket<SocketData>) { if (ws.data.producerTimer) { clearInterval(ws.data.producerTimer); } } } }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native WebSocket Backpressure Memory Ceiling and Drain Governor

Bun 1.2 Native WebSocket Backpressure Memory Ceiling and Drain Governor defines an industrial-grade behavioral standard for backend engineering. Enforces strict socket backpressure management using Bun's native WebSocket return values and drain lifecycle hook. Prevents unbounded native C++ heap accumulation and catastrophic OOM crashes during asymmetric client slow-drain conditions. 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() flooding in async loops without evaluating socket bufferedAmount or implementing the drain lifecycle hook. 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() flooding in async loops without evaluating socket bufferedAmount or implementing the drain lifecycle hook.	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 byte count returned by ws.send() before or immediately after dispatching outbound frames.

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.