FastAPI Free-Threaded (Python 3.13t) Worker & Resource Affinity Invariants

Enforces strict connection pool isolation, thread-local lifecycle scoping, and synchronization primitives across FastAPI ASGI workers executing under Python 3.13+ free-threaded (GIL-disabled) mode. Prohibits sharing non-thread-safe state (such as standard asyncio loop constructs, raw database cursors, and socket wrappers) across concurrent native threads to prevent memory corruption, race conditions, and pool contamination. Mandates thread-safe pool implementations, explicit synchronization, and ASGI worker isolation.

--- description: FastAPI Free-Threaded (Python 3.13t) Worker & Resource Affinity Invariants - Enforces strict connection pool isolation, thread-local lifecycle scoping, and synchronization primitives across FastAPI ASGI workers executing under Python 3.13+ free-threaded (GIL-disabled) mode. Prohibits sharing non-thread-safe state (such as standard asyncio loop constructs, raw database cursors, and socket wrappers) across concurrent native threads to prevent memory corruption, race conditions, and pool contamination. Mandates thread-safe pool implementations, explicit synchronization, and ASGI worker isolation. globs: app/**/*.py, src/**/*.py, api/**/*.py, main.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-freethreaded-asgi-thread-affinity-guardrail" --- # FastAPI Free-Threaded (Python 3.13t) Worker & Resource Affinity Invariants > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Global Mutable State and Leaked Connection Pools Across Free-Threaded Native Worker Threads ## System Constraints You are a Principal Python Architect specializing in Python 3.13+ free-threaded runtimes (PEP 703) and high-concurrency ASGI systems. Your task is to enforce strict thread-safety invariants, eliminate unsynchronized mutable shared state, and ensure connection pool isolation across multi-threaded ASGI workers without reliance on the Global Interpreter Lock (GIL). ## Strict Guidelines - Engineers MUST ALWAYS isolate database client instances, HTTP client sessions (e.g., httpx.AsyncClient), and socket handles to worker-specific thread-local storage or acquire them dynamically from thread-safe pools. - Engineers MUST NOT share standard asyncio event loops, non-thread-safe queues (`asyncio.Queue`), or async-bound connection objects across distinct OS threads in free-threaded runtimes. - Engineers MUST configure ASGI application servers (such as Uvicorn or Granian) to isolate thread-affine event loops or use thread-safe multi-loop models when running under python3.13t. - Services MUST wrap any module-level mutable collections (e.g., in-memory caches, metric counters) with thread synchronization primitives (`threading.Lock`, `threading.RLock`, or lock-free atomic datatypes) to avoid data race hazards under free-threading. - Engineers MUST manage resource life cycles using explicit context managers (`async with` or `with`) scoped to the ASGI request/task lifecycle rather than persisting initialized connection objects in module-level global variables. ## Bad vs Good Implementations ### Module-Level HTTP and Database Client Sharing vs. Thread-Safe Scoped Pool Injection #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In Python 3.13t without the GIL, concurrent native threads executing requests will concurrently mutate internal connection pool buffers and socket pointers within the singular global `httpx.AsyncClient`, leading to race conditions, socket poisoning, and runtime segmentation faults. ```python import httpx from fastapi import FastAPI app = FastAPI() # ANTI-PATTERN: Shared global client without synchronization across free-threaded native threads. # Under Python 3.13t (GIL disabled), concurrent access to the internal transport state causes data races. global_client = httpx.AsyncClient() @app.get("/data") async def fetch_data(): response = await global_client.get("https://api.internal/telemetry") return response.json() ``` #### Production Standard (Correct) > **Standard**: Encapsulates client lifetime cleanly inside the ASGI lifespan context, utilizing connection limit boundaries designed for thread-safe concurrent task orchestration, avoiding unmanaged module-level mutation. ```python from contextlib import asynccontextmanager import httpx from fastapi import FastAPI, Depends from typing import AsyncGenerator # PRODUCTION FIX: Isolate client lifecycles using lifespan context or thread-safe pool dependencies @asynccontextmanager async def lifespan(app: FastAPI): limits = httpx.Limits(max_keepalive_connections=50, max_connections=200) # Transport handles internal thread locks or requests are scoped per context async with httpx.AsyncClient(limits=limits) as client: app.state.http_client = client yield app = FastAPI(lifespan=lifespan) async def get_http_client() -> AsyncGenerator[httpx.AsyncClient, None]: # Retrieve application-scoped client initialized within managed event-loop context client: httpx.AsyncClient = app.state.http_client yield client @app.get("/data") async def fetch_data(client: httpx.AsyncClient = Depends(get_http_client)): response = await client.get("https://api.internal/telemetry") return response.json() ``` ### Global In-Memory Cache Mutex Synchronization in Free-Threaded Runtime #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In free-threaded Python, standard dictionary implementations do not guarantee thread-safe read/write semantics under heavy concurrent thread access. Unsynchronized mutations can cause internal hash-table state corruption. ```python from fastapi import FastAPI app = FastAPI() # ANTI-PATTERN: Plain Python dict modified concurrently across threads in Python 3.13t. # Without the GIL, concurrent updates to dict structures can trigger memory inconsistency. cache: dict[str, str] = {} @app.post("/cache/{key}") async def set_cache(key: str, value: str): cache[key] = value return {"status": "ok"} @app.get("/cache/{key}") async def get_cache(key: str): return {"val": cache.get(key)} ``` #### Production Standard (Correct) > **Standard**: Wraps shared mutable state inside an explicit thread synchronization boundary (`threading.Lock()`), ensuring atomic mutations and consistent reads across all free-threaded ASGI worker threads. ```python import threading from fastapi import FastAPI app = FastAPI() class SynchronizedCache: def __init__(self) -> None: self._lock = threading.Lock() self._data: dict[str, str] = {} def set(self, key: str, value: str) -> None: with self._lock: self._data[key] = value def get(self, key: str) -> str | None: with self._lock: return self._data.get(key) safe_cache = SynchronizedCache() @app.post("/cache/{key}") async def set_cache(key: str, value: str): safe_cache.set(key, value) return {"status": "ok"} @app.get("/cache/{key}") async def get_cache(key: str): return {"val": safe_cache.get(key)} ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI Free-Threaded (Python 3.13t) Worker & Resource Affinity Invariants

FastAPI Free-Threaded (Python 3.13t) Worker & Resource Affinity Invariants defines an industrial-grade behavioral standard for backend engineering. Enforces strict connection pool isolation, thread-local lifecycle scoping, and synchronization primitives across FastAPI ASGI workers executing under Python 3.13+ free-threaded (GIL-disabled) mode. Prohibits sharing non-thread-safe state (such as standard asyncio loop constructs, raw database cursors, and socket wrappers) across concurrent native threads to prevent memory corruption, race conditions, and pool contamination. Mandates thread-safe pool implementations, explicit synchronization, and ASGI worker isolation. 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: Global Mutable State and Leaked Connection Pools Across Free-Threaded Native Worker Threads 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	Global Mutable State and Leaked Connection Pools Across Free-Threaded Native Worker Threads	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 isolate database client instances, HTTP client sessions (e.g., httpx.AsyncClient), and socket handles to worker-specific thread-local storage or acquire them dynamically from thread-safe pools.

Engineers MUST ALWAYS isolate database client instances, HTTP client sessions (e.g., httpx.AsyncClient), and socket handles to worker-specific thread-local storage or acquire them dynamically from thread-safe pools.

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.