FastAPI AnyIO Client Disconnect Shielding & Atomic Pipeline Guardrail

--- description: FastAPI AnyIO Client Disconnect Shielding & Atomic Pipeline Guardrail - Enforces non-cancellable shielded scopes and deterministic cleanups in multi-step asynchronous database transactions under FastAPI. Prevents orphaned mutations, unreleased connection pool slots, and transaction leaks when upstream HTTP clients disconnect mid-pipeline. globs: app/**/*.py, src/**/*.py, api/**/*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-anyio-cancellation-shielding-standard" --- # FastAPI AnyIO Client Disconnect Shielding & Atomic Pipeline Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unshielded async transaction pipelines interrupted by client disconnects, causing orphaned mutations and DB pool starvation ## System Constraints You are a Principal Backend Architect enforcing strict AnyIO and asyncio cancellation safety across all FastAPI transaction pipelines. You mandate that critical mutation boundaries and cleanup routines are explicitly shielded from client disconnect cancellations to prevent data corruption and database connection pool exhaustion. ## Strict Guidelines - Engineers MUST ALWAYS wrap atomic multi-step mutations and transactional cleanup logic in an explicit shielded scope using `anyio.CancelScope(shield=True)` or guarded TaskGroups when client cancellation could leave inconsistent state. - Engineers MUST NOT allow raw `asyncio.CancelledError` or AnyIO cancellations to abort active database transactions without triggering deterministic rollbacks within an active shield. - Code SHOULD decouple upstream client request lifecycles from critical background operations (e.g., billing, audit logs, dual-writes) by dispatching critical work through shielded task groups or worker queues. - Services MUST guarantee that database sessions and connections are closed or returned to the pool in a shielded `finally` block or context manager resilient to cancellation exceptions. - Components NEVER execute multi-step distributed operations (e.g., reserve inventory -> call payment gateway -> record order) in an open, unshielded coroutine susceptible to mid-flight client TCP disconnects. ## Bad vs Good Implementations ### Unshielded Multi-Step Transaction vs. Shielded AnyIO Rollback Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When an HTTP client aborts the connection during `external_payment_service.charge()`, AnyIO/asyncio raises a cancellation error at the await point. Execution aborts immediately, leaving the database transaction in limbo, potentially leaking connection pool slots, and causing orphaned side effects where money is charged but the order is never confirmed or rolled back. ```python from fastapi import APIRouter, Depends from sqlalchemy.ext.asyncio import AsyncSession from app.db import get_session from app.services import external_payment_service from app.models import Order router = APIRouter() @router.post("/orders") async def create_order(payload: dict, session: AsyncSession = Depends(get_session)): # Step 1: Pending order saved to DB order = Order(user_id=payload["user_id"], status="PENDING") session.add(order) await session.flush() # ANTI-PATTERN: If client disconnects here, CancelledError is raised. # The transaction remains unhandled or connection pool hangs until garbage collected. # The payment might succeed downstream while DB state remains uncommitted. payment_result = await external_payment_service.charge(payload["token"], order.id) order.status = "CONFIRMED" await session.commit() return {"status": "ok", "order_id": order.id} ``` #### Production Standard (Correct) > **Standard**: Catches cancellation events triggered by client drops and executes compensating transactions and rollbacks inside an `anyio.CancelScope(shield=True)`. This guarantees that database connections return to the pool cleanly and side-effects are reconciled regardless of client network disruptions. ```python import anyio from fastapi import APIRouter, Depends, HTTPException from sqlalchemy.ext.asyncio import AsyncSession from app.db import get_session from app.services import external_payment_service from app.models import Order router = APIRouter() @router.post("/orders") async def create_order(payload: dict, session: AsyncSession = Depends(get_session)): async with session.begin(): order = Order(user_id=payload["user_id"], status="PENDING") session.add(order) await session.flush() payment_confirmed = False try: # Client disconnect cancellation can be caught and handled safely payment_result = await external_payment_service.charge(payload["token"], order.id) payment_confirmed = payment_result.is_successful except anyio.get_cancelled_exc_class(): # Client disconnected: Shield the compensation and rollback phase with anyio.CancelScope(shield=True): if payment_confirmed: await external_payment_service.refund(order.id) await session.rollback() raise except Exception: with anyio.CancelScope(shield=True): if payment_confirmed: await external_payment_service.refund(order.id) await session.rollback() raise HTTPException(status_code=502, detail="Transaction processing failed") # Shield finalizing commit logic with anyio.CancelScope(shield=True): order.status = "CONFIRMED" await session.commit() return {"status": "ok", "order_id": order.id} ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI AnyIO Client Disconnect Shielding & Atomic Pipeline Guardrail

FastAPI AnyIO Client Disconnect Shielding & Atomic Pipeline Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces non-cancellable shielded scopes and deterministic cleanups in multi-step asynchronous database transactions under FastAPI. Prevents orphaned mutations, unreleased connection pool slots, and transaction leaks when upstream HTTP clients disconnect mid-pipeline. 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 async transaction pipelines interrupted by client disconnects, causing orphaned mutations and DB pool starvation 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 async transaction pipelines interrupted by client disconnects, causing orphaned mutations and DB pool starvation	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 wrap atomic multi-step mutations and transactional cleanup logic in an explicit shielded scope using `anyio.CancelScope(shield=True)` or guarded TaskGroups when client cancellation could leave inconsistent state.

Engineers MUST ALWAYS wrap atomic multi-step mutations and transactional cleanup logic in an explicit shielded scope using `anyio.CancelScope(shield=True)` or guarded TaskGroups when client cancellation could leave inconsistent state.

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.