FastAPI SSE Backpressure and Premature Disconnect Resource Deallocation Guardrail

--- description: FastAPI SSE Backpressure and Premature Disconnect Resource Deallocation Guardrail - Enforces deterministic teardown of upstream database sessions, pub/sub consumer groups, and network sockets during Server-Sent Events (SSE) streaming in FastAPI. Guarantees that client disconnects, socket cancellations, and downstream backpressure collapses propagate immediate generator termination and resource pool release. globs: app/**/*.py, src/**/*.py, api/**/*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-sse-stream-backpressure-resource-guardrail" --- # FastAPI SSE Backpressure and Premature Disconnect Resource Deallocation Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Orphaned Coroutines and Leaked Database/Queue Connections on Abrupt SSE Client Disconnect ## System Constraints You are a Principal Backend Architect enforcing strict upstream resource lifecycle invariants across FastAPI streaming endpoints. You must prevent connection pool exhaustion, memory leaks, and zombie coroutines caused by client-severed Server-Sent Events (SSE) streams. ## Strict Guidelines - Engineers MUST ALWAYS encapsulate streaming generator bodies within a comprehensive `try...finally` block to guarantee upstream resource return (e.g., DB pool connections, Redis Pub/Sub channels) upon client disconnection. - Engineers MUST NOT catch `BaseException` or suppress `asyncio.CancelledError` and `GeneratorExit` inside streaming generators, as Starlette signals disconnects by cancelling the wrapping task or closing the generator. - Code MUST actively poll `await request.is_disconnected()` or monitor the underlying transport before executing expensive upstream operations inside infinite or long-running SSE loops. - Services MUST configure heartbeat/ping intervals (e.g., sending `: keepalive\n\n` comments every 15-30s) to rapidly flush dead TCP half-open sockets through the ASGI server interface. - Components NEVER hold database transaction locks across streaming yields; database sessions MUST be stateless per chunk or read-committed read-only replicas decoupled from the SSE lifecycle. ## Bad vs Good Implementations ### SSE Endpoint Connection Pool Handling on Client Disconnect #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The database connection is retained outside of a try/finally block. When a client abruptly terminates the SSE connection, the ASGI server raises asyncio.CancelledError or closes the generator via GeneratorExit. Because the broad except swallows exceptions or leaves cleanup unreachable, the connection is never returned to the pool, rapidly leading to pool starvation under load. ```python from fastapi import APIRouter, Request from fastapi.responses import StreamingResponse from app.database import get_db_connection router = APIRouter() @router.get("/api/v1/events") async def stream_events(request: Request): async def event_generator(): # ANTI-PATTERN: Leaks connection pool slot if client disconnects mid-stream conn = await get_db_connection() while True: # Catch-all swallows asyncio.CancelledError, creating a zombie loop try: event = await conn.fetch_next_event() yield f"data: {event}\n\n" except Exception: pass # Unreachable code when generator is closed by ASGI runtime await conn.close() return StreamingResponse(event_generator(), media_type="text/event-stream") ``` #### Production Standard (Correct) > **Standard**: Uses an asynchronous context manager (`async with`) guaranteeing upstream resource return to the pool upon generator closure. Actively polls `request.is_disconnected()`, emits periodic `: keepalive\n\n` heartbeats to detect severed TCP sockets, explicitly re-raises `asyncio.CancelledError` and `GeneratorExit`, and sets `X-Accel-Buffering: no` to avoid proxy buffer stalls. ```python import asyncio import logging from collections.abc import AsyncIterator from fastapi import APIRouter, Request from fastapi.responses import StreamingResponse from app.database import pool logger = logging.getLogger(__name__) router = APIRouter() @router.get("/api/v1/events") async def stream_events(request: Request) -> StreamingResponse: async def event_generator() -> AsyncIterator[str]: async with pool.acquire() as conn: try: while True: if await request.is_disconnected(): logger.info("Client disconnected, aborting event stream.") break try: event = await asyncio.wait_for(conn.fetch_next_event(), timeout=15.0) yield f"data: {event}\n\n" except asyncio.TimeoutError: # Keepalive comment to detect half-open sockets and prevent gateway timeouts yield ": keepalive\n\n" except (asyncio.CancelledError, GeneratorExit): logger.info("Streaming task cancelled by client disconnect.") raise finally: logger.info("Releasing streaming resources back to connection pool.") # Async context manager automatically returns conn to pool here return StreamingResponse( event_generator(), media_type="text/event-stream", headers={ "Cache-Control": "no-cache", "Connection": "keep-alive", "X-Accel-Buffering": "no" } ) ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI SSE Backpressure and Premature Disconnect Resource Deallocation Guardrail

FastAPI SSE Backpressure and Premature Disconnect Resource Deallocation Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic teardown of upstream database sessions, pub/sub consumer groups, and network sockets during Server-Sent Events (SSE) streaming in FastAPI. Guarantees that client disconnects, socket cancellations, and downstream backpressure collapses propagate immediate generator termination and resource pool release. 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: Orphaned Coroutines and Leaked Database/Queue Connections on Abrupt SSE 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	Orphaned Coroutines and Leaked Database/Queue Connections on Abrupt SSE 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 encapsulate streaming generator bodies within a comprehensive `try...finally` block to guarantee upstream resource return (e.g., DB pool connections, Redis Pub/Sub channels) upon client disconnection.

Engineers MUST ALWAYS encapsulate streaming generator bodies within a comprehensive `try...finally` block to guarantee upstream resource return (e.g., DB pool connections, Redis Pub/Sub channels) upon client disconnection.

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.