FastAPI AnyIO TaskGroup Structured Concurrency & Cancellation Isolation

--- description: FastAPI AnyIO TaskGroup Structured Concurrency & Cancellation Isolation - Enforces deterministic teardown and structured concurrency isolation for AnyIO task groups within FastAPI route handlers when client disconnects occur. Mandates explicit cancellation shielding for non-idempotent operations and prevents AnyIO cancellation exceptions from corrupting shared worker thread pools or leaking raw errors into ASGI middleware. globs: **/routes/**/*.py, **/api/**/*.py, **/endpoints/**/*.py, **/services/**/*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-anyio-taskgroup-cancellation-isolation" --- # FastAPI AnyIO TaskGroup Structured Concurrency & Cancellation Isolation > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning detached asyncio tasks or unshielded AnyIO TaskGroups that leak unhandled cancellation exceptions and leave thread-pool workers orphaned on client disconnect ## System Constraints You are a Principal Software Architect enforcing production-grade structured concurrency standards in FastAPI applications backed by AnyIO. You mandate deterministic task teardown on HTTP client disconnects, strict cancellation shielding for atomic operations, and rigorous isolation between ASGI request loops and thread-pool executors. ## Strict Guidelines - Engineers MUST ALWAYS scope concurrent async operations within an `anyio.create_task_group()` context block instead of spawning unmanaged `asyncio.create_task()` fire-and-forget coroutines. - Engineers MUST wrap non-interruptible side-effects, resource cleanups, or audit commits inside `anyio.CancelScope(shield=True)` to prevent torn states when a client aborts the connection. - Engineers MUST NOT allow `anyio.get_cancelled_exc_class()` or `asyncio.CancelledError` to propagate unhandled out of endpoints as 500 Internal Server Errors; graceful abort logging or clean HTTP 499 handling MUST be applied. - Code MUST pass `abandon_on_cancel=False` (or use bounded cancellation tokens) when dispatching blocking I/O via `anyio.to_thread.run_sync` to avoid thread exhaustion and orphaned connection checkouts. - Services MUST ensure that sub-tasks scheduled in a task group handle cancellation cooperatively through explicit checkpoints or non-blocking async primitives. - Components NEVER catch naked `Exception` blocks around TaskGroups without re-raising `anyio.get_cancelled_exc_class()` or extracting sub-exceptions from `ExceptionGroup` / `anyio.ExceptionGroup`. ## Bad vs Good Implementations ### Structured Concurrency and Cancellation Isolation in FastAPI Route #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using asyncio.create_task decouples lifecycle management from the ASGI request scope, risking orphan execution or silent failures. Catching bare Exception and converting to 500 swallows asyncio.CancelledError or bubbles up inappropriately. Thread dispatches via asyncio.to_thread cannot be tracked or shielded cleanly on premature disconnect. ```python import asyncio from fastapi import APIRouter, Depends, HTTPException from services.billing import process_payment from services.telemetry import log_metric router = APIRouter() @router.post("/checkout") async def checkout(order_id: str): try: # ANTI-PATTERN: Detached task spawns leak on disconnect. # If client disconnects, process_payment may be severed halfway or run unbounded, # and log_metric may never execute. Raw CancelledError crashes middleware. asyncio.create_task(log_metric("checkout_initiated", order_id)) # Unstructured thread dispatch without cancellation isolation result = await asyncio.to_thread(process_payment, order_id) return {"status": "completed", "result": result} except Exception as exc: # Swallows cancellation or emits 500 on client disconnect raise HTTPException(status_code=500, detail=str(exc)) ``` #### Production Standard (Correct) > **Standard**: Uses anyio.create_task_group for deterministic lifecycle binding. Blocking calls use anyio.to_thread.run_sync(abandon_on_cancel=False) to prevent pool corruption. If the client disconnects, the cancellation exception is explicitly caught and isolated; critical rollback/audit operations are safely executed under anyio.CancelScope(shield=True). ```python import anyio from fastapi import APIRouter, Request, status from fastapi.responses import JSONResponse from services.billing import process_payment_sync from services.telemetry import emit_audit_event router = APIRouter() @router.post("/checkout") async def checkout(request: Request, order_id: str): cancelled_exc = anyio.get_cancelled_exc_class() try: async with anyio.create_task_group() as tg: # Spawn cooperative telemetry within structured scope tg.start_soon(emit_audit_event, "checkout_initiated", order_id) # Execute sync work with cancellation awareness in managed thread pool # abandon_on_cancel=False guarantees the thread finishes safely before context exit result = await anyio.to_thread.run_sync( process_payment_sync, order_id, abandon_on_cancel=False ) return {"status": "completed", "result": result} except cancelled_exc: # Handle client disconnect gracefully without leaking unhandled exceptions with anyio.CancelScope(shield=True): # Shield critical cleanup and compensation logic from cancellation await emit_audit_event("checkout_aborted_by_client", order_id) return JSONResponse( status_code=499, # Client Closed Request content={"status": "aborted", "detail": "Client disconnected before completion"} ) ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI AnyIO TaskGroup Structured Concurrency & Cancellation Isolation

FastAPI AnyIO TaskGroup Structured Concurrency & Cancellation Isolation defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic teardown and structured concurrency isolation for AnyIO task groups within FastAPI route handlers when client disconnects occur. Mandates explicit cancellation shielding for non-idempotent operations and prevents AnyIO cancellation exceptions from corrupting shared worker thread pools or leaking raw errors into ASGI middleware. 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: Spawning detached asyncio tasks or unshielded AnyIO TaskGroups that leak unhandled cancellation exceptions and leave thread-pool workers orphaned on 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	Spawning detached asyncio tasks or unshielded AnyIO TaskGroups that leak unhandled cancellation exceptions and leave thread-pool workers orphaned on 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 scope concurrent async operations within an `anyio.create_task_group()` context block instead of spawning unmanaged `asyncio.create_task()` fire-and-forget coroutines.

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.