Bun 1.2 Native WebSocket Backpressure Queue Bounding Guardrail

--- description: Bun 1.2 Native WebSocket Backpressure Queue Bounding Guardrail - Protects high-throughput Bun edge event gateways from out-of-memory (OOM) kills caused by unbounded native C++ socket buffering. Enforces strict inspection of ws.getBufferedAmount(), mandatory drain callback wiring, and deterministic client eviction when slow consumer buffers exceed memory limits. 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-backpressure-queue-bounding" --- # Bun 1.2 Native WebSocket Backpressure Queue Bounding Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded WebSocket Publishing Without Buffer Inspection or Drain Handler Synchronization ## System Constraints You are a Principal Backend Architect enforcing Bun 1.2 Native WebSocket backpressure constraints. You must prevent memory exhaustion from slow consumers and unbounded zero-copy socket dispatching by enforcing strict drain thresholds and buffer checks. ## Strict Guidelines - Engineers MUST ALWAYS check `ws.getBufferedAmount()` before calling `ws.send()` on high-frequency unicast connections. - Engineers MUST NOT execute fire-and-forget `ws.send()` loops without observing backpressure saturation bounds. - Services MUST implement the `drain(ws)` lifecycle handler on `Bun.serve({ websocket: { ... } })` whenever messages are buffered or throttled. - Code SHOULD enforce a maximum buffered amount threshold (e.g., 512KB to 1MB per socket) and terminate slow consumers using code `1008` (Policy Violation) if the buffer limit is exceeded. - Publish/Subscribe fan-out via `server.publish(topic, data)` SHOULD monitor overall heap growth and avoid unbounded broadcasting to unverified subscriber states. - Components NEVER store unbounded in-memory retry queues per socket; backpressure shedding must either pause upstream ingestion or drop transient packets according to SLA. ## Bad vs Good Implementations ### Naive Unbounded WebSocket Dispatch vs. Bounded Backpressure with Drain Lifecycle #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling `ws.send()` repeatedly without monitoring buffer size or implementing `drain()` allows slow network consumers to accumulate unbounded native memory. Because these allocations live in Bun's native uWebSockets layer rather than the JavaScript heap, standard GC cannot reclaim them, causing deterministic SIGKILL terminations under load. ```typescript import { serve } from 'bun'; // ANTI-PATTERN: Fire-and-forget broadcasting without checking socket buffer // Under high packet rates and slow consumer network links, native uWebSockets buffers // grow without triggering JSC garbage collection, triggering an immediate OS OOM kill. serve({ port: 8080, fetch(req, server) { if (server.upgrade(req)) return; return new Response('Upgrade failed', { status: 400 }); }, websocket: { message(ws, message) { // Blindly echoing or fanning out heavy data const largePayload = new Uint8Array(64 * 1024); for (let i = 0; i < 1000; i++) { ws.send(largePayload); // Unbounded native buffer allocation! } }, }, }); ``` #### Production Standard (Correct) > **Standard**: The production implementation guards every dispatch with `ws.getBufferedAmount()`. If a consumer falls behind and exceeds `MAX_BUFFERED_BYTES`, it is gracefully terminated with WebSocket code 1008 (Policy Violation) before native memory exhaustion occurs. The `drain` hook guarantees safe resumption when the client drains pending network packets below low-watermark thresholds. ```typescript import { serve, type ServerWebSocket } from 'bun'; interface SocketData { id: string; isPaused: boolean; } const MAX_BUFFERED_BYTES = 512 * 1024; // 512 KB per connection limit export const server = serve<SocketData>({ port: 8080, fetch(req, server) { if (server.upgrade(req, { data: { id: crypto.randomUUID(), isPaused: false } })) { return; } return new Response('Upgrade failed', { status: 400 }); }, websocket: { open(ws: ServerWebSocket<SocketData>) { ws.data.isPaused = false; }, message(ws: ServerWebSocket<SocketData>, message) { const buffered = ws.getBufferedAmount(); // Hard backpressure protection: evict toxic slow consumer if (buffered > MAX_BUFFERED_BYTES) { console.warn(`[Slow Consumer] Terminating socket ${ws.data.id}: buffer exceeded ${MAX_BUFFERED_BYTES} bytes`); ws.close(1008, 'Buffer overflow: slow consumer evicted'); return; } const payload = Buffer.from('telemetry-payload'); // Soft backpressure handling: check before send if (buffered + payload.byteLength > MAX_BUFFERED_BYTES) { ws.data.isPaused = true; // Back off or drop non-critical transient frame return; } ws.send(payload); }, drain(ws: ServerWebSocket<SocketData>) { // Native backpressure cleared: resume ingestion or unpause worker stream if (ws.data.isPaused && ws.getBufferedAmount() < MAX_BUFFERED_BYTES / 2) { ws.data.isPaused = false; } }, close(ws: ServerWebSocket<SocketData>) { ws.data.isPaused = false; } }, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native WebSocket Backpressure Queue Bounding Guardrail

Bun 1.2 Native WebSocket Backpressure Queue Bounding Guardrail defines an industrial-grade behavioral standard for backend engineering. Protects high-throughput Bun edge event gateways from out-of-memory (OOM) kills caused by unbounded native C++ socket buffering. Enforces strict inspection of ws.getBufferedAmount(), mandatory drain callback wiring, and deterministic client eviction when slow consumer buffers exceed memory limits. 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 WebSocket Publishing Without Buffer Inspection or Drain Handler Synchronization 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 WebSocket Publishing Without Buffer Inspection or Drain Handler Synchronization	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()` before calling `ws.send()` on high-frequency unicast connections.

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.