Bun 1.2 Deterministic Worker Ring WebSocket Multiplexing Standard

--- description: Bun 1.2 Deterministic Worker Ring WebSocket Multiplexing Standard - In multi-worker Bun 1.2 runtimes, arbitrary socket handoffs and cross-worker native WebSocket upgrades cause file-descriptor epoll desynchronization, TLS session corruption, and unrecoverable renegotiation storms. WebSocket upgrades MUST be strictly pinned to deterministic CPU-affinity worker rings using consistent hashing prior to handshake initiation, guaranteeing that each native file descriptor remains bound to a single worker event loop throughout its lifecycle. globs: src/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-multiworker-websocket-fd-multiplexing-guardrail" --- # Bun 1.2 Deterministic Worker Ring WebSocket Multiplexing Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Cross-Worker IPC Socket Handover and Post-Accept Desynchronized Upgrades ## System Constraints You are a Principal Software Architect enforcing production invariants for Bun 1.2 multi-threaded and multi-worker WebSocket architectures. Bun executes an optimized Zig/C++ event loop over native epoll/kqueue. You must reject any architecture attempting to transfer raw TCP file descriptors, open requests, or active TLS states across Bun worker threads post-handshake. Enforce strict single-owner socket lifecycles, SO_REUSEPORT CPU-affinity partitioning, and pre-upgrade deterministic worker ring routing. ## Strict Guidelines - Engineers MUST ALWAYS anchor each client connection to a deterministic worker thread using consistent hashing (e.g., client IP or session key) before initiating the native WebSocket upgrade via server.upgrade(). - Engineers MUST NOT transfer native Request, Response, or raw Socket file descriptors across Bun Worker boundaries via postMessage() once TLS negotiation has begun. - Services MUST enable reusePort: true on Bun.serve() listeners across partitioned worker rings to let the kernel distribute incoming SYNs deterministically rather than relying on application-space IPC proxying. - Services MUST maintain native WebSocket lifecycle events (open, message, close, drain) strictly within the originating worker thread that accepted the upgrade. - Components NEVER call server.upgrade() on a detached or deserialized request object passed through worker messaging channels. ## Bad vs Good Implementations ### Anti-Pattern: Inter-Worker Socket Delegation Leading to Epoll Race & TLS Storms #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing Request instances across worker boundaries via postMessage attempts to transfer native Zig/C++ socket handles that are already bound to the parent's epoll instance. This leads to double-close panics, corrupted TLS states, and catastrophic worker crash loops. ```typescript import { serve } from "bun"; // Primary orchestrator receives request and attempts IPC transfer to a worker const workerPool = [new Worker("./worker-1.ts"), new Worker("./worker-2.ts")]; serve({ port: 8080, async fetch(req, server) { const url = new URL(req.url); if (url.pathname === "/ws") { // CRITICAL FLAW: Passing raw request/socket across Bun worker boundary. // Desynchronizes Bun native Zig epoll handles and triggers TLS renegotiation failure. const workerIndex = Math.floor(Math.random() * workerPool.length); workerPool[workerIndex].postMessage({ type: "DELEGATE_UPGRADE", req }); return new Response("Upgrading in worker...", { status: 101 }); } return new Response("HTTP OK"); }, }); ``` #### Production Standard (Correct) > **Standard**: Each worker thread runs an independent Bun.serve instance using native reusePort. The operating system kernel dispatches connections directly to the worker's native epoll loop, guaranteeing zero cross-thread FD passing, intact TLS contexts, and optimal backpressure handling. ```typescript import { serve } from "bun"; // worker.ts: Each worker runs an isolated Bun.serve instance with SO_REUSEPORT. // Sockets are accepted, upgraded, and maintained strictly within their local event loop. interface WebSocketData { id: string; workerId: number; } const WORKER_ID = Number(process.env.WORKER_ID ?? 0); export const server = serve<WebSocketData>({ port: 8080, reusePort: true, // Kernel-level CPU affinity distribution; no inter-worker IPC for FDs websocket: { open(ws) { ws.data = { id: crypto.randomUUID(), workerId: WORKER_ID }; }, message(ws, message) { // Purely local processing on pinned worker thread ws.send(`Echo from worker ${ws.data.workerId}: ${message}`); }, close(ws, code, reason) { // Clean local socket lifecycle termination }, drain(ws) { // Local backpressure handling } }, fetch(req, server) { if (req.headers.get("upgrade")?.toLowerCase() === "websocket") { const upgraded = server.upgrade(req, { data: { id: "", workerId: WORKER_ID } }); return upgraded ? undefined : new Response("WebSocket Upgrade Failed", { status: 400 }); } return new Response(`Handled by worker ${WORKER_ID}`, { status: 200 }); }, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Deterministic Worker Ring WebSocket Multiplexing Standard

Bun 1.2 Deterministic Worker Ring WebSocket Multiplexing Standard defines an industrial-grade behavioral standard for backend engineering. In multi-worker Bun 1.2 runtimes, arbitrary socket handoffs and cross-worker native WebSocket upgrades cause file-descriptor epoll desynchronization, TLS session corruption, and unrecoverable renegotiation storms. WebSocket upgrades MUST be strictly pinned to deterministic CPU-affinity worker rings using consistent hashing prior to handshake initiation, guaranteeing that each native file descriptor remains bound to a single worker event loop throughout its lifecycle. 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: Cross-Worker IPC Socket Handover and Post-Accept Desynchronized Upgrades 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	Cross-Worker IPC Socket Handover and Post-Accept Desynchronized Upgrades	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 anchor each client connection to a deterministic worker thread using consistent hashing (e.g., client IP or session key) before initiating the native WebSocket upgrade via server.upgrade().

Engineers MUST ALWAYS anchor each client connection to a deterministic worker thread using consistent hashing (e.g., client IP or session key) before initiating the native WebSocket upgrade via server.upgrade().

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.