@rangojs/router 0.0.0-experimental.1b930379 → 0.0.0-experimental.1c0bdfad

package/src/server/cookie-store.ts

@@ -8,7 +8,8 @@
  */
 
 import type { CookieOptions } from "../router/middleware-types.js";
-import { getRequestContext } from "./request-context.js";
+import { getRequestContext, _getRequestContext } from "./request-context.js";
+import { isInsideCacheScope } from "./context.js";
 import { INSIDE_CACHE_EXEC } from "../cache/taint.js";
 
 /**
@@ -84,10 +85,23 @@ export interface ReadonlyHeaders {
 type HeadersIterator<T> = IterableIterator<T>;
 
 /**
- * Throw if called inside a "use cache" function.
- * Reading request-scoped data (cookies, headers) inside a cached function
- * produces results that vary per request but the cache key does not include
- * those values, leading to one user's data being served to another.
+ * 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 (
@@ -106,6 +120,16 @@ function assertNotInsideCacheContext(ctx: unknown, fnName: string): void {
         `  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));`,
+    );
+  }
 }
 
 const HEADERS_MUTATION_METHODS = new Set(["set", "append", "delete"]);
@@ -144,6 +168,57 @@ export function headers(): ReadonlyHeaders {
   }) 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.

package/src/server/handle-store.ts

@@ -13,6 +13,25 @@
  */
 export type HandleData = Record<string, Record<string, unknown[]>>;
 
