@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.140

package/src/server/live.ts

@@ -0,0 +1,130 @@
+/**
+ * live() — the deterministic PPR hole primitive (docs/design/ppr-shell-resume.md).
+ *
+ * A PPR shell is captured by masking loaders and freezing everything that
+ * settles synchronously or on a microtask into the shared prelude. That freeze
+ * has a sharp edge: a value that is ALREADY resolved — `Promise.resolve(x)`, an
+ * in-memory lookup, a cached read — settles during the capture's quiet window
+ * and gets baked into the shell, served to every user of the URL. That is
+ * usually what you want (deterministic content belongs in the shell), but not
+ * when the value is per-request. `live()` is the escape hatch: it makes its
+ * boundary a deterministic HOLE regardless of how fast the data resolves, so the
+ * capture postpones there and the resumed serve pass streams the fresh value in.
+ *
+ * It is the userland analogue of the loader mask (loader-mask.ts): during the
+ * background shell-capture render `live()` returns a never-settling promise so
+ * the consuming Suspense subtree suspends and React's static prerender postpones
+ * it. Outside capture — the ordinary serve pass, and the client — it is a
+ * passthrough: the thunk runs, or the promise passes through unchanged.
+ *
+ * Two forms:
+ *
+ *   // Thunk (preferred): during capture the fn NEVER runs — no fetch, no cost.
+ *   const price = await live(() => fetchPrice());
+ *
+ *   // Value: the work already fired before live() saw it, so during capture the
+ *   // real promise is discarded and a hole is returned in its place. Use the
+ *   // thunk form unless you already hold the promise.
+ *   const price = await live(pricePromise);
+ *
+ * The consumer story in one line: a hole even when the data is already resolved —
+ *   const x = await live(() => Promise.resolve(value)); // postpones under capture
+ *
+ * @see docs/design/ppr-shell-resume.md ("The live() hole primitive")
+ */
+
+import { _getRequestContext } from "./request-context.js";
+import { isInsideCacheScope } from "./context.js";
+import { INSIDE_CACHE_EXEC } from "../cache/taint.js";
+
+/**
+ * A promise that never settles — the capture-time hole. Same mechanism and
+ * lifecycle as the loader mask (loader-mask.ts createMaskedLoaderPromise): the
+ * consuming Suspense subtree suspends forever, so the static prerender postpones
+ * it as a hole instead of baking a per-request value into the shared shell.
+ * Nothing awaits it to settle — the capture aborts fizz to freeze the prelude
+ * (maxWaitMs in captureShellHTML bounds that), and workerd/GC reclaims the
+ * pending promise when the capture render tree is dropped. Kept never-settling
+ * (not reject-on-abort) deliberately, to stay identical to the loader mask: a
+ * capture-scoped reject signal would buy no capture-behavior difference, since
+ * the abort — not the hole promise — is what ends the render.
+ */
+function captureHole<T>(): Promise<T> {
+  return new Promise<T>(() => {});
+}
+
+/** True only inside the background shell-capture render (shell-capture.ts sets
+ * `_shellCaptureRun` on its derived context). Non-throwing: outside any request
+ * context this is simply false, so live() passes through. */
+function isShellCaptureActive(): boolean {
+  return _getRequestContext()?._shellCaptureRun === true;
+}
+
+/**
+ * Mark a Suspense boundary as a deterministic PPR hole (see the module doc).
+ *
+ * @param fn - Thunk producing the live value. During shell capture it is NOT
+ *   invoked (no side effects, no cost); a never-settling promise is returned so
+ *   the boundary postpones. Outside capture it runs and its result is returned
+ *   as a promise.
+ */
+export function live<T>(fn: () => Promise<T> | T): Promise<T>;
+/**
+ * @param promise - A promise whose work has already fired. During shell capture
+ *   the promise is discarded and a hole is returned in its place (the work still
+ *   ran — prefer the thunk form to avoid that). Outside capture the promise
+ *   passes through unchanged.
+ */
+export function live<T>(promise: Promise<T>): Promise<T>;
+export function live<T>(
+  input: (() => Promise<T> | T) | Promise<T>,
+): Promise<T> {
+  assertNotInsideCacheBoundary();
+  if (isShellCaptureActive()) {
+    return captureHole<T>();
+  }
+  return typeof input === "function"
+    ? Promise.resolve((input as () => Promise<T> | T)())
+    : input;
+}
+
+/**
+ * Throw when live() is called inside a cache boundary — a "use cache" function
+ * (INSIDE_CACHE_EXEC stamped on the request context) or a cache() DSL scope.
+ *
+ * live() only masks during the SHELL capture (ring 4). The inner cache rings
+ * freeze first: a cache()/prerender write deep-settles the promise and stores
+ * its VALUE in the segment cache, and the handler never re-runs on replay — so
+ * a live() there is silently inert, and if the value is per-request it is the
+ * same shared-cache leak cookies()/headers() guard against, defeated by the
+ * very primitive the caller believed made it safe. A "use cache" miss during a
+ * capture render is worse: the fn body runs under the capture flag, live()
+ * returns a never-settling promise, and the cache write wedges awaiting it.
+ * Same guard shape as assertNotInsideCacheContext in cookie-store.ts.
+ */
+function assertNotInsideCacheBoundary(): void {
+  const ctx = _getRequestContext();
+  if (
+    ctx !== null &&
+    ctx !== undefined &&
+    (INSIDE_CACHE_EXEC as symbol) in (ctx as unknown as Record<symbol, unknown>)
+  ) {
+    throw new Error(
+      `live() cannot be called inside a "use cache" function. The cached ` +
+        `function's value is stored and replayed, so nothing inside it can ` +
+        `stay live — and per-request data would be frozen into a shared ` +
+        `cache entry. Read live data in a loader instead (loaders are never ` +
+        `cached), or move the live() call outside the cached function.`,
+    );
+  }
+  if (isInsideCacheScope()) {
+    throw new Error(
+      `live() cannot be called inside a cache() boundary. The segment cache ` +
+        `deep-settles and stores the resolved VALUE at write time, and the ` +
+        `handler never re-runs on a cache hit — so live() cannot keep this ` +
+        `value live, and per-request data would be frozen into the shared ` +
+        `cached segments. Use a loader behind loading() instead: loaders are ` +
+        `the live lane through every cache ring.`,
+    );
+  }
+}

