Chi 5.x Context Deadline Propagation & Outbound Transport Poison Fencing

--- description: Chi 5.x Context Deadline Propagation & Outbound Transport Poison Fencing - Enforces strict inbound-to-outbound context deadline propagation in Go Chi 5.x handlers paired with deterministic HTTP transport connection fencing. Prevents poisoned or desynchronized TCP sockets from being recycled into the runtime epoll idle pool when client contexts abort mid-flight. globs: **/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-chi-context-deadline-transport-poison-fence" --- # Chi 5.x Context Deadline Propagation & Outbound Transport Poison Fencing > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unconditional Body Draining and Default Transport Reuse on Cancelled Inbound Contexts ## System Constraints You are a Principal Software Architect enforcing Go Chi 5.x Context Deadline Propagation and HTTP Transport Connection Poison Fencing. Mandate strict context inheritance with bounded timeouts, forbid http.DefaultClient/http.DefaultTransport usage, and mandate deterministic connection eviction when context cancellations occur mid-stream to avoid epoll socket starvation. ## Strict Guidelines - Engineers MUST ALWAYS derive outbound downstream request contexts from the Chi handler's inbound `r.Context()` using bounded timeouts via `context.WithTimeoutCause` or `context.WithDeadlineCause`. - Engineers MUST NOT unconditionally drain `resp.Body` via `io.Copy(io.Discard, ...)` if `ctx.Err() != nil` or an I/O error occurred, as attempting to drain cancelled streams stalls goroutines and risks returning desynchronized sockets to the transport pool. - Engineers MUST ensure `resp.Body.Close()` is executed immediately without body draining whenever `ctx.Err() != nil`, forcing `net/http.Transport` to tear down the underlying TCP connection rather than recycling a tainted socket. - Services MUST configure custom `*http.Transport` instances with explicit `MaxIdleConns`, `MaxIdleConnsPerHost`, `IdleConnTimeout`, `ResponseHeaderTimeout`, and `TLSHandshakeTimeout` instead of relying on `http.DefaultClient` or `http.DefaultTransport`. - Components NEVER execute outbound network calls inside Chi handlers without structured telemetry, context cancellation checks, and explicit buffer exhaustion limits. ## Bad vs Good Implementations ### Outbound Service Call within Go Chi 5.x Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using http.DefaultClient shares unbounded epoll connection pools. Draining resp.Body via io.Copy when the context may have aborted can block indefinitely or return corrupted HTTP pipelining state to the transport pool, poisoning subsequent requests across the service. ```go package handler import ( "io" "net/http" "github.com/go-chi/chi/v5" ) func RegisterRoutes(r chi.Router) { r.Get("/data", FetchDownstreamData) } func FetchDownstreamData(w http.ResponseWriter, r *http.Request) { // ANTI-PATTERN: DefaultClient uses unbounded shared transport. // Context is used directly without timeout boundaries. req, err := http.NewRequestWithContext(r.Context(), http.MethodGet, "http://downstream.internal/api", nil) if err != nil { http.Error(w, err.Error(), http.StatusInternalServerError) return } resp, err := http.DefaultClient.Do(req) if err != nil { http.Error(w, err.Error(), http.StatusBadGateway) return } defer resp.Body.Close() // ANTI-PATTERN: Blindly draining body even if context is already aborted, // causing epoll hangs and recycling dirty/desynced connections to the pool. _, _ = io.Copy(io.Discard, resp.Body) w.WriteHeader(http.StatusOK) } ``` #### Production Standard (Correct) > **Standard**: Defines an isolated, strictly bounded Transport pool. Attaches a bounded context timeout, and conditionally fences connection recycling: if context cancellation occurred, the body is closed without reading, forcing transport to discard the tainted TCP socket rather than keeping it in epoll idle state. ```go package handler import ( "context" "errors" "io" "net" "net/http" "time" "github.com/go-chi/chi/v5" ) var customTransport = &http.Transport{ Proxy: http.ProxyFromEnvironment, DialContext: (&net.Dialer{ Timeout: 5 * time.Second, KeepAlive: 30 * time.Second, }).DialContext, MaxIdleConns: 100, MaxIdleConnsPerHost: 10, IdleConnTimeout: 90 * time.Second, TLSHandshakeTimeout: 5 * time.Second, ResponseHeaderTimeout: 5 * time.Second, ExpectContinueTimeout: 1 * time.Second, } var fencedClient = &http.Client{ Transport: customTransport, } func RegisterRoutes(r chi.Router) { r.Get("/data", FetchDownstreamData) } func FetchDownstreamData(w http.ResponseWriter, r *http.Request) { ctx, cancel := context.WithTimeoutCause( r.Context(), 3*time.Second, errors.New("downstream fetch deadline exceeded"), ) defer cancel() req, err := http.NewRequestWithContext(ctx, http.MethodGet, "http://downstream.internal/api", nil) if err != nil { http.Error(w, err.Error(), http.StatusInternalServerError) return } resp, err := fencedClient.Do(req) if err != nil { http.Error(w, err.Error(), http.StatusBadGateway) return } defer func() { // FENCE: If the context was cancelled or expired mid-flight, // DO NOT drain the stream. Close immediately to force TCP RST / drop socket, // preventing a desynchronized connection from re-entering the epoll idle pool. if ctx.Err() != nil { _ = resp.Body.Close() return } // Safely drain only if clean context persists, capping drain read limit. _, _ = io.CopyN(io.Discard, resp.Body, 64*1024) _ = resp.Body.Close() }() if resp.StatusCode != http.StatusOK { http.Error(w, "downstream error", http.StatusBadGateway) return } w.WriteHeader(http.StatusOK) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Chi 5.x Context Deadline Propagation & Outbound Transport Poison Fencing

Chi 5.x Context Deadline Propagation & Outbound Transport Poison Fencing defines an industrial-grade behavioral standard for backend engineering. Enforces strict inbound-to-outbound context deadline propagation in Go Chi 5.x handlers paired with deterministic HTTP transport connection fencing. Prevents poisoned or desynchronized TCP sockets from being recycled into the runtime epoll idle pool when client contexts abort mid-flight. 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: Unconditional Body Draining and Default Transport Reuse on Cancelled Inbound 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	Unconditional Body Draining and Default Transport Reuse on Cancelled Inbound 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 derive outbound downstream request contexts from the Chi handler's inbound `r.Context()` using bounded timeouts via `context.WithTimeoutCause` or `context.WithDeadlineCause`.

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.