Bun 1.2 Native WebSocket Low-Watermark Backpressure Invariant

--- description: Bun 1.2 Native WebSocket Low-Watermark Backpressure Invariant - Enforces strict producer suspension and deterministic TCP drain coordination for Bun 1.2 native WebSockets using low/high watermark thresholds on `ws.bufferedAmount`. Prevents unbounded V8/JSC heap exhaustion caused by slow socket consumers during high-throughput binary and text streaming. Mandates cooperative yielding via the native `drain(ws)` socket lifecycle hook rather than fire-and-forget message dispatching. 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-low-watermark-backpressure-invariant" --- # Bun 1.2 Native WebSocket Low-Watermark Backpressure Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Fire-and-Forget `ws.send()` Dispatching Ignoring Native `bufferedAmount` Accumulation ## System Constraints You are a Principal Engineer enforcing the Bun 1.2 Native WebSocket Low-Watermark Backpressure Invariant. Under Bun's native uSockets layer, `ws.send()` queues packets directly into userspace/kernel buffers. Disregarding `ws.bufferedAmount` and omitting `drain(ws)` lifecycle handlers creates unbounded memory leaks and event loop starvation when downstream bandwidth degrades. You must strictly mandate producer suspension when `bufferedAmount` breaches the high watermark (e.g., 512KB) and resume only when the low watermark (e.g., 64KB) is reached via `drain`. ## Strict Guidelines - Engineers MUST ALWAYS implement the `drain(ws)` hook on Bun's WebSocket handler when streaming high-frequency data or large payloads. - Engineers MUST ALWAYS verify `ws.bufferedAmount` before invoking `ws.send()` in streaming loops or asynchronous generators. - Engineers MUST pause producer ingestion and park the dispatch routine when `ws.bufferedAmount` exceeds the high-watermark threshold (default: 512 KiB). - Engineers MUST resume paused producers only when `ws.bufferedAmount` falls below the low-watermark threshold (default: 64 KiB), signaled by the native `drain(ws)` callback. - Engineers MUST NOT create unbounded in-memory promise queues or async dispatch loops that invoke `ws.send()` without awaiting drain synchronization. - Services MUST abort or forcefully close client connections (`ws.close(1008, 'Slow Consumer')`) if backpressure suspension times out or exceeds hard buffer ceiling limits (e.g., 16 MiB). ## Bad vs Good Implementations ### High-Throughput WebSocket Producer with Watermark Backpressure and Drain Coordination #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Invoking ws.send() unconditionally inside an async iterator ignores client link degradation. Unsent bytes continuously accumulate in Bun's uSockets buffer, leading to process OOM crashes under high-load streaming. ```typescript import type { ServerWebSocket } from "bun"; // ANTI-PATTERN: Fire-and-forget push ignoring native socket buffer pressure. // If the client's network link is saturated, bufferedAmount grows unbounded, // exhausting the Bun runtime memory and crashing the process. export async function streamMetricsToClient( ws: ServerWebSocket<unknown>, dataSource: AsyncIterable<Uint8Array> ): Promise<void> { for await (const chunk of dataSource) { // ws.send returns the number of bytes sent or queued, but does not wait for TCP ACK ws.send(chunk); } } ``` #### Production Standard (Correct) > **Standard**: Implements an explicit producer-consumer backpressure contract using `HIGH_WATERMARK` and `LOW_WATERMARK`. Suspends the `for-await` producer loop via an awaitable promise, which is deterministically resolved inside Bun's native `drain(ws)` handler only after the socket buffer recedes below `LOW_WATERMARK`. ```typescript import type { ServerWebSocket, WebSocketHandler } from "bun"; interface SocketData { drainResolver: (() => void) | null; isPaused: boolean; } const HIGH_WATERMARK = 512 * 1024; // 512 KiB: Pause upstream producer const LOW_WATERMARK = 64 * 1024; // 64 KiB: Resume upstream producer export const wsHandler: WebSocketHandler<SocketData> = { open(ws) { ws.data = { drainResolver: null, isPaused: false }; }, message(ws, message) { // Normal message handling... }, drain(ws) { // Fired by Bun when the native kernel buffer drains if (ws.bufferedAmount <= LOW_WATERMARK && ws.data.drainResolver) { const resolve = ws.data.drainResolver; ws.data.drainResolver = null; ws.data.isPaused = false; resolve(); } }, close(ws) { if (ws.data.drainResolver) { ws.data.drainResolver(); ws.data.drainResolver = null; } } }; export async function streamMetricsToClient( ws: ServerWebSocket<SocketData>, dataSource: AsyncIterable<Uint8Array> ): Promise<void> { for await (const chunk of dataSource) { if (ws.readyState !== 1) break; // Backpressure check: Suspend producer if high watermark is reached if (ws.bufferedAmount >= HIGH_WATERMARK) { ws.data.isPaused = true; await new Promise<void>((resolve) => { ws.data.drainResolver = resolve; }); } if (ws.readyState !== 1) break; ws.send(chunk); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native WebSocket Low-Watermark Backpressure Invariant

Bun 1.2 Native WebSocket Low-Watermark Backpressure Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces strict producer suspension and deterministic TCP drain coordination for Bun 1.2 native WebSockets using low/high watermark thresholds on `ws.bufferedAmount`. Prevents unbounded V8/JSC heap exhaustion caused by slow socket consumers during high-throughput binary and text streaming. Mandates cooperative yielding via the native `drain(ws)` socket lifecycle hook rather than fire-and-forget message dispatching. 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: Unbounded Fire-and-Forget `ws.send()` Dispatching Ignoring Native `bufferedAmount` Accumulation 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	Unbounded Fire-and-Forget `ws.send()` Dispatching Ignoring Native `bufferedAmount` Accumulation	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 implement the `drain(ws)` hook on Bun's WebSocket handler when streaming high-frequency data or large payloads.

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.