Axum HTTP/3 QUIC Unilateral Stream Cancellation & Socket Buffer Bounding Standard

--- description: Axum HTTP/3 QUIC Unilateral Stream Cancellation & Socket Buffer Bounding Standard - Enforces strict bounds on concurrent QUIC streams, stream cancellation velocity, and transport-level buffer allocation in Rust Axum/h3 services. Prevents memory exhaustion and edge-node CPU saturation caused by malicious client-side rapid stream reset floods (RESET_STREAM and STOP_SENDING frames). globs: src/**/*.rs, Cargo.toml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-h3-quic-stream-cancellation-guardrail" --- # Axum HTTP/3 QUIC Unilateral Stream Cancellation & Socket Buffer Bounding Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded QUIC Stream Concurrency and Unmonitored Stream Resets Allowing Hyper-Scale Edge DoS ## System Constraints You are a Principal Rust Network Architect enforcing strict defensive parameters for Axum services operating over HTTP/3 and QUIC (quinn/h3). You must mandate defensive Quinn TransportConfig settings, enforce explicit concurrency and buffer bounds, track reset-to-request ratios, and ensure cooperative cancellation handling on all stream-handling tasks. ## Strict Guidelines - Engineers MUST ALWAYS configure explicit low-to-moderate maximum concurrent bidirectional stream limits (max_concurrent_bidi_streams) and unidirectional stream limits on Quinn TransportConfig instead of relying on default or unlimited values. - Engineers MUST configure strict stream_receive_window and receive_window bounds to prevent unbounded socket-buffer allocation during sudden stream stall or abort cycles. - Services MUST track the velocity of client-initiated RESET_STREAM and STOP_SENDING frames per connection and proactively sever connections exceeding anomaly thresholds using CONNECTION_CLOSE. - Code MUST NEVER spawn unmetered, detached Tokio background tasks per QUIC request without bound tokens (e.g., tokio::sync::Semaphore) or cancellation-aware select loops. - Stream processing tasks MUST yield promptly and discard in-flight work upon detecting Request stream cancellation, preventing zombie compute tasks from consuming pipeline capacity. ## Bad vs Good Implementations ### Configuring Quinn Transport and Bounded Stream Rate Limiting in Axum H3 Driver #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default or overly permissive transport configurations with massive stream concurrency limits leave the server vulnerable to QUIC Rapid Reset attacks. Spawning handlers on an unbounded stream limit allows clients to queue thousands of state allocations per connection. ```rust use quinn::{Endpoint, ServerConfig, TransportConfig}; use std::sync::Arc; pub fn create_insecure_quic_server() -> Endpoint { let mut transport = TransportConfig::default(); // ANTI-PATTERN: Unbounded concurrent streams and oversized flow-control windows // allow clients to open thousands of streams and immediately cancel them (Rapid Reset), // exhausting socket buffers and memory while tasks remain scheduled. transport.max_concurrent_bidi_streams(1_000_000u32.into()); transport.max_concurrent_uni_streams(1_000_000u32.into()); let mut server_config = ServerConfig::default(); server_config.transport_config(Arc::new(transport)); // Server accepts connections without tracking reset ratios or rate-limiting streams Endpoint::server(server_config, "0.0.0.0:4433".parse().unwrap()).unwrap() } ``` #### Production Standard (Correct) > **Standard**: Defines strict low stream bounds (128 bidi), limits the stream receive window to 64 KiB, bounds concurrent task creation via an explicit semaphore permit, and cooperatively handles stream termination and client resets via `tokio::select!`. ```rust use quinn::{Connection, Endpoint, ServerConfig, TransportConfig, VarInt}; use std::{sync::Arc, time::Duration}; use tokio::sync::Semaphore; const MAX_CONCURRENT_BIDI_STREAMS: u32 = 128; const MAX_CONCURRENT_UNI_STREAMS: u32 = 16; const STREAM_RECEIVE_WINDOW: u32 = 64 * 1024; // 64 KiB const CONNECTION_RECEIVE_WINDOW: u32 = 1024 * 1024; // 1 MiB pub fn create_hardened_quic_server() -> Endpoint { let mut transport = TransportConfig::default(); // Mitigate rapid reset by constraining parallel allocations transport.max_concurrent_bidi_streams(VarInt::from_u32(MAX_CONCURRENT_BIDI_STREAMS)); transport.max_concurrent_uni_streams(VarInt::from_u32(MAX_CONCURRENT_UNI_STREAMS)); transport.stream_receive_window(VarInt::from_u32(STREAM_RECEIVE_WINDOW)); transport.receive_window(VarInt::from_u32(CONNECTION_RECEIVE_WINDOW)); transport.max_idle_timeout(Some(Duration::from_secs(30).try_into().unwrap())); let mut server_config = ServerConfig::default(); server_config.transport_config(Arc::new(transport)); Endpoint::server(server_config, "0.0.0.0:4433".parse().unwrap()).unwrap() } pub async fn handle_connection_bounded(conn: Connection, stream_limit: Arc<Semaphore>) { loop { let permit = match stream_limit.clone().acquire_owned().await { Ok(p) => p, Err(_) => break, }; match conn.accept_bi().await { Ok((mut send, mut recv)) => { tokio::spawn(async move { let _permit = permit; // RAII release on cancellation or completion // Enforce graceful cancellation check on client abort let mut buf = [0u8; 4096]; tokio::select! { biased; read_res = recv.read(&mut buf) => { if let Ok(None) | Err(_) = read_res { let _ = send.finish(); } } _ = tokio::time::sleep(Duration::from_secs(10)) => { let _ = send.reset(VarInt::from_u32(0x0100)); // H3_REQUEST_CANCELLED } } }); } Err(_) => break, } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum HTTP/3 QUIC Unilateral Stream Cancellation & Socket Buffer Bounding Standard

Axum HTTP/3 QUIC Unilateral Stream Cancellation & Socket Buffer Bounding Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict bounds on concurrent QUIC streams, stream cancellation velocity, and transport-level buffer allocation in Rust Axum/h3 services. Prevents memory exhaustion and edge-node CPU saturation caused by malicious client-side rapid stream reset floods (RESET_STREAM and STOP_SENDING frames). 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 QUIC Stream Concurrency and Unmonitored Stream Resets Allowing Hyper-Scale Edge DoS 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 QUIC Stream Concurrency and Unmonitored Stream Resets Allowing Hyper-Scale Edge DoS	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 configure explicit low-to-moderate maximum concurrent bidirectional stream limits (max_concurrent_bidi_streams) and unidirectional stream limits on Quinn TransportConfig instead of relying on default or unlimited values.

Engineers MUST ALWAYS configure explicit low-to-moderate maximum concurrent bidirectional stream limits (max_concurrent_bidi_streams) and unidirectional stream limits on Quinn TransportConfig instead of relying on default or unlimited values.

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.