FastAPI Async Lifespan Structured Concurrency & TaskGroup Lifecycle Guardrail

--- description: FastAPI Async Lifespan Structured Concurrency & TaskGroup Lifecycle Guardrail - Mandates structured concurrency via Python 3.11+ TaskGroups or AnyIO task groups inside FastAPI lifespan context managers. Enforces deterministic worker draining and deferred database engine disposal during Kubernetes SIGTERM scale-in events to prevent orphaned coroutines and truncated database transactions. globs: app/**/*.py, src/**/*.py, api/**/*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-async-lifespan-taskgroup-standard" --- # FastAPI Async Lifespan Structured Concurrency & TaskGroup Lifecycle Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Fire-and-forget asyncio.create_task invocations coupled with uncoordinated database engine teardown during SIGTERM ## System Constraints You are a Principal Software Architect enforcing structured concurrency and deterministic lifecycle management in FastAPI services. You must reject fire-and-forget asyncio tasks (e.g., bare asyncio.create_task) and deprecated FastAPI lifecycle events (@app.on_event). Mandate Python 3.11+ asyncio.TaskGroup or AnyIO task groups encapsulated strictly within FastAPI lifespan context managers, ensuring that worker loops observe graceful cancellation events and database connection pools remain open until all active tasks complete. ## Strict Guidelines - Engineers MUST ALWAYS manage long-running background workers inside FastAPI lifespan context managers using structured task groups (Python 3.11+ asyncio.TaskGroup or anyio.create_task_group). - Engineers MUST NOT spawn persistent asynchronous worker loops using top-level or request-scoped fire-and-forget asyncio.create_task() calls. - Code MUST propagate a cooperative cancellation token (e.g., asyncio.Event) to worker loops on SIGTERM before awaiting task completion. - Services MUST defer the disposal of database connection pools (e.g., engine.dispose()) and network transports until after all background task groups have exited. - Components NEVER suppress asyncio.CancelledError or BaseException in worker loops without completing transaction rollback or checkpointing. ## Bad vs Good Implementations ### Graceful Lifespan Worker Pool with asyncio.TaskGroup #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using asyncio.create_task without tracking creates an unmonitored coroutine that is not bound to a lifecycle hierarchy. During Kubernetes scale-in (SIGTERM), the lifespan exits yield and disposes the database engine immediately, causing running queries to fail with unhandled exceptions, incomplete transactions, and orphaned async workers. ```python import asyncio from contextlib import asynccontextmanager from fastapi import FastAPI from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db") async def poll_orders_worker(): while True: # Fire-and-forget background worker: vulnerable to abrupt shutdown await asyncio.sleep(1) async with engine.begin() as conn: await conn.execute("UPDATE orders SET processed = true WHERE processed = false") @asynccontextmanager async def lifespan(app: FastAPI): # Anti-pattern: create_task creates an unmonitored zombie coroutine asyncio.create_task(poll_orders_worker()) yield # Database is disposed immediately upon SIGTERM while poll_orders_worker is mid-write await engine.dispose() app = FastAPI(lifespan=lifespan) ``` #### Production Standard (Correct) > **Standard**: The worker is bound to an asyncio.TaskGroup inside the lifespan manager. On SIGTERM, the stop_event triggers cooperative teardown, the TaskGroup waits for the worker loop to finish its active database transaction, and only after the task group has cleanly exited does engine.dispose() run, preventing corrupt state and zombie tasks. ```python import asyncio from contextlib import asynccontextmanager from dataclasses import dataclass from fastapi import FastAPI from sqlalchemy.ext.asyncio import create_async_engine, AsyncEngine @dataclass(slots=True) class AppState: engine: AsyncEngine stop_event: asyncio.Event async def poll_orders_worker(engine: AsyncEngine, stop_event: asyncio.Event) -> None: while not stop_event.is_set(): try: # Cooperative interruption point await asyncio.wait_for(stop_event.wait(), timeout=1.0) except asyncio.TimeoutError: # Process work chunk under active engine guardrail async with engine.begin() as conn: await conn.execute("UPDATE orders SET processed = true WHERE processed = false") @asynccontextmanager async def lifespan(app: FastAPI): engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db") stop_event = asyncio.Event() app.state.runtime = AppState(engine=engine, stop_event=stop_event) async with asyncio.TaskGroup() as tg: # Structured child task safely bound to TaskGroup context worker_task = tg.create_task(poll_orders_worker(engine, stop_event)) try: yield finally: # Signal stop to background loop before teardown stop_event.set() # TaskGroup context manager automatically joins worker_task # Database engine is disposed ONLY after the TaskGroup has fully terminated await engine.dispose() app = FastAPI(lifespan=lifespan) ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI Async Lifespan Structured Concurrency & TaskGroup Lifecycle Guardrail

FastAPI Async Lifespan Structured Concurrency & TaskGroup Lifecycle Guardrail defines an industrial-grade behavioral standard for backend engineering. Mandates structured concurrency via Python 3.11+ TaskGroups or AnyIO task groups inside FastAPI lifespan context managers. Enforces deterministic worker draining and deferred database engine disposal during Kubernetes SIGTERM scale-in events to prevent orphaned coroutines and truncated database transactions. 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: Fire-and-forget asyncio.create_task invocations coupled with uncoordinated database engine teardown during SIGTERM 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	Fire-and-forget asyncio.create_task invocations coupled with uncoordinated database engine teardown during SIGTERM	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 background workers inside FastAPI lifespan context managers using structured task groups (Python 3.11+ asyncio.TaskGroup or anyio.create_task_group).

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.