Bun 1.2 Zero-Copy WebSocket Hibernation & Buffer Pool Standard

--- description: Bun 1.2 Zero-Copy WebSocket Hibernation & Buffer Pool Standard - Enforces Bun 1.2's kernel-level WebSocket hibernation engine and zero-copy binary streaming protocols across all real-time services. Prohibits stateful V8 closure references to ServerWebSocket instances, mandating topic-based pub/sub offloading and pooled ArrayBuffer allocations to maintain microsecond tail latency under millions of concurrent idle connections. globs: src/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-websocket-hibernation-buffer-pool-standard" --- # Bun 1.2 Zero-Copy WebSocket Hibernation & Buffer Pool Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Retaining Persistent ServerWebSocket References and Unpooled Buffer Allocations ## System Constraints You are a Principal Software Architect enforcing the Bun 1.2 Zero-Copy WebSocket Hibernation & Buffer Pool Standard. Bun 1.2 achieves ultra-dense socket capacity and sub-millisecond dispatch by releasing V8 socket wrapper objects back to the kernel during periods of inactivity. You must prevent memory pinning caused by holding references to ServerWebSocket instances in application memory (e.g., custom Maps, Sets, or closure scopes). Require the use of ws.data for metadata storage, server.publish() for broadcast semantics, ws.cork() for atomic packet batching, and strict zero-copy pooled ArrayBuffer views for high-throughput binary frames. ## Strict Guidelines - Engineers MUST NOT store `ServerWebSocket` instances in module-level `Map`, `Set`, array, or long-lived closures, as this permanently defeats Bun's C++ hibernation garbage collection. - Engineers MUST attach all connection-specific state exclusively to the strongly-typed `ws.data` context passed during `server.upgrade(req, { data })`. - Engineers MUST use native topic-based pub/sub (`ws.subscribe()`, `ws.unsubscribe()`, and `server.publish()`) instead of manually iterating over active socket collections. - Services MUST batch multiple consecutive socket transmissions within `ws.cork((socket) => { ... })` to eliminate system call thrashing and enforce kernel-level zero-copy vector writes. - Code MUST transmit binary payloads using reusable pre-allocated `ArrayBufferView` instances or static `Uint8Array` pools rather than calling `Buffer.from()` or constructing ad-hoc strings inside hot frame loops. - Services MUST configure `idleTimeout`, `sendPings: true`, and `backpressureLimit` within the `Bun.serve` WebSocket definition to enforce automatic kernel descriptor teardown. ## Bad vs Good Implementations ### WebSocket Connection & State Management with Hibernation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Storing ServerWebSocket objects in a global Map pins the V8 wrappers in heap memory, entirely neutralizing Bun's hibernation engine. Broadcasting via manual iteration over this Map causes massive GC pressure and scales at O(N) JavaScript frames rather than delegating fanout to the C++ kernel layer. ```typescript import { ServerWebSocket } from 'bun'; interface ClientState { userId: string; subscribedRooms: Set<string>; } // ANTI-PATTERN: Retaining JS references prevents Bun kernel hibernation const activeClients = new Map<string, ServerWebSocket<ClientState>>(); Bun.serve<ClientState>({ port: 3000, fetch(req, server) { const userId = new URL(req.url).searchParams.get('userId') ?? 'anon'; const upgraded = server.upgrade(req, { data: { userId, subscribedRooms: new Set() }, }); return upgraded ? undefined : new Response('Upgrade failed', { status: 400 }); }, websocket: { open(ws) { // CRITICAL LEAK: Retains V8 wrapper object, pinning socket descriptors in heap activeClients.set(ws.data.userId, ws); }, message(ws, message) { // ANTI-PATTERN: Iterating over manual registry with ad-hoc Buffer allocations const payload = Buffer.from(JSON.stringify({ text: message })); for (const client of activeClients.values()) { client.send(payload); } }, close(ws) { activeClients.delete(ws.data.userId); }, }, }); ``` #### Production Standard (Correct) > **Standard**: Enforces verified production invariants and compliant error handling. ```typescript import { ServerWebSocket } from 'bun'; interface SocketContext { readonly userId: string; readonly tenantId: string; } // Zero-copy binary buffer pool for recurring frame headers const POOL_SIZE = 64 * 1024; const sharedBuffer = new ArrayBuffer(POOL_SIZE); const binaryView = new Uint8Array(sharedBuffer); const server = Bun.serve<SocketContext>({ port: 3000, fetch(req, server) { const url = new URL(req.url); const userId = url.searchParams.get('userId'); const tenantId = url.searchParams.get('tenantId'); if (!userId || !tenantId) { return new Response('Unauthorized', { status: 401 }); } const success = server.upgrade(req, { data: { userId, tenantId }, }); return success ? undefined : new Response('Upgrade failed', { status: 400 }); }, websocket: { // Enable kernel hibernation: disconnect idle sockets and wake on demand idleTimeout: 60, sendPings: true, backpressureLimit: 1024 * 1024, // 1MB backpressure threshold closeOnBackpressureLimit: true, open(ws: ServerWebSocket<SocketContext>) { // Subscribe to kernel-managed native pub/sub topics ws.subscribe(`tenant:${ws.data.tenantId}`); ws.subscribe(`user:${ws.data.userId}`); }, message(ws: ServerWebSocket<SocketContext>, message: string | Buffer) { const topic = `tenant:${ws.data.tenantId}`; // Batch syscalls using corking; offload fanout to kernel pub/sub engine ws.cork((socket) => { // Zero-copy publish: Bun broadcasts directly to kernel epoll/kqueue sets server.publish(topic, message); // Write telemetry packet using reusable binary view binaryView[0] = 0xAA; // Magic byte binaryView[1] = 0x01; // ACK opcode socket.send(binaryView.subarray(0, 2), true); }); }, drain(ws: ServerWebSocket<SocketContext>) { // Resume queued transmission after backpressure relieves if (ws.isCorked) return; }, close(ws: ServerWebSocket<SocketContext>) { ws.unsubscribe(`tenant:${ws.data.tenantId}`); ws.unsubscribe(`user:${ws.data.userId}`); }, }, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Zero-Copy WebSocket Hibernation & Buffer Pool Standard

Bun 1.2 Zero-Copy WebSocket Hibernation & Buffer Pool Standard defines an industrial-grade behavioral standard for backend engineering. Enforces Bun 1.2's kernel-level WebSocket hibernation engine and zero-copy binary streaming protocols across all real-time services. Prohibits stateful V8 closure references to ServerWebSocket instances, mandating topic-based pub/sub offloading and pooled ArrayBuffer allocations to maintain microsecond tail latency under millions of concurrent idle connections. 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 Persistent ServerWebSocket References and Unpooled Buffer Allocations 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 Persistent ServerWebSocket References and Unpooled Buffer Allocations	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 NOT store `ServerWebSocket` instances in module-level `Map`, `Set`, array, or long-lived closures, as this permanently defeats 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.