Bun 1.2 Native WebSocket Hibernation and Kernel-Level Backpressure Management

--- description: Bun 1.2 Native WebSocket Hibernation and Kernel-Level Backpressure Management - Enforces memory-safe WebSocket handling in Bun 1.2+ using native socket hibernation and kernel-level backpressure control. Sockets must never be retained in JavaScript heap structures, and egress message streaming must respect socket buffer thresholds and the native drain lifecycle to sustain millions of concurrent connections with near-zero idle resident memory footprint. globs: src/**/*.ts, server/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-websocket-hibernation-backpressure-control" --- # Bun 1.2 Native WebSocket Hibernation and Kernel-Level Backpressure Management > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Retaining ServerWebSocket references in heap collections and dispatching egress messages without drain backpressure handling. ## System Constraints You are a Principal Engineer enforcing Bun 1.2 Native WebSocket Hibernation Backpressure Control. Mandate invariants that prevent JavaScript heap exhaustion and unhandled backpressure. Ensure that WebSocket state is retained strictly in C++ kernel-level hibernation by avoiding JS-level socket references, using native server.publish() instead of manual iteration loops, and handling socket buffer saturation via drain() and send() status codes. ## Strict Guidelines - Engineers MUST NEVER retain `ServerWebSocket` instances in global arrays, Sets, Maps, or closure scopes, as persistent references break Bun's C++ hibernation garbage collection. - Engineers MUST store connection-specific metadata strictly within the typed `ws.data` context passed during the initial HTTP upgrade. - Engineers MUST inspect the return value of `ws.send()`, which indicates the number of bytes queued or sent, to detect backpressure saturation. - Services MUST implement the `drain(ws)` lifecycle callback to resume suspended egress data streams when socket output buffers drop below kernel high-water marks. - Engineers MUST use `server.publish(topic, message)` for broadcasting rather than iterating over connection collections in userland JavaScript. - Code SHOULD wrap consecutive synchronous message dispatches in `ws.cork(() => { ... })` to coalesce writes into a single kernel syscall and optimize MTU utilization. ## Bad vs Good Implementations ### WebSocket Connection Tracking and Egress Backpressure #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Storing ServerWebSocket objects in a JavaScript `Set` prevents Bun's C++ engine from garbage-collecting dormant wrapper objects, defeating native hibernation and exhausting memory at scale. Additionally, iterating over sockets in userland and ignoring `send()` return values leads to unbounded outbound buffer bloat when consumers experience network congestion. ```typescript import { type ServerWebSocket } from "bun"; interface ClientData { id: string; } // ANTI-PATTERN: Retaining WebSocket references prevents Bun socket hibernation const activeClients = new Set<ServerWebSocket<ClientData>>(); export const server = Bun.serve<ClientData>({ port: 3000, fetch(req, server) { const id = crypto.randomUUID(); server.upgrade(req, { data: { id } }); return new Response("Upgrade failed", { status: 400 }); }, websocket: { open(ws) { activeClients.add(ws); // Retaining reference causes V8/JSC heap bloat }, message(ws, message) { // ANTI-PATTERN: Manual loop over JS collection; ignores send() return code & backpressure for (const client of activeClients) { client.send(`Echo to ${client.data.id}: ${message}`); } }, close(ws) { activeClients.delete(ws); } } }); ``` #### Production Standard (Correct) > **Standard**: Zero `ServerWebSocket` references are stored in JavaScript heap collections, allowing Bun's native hibernation state machine to sleep idle connections with near-zero memory footprint. Egress broadcasting is offloaded to C++ via `server.publish()`, and direct socket writes rigorously check `ws.send()` results with the `drain(ws)` lifecycle callback resolving backpressure gracefully. ```typescript import { type ServerWebSocket } from "bun"; interface SocketData { sessionId: string; egressQueue: Uint8Array[]; isBackpressured: boolean; } const BROADCAST_TOPIC = "global-chat"; export const server = Bun.serve<SocketData>({ port: 3000, fetch(req, server) { const sessionId = crypto.randomUUID(); const upgraded = server.upgrade(req, { data: { sessionId, egressQueue: [], isBackpressured: false, }, }); if (upgraded) return undefined; return new Response("WebSocket upgrade failed", { status: 400 }); }, websocket: { open(ws) { // Use native C++ pub/sub registration; no JS references retained ws.subscribe(BROADCAST_TOPIC); }, message(ws, message) { // Native kernel-level broadcast directly from C++ state machine server.publish(BROADCAST_TOPIC, `[${ws.data.sessionId}]: ${message}`); }, drain(ws) { // Called when kernel buffer empties below high-water mark ws.data.isBackpressured = false; while (ws.data.egressQueue.length > 0) { const chunk = ws.data.egressQueue.shift()!; const sendResult = ws.send(chunk); if (sendResult <= 0) { // Socket buffer saturated again; re-queue remaining chunk and yield ws.data.egressQueue.unshift(chunk); ws.data.isBackpressured = true; break; } } }, close(ws) { ws.unsubscribe(BROADCAST_TOPIC); ws.data.egressQueue.length = 0; } } }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native WebSocket Hibernation and Kernel-Level Backpressure Management

Bun 1.2 Native WebSocket Hibernation and Kernel-Level Backpressure Management defines an industrial-grade behavioral standard for backend engineering. Enforces memory-safe WebSocket handling in Bun 1.2+ using native socket hibernation and kernel-level backpressure control. Sockets must never be retained in JavaScript heap structures, and egress message streaming must respect socket buffer thresholds and the native drain lifecycle to sustain millions of concurrent connections with near-zero idle resident memory footprint. 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: Retaining ServerWebSocket references in heap collections and dispatching egress messages without drain backpressure 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	Retaining ServerWebSocket references in heap collections and dispatching egress messages without drain backpressure 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 NEVER retain `ServerWebSocket` instances in global arrays, Sets, Maps, or closure scopes, as persistent references break Bun's C++ hibernation garbage collection.

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.