@rangojs/router 0.0.0-experimental.0f44aca1

package/src/server/request-context.ts

@@ -0,0 +1,914 @@
+/**
+ * Request Context - AsyncLocalStorage for passing request-scoped data throughout rendering
+ *
+ * This is the unified context used everywhere:
+ * - Middleware execution
+ * - Route handlers and loaders
+ * - Server components during rendering
+ * - Error boundaries and streaming
+ *
+ * Available via getRequestContext() anywhere in the request lifecycle.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { CookieOptions } from "../router/middleware.js";
+import type { LoaderDefinition, LoaderContext } from "../types.js";
+import type { ScopedReverseFunction } from "../reverse.js";
+import type {
+  DefaultEnv,
+  DefaultReverseRouteMap,
+  DefaultRouteName,
+} from "../types/global-namespace.js";
+import type { Handle } from "../handle.js";
+import { type ContextVar, contextGet, contextSet } from "../context-var.js";
+import { createHandleStore, type HandleStore } from "./handle-store.js";
+import { isHandle } from "../handle.js";
+import { track, type MetricsStore } from "./context.js";
+import { getFetchableLoader } from "./fetchable-loader-store.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
+import { THEME_COOKIE } from "../theme/constants.js";
+import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
+import { createReverseFunction } from "../router/handler-context.js";
+import { getGlobalRouteMap, isRouteRootScoped } from "../route-map-builder.js";
+import { invariant } from "../errors.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
+
+/**
+ * Unified request context available via getRequestContext()
+ *
+ * This is the same context passed to middleware and handlers.
+ * Use this when you need access to request data outside of route handlers.
+ */
+export interface RequestContext<
+  TEnv = DefaultEnv,
+  TParams = Record<string, string>,
+> {
+  /** Platform bindings (Cloudflare env, etc.) */
+  env: TEnv;
+  /** Original HTTP request */
+  request: Request;
+  /** Parsed URL (with internal `_rsc*` params stripped) */
+  url: URL;
+  /**
+   * The original request URL with all parameters intact, including
+   * internal `_rsc*` transport params.
+   */
+  originalUrl: URL;
+  /** URL pathname */
+  pathname: string;
+  /** URL search params (system params like _rsc* are NOT filtered here) */
+  searchParams: URLSearchParams;
+  /** Variables set by middleware (same as ctx.var) */
+  var: Record<string, any>;
+  /** Get a variable set by middleware */
+  get: {
+    <T>(contextVar: ContextVar<T>): T | undefined;
+    <K extends string>(key: K): any;
+  };
+  /** Set a variable (shared with middleware and handlers) */
+  set: {
+    <T>(contextVar: ContextVar<T>, value: T): void;
+    <K extends string>(key: K, value: any): void;
+  };
+  /**
+   * Route params (populated after route matching)
+   * Initially empty, then set to matched params
+   */
+  params: TParams;
+  /** @internal Stub response for collecting headers/cookies. Use ctx.headers or ctx.header() instead. */
+  readonly res: Response;
+
+  /** @internal Get a cookie value (effective: request + response mutations). Use cookies().get() instead. */
+  cookie(name: string): string | undefined;
+  /** @internal Get all cookies (effective merged view). Use cookies().getAll() instead. */
+  cookies(): Record<string, string>;
+  /** @internal Set a cookie on the response. Use cookies().set() instead. */
+  setCookie(name: string, value: string, options?: CookieOptions): void;
+  /** @internal Delete a cookie. Use cookies().delete() instead. */
+  deleteCookie(
+    name: string,
+    options?: Pick<CookieOptions, "domain" | "path">,
+  ): void;
+  /** Set a response header */
+  header(name: string, value: string): void;
+  /** Set the response status code */
+  setStatus(status: number): void;
+  /** @internal Set status bypassing cache-exec guard (for framework error handling) */
+  _setStatus(status: number): void;
+
+  /**
+   * Access loader data or push handle data.
+   *
+   * For loaders: Returns a promise that resolves to the loader data.
+   * Loaders are executed in parallel and memoized per request.
+   *
+   * For handles: Returns a push function to add data for this segment.
+   * Handle data accumulates across all matched route segments.
+   *
+   * @example
+   * ```typescript
+   * // Loader usage
+   * const cart = await ctx.use(CartLoader);
+   *
+   * // Handle usage
+   * const push = ctx.use(Breadcrumbs);
+   * push({ label: "Shop", href: "/shop" });
+   * ```
+   */
+  use: {
+    <T, TLoaderParams = any>(
+      loader: LoaderDefinition<T, TLoaderParams>,
+    ): Promise<T>;
+    <TData, TAccumulated = TData[]>(
+      handle: Handle<TData, TAccumulated>,
+    ): (data: TData | Promise<TData> | (() => Promise<TData>)) => void;
+  };
+
+  /** HTTP method (GET, POST, PUT, PATCH, DELETE, etc.) */
+  method: string;
+
+  /** @internal Handle store for tracking handle data across segments */
+  _handleStore: HandleStore;
+
+  /** @internal Cache store for segment caching (optional, used by CacheScope) */
+  _cacheStore?: SegmentCacheStore;
+
+  /** @internal Cache profiles for "use cache" profile resolution (per-router) */
+  _cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
+
+  /**
+   * Schedule work to run after the response is sent.
+   * On Cloudflare Workers, uses ctx.waitUntil().
+   * On Node.js, runs as fire-and-forget.
+   *
+   * @example
+   * ```typescript
+   * ctx.waitUntil(async () => {
+   *   await cacheStore.set(key, data, ttl);
+   * });
+   * ```
+   */
+  waitUntil(fn: () => Promise<void>): void;
+
+  /**
+   * Register a callback to run when the response is created.
+   * Callbacks are sync and receive the response. They can:
+   * - Inspect response status/headers
+   * - Return a modified response
+   * - Schedule async work via waitUntil
+   *
+   * @example
+   * ```typescript
+   * ctx.onResponse((res) => {
+   *   if (res.status === 200) {
+   *     ctx.waitUntil(async () => await cacheIt());
+   *   }
+   *   return res;
+   * });
+   * ```
+   */
+  onResponse(callback: (response: Response) => Response): void;
+
+  /** @internal Registered onResponse callbacks */
+  _onResponseCallbacks: Array<(response: Response) => Response>;
+
+  /**
+   * Current theme setting (only available when theme is enabled in router config)
+   *
+   * Returns the theme value from the cookie, or the default theme if not set.
+   * This is the user's preference ("light", "dark", or "system"), not the resolved value.
+   *
+   * @example
+   * ```typescript
+   * route("settings", (ctx) => {
+   *   const currentTheme = ctx.theme; // "light" | "dark" | "system" | undefined
+   *   return <SettingsPage theme={currentTheme} />;
+   * });
+   * ```
+   */
+  theme?: Theme;
+
+  /**
+   * Set the theme (only available when theme is enabled in router config)
+   *
+   * Sets a cookie with the new theme value. The change takes effect on the next request.
+   *
+   * @example
+   * ```typescript
+   * route("settings", (ctx) => {
+   *   if (ctx.method === "POST") {
+   *     const formData = await ctx.request.formData();
+   *     const newTheme = formData.get("theme") as Theme;
+   *     ctx.setTheme(newTheme);
+   *   }
+   *   return <SettingsPage />;
+   * });
+   * ```
+   */
+  setTheme?: (theme: Theme) => void;
+
+  /** @internal Theme configuration (null if theme not enabled) */
+  _themeConfig?: ResolvedThemeConfig | null;
+
+  /**
+   * Attach location state entries to the current response.
+   *
+   * For partial (SPA) requests, the state is included in the RSC payload
+   * metadata and merged into history.pushState on the client. For redirect
+   * responses, the state travels through the redirect payload so the target
+   * page can read it via useLocationState.
+   *
+   * Multiple calls accumulate entries.
+   *
+   * @example
+   * ```typescript
+   * ctx.setLocationState(Flash({ text: "Item saved!" }));
+   * ```
+   */
+  setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
+
+  /** @internal Accumulated location state entries */
+  _locationState?: LocationStateEntry[];
+
+  /**
+   * The matched route name, if the route has an explicit name.
+   * Undefined before route matching or for unnamed routes.
+   * Includes the namespace prefix from include() (e.g., "blog.post").
+   */
+  routeName?: DefaultRouteName;
+
+  /**
+   * Generate URLs from route names.
+   * Uses the global route map. After route matching, scoped (`.name`) resolution
+   * works within the matched include() scope.
+   */
+  reverse: ScopedReverseFunction<
+    Record<string, string>,
+    DefaultReverseRouteMap
+  >;
+
+  /** @internal Route name from route matching, used for scoped reverse resolution */
+  _routeName?: string;
+
+  /** @internal Previous route key (from the navigation source), used for revalidation */
+  _prevRouteKey?: string;
+
+  /** @internal Per-request error dedup set for onError reporting */
+  _reportedErrors: WeakSet<object>;
+
+  /**
+   * @internal Report a non-fatal background error through the router's
+   * onError callback. Wired by the RSC handler / router during request
+   * creation. Cache-runtime and other subsystems call this to surface
+   * errors without failing the response.
+   */
+  _reportBackgroundError?: (error: unknown, category: string) => void;
+
+  /** @internal Per-request debug performance override (set via ctx.debugPerformance()) */
+  _debugPerformance?: boolean;
+
+  /** @internal Request-scoped performance metrics store */
+  _metricsStore?: MetricsStore;
+}
+
+/**
+ * Public view of RequestContext, without internal methods and fields.
+ *
+ * This is the type exported to library consumers. Internal code should
+ * use the full RequestContext interface directly.
+ */
+export type PublicRequestContext<
+  TEnv = DefaultEnv,
+  TParams = Record<string, string>,
+> = Omit<
+  RequestContext<TEnv, TParams>,
+  | "cookie"
+  | "cookies"
+  | "setCookie"
+  | "deleteCookie"
+  | "_handleStore"
+  | "_cacheStore"
+  | "_cacheProfiles"
+  | "_onResponseCallbacks"
+  | "_themeConfig"
+  | "_locationState"
+  | "_routeName"
+  | "_prevRouteKey"
+  | "_reportedErrors"
+  | "_reportBackgroundError"
+  | "_debugPerformance"
+  | "_metricsStore"
+  | "_setStatus"
+  | "res"
+>;
+
+// AsyncLocalStorage instance for request context
+const requestContextStorage = new AsyncLocalStorage<RequestContext<any>>();
+
+/**
+ * Run a function within a request context
+ * Used by the RSC handler to provide context to server actions
+ */
+export function runWithRequestContext<TEnv, T>(
+  context: RequestContext<TEnv>,
+  fn: () => T,
+): T {
+  return requestContextStorage.run(context, fn);
+}
+
+/**
+ * Get the current request context
+ * Throws if called outside of a request context
+ */
+export function getRequestContext<TEnv = DefaultEnv>(): RequestContext<TEnv> {
+  const ctx = requestContextStorage.getStore() as
+    | RequestContext<TEnv>
+    | undefined;
+  invariant(
+    ctx,
+    "getRequestContext() called outside of a request context. " +
+      "This function must be called from within a route handler, loader, middleware, " +
+      "server action, or server component.",
+  );
+  return ctx;
+}
+
+/**
+ * @internal Get the request context without throwing — for internal code that
+ * may run outside a request context (cache stores, optional handle lookups, etc.)
+ */
+export function _getRequestContext<TEnv = DefaultEnv>():
+  | RequestContext<TEnv>
+  | undefined {
+  return requestContextStorage.getStore() as RequestContext<TEnv> | undefined;
+}
+
+/**
+ * Update params on the current request context
+ * Called after route matching to populate route params and route name
+ */
+export function setRequestContextParams(
+  params: Record<string, string>,
+  routeName?: string,
+): void {
+  const ctx = requestContextStorage.getStore();
+  if (ctx) {
+    ctx.params = params;
+    if (routeName !== undefined) {
+      ctx._routeName = routeName;
+      ctx.routeName = (
+        routeName && !isAutoGeneratedRouteName(routeName)
+          ? routeName
+          : undefined
+      ) as DefaultRouteName | undefined;
+    }
+    // Update reverse with scoped resolution now that route is known
+    ctx.reverse = createReverseFunction(
+      getGlobalRouteMap(),
+      routeName,
+      params,
+      routeName ? isRouteRootScoped(routeName) : undefined,
+    );
+  }
+}
+
+/**
+ * Store the previous route key on the request context.
+ * Called during partial-match context creation to make the navigation source
+ * route key available for revalidation and intercept evaluation.
+ * @internal
+ */
+export function setRequestContextPrevRouteKey(
+  prevRouteKey: string | undefined,
+): void {
+  const ctx = requestContextStorage.getStore();
+  if (ctx && prevRouteKey !== undefined) {
+    ctx._prevRouteKey = prevRouteKey;
+  }
+}
+
+/**
+ * Get accumulated location state entries from the current request context.
+ * Returns undefined if no state has been set.
+ *
+ * @internal Used by the RSC handler to include state in payload metadata.
+ */
+export function getLocationState(): LocationStateEntry[] | undefined {
+  const ctx = getRequestContext();
+  return ctx?._locationState;
+}
+
+/**
+ * Get the current request context, throwing if not available
+ * @deprecated Use getRequestContext() directly — it now throws if outside context
+ */
+export function requireRequestContext<
+  TEnv = DefaultEnv,
+>(): RequestContext<TEnv> {
+  return getRequestContext<TEnv>();
+}
+
+/**
+ * Cloudflare Workers ExecutionContext (subset we need)
+ */
+export interface ExecutionContext {
+  waitUntil(promise: Promise<any>): void;
+  passThroughOnException(): void;
+}
+
+/**
+ * Options for creating a request context
+ */
+export interface CreateRequestContextOptions<TEnv> {
+  env: TEnv;
+  request: Request;
+  url: URL;
+  variables: Record<string, any>;
+  /** Optional initial response stub headers/status to seed effective cookie reads */
+  initialResponse?: Response;
+  /** Optional cache store for segment caching (used by CacheScope) */
+  cacheStore?: SegmentCacheStore;
+  /** Optional cache profiles for "use cache" resolution (per-router) */
+  cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
+  /** Optional Cloudflare execution context for waitUntil support */
+  executionContext?: ExecutionContext;
+  /** Optional theme configuration (enables ctx.theme and ctx.setTheme) */
+  themeConfig?: ResolvedThemeConfig | null;
+}
+
+/**
+ * Create a full request context with all methods implemented
+ *
+ * This is used by the RSC handler to create the unified context that's:
+ * - Available via getRequestContext() throughout the request
+ * - Passed to middleware as ctx
+ * - Passed to handlers as ctx
+ */
+export function createRequestContext<TEnv>(
+  options: CreateRequestContextOptions<TEnv>,
+): RequestContext<TEnv> {
+  const {
+    env,
+    request,
+    url,
+    variables,
+    initialResponse,
+    cacheStore,
+    cacheProfiles,
+    executionContext,
+    themeConfig,
+  } = options;
+  const cookieHeader = request.headers.get("Cookie");
+  let parsedCookies: Record<string, string> | null = null;
+
+  // Create stub response for collecting headers/cookies.
+  // All cookie/header mutations go here; cookie reads derive from it.
+  let stubResponse = initialResponse
+    ? new Response(null, {
+        status: initialResponse.status,
+        statusText: initialResponse.statusText,
+        headers: new Headers(initialResponse.headers),
+      })
+    : new Response(null, { status: 200 });
+
+  // Create handle store and loader memoization for this request
+  const handleStore = createHandleStore();
+  const loaderPromises = new Map<string, Promise<any>>();
+
+  // Lazy parse cookies from the original Cookie header
+  const getParsedCookies = (): Record<string, string> => {
+    if (!parsedCookies) {
+      parsedCookies = parseCookiesFromHeader(cookieHeader);
+    }
+    return parsedCookies;
+  };
+
+  // Cached response cookie mutations — invalidated on setCookie/deleteCookie/setTheme
+  let responseCookieCache: Map<string, string | null> | null = null;
+  const getResponseCookies = (): Map<string, string | null> => {
+    if (!responseCookieCache) {
+      responseCookieCache = parseResponseCookies(stubResponse);
+    }
+    return responseCookieCache;
+  };
+  const invalidateResponseCookieCache = () => {
+    responseCookieCache = null;
+  };
+
+  // Effective cookie read: response stub Set-Cookie wins, then original header.
+  // The stub IS the source of truth for same-request mutations.
+  const effectiveCookie = (name: string): string | undefined => {
+    const mutations = getResponseCookies();
+    if (mutations.has(name)) {
+      const v = mutations.get(name);
+      return v === null ? undefined : v;
+    }
+    return getParsedCookies()[name];
+  };
+
+  // Theme helpers (only used when themeConfig is provided)
+  const getTheme = (): Theme | undefined => {
+    if (!themeConfig) return undefined;
+
+    // Use overlay-aware read so setTheme() in the same request is reflected
+    const stored = effectiveCookie(themeConfig.storageKey);
+    if (stored) {
+      // Validate stored value
+      if (stored === "system" && themeConfig.enableSystem) {
+        return "system";
+      }
+      if (themeConfig.themes.includes(stored)) {
+        return stored as Theme;
+      }
+    }
+    return themeConfig.defaultTheme;
+  };
+
+  const setTheme = (theme: Theme): void => {
+    if (!themeConfig) return;
+
+    // Validate theme value
+    if (theme !== "system" && !themeConfig.themes.includes(theme)) {
+      console.warn(
+        `[Theme] Invalid theme value: "${theme}". Valid values: system, ${themeConfig.themes.join(", ")}`,
+      );
+      return;
+    }
+
+    // Write to stub — effectiveCookie() will pick it up on next read
+    stubResponse.headers.append(
+      "Set-Cookie",
+      serializeCookieValue(themeConfig.storageKey, theme, {
+        path: THEME_COOKIE.path,
+        maxAge: THEME_COOKIE.maxAge,
+        sameSite: THEME_COOKIE.sameSite,
+      }),
+    );
+    invalidateResponseCookieCache();
+  };
+
+  // Build the context object first (without use), then add use
+  const ctx: RequestContext<TEnv> = {
+    env,
+    request,
+    url,
+    originalUrl: new URL(request.url),
+    pathname: url.pathname,
+    searchParams: url.searchParams,
+    var: variables,
+    get: ((keyOrVar: any) =>
+      contextGet(variables, keyOrVar)) as RequestContext<TEnv>["get"],
+    set: ((keyOrVar: any, value: any) => {
+      assertNotInsideCacheExec(ctx, "set");
+      contextSet(variables, keyOrVar, value);
+    }) as RequestContext<TEnv>["set"],
+    params: {} as Record<string, string>,
+
+    get res(): Response {
+      return stubResponse;
+    },
+    set res(_: Response) {
+      throw new Error(
+        "ctx.res is read-only. Use ctx.header() to set response headers, or cookies() for cookie mutations.",
+      );
+    },
+
+    cookie(name: string): string | undefined {
+      return effectiveCookie(name);
+    },
+
+    cookies(): Record<string, string> {
+      const parsed = getParsedCookies();
+      const mutations = getResponseCookies();
+      if (mutations.size === 0) return { ...parsed };
+      // Build result without delete (avoids V8 dictionary-mode de-opt)
+      const deleted = new Set<string>();
+      for (const [k, v] of mutations) {
+        if (v === null) deleted.add(k);
+      }
+      const result: Record<string, string> = {};
+      for (const key of Object.keys(parsed)) {
+        if (!deleted.has(key)) result[key] = parsed[key];
+      }
+      for (const [k, v] of mutations) {
+        if (v !== null) result[k] = v;
+      }
+      return result;
+    },
+
+    setCookie(name: string, value: string, options?: CookieOptions): void {
+      assertNotInsideCacheExec(ctx, "setCookie");
+      stubResponse.headers.append(
+        "Set-Cookie",
+        serializeCookieValue(name, value, options),
+      );
+      invalidateResponseCookieCache();
+    },
+
+    deleteCookie(
+      name: string,
+      options?: Pick<CookieOptions, "domain" | "path">,
+    ): void {
+      assertNotInsideCacheExec(ctx, "deleteCookie");
+      stubResponse.headers.append(
+        "Set-Cookie",
+        serializeCookieValue(name, "", { ...options, maxAge: 0 }),
+      );
+      invalidateResponseCookieCache();
+    },
+
+    header(name: string, value: string): void {
+      assertNotInsideCacheExec(ctx, "header");
+      stubResponse.headers.set(name, value);
+    },
+
+    setStatus(status: number): void {
+      assertNotInsideCacheExec(ctx, "setStatus");
+      stubResponse = new Response(null, {
+        status,
+        headers: stubResponse.headers,
+      });
+    },
+
+    _setStatus(status: number): void {
+      stubResponse = new Response(null, {
+        status,
+        headers: stubResponse.headers,
+      });
+    },
+
+    // Placeholder - will be replaced below
+    use: null as any,
+
+    method: request.method,
+
+    _handleStore: handleStore,
+    _cacheStore: cacheStore,
+    _cacheProfiles: cacheProfiles,
+
+    waitUntil(fn: () => Promise<void>): void {
+      if (executionContext?.waitUntil) {
+        // Cloudflare Workers: use native waitUntil
+        executionContext.waitUntil(fn());
+      } else {
+        // Node.js / dev: fire-and-forget with error logging
+        fn().catch((err) =>
+          console.error("[waitUntil] Background task failed:", err),
+        );
+      }
+    },
+
+    _onResponseCallbacks: [],
+
+    onResponse(callback: (response: Response) => Response): void {
+      assertNotInsideCacheExec(ctx, "onResponse");
+      this._onResponseCallbacks.push(callback);
+    },
+
+    // Theme properties (only set when themeConfig is provided)
+    get theme() {
+      return themeConfig ? getTheme() : undefined;
+    },
+    setTheme: themeConfig
+      ? (theme: Theme) => {
+          assertNotInsideCacheExec(ctx, "setTheme");
+          setTheme(theme);
+        }
+      : undefined,
+    _themeConfig: themeConfig,
+
+    setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void {
+      assertNotInsideCacheExec(ctx, "setLocationState");
+      const arr = Array.isArray(entries) ? entries : [entries];
+      this._locationState = this._locationState
+        ? [...this._locationState, ...arr]
+        : arr;
+    },
+    _locationState: undefined,
+
+    _reportedErrors: new WeakSet<object>(),
+    _metricsStore: undefined,
+
+    reverse: createReverseFunction(getGlobalRouteMap(), undefined, {}),
+  };
+
+  // Now create use() with access to ctx
+  ctx.use = createUseFunction({
+    handleStore,
+    loaderPromises,
+    getContext: () => ctx,
+  });
+
+  // Brand with taint symbol so "use cache" excludes ctx from cache keys
+  (ctx as any)[NOCACHE_SYMBOL] = true;
+  return ctx;
+}
+
+/**
+ * Parse Set-Cookie headers from a response into effective cookie state.
+ * Returns a map of cookie name -> value (string) or name -> null (deleted).
+ * Last-write-wins: later Set-Cookie entries for the same name overwrite earlier ones.
+ * Max-Age=0 is treated as a delete.
+ */
+const MAX_AGE_ZERO_RE = /;\s*Max-Age\s*=\s*0/i;
+
+function parseResponseCookies(response: Response): Map<string, string | null> {
+  const result = new Map<string, string | null>();
+  const setCookies = response.headers.getSetCookie();
+
+  for (const header of setCookies) {
+    // First segment before ';' is the name=value pair
+    const semiIdx = header.indexOf(";");
+    const pair = semiIdx === -1 ? header : header.substring(0, semiIdx);
+    const eqIdx = pair.indexOf("=");
+    if (eqIdx === -1) continue;
+
+    let name: string;
+    let value: string;
+    try {
+      name = decodeURIComponent(pair.substring(0, eqIdx).trim());
+      value = decodeURIComponent(pair.substring(eqIdx + 1).trim());
+    } catch {
+      // Malformed encoding — skip this entry
+      continue;
+    }
+
+    // Max-Age=0 means the cookie is being deleted
+    const isDeleted = MAX_AGE_ZERO_RE.test(header);
+    result.set(name, isDeleted ? null : value);
+  }
+
+  return result;
+}
+
+/**
+ * Parse cookies from Cookie header
+ */
+function parseCookiesFromHeader(
+  cookieHeader: string | null,
+): Record<string, string> {
+  if (!cookieHeader) return {};
+
+  const cookies: Record<string, string> = {};
+  const pairs = cookieHeader.split(";");
+
+  for (const pair of pairs) {
+    const [name, ...rest] = pair.trim().split("=");
+    if (name) {
+      const raw = rest.join("=");
+      try {
+        cookies[name] = decodeURIComponent(raw);
+      } catch {
+        // Malformed percent-encoded value (e.g. %zz, %2) - fall back to raw value
+        cookies[name] = raw;
+      }
+    }
+  }
+
+  return cookies;
+}
+
+/**
+ * Serialize a cookie for Set-Cookie header
+ */
+function serializeCookieValue(
+  name: string,
+  value: string,
+  options: CookieOptions = {},
+): string {
+  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
+
+  if (options.domain) cookie += `; Domain=${options.domain}`;
+  if (options.path) cookie += `; Path=${options.path}`;
+  if (options.maxAge !== undefined) cookie += `; Max-Age=${options.maxAge}`;
+  if (options.expires) cookie += `; Expires=${options.expires.toUTCString()}`;
+  if (options.httpOnly) cookie += "; HttpOnly";
+  if (options.secure) cookie += "; Secure";
+  if (options.sameSite) cookie += `; SameSite=${options.sameSite}`;
+
+  return cookie;
+}
+
+/**
+ * Options for creating the use() function
+ */
+export interface CreateUseFunctionOptions<TEnv> {
+  handleStore: HandleStore;
+  loaderPromises: Map<string, Promise<any>>;
+  getContext: () => RequestContext<TEnv>;
+}
+
+/**
+ * Create the use() function for loader and handle composition.
+ *
+ * This is the unified implementation used by both RequestContext and HandlerContext.
+ * - For loaders: executes and memoizes loader functions
+ * - For handles: returns a push function to add handle data
+ */
+export function createUseFunction<TEnv>(
+  options: CreateUseFunctionOptions<TEnv>,
+): RequestContext["use"] {
+  const { handleStore, loaderPromises, getContext } = options;
+
+  return ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
+    // Handle case: return a push function
+    if (isHandle(item)) {
+      const handle = item;
+      const ctx = getContext();
+      const segmentId = (ctx as any)._currentSegmentId;
+
+      if (!segmentId) {
+        throw new Error(
+          `Handle "${handle.$$id}" used outside of handler context. ` +
+            `Handles must be used within route/layout handlers.`,
+        );
+      }
+
+      // Return a push function bound to this handle and segment
+      return (
+        dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>),
+      ) => {
+        // If it's a function, call it immediately to get the promise
+        const valueOrPromise =
+          typeof dataOrFn === "function"
+            ? (dataOrFn as () => Promise<unknown>)()
+            : dataOrFn;
+
+        // Push directly - promises will be serialized by RSC and streamed
+        handleStore.push(handle.$$id, segmentId, valueOrPromise);
+      };
+    }
+
+    // Loader case
+    const loader = item as LoaderDefinition<any, any>;
+
+    // Return cached promise if already started
+    if (loaderPromises.has(loader.$$id)) {
+      return loaderPromises.get(loader.$$id);
+    }
+
+    // Get loader function - either from loader object or fetchable registry
+    let loaderFn = loader.fn;
+    if (!loaderFn) {
+      const fetchable = getFetchableLoader(loader.$$id);
+      if (fetchable) {
+        loaderFn = fetchable.fn;
+      }
+    }
+
+    if (!loaderFn) {
+      throw new Error(
+        `Loader "${loader.$$id}" has no function. This usually means the loader was defined without "use server" and the function was not included in the build.`,
+      );
+    }
+
+    const ctx = getContext();
+
+    // Create loader context with recursive use() support
+    const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
+      params: ctx.params,
+      routeParams: (ctx.params ?? {}) as Record<string, string>,
+      request: ctx.request,
+      searchParams: ctx.searchParams,
+      search: (ctx as any).search ?? {},
+      pathname: ctx.pathname,
+      url: ctx.url,
+      env: ctx.env as any,
+      var: ctx.var as any,
+      get: ctx.get as any,
+      use: <TDep, TDepParams = any>(
+        dep: LoaderDefinition<TDep, TDepParams>,
+      ): Promise<TDep> => {
+        // Recursive call - will start dep loader if not already started
+        return ctx.use(dep);
+      },
+      method: "GET",
+      body: undefined,
+      reverse: createReverseFunction(
+        getGlobalRouteMap(),
+        ctx._routeName,
+        ctx.params as Record<string, string>,
+        ctx._routeName ? isRouteRootScoped(ctx._routeName) : undefined,
+      ),
+    };
+
+    // Start loader execution with tracking
+    const doneLoader = track(`loader:${loader.$$id}`, 2);
+    const promise = Promise.resolve(loaderFn(loaderCtx)).finally(() => {
+      doneLoader();
+    });
+
+    // Memoize for subsequent calls
+    loaderPromises.set(loader.$$id, promise);
+
+    return promise;
+  }) as RequestContext["use"];
+}