FastAPI AnyIO Structured TaskGroup Request-Cancellation Boundary

--- description: FastAPI AnyIO Structured TaskGroup Request-Cancellation Boundary - Enforces strict structured concurrency using AnyIO TaskGroups within FastAPI request lifecycles to guarantee immediate, deterministic teardown of all spawned coroutines upon client HTTP disconnects. Prevents orphaned background tasks, runaway resource consumption, and stale uncommitted database transactions by binding all asynchronous child operations to the ASGI cancellation boundary. 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-structured-taskgroup-cancellation" --- # FastAPI AnyIO Structured TaskGroup Request-Cancellation Boundary > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unstructured asyncio.create_task Fire-and-Forget Spawning In HTTP Request Handlers ## System Constraints You are a Principal Engineer enforcing the FastAPI AnyIO Structured TaskGroup Request-Cancellation Boundary. Mandate strict structured concurrency invariants: disallow unstructured `asyncio.create_task`, require `anyio.create_task_group()` context boundaries within request scopes, and ensure database transactions cleanly roll back when an ASGI `http.disconnect` propagates `asyncio.CancelledError`. ## Strict Guidelines - Engineers MUST ALWAYS encapsulate multiple concurrent asynchronous operations within an `anyio.create_task_group()` context manager inside FastAPI route handlers. - Engineers MUST NOT invoke `asyncio.create_task()` or `asyncio.gather()` directly within request-scoped handlers for concurrent operations, as these bypass parent task group cancellation trees and leak execution upon client disconnect. - Code MUST ensure that database session contexts (e.g., SQLAlchemy AsyncSession or asyncpg transactions) wrap the `anyio.create_task_group()` block or run entirely within a single task boundary to ensure deterministic rollback on `asyncio.CancelledError` or AnyIO exception propagation. - Services MUST explicitly declare background tasks through FastAPI's built-in `BackgroundTasks` abstraction or an external durable queue (e.g., Celery, ARQ) ONLY if execution is intended to outlive the client's HTTP request lifecycle. - Components NEVER suppress `asyncio.CancelledError` or `anyio.get_cancelled_exc_class()` using generic `except Exception:` blocks; cancellation exceptions must either be re-raised immediately or allowed to propagate to trigger deterministic task teardown. ## Bad vs Good Implementations ### Structured Concurrency vs. Unstructured Task Spawning on Client Disconnect #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using asyncio.create_task and asyncio.gather creates unstructured coroutines. If the HTTP client disconnects before completion, Starlette cancels the root request handler, but the child tasks can continue executing detached, causing unmonitored queries, connection pool exhaustion, and race conditions. ```python import asyncio from fastapi import FastAPI, Depends from sqlalchemy.ext.asyncio import AsyncSession from app.db import get_db_session from app.services import fetch_metrics, audit_log app = FastAPI() @app.get("/analytics/{user_id}") async def get_analytics(user_id: str, db: AsyncSession = Depends(get_db_session)): # Anti-Pattern: create_task escapes ASGI cancellation scope # If the client disconnects, these continue running, mutating DB or holding connections task1 = asyncio.create_task(fetch_metrics(user_id)) task2 = asyncio.create_task(audit_log(db, user_id, "view_analytics")) try: metrics, _ = await asyncio.gather(task1, task2) return {"status": "ok", "metrics": metrics} except Exception as exc: # Generic catch swallows cancellation and leaves orphaned tasks running in background return {"status": "error", "detail": str(exc)} ``` #### Production Standard (Correct) > **Standard**: anyio.create_task_group() enforces structured concurrency. If the client disconnects, AnyIO propagates the cancellation signal to all active child tasks, terminates them cleanly, and exits the SQLAlchemy async transaction context, triggering an immediate and deterministic database rollback. ```python import anyio from fastapi import FastAPI, Depends from sqlalchemy.ext.asyncio import AsyncSession from app.db import get_db_session from app.services import fetch_metrics, audit_log app = FastAPI() @app.get("/analytics/{user_id}") async def get_analytics(user_id: str, db: AsyncSession = Depends(get_db_session)): metrics_result = {} # Invariant: anyio.create_task_group guarantees cancellation propagation # If client disconnects, the task group immediately cancels all child tasks async with db.begin(): async with anyio.create_task_group() as tg: async def run_metrics(): metrics_result["data"] = await fetch_metrics(user_id) async def run_audit(): await audit_log(db, user_id, "view_analytics") tg.start_soon(run_metrics) tg.start_soon(run_audit) return {"status": "ok", "metrics": metrics_result.get("data")} ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI AnyIO Structured TaskGroup Request-Cancellation Boundary

FastAPI AnyIO Structured TaskGroup Request-Cancellation Boundary defines an industrial-grade behavioral standard for backend engineering. Enforces strict structured concurrency using AnyIO TaskGroups within FastAPI request lifecycles to guarantee immediate, deterministic teardown of all spawned coroutines upon client HTTP disconnects. Prevents orphaned background tasks, runaway resource consumption, and stale uncommitted database transactions by binding all asynchronous child operations to the ASGI cancellation boundary. 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: Unstructured asyncio.create_task Fire-and-Forget Spawning In HTTP Request 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	Unstructured asyncio.create_task Fire-and-Forget Spawning In HTTP Request 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 multiple concurrent asynchronous operations within an `anyio.create_task_group()` context manager inside FastAPI route handlers.

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.