Bun 1.2 WebSocket Backpressure & Memory-Bounded Buffer Invariant

--- description: Bun 1.2 WebSocket Backpressure & Memory-Bounded Buffer Invariant - Enforces deterministic backpressure monitoring and bounded native buffer limits across all Bun native WebSocket connections. Prevents fatal process termination via SIGKILL by eliminating unmonitored C++ socket write queue expansion under asymmetric client drain rates. 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-buffer-invariant" --- # Bun 1.2 WebSocket Backpressure & Memory-Bounded Buffer Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unchecked fire-and-forget ws.send() invocations causing unmonitored native memory bloat and Linux OOM killer termination ## System Constraints You are a Principal Software Architect enforcing production-grade resilience on Bun 1.2 native WebSockets. Bun executes WebSocket operations through an optimized uWebSockets C++ engine where unbuffered writes escape the JavaScript garbage collector. If a client exhibits slow ingestion, data pushed via `ws.send()` accumulates in native memory without triggering V8/JavaScript heap thresholds, leading inevitably to uncatchable kernel SIGKILL terminations. You must mandate strict backpressure checks via `ws.getBufferedAmount()`, explicit high/low watermarks, mandatory `drain(ws)` lifecycle handlers, and deterministic connection termination or zero-allocation payload dropping for stalled peers. ## Strict Guidelines - Engineers MUST ALWAYS check `ws.getBufferedAmount()` before dispatching high-frequency or binary payloads over native Bun WebSockets. - Engineers MUST define explicit high-watermark (`HWM`) and low-watermark (`LWM`) thresholds per socket connection (e.g., 512KB HWM, 64KB LWM). - Services MUST implement the native `drain(ws)` hook in `Bun.serve({ websocket: { drain(ws) { ... } } })` to resume throttled or paused producers. - Engineers MUST NOT queue unbounded JavaScript arrays or Promises to buffer unwritten messages when backpressure is detected. - Components MUST immediately terminate slow or pathological clients with code `1008` (Policy Violation) when buffered bytes exceed the maximum tolerance threshold (e.g., 2MB). - Broadcast loops MUST inspect individual peer buffered amounts and either skip real-time volatile frames or disconnect stalled sockets rather than blocking the global event loop. ## Bad vs Good Implementations ### High-Throughput Native WebSocket Streaming with Watermark Enforcement #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly calling ws.send() without inspecting ws.getBufferedAmount() allows slow or malicious clients to force unbounded allocations in Bun's underlying native C++ socket layer. Because this memory is outside JavaScript heap limits, it bypasses GC and results in immediate OS-level SIGKILL terminations. ```typescript import { ServerWebSocket } from "bun"; interface ClientData { id: string; } export function setupBroadcast(clients: Set<ServerWebSocket<ClientData>>) { // Anti-Pattern: Unchecked fire-and-forget push in high-throughput feeds // Memory accumulates silently in uSockets native C++ buffers under slow client drain const interval = setInterval(() => { const payload = JSON.stringify({ timestamp: Date.now(), data: crypto.randomUUID() }); for (const ws of clients) { ws.send(payload); // Disregards ws.getBufferedAmount() completely } }, 5); return () => clearInterval(interval); } ``` #### Production Standard (Correct) > **Standard**: Enforces strict memory bounds using ws.getBufferedAmount(). It implements a graceful backpressure state flag, leverages the native drain() hook to recover resumed transmission, and terminates unresponsive consumers before unmanaged C++ memory can destabilize the Bun runtime. ```typescript import { ServerWebSocket, serve } from "bun"; interface ClientData { id: string; isBackpressured: boolean; } const BUFFER_HIGH_WATERMARK_BYTES = 512 * 1024; // 512 KB const BUFFER_CRITICAL_LIMIT_BYTES = 2 * 1024 * 1024; // 2 MB (Hard drop threshold) export const server = serve<ClientData>({ port: 3000, fetch(req, server) { if (server.upgrade(req, { data: { id: crypto.randomUUID(), isBackpressured: false } })) { return; } return new Response("Upgrade failed", { status: 400 }); }, websocket: { open(ws: ServerWebSocket<ClientData>) { ws.data.isBackpressured = false; }, message(ws: ServerWebSocket<ClientData>, message) { // Standard message ingestion }, drain(ws: ServerWebSocket<ClientData>) { // Low-watermark reached: native buffer has drained if (ws.data.isBackpressured && ws.getBufferedAmount() < BUFFER_HIGH_WATERMARK_BYTES / 2) { ws.data.isBackpressured = false; } }, close(ws: ServerWebSocket<ClientData>) { ws.data.isBackpressured = false; } } }); export function safeBroadcast(clients: Iterable<ServerWebSocket<ClientData>>, payload: string | Uint8Array): void { for (const ws of clients) { const buffered = ws.getBufferedAmount(); if (buffered >= BUFFER_CRITICAL_LIMIT_BYTES) { // Client is fatally stalled; sever connection to protect node stability ws.close(1008, "Buffer overflow: slow consumer terminated"); continue; } if (buffered >= BUFFER_HIGH_WATERMARK_BYTES) { // Client is backpressured; drop non-critical frame and mark state ws.data.isBackpressured = true; continue; } if (!ws.data.isBackpressured) { ws.send(payload); } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 WebSocket Backpressure & Memory-Bounded Buffer Invariant

Bun 1.2 WebSocket Backpressure & Memory-Bounded Buffer Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic backpressure monitoring and bounded native buffer limits across all Bun native WebSocket connections. Prevents fatal process termination via SIGKILL by eliminating unmonitored C++ socket write queue expansion under asymmetric client drain rates. 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() invocations causing unmonitored native memory bloat and Linux OOM killer termination 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() invocations causing unmonitored native memory bloat and Linux OOM killer termination	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.getBufferedAmount()` before dispatching high-frequency or binary payloads over native Bun WebSockets.

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.