Bun 1.2 Subprocess Piped Stream Backpressure & FD Quota Standard

--- description: Bun 1.2 Subprocess Piped Stream Backpressure & FD Quota Standard - Enforces bounded concurrency pooling, proactive pipe stream draining, and deterministic resource lifecycle disposal for Bun.spawn subprocesses. Prevents kernel pipe buffer deadlocks and silent file descriptor (FD) exhaustion under high-throughput IPC orchestration. globs: src/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, services/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-subprocess-piped-stream-backpressure-quota" --- # Bun 1.2 Subprocess Piped Stream Backpressure & FD Quota Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Bun Subprocess Spawning with Unconsumed Pipes Causing Buffer Deadlocks and EMFILE Starvation ## System Constraints You are a Principal Backend Engineer enforcing the Bun 1.2 Subprocess Piped Stream Backpressure and File Descriptor Quota Standard. Mandate explicit concurrency pooling for Bun.spawn, concurrent multi-stream consumption to prevent 64KB kernel buffer deadlocks, and deterministic stream teardown across all subprocess lifecycles. ## Strict Guidelines - Engineers MUST ALWAYS bound concurrent subprocess spawns using a semaphore or resource pool to respect process-level ulimit -n file descriptor quotas. - Engineers MUST NEVER await `proc.exited` before or without concurrently draining both `proc.stdout` and `proc.stderr` when configured with 'pipe'; unconsumed output exceeding the OS buffer size (typically 64KB) will deadlock the child process permanently. - Code MUST explicitly close child process input streams (`proc.stdin.close()` or `proc.stdin.end()`) once writing completes to signal EOF to child processes expecting closed standard input. - Services MUST implement deterministic timeout escalation: send SIGTERM first, await a grace period, and forcefully issue SIGKILL if `proc.exited` has not resolved. - Components NEVER leak open subprocess references; all exit paths (normal completion, timeouts, unhandled exceptions) MUST cancel or close unread ReadableStreams and invoke `proc.kill()` in a `finally` block if the process remains active. ## Bad vs Good Implementations ### Deadlock-Prone Unbounded Subprocess Execution vs. Bounded, Drain-Guaranteed Orchestration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawns unbounded subprocesses risking EMFILE. More critically, awaiting `proc.exited` before draining `stdout` and `stderr` deadlocks the child process as soon as either stream writes more bytes than the OS pipe buffer capacity (64KB on Linux). Dangling pipes also leak file descriptors. ```typescript import { spawn } from "bun"; // ANTI-PATTERN: Unbounded spawn, stdout/stderr read sequentially AFTER proc.exited, // causing child deadlock when stderr or stdout exceeds 64KB buffer. export async function runBatchTranscode(files: string[]): Promise<string[]> { // Leaks FDs when files.length > ulimit -n return Promise.all( files.map(async (file) => { const proc = Bun.spawn(["ffmpeg", "-i", file, "-f", "null", "-"], { stdout: "pipe", stderr: "pipe", }); // DEADLOCK HAZARD: If ffmpeg outputs >64KB to stderr before exiting, // the OS pipe buffer fills up and ffmpeg blocks forever. proc.exited never resolves. const exitCode = await proc.exited; if (exitCode !== 0) { throw new Error(`Process failed: ${exitCode}`); } // Streams read only after proc.exited (if it ever exits) return await new Response(proc.stdout).text(); }) ); } ``` #### Production Standard (Correct) > **Standard**: Throttles concurrent processes using an AsyncSemaphore to prevent FD exhaustion. Consumes both `stdout` and `stderr` concurrently with `proc.exited` using `Promise.all`, preventing pipe buffer deadlocks. Integrates robust signal timeout escalation and guarantees process termination in a `finally` block. ```typescript import { spawn, type Subprocess } from "bun"; class AsyncSemaphore { private queue: (() => void)[] = []; private active = 0; constructor(private readonly max: number) {} async acquire(): Promise<void> { if (this.active < this.max) { this.active++; return; } return new Promise((resolve) => this.queue.push(resolve)); } release(): void { this.active--; const next = this.queue.shift(); if (next) { this.active++; next(); } } } const SUBPROCESS_LIMITER = new AsyncSemaphore(16); const PROCESS_TIMEOUT_MS = 30_000; interface ExecResult { stdout: string; stderr: string; exitCode: number; } export async function executeSubprocessWithQuota( cmd: string[], signal?: AbortSignal ): Promise<ExecResult> { await SUBPROCESS_LIMITER.acquire(); let proc: Subprocess<"pipe", "pipe", "pipe"> | null = null; try { proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe", stdin: "ignore", }); const timeoutSignal = AbortSignal.timeout(PROCESS_TIMEOUT_MS); const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal; // Concurrently drain stdout and stderr to prevent OS pipe buffer saturation deadlocks const stdoutPromise = new Response(proc.stdout).text(); const stderrPromise = new Response(proc.stderr).text(); const exitPromise = proc.exited; // Abort listener for clean signal escalation const abortHandler = () => { if (proc && proc.exitCode === null) { proc.kill("SIGTERM"); setTimeout(() => { if (proc && proc.exitCode === null) proc.kill("SIGKILL"); }, 2_000).unref(); } }; combinedSignal.addEventListener("abort", abortHandler, { once: true }); const [stdout, stderr, exitCode] = await Promise.all([ stdoutPromise, stderrPromise, exitPromise, ]); combinedSignal.removeEventListener("abort", abortHandler); if (exitCode !== 0) { throw new Error(`Command failed [exit ${exitCode}]: ${stderr.slice(0, 1000)}`); } return { stdout, stderr, exitCode }; } finally { if (proc && proc.exitCode === null) { proc.kill("SIGKILL"); } SUBPROCESS_LIMITER.release(); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Subprocess Piped Stream Backpressure & FD Quota Standard

Bun 1.2 Subprocess Piped Stream Backpressure & FD Quota Standard defines an industrial-grade behavioral standard for backend engineering. Enforces bounded concurrency pooling, proactive pipe stream draining, and deterministic resource lifecycle disposal for Bun.spawn subprocesses. Prevents kernel pipe buffer deadlocks and silent file descriptor (FD) exhaustion under high-throughput IPC orchestration. 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 Bun Subprocess Spawning with Unconsumed Pipes Causing Buffer Deadlocks and EMFILE Starvation 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 Bun Subprocess Spawning with Unconsumed Pipes Causing Buffer Deadlocks and EMFILE Starvation	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 subprocess spawns using a semaphore or resource pool to respect process-level ulimit -n file descriptor quotas.

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.