Atomic Socket Migration and Graceful In-Flight Draining in Bun Cluster Topologies

--- description: Atomic Socket Migration and Graceful In-Flight Draining in Bun Cluster Topologies - Enforces deterministic, zero-downtime rolling worker recycles in Bun 1.2+ server clusters by utilizing atomic socket handoff and non-destructive worker draining. Guarantees zero dropped TCP SYN packets or truncated in-flight TLS streams by decoupling the listening socket lifecycle from individual worker lifecycles. globs: src/**/*.{ts,js}, server/**/*.{ts,js}, cluster/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-cluster-socket-handoff-zero-downtime-draining-production-standard" --- # Atomic Socket Migration and Graceful In-Flight Draining in Bun Cluster Topologies > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Abrupt Process Termination and Uncoordinated Socket Teardown Triggering TCP Reset (RST) and 502 Bad Gateway Cascades ## System Constraints You are a Principal Software Architect enforcing Bun 1.2+ cluster socket handoff and zero-downtime worker lifecycle management. You must ensure all HTTP/TCP server designs decouple socket binding from request execution, prevent premature worker termination during rolling deploys, and enforce strict draining timeouts with active connection tracking. ## Strict Guidelines - Workers MUST NEVER call `server.stop(true)` or invoke `process.exit()` while in-flight TCP/TLS requests remain unfinalized. - Engineers MUST configure `server.stop(false)` on retirement to cease accepting new connections on the local file descriptor while servicing pending requests. - Primary supervisor processes MUST orchestrate rolling replacements serially: the new worker MUST complete socket inheritance and signal readiness before the retiring worker initiates drain mode. - Services MUST enforce an explicit drain timeout deadline (e.g., 15–30 seconds) that issues an escalation from graceful draining to forced socket termination (`server.stop(true)`) to prevent zombie worker accumulation. - Workers MUST maintain a deterministic in-flight request counter or rely on Bun's native `server.pendingRequests` inspection before process exit. - Sockets passed over IPC or shared via cluster handles MUST preserve kernel-level backlogs (`SO_REUSEPORT` or primary socket passing) to eliminate TCP SYN drop windows during worker turnover. ## Bad vs Good Implementations ### Naive Immediate Termination vs. Atomic Socket Handoff & Drain Protocol #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling server.stop(true) drops all active connections instantly and triggers TCP RST packets to clients. Exiting without coordinating with the cluster supervisor drops queued TCP SYN packets in the socket backlog, resulting in 502/504 errors on upstream proxies. ```typescript import { serve } from 'bun'; const server = serve({ port: 3000, fetch(req) { return new Response('Processed'); }, }); // ANTI-PATTERN: Direct exit drops pending TCP frames and tears down the listening socket process.on('SIGTERM', async () => { console.log('Worker shutting down abruptly...'); // server.stop(true) forcibly tears down active TCP connections with ECONNRESET server.stop(true); process.exit(0); }); ``` #### Production Standard (Correct) > **Standard**: Enables reusePort for zero-downtime binding across cluster workers, notifies supervisor upon readiness, stops accepting new requests via non-destructive server.stop(false), monitors pending requests until completion, and maintains an unref'd timeout guard against indefinite hangs. ```typescript import { serve, type Server } from 'bun'; const DRAIN_TIMEOUT_MS = 15_000; const server: Server = serve({ port: process.env.PORT ? parseInt(process.env.PORT, 10) : 3000, reusePort: true, // Utilize OS-level socket reuse across cluster workers fetch(req) { return new Response('Processed gracefully'); }, }); // Notify parent supervisor that this worker is ready to receive traffic if (process.send) { process.send({ type: 'WORKER_READY', pid: process.pid }); } async function initiateGracefulDrain(): Promise<void> { console.info(`[Worker ${process.pid}] Ceasing ingress; initiating connection drain.`); // 1. Close listener so no new requests are accepted by this worker // Passing 'false' instructs Bun to drain active connections without sending RST server.stop(false); // 2. Bound drain deadline to avoid orphan hanging sockets const forceKillTimer = setTimeout(() => { console.error(`[Worker ${process.pid}] Drain timeout expired. Forcing socket closure.`); server.stop(true); process.exit(1); }, DRAIN_TIMEOUT_MS); forceKillTimer.unref(); // 3. Poll Bun server pending requests until queue is zero while (server.pendingRequests > 0 || server.pendingWebSockets > 0) { await Bun.sleep(100); } console.info(`[Worker ${process.pid}] All pending requests completed cleanly.`); clearTimeout(forceKillTimer); process.exit(0); } process.on('SIGTERM', () => { initiateGracefulDrain().catch((err) => { console.error(`[Worker ${process.pid}] Error during drain:`, err); process.exit(1); }); }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Atomic Socket Migration and Graceful In-Flight Draining in Bun Cluster Topologies

Atomic Socket Migration and Graceful In-Flight Draining in Bun Cluster Topologies defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic, zero-downtime rolling worker recycles in Bun 1.2+ server clusters by utilizing atomic socket handoff and non-destructive worker draining. Guarantees zero dropped TCP SYN packets or truncated in-flight TLS streams by decoupling the listening socket lifecycle from individual worker lifecycles. 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: Abrupt Process Termination and Uncoordinated Socket Teardown Triggering TCP Reset (RST) and 502 Bad Gateway Cascades 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	Abrupt Process Termination and Uncoordinated Socket Teardown Triggering TCP Reset (RST) and 502 Bad Gateway Cascades	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:

Workers MUST NEVER call `server.stop(true)` or invoke `process.exit()` while in-flight TCP/TLS requests remain unfinalized.

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.