Go Chi Arena-Backed Request Context Lifecycle Invariant

--- description: Go Chi Arena-Backed Request Context Lifecycle Invariant - Enforces strict scope-bound memory arena reclamation within Go Chi HTTP middleware pipelines. Forbids arena-allocated pointers from escaping synchronous request boundaries into asynchronous goroutines, eradicating use-after-free memory corruption in zero-allocation services. globs: **/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-chi-arena-request-context-lifecycle" --- # Go Chi Arena-Backed Request Context Lifecycle Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Capturing Arena-Allocated Pointers in Asynchronous Goroutines After Deferred Middleware Arena Reclamation ## System Constraints You are a Principal Systems Architect enforcing strict memory safety and arena allocation lifecycles in Go Chi microservices. Your directive is to guarantee that no pointer allocated within a request-scoped arena escapes into asynchronous goroutines or outlives the synchronous execution lifecycle of the Chi middleware stack. ## Strict Guidelines - Engineers MUST ALWAYS free request-scoped arenas exclusively within the originating Chi middleware via a deferred call after the synchronous handler chain returns. - Engineers MUST NOT pass pointers allocated within an arena into un-joined goroutines, fire-and-forget channel sends, or background task queues. - Code MUST deep-copy (promote) any arena-allocated struct to standard Go runtime heap memory prior to dispatching background operations or asynchronous processing. - Middleware injecting an arena into http.Request.Context MUST provide a type-safe accessor that enforces heap-promotion semantics when crossing goroutine boundaries. - Services MUST compile and test with '-race' and memory sanitizer flags enabled to surface cross-goroutine use-after-free and data races during arena reuse. - Components NEVER store long-lived pointers (e.g., package-level caches, global sync.Pool elements) referencing memory backed by an arena marked for impending reclamation. ## Bad vs Good Implementations ### Arena Scope Leakage in Chi Middleware vs Heap-Promoted Async Dispatch #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The arena is allocated per-request in the Chi middleware and deferred to Free() when ServeHTTP finishes. Spawning an un-joined goroutine in AsyncHandler captures the arena-allocated *UserSession pointer. When the HTTP request completes, Free() marks arena memory as invalid/reusable, leading to non-deterministic silent memory corruption or panic (use-after-free) in the background worker. ```go package middleware import ( "arena" "net/http" "github.com/go-chi/chi/v5" ) type UserSession struct { UserID string Roles []string } func ArenaMiddleware(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { memArena := arena.NewArena() // VIOLATION: Arena is freed immediately after handler returns, // triggering a use-after-free in any asynchronous goroutine capturing arena ptrs. defer memArena.Free() sess := arena.New[UserSession](memArena) sess.UserID = r.Header.Get("X-User-ID") ctx := WithSession(r.Context(), sess) next.ServeHTTP(w, r.WithContext(ctx)) }) } func AsyncHandler(w http.ResponseWriter, r *http.Request) { sess := GetSession(r.Context()) // VIOLATION: Passing sess (arena-backed pointer) to a background goroutine. // memArena.Free() will invalidate this memory while the goroutine runs. go func() { logAuditTrail(sess.UserID) }() w.WriteHeader(http.StatusOK) } ``` #### Production Standard (Correct) > **Standard**: The handler decouples background concurrency from the request arena lifecycle by explicitly promoting arena-allocated data to the Go runtime heap via PromoteToHeap() before spawning the goroutine. The deferred memArena.Free() cleans up synchronously without corrupting background readers. ```go package middleware import ( "arena" "net/http" "github.com/go-chi/chi/v5" ) type UserSession struct { UserID string Roles []string } // PromoteToHeap creates a deep, standard Go heap-allocated copy of the session. func (s *UserSession) PromoteToHeap() UserSession { rolesCopy := make([]string, len(s.Roles)) copy(rolesCopy, s.Roles) return UserSession{ UserID: s.UserID, Roles: rolesCopy, } } func ArenaMiddleware(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { memArena := arena.NewArena() defer memArena.Free() sess := arena.New[UserSession](memArena) sess.UserID = r.Header.Get("X-User-ID") ctx := WithSession(r.Context(), sess) next.ServeHTTP(w, r.WithContext(ctx)) }) } func AsyncHandler(w http.ResponseWriter, r *http.Request) { sess := GetSession(r.Context()) // INVARIANT: Deep-copy arena-allocated values to the standard heap before spawning. heapSafeSession := sess.PromoteToHeap() go func(s UserSession) { logAuditTrail(s.UserID) }(heapSafeSession) w.WriteHeader(http.StatusOK) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go Chi Arena-Backed Request Context Lifecycle Invariant

Go Chi Arena-Backed Request Context Lifecycle Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces strict scope-bound memory arena reclamation within Go Chi HTTP middleware pipelines. Forbids arena-allocated pointers from escaping synchronous request boundaries into asynchronous goroutines, eradicating use-after-free memory corruption in zero-allocation services. 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: Capturing Arena-Allocated Pointers in Asynchronous Goroutines After Deferred Middleware Arena Reclamation 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	Capturing Arena-Allocated Pointers in Asynchronous Goroutines After Deferred Middleware Arena Reclamation	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 free request-scoped arenas exclusively within the originating Chi middleware via a deferred call after the synchronous handler chain returns.

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.