FastAPI AnyIO Lifespan Cancellation and Pool Teardown Boundary

--- description: FastAPI AnyIO Lifespan Cancellation and Pool Teardown Boundary - FastAPI background workers and database pool acquisitions must be strictly anchored to an explicit AnyIO task group within the application lifespan boundary. Unsupervised coroutines and unshielded pool disposal cause worker deadlocks and connection leaks during pod SIGTERM teardown, resulting in hard kills by the container runtime. globs: app/main.py, app/core/lifespan.py, app/core/database.py, app/workers/**/*.py, src/**/*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-anyio-lifespan-cancellation-boundary" --- # FastAPI AnyIO Lifespan Cancellation and Pool Teardown Boundary > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning Unmanaged Background Coroutines and Executing Unshielded Pool Teardown in Lifespan Contexts ## System Constraints You are a Principal Software Architect enforcing structured concurrency and fault-tolerant teardown boundaries in FastAPI applications using AnyIO. You mandate that no background task or database pool checkout operates outside supervised AnyIO TaskGroups managed within the lifespan context. You enforce graceful cancellation propagation and strictly require cancellation shielding for database engine and connection pool disposal. ## Strict Guidelines - Engineers MUST ALWAYS manage long-running application background tasks within an explicit `anyio.create_task_group()` bounded by the FastAPI `lifespan` context manager. - Engineers MUST NOT spawn detached background routines via `asyncio.create_task()` or unmanaged thread pools during application startup or request cycles. - Lifespan teardown MUST explicitly cancel background task scopes using `tg.cancel_scope.cancel()` and await task completion before executing resource disposal. - Engineers MUST wrap database connection pool closure (e.g., `await engine.dispose()`) in an un-cancellable scope using `with anyio.CancelScope(shield=True):` to prevent cancellation cascades from aborting TCP socket cleanup. - Background worker loops MUST handle `anyio.get_cancelled_exc_class()` explicitly around transaction blocks to rollback or release active database sessions cleanly. - Services MUST ensure that database session checkout timeouts are shorter than the Kubernetes pod `terminationGracePeriodSeconds` to prevent unrecoverable termination hangs. ## Bad vs Good Implementations ### FastAPI Lifespan Background Task and Pool Teardown Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using asyncio.create_task inside the lifespan startup phase decouples the task from structured supervision. During Kubernetes SIGTERM termination, the lifespan resumes to execute engine.dispose() while the detached worker is concurrently checking out or holding connections. This causes connection reset errors, deadlock during pool closing, and process hangs until SIGKILL. ```python import asyncio from contextlib import asynccontextmanager from fastapi import FastAPI from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db", pool_size=20) SessionLocal = async_sessionmaker(engine) async def background_worker(): while True: # ANTI-PATTERN: Detached task checks out connection without structured lifecycle bounds async with SessionLocal() as session: await session.execute("SELECT 1") await asyncio.sleep(1) @asynccontextmanager async def lifespan(app: FastAPI): # ANTI-PATTERN: Fire-and-forget asyncio.create_task hangs during SIGTERM asyncio.create_task(background_worker()) yield # ANTI-PATTERN: engine.dispose() called without shield; cancelled tasks corrupt cleanup await engine.dispose() app = FastAPI(lifespan=lifespan) ``` #### Production Standard (Correct) > **Standard**: Background tasks are tied directly to an AnyIO TaskGroup scoped to the lifespan block. When FastAPI initiates shutdown, `tg.cancel_scope.cancel()` signals cancellation to all child tasks and awaits their unwinding. Once all tasks have completed, `engine.dispose()` is executed inside an explicitly shielded CancelScope, guaranteeing that database connections terminate gracefully without hanging worker processes during pod scale-down. ```python from contextlib import asynccontextmanager from typing import AsyncIterator import anyio from fastapi import FastAPI from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db", pool_size=20) SessionLocal = async_sessionmaker(engine) async def background_worker(): try: while True: async with SessionLocal() as session: await session.execute("SELECT 1") await anyio.sleep(1) except anyio.get_cancelled_exc_class(): # Gracefully handle task cancellation boundary raise @asynccontextmanager async def lifespan(app: FastAPI) -> AsyncIterator[None]: async with anyio.create_task_group() as tg: # Start managed background task within bounded group tg.start_soon(background_worker) try: yield finally: # Cancel all workers spawned within the lifespan scope tg.cancel_scope.cancel() # Shield engine disposal from parent cancellation to guarantee clean TCP teardown with anyio.CancelScope(shield=True): await engine.dispose() app = FastAPI(lifespan=lifespan) ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI AnyIO Lifespan Cancellation and Pool Teardown Boundary

FastAPI AnyIO Lifespan Cancellation and Pool Teardown Boundary defines an industrial-grade behavioral standard for backend engineering. FastAPI background workers and database pool acquisitions must be strictly anchored to an explicit AnyIO task group within the application lifespan boundary. Unsupervised coroutines and unshielded pool disposal cause worker deadlocks and connection leaks during pod SIGTERM teardown, resulting in hard kills by the container runtime. 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 Executing Unshielded Pool Teardown in Lifespan Contexts 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 Executing Unshielded Pool Teardown in Lifespan Contexts	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 manage long-running application background tasks within an explicit `anyio.create_task_group()` bounded by the FastAPI `lifespan` context manager.

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.