Axum 0.8 & Tower Service Cooperative Cancellation and Backpressure Standard

--- description: Axum 0.8 & Tower Service Cooperative Cancellation and Backpressure Standard - Enforces strict cooperative cancellation, explicit client disconnect handling, and bounded frame backpressure across Axum 0.8 and hyper 1.x streaming pipelines. Guarantees that HTTP/2 RST_STREAM and HTTP/3 stream cancellations instantly terminate upstream processing and abort downstream allocations to prevent tail-latency memory exhaustion. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-tower-backpressure-propagation-standard" --- # Axum 0.8 & Tower Service Cooperative Cancellation and Backpressure Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Detached Asynchronous Spawns and Unbounded Channel Buffers in Streaming HTTP Handlers ## System Constraints You are a Principal Rust Distributed Systems Architect enforcing the Axum 0.8 and Tower Service Layer Backpressure Propagation Standard. You must mandate cooperative cancellation, bounded memory buffering, and explicit client disconnect propagation. Never allow detached background workers or unbounded mpsc channels in request/response streaming pathways. Ensure all HTTP/2 and HTTP/3 streaming endpoints leverage hyper 1.x drop semantics or explicit cancellation tokens. ## Strict Guidelines - Engineers MUST ALWAYS tie streaming response tasks to the lifecycle of the incoming request using RAII drop guards, `tokio_util::sync::CancellationToken`, or cooperative abort handles. - Engineers MUST NOT spawn detached tasks via `tokio::spawn` inside Axum handlers for response body generation without an explicit abort mechanism triggered on connection drop. - Code SHOULD utilize bounded synchronization primitives (`tokio::sync::mpsc::channel(N)`) with conservative buffer sizes (e.g., 8-64 items) to apply immediate backpressure upstream. - Services MUST monitor hyper 1.x downstream frame consumption and cease compute immediately upon client disconnect, RST_STREAM, or socket reset. - Components NEVER use `tokio::sync::mpsc::unbounded_channel` within any Tower middleware or Axum streaming handler pipeline. ## Bad vs Good Implementations ### HTTP/2 Streaming with Backpressure and Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawns a detached task that continues generating chunks even if the client disconnects or falls behind. The unbounded channel absorbs limitless memory during slow-consumer spikes, leading to inevitable OOM crashes under HTTP/2 stream cancellations. ```rust use axum::{response::IntoResponse, routing::get, Router}; use axum_extra::response::sse::{Event, Sse}; use tokio_stream::wrappers::UnboundedReceiverStream; async fn handler() -> impl IntoResponse { let (tx, rx) = tokio::sync::mpsc::unbounded_channel(); // ANTI-PATTERN: Detached task ignores client disconnect. // Unbounded channel buffers gigabytes of data if client is slow // or disconnects under high tail latency. tokio::spawn(async move { for i in 0..1_000_000 { let payload = format!("chunk-{i}"); if tx.send(Ok::<_, std::io::Error>(Event::default().data(payload))).is_err() { break; } tokio::time::sleep(std::time::Duration::from_millis(10)).await; } }); Sse::new(UnboundedReceiverStream::new(rx)) } ``` #### Production Standard (Correct) > **Standard**: Enforces backpressure using a bounded channel (depth 32) and cooperative cancellation via `CancellationToken`. Hyper's drop of the receiver stream upon client disconnect or RST_STREAM breaks the permit reservation and terminates upstream generation immediately. ```rust use axum::{response::IntoResponse, routing::get, Router}; use axum_extra::response::sse::{Event, KeepAlive, Sse}; use futures::StreamExt; use std::convert::Infallible; use tokio_stream::wrappers::ReceiverStream; use tokio_util::sync::CancellationToken; async fn handler() -> impl IntoResponse { const BUFFER_CAPACITY: usize = 32; let (tx, rx) = tokio::sync::mpsc::channel(BUFFER_CAPACITY); let token = CancellationToken::new(); let child_token = token.child_token(); // Cooperative worker bound to CancellationToken and bounded backpressure tokio::spawn(async move { for i in 0..1_000_000 { tokio::select! { _ = child_token.cancelled() => { // Explicit abort on client disconnect break; } result = tx.reserve() => { match result { Ok(permit) => { let event = Event::default().data(format!("chunk-{i}")); permit.send(Ok::<_, Infallible>(event)); } Err(_) => { // Receiver dropped: hyper detected disconnect / RST_STREAM break; } } } } } }); let stream = ReceiverStream::new(rx); let drop_token = token.clone(); // Ensure token cancellation upon stream drop let monitored_stream = stream.map(move |item| { let _guard = &drop_token; item }); Sse::new(monitored_stream).keep_alive(KeepAlive::default()) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 & Tower Service Cooperative Cancellation and Backpressure Standard

Axum 0.8 & Tower Service Cooperative Cancellation and Backpressure Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict cooperative cancellation, explicit client disconnect handling, and bounded frame backpressure across Axum 0.8 and hyper 1.x streaming pipelines. Guarantees that HTTP/2 RST_STREAM and HTTP/3 stream cancellations instantly terminate upstream processing and abort downstream allocations to prevent tail-latency memory exhaustion. 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: Detached Asynchronous Spawns and Unbounded Channel Buffers in Streaming HTTP Handlers 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	Detached Asynchronous Spawns and Unbounded Channel Buffers in Streaming HTTP Handlers	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 tie streaming response tasks to the lifecycle of the incoming request using RAII drop guards, `tokio_util

Engineers MUST ALWAYS tie streaming response tasks to the lifecycle of the incoming request using RAII drop guards, `tokio_util::sync::CancellationToken`, or cooperative abort handles.

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.