Bun 1.2 Multi-Tenant Isolated Worker Heap Fence & Zero-Copy Memory Standard

--- description: Bun 1.2 Multi-Tenant Isolated Worker Heap Fence & Zero-Copy Memory Standard - Enforces strict isolated execution boundaries and memory fencing across multi-tenant Bun worker threads. Mandates bounded worker pooling, explicit heap telemetry watchdogs with rapid process termination, and zero-copy transferable ArrayBuffer or SharedArrayBuffer pooling to eliminate noisy-neighbor heap exhaustion in edge micro-runtimes. globs: src/**/*.worker.ts, src/**/workers/**/*.ts, src/**/runtime/**/*.ts, src/**/pool/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-worker-heap-fence-production-standard" --- # Bun 1.2 Multi-Tenant Isolated Worker Heap Fence & Zero-Copy Memory Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Worker Spawning with Structured Cloning Allocations Inducing Host OOM ## System Constraints You are a Principal Engineer enforcing Bun 1.2 multi-tenant worker isolation and zero-copy memory safety. Mandate rigid worker pooling, strict heap ceilings with watchdog termination guards, zero-copy buffer transfers, and zero structured clone overhead. ## Strict Guidelines - Engineers MUST ALWAYS govern worker concurrency using a bounded worker pool; raw, unmetered `new Worker()` instantiation per tenant request is strictly forbidden. - Engineers MUST ALWAYS transfer typed data using the transfer list (`postMessage(payload, [payload.buffer])`) or pre-allocated `SharedArrayBuffer` structures to prevent GC thrashing and payload duplication. - Engineers MUST NOT pass deep JavaScript object graphs across worker thread boundaries through structured cloning under high concurrency. - Workers MUST execute periodic self-telemetry checks on `process.memoryUsage()` and invoke controlled termination or eviction before breaching tenant heap limits. - The host coordinator MUST maintain an active watchdog timeout and heartbeat on all tenant workers, issuing immediate `worker.terminate()` when a worker breaches memory or latency budgets. - Components NEVER hold lingering references to detached buffers after transferring ownership via `postMessage`. ## Bad vs Good Implementations ### Multi-Tenant Worker Execution: Unbounded Clone vs Isolated Fenced Pool #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawns an unconstrained number of Worker instances under concurrent load, duplicating memory via structured cloning and offering zero protection if a single tenant payload causes JSC isolate heap exhaustion. ```typescript import { serve } from "bun"; // ANTI-PATTERN: Spawning raw workers per tenant request with structured cloning // and no memory ceiling or lifecycle constraints. serve({ port: 3000, async fetch(req) { const tenantData = await req.json(); // Spawns unmanaged worker per connection; vulnerable to noisy-neighbor OOM const worker = new Worker(new URL("./processor.ts", import.meta.url).href); return new Promise((resolve) => { worker.onmessage = (event) => { resolve(Response.json(event.data)); // Worker is never terminated; leaks isolate thread resources }; // Structured clone creates duplicate object graphs in JSC heap worker.postMessage({ tenant: tenantData, payload: tenantData.payload }); }); }, }); ``` #### Production Standard (Correct) > **Standard**: Implements a strictly bounded worker pool configured with `smol: true`, monitors per-task heap thresholds, executes zero-copy transfer of typed array buffers, and forcibly terminates and recycles workers that exceed duration or memory safety boundaries. ```typescript import { serve } from "bun"; interface WorkerTask { buffer: Uint8Array; resolve: (res: Uint8Array) => void; reject: (err: Error) => void; } // PRODUCTION FIX: Fixed worker pool with zero-copy transfers & heap guardrails class WorkerFencePool { private pool: Worker[] = []; private queue: WorkerTask[] = []; private readonly MAX_HEAP_BYTES = 64 * 1024 * 1024; // 64MB tenant ceiling constructor(private size: number, private scriptUrl: string) { for (let i = 0; i < size; i++) { this.pool.push(this.spawnFencedWorker()); } } private spawnFencedWorker(): Worker { const worker = new Worker(thisScriptUrl(this.scriptUrl), { smol: true }); return worker; } public execute(payload: Uint8Array): Promise<Uint8Array> { return new Promise((resolve, reject) => { const worker = this.pool.pop(); if (!worker) { this.queue.push({ buffer: payload, resolve, reject }); return; } const watchdog = setTimeout(() => { worker.terminate(); this.pool.push(this.spawnFencedWorker()); reject(new Error("TenantWorkerTimeoutOrMemoryCeilingBreach")); }, 3000); worker.onmessage = (e: MessageEvent<{ buffer: Uint8Array; heapUsage: number }>) => { clearTimeout(watchdog); if (e.data.heapUsage > this.MAX_HEAP_BYTES) { worker.terminate(); this.pool.push(this.spawnFencedWorker()); } else { this.pool.push(worker); } resolve(e.data.buffer); this.drainQueue(); }; worker.onerror = (err) => { clearTimeout(watchdog); worker.terminate(); this.pool.push(this.spawnFencedWorker()); reject(err); this.drainQueue(); }; // Zero-copy transfer: buffer ownership moved, original detached worker.postMessage(payload, [payload.buffer]); }); } private drainQueue(): void { if (this.queue.length > 0 && this.pool.length > 0) { const next = this.queue.shift()!; this.execute(next.buffer).then(next.resolve, next.reject); } } } function thisScriptUrl(path: string): string { return new URL(path, import.meta.url).href; } const pool = new WorkerFencePool(navigator.hardwareConcurrency || 4, "./processor.ts"); serve({ port: 3000, async fetch(req) { const body = new Uint8Array(await req.arrayBuffer()); try { const result = await pool.execute(body); return new Response(result, { headers: { "Content-Type": "application/octet-stream" } }); } catch (err: any) { return new Response(err.message, { status: 503 }); } } }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Multi-Tenant Isolated Worker Heap Fence & Zero-Copy Memory Standard

Bun 1.2 Multi-Tenant Isolated Worker Heap Fence & Zero-Copy Memory Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict isolated execution boundaries and memory fencing across multi-tenant Bun worker threads. Mandates bounded worker pooling, explicit heap telemetry watchdogs with rapid process termination, and zero-copy transferable ArrayBuffer or SharedArrayBuffer pooling to eliminate noisy-neighbor heap exhaustion in edge micro-runtimes. 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 Worker Spawning with Structured Cloning Allocations Inducing Host OOM 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 Worker Spawning with Structured Cloning Allocations Inducing Host OOM	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 govern worker concurrency using a bounded worker pool

Engineers MUST ALWAYS govern worker concurrency using a bounded worker pool; raw, unmetered `new Worker()` instantiation per tenant request is strictly forbidden.

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.