Architectural Invariant Design: Bun 1.2 TCP Zero-Copy Backpressure and Socket Drain Lifecycle Enforcement
Bun 1.2 TCP Zero-Copy Backpressure and Socket Drain Lifecycle Enforcement defines an industrial-grade behavioral standard for backend engineering. Mandates strict handling of TCP socket backpressure in Bun 1.2+ runtimes by evaluating socket.write() return codes and synchronizing with the asynchronous drain lifecycle. Bypassing backpressure checks during high-throughput streams causes unmanaged native heap accumulation in Bun worker runtimes, leading to silent latency degradation and resident set size (RSS) out-of-memory crashes. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.
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 TCP Sockets Without Drain Lifecycle Flow Control | 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. |
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 the return value of `socket.write(chunk)` to verify whether the entire payload was consumed by the underlying OS kernel buffer.
Engineers MUST ALWAYS inspect the return value of `socket.write(chunk)` to verify whether the entire payload was consumed by the underlying OS kernel buffer.
Engineers MUST pause upstream async iterators, file reads, or message consumers immediately when `socket.write()` indicates that data has been queued internally (i.e. returns false or partial byte length).
Engineers MUST pause upstream async iterators, file reads, or message consumers immediately when `socket.write()` indicates that data has been queued internally (i.e. returns false or partial byte length).
Code MUST bind the socket's `drain(socket)` lifecycle callback to resume paused streaming pipelines or resolve pending backpressure promises.
Code MUST bind the socket's `drain(socket)` lifecycle callback to resume paused streaming pipelines or resolve pending backpressure promises.
Services MUST clean up pending drain resolvers and drop buffered references when the socket triggers `close(socket)` or `error(socket, err)` to prevent orphaned promise leaks.
Services MUST clean up pending drain resolvers and drop buffered references when the socket triggers `close(socket)` or `error(socket, err)` to prevent orphaned promise leaks.
Engineers MUST NOT continuously write binary chunks inside an unthrottled `for-await` loop without awaiting drain release, as native memory queues will expand without triggering JavaScript garbage collection.
Engineers MUST NOT continuously write binary chunks inside an unthrottled `for-await` loop without awaiting drain release, as native memory queues will expand without triggering JavaScript garbage collection.
Components NEVER instantiate unbounded in-memory array buffers as ad-hoc write queues when Bun's native write buffer signals saturation.
Components NEVER instantiate unbounded in-memory array buffers as ad-hoc write queues when Bun's native write buffer signals saturation.
Frequently Asked Technical Questions
Common questions developers face when configuring AI coding assistants for this stack:
Q:Why is Bun 1.2 TCP Zero-Copy Backpressure and Socket Drain Lifecycle Enforcement critical for AI coding assistants?
Mandates strict handling of TCP socket backpressure in Bun 1.2+ runtimes by evaluating socket.write() return codes and synchronizing with the asynchronous drain lifecycle. Bypassing backpressure checks during high-throughput streams causes unmanaged native heap accumulation in Bun worker runtimes, leading to silent latency degradation and resident set size (RSS) out-of-memory crashes. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.
Q:How does adopting this rule prevent AI hallucinations?
This rule explicitly declares what the AI must avoid (Unchecked Fire-and-Forget Streaming Over TCP Sockets Without Drain Lifecycle Flow Control) 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.