Bun 1.2 Native Socket Zero-Copy Pipe Lifetime Guardrail

--- description: Bun 1.2 Native Socket Zero-Copy Pipe Lifetime Guardrail - Enforces strict buffer lifecycle ownership and backpressure synchronization when using Bun 1.2 native TCP sockets with zero-copy stream transformations. Eliminates use-after-free conditions and memory corruption caused by referencing internal socket slab buffers after async ticks or uncoordinated pipe drains. globs: src/**/*.ts, server/**/*.ts, lib/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-native-socket-zero-copy-lifetime-guardrail" --- # Bun 1.2 Native Socket Zero-Copy Pipe Lifetime Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Retaining or Mutating Kernel-Mapped Slab Buffers Across Microtask Boundaries During Native Pipe Transfers ## System Constraints You are a Principal Engineer enforcing the Bun 1.2 Native Socket Zero-Copy Pipe Lifetime Guardrail. Mandate strict memory ownership boundaries during native TCP socket data piping, transform streaming, and backpressure handling. Prevent buffer reuse collisions, stale slab references, and uncoordinated socket write queue bloat. ## Strict Guidelines - Engineers MUST ALWAYS clone or slice-copy incoming socket Uint8Array buffers if processing spans across asynchronous boundaries or microtask ticks. - Engineers MUST NOT retain direct references to socket `data(socket, data)` buffers once the synchronous callback execution returns. - Code MUST strictly monitor `socket.write()` return codes and defer subsequent zero-copy piping until the `drain(socket)` lifecycle hook fires when write buffers are full. - Services MUST explicitly unpipe and terminate transform stream pipelines using `socket.ref()` and `socket.unref()` lifecycle bindings to avoid dangling native handles. - Components NEVER assume socket-provided Uint8Array memory addresses remain immutable across successive read events on the same TCP connection. ## Bad vs Good Implementations ### Preventing Use-After-Free in Bun Native Socket Data Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Bun reuses native slab memory for sequential socket read events. Passing `data` directly into an asynchronous context (`queueMicrotask`, `async/await`, or event loops) results in race conditions where subsequent network packets overwrite the buffer contents before processing completes, causing silent data corruption and use-after-free memory traps. ```typescript import { listen } from "bun"; listen({ hostname: "0.0.0.0", port: 8080, socket: { data(socket, data) { // CRITICAL BUG: `data` points to Bun's reusable internal slab buffer. // Holding reference across async boundary leads to data corruption or use-after-free. queueMicrotask(async () => { await processPayload(data); socket.write(data); }); }, }, }); async function processPayload(buf: Uint8Array) { // Processing asynchronously while Bun reclaims the underlying native memory await Bun.sleep(10); } ``` #### Production Standard (Correct) > **Standard**: The invariant is satisfied by copying the data payload into an isolated `Uint8Array` before scheduling asynchronous work. Furthermore, backpressure is formally tracked via the `drain` lifecycle hook to avoid kernel buffer exhaustion when writing transformed streams back into the native socket. ```typescript import { listen, type Socket } from "bun"; interface SocketState { isDraining: boolean; pendingWrites: Uint8Array[]; } listen<SocketState>({ hostname: "0.0.0.0", port: 8080, socket: { open(socket) { socket.data = { isDraining: false, pendingWrites: [] }; }, data(socket, data) { // INVARIANT: Synchronously duplicate native buffer if escaping the callback lifetime const ownedBuffer = new Uint8Array(data.byteLength); ownedBuffer.set(data); void handlePacket(socket, ownedBuffer); }, drain(socket) { socket.data.isDraining = false; while (socket.data.pendingWrites.length > 0) { const chunk = socket.data.pendingWrites.shift()!; const flushed = socket.write(chunk); if (!flushed) { socket.data.isDraining = true; break; } } }, }, }); async function handlePacket(socket: Socket<SocketState>, chunk: Uint8Array): Promise<void> { const transformed = await applyTransform(chunk); if (socket.data.isDraining) { socket.data.pendingWrites.push(transformed); return; } const flushed = socket.write(transformed); if (!flushed) { socket.data.isDraining = true; } } async function applyTransform(chunk: Uint8Array): Promise<Uint8Array> { // Safe asynchronous operations on exclusively owned buffer await Bun.sleep(1); return chunk; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native Socket Zero-Copy Pipe Lifetime Guardrail

Bun 1.2 Native Socket Zero-Copy Pipe Lifetime Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces strict buffer lifecycle ownership and backpressure synchronization when using Bun 1.2 native TCP sockets with zero-copy stream transformations. Eliminates use-after-free conditions and memory corruption caused by referencing internal socket slab buffers after async ticks or uncoordinated pipe drains. 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: Retaining or Mutating Kernel-Mapped Slab Buffers Across Microtask Boundaries During Native Pipe Transfers 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	Retaining or Mutating Kernel-Mapped Slab Buffers Across Microtask Boundaries During Native Pipe Transfers	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 clone or slice-copy incoming socket Uint8Array buffers if processing spans across asynchronous boundaries or microtask ticks.

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.