FastAPI StreamingResponse Upstream Async Generator Disconnect Cancellation Guardrail

FastAPI `StreamingResponse` iterators do not automatically interrupt long-running upstream database or network generators when clients abort connections unless explicit ASGI disconnect monitoring is bound to the async generator loop. Unbound stream generators continue iterating in background tasks, exhausting connection pools, leaking cursor memory, and leaving zombie database transactions open. This standard mandates explicit request disconnect polling via `request.is_disconnected()`, `asyncio.CancelledError` trapping, and deterministic resource release within upstream async generator iterators.

--- description: FastAPI StreamingResponse Upstream Async Generator Disconnect Cancellation Guardrail - FastAPI `StreamingResponse` iterators do not automatically interrupt long-running upstream database or network generators when clients abort connections unless explicit ASGI disconnect monitoring is bound to the async generator loop. Unbound stream generators continue iterating in background tasks, exhausting connection pools, leaking cursor memory, and leaving zombie database transactions open. This standard mandates explicit request disconnect polling via `request.is_disconnected()`, `asyncio.CancelledError` trapping, and deterministic resource release within upstream async generator iterators. globs: app/**/*.py, src/**/*.py, api/**/*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-streamingresponse-async-generator-cancellation-guardrail" --- # FastAPI StreamingResponse Upstream Async Generator Disconnect Cancellation Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unmonitored StreamingResponse generator causing zombie database queries and pool exhaustion on client disconnect ## System Constraints You are a Principal Backend Architect enforcing strict ASGI lifecycle and async cancellation semantics in FastAPI. You must ensure all `StreamingResponse` streaming iterators actively monitor client disconnection status via `request.is_disconnected()`, properly propagate `asyncio.CancelledError`, and deterministically close upstream database cursors and network buffers when clients terminate HTTP streams prematurely. ## Strict Guidelines - Engineers MUST ALWAYS pass the ASGI `Request` instance into any async generator passed to `StreamingResponse`. - Engineers MUST periodically check `await request.is_disconnected()` inside the generator loop before or immediately following expensive chunk yields. - Engineers MUST wrap streaming yields in `try...finally` blocks or asynchronous context managers to guarantee deterministic disposal of database sessions, cursors, or upstream network sockets. - Engineers MUST NOT swallow `asyncio.CancelledError` or `GeneratorExit`; they must be caught only to perform immediate cleanup and re-raised or allowed to terminate the iterator. - Engineers MUST NOT rely solely on Starlette/FastAPI middleware to abort un-awaited upstream background generators, as ASGI `http.disconnect` events only terminate the response writer, not detached generator tasks. - Streaming generators MUST break early and cleanly raise or return when `request.is_disconnected()` evaluates to `True`. ## Bad vs Good Implementations ### Unbounded StreamingResponse generator vs. Disconnect-aware Generator with Guaranteed Resource Teardown #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When an HTTP client aborts the request, FastAPI's ASGI response sender stops reading from the generator, but `stream_report_bad` continues executing until the entire query is fetched. The database session remains locked, consuming async worker loop time and exhausting connection pools under high abort/cancellation rates. ```python from fastapi import FastAPI, Depends from fastapi.responses import StreamingResponse from sqlalchemy.ext.asyncio import AsyncSession from app.database import get_db app = FastAPI() async def stream_report_bad(session: AsyncSession): # ANTI-PATTERN: If client disconnects at chunk 5, loop continues processing all 100,000 # rows in memory. Session is never returned to the pool until complete iteration. result = await session.stream(LargeQuery()) async for row in result: yield row.to_csv_chunk() @app.get('/export') async def export_data(db: AsyncSession = Depends(get_db)): return StreamingResponse( stream_report_bad(db), media_type='text/csv' ) ``` #### Production Standard (Correct) > **Standard**: By injecting `Request` and checking `await request.is_disconnected()`, the generator immediately halts execution when the client closes the TCP socket. Enclosing the logic in `try...finally` with `CancelledError` handling guarantees that upstream database cursors and sessions are cleanly reclaimed immediately rather than leaking in the event loop. ```python import asyncio import logging from fastapi import FastAPI, Request, Depends from fastapi.responses import StreamingResponse from sqlalchemy.ext.asyncio import AsyncSession from app.database import get_db logger = logging.getLogger(__name__) app = FastAPI() async def stream_report_good(request: Request, session: AsyncSession): try: result = await session.stream(LargeQuery()) async for row in result: if await request.is_disconnected(): logger.warning('Client disconnected prematurely; aborting query iterator.') break yield row.to_csv_chunk() # Cooperative scheduling checkpoint await asyncio.sleep(0) except (asyncio.CancelledError, GeneratorExit): logger.info('Stream generator explicitly cancelled.') raise finally: # Invariant: Guarantee clean session and cursor release await session.close() @app.get('/export') async def export_data(request: Request, db: AsyncSession = Depends(get_db)): return StreamingResponse( stream_report_good(request, db), media_type='text/csv' ) ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI StreamingResponse Upstream Async Generator Disconnect Cancellation Guardrail

FastAPI StreamingResponse Upstream Async Generator Disconnect Cancellation Guardrail defines an industrial-grade behavioral standard for backend engineering. FastAPI `StreamingResponse` iterators do not automatically interrupt long-running upstream database or network generators when clients abort connections unless explicit ASGI disconnect monitoring is bound to the async generator loop. Unbound stream generators continue iterating in background tasks, exhausting connection pools, leaking cursor memory, and leaving zombie database transactions open. This standard mandates explicit request disconnect polling via `request.is_disconnected()`, `asyncio.CancelledError` trapping, and deterministic resource release within upstream async generator iterators. 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: Unmonitored StreamingResponse generator causing zombie database queries and pool exhaustion on 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	Unmonitored StreamingResponse generator causing zombie database queries and pool exhaustion on 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 pass the ASGI `Request` instance into any async generator passed to `StreamingResponse`.

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.