Bun 1.2 Direct Socket Buffer Pinning and Memory Invariance

--- description: "Bun 1.2 Direct Socket Buffer Pinning and Memory Invariance - Enforces deterministic off-heap buffer pinning when utilizing Bun 1.2 native direct socket handles during high-throughput WebSocket broadcast pipelines. Precludes pointer invalidation, V8/JSC heap thrashing, and zero-copy read degradation by preventing native TCP buffers from escaping into unpinned JavaScript garbage collection arenas during multi-gigabit fanouts." globs: "src/**/*.{ts,tsx}, server/**/*.{ts,tsx}, lib/**/*.{ts,tsx}" alwaysApply: true license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-direct-socket-buffer-pinning-invariant" --- # Bun 1.2 Direct Socket Buffer Pinning and Memory Invariance > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Slicing, copying, or retaining native socket buffers in V8/JSC GC-managed heaps during high-throughput fanouts ## System Constraints You are a Principal Systems Architect enforcing the Bun 1.2 Direct Socket Buffer Pinning Invariant. In multi-gigabit TCP/WebSocket streaming servers, passing raw network buffers across asynchronous execution boundaries causes memory relocation, data tearing, and garbage collector latency spikes. You must enforce zero-copy off-heap views or explicit linear buffer reuse patterns to ensure native C++ socket pointers remain pinned and uncorrupted during fanout. ## Strict Guidelines - Engineers MUST ALWAYS pass pinned Uint8Array slices synchronously to `ws.publish()` or `server.publish()` within the native `data(socket, buffer)` callback boundary. - Engineers MUST NOT capture raw network socket buffers inside unbound asynchronous microtasks (such as `setTimeout`, `setImmediate`, or unawaited `Promise.all`) without copying to a pre-allocated slab or detached ArrayBuffer. - Code SHOULD utilize Bun's native `Bun.ArrayBuffer.sink()` or fixed-size off-heap `SharedArrayBuffer` structures when buffering multi-frame payloads across async boundaries. - Services MUST monitor pointer stabilization using `Bun.gc(false)` during stress harnesses to detect implicit heap reallocations and buffer eviction under saturating network load. - Components NEVER cast incoming native buffers into V8/JSC strings directly within the socket ingestion loop when performing binary fanouts. ## Bad vs Good Implementations ### WebSocket Fanout Invariant: Escaping Buffer Reference vs Pinned Synchronous Publish #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Escaping the synchronous `data` callback boundary allows the underlying native TCP receive ring buffer to be recycled or relocated before the async microtask runs, causing buffer corruption or use-after-free conditions in the fanout. ```typescript import { ServerWebSocket } from 'bun'; // Anti-pattern: Socket buffer escapes callback into unpinned async task. // JSC garbage collector or TCP buffer reuse may mutate or invalidate pointer before broadcast. Bun.listen({ hostname: '0.0.0.0', port: 4001, socket: { data(socket, buffer) { // Asynchronous boundary leaks raw native memory reference queueMicrotask(async () => { const payload = buffer.slice(0); // Slice allocates on GC heap, but original buffer pointer is already compromised await someTelemetryLog(payload); // Potential segfault or payload corruption under 10Gbps load socket.publish('market-feed', payload); }); }, }, }); async function someTelemetryLog(data: Uint8Array): Promise<void> { await Bun.sleep(1); } ``` #### Production Standard (Correct) > **Standard**: Publishes synchronously while the direct native socket buffer remains pinned by the Bun runtime. Any asynchronous work operates strictly on a cloned array, guaranteeing zero memory relocation or pointer invalidation on the primary network fanout path. ```typescript import { ServerWebSocket } from 'bun'; // Production Invariant: Synchronous zero-copy fanout while buffer is pinned, // paired with an explicit copy to an immutable pool only if asynchronous dispatch is required. Bun.listen({ hostname: '0.0.0.0', port: 4001, socket: { data(socket, buffer) { // 1. Direct zero-copy publish occurs synchronously while native pointer is guaranteed pinned const bytesSent = socket.publish('market-feed', buffer); if (bytesSent < 0) { // Handle backpressure without storing unpinned native buffer pointer socket.cork(() => socket.publish('market-feed', buffer)); } // 2. If async persistence/telemetry is required, explicitly duplicate bytes into isolated memory const pinnedCopy = new Uint8Array(buffer.byteLength); pinnedCopy.set(buffer); queueMicrotask(async () => { await someTelemetryLog(pinnedCopy); }); }, }, }); async function someTelemetryLog(data: Uint8Array): Promise<void> { await Bun.sleep(1); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Direct Socket Buffer Pinning and Memory Invariance

Bun 1.2 Direct Socket Buffer Pinning and Memory Invariance defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic off-heap buffer pinning when utilizing Bun 1.2 native direct socket handles during high-throughput WebSocket broadcast pipelines. Precludes pointer invalidation, V8/JSC heap thrashing, and zero-copy read degradation by preventing native TCP buffers from escaping into unpinned JavaScript garbage collection arenas during multi-gigabit fanouts. 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: Slicing, copying, or retaining native socket buffers in V8/JSC GC-managed heaps during high-throughput fanouts 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	Slicing, copying, or retaining native socket buffers in V8/JSC GC-managed heaps during high-throughput fanouts	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 pass pinned Uint8Array slices synchronously to `ws.publish()` or `server.publish()` within the native `data(socket, buffer)` callback boundary.

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.