Axum 0.8 Tower Service Load-Shedding Backpressure Invariant

--- description: Axum 0.8 Tower Service Load-Shedding Backpressure Invariant - Protects Tokio work-stealing thread pools from executor saturation by enforcing bounded buffer drop policies before request deserialization. Mandates placement of Tower load shedding and concurrency limit layers at the outermost edge of Axum 0.8 routers with explicit 503 Service Unavailable mapping. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-0-8-tower-load-shedding-backpressure-invariant" --- # Axum 0.8 Tower Service Load-Shedding Backpressure Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Deserializing Payloads or Buffering In-Flight Requests Without Upstream Edge Load-Shedding ## System Constraints You are a Principal Rust Architect enforcing Axum 0.8 and Tower load-shedding backpressure invariants. Mandate bounded execution and edge rejection before request body deserialization to protect Tokio worker threads. ## Strict Guidelines - Engineers MUST ALWAYS place Tower `LoadShedLayer` and `ConcurrencyLimitLayer` upstream of request body extractors to drop excessive traffic prior to allocating memory or executing deserialization logic. - Engineers MUST wrap `LoadShedLayer` with Axum's `HandleErrorLayer` to translate `tower::load_shed::error::Overloaded` into an explicit `503 Service Unavailable` HTTP response. - Code MUST NEVER use unbounded `tower::buffer::BufferLayer` or unbound Tokio `mpsc` channels within the HTTP request pipeline, as they lead to silent memory exhaustion under sustained ingress spikes. - Services MUST enforce strict body size limits (`axum::extract::DefaultBodyLimit`) in conjunction with load shedding to prevent memory starvation from slow-drain attacks. - Components NEVER execute blocking operations (e.g., synchronous file I/O, heavy crypto, or synchronous database drivers) within Axum handlers without delegating via `tokio::task::spawn_blocking`. ## Bad vs Good Implementations ### Edge Load Shedding vs Unbounded Deserialization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The router has no concurrency barrier or load-shedding layer. When high traffic arrives, Tokio workers concurrently read and deserialize incoming JSON bodies into heap memory, exhausting allocator resources and stalling cooperative scheduling before any request can be shed. ```rust use axum::{routing::post, Json, Router}; use serde::Deserialize; #[derive(Deserialize)] struct HeavyPayload { data: Vec<u8>, } // ANTI-PATTERN: Heavy body parsing occurs before concurrency/load-shed evaluation. // An ingress spike will exhaust Tokio worker memory and starve the executor pool. async fn compute(Json(payload): Json<HeavyPayload>) -> &'static str { // Simulated CPU-intensive or state-bound operation let _ = payload.data.len(); "ok" } pub fn app() -> Router { Router::new().route("/compute", post(compute)) } ``` #### Production Standard (Correct) > **Standard**: The middleware stack enforces bounded concurrency and fast drops at the outermost edge using Tower's `LoadShedLayer` and `ConcurrencyLimitLayer`. Requests exceeding the threshold are immediately failed with HTTP 503 before stream extraction or JSON deserialization can saturate the Tokio executor. ```rust use axum::{ error_handling::HandleErrorLayer, extract::DefaultBodyLimit, http::StatusCode, routing::post, BoxError, Json, Router, }; use serde::Deserialize; use tower::{limit::ConcurrencyLimitLayer, load_shed::LoadShedLayer, ServiceBuilder}; #[derive(Deserialize)] struct HeavyPayload { data: Vec<u8>, } async fn compute(Json(payload): Json<HeavyPayload>) -> &'static str { let _ = payload.data.len(); "ok" } async fn handle_shed_error(err: BoxError) -> (StatusCode, &'static str) { if err.is::<tower::load_shed::error::Overloaded>() { (StatusCode::SERVICE_UNAVAILABLE, "Server overloaded: request shed") } else { (StatusCode::INTERNAL_SERVER_ERROR, "Internal service error") } } pub fn app() -> Router { let middleware = ServiceBuilder::new() .layer(HandleErrorLayer::new(handle_shed_error)) .layer(LoadShedLayer::new()) .layer(ConcurrencyLimitLayer::new(1024)) .layer(DefaultBodyLimit::max(2 * 1024 * 1024)); Router::new() .route("/compute", post(compute)) .layer(middleware) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Tower Service Load-Shedding Backpressure Invariant

Axum 0.8 Tower Service Load-Shedding Backpressure Invariant defines an industrial-grade behavioral standard for backend engineering. Protects Tokio work-stealing thread pools from executor saturation by enforcing bounded buffer drop policies before request deserialization. Mandates placement of Tower load shedding and concurrency limit layers at the outermost edge of Axum 0.8 routers with explicit 503 Service Unavailable mapping. 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: Deserializing Payloads or Buffering In-Flight Requests Without Upstream Edge Load-Shedding 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	Deserializing Payloads or Buffering In-Flight Requests Without Upstream Edge Load-Shedding	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 place Tower `LoadShedLayer` and `ConcurrencyLimitLayer` upstream of request body extractors to drop excessive traffic prior to allocating memory or executing deserialization logic.

Engineers MUST ALWAYS place Tower `LoadShedLayer` and `ConcurrencyLimitLayer` upstream of request body extractors to drop excessive traffic prior to allocating memory or executing deserialization logic.

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.