FastAPI AnyIO TaskGroup Lifetime Boundaries & Python 3.12+ ExceptionGroup Handling

--- description: FastAPI AnyIO TaskGroup Lifetime Boundaries & Python 3.12+ ExceptionGroup Handling - Enforces strict structured concurrency using AnyIO TaskGroups within FastAPI request-response lifecycles to prevent coroutine leakage during concurrent fan-out. Mandates Python 3.12+ except* syntax or explicit ExceptionGroup unwrapping to safely handle partial failures without leaving orphaned background tasks running on the event loop. globs: app/**/*.py, src/**/*.py, api/**/*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-taskgroup-structured-concurrency-standard" --- # FastAPI AnyIO TaskGroup Lifetime Boundaries & Python 3.12+ ExceptionGroup Handling > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded asyncio.create_task Fan-Out and Broad Exception Swallowing in Concurrent Endpoints ## System Constraints You are a Principal Backend Architect enforcing strict structured concurrency and resilient RPC fan-out patterns in FastAPI services. Mandate AnyIO TaskGroup lifetime boundaries, proper exception group unwrapping, and zero-coroutine-leak policies across all asynchronous endpoints. ## Strict Guidelines - Engineers MUST ALWAYS bound concurrent RPC calls within an 'async with anyio.create_task_group() as tg:' context block rather than spawning unmanaged background tasks with asyncio.create_task. - Engineers MUST NOT catch base 'Exception' directly around a TaskGroup block when running Python 3.12+; handlers MUST use 'except*' syntax to selectively extract and unwrap constituent sub-exceptions. - Route handlers MUST ensure that any TaskGroup error automatically triggers sibling cancellation, enforcing fail-fast semantics across all fanned-out child tasks. - Services MUST map unwrapped upstream exceptions into concrete FastAPI HTTPException status codes (e.g., 502 Bad Gateway or 504 Gateway Timeout) instead of bubbling unhandled ExceptionGroups to Starlette's top-level 500 handler. - Components NEVER start detached background processing inside an HTTP handler without passing an explicit background runner, BackgroundTasks abstraction, or out-of-process job queue. ## Bad vs Good Implementations ### RPC Fan-Out: Unmanaged asyncio.create_task vs. AnyIO TaskGroup with except* #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using unmanaged asyncio.create_task with asyncio.gather does not enforce strict lexical task lifetimes. If one task fails, remaining sibling tasks can continue running invisibly on the event loop. Catching bare Exception obscures the underlying causes and fails to properly cancel outstanding tasks. ```python import asyncio from fastapi import APIRouter, HTTPException router = APIRouter() async def fetch_user(uid: str) -> dict: await asyncio.sleep(0.1) return {"id": uid, "role": "user"} async def fetch_permissions(uid: str) -> list[str]: await asyncio.sleep(0.2) raise ConnectionError("Permission service unavailable") @router.get("/users/{uid}/dashboard") async def get_dashboard(uid: str): # ANTI-PATTERN: Detached task creation and naive asyncio.gather without structured teardown # If fetch_permissions fails, fetch_user may continue running as an orphan. # Swallowing generic Exception hides specific multi-task failures. try: t1 = asyncio.create_task(fetch_user(uid)) t2 = asyncio.create_task(fetch_permissions(uid)) user, perms = await asyncio.gather(t1, t2) return {"user": user, "permissions": perms} except Exception as e: # Fails to isolate task failures; leaves potential leaked coroutines raise HTTPException(status_code=500, detail=str(e)) ``` #### Production Standard (Correct) > **Standard**: AnyIO TaskGroup binds child coroutines to the lexical context. If any task raises, the TaskGroup cancels all sibling tasks immediately, preventing orphan coroutines. Python 3.12+ 'except*' cleanly handles the resulting ExceptionGroup and converts upstream issues into appropriate HTTP status codes. ```python import anyio from fastapi import APIRouter, HTTPException, status router = APIRouter() async def fetch_user(uid: str, container: dict) -> None: await anyio.sleep(0.1) container["user"] = {"id": uid, "role": "user"} async def fetch_permissions(uid: str, container: dict) -> None: await anyio.sleep(0.2) raise ConnectionError("Permission service unreachable") @router.get("/users/{uid}/dashboard") async def get_dashboard(uid: str): results: dict = {} # PRODUCTION FIX: AnyIO TaskGroup guarantees bounded lifecycle & sibling cancellation try: async with anyio.create_task_group() as tg: tg.start_soon(fetch_user, uid, results) tg.start_soon(fetch_permissions, uid, results) except* ConnectionError as eg: # Python 3.12+ except* syntax unwraps ExceptionGroup without masking errors raise HTTPException( status_code=status.HTTP_502_BAD_GATEWAY, detail=f"Upstream dependency failed: {eg.exceptions[0]}" ) except* TimeoutError: raise HTTPException( status_code=status.HTTP_504_GATEWAY_TIMEOUT, detail="Upstream RPC timed out" ) return results ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI AnyIO TaskGroup Lifetime Boundaries & Python 3.12+ ExceptionGroup Handling

FastAPI AnyIO TaskGroup Lifetime Boundaries & Python 3.12+ ExceptionGroup Handling defines an industrial-grade behavioral standard for backend engineering. Enforces strict structured concurrency using AnyIO TaskGroups within FastAPI request-response lifecycles to prevent coroutine leakage during concurrent fan-out. Mandates Python 3.12+ except* syntax or explicit ExceptionGroup unwrapping to safely handle partial failures without leaving orphaned background tasks running on the event loop. 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 asyncio.create_task Fan-Out and Broad Exception Swallowing in Concurrent Endpoints 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 asyncio.create_task Fan-Out and Broad Exception Swallowing in Concurrent Endpoints	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 bound concurrent RPC calls within an 'async with anyio.create_task_group() as tg

Engineers MUST ALWAYS bound concurrent RPC calls within an 'async with anyio.create_task_group() as tg:' context block rather than spawning unmanaged background tasks with asyncio.create_task.

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.