Bun 1.2 Isolated Native Worker Thread Topologies for Multi-Tenant Workloads

--- description: Bun 1.2 Isolated Native Worker Thread Topologies for Multi-Tenant Workloads - Enforces bounded, zero-copy native Worker thread pools in Bun 1.2 to isolate CPU-intensive multi-tenant execution. Mitigates JavaScriptCore (JSC) heap fragmentation, thread starvation, and event-loop blocking by requiring deterministic lifecycle management and Transferable Object ownership transfer. globs: src/**/*.worker.ts, src/**/workers/**/*.ts, src/**/services/**/*.ts, src/**/pool/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-isolated-native-worker-pool-standard" --- # Bun 1.2 Isolated Native Worker Thread Topologies for Multi-Tenant Workloads > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Ad-Hoc Worker Spawning with Deep-Cloned Payloads and Unbounded Lifecycles ## System Constraints You are a Principal Software Architect enforcing production-grade Bun 1.2 Worker Thread standards. You must ensure all multi-tenant or CPU-heavy workloads run in bounded native worker pools using zero-copy Transferable ArrayBuffers, explicit worker recycling to counter JSC heap fragmentation, and deterministic timeout termination. ## Strict Guidelines - Engineers MUST ALWAYS enforce a strictly bounded worker pool based on `navigator.hardwareConcurrency`; spawning dynamic `new Worker()` instances per HTTP request is prohibited. - Engineers MUST ALWAYS pass large binary or structured payloads using Transferable Objects (`postMessage(message, [buffer])`) to achieve zero-copy ownership transfer between JavaScriptCore heaps. - Engineers MUST ALWAYS implement worker recycling (terminate and respawn after a fixed number of operations or memory threshold) to prevent irreversible JSC native heap fragmentation. - Engineers MUST ALWAYS attach both `error` and `messageerror` event listeners to prevent unhandled rejections from crashing the supervisor process. - Engineers MUST bind every worker execution to an `AbortSignal` with a strict execution timeout, immediately executing `worker.terminate()` if tenant code exceeds SLA limits. - Engineers MUST NEVER serialize complex, deeply nested JSON objects across the worker bridge when binary protocol buffers or typed arrays can be transferred directly. ## Bad vs Good Implementations ### CPU-bound Tenant Processing: Ad-Hoc Instantiation vs. Bounded Worker Pool with Zero-Copy #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawns a new native OS thread and JavaScriptCore VM instance for every incoming HTTP request. Structured cloning of large JSON payloads incurs massive allocation and GC overhead across threads. Missing termination leaks worker instances, rapidly exhausting OS thread limits and degrading performance. ```typescript import { serve } from "bun"; serve({ port: 3000, async fetch(req) { const payload = await req.json(); // ANTI-PATTERN: Spawning unmanaged native workers per HTTP request. // Clones the payload across JSC heaps, risking thread exhaustion and fragmentation. const worker = new Worker(new URL("./compute.worker.ts", import.meta.url).href); return new Promise((resolve) => { worker.postMessage(payload); // Deep structured-clone causes high GC pressure worker.onmessage = (event) => { // Worker is never terminated; leaks native thread and JSC VM instance resolve(Response.json(event.data)); }; }); }, }); ``` #### Production Standard (Correct) > **Standard**: Implements a strictly bounded worker pool sized to host CPU cores. Employs zero-copy ArrayBuffer transfer lists to eliminate heap duplication. Includes hard timeout cancellation via worker termination to protect against runaway tenant compute, and automatically recycles workers after 500 tasks to guard against JSC native heap fragmentation. ```typescript import { serve } from "bun"; interface Task { buffer: ArrayBuffer; resolve: (data: ArrayBuffer) => void; reject: (err: Error) => void; signal: AbortSignal; } export class BoundedTenantWorkerPool { private workers: Worker[] = []; private queue: Task[] = []; private activeWorkers = new Set<Worker>(); private taskCounts = new WeakMap<Worker, number>(); private readonly maxTasksPerWorker = 500; // Counteract JSC heap fragmentation constructor( private readonly scriptUrl: URL, private readonly poolSize = Math.max(1, navigator.hardwareConcurrency - 1) ) { for (let i = 0; i < this.poolSize; i++) { this.spawnWorker(); } } private spawnWorker(): Worker { const worker = new Worker(this.scriptUrl.href); this.taskCounts.set(worker, 0); this.workers.push(worker); return worker; } public async execute(buffer: ArrayBuffer, timeoutMs = 5000): Promise<ArrayBuffer> { const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), timeoutMs); return new Promise<ArrayBuffer>((resolve, reject) => { this.queue.push({ buffer, resolve: (res) => { clearTimeout(timeout); resolve(res); }, reject: (err) => { clearTimeout(timeout); reject(err); }, signal: controller.signal, }); this.dispatch(); }); } private dispatch(): void { if (this.queue.length === 0 || this.workers.length === 0) return; const worker = this.workers.pop()!; const task = this.queue.shift()!; this.activeWorkers.add(worker); if (task.signal.aborted) { this.recycleWorker(worker); task.reject(new Error("Task timed out before execution")); this.dispatch(); return; } const abortHandler = () => { this.recycleWorker(worker); task.reject(new Error("Worker task execution exceeded timeout limit")); this.dispatch(); }; task.signal.addEventListener("abort", abortHandler, { once: true }); worker.onmessage = (e: MessageEvent<ArrayBuffer>) => { task.signal.removeEventListener("abort", abortHandler); this.activeWorkers.delete(worker); const currentTasks = (this.taskCounts.get(worker) ?? 0) + 1; if (currentTasks >= this.maxTasksPerWorker) { this.recycleWorker(worker); } else { this.taskCounts.set(worker, currentTasks); this.workers.push(worker); } task.resolve(e.data); this.dispatch(); }; worker.onerror = (err) => { task.signal.removeEventListener("abort", abortHandler); this.recycleWorker(worker); task.reject(err); this.dispatch(); }; // Zero-copy memory transfer into worker thread worker.postMessage(task.buffer, [task.buffer]); } private recycleWorker(worker: Worker): void { this.activeWorkers.delete(worker); worker.terminate(); this.spawnWorker(); } } const pool = new BoundedTenantWorkerPool(new URL("./compute.worker.ts", import.meta.url)); serve({ port: 3000, async fetch(req) { const rawBytes = await req.arrayBuffer(); try { const result = await pool.execute(rawBytes, 3000); return new Response(result, { headers: { "Content-Type": "application/octet-stream" }, }); } catch (error) { const message = error instanceof Error ? error.message : "Compute failure"; return new Response(message, { status: 500 }); } }, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Isolated Native Worker Thread Topologies for Multi-Tenant Workloads

Bun 1.2 Isolated Native Worker Thread Topologies for Multi-Tenant Workloads defines an industrial-grade behavioral standard for backend engineering. Enforces bounded, zero-copy native Worker thread pools in Bun 1.2 to isolate CPU-intensive multi-tenant execution. Mitigates JavaScriptCore (JSC) heap fragmentation, thread starvation, and event-loop blocking by requiring deterministic lifecycle management and Transferable Object ownership transfer. 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: Ad-Hoc Worker Spawning with Deep-Cloned Payloads and Unbounded Lifecycles 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	Ad-Hoc Worker Spawning with Deep-Cloned Payloads and Unbounded Lifecycles	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 enforce a strictly bounded worker pool based on `navigator.hardwareConcurrency`

Engineers MUST ALWAYS enforce a strictly bounded worker pool based on `navigator.hardwareConcurrency`; spawning dynamic `new Worker()` instances per HTTP request is prohibited.

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.