Go Chi HTTP/2 & HTTP/3 Context Propagation and Subtree Cancellation Guardrail

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Orphan Goroutines and Context Severance During HTTP/2 Client Transport Disconnects) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Go Chi HTTP/2 & HTTP/3 Context Propagation and Subtree Cancellation Guardrail

--- description: Go Chi HTTP/2 & HTTP/3 Context Propagation and Subtree Cancellation Guardrail - Mandates strict downstream propagation of Chi request contexts and active cancellation listeners across all spawned goroutine subtrees. Inbound HTTP/2 RST_STREAM frames and HTTP/3 transport terminations must preemptively abort downstream database transactions and RPC calls to prevent connection pool exhaustion and resource leaks under network degradation. globs: cmd/**/*.go, internal/**/*.go, pkg/**/*.go, api/**/*.go, **/*_test.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-chi-context-deadline-tree-cancellation-standard" --- # Go Chi HTTP/2 & HTTP/3 Context Propagation and Subtree Cancellation Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Orphan Goroutines and Context Severance During HTTP/2 Client Transport Disconnects ## System Constraints You are a Principal Backend Systems Architect specializing in high-throughput Go networking and resilient microservices. Enforce strict adherence to Go context tree propagation inside Chi routers and middleware. Never permit context severance (e.g., context.Background(), context.TODO()) in request-scoped operations. Mandate errgroup or select-driven cancellation listeners on all concurrent subtasks to release database pool connections immediately when inbound HTTP/2 or HTTP/3 transport streams reset. ## Strict Guidelines - Engineers MUST ALWAYS propagate r.Context() down every function parameter boundary, repository interface, and external RPC call without re-instantiating roots via context.Background(). - Engineers MUST NOT spawn unbounded or unmonitored goroutines inside Chi handlers; all concurrent branches MUST be managed by errgroup.WithContext(r.Context()) or explicit ctx.Done() lifecycle channels. - Code SHOULD utilize context.WithTimeoutCause or context.WithCancelCause to distinguish client disconnects (http2.StreamError or net.ErrClosed) from internal processing timeouts. - Services MUST configure database drivers (e.g., pgx, database/sql) to strictly honor context deadlines and cancellations across queries, pool acquisitions, and transaction rollbacks. - Components NEVER execute I/O-bound operations across channel operations without multiplexing against <-ctx.Done() to avert unrecoverable goroutine deadlocks upon client transport teardown. ## Bad vs Good Implementations ### Chi Request Subtree Execution & Database Propagation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Severing the context via context.Background() and launching unmonitored goroutines completely disconnects execution from Chi's underlying HTTP/2 or HTTP/3 transport stream. If a client disconnects, times out, or emits a RST_STREAM, the database queries and background goroutines continue running, exhausting pool connections and CPU. ```go package handlers import ( "context" "database/sql" "net/http" ) func ProcessOrderHandler(db *sql.DB) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { // ANTI-PATTERN: Severing context isolates the query from HTTP/2 RST_STREAM events. // If the client disconnects, this query runs to completion, tying up db pool connections. ctx := context.Background() // ANTI-PATTERN: Unmonitored goroutine leaks if client abandons request go func() { _, _ = db.ExecContext(ctx, "UPDATE inventory SET stock = stock - 1 WHERE item_id = $1", "item-123") }() var orderID string err := db.QueryRowContext(ctx, "SELECT id FROM orders WHERE user_id = $1", "user-456").Scan(&orderID) if err != nil { http.Error(w, err.Error(), http.StatusInternalServerError) return } w.Write([]byte(orderID)) } } ``` #### Production Standard (Correct) > **Standard**: The handler constructs a fail-safe tree by deriving from r.Context() and synchronizing concurrent queries via errgroup.WithContext(ctx). When the HTTP/2 or HTTP/3 stream terminates, the driver receives the cancellation signal, abruptly aborting active SQL operations and returning connections to the pool. ```go package handlers import ( "context" "database/sql" "errors" "net/http" "time" "golang.org/x/sync/errgroup" ) func ProcessOrderHandler(db *sql.DB) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { // Derive a strict bounded deadline from the inbound request context ctx, cancel := context.WithTimeoutCause( r.Context(), 3*time.Second, errors.New("order processing deadline exceeded"), ) defer cancel() // Bind concurrent branches to the same lifecycle subtree via errgroup g, groupCtx := errgroup.WithContext(ctx) g.Go(func() error { // Propagate group context: cancels immediately on client disconnect or group error _, err := db.ExecContext(groupCtx, "UPDATE inventory SET stock = stock - 1 WHERE item_id = $1", "item-123") return err }) var orderID string g.Go(func() error { return db.QueryRowContext(groupCtx, "SELECT id FROM orders WHERE user_id = $1", "user-456").Scan(&orderID) }) if err := g.Wait(); err != nil { // Distinguish client cancellation from internal infrastructure failure if errors.Is(ctx.Err(), context.Canceled) { // Transport stream aborted by client (HTTP/2 RST_STREAM / HTTP/3 QUIC stream reset) w.WriteHeader(499) // Client Closed Request return } http.Error(w, err.Error(), http.StatusInternalServerError) return } w.WriteHeader(http.StatusOK) _, _ = w.Write([]byte(orderID)) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go Chi HTTP/2 & HTTP/3 Context Propagation and Subtree Cancellation Guardrail

Go Chi HTTP/2 & HTTP/3 Context Propagation and Subtree Cancellation Guardrail defines an industrial-grade behavioral standard for backend engineering. Mandates strict downstream propagation of Chi request contexts and active cancellation listeners across all spawned goroutine subtrees. Inbound HTTP/2 RST_STREAM frames and HTTP/3 transport terminations must preemptively abort downstream database transactions and RPC calls to prevent connection pool exhaustion and resource leaks under network degradation. 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: Orphan Goroutines and Context Severance During HTTP/2 Client Transport Disconnects 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	Orphan Goroutines and Context Severance During HTTP/2 Client Transport Disconnects	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() down every function parameter boundary, repository interface, and external RPC call without re-instantiating roots via context.Background().

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.