@rangojs/router 0.0.0-experimental.15 → 0.0.0-experimental.151

package/src/server/cookie-parse.ts

@@ -0,0 +1,32 @@
+/**
+ * Canonical inbound-Cookie-header parser.
+ *
+ * Kept as a dependency-free leaf so any consumer (request-context, the host
+ * dispatcher, tests) can share one implementation without pulling a heavier
+ * module's graph. A duplicate copy in middleware-cookies.ts was removed; the
+ * host copy in cookie-handler.ts was collapsed onto this one. Not part of the
+ * public export surface.
+ */
+export 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-encoding: fall back to raw value
+        cookies[name] = raw;
+      }
+    }
+  }
+
+  return cookies;
+}

package/src/server/cookie-store.ts

@@ -0,0 +1,337 @@
+/**
+ * Cookie Store — Next.js-style cookie facade backed by the response-derived model.
+ *
+ * `cookies()` returns a CookieStore scoped to the current request.
+ * Reads merge the original Cookie header with Set-Cookie mutations
+ * already queued on the response stub (last-write-wins).
+ * Writes append Set-Cookie to the response stub.
+ */
+
+import type { CookieOptions } from "../router/middleware-types.js";
+import { getRequestContext, _getRequestContext } from "./request-context.js";
+import {
+  isInsideCacheScope,
+  getCurrentLoaderBodyId,
+  isInsideHandlerInvokedLoaderBody,
+} from "./context.js";
+import { INSIDE_CACHE_EXEC } from "../cache/taint.js";
+
+/**
+ * A single cookie entry returned by get() and getAll().
+ */
+export interface Cookie {
+  name: string;
+  value: string;
+}
+
+/**
+ * Request-scoped cookie store.
+ *
+ * Reads see the effective merged view (original request + same-request mutations).
+ * Writes append Set-Cookie headers to the shared response stub.
+ */
+export interface CookieStore {
+  /** Get a single cookie by name. Returns undefined if not set or deleted. */
+  get(name: string): Cookie | undefined;
+
+  /** Get all effective cookies, or all cookies with a given name. */
+  getAll(name?: string): Cookie[];
+
+  /** Check whether a cookie exists in the effective view. */
+  has(name: string): boolean;
+
+  /** Set a cookie (appends Set-Cookie to the response stub). */
+  set(name: string, value: string, options?: CookieOptions): void;
+
+  /** Delete a cookie (appends Set-Cookie with maxAge=0 to the response stub). */
+  delete(name: string, options?: Pick<CookieOptions, "domain" | "path">): void;
+}
+
+/**
+ * Get the request-scoped cookie store.
+ *
+ * Must be called inside a request context (middleware, handler, loader, action).
+ * Throws if called outside request scope.
+ *
+ * @example
+ * ```typescript
+ * import { cookies } from "@rangojs/router";
+ *
+ * // In a handler, loader, or action:
+ * const session = cookies().get("session")?.value;
+ * cookies().set("session", "new-token", { httpOnly: true });
+ * cookies().delete("session");
+ * ```
+ */
+export function cookies(): CookieStore {
+  const ctx = getRequestContext();
+  assertNotInsideCacheContext(ctx, "cookies");
+  assertNotInsideShellCapture(ctx, "cookies");
+  return createCookieStore(ctx);
+}
+
+/**
+ * Read-only view of HTTP headers.
+ * Exposes only the read methods of the Headers API.
+ */
+export interface ReadonlyHeaders {
+  get(name: string): string | null;
+  has(name: string): boolean;
+  entries(): HeadersIterator<[string, string]>;
+  keys(): HeadersIterator<string>;
+  values(): HeadersIterator<string>;
+  forEach(
+    callback: (value: string, name: string, parent: ReadonlyHeaders) => void,
+  ): void;
+  [Symbol.iterator](): HeadersIterator<[string, string]>;
+}
+
+// Minimal iterator interface (avoids pulling IterableIterator from lib.dom)
+type HeadersIterator<T> = IterableIterator<T>;
+
+/**
+ * Throw if called inside a cache boundary — either a "use cache" function
+ * (`INSIDE_CACHE_EXEC` stamped on ctx by the cache runtime) or a `cache()`
+ * DSL boundary (`isInsideCacheScope()` — the render-store flag set while
+ * resolving a `type: "cache"` route entry).
+ *
+ * Reading request-scoped data (cookies, headers) inside a cached scope
+ * produces per-request values that are NOT reflected in the cache key, so
+ * they would be frozen into the shared cache entry and served to the wrong
+ * users. This is the same hazard for both scopes: a `cache()` boundary caches
+ * everything except loaders (it is the document-level "PPR shell"), so a read
+ * here is baked into the shell exactly like a `"use cache"` return value is
+ * baked into its cache entry.
+ *
+ * `isInsideCacheScope()` returns false inside loaders (loaders always run
+ * fresh on every request, even on a cache hit), so reading cookies()/headers()
+ * from a loader is allowed — loaders are the dynamic "holes" of a cached
+ * document.
+ */
+function assertNotInsideCacheContext(ctx: unknown, fnName: string): void {
+  if (
+    ctx !== null &&
+    ctx !== undefined &&
+    typeof ctx === "object" &&
+    (INSIDE_CACHE_EXEC as symbol) in (ctx as Record<symbol, unknown>)
+  ) {
+    throw new Error(
+      `${fnName}() cannot be called inside a "use cache" function. ` +
+        `Request-scoped data (cookies, headers) varies per request but is not ` +
+        `reflected in the cache key, so cached results would be served to the ` +
+        `wrong users. Extract the value before the cached function and pass it ` +
+        `as an argument:\n\n` +
+        `  const locale = cookies().get("locale")?.value ?? "en";\n` +
+        `  const data = await getCachedData(locale); // locale is now in the cache key`,
+    );
+  }
+  if (isInsideCacheScope()) {
+    throw new Error(
+      `${fnName}() cannot be called inside a cache() boundary. ` +
+        `A cache() scope caches everything except loaders, so request-scoped ` +
+        `data (cookies, headers) read here would be frozen into the shared ` +
+        `cached shell and served to other users. Read it inside a loader ` +
+        `instead — loaders always run fresh on every request, even on a cache hit:\n\n` +
+        `  loader("user", () => getUser(cookies().get("session")?.value));`,
+    );
+  }
+}
+
+/**
+ * Throw if called during the ACTIVE background shell-capture render
+ * (`_shellCaptureRun` true on the derived request context built by
+ * shell-capture.ts). The captured shell prelude is shared across every user
+ * hitting the URL, so a request-scoped read here would bake one user's
+ * cookies/headers into markup served to others — same hazard as the cache
+ * scopes above, at the document tier. DSL segment loaders need no exemption:
+ * the live lane is masked (never executed) during capture, and the bake lane
+ * is exactly what this guard exists for.
+ *
+ * HANDLER-INVOKED loader bodies (`await ctx.use(Loader)` from a handler) are
+ * EXEMPT — the consumption-lane rule: handler consumption yields a BAKED
+ * shared copy in every artifact tier, and the cache-purity guards above
+ * already permit identity reads there (cache()/"use cache" bake the same
+ * reads today). Guarding only the PPR tier made the same code legal under
+ * cache() but capture-refusing under ppr (issue #672 / #674). The trade is
+ * documented: an identity read in a handler-consumed loader bakes the CAPTURE
+ * request's value into the shared shell; client-side consumption (useLoader)
+ * is the live lane.
+ *
+ * Keys off `_shellCaptureRun`, NOT the `_shellCapture` descriptor: the descriptor
+ * is also present during the FOREGROUND render (it means "a capture is wanted"),
+ * and the foreground must read cookies/headers normally to serve the real user.
+ * Only the derived capture context sets `_shellCaptureRun`.
+ *
+ * Applies only to the READ surfaces (cookies(), headers()) whose values
+ * become markup. Response directives (invalidateClientCache(),
+ * keepClientCache()) stay callable: during capture they are header effects on
+ * a discarded response, and on the live HIT path the full pipeline runs so their
+ * headers flow to the client normally.
+ *
+ * The throw makes such a route PPR-ineligible by construction: the capture
+ * render errors, nothing is stored, and every request keeps getting the
+ * normal axis-1 render.
+ */
+function assertNotInsideShellCapture(ctx: unknown, fnName: string): void {
+  if (
+    ctx !== null &&
+    typeof ctx === "object" &&
+    (ctx as { _shellCaptureRun?: unknown })._shellCaptureRun === true
+  ) {
+    if (isInsideHandlerInvokedLoaderBody()) return;
+    // Flag the capture context BEFORE throwing: inside an executing bake-lane
+    // loader this throw is swallowed by wrapLoaderPromise into per-loader error
+    // UI, which would bake silently into the shared shell. The capture checks
+    // the flag after the render and refuses (shell-capture.ts). Also record
+    // WHICH loader body (if any) made the read, so the refusal warning can
+    // name the real source instead of hardcoding a lane — the read may come
+    // from a bake-lane loader OR from handler/render code (issue #672).
+    (ctx as { _shellCaptureGuardTripped?: string })._shellCaptureGuardTripped =
+      fnName;
+    (
+      ctx as { _shellCaptureGuardTrippedLoaderId?: string }
+    )._shellCaptureGuardTrippedLoaderId = getCurrentLoaderBodyId();
+    throw new Error(
+      `${fnName}() cannot be called while capturing a shared shell ` +
+        `(shell-cache middleware). The captured shell is served to every user ` +
+        `of this URL, so request-scoped data read here would leak one user's ` +
+        `${fnName === "cookies" ? "cookies" : "headers"} to others. Read it ` +
+        `inside a loader instead — loaders are never captured and always run ` +
+        `fresh per request:\n\n` +
+        `  loader("user", () => getUser(cookies().get("session")?.value));`,
+    );
+  }
+}
+
+const HEADERS_MUTATION_METHODS = new Set(["set", "append", "delete"]);
+
+/**
+ * Get the original request headers (read-only).
+ *
+ * Must be called inside a request context.
+ * Returns a read-only view of the incoming request's headers.
+ * Mutation methods (set, append, delete) throw at runtime.
+ *
+ * @example
+ * ```typescript
+ * import { headers } from "@rangojs/router";
+ *
+ * const auth = headers().get("authorization");
+ * const contentType = headers().get("content-type");
+ * ```
+ */
+export function headers(): ReadonlyHeaders {
+  const ctx = getRequestContext();
+  assertNotInsideCacheContext(ctx, "headers");
+  assertNotInsideShellCapture(ctx, "headers");
+  return new Proxy(ctx.request.headers, {
+    get(target, prop, receiver) {
+      if (typeof prop === "string" && HEADERS_MUTATION_METHODS.has(prop)) {
+        return () => {
+          throw new Error(
+            `headers().${prop}() is not allowed. headers() returns a read-only view of request headers. ` +
+              `Use ctx.header() to set response headers.`,
+          );
+        };
+      }
+      const value = Reflect.get(target, prop, receiver);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  }) as unknown as ReadonlyHeaders;
+}
+
+/**
+ * Force the calling client's caches to miss from now on, from the server seat:
+ * write a rotated `Set-Cookie` for the rango state. The responding client
+ * applies it on receipt, and its history cache is marked stale by the
+ * jar-divergence observer at its next read. Per-client and lazy — it rotates
+ * only the client that receives this response, not every client.
+ *
+ * Idempotent within a request (one `Set-Cookie`). Inert (a dev warning) when
+ * called outside a request context. Like `cookies()`, it throws inside a
+ * `"use cache"` / `cache()` boundary, but is allowed from a loader (loaders are
+ * the dynamic holes of a cached document).
+ */
+export function invalidateClientCache(): void {
+  const ctx = _getRequestContext();
+  if (!ctx) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        "[rango] invalidateClientCache() was called outside a request context; ignored.",
+      );
+    }
+    return;
+  }
+  assertNotInsideCacheContext(ctx, "invalidateClientCache");
+  ctx._rotateStateCookie();
+}
+
+/**
+ * Suppress a server action's automatic client-cache invalidation: tell the
+ * action bridge this action changed nothing a route renders, so it should leave
+ * the client's state and caches alone (no rotation, no prefetch wipe, no
+ * broadcast, no revalidation refetch). Per-response, not per-action-definition —
+ * only the execution knows whether anything changed.
+ *
+ * Sets an internal response header the bridge reads. Idempotent within a
+ * request. Inert (a dev warning) outside a request context — there is no
+ * automatic invalidation to suppress.
+ */
+export function keepClientCache(): void {
+  const ctx = _getRequestContext();
+  if (!ctx) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        "[rango] keepClientCache() was called outside a request context; ignored.",
+      );
+    }
+    return;
+  }
+  assertNotInsideCacheContext(ctx, "keepClientCache");
+  ctx._setKeepCacheDirective();
+}
+
+/**
+ * Create a CookieStore backed by a RequestContext.
+ * @internal Shared between cookies() shorthand and context methods.
+ */
+function createCookieStore(ctx: {
+  cookie(name: string): string | undefined;
+  cookies(): Record<string, string>;
+  setCookie(name: string, value: string, options?: CookieOptions): void;
+  deleteCookie(
+    name: string,
+    options?: Pick<CookieOptions, "domain" | "path">,
+  ): void;
+}): CookieStore {
+  return {
+    get(name: string): Cookie | undefined {
+      const value = ctx.cookie(name);
+      return value !== undefined ? { name, value } : undefined;
+    },
+
+    getAll(name?: string): Cookie[] {
+      const all = ctx.cookies();
+      if (name !== undefined) {
+        const value = all[name];
+        return value !== undefined ? [{ name, value }] : [];
+      }
+      return Object.entries(all).map(([n, v]) => ({ name: n, value: v }));
+    },
+
+    has(name: string): boolean {
+      return ctx.cookie(name) !== undefined;
+    },
+
+    set(name: string, value: string, options?: CookieOptions): void {
+      ctx.setCookie(name, value, options);
+    },
+
+    delete(
+      name: string,
+      options?: Pick<CookieOptions, "domain" | "path">,
+    ): void {
+      ctx.deleteCookie(name, options);
+    },
+  };
+}

