FastAPI AnyIO Structured TaskGroup Lifecycle & Orphan Mitigation Guardrail

--- description: FastAPI AnyIO Structured TaskGroup Lifecycle & Orphan Mitigation Guardrail - Guarantees that all concurrent subtasks spawned during a FastAPI request are managed via AnyIO TaskGroups strictly bounded to the HTTP connection lifecycle. Prevents unbounded background task execution, lingering database connection locks, and memory leaks caused by client disconnects or unhandled task exceptions. 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-cancellation-guardrail" --- # FastAPI AnyIO Structured TaskGroup Lifecycle & Orphan Mitigation Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning Unstructured Asyncio Background Tasks Within FastAPI Endpoints ## System Constraints You are a Principal Backend Architect enforcing structured concurrency standards in FastAPI using AnyIO. You mandate that no concurrent subtask ever escapes its parent request boundary. You prohibit `asyncio.create_task` or detached `asyncio.gather` for request-dependent workflows, enforcing `anyio.create_task_group` context managers with explicit cancellation propagation, shielding guards, and deterministic teardown. ## Strict Guidelines - Engineers MUST ALWAYS encapsulate concurrent child operations in an `anyio.create_task_group()` context block tied directly to the endpoint handler scope. - Engineers MUST NOT utilize `asyncio.create_task` inside request handlers unless explicitly registered with a durable background worker or framework-level BackgroundTasks queue. - Code MUST handle `anyio.get_cancelled_exc_class()` explicitly or permit cancellation exceptions to bubble up unimpeded to ensure clean TaskGroup teardown. - Services MUST wrap non-cancellable critical teardown routines (such as auditing or releasing distributed locks) in `anyio.CancelScope(shield=True)`. - Components NEVER swallow cancellation exceptions with generic `except Exception:` blocks without re-raising. ## Bad vs Good Implementations ### Unstructured Fire-and-Forget vs. AnyIO Structured TaskGroup #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using asyncio.create_task detaches child tasks from the FastAPI request scope. If the client disconnects or an exception occurs, fetch_enrichment and log_audit_trail continue executing, leaking connections and compute. ```python import asyncio from fastapi import FastAPI, HTTPException app = FastAPI() async def fetch_enrichment(item_id: str) -> dict: await asyncio.sleep(2.0) return {"enriched": item_id} async def log_audit_trail(item_id: str) -> None: await asyncio.sleep(1.0) # Write to external service @app.get("/items/{item_id}") async def get_item(item_id: str): # Anti-Pattern: create_task creates unmonitored orphans. # If client disconnects, task continues executing indefinitely, # leaking database sessions, sockets, and memory. asyncio.create_task(log_audit_trail(item_id)) data_task = asyncio.create_task(fetch_enrichment(item_id)) result = await data_task return {"status": "ok", "data": result} ``` #### Production Standard (Correct) > **Standard**: AnyIO create_task_group binds subtask lifecycles directly to the request scope. If the client aborts or an exception is raised, child tasks are immediately cancelled, preventing orphan processes and socket leakage. ```python import anyio from fastapi import FastAPI, Request app = FastAPI() async def fetch_enrichment(item_id: str) -> dict: await anyio.sleep(2.0) return {"enriched": item_id} async def log_audit_trail(item_id: str) -> None: # Non-cancellable critical write shielded from parent cancellation with anyio.CancelScope(shield=True): await anyio.sleep(1.0) @app.get("/items/{item_id}") async def get_item(item_id: str, request: Request): enrichment_result: dict = {} async def _fetch(): nonlocal enrichment_result enrichment_result = await fetch_enrichment(item_id) # Invariant: Structured TaskGroup guarantees both tasks are cancelled # or completely finalized before HTTP handler exit. async with anyio.create_task_group() as tg: tg.start_soon(_fetch) tg.start_soon(log_audit_trail, item_id) return {"status": "ok", "data": enrichment_result} ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI AnyIO Structured TaskGroup Lifecycle & Orphan Mitigation Guardrail

FastAPI AnyIO Structured TaskGroup Lifecycle & Orphan Mitigation Guardrail defines an industrial-grade behavioral standard for backend engineering. Guarantees that all concurrent subtasks spawned during a FastAPI request are managed via AnyIO TaskGroups strictly bounded to the HTTP connection lifecycle. Prevents unbounded background task execution, lingering database connection locks, and memory leaks caused by client disconnects or unhandled task exceptions. 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 Unstructured Asyncio Background Tasks Within FastAPI 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	Spawning Unstructured Asyncio Background Tasks Within FastAPI 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 encapsulate concurrent child operations in an `anyio.create_task_group()` context block tied directly to the endpoint handler scope.

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.