Bun 1.2 Zero-Copy TCP Socket Re-Binding and SO_REUSEPORT Handoff Standard

--- description: Bun 1.2 Zero-Copy TCP Socket Re-Binding and SO_REUSEPORT Handoff Standard - Mandates kernel-level SO_REUSEPORT socket configuration and zero-copy TCP buffer lifecycles in Bun 1.2 microservices during rolling deployments. Prevents TCP reset (RST) spikes, port-binding contention, and in-flight zero-copy buffer eviction during blue/green process replacements. Enforces non-destructive socket drainage and strict dual-process overlap until health-probe convergence. globs: src/**/*.{ts,js}, server/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-zero-copy-tcp-reuseport-handoff-standard" --- # Bun 1.2 Zero-Copy TCP Socket Re-Binding and SO_REUSEPORT Handoff Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: EADDRINUSE collisions and abruptly dropped TCP connections from premature teardown without SO_REUSEPORT socket handoffs. ## System Constraints You are a Principal Engineer enforcing the Bun 1.2 Native Zero-Copy TCP Socket Re-Binding Standard. You must strictly require SO_REUSEPORT kernel socket binding, zero-copy socket buffer draining, and zero-downtime graceful signal handoffs across all Bun microservices. ## Strict Guidelines - Services MUST explicitly pass `reusePort: true` inside `Bun.listen()` or `Bun.serve()` configurations to enable kernel-level `SO_REUSEPORT` load balancing and seamless process replacement. - Engineers MUST NOT issue unconditional `process.exit()` calls before checking active connection drain states and zero-copy socket buffer flushes. - Services MUST implement a phased shutdown lifecycle triggered by `SIGTERM`: first stop accepting new TCP connections (`server.stop(false)` or `server.pause()`), second drain pending zero-copy writes via `socket.flush()`, and finally terminate the process after existing sockets are closed or a hard deadline expires. - Code MUST NEVER unbind or close the primary listening socket before the replacement worker process signals successful bind and health verification. - Engineers MUST configure kernel-level backlogs explicitly (`backlog: 1024` or higher) alongside `reusePort: true` to prevent SYN packet dropouts during burst handoffs. - Services handling streaming zero-copy workloads MUST monitor `socket.data` reference lifecycles and ensure all slice references are consumed or copied prior to socket close. ## Bad vs Good Implementations ### Bun 1.2 Zero-Downtime SO_REUSEPORT TCP Listener Handoff #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting `reusePort: true` leads to `EADDRINUSE` failures when starting a concurrent replacement process. Terminating abruptly on `SIGTERM` via `process.exit(0)` discards kernel socket buffers and truncates in-flight TCP connections without graceful drainage. ```typescript import { listen } from 'bun'; // ANTI-PATTERN: Default listen does not enable SO_REUSEPORT. // Deploying a new instance will throw EADDRINUSE or force terminating // the old process before the new one is warm, causing connection drops. const server = listen({ hostname: '0.0.0.0', port: 8080, socket: { data(socket, data) { socket.write(data); }, open(socket) {}, close(socket) {}, error(socket, error) {} } }); process.on('SIGTERM', () => { // Abrupt unbinding and hard exit cuts off in-flight zero-copy TCP writes server.stop(); process.exit(0); }); ``` #### Production Standard (Correct) > **Standard**: Uses `reusePort: true` and an explicit backlog, allowing an updated process to bind to port 8080 concurrently without downtime. On `SIGTERM`, `server.stop(false)` ceases accepting new connections while active sockets drain their TCP buffers before process termination. ```typescript import { listen, type TCPSocketListener, type TCPSocket } from 'bun'; interface SessionState { inFlightWrites: number; } const activeSockets = new Set<TCPSocket<SessionState>>(); // PRODUCTION FIX: Enable kernel-level SO_REUSEPORT and explicit backlog const server: TCPSocketListener<SessionState> = listen<SessionState>({ hostname: '0.0.0.0', port: 8080, socket: { data(socket, data) { socket.data.inFlightWrites++; const flushed = socket.write(data); if (flushed) { socket.data.inFlightWrites--; } }, open(socket) { socket.data = { inFlightWrites: 0 }; activeSockets.add(socket); }, drain(socket) { socket.data.inFlightWrites = 0; }, close(socket) { activeSockets.delete(socket); }, error(socket, err) { console.error(`Socket error: ${err.message}`); activeSockets.delete(socket); } }, // Kernel-level socket sharing across concurrent replacement processes reusePort: true, backlog: 2048 }); async function gracefulHandoff(): Promise<void> { // Stop receiving incoming TCP connections on this PID; replacement handles new SYNs server.stop(false); const deadline = Date.now() + 15000; const checkDrain = async (): Promise<void> => { for (const socket of activeSockets) { if (socket.data?.inFlightWrites === 0) { socket.end(); } } if (activeSockets.size === 0 || Date.now() > deadline) { for (const socket of activeSockets) { socket.terminate(); } process.exit(0); } setTimeout(checkDrain, 100); }; await checkDrain(); } process.on('SIGTERM', () => { void gracefulHandoff(); }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Zero-Copy TCP Socket Re-Binding and SO_REUSEPORT Handoff Standard

Bun 1.2 Zero-Copy TCP Socket Re-Binding and SO_REUSEPORT Handoff Standard defines an industrial-grade behavioral standard for backend engineering. Mandates kernel-level SO_REUSEPORT socket configuration and zero-copy TCP buffer lifecycles in Bun 1.2 microservices during rolling deployments. Prevents TCP reset (RST) spikes, port-binding contention, and in-flight zero-copy buffer eviction during blue/green process replacements. Enforces non-destructive socket drainage and strict dual-process overlap until health-probe convergence. 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: EADDRINUSE collisions and abruptly dropped TCP connections from premature teardown without SO_REUSEPORT socket handoffs. 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	EADDRINUSE collisions and abruptly dropped TCP connections from premature teardown without SO_REUSEPORT socket handoffs.	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 explicitly pass `reusePort

Services MUST explicitly pass `reusePort: true` inside `Bun.listen()` or `Bun.serve()` configurations to enable kernel-level `SO_REUSEPORT` load balancing and seamless process replacement.

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.