Go Chi v5 HTTP/3 Stream Lifecycle Zero-Escape Context Barrier

--- description: Go Chi v5 HTTP/3 Stream Lifecycle Zero-Escape Context Barrier - Enforces strict lifecycle boundaries between multiplexed QUIC/HTTP/3 stream contexts and asynchronous operations in Go Chi v5 services. Eliminates memory corruption, heap escapes, and premature cancellations caused by passing request contexts or pooled sync.Pool buffers across stream boundary horizons. globs: **/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-chi-http3-zero-escape-context-barrier" --- # Go Chi v5 HTTP/3 Stream Lifecycle Zero-Escape Context Barrier > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Escaping Ephemeral QUIC Stream Contexts and Pooled Buffers into Unbounded Background Goroutines ## System Constraints You are a Principal Systems Architect enforcing strict HTTP/3 QUIC stream lifecycle invariants in Go Chi v5 applications. In multiplexed QUIC connections, individual stream cancellations (RST_STREAM) instantly terminate r.Context(), causing immediate aborts and severe data corruption if stream contexts or sync.Pool-allocated memory buffers escape the stream handler stack frame. You must enforce explicit context detachment barriers and strict zero-escape memory semantics. ## Strict Guidelines - Engineers MUST ALWAYS isolate asynchronous operations from the HTTP/3 stream context by constructing an explicit detached context using `context.WithoutCancel()` (Go 1.21+) or an isolated `context.Background()` with a dedicated bounded timeout. - Engineers MUST NOT leak references to `sync.Pool`-allocated request wrappers, Chi context structures (`chi.RouteContext`), or raw byte buffers into background goroutines or long-lived caches. - Code MUST return pooled memory buffers to `sync.Pool` strictly within a `defer` block in the primary request stack frame, guaranteeing zero concurrent reads/writes after stream handler exit. - Services MUST deep-copy or clone any required payload bytes and telemetry baggage before dispatching tasks across goroutine boundaries rather than passing pointers to ephemeral stream buffers. - Components NEVER attach goroutine-spawning hooks to Chi middleware without introducing an explicit context and memory barrier that shields against QUIC stream reset interrupts. ## Bad vs Good Implementations ### Escaping QUIC Stream Context and Pooled Memory vs. Zero-Escape Detached Barrier #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing r.Context() to the background goroutine causes premature cancellation when the QUIC stream closes. Concurrently recycling the pooled buffer inside the goroutine leaks stack pointers to the heap, causes severe data races with subsequent pool acquisitions, and breaks memory safety. ```go package handlers import ( "bytes" "net/http" "sync" "github.com/go-chi/chi/v5" ) var bufPool = sync.Pool{ New: func() any { return new(bytes.Buffer) }, } func AsyncAuditHandler(w http.ResponseWriter, r *http.Request) { buf := bufPool.Get().(*bytes.Buffer) buf.Reset() _, _ = buf.ReadFrom(r.Body) // ANTI-PATTERN: Leaks r.Context() and pooled *bytes.Buffer into goroutine. // In HTTP/3, client stream reset (CANCEL/CANCEL_PUSH) immediately cancels r.Context(). // buf is returned to sync.Pool concurrently while the goroutine reads from it, // triggering data races, heap escapes, and invalid memory writes. go func() { defer bufPool.Put(buf) processAuditRecord(r.Context(), buf.Bytes()) }() w.WriteHeader(http.StatusAccepted) } func processAuditRecord(ctx context.Context, data []byte) { // Fails abruptly if HTTP/3 QUIC stream drops before execution completes } ``` #### Production Standard (Correct) > **Standard**: The pooled buffer is strictly reclaimed on stack unwind via defer, preventing heap escapes. The payload is deep-copied to isolate it from the pool lifecycle, and `context.WithoutCancel()` creates an explicit boundary detached from QUIC stream cancellation. ```go package handlers import ( "bytes" "context" "io" "net/http" "sync" "time" ) var bufPool = sync.Pool{ New: func() any { return new(bytes.Buffer) }, } func AsyncAuditHandler(w http.ResponseWriter, r *http.Request) { buf := bufPool.Get().(*bytes.Buffer) buf.Reset() // Guarantee pooled resource reclamation strictly on stack exit defer bufPool.Put(buf) if _, err := io.Copy(buf, r.Body); err != nil { http.Error(w, "payload read failure", http.StatusBadRequest) return } // ZERO-ESCAPE BARRIER: Deep-copy payload data out of ephemeral pool memory payloadCopy := make([]byte, buf.Len()) copy(payloadCopy, buf.Bytes()) // Establish context barrier detached from volatile HTTP/3 QUIC stream lifecycle detachedCtx, cancel := context.WithTimeout(context.WithoutCancel(r.Context()), 5*time.Second) go func(ctx context.Context, data []byte) { defer cancel() processAuditRecord(ctx, data) }(detachedCtx, payloadCopy) w.WriteHeader(http.StatusAccepted) } func processAuditRecord(ctx context.Context, data []byte) { // Executes deterministically within bounded 5-second deadline regardless of stream state } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go Chi v5 HTTP/3 Stream Lifecycle Zero-Escape Context Barrier

Go Chi v5 HTTP/3 Stream Lifecycle Zero-Escape Context Barrier defines an industrial-grade behavioral standard for backend engineering. Enforces strict lifecycle boundaries between multiplexed QUIC/HTTP/3 stream contexts and asynchronous operations in Go Chi v5 services. Eliminates memory corruption, heap escapes, and premature cancellations caused by passing request contexts or pooled sync.Pool buffers across stream boundary horizons. 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: Escaping Ephemeral QUIC Stream Contexts and Pooled Buffers into Unbounded Background Goroutines 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	Escaping Ephemeral QUIC Stream Contexts and Pooled Buffers into Unbounded Background Goroutines	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 isolate asynchronous operations from the HTTP/3 stream context by constructing an explicit detached context using `context.WithoutCancel()` (Go 1.21+) or an isolated `context.Background()` with a dedicated bounded timeout.

Engineers MUST ALWAYS isolate asynchronous operations from the HTTP/3 stream context by constructing an explicit detached context using `context.WithoutCancel()` (Go 1.21+) or an isolated `context.Background()` with a dedicated bounded timeout.

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.