FastAPI & AnyIO Structured Concurrency Async Task Shield Isolation Guardrail

--- description: FastAPI & AnyIO Structured Concurrency Async Task Shield Isolation Guardrail - Enforces strict structured concurrency in FastAPI applications running atop AnyIO by prohibiting raw asyncio background task spawning and unshielded async coroutines. Requires multi-tenant asynchronous tasks to execute within explicit, supervised task groups encapsulated by cancellation shields with bounded timeouts to prevent orphaned tasks, partial writes, and exhausted database connection pools. globs: app/**/*.py, src/**/*.py, routers/**/*.py, services/**/*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-anyio-task-shield-isolation" --- # FastAPI & AnyIO Structured Concurrency Async Task Shield Isolation Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning raw background tasks or using unshielded coroutines that leak connections and leave partial tenant mutations upon client disconnect ## System Constraints You are a Principal Backend Systems Architect enforcing strict AnyIO structured concurrency and cancellation isolation within FastAPI applications. You must mandate that fire-and-forget or client-disconnected critical operations are never spawned using `asyncio.create_task()` or unbounded `BackgroundTasks`. All asynchronous operations that must survive client disconnects must be encapsulated using `anyio.CancelScope(shield=True)` within bounded supervision trees, explicitly managing multi-tenant context propagation and database session checkout/release lifecycles. ## Strict Guidelines - Engineers MUST ALWAYS encapsulate mission-critical cleanup, transactional commits, or multi-tenant audit writes in `anyio.CancelScope(shield=True)` with an explicit timeout deadline. - Engineers MUST NOT invoke `asyncio.create_task()`, `asyncio.ensure_future()`, or unmanaged thread spawns inside FastAPI endpoint handlers or route dependencies. - Services MUST manage long-running background tasks via a managed `anyio.create_task_group()` bound to the application lifespan context, never request-scoped lifespan boundaries. - Engineers MUST ALWAYS isolate tenant context variables (e.g., using `contextvars.copy_context()`) when delegating work across structured task group boundaries. - Database transactions inside shielded scopes MUST open dedicated tenant connections and explicitly release or roll back pools inside `finally` blocks, preventing resource exhaustion during upstream cancellation. ## Bad vs Good Implementations ### Orphaned Unstructured Background Task vs. Shielded Structured Concurrency Task #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using `asyncio.create_task` violates structured concurrency. The task runs in an unmanaged scope holding a request-scoped database session. If the client disconnects, AnyIO/Starlette cancels the request scope, causing `db` to be closed while `process_tenant_audit` is mid-write, resulting in connection pool corruption, orphaned background coroutines, and lost audit trails. ```python import asyncio from fastapi import APIRouter, Depends from sqlalchemy.ext.asyncio import AsyncSession from app.db import get_db router = APIRouter() async def process_tenant_audit(db: AsyncSession, tenant_id: str, payload: dict): # CRITICAL FLAW: Inherits request-scoped DB session and runs detached via asyncio.create_task # If the client disconnects or request finishes, session is closed prematurely while task runs, # leading to leaked connection locks, unhandled exceptions, and orphaned execution. await db.execute("INSERT INTO audit_logs (tenant_id, data) VALUES (:t, :d)", {"t": tenant_id, "d": str(payload)}) await db.commit() @router.post("/tenants/{tenant_id}/sync") async def sync_tenant_data(tenant_id: str, payload: dict, db: AsyncSession = Depends(get_db)): asyncio.create_task(process_tenant_audit(db, tenant_id, payload)) return {"status": "accepted"} ``` #### Production Standard (Correct) > **Standard**: Adheres to structured concurrency using AnyIO. The subordinate task is bound to an `anyio.create_task_group()`, allocates its own database session from the factory, and encapsulates the critical write inside `anyio.CancelScope(shield=True)` protected by a bounded deadline (`fail_after(5.0)`). Upstream cancellations do not orphan tasks or corrupt database sessions. ```python import anyio from fastapi import APIRouter, status from app.db import async_session_factory router = APIRouter() async def write_tenant_audit_shielded(tenant_id: str, payload: dict) -> None: # Dedicated session lifecycle with shielded cancellation boundary with anyio.CancelScope(shield=True): with anyio.fail_after(5.0): # Bounded execution window for the shielded section async with async_session_factory() as session: async with session.begin(): await session.execute( "INSERT INTO audit_logs (tenant_id, data) VALUES (:t, :d)", {"t": tenant_id, "d": str(payload)} ) @router.post("/tenants/{tenant_id}/sync", status_code=status.HTTP_202_ACCEPTED) async def sync_tenant_data(tenant_id: str, payload: dict): async with anyio.create_task_group() as tg: # Subordinate task lifecycle bounded to structured scope with explicit isolation tg.start_soon(write_tenant_audit_shielded, tenant_id, payload) return {"status": "accepted"} ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI & AnyIO Structured Concurrency Async Task Shield Isolation Guardrail

FastAPI & AnyIO Structured Concurrency Async Task Shield Isolation Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces strict structured concurrency in FastAPI applications running atop AnyIO by prohibiting raw asyncio background task spawning and unshielded async coroutines. Requires multi-tenant asynchronous tasks to execute within explicit, supervised task groups encapsulated by cancellation shields with bounded timeouts to prevent orphaned tasks, partial writes, and exhausted database connection pools. 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: Spawning raw background tasks or using unshielded coroutines that leak connections and leave partial tenant mutations upon 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	Spawning raw background tasks or using unshielded coroutines that leak connections and leave partial tenant mutations upon 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 mission-critical cleanup, transactional commits, or multi-tenant audit writes in `anyio.CancelScope(shield=True)` with an explicit timeout deadline.

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.