Bun 1.2 Native S3 Streaming Zero-Copy Backpressure Standard

--- description: Bun 1.2 Native S3 Streaming Zero-Copy Backpressure Standard - Enforces zero-copy stream piping for Bun 1.2 native S3 client uploads to prevent unconstrained V8/JSC heap allocation. Mandates direct linkage between incoming consumer HTTP request bodies or native file streams and native S3 target writers without intermediate JavaScript buffer allocation. globs: src/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-s3-streaming-zero-copy-backpressure-guardrail" --- # Bun 1.2 Native S3 Streaming Zero-Copy Backpressure Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Buffering HTTP Request Payloads into Memory Before Forwarding to S3 Multipart Uploads ## System Constraints You are a Principal Engineer enforcing Bun 1.2 Native S3 Streaming Zero-Copy Backpressure Guardrails. Mandate that incoming HTTP streams and file descriptors are piped directly into Bun's native S3 client without materializing chunks in JavaScript heap memory. ## Strict Guidelines - Engineers MUST ALWAYS pass the raw 'req.body' (ReadableStream) directly into 's3Client.file(key).write()' or 'Bun.write(s3Destination, stream)' to maintain native zero-copy kernel backpressure. - Engineers MUST NOT call 'req.arrayBuffer()', 'req.bytes()', 'req.text()', or 'Buffer.concat()' on incoming payload streams intended for S3 persistence. - Engineers MUST NOT iterate over 'req.body' chunks with 'for await (const chunk of req.body)' when uploading directly to S3. - Services MUST configure multipart part sizes using native 'Bun.S3Client' options rather than manually chunking and buffering arrays in userland JavaScript memory. - Code SHOULD leverage native 'Bun.file()' descriptors when uploading disk files to S3 to bypass userland memory buffers entirely. ## Bad vs Good Implementations ### Direct Zero-Copy HTTP-to-S3 Stream vs Intermediate Heap Buffering #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling 'await req.arrayBuffer()' materializes the entire uploaded file inside the JavaScript runtime heap. Under concurrent uploads, this bypasses TCP backpressure, spikes GC overhead, and causes out-of-memory (OOM) fatal crashes. ```typescript import { S3Client } from "bun"; const s3 = new S3Client({ bucket: process.env.S3_BUCKET!, accessKeyId: process.env.AWS_ACCESS_KEY_ID!, secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!, }); export async function handleUpload(req: Request): Promise<Response> { // ANTI-PATTERN: Pulling entire request into JSC heap buffers // Multiple concurrent large uploads will immediately cause OOM crash const rawData = await req.arrayBuffer(); const destination = s3.file("uploads/asset.bin"); await destination.write(rawData); return new Response("Uploaded", { status: 201 }); } ``` #### Production Standard (Correct) > **Standard**: Passing 'req.body' directly into 'destination.write()' allows Bun's native Zig/C++ runtime to pipe network socket buffers straight into the S3 multipart stream with zero JavaScript heap allocations, pausing incoming socket reads when the S3 upstream slows down. ```typescript import { S3Client } from "bun"; const s3 = new S3Client({ bucket: process.env.S3_BUCKET!, accessKeyId: process.env.AWS_ACCESS_KEY_ID!, secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!, partSize: 5 * 1024 * 1024, // 5MB native multipart chunks }); export async function handleUpload(req: Request): Promise<Response> { if (!req.body) { return new Response("Missing payload body", { status: 400 }); } // PRODUCTION INVARIANT: Direct native streaming pipe // Links client socket read backpressure directly to S3 TLS socket buffers const destination = s3.file("uploads/asset.bin", { type: req.headers.get("content-type") ?? "application/octet-stream", }); await destination.write(req.body); return new Response("Uploaded", { status: 201 }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native S3 Streaming Zero-Copy Backpressure Standard

Bun 1.2 Native S3 Streaming Zero-Copy Backpressure Standard defines an industrial-grade behavioral standard for backend engineering. Enforces zero-copy stream piping for Bun 1.2 native S3 client uploads to prevent unconstrained V8/JSC heap allocation. Mandates direct linkage between incoming consumer HTTP request bodies or native file streams and native S3 target writers without intermediate JavaScript buffer allocation. 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: Buffering HTTP Request Payloads into Memory Before Forwarding to S3 Multipart Uploads 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	Buffering HTTP Request Payloads into Memory Before Forwarding to S3 Multipart Uploads	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 the raw 'req.body' (ReadableStream) directly into 's3Client.file(key).write()' or 'Bun.write(s3Destination, stream)' to maintain native zero-copy kernel backpressure.

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.