FastAPI 0.115+ AnyIO Lifespan TaskGroup Cancellation Boundary

--- description: FastAPI 0.115+ AnyIO Lifespan TaskGroup Cancellation Boundary - Enforces structured concurrency boundaries within FastAPI 0.115+ lifespan handlers by mandating `anyio.create_task_group()` for all background coroutines. Prohibits unstructured `asyncio.create_task()` execution that bypasses lifespan cancellation scopes, preventing orphaned coroutines, unhandled exceptions, and deadlocks during SIGTERM graceful draining. globs: app/**/*.py, src/**/*.py, main.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-anyio-lifespan-taskgroup-boundary" --- # FastAPI 0.115+ AnyIO Lifespan TaskGroup Cancellation Boundary > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning Unbound Lifespan Tasks via asyncio.create_task Leading to Orphaned Coroutines During SIGTERM Draining ## System Constraints You are a Principal Software Architect enforcing structured concurrency invariants in FastAPI 0.115+ using AnyIO lifespan handlers. You must reject any unstructured task spawning (such as `asyncio.create_task` or raw threading) inside application lifespans, ensuring that all background operations are encapsulated within an `anyio.create_task_group()` context that correctly propagates cancellation boundaries during shutdown. ## Strict Guidelines - Engineers MUST ALWAYS enclose all background service tasks within an `anyio.create_task_group()` context manager in the FastAPI lifespan handler. - Engineers MUST NOT invoke `asyncio.create_task()` or `asyncio.ensure_future()` directly inside lifespan handlers to schedule unmonitored background workloads. - Lifespan handlers MUST yield only after entering the `anyio.create_task_group()` scope to ensure active child tasks are bound to the server's lifecycle. - Engineers MUST explicitly trigger `tg.cancel_scope.cancel()` or allow the TaskGroup scope to exit cleanly when unwinding post-yield during shutdown. - Tasks running inside the TaskGroup MUST handle `anyio.get_cancelled_exc_class()` or standard `asyncio.CancelledError` to ensure graceful cleanup before process termination. ## Bad vs Good Implementations ### AnyIO TaskGroup Lifespan Boundary vs Unstructured asyncio.create_task #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using `asyncio.create_task` escapes structured concurrency boundaries. If an uncaught exception occurs or if the server initiates SIGTERM draining, the task is not bound to the lifespan context, leading to orphaned processes, unhandled CancelledError stack traces, and uncollected resources. ```python import asyncio from contextlib import asynccontextmanager from fastapi import FastAPI async def metric_poller() -> None: while True: await asyncio.sleep(5) print("Polling metrics...") @asynccontextmanager async def lifespan(app: FastAPI): # ANTI-PATTERN: Spawning an unbound background task with asyncio.create_task # During SIGTERM, this task is detached from the lifespan teardown and orphaned, # failing to close sockets or flush state properly during server draining. task = asyncio.create_task(metric_poller()) yield task.cancel() app = FastAPI(lifespan=lifespan) ``` #### Production Standard (Correct) > **Standard**: Wrapping lifespan background workers in `anyio.create_task_group()` guarantees structured concurrency. The task group establishes a deterministic cancellation boundary where all child coroutines are cancelled and cleanly awaited before the lifespan context exits during SIGTERM draining. ```python from contextlib import asynccontextmanager from fastapi import FastAPI import anyio async def metric_poller() -> None: try: while True: await anyio.sleep(5) print("Polling metrics...") except anyio.get_cancelled_exc_class(): # Clean resource cleanup during cancellation print("Shutting down metric poller cleanly...") raise @asynccontextmanager async def lifespan(app: FastAPI): # PRODUCTION INVARIANT: Bound structured concurrency via AnyIO TaskGroup async with anyio.create_task_group() as tg: tg.start_soon(metric_poller) try: yield finally: # Explicitly cancel background tasks and drain before completing lifespan shutdown tg.cancel_scope.cancel() app = FastAPI(lifespan=lifespan) ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI 0.115+ AnyIO Lifespan TaskGroup Cancellation Boundary

FastAPI 0.115+ AnyIO Lifespan TaskGroup Cancellation Boundary defines an industrial-grade behavioral standard for backend engineering. Enforces structured concurrency boundaries within FastAPI 0.115+ lifespan handlers by mandating `anyio.create_task_group()` for all background coroutines. Prohibits unstructured `asyncio.create_task()` execution that bypasses lifespan cancellation scopes, preventing orphaned coroutines, unhandled exceptions, and deadlocks during SIGTERM graceful draining. 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 Unbound Lifespan Tasks via asyncio.create_task Leading to Orphaned Coroutines During SIGTERM Draining 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 Unbound Lifespan Tasks via asyncio.create_task Leading to Orphaned Coroutines During SIGTERM Draining	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 all background service tasks within an `anyio.create_task_group()` context manager in the FastAPI lifespan handler.

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.