Bun 1.2 WebSocket Backpressure High-Watermark Drain Protocol

--- description: Bun 1.2 WebSocket Backpressure High-Watermark Drain Protocol - Enforces mandatory backpressure inspection via ServerWebSocket.getBufferedAmount() and asynchronous drain checkpoint synchronization in Bun 1.2 native WebSocket servers. High-throughput fan-out broadcasts without backpressure tracking queue unbounded native payloads in the underlying C++/JavaScriptCore boundary, triggering silent OOM termination under load. Adherence guarantees deterministic flow control and bounded heap allocations across concurrent subscriber sets. globs: src/**/*.ts, server/**/*.ts, lib/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-websocket-backpressure-drain-protocol-bun-1-2-websocke-336" --- # Bun 1.2 WebSocket Backpressure High-Watermark Drain Protocol > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unchecked Fire-and-Forget ServerWebSocket.send() in Mass Broadcast Loops ## System Constraints You are a Principal Engineer enforcing the Bun 1.2 WebSocket Backpressure High-Watermark Drain Protocol. You must reject any fire-and-forget loops over ServerWebSocket instances that emit payloads without checking ws.getBufferedAmount() or handling the return code of ws.send(). Ensure all high-volume broadcast subsystems integrate a drain checkpoint mechanism via the native `drain(ws)` hook or an explicit per-client pause-and-resume buffer queue to prevent JavaScriptCore heap exhaustion. ## Strict Guidelines - Engineers MUST ALWAYS inspect the byte return value of `ws.send()` or poll `ws.getBufferedAmount()` against a strict high-watermark threshold (e.g., 64 KiB to 1 MiB) before dispatching new frames. - Engineers MUST NOT assume `ws.publish()` or iterating through active socket maps without checking backpressure is memory-safe during client network degradation. - Code MUST register a `drain(ws)` handler on the Bun `websocket` configuration object when handling buffered writes, using it to resume throttled streams. - Services MUST suspend active push streams or queue messages in an eviction-capable local ring buffer when a subscriber's `getBufferedAmount()` exceeds the configured high-watermark limit. - Components NEVER silently drop or synchronously buffer unlimited frames in userspace JavaScript heap when the underlying socket write buffer is saturated; slow or non-responsive peers MUST be flagged, shed, or disconnected. ## Bad vs Good Implementations ### Broadcast Fan-Out with Bounded Backpressure Drain Checkpoint #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Iterating over sockets and invoking ws.send() unconditionally ignores socket congestion. Bun queues unsent messages in native memory, resulting in unbounded memory expansion and catastrophic process crashes when clients experience latency or packet loss. ```typescript import type { ServerWebSocket } from "bun"; interface ClientData { id: string; } const clients = new Set<ServerWebSocket<ClientData>>(); export function broadcastMetric(payload: string): void { // ANTI-PATTERN: Blindly sending to all clients without checking buffered amount. // A slow client causes Bun's C++ buffer queue to grow without bounds, crashing the process. for (const ws of clients) { ws.send(payload); } } Bun.serve<ClientData>({ port: 3000, fetch(req, server) { server.upgrade(req, { data: { id: crypto.randomUUID() } }); return undefined; }, websocket: { open(ws) { clients.add(ws); }, close(ws) { clients.delete(ws); }, message(ws, msg) { /* no-op */ }, }, }); ``` #### Production Standard (Correct) > **Standard**: Implements the backpressure protocol by inspecting ws.getBufferedAmount() before and after transmission, queuing excess frames in bounded userspace structures, disconnecting chronically congested peers, and emptying queues via the native drain(ws) callback. ```typescript import type { ServerWebSocket } from "bun"; interface ClientData { id: string; isPaused: boolean; pendingQueue: string[]; } const HIGH_WATERMARK = 1024 * 64; // 64 KiB const MAX_PENDING_DROPS = 100; const clients = new Set<ServerWebSocket<ClientData>>(); export function broadcastMetric(payload: string): void { for (const ws of clients) { const buffered = ws.getBufferedAmount(); if (buffered >= HIGH_WATERMARK || ws.data.isPaused) { ws.data.isPaused = true; if (ws.data.pendingQueue.length >= MAX_PENDING_DROPS) { // Disconnect terminally congested or non-responsive peers ws.close(1008, "Backpressure buffer exceeded"); clients.delete(ws); continue; } ws.data.pendingQueue.push(payload); continue; } const sentBytes = ws.send(payload); if (sentBytes === -1 || ws.getBufferedAmount() >= HIGH_WATERMARK) { ws.data.isPaused = true; } } } Bun.serve<ClientData>({ port: 3000, fetch(req, server) { server.upgrade(req, { data: { id: crypto.randomUUID(), isPaused: false, pendingQueue: [] }, }); return undefined; }, websocket: { open(ws) { clients.add(ws); }, close(ws) { clients.delete(ws); }, message(ws, msg) { /* message processing */ }, drain(ws) { // INVARIANT: Bun calls drain when internal buffer clears below threshold while (ws.data.pendingQueue.length > 0) { if (ws.getBufferedAmount() >= HIGH_WATERMARK) { return; } const next = ws.data.pendingQueue.shift()!; ws.send(next); } ws.data.isPaused = false; }, }, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 WebSocket Backpressure High-Watermark Drain Protocol

Bun 1.2 WebSocket Backpressure High-Watermark Drain Protocol defines an industrial-grade behavioral standard for backend engineering. Enforces mandatory backpressure inspection via ServerWebSocket.getBufferedAmount() and asynchronous drain checkpoint synchronization in Bun 1.2 native WebSocket servers. High-throughput fan-out broadcasts without backpressure tracking queue unbounded native payloads in the underlying C++/JavaScriptCore boundary, triggering silent OOM termination under load. Adherence guarantees deterministic flow control and bounded heap allocations across concurrent subscriber sets. 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 ServerWebSocket.send() in Mass Broadcast Loops 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 ServerWebSocket.send() in Mass Broadcast Loops	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 the byte return value of `ws.send()` or poll `ws.getBufferedAmount()` against a strict high-watermark threshold (e.g., 64 KiB to 1 MiB) before dispatching new 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.