package/src/server/fetchable-loader-store.ts

@@ -12,21 +12,26 @@
 import type { LoaderFn } from "../types.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 
-const fetchableLoaderRegistry = new Map<
-  string,
-  { fn: LoaderFn<any, any, any>; middleware: MiddlewareFn[] }
->();
+export interface LoaderRegistryEntry {
+  fn: LoaderFn<any, any, any>;
+  middleware: MiddlewareFn[];
+  /** Whether this loader is fetchable via the _rsc_loader endpoint. */
+  fetchable: boolean;
+}
+
+const fetchableLoaderRegistry = new Map<string, LoaderRegistryEntry>();
 
 export function registerFetchableLoader(
   id: string,
   fn: LoaderFn<any, any, any>,
   middleware: MiddlewareFn[],
+  fetchable: boolean,
 ): void {
-  fetchableLoaderRegistry.set(id, { fn, middleware });
+  fetchableLoaderRegistry.set(id, { fn, middleware, fetchable });
 }
 
 export function getFetchableLoader(
   id: string,
-): { fn: LoaderFn<any, any, any>; middleware: MiddlewareFn[] } | undefined {
+): LoaderRegistryEntry | undefined {
   return fetchableLoaderRegistry.get(id);
 }

package/src/server/handle-store.ts

