Axum 0.8 Tower Service Clone and Stateful Buffer Isolation Standard

--- description: Axum 0.8 Tower Service Clone and Stateful Buffer Isolation Standard - Enforces strict per-request state isolation when implementing custom Tower Service and Layer abstractions in Axum 0.8. Eliminates cross-request state contamination, unhandled backpressure deadlocks, and race conditions caused by shallow cloning internal buffers across Tokio's multi-threaded work-stealing runtime. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-0-8-tower-service-clone-isolation" --- # Axum 0.8 Tower Service Clone and Stateful Buffer Isolation Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Persisting Request Buffers or Mutable Context Across Tower Service Clones ## System Constraints You are a Principal Rust Systems Architect specializing in Axum 0.8 and the Tower Service ecosystem. You mandate strict state isolation between Service::clone instances, zero un-synchronized shared memory across Tokio worker threads, proper poll_ready propagation, and request-scoped buffer allocation to prevent cross-request contamination and memory leaks. ## Strict Guidelines - Engineers MUST ALWAYS implement Service<Request<B>> where request-specific buffers, accumulators, and scratch spaces are created strictly inside call(&mut self, req) or encapsulated in per-request futures. - Engineers MUST NOT store mutable per-request state (such as Vec<u8>, BytesMut, or un-synchronized counters) inside the Tower Service struct itself across Service::clone invocations. - Engineers MUST ensure that any state shared across Service clones is wrapped in immutable reference counts (Arc<T>) or thread-safe primitives (Arc<AtomicU64>, Arc<RwLock<T>>) intended strictly for cross-cutting telemetry or synchronized caches. - Custom Tower middleware MUST propagate readiness by calling this.inner.poll_ready(cx) in Service::poll_ready unless explicitly implementing a decoupling buffer or backpressure regulator. - Components NEVER assume Service::clone yields an independent logical session; Tower clones services to handle concurrent requests across Tokio worker threads concurrently. ## Bad vs Good Implementations ### Stateful Buffer Isolation in Custom Tower Middleware #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Storing `BytesMut` on the Service struct violates request isolation. In Axum, Tower services are cloned to handle concurrent requests across worker threads. Reusing or shallow-cloning stateful buffers corrupts request logs and risks data races or memory growth across requests. ```rust use std::task::{Context, Poll}; use tower::Service; use axum::extract::Request; use axum::response::Response; use bytes::BytesMut; #[derive(Clone)] pub struct StatefulLoggingService<S> { inner: S, // ANTI-PATTERN: Shared mutable buffer across clones or reused across invocations // When cloned across Tokio threads, this causes race conditions or reuses dirty buffers buffer: BytesMut, } impl<S> Service<Request> for StatefulLoggingService<S> where S: Service<Request, Response = Response> + Clone + Send + 'static, S::Future: Send + 'static, { type Response = S::Response; type Error = S::Error; type Future = S::Future; fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { self.inner.poll_ready(cx) } fn call(&mut self, req: Request) -> Self::Future { // Mutating struct-level buffer during request execution self.buffer.extend_from_slice(req.uri().path().as_bytes()); self.inner.call(req) } } ``` #### Production Standard (Correct) > **Standard**: By eliminating struct-level mutable buffers, the service becomes safe to clone across arbitrary Tokio runtime threads. Ephemeral request state is confined to `call` scope, and global coordination uses thread-safe atomics. ```rust use std::task::{Context, Poll}; use tower::Service; use axum::extract::Request; use axum::response::Response; use std::sync::Arc; use std::sync::atomic::{AtomicU64, Ordering}; #[derive(Clone)] pub struct IsolatedLoggingService<S> { inner: S, // Invariant: Shared state across clones is strictly read-only or thread-safe atomic telemetry global_metrics: Arc<AtomicU64>, } impl<S> Service<Request> for IsolatedLoggingService<S> where S: Service<Request, Response = Response> + Send + 'static, S::Future: Send + 'static, { type Response = S::Response; type Error = S::Error; type Future = S::Future; #[inline] fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { self.inner.poll_ready(cx) } fn call(&mut self, req: Request) -> Self::Future { self.global_metrics.fetch_add(1, Ordering::Relaxed); // Invariant: Ephemeral scratchpads or request data MUST be allocated locally // within call() or inside the returned future pinned frame let path = req.uri().path().to_owned(); let mut local_scratch = Vec::with_capacity(path.len()); local_scratch.extend_from_slice(path.as_bytes()); self.inner.call(req) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Tower Service Clone and Stateful Buffer Isolation Standard

Axum 0.8 Tower Service Clone and Stateful Buffer Isolation Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict per-request state isolation when implementing custom Tower Service and Layer abstractions in Axum 0.8. Eliminates cross-request state contamination, unhandled backpressure deadlocks, and race conditions caused by shallow cloning internal buffers across Tokio's multi-threaded work-stealing runtime. 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: Persisting Request Buffers or Mutable Context Across Tower Service Clones 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	Persisting Request Buffers or Mutable Context Across Tower Service Clones	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 implement Service<Request<B>> where request-specific buffers, accumulators, and scratch spaces are created strictly inside call(&mut self, req) or encapsulated in per-request futures.

Engineers MUST ALWAYS implement Service<Request<B>> where request-specific buffers, accumulators, and scratch spaces are created strictly inside call(&mut self, req) or encapsulated in per-request futures.

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.