FastAPI Async Lifespan Generator Deterministic Teardown Invariant

--- description: FastAPI Async Lifespan Generator Deterministic Teardown Invariant - Enforces deterministic teardown of database connection pools, HTTP clients, and background task coroutines using FastAPI lifespan context managers. Guarantees clean state draining during SIGTERM signals under multi-worker ASGI runtimes (Uvicorn/Gunicorn) to prevent unhandled connection reset cascades and aborted in-flight transactions. globs: app/**/*.py, src/**/*.py, **/main.py, **/lifespan.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-async-lifespan-cleanup-invariant" --- # FastAPI Async Lifespan Generator Deterministic Teardown Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unstructured Startup/Shutdown Handlers Leaking Sockets and Stranding Coroutines on Worker Recycling ## System Constraints You are a Principal Backend Architect enforcing strict asyncio lifecycle management and resource disposal patterns in FastAPI applications. Deprecate all legacy event hooks, mandate async context manager lifespan protocols, guarantee try/finally isolation around yields, and enforce deterministic cancellation and draining of spawned background tasks upon ASGI worker termination. ## Strict Guidelines - Engineers MUST ALWAYS use the '@asynccontextmanager' protocol for FastAPI application 'lifespan' rather than deprecated '@app.on_event("startup")' and '@app.on_event("shutdown")' hooks. - Engineers MUST wrap post-yield teardown logic within a comprehensive 'try ... finally' block to guarantee resource deallocation even if 'CancelledError' is raised during shutdown. - Code SHOULD enforce explicit bounded timeouts (via 'asyncio.timeout' or 'asyncio.wait_for') during pool disposal to prevent zombie worker hangs during container SIGKILL escalation periods. - Services MUST explicitly cancel, await, and catch exceptions for all long-running background tasks spawned in the lifespan context before closing persistence layers. - Components NEVER store initialized async client state (e.g., SQLAlchemy AsyncEngine, Redis Client, httpx.AsyncClient) on global module variables; state MUST be bound to 'app.state' or managed via dependency injection registries. ## Bad vs Good Implementations ### Deterministic Lifespan Resource Teardown and Task Draining #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Legacy on_event hooks do not preserve execution context or guarantee reverse-order teardown. Background tasks are orphaned, causing unhandled TaskPendingError and abrupt TCP RST packets to downstream dependencies on worker restart. ```python from fastapi import FastAPI import asyncio import httpx app = FastAPI() # ANTI-PATTERN: Deprecated event handlers with unmanaged global state # Background tasks are orphaned; SIGTERM causes abrupt socket reset without pooling drain. client = None background_task = None async def poll_external_worker(): while True: await asyncio.sleep(5) @app.on_event("startup") async def startup_event(): global client, background_task client = httpx.AsyncClient() background_task = asyncio.create_task(poll_external_worker()) @app.on_event("shutdown") async def shutdown_event(): # Vulnerable to unhandled CancelledError; does not await or cancel background_task await client.aclose() ``` #### Production Standard (Correct) > **Standard**: Utilizes the official '@asynccontextmanager' lifespan handler with an isolated 'try ... finally' block. Background tasks are explicitly cancelled and awaited, resources bound to 'app.state' are closed in strict reverse order, and an explicit 'asyncio.timeout' bounds teardown execution before Gunicorn/Kubernetes escalates to SIGKILL. ```python from contextlib import asynccontextmanager from typing import AsyncGenerator import asyncio import logging from fastapi import FastAPI import httpx from sqlalchemy.ext.asyncio import create_async_engine, AsyncEngine logger = logging.getLogger(__name__) async def monitor_heartbeat(): try: while True: await asyncio.sleep(5) except asyncio.CancelledError: logger.info("Heartbeat task received cancellation; draining safely.") raise @asynccontextmanager async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]: # 1. Startup phase: Initialize clients and bind to app.state engine: AsyncEngine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db", pool_pre_ping=True) http_client = httpx.AsyncClient(timeout=10.0) app.state.db_engine = engine app.state.http_client = http_client task = asyncio.create_task(monitor_heartbeat(), name="heartbeat_monitor") app.state.heartbeat_task = task try: yield finally: # 2. Teardown phase: Reverse-order guaranteed teardown within bounded timeout logger.info("SIGTERM received: Starting deterministic resource teardown.") try: async with asyncio.timeout(10.0): # Cancel background tasks task.cancel() await asyncio.gather(task, return_exceptions=True) # Drain HTTP client connections await http_client.aclose() # Dispose SQLAlchemy database engine connection pool await engine.dispose() logger.info("Deterministic teardown completed without pool leaks.") except* TimeoutError: logger.error("Teardown timed out after 10.0s; forcing pool abandonment.") app = FastAPI(lifespan=lifespan) ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI Async Lifespan Generator Deterministic Teardown Invariant

FastAPI Async Lifespan Generator Deterministic Teardown Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic teardown of database connection pools, HTTP clients, and background task coroutines using FastAPI lifespan context managers. Guarantees clean state draining during SIGTERM signals under multi-worker ASGI runtimes (Uvicorn/Gunicorn) to prevent unhandled connection reset cascades and aborted in-flight 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: Unstructured Startup/Shutdown Handlers Leaking Sockets and Stranding Coroutines on Worker Recycling 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	Unstructured Startup/Shutdown Handlers Leaking Sockets and Stranding Coroutines on Worker Recycling	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 use the '@asynccontextmanager' protocol for FastAPI application 'lifespan' rather than deprecated '@app.on_event("startup")' and '@app.on_event("shutdown")' hooks.

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.