Go 1.24 Chi Context-Driven Graceful Pipeline Draining & Goroutine Leak Invariants

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Unbounded Background Goroutines, Detached Contexts, and Abrupt Process Termination Dropping In-Flight Workloads) 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 1.24 Chi Context-Driven Graceful Pipeline Draining & Goroutine Leak Invariants

--- description: Go 1.24 Chi Context-Driven Graceful Pipeline Draining & Goroutine Leak Invariants - Enforces strict context propagation, deterministic goroutine lifecycle bounding, and orderly HTTP server draining for Go 1.24 applications using the Chi router during Kubernetes SIGTERM rolling updates. Prevents dropped in-flight requests and lingering background workers by synchronizing OS signal captures, net/http server shutdowns, and context-chained channel pipelines with sync.WaitGroup barriers. globs: cmd/**/*.go, internal/**/*.go, pkg/**/*.go, **/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-chi-graceful-draining-goroutine-leak-prevention" --- # Go 1.24 Chi Context-Driven Graceful Pipeline Draining & Goroutine Leak Invariants > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Background Goroutines, Detached Contexts, and Abrupt Process Termination Dropping In-Flight Workloads ## System Constraints You are a Principal Backend Architect enforcing strict Go 1.24 Chi Context-Driven Graceful Pipeline Draining and Goroutine Leak Invariants. You must ensure that every HTTP service captures SIGINT/SIGTERM using signal.NotifyContext, cleanly ceases listener acceptance via http.Server.Shutdown(), and allows active Chi handlers and downstream worker pipelines to drain completely within a bounded timeout. You forbid uncoordinated 'go func()' invocations without lifecycle tracking, detached contexts, and channel blocking without context select cases. ## Strict Guidelines - Engineers MUST ALWAYS initialize process signal listeners via signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) at the application entrypoint to guarantee unified lifecycle propagation across Chi routes and background pools. - Engineers MUST ALWAYS coordinate asynchronous handler pipelines using explicit sync.WaitGroup tracking or context-aware worker pools, ensuring no goroutine escapes the scope of the server's graceful shutdown deadline. - Engineers MUST NOT spawn detached background goroutines using context.Background() or context.TODO() inside Chi request handlers when processing work that must complete reliably during SIGTERM draining. - Services MUST invoke http.Server.Shutdown(drainCtx) with a strictly bounded context (e.g., context.WithTimeout) rather than http.Server.Close(), guaranteeing existing HTTP connections finish within the Kubernetes terminationGracePeriodSeconds. - Code MUST ALWAYS select on ctx.Done() across every channel read or write inside worker pipelines to prevent indefinite blocking and memory leaks when a termination context is cancelled. ## Bad vs Good Implementations ### Graceful Chi Server Lifecycle and Channel Pipeline Draining #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The HTTP server executes ListenAndServe without capturing OS termination signals (SIGTERM/SIGINT). Upon a Kubernetes rollout, the container exits immediately, truncating in-flight connections. Spawning goroutines with detached contexts drops background work without any synchronization barrier. ```go package main import ( "context" "fmt" "net/http" "github.com/go-chi/chi/v5" ) func main() { r := chi.NewRouter() r.Post("/process", func(w http.ResponseWriter, r *http.Request) { // Anti-pattern: Detached goroutine unlinked to server lifecycle go func() { // In-flight work lost on immediate SIGTERM fmt.Println("Processing async pipeline payload...") }() w.WriteHeader(http.StatusAccepted) }) // Anti-pattern: Blocking ListenAndServe without SIGTERM capture or Shutdown() _ = http.ListenAndServe(":8080", r) } ``` #### Production Standard (Correct) > **Standard**: Coordinates termination using signal.NotifyContext, stops listener acceptance cleanly via http.Server.Shutdown(drainCtx), and uses a sync.WaitGroup to flush buffered worker queue channels without dropping requests or leaking goroutines. ```go package main import ( "context" "errors" "log/slog" "net/http" "os" "os/signal" "sync" "syscall" "time" "github.com/go-chi/chi/v5" ) type Pipeline struct { wg sync.WaitGroup jobs chan string } func (p *Pipeline) Enqueue(ctx context.Context, item string) error { select { case <-ctx.Done(): return ctx.Err() case p.jobs <- item: return nil } } func (p *Pipeline) StartWorker(ctx context.Context) { p.wg.Add(1) go func() { defer p.wg.Done() for { select { case <-ctx.Done(): // Drain remaining channel buffer before exiting for item := range p.jobs { slog.Info("drained payload", "item", item) } return case item, ok := <-p.jobs: if !ok { return } slog.Info("processed payload", "item", item) } } }() } func main() { rootCtx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() pipeline := &Pipeline{jobs: make(chan string, 100)} pipeline.StartWorker(rootCtx) r := chi.NewRouter() r.Post("/process", func(w http.ResponseWriter, r *http.Request) { if err := pipeline.Enqueue(r.Context(), "order-payload"); err != nil { http.Error(w, "server terminating", http.StatusServiceUnavailable) return } w.WriteHeader(http.StatusAccepted) }) srv := &http.Server{ Addr: ":8080", Handler: r, ReadHeaderTimeout: 5 * time.Second, } serverErr := make(chan error, 1) go func() { if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) { serverErr <- err } }() select { case err := <-serverErr: slog.Error("server failed", "err", err) case <-rootCtx.Done(): slog.Info("shutdown signal received, draining...") } drainCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second) defer cancel() if err := srv.Shutdown(drainCtx); err != nil { slog.Error("forced shutdown triggered", "err", err) } close(pipeline.jobs) pipeline.wg.Wait() slog.Info("server and pipeline drained successfully") } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go 1.24 Chi Context-Driven Graceful Pipeline Draining & Goroutine Leak Invariants

Go 1.24 Chi Context-Driven Graceful Pipeline Draining & Goroutine Leak Invariants defines an industrial-grade behavioral standard for backend engineering. Enforces strict context propagation, deterministic goroutine lifecycle bounding, and orderly HTTP server draining for Go 1.24 applications using the Chi router during Kubernetes SIGTERM rolling updates. Prevents dropped in-flight requests and lingering background workers by synchronizing OS signal captures, net/http server shutdowns, and context-chained channel pipelines with sync.WaitGroup barriers. 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: Unbounded Background Goroutines, Detached Contexts, and Abrupt Process Termination Dropping In-Flight Workloads 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	Unbounded Background Goroutines, Detached Contexts, and Abrupt Process Termination Dropping In-Flight Workloads	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 initialize process signal listeners via signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) at the application entrypoint to guarantee unified lifecycle propagation across Chi routes and background pools.

Engineers MUST ALWAYS initialize process signal listeners via signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) at the application entrypoint to guarantee unified lifecycle propagation across Chi routes and background pools.

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.