@@ -14,9 +14,37 @@
 export type HandleData = Record<string, Record<string, unknown[]>>;
 
 /**
- * Deep clone handle data to create a snapshot.
- * @internal
+ * Build a HandleData snapshot from a HandleStore using segment ordering.
+ * Reads data directly from the store for each segment in order.
  */
+export function buildHandleSnapshot(
+  handleStore: HandleStore,
+  segmentOrder: string[],
+): HandleData {
+  const data: HandleData = {};
+  for (const segmentId of segmentOrder) {
+    const segData = handleStore.getDataForSegment(segmentId);
+    for (const handleName in segData) {
+      if (!data[handleName]) data[handleName] = {};
+      data[handleName][segmentId] = segData[handleName];
+    }
+  }
+  return data;
+}
+
+function createLateHandlePushError(
+  handleName: string,
+  segmentId: string,
+): Error {
+  const error = new Error(
+    `Handle "${handleName}" for segment "${segmentId}" was pushed after handle collection completed. ` +
+      `This usually means an async JSX subtree suspended and later tried to push a handle during streaming. ` +
+      `Push handles from the route/layout handler or during the initial synchronous JSX render instead.`,
+  );
+  error.name = "LateHandlePushError";
+  return error;
+}
+
 function cloneHandleData(data: HandleData): HandleData {
   const clone: HandleData = {};
   for (const handleName in data) {
@@ -44,11 +72,26 @@ export interface HandleStore {
   track<T>(promise: Promise<T>): Promise<T>;
 
   /**
-   * Promise that resolves when all tracked handlers have settled.
-   * Does not reject - uses Promise.allSettled internally.
+   * Signal that no more track() calls will be made.
+   * settled will not resolve until seal() is called AND all tracked
+   * promises have settled. Calling stream() or getData() auto-seals.
+   */
+  seal(): void;
+
+  /**
+   * Promise that resolves when the store is sealed AND all tracked
+   * handlers have settled.
    */
   readonly settled: Promise<void>;
 
+  /**
+   * Optional error callback for late streaming-handle failures.
+   * Called when push() throws LateHandlePushError (handle pushed after
+   * stream completion). Allows the router to surface these errors
+   * to onError and telemetry.
+   */
+  onError?: (error: Error) => void;
+
   /**
    * Push handle data for a specific handle and segment.
    * Multiple pushes to the same handle/segment accumulate in an array.
@@ -58,9 +101,7 @@ export interface HandleStore {
 
   /**
    * Get all collected handle data after all handlers have settled.
-   * Returns a promise that waits for `settled`, then returns the data.
-   * The data may contain unresolved promises which RSC will stream.
-   * @deprecated Use stream() for progressive updates
+   * Waits for `settled`, then returns the finalized data.
    */
   getData(): Promise<HandleData>;
 
@@ -81,7 +122,10 @@ export interface HandleStore {
    * Replay cached handle data back into the store (for cache hits).
    * Used to restore handle data when serving cached segments.
    */
-  replaySegmentData(segmentId: string, segmentHandles: Record<string, unknown[]>): void;
+  replaySegmentData(
+    segmentId: string,
+    segmentHandles: Record<string, unknown[]>,
+  ): void;
 }
 
 /**
@@ -105,11 +149,35 @@ export interface HandleStore {
  * ```
  */
 export function createHandleStore(): HandleStore {
-  const pending: Promise<unknown>[] = [];
   const data: HandleData = {};
 
-  // Queue for pending emissions and resolver for waiting consumer
-  let pendingEmissions: HandleData[] = [];
+  // Settlement barrier: resolved only when sealed AND inflight === 0.
+  // seal() signals "no more track() calls". Each track() increments
+  // inflightCount, each promise.finally() decrements. settled resolves
+  // once both conditions are met — even if tracks are added while
+  // earlier ones are still in flight.
+  let sealed = false;
+  let inflightCount = 0;
+  let drainWaiters: (() => void)[] = [];
+
+  function notifyDrain() {
+    if (sealed && inflightCount === 0 && drainWaiters.length > 0) {
+      const waiters = drainWaiters;
+      drainWaiters = [];
+      for (const resolve of waiters) resolve();
+    }
+  }
+
+  function sealInternal() {
+    if (sealed) return;
+    sealed = true;
+    notifyDrain();
+  }
+
+  // Dirty flag for pending emissions and resolver for waiting consumer.
+  // stream() only ever yields the latest full state, so we track a single
+  // dirty bit and clone `data` once at yield time instead of per push.
+  let hasPendingEmission = false;
   let emissionResolver: (() => void) | null = null;
   let completed = false;
 
@@ -124,7 +192,7 @@ export function createHandleStore(): HandleStore {
 
   // Wait for the next emission or completion
   function waitForEmission(): Promise<void> {
-    if (pendingEmissions.length > 0 || completed) {
+    if (hasPendingEmission || completed) {
       return Promise.resolve();
     }
     return new Promise((resolve) => {
@@ -134,18 +202,36 @@ export function createHandleStore(): HandleStore {
 
   return {
     track<T>(promise: Promise<T>): Promise<T> {
-      pending.push(promise);
+      inflightCount++;
+      // Use .then() instead of .finally() to avoid creating an unhandled rejection
+      // branch when the promise rejects. .finally() re-throws on a new branch that
+      // can crash the process if not caught.
+      const onSettle = () => {
+        inflightCount--;
+        notifyDrain();
+      };
+      promise.then(onSettle, onSettle);
       return promise;
     },
 
+    seal() {
+      sealInternal();
+    },
+
     get settled(): Promise<void> {
-      if (pending.length === 0) {
-        return Promise.resolve();
-      }
-      return Promise.allSettled(pending).then(() => {});
+      if (sealed && inflightCount === 0) return Promise.resolve();
+      return new Promise<void>((resolve) => {
+        drainWaiters.push(resolve);
+      });
     },
 
     push(handleName: string, segmentId: string, value: unknown): void {
+      if (completed) {
+        const error = createLateHandlePushError(handleName, segmentId);
+        if (this.onError) this.onError(error);
+        throw error;
+      }
+
       if (!data[handleName]) {
         data[handleName] = {};
       }
@@ -154,49 +240,42 @@ export function createHandleStore(): HandleStore {
       }
       data[handleName][segmentId].push(value);
 
-      // Queue a snapshot for emission
-      pendingEmissions.push(cloneHandleData(data));
+      // Mark dirty; the actual snapshot is cloned once at yield time.
+      hasPendingEmission = true;
       signalEmission();
     },
 
     getData(): Promise<HandleData> {
-      return this.settled.then(() => data);
+      sealInternal();
+      return this.settled.then(() => cloneHandleData(data));
     },
 
     async *stream(): AsyncGenerator<HandleData, void, unknown> {
-      // Set up completion handler
+      sealInternal();
+
       this.settled.then(() => {
         completed = true;
         signalEmission();
       });
 
-      // Initial small delay to batch rapid synchronous pushes
-      // This allows multiple handles pushing in quick succession to be batched
+      // Batch rapid synchronous pushes with initial delay
       await new Promise((resolve) => setTimeout(resolve, 0));
 
-      // If we already have data, yield the accumulated state
       if (Object.keys(data).length > 0) {
-        // Clear pending emissions since we're yielding current state
-        pendingEmissions = [];
+        hasPendingEmission = false;
         yield cloneHandleData(data);
       }
 
-      // Continue streaming on each push
       while (!completed) {
         await waitForEmission();
 
-        // Yield all pending emissions (yield latest only)
-        if (pendingEmissions.length > 0) {
-          // Skip intermediate states, yield the latest
-          const latest = pendingEmissions[pendingEmissions.length - 1];
-          pendingEmissions = [];
-          yield latest;
+        if (hasPendingEmission) {
+          hasPendingEmission = false;
+          yield cloneHandleData(data);
         }
       }
 
-      // Final yield only if there are pending emissions that weren't yielded
-      // (handles that pushed after our last yield but before completion)
-      if (pendingEmissions.length > 0) {
+      if (hasPendingEmission) {
         yield cloneHandleData(data);
       }
     },
@@ -211,18 +290,20 @@ export function createHandleStore(): HandleStore {
       return result;
     },
 
-    replaySegmentData(segmentId: string, segmentHandles: Record<string, unknown[]>): void {
+    replaySegmentData(
+      segmentId: string,
+      segmentHandles: Record<string, unknown[]>,
+    ): void {
       for (const handleName in segmentHandles) {
         if (!data[handleName]) {
           data[handleName] = {};
         }
-        // Replace with replayed data (not append) to avoid handle bleeding between routes.
-        // When a cached segment is restored, its handles should replace any existing data
-        // for that segment, not accumulate on top of data from a different route.
+        // Replace (not append) to avoid handle bleeding between routes.
+        // Cached segment restoration should replace existing data for that
+        // segment, not accumulate on top of data from a different route.
         data[handleName][segmentId] = [...segmentHandles[handleName]];
       }
-      // Trigger emission for streaming
-      pendingEmissions.push(cloneHandleData(data));
+      hasPendingEmission = true;
       signalEmission();
     },
   };