Go 1.24 Chi Context-Bound Structured Concurrency & Graceful Cancellation

--- description: Go 1.24 Chi Context-Bound Structured Concurrency & Graceful Cancellation - Enforces strict hierarchical context derivation, explicit lifetime containment, and bounded timeout propagation across concurrent fan-outs within Go 1.24 Chi HTTP routing pipelines. Prevents orphan goroutines, descriptor leaks, and distributed cascading failures by requiring all sub-tasks to bind to request context lifecycle signals. globs: **/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-chi-structured-concurrency-cancellation" --- # Go 1.24 Chi Context-Bound Structured Concurrency & Graceful Cancellation > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Detached Goroutine Spawning and Context-Agnostic Channel Blocking ## System Constraints You are a Principal Backend Systems Architect enforcing Go 1.24 runtime standards, Chi router idioms, and structured concurrency invariants. Mandate that every concurrent execution flow initiated within an HTTP handler derives directly or indirectly from http.Request.Context(), utilizes bounded errgroup.WithContext trees, guarantees resource termination on parent cancellation, and never leaks detached execution threads. ## Strict Guidelines - Engineers MUST ALWAYS derive sub-operation contexts from r.Context() using context.WithTimeout, context.WithDeadline, or errgroup.WithContext. - Engineers MUST NOT spawn detached goroutines using context.Background() or context.TODO() within HTTP request flows. - Code MUST monitor ctx.Done() across all blocking channel receives, long-running loops, and synchronization points. - Services MUST drain or cleanly abandon buffered channels when parent contexts are canceled, preventing worker goroutines from blocking indefinitely on channel writes. - Components NEVER start asynchronous tasks inside Chi middleware or handlers without explicit join points or structured tracking (e.g., sync.WaitGroup or errgroup.Group) that guarantee termination before handler return unless delegated to an asynchronous durable worker queue. ## Bad vs Good Implementations ### Concurrent Fan-Out with Graceful Cancellation in Chi Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawns a goroutine with detached context.Background(), ignores r.Context(), and performs unbuffered channel writes. If the HTTP client aborts or the handler times out after 2 seconds, the worker goroutine blocks indefinitely on channel transmission, leaking both memory and runtime threads. ```go package handlers import ( "context" "encoding/json" "net/http" "time" ) func BadFanoutHandler(w http.ResponseWriter, r *http.Request) { results := make(chan string) // ANTI-PATTERN: Detached goroutine with context.Background() // If the HTTP client disconnects, this goroutine and network call leak. go func() { ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) defer cancel() res, _ := fetchExternalService(ctx) results <- res // Will block indefinitely if handler exits early }() select { case res := <-results: json.NewEncoder(w).Encode(map[string]string{"result": res}) case <-time.After(2 * time.Second): http.Error(w, "timeout", http.StatusGatewayTimeout) } } func fetchExternalService(ctx context.Context) (string, error) { time.Sleep(3 * time.Second) return "payload", nil } ``` #### Production Standard (Correct) > **Standard**: Binds execution to r.Context() using golang.org/x/sync/errgroup. Cancellation or client disconnects immediately propagate through gctx to all child RPC requests. errgroup.Wait guarantees that all goroutines terminate before the handler exits, preventing thread leaks and dangling writes. ```go package handlers import ( "context" "encoding/json" "net/http" "time" "golang.org/x/sync/errgroup" ) type ResponseData struct { AuthStatus string `json:"auth_status"` Profile string `json:"profile"` } func GoodFanoutHandler(w http.ResponseWriter, r *http.Request) { // Enforce hierarchical deadline capped at 2.5s within parent request lifecycle ctx, cancel := context.WithTimeout(r.Context(), 2500*time.Millisecond) defer cancel() g, gctx := errgroup.WithContext(ctx) var authStatus, profile string g.Go(func() error { var err error authStatus, err = queryAuth(gctx) return err }) g.Go(func() error { var err error profile, err = queryProfile(gctx) return err }) if err := g.Wait(); err != nil { if ctx.Err() == context.DeadlineExceeded { http.Error(w, "gateway timeout", http.StatusGatewayTimeout) return } http.Error(w, "internal service error", http.StatusBadGateway) return } w.Header().Set("Content-Type", "application/json") _ = json.NewEncoder(w).Encode(ResponseData{ AuthStatus: authStatus, Profile: profile, }) } func queryAuth(ctx context.Context) (string, error) { req, err := http.NewRequestWithContext(ctx, http.MethodGet, "http://auth.internal/check", nil) if err != nil { return "", err } _ = req return "authenticated", nil } func queryProfile(ctx context.Context) (string, error) { req, err := http.NewRequestWithContext(ctx, http.MethodGet, "http://profile.internal/get", nil) if err != nil { return "", err } _ = req return "user-data", nil } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go 1.24 Chi Context-Bound Structured Concurrency & Graceful Cancellation

Go 1.24 Chi Context-Bound Structured Concurrency & Graceful Cancellation defines an industrial-grade behavioral standard for backend engineering. Enforces strict hierarchical context derivation, explicit lifetime containment, and bounded timeout propagation across concurrent fan-outs within Go 1.24 Chi HTTP routing pipelines. Prevents orphan goroutines, descriptor leaks, and distributed cascading failures by requiring all sub-tasks to bind to request context lifecycle signals. 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: Detached Goroutine Spawning and Context-Agnostic Channel Blocking 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	Detached Goroutine Spawning and Context-Agnostic Channel Blocking	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 derive sub-operation contexts from r.Context() using context.WithTimeout, context.WithDeadline, or errgroup.WithContext.

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.