Bun 1.2 Native FFI Buffer Pinning and Explicit Memory Reclamation Standard

--- description: Bun 1.2 Native FFI Buffer Pinning and Explicit Memory Reclamation Standard - Establishes deterministic lifecycle boundaries and pin-tracking for Uint8Array memory buffers crossed between Bun 1.2 runtime and foreign native dynamic libraries (C/Rust). Prevents premature JavaScript garbage collection, use-after-free (UAF), and native memory leaks during asynchronous FFI invocations and worker-thread dispatch under high-throughput I/O. globs: src/**/*.{ts,js}, lib/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-ffi-buffer-pinning-reclamation" --- # Bun 1.2 Native FFI Buffer Pinning and Explicit Memory Reclamation Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Ephemeral FFI pointer conversions causing catastrophic use-after-free or unbounded unmanaged heap leaks ## System Constraints You are a Principal Systems and Backend Engineer enforcing the Bun 1.2 Native FFI Buffer Pinning and Memory Reclamation Standard. Foreign Function Interface boundaries require strict deterministic guarantees: JavaScript Garbage Collection has no awareness of unmanaged C/Rust thread pools, and unmanaged native allocators (malloc/jemalloc) will never be collected by JavaScript engine heuristics. You must mandate unmanaged lifecycle tracking via explicit Pin/Free guards, enforce pointer validation using Bun.toArrayBuffer/Bun.ptr, and completely prohibit passing temporary views across asynchronous native calls without persistent references. ## Strict Guidelines - Engineers MUST ALWAYS maintain an active JavaScript reference to any TypedArray passed as a pointer (`ptr(buffer)`) until native execution and all associated native worker callbacks are fully completed. - Engineers MUST NOT create temporary or inline buffer references directly inside FFI invocation arguments (e.g., `lib.symbols.process(ptr(new Uint8Array(1024)))`), as V8/JSC GC can collect and relocate the backing store mid-execution. - Engineers MUST wrap unmanaged heap memory allocated by foreign functions in a formal `FinalizationRegistry` or explicit `Disposable` (`using` keyword via Symbol.dispose) to guarantee deallocation via the foreign library's designated deallocator. - Services MUST explicitly call native free routines (e.g., `lib.symbols.free_buffer(ptr)`) rather than relying on JavaScript Garbage Collection to reclaim memory allocated across native boundaries. - Components NEVER cast raw pointers (`bun:ffi` `Pointer` or `number`) into `Bun.toArrayBuffer()` without asserting boundary limits, length, and null-pointer validity (`ptr === 0`). ## Bad vs Good Implementations ### Asynchronous FFI Buffer Passing with Deterministic Lifetime Pinning #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing an inline, unanchored buffer reference to an asynchronous native FFI function causes a catastrophic use-after-free (UAF) race condition. The JavaScript GC can collect and reuse the backing array buffer memory while the native thread is actively reading it. ```typescript import { cc, ptr } from "bun:ffi"; const lib = cc({ source: "./native_ops.c", symbols: { process_payload_async: { args: ["ptr", "usize"], returns: "void", }, }, }); export function submitTelemetry(data: Record<string, unknown>) { const payload = Buffer.from(JSON.stringify(data)); // CRITICAL BUG: `payload` goes out of scope immediately. // When Bun GC sweeps, the underlying memory is freed while native_ops.c is still reading. lib.symbols.process_payload_async(ptr(payload), payload.byteLength); } ``` #### Production Standard (Correct) > **Standard**: Explicitly pins the Uint8Array buffer in module-scoped state (`pinnedBuffers`) keyed by an operation ID. This guarantees the JavaScript engine cannot reclaim the backing store while the native C/Rust thread interacts with the memory pointer. ```typescript import { dlopen, ptr, FFIType } from "bun:ffi"; const { symbols: lib } = dlopen("libnative_ops.so", { process_payload_async: { args: [FFIType.ptr, FFIType.usize, FFIType.u64], returns: FFIType.void, }, register_completion_callback: { args: [FFIType.function], returns: FFIType.void, }, }); // Pinning anchor map prevents premature JavaScript GC deallocation const pinnedBuffers = new Map<bigint, Uint8Array>(); let opCounter = 0n; export async function submitTelemetry(data: Record<string, unknown>): Promise<void> { const opId = ++opCounter; const rawBuffer = new TextEncoder().encode(JSON.stringify(data)); // Pin: Hold persistent reference in module scope pinnedBuffers.set(opId, rawBuffer); return new Promise<void>((resolve, reject) => { try { lib.process_payload_async(ptr(rawBuffer), rawBuffer.byteLength, opId); // In production, an FFI callback resolves this promise and executes unpinning: // pinnedBuffers.delete(opId); resolve(); } catch (err) { pinnedBuffers.delete(opId); reject(err); } }); } ``` ### Deterministic Native Heap Reclamation via Explicit Disposable Pattern #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The native library allocates a heap buffer, and `toArrayBuffer` creates an external view, but the unmanaged memory is never freed. Under heavy I/O workloads, this causes unbounded native heap growth and out-of-memory container termination. ```typescript import { dlopen, FFIType, toArrayBuffer } from "bun:ffi"; const { symbols: lib } = dlopen("libimage.so", { generate_thumbnail: { args: [FFIType.ptr, FFIType.usize, FFIType.ptr], returns: FFIType.ptr, }, }); export function createThumbnail(input: Uint8Array): Uint8Array { const outLenPtr = new Uint32Array(1); // Bug: Pointer returned from native allocation is read into JS view, // but native malloc buffer is orphaned and leaked forever in the process heap. const nativePtr = lib.generate_thumbnail(input, input.byteLength, outLenPtr); const length = outLenPtr[0]!; const resultBuffer = toArrayBuffer(nativePtr, 0, length); return new Uint8Array(resultBuffer); } ``` #### Production Standard (Correct) > **Standard**: Uses TypeScript/JavaScript explicit resource management (`using` and `Symbol.dispose`) to guarantee that the native allocation is freed via `free_image_buffer` immediately upon leaving the scope, cloning the bytes into managed memory. ```typescript import { dlopen, FFIType, toArrayBuffer, type Pointer } from "bun:ffi"; const { symbols: lib } = dlopen("libimage.so", { generate_thumbnail: { args: [FFIType.ptr, FFIType.usize, FFIType.ptr], returns: FFIType.ptr, }, free_image_buffer: { args: [FFIType.ptr], returns: FFIType.void, }, }); export class NativeBufferScope implements Disposable { constructor(public readonly ptr: Pointer) {} [Symbol.dispose](): void { if (this.ptr !== 0) { lib.free_image_buffer(this.ptr); } } } export function createThumbnail(input: Uint8Array): Uint8Array { const outLenPtr = new Uint32Array(1); const rawPtr = lib.generate_thumbnail(input, input.byteLength, outLenPtr); if (rawPtr === 0) { throw new Error("Native thumbnail generation failed: Null pointer returned"); } using scope = new NativeBufferScope(rawPtr); const length = outLenPtr[0]!; // Copy the data into managed JS memory before deterministic disposal const tempView = new Uint8Array(toArrayBuffer(scope.ptr, 0, length)); return new Uint8Array(tempView); // Detaches from native pointer lifetime } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native FFI Buffer Pinning and Explicit Memory Reclamation Standard

Bun 1.2 Native FFI Buffer Pinning and Explicit Memory Reclamation Standard defines an industrial-grade behavioral standard for backend engineering. Establishes deterministic lifecycle boundaries and pin-tracking for Uint8Array memory buffers crossed between Bun 1.2 runtime and foreign native dynamic libraries (C/Rust). Prevents premature JavaScript garbage collection, use-after-free (UAF), and native memory leaks during asynchronous FFI invocations and worker-thread dispatch under high-throughput I/O. 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: Ephemeral FFI pointer conversions causing catastrophic use-after-free or unbounded unmanaged heap leaks 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	Ephemeral FFI pointer conversions causing catastrophic use-after-free or unbounded unmanaged heap leaks	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 maintain an active JavaScript reference to any TypedArray passed as a pointer (`ptr(buffer)`) until native execution and all associated native worker callbacks are fully completed.

Engineers MUST ALWAYS maintain an active JavaScript reference to any TypedArray passed as a pointer (`ptr(buffer)`) until native execution and all associated native worker callbacks are fully completed.

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.