Bun 1.2 Native WebSocket Backpressure High-Watermark Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Unchecked Fire-and-Forget Streaming Over Saturated Bun WebSockets Inducing Native Heap Exhaustion) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Bun 1.2 Native WebSocket Backpressure High-Watermark Standard

--- description: Bun 1.2 Native WebSocket Backpressure High-Watermark Standard - Enforces strict backpressure monitoring on Bun native WebSockets using `ws.getBufferedAmount()` and the return value of `ws.send()`. Failure to handle backpressure allows slow or malicious consumers to force unbounded C++ heap buffer allocations in uWebSockets, causing process-level Out-Of-Memory (OOM) crashes under sustained broadcast loads. globs: src/**/*.{ts,js,mjs}, server/**/*.{ts,js,mjs}, app/**/*.{ts,js,mjs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-websocket-backpressure-high-watermark-standard" --- # Bun 1.2 Native WebSocket Backpressure High-Watermark Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unchecked Fire-and-Forget Streaming Over Saturated Bun WebSockets Inducing Native Heap Exhaustion ## System Constraints You are a Principal Engineer enforcing the Bun 1.2 Native WebSocket Backpressure High-Watermark Standard. Mandate native uWebSockets buffer checks on every outbound frame, prevent unbounded memory retention during push-based fan-outs, and guarantee deterministic connection shedding or producer throttling when client buffers breach high-watermark thresholds. ## Strict Guidelines - Engineers MUST ALWAYS evaluate the byte return value of `ws.send(data)` or inspect `ws.getBufferedAmount()` before sending subsequent payloads in high-throughput or batch emission loops. - Engineers MUST NOT continuously invoke `ws.send()` if `ws.getBufferedAmount()` exceeds the defined high-watermark threshold (default maximum: 512 KiB per client). - Services MUST implement native drain handlers (`drain(ws)`) in Bun's `WebSocketHandler` to resume paused upstream data streams or pull-based iterators when client buffers drop below the low-watermark threshold. - Services MUST terminate saturated or unresponsive connections with explicit close codes (`ws.close(1008, 'Policy Violation: Exceeded Backpressure Threshold')`) when buffers breach absolute emergency limits. - Components NEVER buffer unbounded outbound message queues in JavaScript memory as a naive workaround for backpressure; producers MUST pause at the source. ## Bad vs Good Implementations ### Naive Broadcast Fan-out vs. Backpressure-Aware Streaming with Watermarks #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Ignoring the return value of ws.send and omitting ws.getBufferedAmount() causes outbound payloads to accumulate indefinitely in native memory buffers when clients experience network jitter or slow consumers fail to acknowledge TCP windows, leading to an unrecoverable SIGKILL (OOM). ```typescript import { ServerWebSocket } from 'bun'; interface ClientData { id: string; } // ANTI-PATTERN: Fire-and-forget broadcast ignoring native C++ buffer saturation. // If a client on a slow connection lags, uWebSockets buffers continuously in the native heap. export function broadcastMetrics(clients: Set<ServerWebSocket<ClientData>>, payload: Uint8Array): void { for (const ws of clients) { // ws.send returns the number of bytes sent or buffered, but is ignored here ws.send(payload); } } ``` #### Production Standard (Correct) > **Standard**: Checks ws.getBufferedAmount() before and during writes, sets an explicit high-watermark to mark backpressured clients, triggers native connection termination if the hard threshold is breached, and implements the native drain() lifecycle callback to safely resume data dispatch. ```typescript import { ServerWebSocket, WebSocketHandler } from 'bun'; const HIGH_WATERMARK_BYTES = 512 * 1024; // 512 KiB const HARD_LIMIT_BYTES = 2 * 1024 * 1024; // 2 MiB interface ClientState { id: string; isPaused: boolean; } export function safeSend(ws: ServerWebSocket<ClientState>, data: Uint8Array | string): boolean { const currentBuffered = ws.getBufferedAmount(); if (currentBuffered > HARD_LIMIT_BYTES) { // Saturated beyond recovery; terminate socket to preserve process integrity ws.close(1008, 'Policy Violation: Native buffer overflow'); return false; } if (currentBuffered > HIGH_WATERMARK_BYTES) { ws.data.isPaused = true; return false; // Backpressure engaged: caller must pause feeding this client } const sentOrBuffered = ws.send(data); if (sentOrBuffered < 0) { return false; // Socket dropping or failed } return true; } export const websocketHandlers: WebSocketHandler<ClientState> = { open(ws) { ws.data = { id: crypto.randomUUID(), isPaused: false }; }, message(ws, message) { // Handle inbound frames }, drain(ws) { // Native hook called when uWebSockets flushes buffered queue below low-watermark if (ws.data.isPaused && ws.getBufferedAmount() < HIGH_WATERMARK_BYTES / 2) { ws.data.isPaused = false; // Upstream pull-loop or queue can resume pumping messages here } }, close(ws, code, message) { ws.data.isPaused = false; } }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native WebSocket Backpressure High-Watermark Standard

Bun 1.2 Native WebSocket Backpressure High-Watermark Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict backpressure monitoring on Bun native WebSockets using `ws.getBufferedAmount()` and the return value of `ws.send()`. Failure to handle backpressure allows slow or malicious consumers to force unbounded C++ heap buffer allocations in uWebSockets, causing process-level Out-Of-Memory (OOM) crashes under sustained broadcast loads. 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: Unchecked Fire-and-Forget Streaming Over Saturated Bun WebSockets Inducing Native Heap Exhaustion 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	Unchecked Fire-and-Forget Streaming Over Saturated Bun WebSockets Inducing Native Heap Exhaustion	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 evaluate the byte return value of `ws.send(data)` or inspect `ws.getBufferedAmount()` before sending subsequent payloads in high-throughput or batch emission loops.

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.