FastAPI Async Lifespan & Distributed Pool Drain Invariant

--- description: FastAPI Async Lifespan & Distributed Pool Drain Invariant - Enforces strict ASGI lifespan context manager architecture across FastAPI services to guarantee deterministic teardown sequences for asynchronous databases, message brokers, and background workers. Prevents socket truncation, connection pool starvation, and corrupted in-flight writes during Kubernetes rolling deployments and SIGTERM container termination signals. globs: app/**/*.py, src/**/*.py, **/main.py, **/lifespan.py, **/dependencies.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-async-lifespan-pool-drain-invariant" --- # FastAPI Async Lifespan & Distributed Pool Drain Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unordered Deprecated Event Handlers Truncating Active In-Flight Requests and Severing Broker TCP Sockets ## System Constraints You are a Principal Backend Architect enforcing robust ASGI lifespan management and graceful termination semantics in FastAPI microservices. Mandate strict adherence to the asynccontextmanager lifespan protocol, explicit reverse-order resource drainage, and shielded async teardown to withstand container preemption. ## Strict Guidelines - Engineers MUST ALWAYS use the FastAPI(lifespan=...) asynccontextmanager protocol instead of deprecated @app.on_event('startup') and @app.on_event('shutdown') handlers. - Engineers MUST ALWAYS attach initialized clients and pools to app.state (or yield a lifespan mapping) rather than relying on unmanaged global singleton state. - Code MUST drain resources in strict reverse topological dependency order: pause ingress consumers first, flush buffered messaging producers second, drain in-flight worker tasks third, and dispose async database engines last. - Services MUST shield network pool shutdown routines using asyncio.shield and bounded asyncio.wait_for timeouts to guarantee teardown completes before the orchestrator's SIGKILL deadline. - Components NEVER drop or sever active database connections abruptly without invoking engine.dispose() or pool.close() followed by pool.wait_closed(). ## Bad vs Good Implementations ### FastAPI Lifespan Context with Phased Resource Drain vs Deprecated Event Handlers #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using deprecated @app.on_event handlers executes shutdown unpredictably with no context preservation. Concurrently stopping Kafka and disposing SQLAlchemy can truncate running requests, drop in-flight commits, or hang indefinitely if an external broker does not acknowledge disconnect within the termination grace period. ```python from fastapi import FastAPI from sqlalchemy.ext.asyncio import create_async_engine import aiokafka app = FastAPI() # ANTI-PATTERN: Global unmanaged client instances and deprecated events engine = create_async_engine("postgresql+asyncpg://user:pass@db:5432/app") producer = aiokafka.AIOKafkaProducer(bootstrap_servers="kafka:9092") @app.on_event("startup") async def startup_event(): await producer.start() @app.on_event("shutdown") async def shutdown_event(): # ANTI-PATTERN: Concurrently tearing down dependencies without ordering; # cuts off database while in-flight Kafka flushes might still require DB access. # Lacks timeouts and exception shields against pod termination signals. await producer.stop() await engine.dispose() ``` #### Production Standard (Correct) > **Standard**: Adheres to the official ASGI lifespan protocol. Infrastructure is attached cleanly to app.state. During container shutdown, resources are dismantled in strict reverse order: message producer buffers are flushed first under a timeout shield, followed by closing the database engine pool, ensuring no active transactions are orphaned during pod preemption. ```python from contextlib import asynccontextmanager import asyncio import logging from fastapi import FastAPI from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine import aiokafka logger = logging.getLogger("lifespan") @asynccontextmanager async def lifespan(app: FastAPI): # 1. SETUP: Initialize infrastructure in forward dependency order engine: AsyncEngine = create_async_engine( "postgresql+asyncpg://user:pass@db:5432/app", pool_pre_ping=True, pool_size=20, max_overflow=10, ) producer = aiokafka.AIOKafkaProducer(bootstrap_servers="kafka:9092") await producer.start() # Expose state deterministically via application state app.state.db_engine = engine app.state.kafka_producer = producer logger.info("Application infrastructure initialized successfully") yield # 2. TEARDOWN: Execute deterministic reverse-order graceful drain logger.info("Termination signal received. Starting deterministic pool drain...") try: # Phase A: Flush in-flight streaming telemetry/events (10s limit) await asyncio.wait_for(asyncio.shield(producer.stop()), timeout=10.0) logger.info("Streaming producer flushed and stopped") except (asyncio.TimeoutError, Exception) as exc: logger.error("Producer drain encountered error/timeout: %s", exc) try: # Phase B: Dispose connection pool once all producers/workers are settled await asyncio.wait_for(asyncio.shield(engine.dispose()), timeout=5.0) logger.info("Database connection pool closed successfully") except (asyncio.TimeoutError, Exception) as exc: logger.error("Database pool disposal encountered error/timeout: %s", exc) app = FastAPI(lifespan=lifespan) ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI Async Lifespan & Distributed Pool Drain Invariant

FastAPI Async Lifespan & Distributed Pool Drain Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces strict ASGI lifespan context manager architecture across FastAPI services to guarantee deterministic teardown sequences for asynchronous databases, message brokers, and background workers. Prevents socket truncation, connection pool starvation, and corrupted in-flight writes during Kubernetes rolling deployments and SIGTERM container termination signals. 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: Unordered Deprecated Event Handlers Truncating Active In-Flight Requests and Severing Broker TCP Sockets 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	Unordered Deprecated Event Handlers Truncating Active In-Flight Requests and Severing Broker TCP Sockets	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 FastAPI(lifespan=...) asynccontextmanager protocol instead of deprecated @app.on_event('startup') and @app.on_event('shutdown') handlers.

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.