Bun 1.2 Native WebSocket Streaming Backpressure and Buffer Watermark Guardrail

--- description: Bun 1.2 Native WebSocket Streaming Backpressure and Buffer Watermark Guardrail - Mandates explicit backpressure management, low-level buffer watermark checks, and drain lifecycle coordination for native Bun 1.2 WebSocket streaming. Prevents unbounded heap growth and event-loop lag caused by slow consumers during high-throughput live broadcasts. 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-streaming-backpressure-watermark" --- # Bun 1.2 Native WebSocket Streaming Backpressure and Buffer Watermark Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unchecked Fire-and-Forget ws.send() Loops Saturating Native Memory Without Drain Handling ## System Constraints You are a Principal Engineer enforcing Bun 1.2 Native WebSocket Streaming Backpressure and Buffer Watermark Guardrails. Mandate explicit backpressure tracking via ws.getBufferedAmount(), rigorous drain lifecycle callbacks, high/low watermark thresholds, and proactive slow-consumer disconnection or frame-dropping policies to preserve node stability under heavy streaming load. ## Strict Guidelines - Engineers MUST ALWAYS implement the native `drain(ws)` lifecycle handler in `Bun.serve({ websocket: { ... } })` to orchestrate stream resumption when client buffers clear. - Engineers MUST ALWAYS verify `ws.getBufferedAmount()` against a designated High-Watermark (e.g., 512 KB - 1 MB) before pushing binary or high-frequency telemetry frames. - Engineers MUST NOT execute unbounded `ws.send()` loops over fast iterables or external pub/sub channels without pausing the upstream source or applying frame-shedding strategies. - Services MUST drop non-critical frames (e.g., delta updates) or terminate chronically saturated sockets when buffered amount crosses the fatal threshold (e.g., > 2 MB). - Engineers SHOULD wrap burst transmissions in `ws.cork((ws) => { ... })` to coalesce system write calls and minimize kernel context switching during multi-frame broadcasts. ## Bad vs Good Implementations ### Naive Broadcast Stream vs. Watermark-Monitored Resilient WebSocket Stream #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Iterating over sockets and directly invoking `ws.send()` completely bypasses native backpressure. When a slow consumer lags behind high-throughput feeds, Bun queues packets in memory indefinitely without emitting warnings, causing native memory inflation, GC thrashing, and process termination. ```typescript import { serve, ServerWebSocket } from "bun"; type ClientData = { id: string }; const clients = new Set<ServerWebSocket<ClientData>>(); // ANTI-PATTERN: Blindly writing into ws without checking buffered amount // Saturated slow clients cause unbounded native heap growth and eventual OOM crash function broadcastPayload(payload: Uint8Array) { for (const ws of clients) { ws.send(payload); } } serve<ClientData>({ port: 8080, websocket: { open(ws) { clients.add(ws); }, message(ws, message) {}, close(ws) { clients.delete(ws); }, }, fetch(req, server) { if (server.upgrade(req, { data: { id: crypto.randomUUID() } })) return; return new Response("Upgrade failed", { status: 400 }); }, }); ``` #### Production Standard (Correct) > **Standard**: Monitors `ws.getBufferedAmount()` against explicit watermarks. Evicts slow clients that exceed safety thresholds, drops non-essential frames during transient spikes, hooks into Bun's native `drain` callback to reset backpressure state, and leverages `ws.cork` to aggregate network frames. ```typescript import { serve, ServerWebSocket } from "bun"; interface ClientState { id: string; isPaused: boolean; droppedFrames: number; } const HIGH_WATERMARK_BYTES = 512 * 1024; // 512 KB const MAX_BUFFER_LIMIT_BYTES = 2 * 1024 * 1024; // 2 MB fatal disconnect limit const clients = new Set<ServerWebSocket<ClientState>>(); export function broadcastSafe(payload: Uint8Array, isEphemeral = true): void { for (const ws of clients) { const buffered = ws.getBufferedAmount(); // Guardrail: Severe lag protection - evict dead or unrecoverable client if (buffered >= MAX_BUFFER_LIMIT_BYTES) { ws.close(1008, "Buffer overflow: slow consumer terminated"); clients.delete(ws); continue; } // Guardrail: High watermark backpressure strategy if (buffered >= HIGH_WATERMARK_BYTES) { if (isEphemeral) { // Shed non-critical frame to preserve socket health ws.data.droppedFrames++; continue; } // Mark paused and wait for socket drain event ws.data.isPaused = true; continue; } // Batch socket writes using native corking ws.cork((socket) => { socket.send(payload); }); } } serve<ClientState>({ port: 8080, websocket: { open(ws) { clients.add(ws); }, drain(ws) { // Low-watermark reached: Socket has flushed buffered data ws.data.isPaused = false; }, message(ws, message) { // Handle client messages }, close(ws) { clients.delete(ws); }, }, fetch(req, server) { const state: ClientState = { id: crypto.randomUUID(), isPaused: false, droppedFrames: 0 }; if (server.upgrade(req, { data: state })) return; return new Response("Upgrade failed", { status: 400 }); }, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native WebSocket Streaming Backpressure and Buffer Watermark Guardrail

Bun 1.2 Native WebSocket Streaming Backpressure and Buffer Watermark Guardrail defines an industrial-grade behavioral standard for backend engineering. Mandates explicit backpressure management, low-level buffer watermark checks, and drain lifecycle coordination for native Bun 1.2 WebSocket streaming. Prevents unbounded heap growth and event-loop lag caused by slow consumers during high-throughput live broadcasts. 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() Loops Saturating Native Memory Without Drain 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	Unchecked Fire-and-Forget ws.send() Loops Saturating Native Memory Without Drain 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 implement the native `drain(ws)` lifecycle handler in `Bun.serve({ websocket

Engineers MUST ALWAYS implement the native `drain(ws)` lifecycle handler in `Bun.serve({ websocket: { ... } })` to orchestrate stream resumption when client buffers clear.

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.