Bun 1.2 Native WebSocket Kernel Backpressure and Buffer Draining Standard

--- description: Bun 1.2 Native WebSocket Kernel Backpressure and Buffer Draining Standard - Mandates explicit C-level memory buffer monitoring and drain-event orchestration for Bun native WebSockets. In high-throughput streaming pipelines, blind calls to ws.send() accumulate un-drained packets inside native uWebSockets C++ ring buffers outside the JavaScript runtime heap, evading V8/JSC GC thresholds and triggering silent OS OOM termination. This standard enforces watermarked backpressure control, producer pause/resume states, and bounded client disconnect thresholds. globs: src/**/*.{ts,tsx}, server/**/*.{ts,tsx}, services/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-websocket-kernel-backpressure-standard" --- # Bun 1.2 Native WebSocket Kernel Backpressure and Buffer Draining Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Blind ws.send() invocation during high-throughput streaming without bufferedAmount tracking and drain lifecycle handling. ## System Constraints You are a Principal Engineer enforcing Bun 1.2 Native WebSocket Kernel Backpressure Standard. Mandate invariants that eliminate unbounded C-level socket memory accumulation. Native Bun WebSockets rely on uWebSockets C++ buffers. When downstream consumers possess insufficient network throughput, data queued via `ws.send()` builds up within native memory allocations invisible to JavaScript garbage collection. You must enforce explicit backpressure logic using `ws.bufferedAmount`, the `drain(ws)` socket handler, high-watermark producer pausing, low-watermark producer resuming, and eviction of unrecoverable slow consumers. ## Strict Guidelines - Engineers MUST ALWAYS check `ws.bufferedAmount` prior to writing payload buffers during continuous or high-throughput transmissions. - Engineers MUST NOT continuously push data to a native Bun WebSocket if `ws.bufferedAmount` exceeds the configured HIGH_WATER_MARK (default: 1MB). - Code SHOULD define a LOW_WATER_MARK (default: 256KB) and register the `drain(ws)` callback in `Bun.serve({ websocket: { drain } })` to signal producer resumption. - Services MUST immediately terminate (`ws.close(1008, 'Buffer overflow')`) and clean up upstream producer listeners when `ws.bufferedAmount` breaches a hard safety ceiling (e.g., 16MB) to protect the host process from OS OOM killing. - Components NEVER store unbounded outbound message arrays in JavaScript memory to bypass `ws.bufferedAmount`; queue bounds MUST be strictly enforced. ## Bad vs Good Implementations ### Naive high-throughput push causing native memory exhaustion vs Watermarked Drain Orchestration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling ws.send() inside high-frequency listeners without inspecting ws.bufferedAmount pushes buffers directly into native uWebSockets C-layer queues. If a consumer's TCP window fills up, native heap memory grows without triggering garbage collection until the host system runs out of memory and kills the Bun process. ```typescript import { serve } from "bun"; interface MarketTick { symbol: string; price: number; timestamp: number; } // Simulated high-throughput source (e.g. 50k ticks/sec) declare const tickFeed: { subscribe(fn: (tick: MarketTick) => void): void }; serve({ port: 8080, fetch(req, server) { server.upgrade(req); return undefined; }, websocket: { message(ws, message) {}, open(ws) { // CRITICAL VIOLATION: Subscribes unbounded producer directly to ws.send. // If client has a slow connection (e.g., 3G mobile), native C++ socket // queues expand indefinitely, triggering an uncatchable SIGKILL by the OS kernel. tickFeed.subscribe((tick) => { ws.send(JSON.stringify(tick)); }); }, }, }); ``` #### Production Standard (Correct) > **Standard**: Implements an industrial-grade backpressure barrier: ws.bufferedAmount is evaluated on every outbound frame. If the socket exceeds the 1MB high-water mark, streaming pauses. The native websocket.drain hook detects when the C++ kernel buffer flushes below 256KB and resumes the stream. If a slow consumer breaches 16MB, it is evicted immediately before heap exhaustion occurs. ```typescript import { serve, type ServerWebSocket } from "bun"; interface SocketState { isPaused: boolean; unsubscribe?: () => void; } interface MarketTick { symbol: string; price: number; timestamp: number; } declare const tickFeed: { subscribe(fn: (tick: MarketTick) => void): () => void; }; const HIGH_WATER_MARK = 1024 * 1024; // 1 MB: Pause producer const LOW_WATER_MARK = 256 * 1024; // 256 KB: Resume producer const HARD_EVICT_LIMIT = 16 * 1024 * 1024; // 16 MB: Drop toxic slow client serve<SocketState>({ port: 8080, fetch(req, server) { const ok = server.upgrade(req, { data: { isPaused: false }, }); return ok ? undefined : new Response("Upgrade failed", { status: 400 }); }, websocket: { open(ws: ServerWebSocket<SocketState>) { ws.data.unsubscribe = tickFeed.subscribe((tick: MarketTick) => { // Guardrail 1: Hard ceiling protection against zombie / adversarial consumers if (ws.bufferedAmount >= HARD_EVICT_LIMIT) { ws.close(1008, "Kernel buffer capacity exceeded"); return; } // Guardrail 2: Soft watermark throttling if (ws.bufferedAmount >= HIGH_WATER_MARK) { ws.data.isPaused = true; return; // Backpressure applied: drop or pause depending on domain semantics } if (!ws.data.isPaused) { ws.send(JSON.stringify(tick)); } }); }, drain(ws: ServerWebSocket<SocketState>) { // Guardrail 3: Low-watermark recovery via native C-level drain callback if (ws.data.isPaused && ws.bufferedAmount <= LOW_WATER_MARK) { ws.data.isPaused = false; } }, close(ws: ServerWebSocket<SocketState>) { if (ws.data.unsubscribe) { ws.data.unsubscribe(); ws.data.unsubscribe = undefined; } }, message(ws, msg) {} }, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native WebSocket Kernel Backpressure and Buffer Draining Standard

Bun 1.2 Native WebSocket Kernel Backpressure and Buffer Draining Standard defines an industrial-grade behavioral standard for backend engineering. Mandates explicit C-level memory buffer monitoring and drain-event orchestration for Bun native WebSockets. In high-throughput streaming pipelines, blind calls to ws.send() accumulate un-drained packets inside native uWebSockets C++ ring buffers outside the JavaScript runtime heap, evading V8/JSC GC thresholds and triggering silent OS OOM termination. This standard enforces watermarked backpressure control, producer pause/resume states, and bounded client disconnect thresholds. 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: Blind ws.send() invocation during high-throughput streaming without bufferedAmount tracking and drain lifecycle handling. 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	Blind ws.send() invocation during high-throughput streaming without bufferedAmount tracking and drain lifecycle handling.	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 check `ws.bufferedAmount` prior to writing payload buffers during continuous or high-throughput transmissions.

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.