Bun 1.2 Kernel Socket Backpressure & Zero-Copy WebSocket Stream Standard

--- description: Bun 1.2 Kernel Socket Backpressure & Zero-Copy WebSocket Stream Standard - Enforces deterministic TCP buffer drainage thresholds and binary chunk recycling across high-throughput Bun WebSocket server connections. Mandates explicit inspection of ws.getBufferedAmount() combined with reactive drain callbacks to prevent native kernel-buffer saturation and process-level out-of-memory cascading faults. globs: src/**/*.{ts,tsx}, server/**/*.{ts,tsx}, ws/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-socket-backpressure-zerocopy-invariant" --- # Bun 1.2 Kernel Socket Backpressure & Zero-Copy WebSocket Stream Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded WebSocket chunk streaming and ad-hoc Buffer allocations without socket drainage coordination causing native heap runaway. ## System Constraints You are a Principal Engineer enforcing Bun 1.2 Kernel Socket Backpressure & Zero-Copy WebSocket Stream Invariants. Mandate strict adherence to ws.getBufferedAmount() gating, drain lifecycle management, and preallocated typed array recycling across all WebSocket streaming loops. Ban fire-and-forget send() operations on streams without upstream backpressure propagation. ## Strict Guidelines - Engineers MUST ALWAYS inspect ws.getBufferedAmount() before dispatching binary payloads across Bun WebSocket connections. - Engineers MUST pause upstream ReadableStream controllers or async iterators when ws.getBufferedAmount() exceeds the defined HIGH_WATER_MARK (e.g., 1MB). - Engineers MUST implement the server-level 'drain(ws)' WebSocket lifecycle handler to resume paused upstream producers once socket buffers flush below LOW_WATER_MARK. - Engineers MUST NOT allocate ephemeral Buffer or Uint8Array instances per message inside streaming hot paths; reusable memory pools or slice-free ArrayBuffer views MUST be employed. - Code SHOULD leverage Bun-native zero-copy serialization mechanisms when transferring binary payloads to avoid JavaScript Core heap-to-native buffer duplication. - Services MUST immediately terminate slow or unresponsive client connections whose buffered amount continues to exceed MAXIMUM_BACKLOG threshold after backpressure application. - Components NEVER execute unbounded 'for await' stream iterations directly pushing to 'ws.send()' without explicit drain synchronization. ## Bad vs Good Implementations ### High-Throughput WebSocket Streaming with Backpressure and Buffer Recycling #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Iterating an async stream and calling ws.send() unconditionally ignores socket backpressure. If client network latency spikes, native C++ socket buffers in Bun's uWebSockets core grow unbounded outside the JS garbage collector's vision, triggering native OOM SIGKILL panics. It also continuously allocates short-lived Buffer objects, leading to severe GC thrashing. ```typescript import { serve, type ServerWebSocket } from 'bun'; interface SessionData { streamId: string; } serve<SessionData>({ websocket: { async message(ws: ServerWebSocket<SessionData>, message) { const upstream = getTelemetryStream(ws.data.streamId); // CRITICAL ANTI-PATTERN: Fire-and-forget streaming // Allocates new buffers on every tick and ignores native kernel socket backpressure. for await (const telemetryRecord of upstream) { const payload = Buffer.from(JSON.stringify(telemetryRecord)); ws.send(payload, true); } }, open(ws) { console.log('Client connected:', ws.remoteAddress); } }, port: 8080 }); async function* getTelemetryStream(id: string) { while (true) { yield { id, timestamp: Date.now(), metrics: [1.2, 3.4, 5.6] }; } } ``` #### Production Standard (Correct) > **Standard**: Enforces strict backpressure using Bun's ws.getBufferedAmount() and the native drain(ws) callback. Upstream stream iteration yields execution when the socket buffer crosses HIGH_WATER_MARK_BYTES and deterministically resumes only when drained below LOW_WATER_MARK_BYTES. Allocations are eliminated via an invariant static ArrayBuffer view recycling pattern. ```typescript import { serve, type ServerWebSocket } from 'bun'; interface SessionData { streamId: string; isPaused: boolean; resumeProducer?: () => void; } const HIGH_WATER_MARK_BYTES = 1024 * 1024; // 1 MB const LOW_WATER_MARK_BYTES = 256 * 1024; // 256 KB const POOL_SIZE_BYTES = 64 * 1024; // Pre-allocated chunk buffer const sharedBufferPool = new Uint8Array(POOL_SIZE_BYTES); serve<SessionData>({ websocket: { async message(ws: ServerWebSocket<SessionData>) { const upstream = getTelemetryStream(ws.data.streamId); for await (const chunkLength of upstream) { // Zero-copy binary view recycling from static buffer pool const binaryView = sharedBufferPool.subarray(0, chunkLength); // Inspect kernel-level pending socket buffer size if (ws.getBufferedAmount() > HIGH_WATER_MARK_BYTES) { ws.data.isPaused = true; await new Promise<void>((resolve) => { ws.data.resumeProducer = resolve; }); } const sendStatus = ws.send(binaryView, true); if (sendStatus === -1) { ws.close(1011, 'Socket write failure'); break; } } }, drain(ws: ServerWebSocket<SessionData>) { // Invoked by Bun when the kernel socket drains below kernel threshold if (ws.data.isPaused && ws.getBufferedAmount() <= LOW_WATER_MARK_BYTES) { ws.data.isPaused = false; if (ws.data.resumeProducer) { const resume = ws.data.resumeProducer; ws.data.resumeProducer = undefined; resume(); } } }, open(ws: ServerWebSocket<SessionData>) { ws.data.isPaused = false; }, close(ws: ServerWebSocket<SessionData>) { if (ws.data.resumeProducer) { ws.data.resumeProducer(); ws.data.resumeProducer = undefined; } } }, port: 8080 }); async function* getTelemetryStream(id: string): AsyncGenerator<number> { while (true) { // Serialize deterministically into sharedBufferPool without allocating const bytesWritten = serializeTelemetryDirect(id, sharedBufferPool); yield bytesWritten; } } function serializeTelemetryDirect(id: string, target: Uint8Array): number { const view = new DataView(target.buffer, target.byteOffset, target.byteLength); view.setFloat64(0, Date.now(), true); return 8; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Kernel Socket Backpressure & Zero-Copy WebSocket Stream Standard

Bun 1.2 Kernel Socket Backpressure & Zero-Copy WebSocket Stream Standard defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic TCP buffer drainage thresholds and binary chunk recycling across high-throughput Bun WebSocket server connections. Mandates explicit inspection of ws.getBufferedAmount() combined with reactive drain callbacks to prevent native kernel-buffer saturation and process-level out-of-memory cascading faults. 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 WebSocket chunk streaming and ad-hoc Buffer allocations without socket drainage coordination causing native heap runaway. 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 WebSocket chunk streaming and ad-hoc Buffer allocations without socket drainage coordination causing native heap runaway.	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 inspect ws.getBufferedAmount() before dispatching binary payloads across Bun WebSocket connections.

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.