FastAPI & AnyIO TaskGroup Structured Concurrency Guardrail

--- description: FastAPI & AnyIO TaskGroup Structured Concurrency Guardrail - Enforces strict structured concurrency in FastAPI request lifecycles using AnyIO TaskGroups to prevent orphaned child coroutines and leaked resources. Mandates that all concurrent fan-out operations remain bound to the request scope, ensuring immediate and clean cancellation cascading when a client disconnects or an upstream timeout occurs. 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-taskgroup-structured-concurrency" --- # FastAPI & AnyIO TaskGroup Structured Concurrency Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Fire-and-Forget asyncio.create_task Spawning Zombie Routines on Client Disconnect ## System Constraints You are a Principal Backend Architect enforcing strict structured concurrency in FastAPI applications using AnyIO. You must eliminate all instances of unbounded, unmonitored async tasks (such as naked asyncio.create_task) spawned during HTTP request lifecycles. Ensure every concurrent sub-routine is enclosed in an anyio.create_task_group() or dedicated lifecycle-managed supervisor so that client disconnections immediately cancel all child coroutines and reclaim associated sockets, DB connections, and memory buffers. ## Strict Guidelines - Engineers MUST ALWAYS encapsulate concurrent fan-out operations inside an `async with anyio.create_task_group() as tg:` context block within the request lifecycle. - Engineers MUST NOT invoke `asyncio.create_task()` or `asyncio.ensure_future()` directly inside FastAPI endpoint handlers to perform ad-hoc request-dependent processing. - Code SHOULD handle `anyio.get_cancelled_exc_class()` or `asyncio.CancelledError` gracefully within child workers to release acquired mutexes, transactions, and pooled connections. - Services MUST monitor client disconnection via `await request.is_disconnected()` in long-polling or streaming endpoints to trigger immediate early cancellation of active task groups. - Components NEVER allow background persistence or deferred side effects to execute in unmanaged request tasks; durable background execution MUST use dedicated external worker queues (e.g., Celery, ARQ, SAQ) rather than dangling in-process coroutines. ## Bad vs Good Implementations ### Concurrent Fan-Out with AnyIO TaskGroup vs Naked asyncio.create_task #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using asyncio.create_task inside a request handler escapes the structured lifecycle. If the client disconnects or an upstream timeout trips before `await`, the spawned tasks continue running in the background as zombies, retaining database connections and consuming resources unnecessarily. ```python import asyncio from fastapi import APIRouter, HTTPException router = APIRouter() async def fetch_user_profile(user_id: str) -> dict: await asyncio.sleep(2) # Simulates remote I/O return {"id": user_id, "name": "Alice"} async def fetch_user_orders(user_id: str) -> list: await asyncio.sleep(2) # Simulates remote DB query return [{"order_id": 101, "total": 49.99}] @router.get("/users/{user_id}/dashboard-bad") async def get_user_dashboard(user_id: str): # ANTI-PATTERN: asyncio.create_task detaches execution from request cancellation. # If the client aborts or disconnects, these tasks continue executing to completion, # leaking threadpool/DB connection resources and burning compute. profile_task = asyncio.create_task(fetch_user_profile(user_id)) orders_task = asyncio.create_task(fetch_user_orders(user_id)) profile = await profile_task orders = await orders_task return {"profile": profile, "orders": orders} ``` #### Production Standard (Correct) > **Standard**: Using `anyio.create_task_group()` guarantees structured concurrency. If the client closes the connection or an exception is raised in one task, AnyIO automatically signals cancellation to all remaining tasks in the group, preventing orphaned executions. ```python import anyio from fastapi import APIRouter, Request, HTTPException router = APIRouter() async def fetch_user_profile(user_id: str, results: dict) -> None: # Automatically cancelled if parent task group cancels await anyio.sleep(2) results["profile"] = {"id": user_id, "name": "Alice"} async def fetch_user_orders(user_id: str, results: dict) -> None: await anyio.sleep(2) results["orders"] = [{"order_id": 101, "total": 49.99}] @router.get("/users/{user_id}/dashboard-good") async def get_user_dashboard(user_id: str, request: Request): results = {} try: # INVARIANT: AnyIO TaskGroup binds child routines to current request context. # If client disconnects or an exception occurs, all child tasks are cancelled promptly. async with anyio.create_task_group() as tg: tg.start_soon(fetch_user_profile, user_id, results) tg.start_soon(fetch_user_orders, user_id, results) except anyio.get_cancelled_exc_class(): # Client disconnected or timeout struck; cleanup happens cleanly raise HTTPException(status_code=499, detail="Client Closed Request") return results ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI & AnyIO TaskGroup Structured Concurrency Guardrail

FastAPI & AnyIO TaskGroup Structured Concurrency Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces strict structured concurrency in FastAPI request lifecycles using AnyIO TaskGroups to prevent orphaned child coroutines and leaked resources. Mandates that all concurrent fan-out operations remain bound to the request scope, ensuring immediate and clean cancellation cascading when a client disconnects or an upstream timeout occurs. 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: Unbounded Fire-and-Forget asyncio.create_task Spawning Zombie Routines 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	Unbounded Fire-and-Forget asyncio.create_task Spawning Zombie Routines 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 encapsulate concurrent fan-out operations inside an `async with anyio.create_task_group() as tg

Engineers MUST ALWAYS encapsulate concurrent fan-out operations inside an `async with anyio.create_task_group() as tg:` context block within the request lifecycle.

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.