FastAPI Async Cancellation Shield and Structured TaskGroup Guardrail

--- description: FastAPI Async Cancellation Shield and Structured TaskGroup Guardrail - Enforces strict asynchronous cancellation boundaries and structured concurrency across FastAPI handlers when client streams or HTTP/3 sessions disconnect mid-flight. Prevents orphaned background tasks, unclosed SQLAlchemy/asyncpg transactions, and inconsistent external state mutation by mandating asyncio.shield on critical sections and asyncio.TaskGroup for child task lifecycles. globs: app/**/*.py, src/**/*.py, services/**/*.py, routers/**/*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-async-cancellation-shield-taskgroup-guardrail" --- # FastAPI Async Cancellation Shield and Structured TaskGroup Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unshielded Database Mutations and Naked asyncio.create_task Inside Client-Cancellable Route Handlers ## System Constraints You are a Principal Backend Architect enforcing structured async concurrency and cancellation boundaries in FastAPI applications. You must prevent unmanaged transaction leaks and orphaned coroutines caused by client disconnections, stream resets, and ASGI cancellation propagation. ## Strict Guidelines - Engineers MUST ALWAYS encapsulate non-idempotent commits, financial mutations, and critical DB transactions within an `asyncio.shield()` boundary to guarantee completion or controlled rollback upon client stream cancellation. - Engineers MUST NOT invoke fire-and-forget background operations using naked `asyncio.create_task()` directly in route handlers without attaching them to a supervised task supervisor or structured `asyncio.TaskGroup`. - Code SHOULD leverage Python 3.11+ `asyncio.TaskGroup` for spawning and coordinating concurrent subtasks so that cancellation bubbles uniformly without leaving unmonitored dangling tasks. - Services MUST ensure database context managers (`async with session.begin():`) are evaluated under explicit cancellation shields if a partial commit can result in split-brain data corruption when `asyncio.CancelledError` is injected. - Components NEVER catch `asyncio.CancelledError` or `BaseException` silently without either re-raising the cancellation or running a mandatory cleanup routine within a shielded block. ## Bad vs Good Implementations ### Client Disconnection Handling with asyncio.shield and Structured TaskGroup #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: If the client resets the connection while waiting on async I/O inside `db.begin()`, `asyncio.CancelledError` is raised immediately. If the database driver is interrupted during commit/rollback, unmanaged state or connection pool exhaustion occurs. Furthermore, `asyncio.create_task` produces an unmonitored orphan task with no error boundary or supervisor. ```python import asyncio from fastapi import APIRouter, Depends from sqlalchemy.ext.asyncio import AsyncSession from app.db import get_session router = APIRouter() @router.post("/orders/{order_id}/settle") async def settle_order(order_id: str, db: AsyncSession = Depends(get_session)): # ANTI-PATTERN: Client stream cancellation (HTTP/3 reset) raises asyncio.CancelledError # mid-execution. Transaction is left in an indeterminate state, and the spawned email # task becomes an unmanaged orphan detached from any supervisor. async with db.begin(): await db.execute("UPDATE orders SET status = 'settled' WHERE id = :id", {"id": order_id}) await asyncio.sleep(0.05) # Window for client disconnect await db.execute("INSERT INTO ledger_entries (order_id) VALUES (:id)", {"id": order_id}) # Naked task spawn: If the loop shuts down or crashes, this orphan task leaks asyncio.create_task(send_confirmation_notification(order_id)) return {"status": "completed"} ``` #### Production Standard (Correct) > **Standard**: Critical writes are encapsulated in `_execute_atomic_settlement` and guarded by `asyncio.shield()`. If the client resets the stream, the DB operation is guaranteed to finish cleanly while the outer handler intercepts `CancelledError`, awaits the shielded execution, and properly re-raises. Asynchronous child routines are tracked inside an `asyncio.TaskGroup` to ensure deterministic task teardown without orphans. ```python import asyncio import logging from fastapi import APIRouter, Depends from sqlalchemy.ext.asyncio import AsyncSession from app.db import get_session from app.notifications import send_confirmation_notification logger = logging.getLogger(__name__) router = APIRouter() async def _execute_atomic_settlement(db: AsyncSession, order_id: str) -> None: async with db.begin(): await db.execute("UPDATE orders SET status = 'settled' WHERE id = :id", {"id": order_id}) await db.execute("INSERT INTO ledger_entries (order_id) VALUES (:id)", {"id": order_id}) @router.post("/orders/{order_id}/settle") async def settle_order(order_id: str, db: AsyncSession = Depends(get_session)): # PRODUCTION FIX: Protect critical non-idempotent DB state mutation with asyncio.shield. # Even if HTTP/3 cancels the outer coroutine, the DB transaction finishes atomically. settlement_coro = _execute_atomic_settlement(db, order_id) shielded_settlement = asyncio.shield(settlement_coro) try: await shielded_settlement except asyncio.CancelledError: logger.warning(f"Client cancelled request during order settlement: {order_id}") # Wait for the shielded critical section to cleanly resolve before propagating await shielded_settlement raise # Use Python 3.11+ TaskGroup for deterministic child task cleanup try: async with asyncio.TaskGroup() as tg: tg.create_task(send_confirmation_notification(order_id)) except* Exception as eg: logger.error(f"Background post-settlement task failed: {eg.exceptions}") return {"status": "completed"} ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI Async Cancellation Shield and Structured TaskGroup Guardrail

FastAPI Async Cancellation Shield and Structured TaskGroup Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces strict asynchronous cancellation boundaries and structured concurrency across FastAPI handlers when client streams or HTTP/3 sessions disconnect mid-flight. Prevents orphaned background tasks, unclosed SQLAlchemy/asyncpg transactions, and inconsistent external state mutation by mandating asyncio.shield on critical sections and asyncio.TaskGroup for child task lifecycles. 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 Database Mutations and Naked asyncio.create_task Inside Client-Cancellable Route 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	Unshielded Database Mutations and Naked asyncio.create_task Inside Client-Cancellable Route 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 encapsulate non-idempotent commits, financial mutations, and critical DB transactions within an `asyncio.shield()` boundary to guarantee completion or controlled rollback upon client stream cancellation.

Engineers MUST ALWAYS encapsulate non-idempotent commits, financial mutations, and critical DB transactions within an `asyncio.shield()` boundary to guarantee completion or controlled rollback upon client stream cancellation.

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.