FastAPI Async Dependency Lifecycle and Early-Disconnect Teardown Invariant

--- description: FastAPI Async Dependency Lifecycle and Early-Disconnect Teardown Invariant - Enforces deterministic teardown execution for nested async generators and context managers (such as SQLAlchemy AsyncSessions or Redis transaction pipelines) used within FastAPI dependency injection trees. Prevents connection leaks, orphaned transactions, and hanging locks triggered when clients disconnect prematurely during request processing or async streaming. Mandates strict try/finally semantics, shielded background cleanup tasks, and ASGI-level disconnect handling. globs: **/*.py, app/dependencies/**/*.py, app/core/**/*.py, app/api/**/*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-async-dependency-teardown-invariant" --- # FastAPI Async Dependency Lifecycle and Early-Disconnect Teardown Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unshielded Dependency Generators Leaking Connection Pool Handles on Cancelled Tasks During Client Disconnect ## System Constraints You are a Principal Software Architect enforcing production-grade ASGI lifecycle and dependency injection invariants in FastAPI applications. You must mandate deterministic teardown execution for asynchronous context managers and dependencies when client disconnects trigger asyncio.CancelledError. Ensure all database transactions, Redis locks, and pooled resources are safely rolled back and closed using robust async generator lifecycles with asyncio.shield where necessary. ## Strict Guidelines - Engineers MUST ALWAYS wrap the 'yield' statement in FastAPI dependency generators inside a strict 'try...finally' or 'try...except BaseException...finally' block to ensure teardown execution. - Engineers MUST NOT rely on implicit cleanup or garbage collection for asynchronous database sessions, transactions, or network clients. - Code MUST explicitly catch 'asyncio.CancelledError' or 'BaseException' during dependency teardown if asynchronous cleanup routines (like rollback or session release) must run without being truncated by task cancellation. - Services MUST wrap asynchronous teardown steps (e.g., 'await session.rollback()') in 'asyncio.shield()' or execute them within an independent background cleanup scope if task cancellation is active, preventing orphaned connections in async connection pools. - Components NEVER execute raw async code post-yield without handling ASGI disconnect scenarios, and must ensure that connection pool check-ins occur deterministically even on HTTP disconnects or worker timeouts. ## Bad vs Good Implementations ### FastAPI Async Dependency Cleanup under Task Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When an HTTP client aborts the connection mid-flight, FastAPI cancels the request task. This raises an asyncio.CancelledError inside the generator at the yield point. In this bad implementation, execution aborts immediately; session.commit() and session.close() are never called, leading to uncommitted dirty transactions and exhausted connection pools. ```python from typing import AsyncGenerator from fastapi import Depends from sqlalchemy.ext.asyncio import AsyncSession from app.core.database import async_session_factory async def get_db_session() -> AsyncGenerator[AsyncSession, None]: session = async_session_factory() # ANTI-PATTERN: If client disconnects while the endpoint awaits, # asyncio.CancelledError is raised inside the generator at the yield. # Without try...finally and shielding, rollback and close may be skipped # or interrupted mid-flight, leaking connections in asyncpg/SQLAlchemy pools. yield session await session.commit() await session.close() ``` #### Production Standard (Correct) > **Standard**: The good implementation encapsulates the yield inside a try/except BaseException/finally block. When a client disconnects, task cancellation raises CancelledError, which enters the exception handler. Wrapping session.rollback() and session.close() in asyncio.shield guarantees that the coroutines complete execution without being cancelled mid-network-packet, properly returning the raw connection to the connection pool. ```python import asyncio from typing import AsyncGenerator from fastapi import Depends from sqlalchemy.ext.asyncio import AsyncSession from app.core.database import async_session_factory async def get_db_session() -> AsyncGenerator[AsyncSession, None]: session: AsyncSession = async_session_factory() try: yield session except BaseException: # Ensure active transaction is rolled back safely even if cancelled await asyncio.shield(session.rollback()) raise finally: # Deterministically close and return connection to pool, shielded from task cancellation await asyncio.shield(session.close()) ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI Async Dependency Lifecycle and Early-Disconnect Teardown Invariant

FastAPI Async Dependency Lifecycle and Early-Disconnect Teardown Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic teardown execution for nested async generators and context managers (such as SQLAlchemy AsyncSessions or Redis transaction pipelines) used within FastAPI dependency injection trees. Prevents connection leaks, orphaned transactions, and hanging locks triggered when clients disconnect prematurely during request processing or async streaming. Mandates strict try/finally semantics, shielded background cleanup tasks, and ASGI-level disconnect handling. 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: Unshielded Dependency Generators Leaking Connection Pool Handles on Cancelled Tasks During Client Disconnect 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	Unshielded Dependency Generators Leaking Connection Pool Handles on Cancelled Tasks During Client Disconnect	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 wrap the 'yield' statement in FastAPI dependency generators inside a strict 'try...finally' or 'try...except BaseException...finally' block to ensure teardown execution.

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.