Bun 1.2 Native WebSocket Backpressure & Zero-Copy Buffer Recycling Protocol

--- description: Bun 1.2 Native WebSocket Backpressure & Zero-Copy Buffer Recycling Protocol - Enforces strict TCP-level backpressure management and zero-copy binary buffer pooling for Bun 1.2 native WebSocket servers. Prohibits unchecked calls to `ws.send()` by evaluating `ws.getBufferedAmount()` against high-water marks and leveraging native `drain()` handlers with `ws.cork()` payload batching to eliminate kernel buffer bloat and Out-Of-Memory (OOM) crashes under high fan-out load. globs: src/**/*.ts, server/**/*.ts, gateway/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-websocket-cluster-backpressure-protocol" --- # Bun 1.2 Native WebSocket Backpressure & Zero-Copy Buffer Recycling Protocol > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded `ws.send()` dispatching without `getBufferedAmount()` checks and missing native `drain()` lifecycle control. ## System Constraints You are a Principal Systems Engineer enforcing Bun 1.2 Native WebSocket Cluster-Aware Backpressure Protocol. Mandate invariants regarding kernel-level TCP backpressure thresholds, zero-copy buffer pooling, corked socket writes, and strict drain event handling. Enforce that unchecked socket writes without buffered amount inspection are flagged as critical reliability hazards. ## Strict Guidelines - Engineers MUST ALWAYS check `ws.getBufferedAmount()` against a deterministic High-Water Mark (HWM) before dispatching outbound frames. - Engineers MUST pause upstream consumption or queue outbound payloads in a bounded circular buffer when `ws.getBufferedAmount() > BACKPRESSURE_HIGH_WATERMARK`. - Engineers MUST implement the native `drain(ws)` lifecycle callback in the `Bun.serve({ websocket: { ... } })` configuration to resume dispatch when buffered bytes fall below the Low-Water Mark (LWM). - Engineers MUST use `ws.cork((ws) => { ... })` when dispatching multiple small payloads or broadcasts to coalesce writes into single TCP segments at the native layer. - Engineers MUST NOT allocate ephemeral `Buffer` or `Uint8Array` instances per message; use pre-allocated static slabs or recycled pooled views via zero-copy slicing (`subarray`). - Services MUST terminate or evict delinquent slow consumers exceeding hard backpressure ceilings (`BACKPRESSURE_ABORT_THRESHOLD`) with status code 1008 (Policy Violation) to avoid cluster-wide head-of-line blocking. ## Bad vs Good Implementations ### Backpressure Handling and Corking in Bun.serve WebSocket Gateway #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly calling `ws.send()` in a loop without inspecting `ws.getBufferedAmount()` allows slow clients to accumulate millions of un-drained bytes in native memory, evading V8/JavaScript GC limits and triggering kernel-level OOM kills. ```typescript import { ServerWebSocket } from 'bun'; // ANTI-PATTERN: Fire-and-forget broadcasts cause unbounded buffer bloat. export function broadcastEvent(clients: Set<ServerWebSocket<unknown>>, payload: Uint8Array) { for (const ws of clients) { // Allocates new buffers per send and ignores native socket backpressure state const cloned = Buffer.from(payload); ws.send(cloned); // If client is slow, ws buffered memory grows unbounded until process OOMs } } ``` #### Production Standard (Correct) > **Standard**: Calculates socket saturation using `ws.getBufferedAmount()`, halts dispatching when above the 64 KiB HWM, queues payloads up to a safe bounded capacity, evicts pathological clients exceeding 1 MiB, and resumes queue draining inside Bun's native `drain` hook with `ws.cork()` optimization. ```typescript import { ServerWebSocket } from 'bun'; const HWM_BYTES = 64 * 1024; // 64 KiB High-Water Mark const ABORT_BYTES = 1024 * 1024; // 1 MiB Hard Limit interface SocketData { id: string; paused: boolean; queue: Uint8Array[]; } export const websocketHandler = { message(ws: ServerWebSocket<SocketData>, message: string | Buffer) { // Inbound processing with zero-copy binary dispatch }, drain(ws: ServerWebSocket<SocketData>) { // Native kernel buffer drained below watermark; flush bounded queue while (ws.data.queue.length > 0) { if (ws.getBufferedAmount() >= HWM_BYTES) { return; } const nextPayload = ws.data.queue.shift()!; ws.send(nextPayload); } ws.data.paused = false; } }; export function broadcastSafe(clients: Iterable<ServerWebSocket<SocketData>>, payload: Uint8Array) { for (const ws of clients) { const buffered = ws.getBufferedAmount(); if (buffered >= ABORT_BYTES) { // Terminate toxic slow consumer ws.close(1008, 'Slow consumer threshold exceeded'); continue; } if (buffered >= HWM_BYTES || ws.data.paused) { ws.data.paused = true; if (ws.data.queue.length < 500) { ws.data.queue.push(payload); } continue; } // Coalesce binary write at the native C++ layer ws.cork(() => { ws.send(payload); }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native WebSocket Backpressure & Zero-Copy Buffer Recycling Protocol

Bun 1.2 Native WebSocket Backpressure & Zero-Copy Buffer Recycling Protocol defines an industrial-grade behavioral standard for backend engineering. Enforces strict TCP-level backpressure management and zero-copy binary buffer pooling for Bun 1.2 native WebSocket servers. Prohibits unchecked calls to `ws.send()` by evaluating `ws.getBufferedAmount()` against high-water marks and leveraging native `drain()` handlers with `ws.cork()` payload batching to eliminate kernel buffer bloat and Out-Of-Memory (OOM) crashes under high fan-out load. 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 `ws.send()` dispatching without `getBufferedAmount()` checks and missing native `drain()` lifecycle control. 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 `ws.send()` dispatching without `getBufferedAmount()` checks and missing native `drain()` lifecycle control.	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()` against a deterministic High-Water Mark (HWM) before dispatching outbound 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.