Go Chi HTTP/3 Connection Migration and Context Cancellation Propagation

--- description: Go Chi HTTP/3 Connection Migration and Context Cancellation Propagation - Guarantees immediate propagation of cancellation signals and QUIC stream teardowns down to database transactions and worker routines during rapid mobile network migrations. Enforces strict binding to r.Context() and prevents detached context leakage when underlying HTTP/3 UDP 4-tuples shift or fail path validation. globs: cmd/**/*.go, internal/**/*.go, pkg/**/*.go, **/*handler*.go, **/*router*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-chi-http3-connection-migration-context-cancellation-invariants" --- # Go Chi HTTP/3 Connection Migration and Context Cancellation Propagation > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Decoupled Context Lifecycles and Goroutine Leaks During QUIC Stream Resets and Network Handoffs ## System Constraints You are a Principal Backend Architect enforcing strict Go Chi HTTP/3 connection migration and context cancellation propagation invariants. Under HTTP/3 (QUIC), mobile clients frequently migrate across UDP 4-tuples (e.g., Wi-Fi to 5G) or abort streams when path validation fails. You must ensure that HTTP request contexts immediately abort downstream database queries, RPCs, and IO operations upon stream termination, preventing zombie transactions, memory leaks, and goroutine starvation. ## Strict Guidelines - Engineers MUST ALWAYS propagate r.Context() directly to all downstream database calls, redis pipelines, and outbound HTTP/RPC requests without stripping cancellation signals. - Engineers MUST NOT spawn detached background goroutines using context.Background() or context.TODO() inside Chi handler chains for client-requested workloads. - Streaming endpoints (SSE, chunked data, WebTransport) MUST monitor r.Context().Done() concurrently with send operations to detect broken QUIC streams immediately. - Middleware chains MUST NEVER create child contexts with new cancellation roots that swallow or fail to link to the parent request's Done channel. - Database transactions MUST be initiated using db.BeginTx(r.Context(), opts) so that any QUIC stream reset or network handoff failure triggers an automatic context rollback. - Services MUST ensure that response flushers and chunked writers check for context errors before every write to avoid panics on dead QUIC stream handles. ## Bad vs Good Implementations ### Database Transaction and Streaming Under HTTP/3 Chi Router #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using context.Background() detaches the handler from the HTTP/3 request lifecycle. If a mobile device migrates networks and the QUIC stream is reset by peer, the database transaction and lock remain active as zombie processes, exhausting connection pools and causing contention. ```go package handler import ( "context" "database/sql" "net/http" "time" "github.com/go-chi/chi/v5" ) func MountRoutes(r chi.Router, db *sql.DB) { r.Post("/process-data", func(w http.ResponseWriter, r *http.Request) { // ANTI-PATTERN: Detaching context using Background() prevents cancellation // when the client experiences a failed HTTP/3 connection migration. ctx := context.Background() tx, err := db.BeginTx(ctx, nil) if err != nil { http.Error(w, err.Error(), http.StatusInternalServerError) return } defer tx.Rollback() // Spawning unbounded goroutine uncoupled from r.Context(). // If the QUIC stream resets or client drops, this goroutine and lock persist indefinitely. go func() { _, _ = tx.ExecContext(ctx, "UPDATE account_balances SET locked = true WHERE id = ?", 1234) time.Sleep(5 * time.Second) // Simulating long operation _ = tx.Commit() }() w.WriteHeader(http.StatusAccepted) }) } ``` #### Production Standard (Correct) > **Standard**: Binding db.BeginTx and tx.ExecContext directly to r.Context() guarantees that QUIC stream resets or aborted migrations immediately roll back transactions, release row locks, and avoid leaking database connections. ```go package handler import ( "database/sql" "errors" "net/http" "github.com/go-chi/chi/v5" ) func MountRoutes(r chi.Router, db *sql.DB) { r.Post("/process-data", func(w http.ResponseWriter, r *http.Request) { ctx := r.Context() // INVARIANT: Bind transaction directly to r.Context(). // If the QUIC connection migration fails or stream resets, ctx.Done() cancels tx. tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelReadCommitted}) if err != nil { http.Error(w, err.Error(), http.StatusInternalServerError) return } defer tx.Rollback() // Safe no-op if successfully committed or canceled // Execute synchronously or bounded within the request context _, err = tx.ExecContext(ctx, "UPDATE account_balances SET locked = true WHERE id = ?", 1234) if err != nil { if errors.Is(ctx.Err(), context.Canceled) { // Client disconnected during HTTP/3 migration; exit cleanly return } http.Error(w, err.Error(), http.StatusInternalServerError) return } if err := tx.Commit(); err != nil { if !errors.Is(ctx.Err(), context.Canceled) { http.Error(w, err.Error(), http.StatusInternalServerError) } return } w.WriteHeader(http.StatusOK) }) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go Chi HTTP/3 Connection Migration and Context Cancellation Propagation

Go Chi HTTP/3 Connection Migration and Context Cancellation Propagation defines an industrial-grade behavioral standard for backend engineering. Guarantees immediate propagation of cancellation signals and QUIC stream teardowns down to database transactions and worker routines during rapid mobile network migrations. Enforces strict binding to r.Context() and prevents detached context leakage when underlying HTTP/3 UDP 4-tuples shift or fail path validation. 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: Decoupled Context Lifecycles and Goroutine Leaks During QUIC Stream Resets and Network Handoffs 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	Decoupled Context Lifecycles and Goroutine Leaks During QUIC Stream Resets and Network Handoffs	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 propagate r.Context() directly to all downstream database calls, redis pipelines, and outbound HTTP/RPC requests without stripping cancellation signals.

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.