FastAPI AnyIO Structured TaskGroup Cancellation and Shielded Resource Drain

--- description: FastAPI AnyIO Structured TaskGroup Cancellation and Shielded Resource Drain - Enforces AnyIO structured concurrency within FastAPI route lifecycles to guarantee deterministic cancellation cascading on client aborts. Mandates shielded cleanup scopes during task teardown to prevent connection leaks, orphaned coroutines, and corrupted resource drains. 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-drain" --- # FastAPI AnyIO Structured TaskGroup Cancellation and Shielded Resource Drain > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning unmanaged background coroutines and unshielded cleanup handlers during ASGI client disconnects. ## System Constraints You are a Principal Backend Architect enforcing strict structured concurrency and cancellation safety in FastAPI services powered by AnyIO. Mandate that all concurrent subtasks initiated within an ASGI request boundary are bounded by an AnyIO TaskGroup. Forbid raw asyncio.create_task and untracked coroutine scheduling. Ensure that all cancellation exceptions propagate cleanly and that teardown/drain routines are explicitly wrapped in shielded cancellation scopes to guarantee total resource reclamation. ## Strict Guidelines - Engineers MUST ALWAYS enclose concurrent child operations inside an `anyio.create_task_group()` context within the request lifecycle. - Engineers MUST NOT use `asyncio.create_task()` or unmanaged thread spawns inside FastAPI endpoint handlers or dependencies. - Code SHOULD guard critical teardown logic (e.g., releasing locks, draining queues, closing network sockets) using `with anyio.CancelScope(shield=True):` inside `finally` blocks. - Services MUST re-raise `anyio.get_cancelled_exc_class()` immediately and never silence cancellation exceptions inside generic `except Exception:` blocks. - Components NEVER assume child coroutines will finish running if the client disconnects; they must design worker tasks to be cancellation-safe and idempotent. ## Bad vs Good Implementations ### Unbounded coroutine spawn with unshielded teardown vs AnyIO TaskGroup with shielded drain #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using asyncio.create_task detaches execution from FastAPI's ASGI request scope, causing orphaned worker coroutines that ignore client drops. Furthermore, the finally block is unshielded, meaning an incoming cancellation during client abort will terminate release_transient_connection mid-stream, leaking connection pool slots. ```python import asyncio from fastapi import APIRouter, HTTPException router = APIRouter() async def process_item(item_id: str): # Simulate slow streaming or processing await asyncio.sleep(5) @router.post("/items/{item_id}/process") async def start_processing(item_id: str): # ANTI-PATTERN: Fire-and-forget task escapes ASGI lifecycle. # If the client disconnects, this task continues indefinitely or leaks. asyncio.create_task(process_item(item_id)) # ANTI-PATTERN: Teardown is unshielded; client abort terminates teardown mid-execution try: return {"status": "enqueued"} finally: # Leaks connection if CancelledError triggers during socket release await release_transient_connection(item_id) ``` #### Production Standard (Correct) > **Standard**: The AnyIO TaskGroup binds worker coroutines to the request lifecycle. If the client disconnects or an error occurs, AnyIO deterministically cancels all active child tasks within the group. The finally cleanup block runs inside a shielded CancelScope, guaranteeing database and network resources are cleanly drained and closed despite the active cancellation signal. ```python import anyio from fastapi import APIRouter, Request, status from app.core.resources import acquire_transient_connection, release_transient_connection router = APIRouter() async def worker_task(item_id: str, cancel_scope: anyio.CancelScope): # Structured child worker respecting cancellation scope await anyio.sleep(5) @router.post("/items/{item_id}/process", status_code=status.HTTP_202_ACCEPTED) async def start_processing(item_id: str, request: Request): conn = await acquire_transient_connection(item_id) try: # Structured taskgroup guarantees all tasks cancel if client aborts async with anyio.create_task_group() as tg: tg.start_soon(worker_task, item_id, tg.cancel_scope) return {"status": "processing"} finally: # CRITICAL: Shield cancellation during cleanup to guarantee full resource drain with anyio.CancelScope(shield=True): await release_transient_connection(conn) ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI AnyIO Structured TaskGroup Cancellation and Shielded Resource Drain

FastAPI AnyIO Structured TaskGroup Cancellation and Shielded Resource Drain defines an industrial-grade behavioral standard for backend engineering. Enforces AnyIO structured concurrency within FastAPI route lifecycles to guarantee deterministic cancellation cascading on client aborts. Mandates shielded cleanup scopes during task teardown to prevent connection leaks, orphaned coroutines, and corrupted resource drains. 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 unmanaged background coroutines and unshielded cleanup handlers during ASGI client disconnects. 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 unmanaged background coroutines and unshielded cleanup handlers during ASGI client disconnects.	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 enclose concurrent child operations inside an `anyio.create_task_group()` context 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.