package/src/server/loader-registry.ts

@@ -6,25 +6,15 @@
  */
 
 import type { LoaderFn } from "../types.js";
-import type { MiddlewareFn } from "../router/middleware.js";
-import { getFetchableLoader } from "./fetchable-loader-store.js";
+import {
+  getFetchableLoader,
+  type LoaderRegistryEntry,
+} from "./fetchable-loader-store.js";
 
-interface RegisteredLoader {
-  fn: LoaderFn<any, any, any>;
-  middleware: MiddlewareFn[];
-}
-
-// 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
-const loaderRegistry = new Map<string, RegisteredLoader>();
+// 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;
 
@@ -32,35 +22,11 @@ let lazyLoaderImports: Map<string, LazyLoaderImport> | null = null;
  * Set the lazy loader imports map (called by the loader manifest)
  */
 export function setLoaderImports(
-  imports: Record<string, LazyLoaderImport>
+  imports: Record<string, LazyLoaderImport>,
 ): void {
   lazyLoaderImports = new Map(Object.entries(imports));
 }
 
-/**
- * Register a fetchable loader by $$id
- * Called by createLoader when fetchable option is provided
- */
-export function registerLoader(
-  id: string,
-  fn: LoaderFn<any, any, any>,
-  middleware: MiddlewareFn[] = []
-): void {
-  if (loaderRegistry.has(id)) {
-    // Already registered (can happen during HMR)
-    return;
-  }
-  loaderRegistry.set(id, { fn, middleware });
-}
-
-/**
- * Get a registered loader by $$id (synchronous)
- * Returns undefined if loader is not registered
- */
-export function getLoader(id: string): RegisteredLoader | undefined {
-  return loaderRegistry.get(id);
-}
-
 /**
  * Get a loader by $$id, loading it lazily if needed
  * This is the primary method for the RSC handler to get loaders
@@ -69,81 +35,69 @@ export function getLoader(id: string): RegisteredLoader | undefined {
  * In dev: IDs are "filePath#exportName", resolved via dynamic import
  */
 export async function getLoaderLazy(
-  id: string
-): Promise<RegisteredLoader | 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)
+  id: string,
+): Promise<LoaderRegistryEntry | undefined> {
+  // 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"
+  // The remaining dev fallback (parse the id as "src/path/file.ts#ExportName"
+  // and import it by path) only makes sense in dev, where ids ARE file paths
+  // and the dev loader manifest is intentionally empty. In production ids are
+  // hashed ("<hash>#ExportName") and every resolvable loader is reached above
+  // via the in-memory registry or the lazy import manifest. The hash is not a
+  // path, so a production fall-through would run import("/<hash>") and throw a
+  // misleading "No such module <hash>" 500 instead of reporting the loader as
+  // unregistered. Return undefined in production so a genuinely unknown loader
+  // is a clean 404 "not found in registry" from handleLoaderFetch.
+  if (process.env.NODE_ENV === "production") {
+    return undefined;
+  }
+
   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;
     }
   }
 
   return undefined;
 }
 
-/**
- * Check if a loader is registered by $$id
- */
-export function hasLoader(id: string): boolean {
-  return loaderRegistry.has(id) || getFetchableLoader(id) !== undefined;
-}
-
-/**
- * Get all registered loader IDs (for debugging)
- */
-export function getRegisteredLoaderIds(): string[] {
-  return Array.from(loaderRegistry.keys());
-}
-
 /**
  * Register a loader by its $$id (injected by Vite plugin)
  * This is called during module loading to cache loaders
@@ -155,20 +109,17 @@ export function registerLoaderById(loader: {
   if (!loader.$$id) {
     return;
   }
-  if (loaderRegistry.has(loader.$$id)) {
-    // Already registered (can happen during HMR)
-    return;
-  }
-
-  // For fetchable loaders, fn is stored in the fetchable registry by $$id
   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, middleware: [] });
+    loaderRegistry.set(loader.$$id, {
+      fn: loader.fn,
+      middleware: [],
+      fetchable: false,
+    });
   }
 }