Deterministic Teardown for Dependency-Injected Async Generators in Streaming Endpoints

--- description: Deterministic Teardown for Dependency-Injected Async Generators in Streaming Endpoints - Enforces deterministic release of sockets, transactions, and telemetry spans yielded by FastAPI async generator dependencies during client disconnects or ASGI stream cancellations. Because Starlette StreamingResponse teardowns occur outside the immediate task context upon asyncio.CancelledError, generator dependencies must guarantee idempotency and shield finalization blocks from premature task death. globs: **/*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-async-generator-stream-teardown-guardrail" --- # Deterministic Teardown for Dependency-Injected Async Generators in Streaming Endpoints > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Resource Leakage via Abrupt ASGI Cancellation in Dependency-Injected Streaming Generators ## System Constraints You are a Principal Software Architect enforcing reliable teardown semantics across FastAPI streaming architectures. In Starlette and FastAPI, yielding dependencies execute post-yield cleanup inside a finally block after the response is sent. When a client disconnects during a StreamingResponse, an asyncio.CancelledError propagates through the generator runner, which can prematurely abort naive teardown blocks or cause unhandled exceptions that leave database connections checked out, socket file descriptors dangling, and distributed traces unclosed. You must mandate bulletproof, non-cancellable resource cleanups using asyncio.shield and defensive context management. ## Strict Guidelines - Engineers MUST ALWAYS encapsulate yield statements inside try...finally blocks within async generator dependencies. - Engineers MUST NOT allow asyncio.CancelledError or BaseException to bypass connection pool release or telemetry context closure. - Code SHOULD wrap critical cleanup routines (e.g., connection.close(), span.end(), session.rollback()) in asyncio.shield() or ensure synchronous teardown runs without interruption if an async cancel occurs. - Services MUST explicitly handle client disconnection signals within StreamingResponse iterators by catching asyncio.CancelledError and breaking cleanly. - Components NEVER assume post-yield code executes in an uncancelled task state when serving long-lived SSE or WebSocket streams. ## Bad vs Good Implementations ### Async Generator Dependency Cleanup Under Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: If a client disconnects mid-stream, asyncio.CancelledError is injected into the running task. The finally block is entered, but any subsequent await within the cleanup (such as session.rollback()) is immediately aborted by the pending cancellation token, stranding connection locks in the pool. ```python from fastapi import Depends, FastAPI from fastapi.responses import StreamingResponse import asyncio app = FastAPI() async def get_db_session(): session = await pool.acquire() try: yield session finally: # Fails silently or gets aborted midway if client disconnects abruptly # while the generator is paused at yield during stream consumption await session.rollback() await pool.release(session) @app.get("/events") async def stream_events(db=Depends(get_db_session)): async def event_generator(): while True: data = await db.fetch_next_event() yield f"data: {data}\n\n" await asyncio.sleep(1) return StreamingResponse(event_generator(), media_type="text/event-stream") ``` #### Production Standard (Correct) > **Standard**: The cleanup logic is encapsulated inside an inner coroutine and executed under asyncio.shield(), ensuring that the ASGI task cancellation signal cannot truncate the release of connection pool resources. ```python from fastapi import Depends, FastAPI from fastapi.responses import StreamingResponse import asyncio import logging logger = logging.getLogger(__name__) app = FastAPI() async def get_db_session(): session = await pool.acquire() try: yield session finally: # Ensure teardown executes deterministically without being interrupted by CancelledError async def _safe_cleanup(): try: await session.rollback() except Exception: logger.exception("Error rolling back session during stream teardown") finally: await pool.release(session) # Shield cleanup execution from ASGI task cancellation context await asyncio.shield(_safe_cleanup()) @app.get("/events") async def stream_events(db=Depends(get_db_session)): async def event_generator(): try: while True: data = await db.fetch_next_event() yield f"data: {data}\n\n" await asyncio.sleep(1) except asyncio.CancelledError: logger.info("Client disconnected from event stream; propagating cancellation cleanly.") raise return StreamingResponse(event_generator(), media_type="text/event-stream") ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Deterministic Teardown for Dependency-Injected Async Generators in Streaming Endpoints

Deterministic Teardown for Dependency-Injected Async Generators in Streaming Endpoints defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic release of sockets, transactions, and telemetry spans yielded by FastAPI async generator dependencies during client disconnects or ASGI stream cancellations. Because Starlette StreamingResponse teardowns occur outside the immediate task context upon asyncio.CancelledError, generator dependencies must guarantee idempotency and shield finalization blocks from premature task death. 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: Resource Leakage via Abrupt ASGI Cancellation in Dependency-Injected Streaming Generators 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	Resource Leakage via Abrupt ASGI Cancellation in Dependency-Injected Streaming Generators	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 encapsulate yield statements inside try...finally blocks within async generator dependencies.

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.