Next.js 15 Async Request Context & AsyncLocalStorage Isolation Standard

--- description: Next.js 15 Async Request Context & AsyncLocalStorage Isolation Standard - Enforces strict isolation of Node.js AsyncLocalStorage (ALS) and Next.js 15 dynamic asynchronous request boundaries during concurrent React Server Component (RSC) streaming renders. Prevents cross-request telemetry contamination, cryptographic context bleed, and tenant credential mixing caused by un-scoped ALS contexts, module-level singletons, and microtask interleaving. globs: app/**/*.{ts,tsx}, src/app/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, src/lib/**/*.{ts,tsx}, middleware.ts, src/middleware.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nextjs-15-async-request-context-als-leak-guardrail" --- # Next.js 15 Async Request Context & AsyncLocalStorage Isolation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module-Level State and Unbounded AsyncLocalStorage Execution Leaking Across Interleaved Streaming RSC Render Passes ## System Constraints You are a Principal Software Architect enforcing the Next.js 15 Async Request Context & AsyncLocalStorage Isolation Standard. You must prevent cross-tenant and cross-request state contamination in concurrent, streaming React Server Component (RSC) environments. Next.js 15 converts dynamic request APIs (cookies, headers, params, searchParams) to Promises. You must reject any module-level mutable variables, uncontained AsyncLocalStorage.enterWith() invocations, and fire-and-forget background promises that omit explicit execution context binding. Mandate React cache() for request-lifetime memoization and strict, immutable AsyncLocalStorage.run() scope enforcement. ## Strict Guidelines - Engineers MUST ALWAYS isolate request-specific cryptographic nonces, tenant IDs, and telemetry spans using immutable context wrappers executed via AsyncLocalStorage.run() or per-request React.cache() singletons. - Engineers MUST NOT invoke AsyncLocalStorage.enterWith() in Next.js Server Components, Server Actions, Route Handlers, or Middleware, as it permanently mutates the V8 execution context across asynchronous boundaries and bleeds state across interleaved RSC streams. - Engineers MUST NOT store per-request telemetry, authentication tokens, or tenancy data in module-scoped variables or outer-closure singletons. - Code MUST explicitly await all Next.js 15 dynamic APIs (e.g., await headers(), await cookies()) before capturing context state to guarantee proper subscription to the current request's asynchronous boundary. - Services that dispatch asynchronous background tasks or detached promises from within an RSC render pass MUST capture the active ALS store snapshot using AsyncLocalStorage.bind() or run within an explicitly re-entered boundary. - Components NEVER reassign or mutate the value returned from an AsyncLocalStorage.getStore() call; stores MUST be treated as strictly read-only and deeply frozen. ## Bad vs Good Implementations ### Module-Level Mutable State vs React cache() with AsyncLocalStorage.run Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: AsyncLocalStorage.enterWith() mutates the current execution resource transition permanently, which in Node.js/Next.js streaming environments causes subsequent microtasks and interleaved RSC components from different HTTP requests to read the mutated context. The fallback to the mutable module-level variable globalActiveTenant guarantees cross-tenant state bleed under load. ```typescript import { AsyncLocalStorage } from 'node:async_hooks'; interface RequestContext { tenantId: string; traceId: string; signingKey: string; } // ANTI-PATTERN: Module-level singleton and enterWith() bleed across concurrent streaming chunks export const requestContextStorage = new AsyncLocalStorage<RequestContext>(); let globalActiveTenant = 'default'; export async function initContext(tenantId: string, traceId: string, signingKey: string) { globalActiveTenant = tenantId; // enterWith leaks context past the async turn into concurrent RSC render passes requestContextStorage.enterWith({ tenantId, traceId, signingKey }); } export function getRequestContext(): RequestContext { const store = requestContextStorage.getStore(); if (!store) { return { tenantId: globalActiveTenant, traceId: 'unknown', signingKey: 'fallback' }; } return store; } ``` #### Production Standard (Correct) > **Standard**: Utilizes React.cache() to tie context resolution directly to the Next.js 15 request lifecycle, safely awaiting dynamic headers(). The context object is deeply frozen, and AsyncLocalStorage.run() is enforced to guarantee strict stack/scope containment with zero global mutation or cross-request pollution. ```typescript import { AsyncLocalStorage } from 'node:async_hooks'; import { cache } from 'react'; import { headers } from 'next/headers'; export interface RequestContext { readonly tenantId: string; readonly traceId: string; readonly signingKey: string; } const asyncLocalStorage = new AsyncLocalStorage<RequestContext>(); /** * React.cache() guarantees reference stability per-request tree in Next.js 15 RSC. * Dynamic APIs (headers(), cookies()) are awaited to establish the dynamic boundary. */ export const getRequestContext = cache(async (): Promise<RequestContext> => { const headerList = await headers(); const tenantId = headerList.get('x-tenant-id'); const traceId = headerList.get('x-trace-id') ?? crypto.randomUUID(); if (!tenantId) { throw new Error('Tenant context isolation failure: Missing required header'); } const context: RequestContext = Object.freeze({ tenantId, traceId, signingKey: crypto.createHash('sha256').update(tenantId).digest('hex'), }); return context; }); /** * Strictly scoped execution boundary for external service calls or background dispatches. */ export async function withRequestContext<T>( context: RequestContext, fn: () => Promise<T> ): Promise<T> { return asyncLocalStorage.run(context, fn); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 Async Request Context & AsyncLocalStorage Isolation Standard

Next.js 15 Async Request Context & AsyncLocalStorage Isolation Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation of Node.js AsyncLocalStorage (ALS) and Next.js 15 dynamic asynchronous request boundaries during concurrent React Server Component (RSC) streaming renders. Prevents cross-request telemetry contamination, cryptographic context bleed, and tenant credential mixing caused by un-scoped ALS contexts, module-level singletons, and microtask interleaving. 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 Module-Level State and Unbounded AsyncLocalStorage Execution Leaking Across Interleaved Streaming RSC Render Passes 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 Module-Level State and Unbounded AsyncLocalStorage Execution Leaking Across Interleaved Streaming RSC Render Passes	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 request-specific cryptographic nonces, tenant IDs, and telemetry spans using immutable context wrappers executed via AsyncLocalStorage.run() or per-request React.cache() singletons.

Engineers MUST ALWAYS isolate request-specific cryptographic nonces, tenant IDs, and telemetry spans using immutable context wrappers executed via AsyncLocalStorage.run() or per-request React.cache() singletons.

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.