Bun 1.2 High-Density WebSocket Epoll Hibernation Architecture

--- description: Bun 1.2 High-Density WebSocket Epoll Hibernation Architecture - Enforces Bun's native C++ epoll/kqueue WebSocket hibernation runtime lifecycle to sustain millions of concurrent edge connections. Prohibits JavaScript closures, event-emitter bindings, and long-lived heap object references per socket that defeat the V8/JSC GC reclamation during idle states. Mandates strictly typed native `ws.data` payloads and pub/sub topic routing to maintain sub-kilobyte memory footprints per connection. 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-hibernation-engine" --- # Bun 1.2 High-Density WebSocket Epoll Hibernation Architecture > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Attaching State to Closures or Event Handlers Defeating Native Socket Hibernation ## System Constraints You are a Principal Systems Engineer and Low-Level Bun Runtime Specialist enforcing strict adherence to the Bun 1.2 WebSocket Hibernation Engine. You must eradicate memory leaks caused by per-socket JavaScript closures, heap allocations in idle connection states, and manual heartbeat timers. ## Strict Guidelines - Engineers MUST ALWAYS implement WebSockets using Bun's top-level server handlers (`open`, `message`, `close`, `drain`) rather than instantiating per-socket event listeners or object closures. - Engineers MUST ALWAYS store connection context exclusively in the typed `ws.data` payload initialized during the `upgrade()` handshake, keeping it strictly plain-old-data (POD) to allow C++ runtime hibernation. - Engineers MUST NOT create per-socket `setInterval` or `setTimeout` timers for heartbeats; native `idleTimeout` and `sendPings: true` in `Bun.serve` MUST be utilized instead. - Code SHOULD rely on Bun's native zero-copy pub/sub engine (`server.publish()`, `ws.subscribe()`, `ws.unsubscribe()`) rather than iterating across in-memory arrays or maps of active socket instances. - Services MUST explicitly backpressure-check the return value of `ws.send()` and handle the native `drain(ws)` event to avoid unbounded native buffer queueing during network saturation. - Components NEVER store direct references to `ServerWebSocket` instances in global Maps, Sets, or external long-lived structures, as this pins the socket in JavaScript memory and permanently inhibits kernel epoll hibernation. ## Bad vs Good Implementations ### Per-Socket Closures and Handlers vs. Native Bun Hibernation Handlers #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Creating per-socket timers and retaining `ServerWebSocket` references in a JavaScript `Map` forces the JavaScript Core (JSC) garbage collector to retain the context. This completely bypasses Bun's native C++ epoll hibernation, ballooning memory usage from ~1KB per idle connection to over 20-50KB, exhausting memory at edge scales. ```typescript import { serve } from "bun"; interface ClientState { userId: string; timer: Timer; } const activeSockets = new Map<string, any>(); serve({ port: 8080, fetch(req, server) { if (server.upgrade(req)) return; return new Response("Not a WebSocket", { status: 400 }); }, websocket: { open(ws) { // VIOLATION: Retaining socket reference in a JS Map pins it in JSC heap const id = crypto.randomUUID(); const state: ClientState = { userId: id, // VIOLATION: Per-socket JS timers inhibit C++ epoll hibernation timer: setInterval(() => { ws.send(JSON.stringify({ type: "ping" })); }, 15000) }; activeSockets.set(id, { ws, state }); }, message(ws, message) { // VIOLATION: Iterating over in-memory instances instead of native pub/sub for (const [id, client] of activeSockets) { client.ws.send(message); } }, close(ws) { for (const [id, client] of activeSockets) { if (client.ws === ws) { clearInterval(client.state.timer); activeSockets.delete(id); break; } } } } }); ``` #### Production Standard (Correct) > **Standard**: By utilizing Bun 1.2's native server handlers, typed `ws.data`, automatic `idleTimeout`, and native C++ pub/sub (`ws.subscribe()` / `server.publish()`), the connection drops down into kernel epoll/kqueue sleep. No JS closures or Maps retain the socket, reducing baseline memory to ~1KB per connection. ```typescript import { serve, type ServerWebSocket } from "bun"; interface SocketData { sessionId: string; userId: string; channels: string[]; } const server = serve<SocketData>({ port: 8080, // Native C++ hibernation engine manages idle timeouts & keepalive pings idleTimeout: 60, fetch(req, server) { const url = new URL(req.url); const userId = url.searchParams.get("userId") ?? "anonymous"; const success = server.upgrade(req, { data: { sessionId: crypto.randomUUID(), userId, channels: ["global"] } }); return success ? undefined : new Response("WebSocket upgrade failed", { status: 400 }); }, websocket: { // Backpressure threshold in bytes backpressureLimit: 1024 * 1024, closeOnBackpressureLimit: true, open(ws: ServerWebSocket<SocketData>) { // Subscribe using Bun's native zero-allocation C++ topic engine ws.subscribe("global"); ws.subscribe(`user:${ws.data.userId}`); }, message(ws: ServerWebSocket<SocketData>, message: string | Buffer) { // Publish directly into native broadcast bus without instantiating JS targets server.publish("global", message); }, drain(ws: ServerWebSocket<SocketData>) { // Handle kernel buffer drain when unblocked console.info(`Socket buffer drained for session ${ws.data.sessionId}`); }, close(ws: ServerWebSocket<SocketData>, code: number, reason: string) { ws.unsubscribe("global"); ws.unsubscribe(`user:${ws.data.userId}`); } } }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 High-Density WebSocket Epoll Hibernation Architecture

Bun 1.2 High-Density WebSocket Epoll Hibernation Architecture defines an industrial-grade behavioral standard for backend engineering. Enforces Bun's native C++ epoll/kqueue WebSocket hibernation runtime lifecycle to sustain millions of concurrent edge connections. Prohibits JavaScript closures, event-emitter bindings, and long-lived heap object references per socket that defeat the V8/JSC GC reclamation during idle states. Mandates strictly typed native `ws.data` payloads and pub/sub topic routing to maintain sub-kilobyte memory footprints per connection. 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: Attaching State to Closures or Event Handlers Defeating Native Socket Hibernation 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	Attaching State to Closures or Event Handlers Defeating Native Socket Hibernation	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 WebSockets using Bun's top-level server handlers (`open`, `message`, `close`, `drain`) rather than instantiating per-socket event listeners or object closures.

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.