+/**
+ * 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,
@@ -26,10 +45,6 @@ function createLateHandlePushError(
   return error;
 }
 
-/**
- * Deep clone handle data to create a snapshot.
- * @internal
- */
 function cloneHandleData(data: HandleData): HandleData {
   const clone: HandleData = {};
   for (const handleName in data) {
@@ -159,8 +174,10 @@ export function createHandleStore(): HandleStore {
     notifyDrain();
   }
 
-  // Queue for pending emissions and resolver for waiting consumer
-  let pendingEmissions: HandleData[] = [];
+  // 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;
 
@@ -175,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) => {
@@ -186,11 +203,9 @@ export function createHandleStore(): HandleStore {
   return {
     track<T>(promise: Promise<T>): Promise<T> {
       inflightCount++;
-      // Use .then(onSettle, onSettle) instead of .finally() to avoid
-      // creating an unhandled rejection branch when the tracked promise
-      // rejects (e.g. error route handlers). .finally() re-throws the
-      // rejection on a new branch that nobody catches, which can crash
-      // the server process.
+      // 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();
@@ -225,8 +240,8 @@ 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();
     },
 
@@ -236,43 +251,31 @@ export function createHandleStore(): HandleStore {
     },
 
     async *stream(): AsyncGenerator<HandleData, void, unknown> {
-      // Auto-seal: stream() is called after all track() registrations.
       sealInternal();
 
-      // Set up completion handler
       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 = [];
-        const snapshot = cloneHandleData(data);
-        yield snapshot;
+        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);
       }
     },
@@ -295,13 +298,12 @@ export function createHandleStore(): HandleStore {
         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();
     },
   };

package/src/server/loader-registry.ts

@@ -11,17 +11,10 @@ import {
   type LoaderRegistryEntry,
 } from "./fetchable-loader-store.js";
 
-// Server-side cache - maps loader $$id to function and middleware
-// This is a CACHE populated by getLoaderLazy() when loaders are first accessed.
-// The source of truth is fetchableLoaderRegistry in loader.ts, which is populated
-// when createLoader() runs. This cache exists to:
-// 1. Avoid repeated lookups/imports for the same loader
-// 2. Support lazy loading in production (loaders imported on-demand)
-// 3. Provide a stable reference for the RSC handler
+// Cache populated by getLoaderLazy() when loaders are first accessed.
+// Source of truth is fetchableLoaderRegistry in loader.ts (populated on createLoader).
 const loaderRegistry = new Map<string, LoaderRegistryEntry>();
 
-// Lazy import map - set by the loader manifest
-// Maps loader $$id to a function that imports the loader module
 type LazyLoaderImport = () => Promise<{ $$id: string }>;
 let lazyLoaderImports: Map<string, LazyLoaderImport> | null = null;
 
@@ -44,59 +37,49 @@ export function setLoaderImports(
 export async function getLoaderLazy(
   id: string,
 ): Promise<LoaderRegistryEntry | undefined> {
-  // Check if already cached in main registry
-  const existing = loaderRegistry.get(id);
-  if (existing) {
-    return existing;
-  }
-
-  // Check the fetchable loader registry (populated by createLoader)
+  // Check fetchableLoaderRegistry first — it's the source of truth.
+  // createLoader() updates it on HMR, ensuring fresh functions after file changes.
   const fetchable = getFetchableLoader(id);
   if (fetchable) {
-    // Cache in main registry for future requests
     loaderRegistry.set(id, fetchable);
     return fetchable;
   }
 
-  // Try to lazy load from the import map (production mode)
+  const existing = loaderRegistry.get(id);
+  if (existing) {
+    return existing;
+  }
+
   if (lazyLoaderImports && lazyLoaderImports.size > 0) {
     const lazyImport = lazyLoaderImports.get(id);
     if (lazyImport) {
-      try {
-        // Import the loader module - this triggers createLoader which registers fn
-        await lazyImport();
+      // A failed import is a real server breakage (broken transitive import,
+      // syntax error, throw in module top-level code), not a "loader not
+      // registered" case. Rethrow so the caller can return a 500 and route
+      // the failure through onError, instead of collapsing it to a 404.
+      await lazyImport();
 
-        // Now try to get from fetchable registry (createLoader registered it)
-        const registered = getFetchableLoader(id);
-        if (registered) {
-          loaderRegistry.set(id, registered);
-          return registered;
-        }
-      } catch (error) {
-        console.error(`[LoaderRegistry] Failed to load loader "${id}":`, error);
+      const registered = getFetchableLoader(id);
+      if (registered) {
+        loaderRegistry.set(id, registered);
+        return registered;
       }
     }
   }
 
-  // Dev mode fallback: parse the ID and use Vite's dynamic import
-  // ID format in dev: "src/path/to/file.ts#ExportName"
+  // Dev fallback: parse ID (format: "src/path/to/file.ts#ExportName") and import
   const hashIndex = id.indexOf("#");
   if (hashIndex !== -1) {
     const filePath = id.slice(0, hashIndex);
 
-    try {
-      // In dev mode, Vite handles dynamic imports
-      // Just importing the module triggers createLoader which registers the fn
-      await import(/* @vite-ignore */ `/${filePath}`);
+    // Same as the lazy branch: a thrown import is a server error, not a
+    // not-found. Let it propagate to the caller for a 500 + onError.
+    await import(/* @vite-ignore */ `/${filePath}`);
 
-      // Now try to get from fetchable registry
-      const registered = getFetchableLoader(id);
-      if (registered) {
-        loaderRegistry.set(id, registered);
-        return registered;
-      }
-    } catch (error) {
-      console.error(`[LoaderRegistry] Failed to load loader "${id}":`, error);
+    const registered = getFetchableLoader(id);
+    if (registered) {
+      loaderRegistry.set(id, registered);
+      return registered;
     }
   }
 
@@ -114,15 +97,12 @@ export function registerLoaderById(loader: {
   if (!loader.$$id) {
     return;
   }
-  // For fetchable loaders, fn is stored in the fetchable registry by $$id.
-  // Always re-check the fetchable registry so HMR picks up the new function.
   const fetchable = getFetchableLoader(loader.$$id);
   if (fetchable) {
     loaderRegistry.set(loader.$$id, fetchable);
     return;
   }
 
-  // Fall back to using fn from the loader object (non-fetchable loaders)
   if (loader.fn) {
     loaderRegistry.set(loader.$$id, {
       fn: loader.fn,