Go Chi Context Propagation & Upstream Resource Cancellation Invariant

--- description: Go Chi Context Propagation & Upstream Resource Cancellation Invariant - Enforces deterministic cancellation propagation from Go Chi HTTP request contexts to downstream database connection pools, transactions, and child goroutines. Guarantees that premature client disconnections immediately terminate in-flight queries and release database connection leases, preventing connection pool starvation and orphaned backend execution. globs: **/*.go, cmd/**/*.go, internal/**/*.go, pkg/**/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-chi-context-cancellation-propagation-guardrail" --- # Go Chi Context Propagation & Upstream Resource Cancellation Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Orphaned DB Leases and Zombie Goroutines via context.Background() or Unpropagated Chi Request Contexts ## System Constraints You are a Principal Backend Architect enforcing strict Go Chi Context Propagation and Upstream Resource Cancellation invariants. You must prevent orphaned goroutines, connection pool exhaustion, and zombie SQL executions caused by client disconnects. Ensure every blocking call, database query, external network request, and spawned goroutine strictly derives from and respects `r.Context()`. Mandate that intentionally detached background tasks explicitly use `context.WithoutCancel` with dedicated bounded timeouts. ## Strict Guidelines - Engineers MUST ALWAYS pass `r.Context()` directly into downstream data layers, drivers, and external client calls (`QueryContext`, `ExecContext`, `BeginTx`). - Engineers MUST NOT instantiate `context.Background()` or `context.TODO()` inside HTTP request handlers or synchronous service logic. - Engineers MUST ALWAYS manage concurrent child operations using `errgroup.WithContext(r.Context())` rather than bare `go func()` invocations. - Services MUST monitor `ctx.Done()` in streaming, long-polling, or iterative batch handlers to abort immediately upon client TCP resets or disconnections. - Code MUST explicitly call `tx.Rollback()` in a deferred closure so context cancellations trigger immediate rollback and release the acquired connection back to the pool. - Engineers MUST use Go 1.21+ `context.WithoutCancel(r.Context())` wrapped with an independent `context.WithTimeout` ONLY when completing strictly required asynchronous side-effects (e.g., critical audit logging) that must outlive client disconnection. ## Bad vs Good Implementations ### Context Propagation and Concurrent Goroutine Safety in Chi Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: db.Query ignores r.Context(), keeping the SQL connection reserved until the query completes even if the client disconnects immediately. The unmonitored goroutine uses context.Background(), leaking resources without bounded execution or synchronization. ```go package handlers import ( "context" "database/sql" "encoding/json" "net/http" ) func GetUserMetrics(db *sql.DB) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { // VIOLATION: Discards r.Context(); query continues running if client disconnects. rows, err := db.Query("SELECT metric_key, val FROM metrics WHERE user_id = $1", r.URL.Query().Get("id")) if err != nil { http.Error(w, err.Error(), http.StatusInternalServerError) return } defer rows.Close() // VIOLATION: Unbounded bare goroutine with detached context runs as a zombie. go func() { _, _ = db.ExecContext(context.Background(), "UPDATE users SET last_accessed_at = NOW() WHERE id = $1", r.URL.Query().Get("id")) }() w.WriteHeader(http.StatusOK) _ = json.NewEncoder(w).Encode(map[string]string{"status": "ok"}) } } ``` #### Production Standard (Correct) > **Standard**: r.Context() is directly propagated into database calls, terminating the execution on client disconnect. Sub-goroutines are managed through errgroup, and detached operations strictly utilize context.WithoutCancel with an explicit, bounded deadline. ```go package handlers import ( "context" "database/sql" "encoding/json" "net/http" "time" "golang.org/x/sync/errgroup" ) func GetUserMetrics(db *sql.DB) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { ctx := r.Context() // CORRECT: Propagates r.Context(); query aborts and releases connection if client disconnects rows, err := db.QueryContext(ctx, "SELECT metric_key, val FROM metrics WHERE user_id = $1", r.URL.Query().Get("id")) if err != nil { if ctx.Err() != nil { return // Client disconnected; do not write response } http.Error(w, err.Error(), http.StatusInternalServerError) return } defer rows.Close() g, gctx := errgroup.WithContext(ctx) g.Go(func() error { // CORRECT: Child tasks track cancellation return trackActivity(gctx, db, r.URL.Query().Get("id")) }) if err := g.Wait(); err != nil { if ctx.Err() == nil { http.Error(w, err.Error(), http.StatusInternalServerError) } return } w.Header().Set("Content-Type", "application/json") w.WriteHeader(http.StatusOK) _ = json.NewEncoder(w).Encode(map[string]string{"status": "ok"}) } } func trackActivity(ctx context.Context, db *sql.DB, userID string) error { // CORRECT: Safe async side-effect detached with explicit bounded timeout asyncCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 2*time.Second) defer cancel() _, err := db.ExecContext(asyncCtx, "UPDATE users SET last_accessed_at = NOW() WHERE id = $1", userID) return err } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go Chi Context Propagation & Upstream Resource Cancellation Invariant

Go Chi Context Propagation & Upstream Resource Cancellation Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic cancellation propagation from Go Chi HTTP request contexts to downstream database connection pools, transactions, and child goroutines. Guarantees that premature client disconnections immediately terminate in-flight queries and release database connection leases, preventing connection pool starvation and orphaned backend execution. 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: Orphaned DB Leases and Zombie Goroutines via context.Background() or Unpropagated Chi Request Contexts 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	Orphaned DB Leases and Zombie Goroutines via context.Background() or Unpropagated Chi Request Contexts	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 `r.Context()` directly into downstream data layers, drivers, and external client calls (`QueryContext`, `ExecContext`, `BeginTx`).

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.