Go Chi HTTP/3 Flow-Control Stream Budget Allocation Standard

--- description: Go Chi HTTP/3 Flow-Control Stream Budget Allocation Standard - Enforces bounded per-session stream concurrency and token-bucket bandwidth budgeting for HTTP/3 services running on Go Chi. Prevents protocol-level QUIC connection flow-control window exhaustion (MAX_DATA starvation) and connection-level head-of-line blocking under asymmetric stream bursts. 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-quic-stream-budget-allocation-standard" --- # Go Chi HTTP/3 Flow-Control Stream Budget Allocation Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded HTTP/3 Stream Multiplexing Leading to QUIC Connection Window Exhaustion and Stream Starvation ## System Constraints You are a Principal Backend Architect enforcing strict HTTP/3 flow-control and QUIC stream budgeting within Go Chi microservices. Mandate explicit per-session token-bucket allocation guards, deterministic stream rejection when budgets are depleted, and prevention of protocol-level head-of-line blocking. ## Strict Guidelines - Engineers MUST ALWAYS enforce per-session stream concurrency limits in Chi middleware for HTTP/3 routes to prevent QUIC MAX_DATA / MAX_STREAMS exhaustion. - Engineers MUST NOT allow unbounded multiplexed streaming endpoints to consume shared connection-level flow-control windows without isolated token-bucket budgets. - Code SHOULD extract the underlying QUIC session identifier or TLS session ticket from the request context to key stream allocators. - Services MUST reject requests with HTTP 429 (Too Many Requests) or protocol-level stream resets before consuming body buffers if the session stream budget is depleted. - Components NEVER hold acquired stream budget tokens across asynchronous unmonitored goroutines without structured context cancellation and deterministic defer release. ## Bad vs Good Implementations ### Unbounded HTTP/3 Stream Consumption vs. Budgeted Token-Bucket Guardrail #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accepting arbitrary streaming uploads without session-scoped budget allocation allows rogue or bursty clients to exhaust the QUIC connection flow-control window (MAX_DATA), stalling all other multiplexed streams on the same transport connection. ```go package transport import ( "io" "net/http" "github.com/go-chi/chi/v5" ) func RegisterStreamRoutes(r chi.Router) { // ANTI-PATTERN: Unbounded stream processing on HTTP/3. // Under concurrent stream load, unthrottled reads exhaust the QUIC connection-level // MAX_DATA flow-control window, starving concurrent unary/control streams and causing HoL blocking. r.Post("/stream/ingest", func(w http.ResponseWriter, r *http.Request) { buf := make([]byte, 64*1024) for { n, err := r.Body.Read(buf) if n > 0 { _ = processPayload(buf[:n]) } if err == io.EOF { break } if err != nil { w.WriteHeader(http.StatusInternalServerError) return } } w.WriteHeader(http.StatusAccepted) }) } func processPayload(b []byte) error { return nil } ``` #### Production Standard (Correct) > **Standard**: Applies a thread-safe token-bucket budget per QUIC/TLS session within Chi middleware. When a connection bursts beyond its negotiated stream allotment, new streams are non-blockingly rejected with HTTP 429, preventing flow-control exhaustion across the QUIC session. ```go package transport import ( "context" "crypto/tls" "encoding/hex" "errors" "net/http" "sync" "golang.org/x/time/rate" "github.com/go-chi/chi/v5" ) type SessionStreamGuard struct { mu sync.Mutex sessions map[string]*rate.Limiter limit rate.Limit burst int } func NewSessionStreamGuard(r rate.Limit, b int) *SessionStreamGuard { return &SessionStreamGuard{ sessions: make(map[string]*rate.Limiter), limit: r, burst: b, } } func (g *SessionStreamGuard) Middleware(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { sessionKey := getSessionKey(r) g.mu.Lock() limiter, exists := g.sessions[sessionKey] if !exists { limiter = rate.NewLimiter(g.limit, g.burst) g.sessions[sessionKey] = limiter } g.mu.Unlock() if !limiter.Allow() { w.Header().Set("Retry-After", "1") http.Error(w, "QUIC Stream Budget Depleted", http.StatusTooManyRequests) return } next.ServeHTTP(w, r) }) } func getSessionKey(r *http.Request) string { if r.TLS != nil && len(r.TLS.TLSUnique) > 0 { return hex.EncodeToString(r.TLS.TLSUnique) } return r.RemoteAddr } func RegisterStreamRoutes(r chi.Router, guard *SessionStreamGuard) { r.Route("/stream", func(sr chi.Router) { sr.Use(guard.Middleware) sr.Post("/ingest", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusAccepted) }) }) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go Chi HTTP/3 Flow-Control Stream Budget Allocation Standard

Go Chi HTTP/3 Flow-Control Stream Budget Allocation Standard defines an industrial-grade behavioral standard for backend engineering. Enforces bounded per-session stream concurrency and token-bucket bandwidth budgeting for HTTP/3 services running on Go Chi. Prevents protocol-level QUIC connection flow-control window exhaustion (MAX_DATA starvation) and connection-level head-of-line blocking under asymmetric stream bursts. 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 HTTP/3 Stream Multiplexing Leading to QUIC Connection Window Exhaustion and Stream Starvation 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 HTTP/3 Stream Multiplexing Leading to QUIC Connection Window Exhaustion and Stream Starvation	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 enforce per-session stream concurrency limits in Chi middleware for HTTP/3 routes to prevent QUIC MAX_DATA / MAX_STREAMS exhaustion.

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.