Bun 1.2 WebSocket Kernel Backpressure Throttling Invariant

--- description: Bun 1.2 WebSocket Kernel Backpressure Throttling Invariant - Enforces strict handling of native socket buffer backpressure in Bun 1.2 real-time WebSocket gateways. Mandates checking ws.getBufferedAmount() and the return code of ws.send(), pausing upstream producers, and utilizing the drain(ws) lifecycle callback to prevent unmanaged C++ heap allocation and silent container OOM crashes. globs: src/**/*.{ts,tsx}, server/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-websocket-kernel-backpressure-throttling" --- # Bun 1.2 WebSocket Kernel Backpressure Throttling Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unchecked Fire-and-Forget ws.send() Causing Unbounded Native Memory Bloat and OOM Kills ## System Constraints You are a Principal Engineer enforcing Bun 1.2 WebSocket Kernel Backpressure Throttling Invariants. Mandate native socket buffer inspection, bounded JS queuing, and strict drain callback lifecycle handling on all high-throughput WebSocket streams. ## Strict Guidelines - Engineers MUST ALWAYS inspect ws.getBufferedAmount() before and after dispatching binary or string frames via ws.send(). - Engineers MUST NOT execute fire-and-forget loops over client sets without backpressure checks, as Bun's underlying uWebSockets C++ buffer bypasses JavaScript GC heap limits. - Code MUST declare and implement the `drain(ws)` lifecycle callback in Bun.serve({ websocket: { drain(ws) { ... } } }) to resume paused producers or flush bounded queues. - Services MUST define explicit High-Water Mark (HWM) and Low-Water Mark (LWM) byte thresholds (e.g., HWM: 1 MiB, LWM: 256 KiB) per connection. - Components NEVER buffer unbounded arrays in JavaScript memory when native backpressure triggers; connections violating maximum safety buffers MUST be terminated with 1008 (Policy Violation). ## Bad vs Good Implementations ### Naive Broadcast vs. Bounded Kernel Backpressure Protocol #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly calling ws.send without evaluating ws.getBufferedAmount() or the return value causes unmonitored C++ kernel/socket buffer growth. Under high fan-out with slow clients, memory usage explodes off-heap, causing abrupt container termination by the OS kernel OOM killer. ```typescript import { ServerWebSocket } from "bun"; // ANTI-PATTERN: Fire-and-forget frame dispatching // Under slow-consumer conditions, native uWebSockets buffers accumulate indefinitely. // This creates catastrophic off-heap C++ memory spikes undetected by v8/JSC GC, leading to SIGKILL. export function broadcastMarketData(clients: Set<ServerWebSocket<unknown>>, payload: Uint8Array): void { for (const ws of clients) { ws.send(payload); // Ignores backpressure and return codes } } ``` #### Production Standard (Correct) > **Standard**: Tracks native socket backpressure using ws.getBufferedAmount() and ws.send() status codes. Pauses direct transmission at high-water marks, buffers into a bounded JavaScript queue, enforces hard disconnection on delinquent clients, and smoothly drains backlogged frames inside Bun's native drain() lifecycle hook. ```typescript import { ServerWebSocket, WebSocketHandler } from "bun"; export interface ClientSession { id: string; isBackpressured: boolean; overflowQueue: Uint8Array[]; } const HIGH_WATER_MARK = 1024 * 1024; // 1 MiB backpressure ceiling const LOW_WATER_MARK = 256 * 1024; // 256 KiB resume threshold const MAX_OVERFLOW_FRAMES = 100; // Bounded JS safety limit export function safeSend(ws: ServerWebSocket<ClientSession>, payload: Uint8Array): boolean { if (ws.data.isBackpressured) { if (ws.data.overflowQueue.length >= MAX_OVERFLOW_FRAMES) { ws.close(1008, "Buffer quota exceeded: slow consumer"); return false; } ws.data.overflowQueue.push(payload); return false; } const sentResult = ws.send(payload); const currentBuffered = ws.getBufferedAmount(); // In Bun, ws.send returns the number of buffered bytes or -1 on drop if (sentResult === -1 || currentBuffered > HIGH_WATER_MARK) { ws.data.isBackpressured = true; return false; } return true; } export const websocket: WebSocketHandler<ClientSession> = { open(ws) { ws.data = { id: crypto.randomUUID(), isBackpressured: false, overflowQueue: [] }; }, message(ws, message) { // Ingress handling }, drain(ws) { // Invoked by Bun native runtime when kernel buffer clears below watermark while (ws.data.overflowQueue.length > 0) { if (ws.getBufferedAmount() > LOW_WATER_MARK) { return; // Retain backpressure, await next native drain event } const nextFrame = ws.data.overflowQueue.shift()!; ws.send(nextFrame); } ws.data.isBackpressured = false; }, close(ws) { ws.data.overflowQueue.length = 0; } }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 WebSocket Kernel Backpressure Throttling Invariant

Bun 1.2 WebSocket Kernel Backpressure Throttling Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces strict handling of native socket buffer backpressure in Bun 1.2 real-time WebSocket gateways. Mandates checking ws.getBufferedAmount() and the return code of ws.send(), pausing upstream producers, and utilizing the drain(ws) lifecycle callback to prevent unmanaged C++ heap allocation and silent container OOM crashes. 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() Causing Unbounded Native Memory Bloat and OOM Kills 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() Causing Unbounded Native Memory Bloat and OOM Kills	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() before and after dispatching binary or string frames via ws.send().

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.