Bun 1.2 Native Connection Pool Backpressure Isolation & Thread Starvation Guardrail

--- description: Bun 1.2 Native Connection Pool Backpressure Isolation & Thread Starvation Guardrail - Bun 1.2 leverages native Zig/C++ async I/O primitives and uSockets underneath the JavaScript runtime. Unbounded asynchronous native operations—such as unthrottled fetch dispatches, unmetered native socket allocations, and limitless database pool acquisitions—exhaust native file descriptors and starve worker threads during traffic bursts. This standard mandates deterministic semaphore bounds, acquisition deadlines, and native backpressure isolation across all outbound I/O layers. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-native-connection-pool-backpressure-isolation" --- # Bun 1.2 Native Connection Pool Backpressure Isolation & Thread Starvation Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Asynchronous Native I/O Dispatch Inducing Zig Worker Pool Starvation and FD Exhaustion ## System Constraints You are a Principal Software Architect enforcing Bun 1.2 Native Connection Pool Backpressure Isolation. Mandate explicit concurrency gates, bounded acquisition queues, and fast-failing timeouts on all native I/O boundaries to eliminate worker thread starvation and event loop delays under bursty workloads. ## Strict Guidelines - Engineers MUST ALWAYS bound concurrent native operations (fetch, native SQL, and TCP socket handles) using an explicit bounded semaphore or token-bucket controller. - Engineers MUST NOT dispatch unbounded parallel arrays directly through Promise.all or Promise.allSettled without bounded concurrency slicing. - Code SHOULD enforce strict acquisition timeouts on native connection pool checkout requests, immediately rejecting callers with a 503 or custom backpressure error when wait queues exceed capacity. - Services MUST monitor and expose queue depth metrics and reject ingress traffic before backpressure cascades into file descriptor exhaustion. - Components NEVER hold open native connection handles across tick-spanning asynchronous gaps without dedicated lease-abort hooks. ## Bad vs Good Implementations ### Outbound Native HTTP Fetch Dispatcher with Strict Backpressure Semaphore #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Executing hundreds or thousands of unmetered native fetch calls concurrently bypasses JavaScript queue discipline and overwhelms Bun's underlying Zig network thread pool. This leads to socket allocation stalls, delayed microtask resolution, and unrecoverable FD exhaustion. ```typescript import { serve } from "bun"; // ANTI-PATTERN: Unbounded concurrent native fetch dispatches exhaust Bun's // internal Zig worker queues and native epoll/kqueue file descriptors during spikes. export async function handleBurstOutbound(requests: Array<{ id: string; url: string }>) { return Promise.all( requests.map(async (req) => { const response = await fetch(req.url, { headers: { "x-request-id": req.id } }); return response.json(); }) ); } ``` #### Production Standard (Correct) > **Standard**: Enforces deterministic concurrency limits (64 active native sockets) with bounded waiting queues (max 512) and explicit acquisition deadlines (1500ms). Prevents native worker thread starvation and rejects excess bursts gracefully before resource exhaustion occurs. ```typescript export class NativeBackpressurePool { private running = 0; private queue: Array<{ resolve: () => void; reject: (err: Error) => void }> = []; constructor( private readonly maxConcurrent: number, private readonly maxQueueDepth: number, private readonly acquireTimeoutMs: number ) {} async acquire(signal?: AbortSignal): Promise<() => void> { if (signal?.aborted) { throw new Error("Operation aborted prior to pool acquisition"); } if (this.running < this.maxConcurrent) { this.running++; return () => this.release(); } if (this.queue.length >= this.maxQueueDepth) { throw new Error(`Connection pool backpressure limit reached: queue depth ${this.queue.length}`); } return new Promise<() => void>((resolve, reject) => { const timer = setTimeout(() => { const idx = this.queue.findIndex(item => item.reject === reject); if (idx !== -1) { this.queue.splice(idx, 1); reject(new Error(`Native pool acquisition timed out after ${this.acquireTimeoutMs}ms`)); } }, this.acquireTimeoutMs); const abortHandler = () => { clearTimeout(timer); const idx = this.queue.findIndex(item => item.reject === reject); if (idx !== -1) { this.queue.splice(idx, 1); reject(new Error("Native pool acquisition aborted")); } }; signal?.addEventListener("abort", abortHandler, { once: true }); this.queue.push({ resolve: () => { clearTimeout(timer); signal?.removeEventListener("abort", abortHandler); resolve(() => this.release()); }, reject }); }); } private release(): void { this.running--; const next = this.queue.shift(); if (next) { this.running++; next.resolve(); } } } const outboundPool = new NativeBackpressurePool(64, 512, 1500); export async function handleBurstOutbound(requests: Array<{ id: string; url: string }>, parentSignal?: AbortSignal) { return Promise.all( requests.map(async (req) => { const release = await outboundPool.acquire(parentSignal); try { const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), 5000); const response = await fetch(req.url, { headers: { "x-request-id": req.id }, signal: controller.signal }); clearTimeout(timer); return await response.json(); } finally { release(); } }) ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native Connection Pool Backpressure Isolation & Thread Starvation Guardrail

Bun 1.2 Native Connection Pool Backpressure Isolation & Thread Starvation Guardrail defines an industrial-grade behavioral standard for backend engineering. Bun 1.2 leverages native Zig/C++ async I/O primitives and uSockets underneath the JavaScript runtime. Unbounded asynchronous native operations—such as unthrottled fetch dispatches, unmetered native socket allocations, and limitless database pool acquisitions—exhaust native file descriptors and starve worker threads during traffic bursts. This standard mandates deterministic semaphore bounds, acquisition deadlines, and native backpressure isolation across all outbound I/O layers. 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: Unbounded Asynchronous Native I/O Dispatch Inducing Zig Worker Pool Starvation and FD Exhaustion 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	Unbounded Asynchronous Native I/O Dispatch Inducing Zig Worker Pool Starvation and FD Exhaustion	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 bound concurrent native operations (fetch, native SQL, and TCP socket handles) using an explicit bounded semaphore or token-bucket controller.

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.