Axum Tokio HTTP/2 & HTTP/3 Premature Stream Cancellation and Buffer Drain Guardrail

--- description: Axum Tokio HTTP/2 & HTTP/3 Premature Stream Cancellation and Buffer Drain Guardrail - Enforces deterministic cancellation safety and clean socket buffer release for HTTP/2 and HTTP/3 request body streams in Axum and Tokio applications. Prevents socket window starvation, worker task leaks, and connection pool lockups caused by client disconnects, early handler aborts, or unbounded background stream consumers. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-tokio-stream-cancellation-drain-guardrail" --- # Axum Tokio HTTP/2 & HTTP/3 Premature Stream Cancellation and Buffer Drain Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Early Handler Return or Detached Background Streaming Without Cancellation-Safe Body Drain ## System Constraints You are a Principal Software Architect enforcing production-grade Axum and Tokio async safety standards. You must mandate that all HTTP/2 and HTTP/3 request body streams are processed with strict cancellation safety, bounded timeouts, and explicit buffer exhaustion or drop semantics. Do not allow detached tasks that hold stream references without client disconnect propagation or handlers that abandon partially read streams. ## Strict Guidelines - Engineers MUST ALWAYS handle client stream cancellation gracefully using tokio::select! or Tokio CancellationToken to abort processing immediately when a client resets an HTTP/2 or HTTP/3 stream. - Engineers MUST NOT spawn detached background tasks (tokio::spawn) that capture request body streams without linking their lifecycle to the connection's abort signal or a bounded timeout. - Code SHOULD ensure that early exit returns (e.g., 401 Unauthorized, 413 Payload Too Large) either explicitly drop the request body or consume/drain remaining frames up to a conservative byte ceiling to allow Hyper to issue an RST_STREAM or reuse multiplexed streams cleanly. - Services MUST configure Hyper and Axum server timeouts (e.g., http2_keep_alive_timeout, http2_max_concurrent_streams, and request timeouts via tower::timeout::TimeoutLayer) to prevent hanging worker pools on stale stream allocations. - Handlers NEVER process unbounded chunk iteration across await points without verifying cancellation safety, ensuring partial chunks do not leak buffer allocations into global state upon drop. ## Bad vs Good Implementations ### Handling Request Body Streaming with Cancellation Safety and Drain Guard #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawning a detached task that consumes an Axum data stream detaches the stream from the request lifetime. If an HTTP/2 or HTTP/3 client cancels the stream (RST_STREAM) or disconnects, the background task may hang waiting on hyper's internal body channel, leaking connection buffer memory and consuming async runtime threads. ```rust use axum::{body::Body, extract::Request, response::IntoResponse, http::StatusCode}; use futures_util::StreamExt; pub async fn upload_handler(req: Request<Body>) -> impl IntoResponse { let (_parts, body) = req.into_parts(); let mut stream = body.into_data_stream(); // ANTI-PATTERN: Spawning unmonitored background task reading stream. // If the HTTP/2 client sends RST_STREAM or aborts, this task continues // waiting on stalled socket buffers, blocking Tokio worker pools. tokio::spawn(async move { let mut total_bytes = 0; while let Some(chunk_result) = stream.next().await { match chunk_result { Ok(chunk) => { total_bytes += chunk.len(); // Slow or hanging I/O tokio::time::sleep(std::time::Duration::from_millis(50)).await; } Err(_) => break, } } }); StatusCode::ACCEPTED } ``` #### Production Standard (Correct) > **Standard**: The body stream is processed in-line under a bounded timeout. When a client cancels or the timeout fires, the stream future is dropped immediately, which drops hyper's internal frame receiver, triggers the clean release of HTTP/2 socket buffers, and avoids worker task leaks. ```rust use axum::{body::Body, extract::Request, response::IntoResponse, http::StatusCode}; use futures_util::StreamExt; use tokio::time::{timeout, Duration}; const STREAM_TIMEOUT: Duration = Duration::from_secs(30); const MAX_PAYLOAD_BYTES: usize = 10 * 1024 * 1024; // 10MB pub async fn upload_handler(req: Request<Body>) -> Result<impl IntoResponse, StatusCode> { let (_parts, body) = req.into_parts(); let mut stream = body.into_data_stream(); let mut total_bytes = 0; // INVARIANT: Body stream is read inline within a bounded timeout. // If the client aborts, the future is dropped, causing hyper's Body // stream to drop immediately, signaling RST_STREAM and freeing socket buffers. let process_stream = async { while let Some(chunk_res) = stream.next().await { let chunk = chunk_res.map_err(|_| StatusCode::BAD_REQUEST)?; total_bytes += chunk.len(); if total_bytes > MAX_PAYLOAD_BYTES { return Err(StatusCode::PAYLOAD_TOO_LARGE); } // Simulated bounded async work tokio::task::yield_now().await; } Ok::<usize, StatusCode>(total_bytes) }; match timeout(STREAM_TIMEOUT, process_stream).await { Ok(Ok(_bytes)) => Ok(StatusCode::OK), Ok(Err(status)) => Err(status), Err(_) => Err(StatusCode::REQUEST_TIMEOUT), } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum Tokio HTTP/2 & HTTP/3 Premature Stream Cancellation and Buffer Drain Guardrail

Axum Tokio HTTP/2 & HTTP/3 Premature Stream Cancellation and Buffer Drain Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic cancellation safety and clean socket buffer release for HTTP/2 and HTTP/3 request body streams in Axum and Tokio applications. Prevents socket window starvation, worker task leaks, and connection pool lockups caused by client disconnects, early handler aborts, or unbounded background stream consumers. 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: Early Handler Return or Detached Background Streaming Without Cancellation-Safe Body Drain 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	Early Handler Return or Detached Background Streaming Without Cancellation-Safe Body Drain	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 handle client stream cancellation gracefully using tokio

Engineers MUST ALWAYS handle client stream cancellation gracefully using tokio::select! or Tokio CancellationToken to abort processing immediately when a client resets an HTTP/2 or HTTP/3 stream.

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.