Fastify v5 AsyncLocalStorage Request Context Isolation & Anti-Bleed Standard

--- description: Fastify v5 AsyncLocalStorage Request Context Isolation & Anti-Bleed Standard - Enforces strict AsyncLocalStorage boundary encapsulation across Fastify v5 request lifecycles to prevent cross-tenant telemetry, logging, and security context leakage. Mandates execution within async hook boundaries (onRequest/preHandler) using explicit `als.run()` scopes instead of naive `als.enterWith()`, ensuring determinism across asynchronous continuations, connection pool handoffs, and microtask queues. globs: src/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastify-v5-asynclocalstorage-context-isolation-standard" --- # Fastify v5 AsyncLocalStorage Request Context Isolation & Anti-Bleed Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Ambient ALS Mutability via enterWith() and Hook De-synchronization Leading to Cross-Tenant Context Pollution ## System Constraints You are a Principal Backend Architect enforcing zero-leakage multitenancy and deterministic request tracing in Fastify v5 microservices. You must enforce strict AsyncLocalStorage (ALS) scoping using deterministic `als.run()` wrappers within Fastify's request lifecycle, banning `als.enterWith()` and unconfined promise branches. ## Strict Guidelines - Engineers MUST ALWAYS wrap request lifecycles inside `als.run(context, ...)` within Fastify's `onRequest` hook using callback or async continuation patterns. - Engineers MUST NEVER invoke `als.enterWith()` inside route handlers, plugins, or lifecycle hooks, as it pollutes ambient Node.js event-loop turns and leaks across concurrent requests. - Engineers MUST ensure that any background tasks or fire-and-forget asynchronous promises spawned outside the primary request pipeline capture the store explicitly or run in an isolated ALS branch via `als.run()`. - Services MUST extract context strictly through immutable getter accessors that throw a typed `RequestContextNotFoundError` if invoked outside an active request scope. - Components NEVER store mutable request context references on singleton services, Fastify instance decorators, or module-scoped global variables. - Engineers MUST register ALS context-binding hooks prior to any routing, body parsing, or authentication plugins to guarantee complete lifecycle telemetry capture. ## Bad vs Good Implementations ### Naive Context Setup via enterWith() vs Deterministic als.run() in onRequest Hook #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: `als.enterWith()` overwrites ambient execution context across un-nested promise ticks and event loop turns. Under high concurrency in Fastify, this causes request context bleeding across distinct tenants, exposing critical cross-tenant data. ```typescript import { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify'; import { AsyncLocalStorage } from 'node:async_hooks'; interface RequestContext { tenantId: string; requestId: string; } export const als = new AsyncLocalStorage<RequestContext>(); export async function registerContextPlugin(app: FastifyInstance) { // CRITICAL BUG: enterWith() leaks state across concurrent async ticks app.addHook('onRequest', async (req: FastifyRequest) => { const tenantId = (req.headers['x-tenant-id'] as string) || 'anonymous'; als.enterWith({ tenantId, requestId: req.id }); }); app.get('/tenant-data', async () => { // Under load, this returns another tenant's ID due to context bleed const ctx = als.getStore(); return { tenantId: ctx?.tenantId }; }); } ``` #### Production Standard (Correct) > **Standard**: Encapsulating the request continuation within `als.run()` inside a standard callback-based `onRequest` hook enforces strict lexical and asynchronous boundary isolation, guaranteeing zero cross-tenant context pollution across concurrent promises. ```typescript import { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify'; import { AsyncLocalStorage } from 'node:async_hooks'; export interface RequestContext { readonly tenantId: string; readonly requestId: string; } export const als = new AsyncLocalStorage<RequestContext>(); export class MissingContextError extends Error { constructor() { super('Active RequestContext missing from AsyncLocalStorage'); this.name = 'MissingContextError'; } } export function getRequestContext(): RequestContext { const store = als.getStore(); if (!store) { throw new MissingContextError(); } return store; } export async function registerContextPlugin(app: FastifyInstance) { // Deterministic isolation: wrap downstream execution inside als.run app.addHook('onRequest', (req: FastifyRequest, _reply: FastifyReply, done: (err?: Error) => void) => { const tenantId = (req.headers['x-tenant-id'] as string) || 'anonymous'; const context: RequestContext = Object.freeze({ tenantId, requestId: req.id }); als.run(context, () => { done(); }); }); app.get('/tenant-data', async () => { const ctx = getRequestContext(); return { tenantId: ctx.tenantId }; }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Fastify v5 AsyncLocalStorage Request Context Isolation & Anti-Bleed Standard

Fastify v5 AsyncLocalStorage Request Context Isolation & Anti-Bleed Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict AsyncLocalStorage boundary encapsulation across Fastify v5 request lifecycles to prevent cross-tenant telemetry, logging, and security context leakage. Mandates execution within async hook boundaries (onRequest/preHandler) using explicit `als.run()` scopes instead of naive `als.enterWith()`, ensuring determinism across asynchronous continuations, connection pool handoffs, and microtask queues. 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: Ambient ALS Mutability via enterWith() and Hook De-synchronization Leading to Cross-Tenant Context Pollution 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	Ambient ALS Mutability via enterWith() and Hook De-synchronization Leading to Cross-Tenant Context Pollution	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 wrap request lifecycles inside `als.run(context, ...)` within Fastify's `onRequest` hook using callback or async continuation patterns.

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.