Bun 1.2 Cluster Zero-Downtime Socket Handoff & Drain Protocol

--- description: "Bun 1.2 Cluster Zero-Downtime Socket Handoff & Drain Protocol - Mandates deterministic zero-downtime rolling restarts in Bun 1.2+ clusters via kernel-level SO_REUSEPORT socket coordination. Enforces an explicit two-phase IPC synchronization protocol ensuring the incoming replacement worker actively listens on the shared port before the outgoing worker initiates connection draining and file descriptor release." globs: "src/**/*.ts, server/**/*.ts, cluster/**/*.ts" alwaysApply: true license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-cluster-zero-downtime-socket-handoff-standard" --- # Bun 1.2 Cluster Zero-Downtime Socket Handoff & Drain Protocol > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Out-of-Sequence Worker Termination and Unsynchronized SO_REUSEPORT Drains Dropping In-Flight TCP Connections ## System Constraints You are a Principal Engineer enforcing the Bun 1.2 Cluster Zero-Downtime Socket Handoff Standard. You must mandate that all multi-worker configurations employ SO_REUSEPORT socket sharing alongside explicit bidirectional IPC handshake protocols. Prevent race conditions where workers are terminated before the successor binds, and ensure connection draining uses non-destructive server stopping with timeout guards. ## Strict Guidelines - Services MUST ALWAYS configure Bun.serve with `reusePort: true` when operating under multi-process clustering. - The primary orchestrator MUST NEVER signal an active worker to drain or exit until the successor worker has explicitly emitted a verified IPC 'ready' event. - Retiring workers MUST call `server.stop(false)` to cease accepting new connections while permitting in-flight TCP sessions to drain gracefully. - Retiring workers MUST implement a deterministic drain timeout (deadline) that enforces a hard termination (`server.stop(true)`) only if inflight requests fail to clear within the SLA window. - Engineers MUST NOT rely on synchronous process signals (e.g., bare SIGTERM or SIGKILL) for worker recycling without an asynchronous drain barrier. ## Bad vs Good Implementations ### Cluster Socket Handoff and Worker Drain Protocol #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The orchestrator kills the old worker before the new worker binds to the port, creating an availability gap where incoming SYNs are dropped. Additionally, the worker does not enable `reusePort`, causing binding races, and exits immediately on SIGTERM without draining in-flight requests. ```typescript import { spawn } from "bun"; // ANTI-PATTERN: Naive worker recycling causing TCP RST and connection drops export class NaiveCluster { private workers: Array<ReturnType<typeof spawn>> = []; async reloadWorker(index: number) { const oldWorker = this.workers[index]; // Kills the old worker before verifying the new one is bound to the port oldWorker.kill("SIGTERM"); const newWorker = spawn(["bun", "run", "src/worker.ts"], { stdout: "inherit", stderr: "inherit", }); this.workers[index] = newWorker; } } // worker.ts import { serve } from "bun"; // Missing reusePort allows socket collisions or bind errors serve({ port: 8080, fetch(req) { return new Response("OK"); }, }); process.on("SIGTERM", () => { // Abrupt exit drops active TCP connections immediately process.exit(0); }); ``` #### Production Standard (Correct) > **Standard**: Enforces `reusePort: true` so multiple Bun processes bind to port 8080 without conflicts. The orchestrator spawns the replacement worker and only initiates predecessor shutdown after receiving the 'READY' IPC signal. The retiring worker calls `server.stop(false)` to reject new connections while allowing inflight traffic to drain cleanly before exiting. ```typescript import { spawn, type Subprocess } from "bun"; // PRODUCTION FIX: Coordinated SO_REUSEPORT rolling restart with explicit IPC handshakes interface ClusterMessage { type: "READY" | "DRAIN" | "DRAINED"; } export class ZeroDowntimeCluster { private workers: Map<number, Subprocess> = new Map(); async reloadWorker(workerId: number): Promise<void> { const oldWorker = this.workers.get(workerId); // 1. Spawn successor worker with IPC enabled const newWorker = spawn(["bun", "run", "src/worker.ts"], { ipc(message: ClusterMessage) { if (message.type === "READY") { // 2. Successor is actively listening on SO_REUSEPORT; initiate graceful drain of predecessor if (oldWorker) { oldWorker.send({ type: "DRAIN" }); } } }, stdout: "inherit", stderr: "inherit", }); this.workers.set(workerId, newWorker); } } // worker.ts import { serve, type Server } from "bun"; let server: Server | null = null; let inFlightRequests = 0; const DRAIN_TIMEOUT_MS = 15000; server = serve({ port: 8080, reusePort: true, // Guarantees kernel-level socket load distribution fetch(req) { inFlightRequests++; try { return new Response("Handled safely"); } finally { inFlightRequests--; } }, }); // Signal orchestrator that socket bind is complete and epoll loop is active process.send?.({ type: "READY" }); process.on("message", async (message: ClusterMessage) => { if (message.type === "DRAIN" && server) { // Stop accepting new connections, but maintain existing connections open server.stop(false); const start = Date.now(); const checkDrain = setInterval(() => { const timedOut = Date.now() - start > DRAIN_TIMEOUT_MS; if (inFlightRequests === 0 || timedOut) { clearInterval(checkDrain); if (timedOut && server) { server.stop(true); // Force close lingering stalled connections } process.send?.({ type: "DRAINED" }); process.exit(0); } }, 100); } }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Cluster Zero-Downtime Socket Handoff & Drain Protocol

Bun 1.2 Cluster Zero-Downtime Socket Handoff & Drain Protocol defines an industrial-grade behavioral standard for backend engineering. Mandates deterministic zero-downtime rolling restarts in Bun 1.2+ clusters via kernel-level SO_REUSEPORT socket coordination. Enforces an explicit two-phase IPC synchronization protocol ensuring the incoming replacement worker actively listens on the shared port before the outgoing worker initiates connection draining and file descriptor release. 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: Out-of-Sequence Worker Termination and Unsynchronized SO_REUSEPORT Drains Dropping In-Flight TCP Connections 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	Out-of-Sequence Worker Termination and Unsynchronized SO_REUSEPORT Drains Dropping In-Flight TCP Connections	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:

Services MUST ALWAYS configure Bun.serve with `reusePort

Services MUST ALWAYS configure Bun.serve with `reusePort: true` when operating under multi-process clustering.

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.