FastAPI AnyIO Cancellation Shielding and Connection Drain Invariant

--- description: FastAPI AnyIO Cancellation Shielding and Connection Drain Invariant - Enforces strict cancellation boundaries and deterministic connection draining in FastAPI services running on AnyIO/asyncio. Prevents orphaned mutations, partial transactional states, and thread pool starvation caused by unhandled client disconnections and mid-flight ASGI task cancellations. globs: app/**/*.py, src/**/*.py, api/**/*.py, **/*_router.py, **/*_service.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-anyio-cancellation-shielding-drain-guardrail" --- # FastAPI AnyIO Cancellation Shielding and Connection Drain Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unshielded Multi-Step Asynchronous Mutations and Unprotected Thread Worker Dispatches Under Client Disconnect ## System Constraints You are a Principal Software Architect enforcing rigorous ASGI cancellation safety, AnyIO cancellation shielding, and resource drain invariants in FastAPI applications. Every asynchronous endpoint and service layer performing non-idempotent operations, multi-stage database transactions, external payment/webhook interactions, or thread pool delegation MUST isolate cancellation boundaries to prevent corrupted state, hung sockets, and thread pool exhaustion. ## Strict Guidelines - Engineers MUST ALWAYS isolate critical, non-abortable mutation steps (such as transactional database commits, financial ledger writes, and external state synchronization) inside an explicit `anyio.CancelScope(shield=True)` block when a cancellation halfway through would leave state inconsistent. - Engineers MUST NOT run blocking synchronous I/O or CPU-bound tasks via `anyio.to_thread.run_sync` inside a cancellable scope without explicit timeout protection and clean termination flags, avoiding thread worker saturation upon ASGI client abort. - Engineers MUST ensure that any response streaming or incoming body draining explicitly catches `anyio.get_cancelled_exc_class()` to finalize database sessions, release acquired semaphores, and close open streams in a dedicated `finally` or shielded cleanup block. - Services MUST NEVER allow a client disconnection during an external charge or remote write to terminate the handler before persisting an audit trail, rollback record, or reconciliation marker to the local database. - Components performing long-running background continuation MUST decouple from the request lifecycle by explicitly spawning detached tasks via a root-scoped `TaskGroup` or pushing to a durable task broker, rather than relying on ASGI handler continuation. ## Bad vs Good Implementations ### Non-Atomic Multi-Step Order Processing on Client Disconnect vs Shielded Cancellation Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Client disconnection during the window between payment capture and the database commit raises an unhandled cancellation error (`asyncio.CancelledError` via AnyIO). This abruptly terminates the coroutine, abandoning the transaction and resulting in a silent critical state divergence where money was deducted from the client without updating internal inventory and order state. ```python import anyio from fastapi import APIRouter, Depends, HTTPException, status from sqlalchemy.ext.asyncio import AsyncSession router = APIRouter() @router.post("/orders/{order_id}/checkout") async def checkout_order(order_id: str, db: AsyncSession = Depends(get_db)): # Anti-Pattern: If client closes socket during payment processing or ledger write, # ASGI cancellation aborts the coroutine midway, leaving the payment captured without a committed order. order = await db.get(Order, order_id) if not order or order.status != "pending": raise HTTPException(status_code=400, detail="Invalid order status") # Vulnerable: external side-effect runs without shielding charge_receipt = await payment_gateway.capture_charge(order.amount_cents) # If the client disconnects HERE, CancelledError terminates the coroutine. # The customer was billed, but the order is never marked as paid in the database. order.status = "paid" order.payment_intent_id = charge_receipt.id await db.commit() return {"status": "confirmed", "receipt": charge_receipt.id} ``` #### Production Standard (Correct) > **Standard**: By wrapping the local database commit and audit dispatch inside `anyio.CancelScope(shield=True)`, the critical post-charge reconciliation steps are protected against ASGI cancellations triggered by premature client disconnections, guaranteeing zero state divergence and deterministic execution. ```python import anyio from fastapi import APIRouter, Depends, HTTPException, status from sqlalchemy.ext.asyncio import AsyncSession router = APIRouter() @router.post("/orders/{order_id}/checkout") async def checkout_order(order_id: str, db: AsyncSession = Depends(get_db)): order = await db.get(Order, order_id) if not order or order.status != "pending": raise HTTPException(status_code=400, detail="Invalid order status") charge_receipt = None try: charge_receipt = await payment_gateway.capture_charge(order.amount_cents) except anyio.get_cancelled_exc_class(): # Client disconnected during payment initiation; verify upstream state or mark for reconciliation await payment_gateway.reconcile_abort(order.id) raise # Invariant: Once charge_receipt is acquired, state reconciliation MUST run to completion. # CancelScope(shield=True) guarantees immunity from client disconnection cancellation. with anyio.CancelScope(shield=True): order.status = "paid" order.payment_intent_id = charge_receipt.id await db.commit() await db.refresh(order) await audit_logger.log_event("order.checkout_completed", order_id=order.id) return {"status": "confirmed", "receipt": charge_receipt.id} ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI AnyIO Cancellation Shielding and Connection Drain Invariant

FastAPI AnyIO Cancellation Shielding and Connection Drain Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces strict cancellation boundaries and deterministic connection draining in FastAPI services running on AnyIO/asyncio. Prevents orphaned mutations, partial transactional states, and thread pool starvation caused by unhandled client disconnections and mid-flight ASGI task cancellations. 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: Unshielded Multi-Step Asynchronous Mutations and Unprotected Thread Worker Dispatches Under Client Disconnect 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	Unshielded Multi-Step Asynchronous Mutations and Unprotected Thread Worker Dispatches Under Client Disconnect	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 isolate critical, non-abortable mutation steps (such as transactional database commits, financial ledger writes, and external state synchronization) inside an explicit `anyio.CancelScope(shield=True)` block when a cancellation halfway through would leave state inconsistent.

Engineers MUST ALWAYS isolate critical, non-abortable mutation steps (such as transactional database commits, financial ledger writes, and external state synchronization) inside an explicit `anyio.CancelScope(shield=True)` block when a cancellation halfway through would leave state inconsistent.

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.