Bun 1.2 Native Socket Zero-Copy ArrayBuffer Drain & Backpressure Invariant

--- description: Bun 1.2 Native Socket Zero-Copy ArrayBuffer Drain & Backpressure Invariant - Enforces strict backpressure synchronization and bounded buffer thresholds on native Bun 1.2 WebSocket broadcast loops. Prevents catastrophic off-heap C++ buffer allocation and process-level RSS memory exhaustion caused by slow socket consumers during high-volume binary streaming. globs: src/**/*.{ts,tsx}, server/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-native-websocket-backpressure-drain-invariant" --- # Bun 1.2 Native Socket Zero-Copy ArrayBuffer Drain & Backpressure Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unchecked Fire-and-Forget ws.send() Calls Triggering Unbounded Off-Heap C++ Queue Bloat ## System Constraints You are a Principal Systems Engineer enforcing Bun 1.2 Native Socket Zero-Copy ArrayBuffer Drain Invariants. Under high-throughput broadcast flows, Bun queues native socket frames in an off-heap C++ ring buffer that is invisible to JavaScript garbage collection. You must forbid unmonitored ws.send() calls and enforce strict backpressure handling via getBufferedAmount(), the native drain(ws) callback, and bounded client disconnect thresholds. ## Strict Guidelines - Engineers MUST ALWAYS implement the native `drain(ws)` socket handler on `Bun.serve` when streaming binary buffers across WebSockets. - Engineers MUST NOT execute fire-and-forget `ws.send(buffer)` operations across socket sets without validating `ws.getBufferedAmount()` against a fixed high-water mark. - Services MUST immediately terminate or shed slow consumers (`ws.close(1008, 'Buffer Overflow')`) when `ws.getBufferedAmount()` crosses the catastrophic threshold (e.g., 2MB). - Engineers MUST NEVER mutate, re-slice, or detach an underlying `ArrayBuffer` passed to `ws.send()` while zero-copy transfers are queued in the native layer. - Code SHOULD leverage immutable `Uint8Array` references for zero-copy binary dispatch and pause publisher streams when socket queues saturate. - Publishers MUST defer re-enqueuing data to a backpressured socket until Bun's native `drain` hook verifies that the kernel transmit window has cleared. ## Bad vs Good Implementations ### Unbounded WebSocket Broadcast vs. Native Drain Backpressure Synchronization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling ws.send() blindly ignores slow consumers. Bun queues unsent frames in off-heap C++ buffers outside JSC garbage collection. In multi-gigabit workloads, these unmonitored queues consume gigabytes of RSS memory within seconds, triggering the OS OOM killer. ```typescript import { serve, ServerWebSocket } from 'bun'; interface ClientData { id: string; } const clients = new Set<ServerWebSocket<ClientData>>(); // ANTI-PATTERN: Blindly sending multi-megabyte ArrayBuffers to all connected clients. // If a single client throttles TCP ACK packets, Bun's internal uSockets layer // queues data off-heap, causing silent Resident Set Size (RSS) explosion and OOM panic. export function broadcastFrame(frame: Uint8Array) { for (const ws of clients) { ws.send(frame); } } serve<ClientData>({ port: 8080, websocket: { open(ws) { clients.add(ws); }, close(ws) { clients.delete(ws); }, message(ws, message) { // No drain handler, no backpressure validation }, }, fetch(req, server) { server.upgrade(req); return new Response('Upgraded', { status: 101 }); }, }); ``` #### Production Standard (Correct) > **Standard**: Implements the invariant: tracks ws.getBufferedAmount(), enforces an upper threshold (512KB) before deferring packets to an application queue, terminates rogue slow consumers exceeding 2MB, and utilizes Bun's native drain(ws) callback to flush queued ArrayBuffers only when the kernel socket buffer has emptied. ```typescript import { serve, ServerWebSocket } from 'bun'; interface SocketState { id: string; isBackpressured: boolean; pendingQueue: Uint8Array[]; } const HIGH_WATER_MARK = 1024 * 512; // 512 KB max off-heap queue const HARD_DROP_LIMIT = 1024 * 1024 * 2; // 2 MB drop threshold const clients = new Set<ServerWebSocket<SocketState>>(); export function broadcastFrame(frame: Uint8Array) { // Pass immutable zero-copy view const immutableFrame = new Uint8Array(frame.buffer, frame.byteOffset, frame.byteLength); for (const ws of clients) { const buffered = ws.getBufferedAmount(); if (buffered >= HARD_DROP_LIMIT) { // Client is fatally lagging; terminate immediately to preserve server RSS stability ws.close(1008, 'Backpressure threshold exceeded'); clients.delete(ws); continue; } if (buffered >= HIGH_WATER_MARK || ws.data.isBackpressured) { // Apply backpressure: queue application frame or shed non-critical payload ws.data.isBackpressured = true; ws.data.pendingQueue.push(immutableFrame); continue; } // Send returns 0 or byte count transferred; verify backpressure after dispatch ws.send(immutableFrame); if (ws.getBufferedAmount() > HIGH_WATER_MARK) { ws.data.isBackpressured = true; } } } serve<SocketState>({ port: 8080, websocket: { open(ws) { ws.data = { id: crypto.randomUUID(), isBackpressured: false, pendingQueue: [] }; clients.add(ws); }, close(ws) { clients.delete(ws); }, drain(ws) { // INVARIANT: Native drain handler signals kernel buffer availability const state = ws.data; while (state.pendingQueue.length > 0) { if (ws.getBufferedAmount() >= HIGH_WATER_MARK) { return; // Remain in backpressured state } const nextFrame = state.pendingQueue.shift(); if (nextFrame) { ws.send(nextFrame); } } state.isBackpressured = false; }, message(ws, message) { // Handle client messages }, }, fetch(req, server) { server.upgrade(req, { data: { id: '', isBackpressured: false, pendingQueue: [] }, }); return new Response('Upgraded', { status: 101 }); }, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native Socket Zero-Copy ArrayBuffer Drain & Backpressure Invariant

Bun 1.2 Native Socket Zero-Copy ArrayBuffer Drain & Backpressure Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces strict backpressure synchronization and bounded buffer thresholds on native Bun 1.2 WebSocket broadcast loops. Prevents catastrophic off-heap C++ buffer allocation and process-level RSS memory exhaustion caused by slow socket consumers during high-volume binary streaming. 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() Calls Triggering Unbounded Off-Heap C++ Queue Bloat 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() Calls Triggering Unbounded Off-Heap C++ Queue Bloat	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)` socket handler on `Bun.serve` when streaming binary buffers across 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.