Go Chi HTTP/2 Stream Context Cancellation & Slab Reallocation Invariant

--- description: Go Chi HTTP/2 Stream Context Cancellation & Slab Reallocation Invariant - Enforces strict context-cancellation propagation and deterministic slab buffer cleanup for long-lived HTTP/2 streams handled by Chi. Prevents unbounded goroutine accumulation, context cancellation masking, and sync.Pool buffer fragmentation or cross-stream corruption when multiplexed clients prematurely disconnect. globs: **/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-chi-h2-stream-cancellation-slab-invariant" --- # Go Chi HTTP/2 Stream Context Cancellation & Slab Reallocation Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Ignoring r.Context().Done() or returning dirty sync.Pool byte slabs across prematurely aborted HTTP/2 stream flushes ## System Constraints You are a Principal Systems Engineer and Low-Latency Go Architect enforcing Go Chi HTTP/2 Stream Context Cancellation and Slab Buffer Reallocation invariants. Mandate non-blocking context cancellation checks, explicit http.Flusher handling, strict slab resetting before sync.Pool return, and zero goroutine leakage on stream teardown. ## Strict Guidelines - Engineers MUST ALWAYS verify that the http.ResponseWriter implements http.Flusher and listen to r.Context().Done() on every stream iteration or channel read. - Engineers MUST NEVER return byte slices or chunk buffers to a sync.Pool without resetting their slice bounds to zero length (buf[:0]) and verifying that the buffer was not corrupted or grown beyond the max slab limit. - Engineers MUST NEVER spin up decoupled background worker goroutines referencing the request context without binding their lifetimes to an explicit errgroup or sync.WaitGroup that terminates deterministically upon r.Context().Done(). - Code MUST explicitly drop oversized slab buffers exceeding maximum capacity (e.g., > 64KiB) instead of recycling them into sync.Pool to eliminate memory fragmentation under bursty payloads. - Handlers MUST ensure defer pool.Put(buf) operations are guarded against double-release and are executed in the same call frame, even when stream writes fail due to client RST_STREAM. ## Bad vs Good Implementations ### HTTP/2 Server-Sent Events / Chunked Streaming Handler with Slab Buffer Lifecycle #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The goroutine generating data never observes r.Context().Done(), causing permanent goroutine leaks on client disconnection. The sync.Pool buffer is appended to without resetting slice length (buf[:0]), causing unbounded slice reallocation, heap escape, and corrupted data reuse across multiplexed HTTP/2 streams. ```go package handlers import ( "fmt" "net/http" "sync" "time" ) var badPool = sync.Pool{ New: func() any { return make([]byte, 4096) }, } func BadStreamHandler(w http.ResponseWriter, r *http.Request) { flusher, _ := w.(http.Flusher) ch := make(chan []byte) // Leak: Unbound goroutine continues running after client disconnects go func() { for { time.Sleep(100 * time.Millisecond) ch <- []byte("stream payload") } }() for data := range ch { slab := badPool.Get().([]byte) // Flaw: Slab buffer not reset, potentially grows unbounded slab = append(slab, data...) w.Write(slab) flusher.Flush() // Leak/Corruption: Returning mutated slab without reset; missing context exit badPool.Put(slab) } } ``` #### Production Standard (Correct) > **Standard**: The handler actively listens to ctx.Done() to break stream writes immediately upon client RST_STREAM. The slab buffer uses sync.Pool with an upper capacity boundary threshold (64KiB) to prevent memory fragmentation, resets byte lengths deterministically before and after usage via defer, and gracefully shuts down child producer goroutines. ```go package handlers import ( "bytes" "context" "errors" "net/http" "sync" ) const maxSlabCapacity = 64 * 1024 var slabPool = sync.Pool{ New: func() any { return bytes.NewBuffer(make([]byte, 0, 4096)) }, } func GoodStreamHandler(w http.ResponseWriter, r *http.Request) { flusher, ok := w.(http.Flusher) if !ok { http.Error(w, "Streaming unsupported", http.StatusBadRequest) return } w.Header().Set("Content-Type", "text/event-stream") w.Header().Set("Cache-Control", "no-cache") w.Header().Set("X-Accel-Buffering", "no") ctx := r.Context() dataCh := make(chan []byte, 1) go produceStreamData(ctx, dataCh) for { select { case <-ctx.Done(): return case chunk, open := <-dataCh: if !open { return } if err := writeSlabChunk(w, flusher, chunk); err != nil { return } } } } func writeSlabChunk(w http.ResponseWriter, flusher http.Flusher, chunk []byte) error { buf := slabPool.Get().(*bytes.Buffer) buf.Reset() defer func() { if buf.Cap() <= maxSlabCapacity { buf.Reset() slabPool.Put(buf) } }() buf.WriteString("data: ") buf.Write(chunk) buf.WriteString("\n\n") if _, err := w.Write(buf.Bytes()); err != nil { return errors.Join(err, context.Canceled) } flusher.Flush() return nil } func produceStreamData(ctx context.Context, out chan<- []byte) { defer close(out) for { select { case <-ctx.Done(): return default: // Emit simulated payload out <- []byte("stream payload") return } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go Chi HTTP/2 Stream Context Cancellation & Slab Reallocation Invariant

Go Chi HTTP/2 Stream Context Cancellation & Slab Reallocation Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces strict context-cancellation propagation and deterministic slab buffer cleanup for long-lived HTTP/2 streams handled by Chi. Prevents unbounded goroutine accumulation, context cancellation masking, and sync.Pool buffer fragmentation or cross-stream corruption when multiplexed clients prematurely disconnect. 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: Ignoring r.Context().Done() or returning dirty sync.Pool byte slabs across prematurely aborted HTTP/2 stream flushes 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	Ignoring r.Context().Done() or returning dirty sync.Pool byte slabs across prematurely aborted HTTP/2 stream flushes	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 verify that the http.ResponseWriter implements http.Flusher and listen to r.Context().Done() on every stream iteration or channel read.

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.