Go Chi context.AfterFunc HTTP/2 Resource Finalization & Leak Prevention

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Spawning dedicated watchdog goroutines or failing to deregister context cancellation hooks for long-lived sockets) 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.

--- description: Go Chi context.AfterFunc HTTP/2 Resource Finalization & Leak Prevention - Enforces deterministic resource finalization and external socket termination in Go Chi handlers using Go 1.21+ context.AfterFunc. Eliminates orphan watcher goroutines while ensuring immediate, non-blocking teardown of downstream TCP/gRPC connections upon HTTP/2 client disconnects (RST_STREAM). 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-afterfunc-resource-finalization" --- # Go Chi context.AfterFunc HTTP/2 Resource Finalization & Leak Prevention > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning dedicated watchdog goroutines or failing to deregister context cancellation hooks for long-lived sockets ## System Constraints You are a Principal Backend Architect enforcing strict concurrency invariants in Go Chi microservices. You must ensure that HTTP/2 client disconnections instantly propagate to downstream sockets (such as raw net.Conn, gRPC ClientStreams, or SSE loops) using Go 1.21's context.AfterFunc. You must prohibit legacy background monitoring goroutines that leak memory under high churn. ## Strict Guidelines - Engineers MUST ALWAYS use `context.AfterFunc(r.Context(), ...)` instead of spawning dedicated `go func() { <-ctx.Done(); ... }()` watcher goroutines to monitor client disconnects. - Engineers MUST ALWAYS defer the execution of the cancellation handle returned by `context.AfterFunc` (e.g., `stop := context.AfterFunc(...); defer stop()`) to prevent resource retention and memory leaks once handler execution concludes. - Callbacks registered with `context.AfterFunc` MUST be strictly non-blocking and idempotent; blocking operations inside the callback MUST NOT be allowed, as they stall the runtime context scheduler. - Code MUST close downstream net.Conn, cancel sub-contexts, or signal non-blocking termination channels inside `context.AfterFunc` callbacks upon HTTP/2 RST_STREAM frames. - Services MUST NOT rely solely on standard downstream socket read timeouts when serving continuous streaming responses over HTTP/2, as broken client connections will hold server resources until the next flush. ## Bad vs Good Implementations ### Downstream Socket Teardown on HTTP/2 Client Disconnect #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawning a separate goroutine waiting on `<-r.Context().Done()` leaks a goroutine stack for every successful request that finishes before the context is explicitly canceled. Additionally, if the downstream socket closes first, the watcher goroutine remains suspended indefinitely until the client drops. ```go package handlers import ( "io" "net" "net/http" "github.com/go-chi/chi/v5" ) func StreamProxyHandler(w http.ResponseWriter, r *http.Request) { // ANTI-PATTERN: Leaks a goroutine per request if request finishes normally, // or blocks if the downstream read hangs before ctx is cancelled. downstreamConn, err := net.Dial("tcp", "upstream.internal:9000") if err != nil { http.Error(w, err.Error(), http.StatusBadGateway) return } defer downstreamConn.Close() // Leaky watcher goroutine go func() { <-r.Context().Done() downstreamConn.Close() }() w.WriteHeader(http.StatusOK) _, _ = io.Copy(w, downstreamConn) } ``` #### Production Standard (Correct) > **Standard**: Using `context.AfterFunc` eliminates the overhead of an extra monitoring goroutine. The `stop()` call ensures the callback is deregistered when the handler finishes normally, while `sync.Once` guarantees safe, idempotent socket teardown whether the transfer finishes or the client disconnects prematurely via HTTP/2 RST_STREAM. ```go package handlers import ( "context" "io" "net" "net/http" "sync" "github.com/go-chi/chi/v5" ) func StreamProxyHandler(w http.ResponseWriter, r *http.Request) { downstreamConn, err := net.Dial("tcp", "upstream.internal:9000") if err != nil { http.Error(w, err.Error(), http.StatusBadGateway) return } var closeOnce sync.Once closeSocket := func() { closeOnce.Do(func() { _ = downstreamConn.Close() }) } defer closeSocket() // Register immediate, non-blocking cleanup hook on client HTTP/2 disconnect stop := context.AfterFunc(r.Context(), func() { closeSocket() }) defer stop() // Deregisters callback immediately on handler exit w.WriteHeader(http.StatusOK) _, _ = io.Copy(w, downstreamConn) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go Chi context.AfterFunc HTTP/2 Resource Finalization & Leak Prevention

Go Chi context.AfterFunc HTTP/2 Resource Finalization & Leak Prevention defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic resource finalization and external socket termination in Go Chi handlers using Go 1.21+ context.AfterFunc. Eliminates orphan watcher goroutines while ensuring immediate, non-blocking teardown of downstream TCP/gRPC connections upon HTTP/2 client disconnects (RST_STREAM). 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: Spawning dedicated watchdog goroutines or failing to deregister context cancellation hooks for long-lived sockets 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	Spawning dedicated watchdog goroutines or failing to deregister context cancellation hooks for long-lived sockets	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 use `context.AfterFunc(r.Context(), ...)` instead of spawning dedicated `go func() { <-ctx.Done()

Engineers MUST ALWAYS use `context.AfterFunc(r.Context(), ...)` instead of spawning dedicated `go func() { <-ctx.Done(); ... }()` watcher goroutines to monitor client disconnects.

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.