@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/src/router/segment-resolution/helpers.ts

@@ -0,0 +1,263 @@
+/**
+ * Shared Helpers for Segment Resolution
+ *
+ * Common utilities used by both fresh and revalidation resolution paths:
+ * - Handler result processing (Response vs ReactNode)
+ * - Static handler interception (build-time pre-rendered components)
+ * - Layout handler resolution with static fallback
+ * - Error boundary segment creation
+ */
+
+import type { ReactNode } from "react";
+import { DataNotFoundError } from "../../errors";
+import {
+  createErrorInfo,
+  createErrorSegment,
+  createNotFoundInfo,
+  createNotFoundSegment,
+} from "../error-handling.js";
+import { getRequestContext } from "../../server/request-context.js";
+import { DefaultErrorFallback } from "../../default-error-boundary.js";
+import type { EntryData } from "../../server/context";
+import type { ResolvedSegment, ErrorInfo, HandlerContext } from "../../types";
+import type { SegmentResolutionDeps } from "../types.js";
+import { debugLog } from "../logging.js";
+import { tryStaticLookup } from "./static-store.js";
+import type { TelemetrySink } from "../telemetry.js";
+import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
+
+// ---------------------------------------------------------------------------
+// Handler result processing
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle Response returns from handlers.
+ * When a handler returns a Response (e.g., redirect), throw it to trigger
+ * the short-circuit mechanism. Otherwise return the ReactNode.
+ */
+export function handleHandlerResult(
+  result: ReactNode | Response | Promise<ReactNode> | Promise<Response>,
+): ReactNode {
+  if (result instanceof Response) {
+    throw result;
+  }
+  if (result instanceof Promise) {
+    return result.then((resolved) => {
+      if (resolved instanceof Response) {
+        throw resolved;
+      }
+      return resolved;
+    }) as ReactNode;
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Static handler interception
+// ---------------------------------------------------------------------------
+
+/**
+ * Try to resolve a component from the build-time static store.
+ * Returns undefined synchronously when the entry is not a static prerender,
+ * avoiding unnecessary promise wrapping on the hot path.
+ */
+export function tryStaticHandler(
+  entry: EntryData,
+  segmentId: string,
+): Promise<ReactNode | undefined> | undefined {
+  const entryAny = entry as any;
+  if (entryAny.isStaticPrerender && entryAny.staticHandlerId) {
+    return tryStaticLookup(entryAny.staticHandlerId, segmentId);
+  }
+  return undefined;
+}
+
+/**
+ * Try to resolve a parallel slot component from the build-time static store.
+ * Returns undefined synchronously when no static handler ID exists for the slot.
+ */
+export function tryStaticSlot(
+  parallelEntry: EntryData,
+  slot: string,
+  segmentId: string,
+): Promise<ReactNode | undefined> | undefined {
+  const slotStaticId = (parallelEntry as any).staticHandlerIds?.[slot];
+  if (slotStaticId) {
+    return tryStaticLookup(slotStaticId, segmentId);
+  }
+  return undefined;
+}
+
+/**
+ * Resolve a layout or cache entry's handler component.
+ * Checks build-time static store first, then invokes the handler.
+ */
+export async function resolveLayoutComponent<TEnv>(
+  entry: EntryData,
+  context: HandlerContext<any, TEnv>,
+): Promise<ReactNode> {
+  const component = await tryStaticHandler(entry, entry.shortCode);
+  if (component !== undefined) return component;
+  return typeof entry.handler === "function"
+    ? handleHandlerResult(await entry.handler(context))
+    : (entry.handler as ReactNode);
+}
+
+// ---------------------------------------------------------------------------
+// Error boundary segment creation
+// ---------------------------------------------------------------------------
+
+/**
+ * Context for error reporting in segment resolution.
+ * When provided, callOnError is invoked with this context.
+ */
+export interface ErrorReportContext {
+  request?: Request;
+  url?: URL;
+  routeKey?: string;
+  env?: any;
+  isPartial?: boolean;
+  requestStartTime?: number;
+  telemetry?: TelemetrySink;
+}
+
+/**
+ * Handle a caught error during segment resolution by creating an
+ * error or not-found segment with the nearest boundary.
+ *
+ * Called by resolveWithErrorBoundary to produce error/notFound segments.
+ */
+export function catchSegmentError<TEnv>(
+  error: unknown,
+  entry: EntryData,
+  params: Record<string, string>,
+  deps: SegmentResolutionDeps<TEnv>,
+  report?: ErrorReportContext,
+  pathname?: string,
+): ResolvedSegment {
+  const reportError = (
+    handledByBoundary: boolean,
+    metadata?: Record<string, unknown>,
+  ) => {
+    if (!report) return;
+    deps.callOnError(error, "handler", {
+      request: report.request as Request,
+      url: report.url,
+      routeKey: report.routeKey,
+      params,
+      segmentId: entry.shortCode,
+      segmentType: entry.type as any,
+      env: report.env,
+      isPartial: report.isPartial,
+      handledByBoundary,
+      metadata,
+      requestStartTime: report.requestStartTime,
+    });
+    if (report.telemetry) {
+      const errorObj =
+        error instanceof Error ? error : new Error(String(error));
+      safeEmit(resolveSink(report.telemetry), {
+        type: "handler.error",
+        timestamp: performance.now(),
+        requestId: report.request ? getRequestId(report.request) : undefined,
+        segmentId: entry.shortCode,
+        segmentType: entry.type,
+        error: errorObj,
+        handledByBoundary,
+        pathname,
+        routeKey: report.routeKey,
+        params,
+      });
+    }
+  };
+
+  const setResponseStatus = (status: number) => {
+    const reqCtx = getRequestContext();
+    if (reqCtx) {
+      reqCtx.setStatus(status);
+    }
+  };
+
+  if (error instanceof DataNotFoundError) {
+    const notFoundFallback = deps.findNearestNotFoundBoundary(entry);
+
+    if (notFoundFallback) {
+      const notFoundInfo = createNotFoundInfo(
+        error,
+        entry.shortCode,
+        entry.type,
+        pathname,
+      );
+
+      reportError(true, {
+        notFound: true,
+        message: notFoundInfo.message,
+      });
+
+      debugLog("segment", "notFound boundary handled error", {
+        segmentId: entry.shortCode,
+        message: notFoundInfo.message,
+      });
+
+      setResponseStatus(404);
+
+      return createNotFoundSegment(
+        notFoundInfo,
+        notFoundFallback,
+        entry,
+        params,
+      );
+    }
+  }
+
+  const fallback = deps.findNearestErrorBoundary(entry);
+  const segmentType: ErrorInfo["segmentType"] = entry.type;
+  const errorInfo = createErrorInfo(error, entry.shortCode, segmentType);
+  const effectiveFallback = fallback ?? DefaultErrorFallback;
+
+  reportError(!!effectiveFallback);
+
+  debugLog("segment", "error boundary handled error", {
+    segmentId: entry.shortCode,
+    boundary: fallback ? "custom" : "default",
+    message: errorInfo.message,
+  });
+
+  setResponseStatus(500);
+
+  return createErrorSegment(errorInfo, effectiveFallback, entry, params);
+}
+
+/**
+ * Generic error boundary wrapper for segment resolution.
+ * Catches non-Response errors and produces an error/notFound segment
+ * via catchSegmentError. Response throws (e.g. redirects) are re-thrown.
+ *
+ * The caller provides a `wrapError` callback to shape the error segment
+ * into the expected return type (e.g. ResolvedSegment[] for the fresh
+ * path, or SegmentRevalidationResult for the revalidation path).
+ */
+export async function resolveWithErrorBoundary<TEnv, TResult>(
+  entry: EntryData,
+  params: Record<string, string>,
+  resolveFn: () => Promise<TResult>,
+  wrapError: (segment: ResolvedSegment) => TResult,
+  deps: SegmentResolutionDeps<TEnv>,
+  report?: ErrorReportContext,
+  pathname?: string,
+): Promise<TResult> {
+  try {
+    return await resolveFn();
+  } catch (error) {
+    if (error instanceof Response) throw error;
+    const segment = catchSegmentError(
+      error,
+      entry,
+      params,
+      deps,
+      report,
+      pathname,
+    );
+    return wrapError(segment);
+  }
+}

package/src/router/segment-resolution/loader-cache.ts

@@ -5,7 +5,13 @@
  * this module wraps the loader execution with cache lookup/store using the
  * getItem()/setItem() methods on SegmentCacheStore.
  *
- * Cache key format: loader:{loaderId}:{pathname}:{sortedParams}
+ * Cache key resolution (3-tier, matching CacheScope.resolveKey):
+ *   1. options.key(requestCtx) — full override
+ *   2. store.keyGenerator(requestCtx, defaultKey) — store-level modification
+ *   3. loader:{loaderId}:{pathname}:{sortedParams} — default
+ *
+ * Values are serialized via RSC Flight (serializeResult/deserializeResult),
+ * supporting ReactNode, Promises, null, and all RSC-serializable types.
  *
  * On hit: returns cached data directly, skips loader execution.
  * On stale hit (SWR): returns stale data, schedules background revalidation.
@@ -14,11 +20,32 @@
 
 import type { LoaderEntry } from "../../server/context.js";
 import type { HandlerContext } from "../../types.js";
-import type { SegmentCacheStore } from "../../cache/types.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import { getRequestContext } from "../../server/request-context.js";
-
-const DEFAULT_TTL_SECONDS = 60;
+import { sortedRouteParams } from "../../cache/cache-key-utils.js";
+import {
+  resolveTtl,
+  resolveSwrWindow,
+  resolveCacheKey,
+  resolveCacheStore,
+  DEFAULT_ROUTE_TTL,
+} from "../../cache/cache-policy.js";
+import { readThroughItem } from "../../cache/read-through-swr.js";
+// Lazy-loaded to avoid pulling @vitejs/plugin-rsc/rsc into modules that
+// import segment-resolution but never use loader caching.
+let _serializeResult: typeof import("../../cache/segment-codec.js").serializeResult;
+let _deserializeResult: typeof import("../../cache/segment-codec.js").deserializeResult;
+async function getCodec() {
+  if (!_serializeResult) {
+    const mod = await import("../../cache/segment-codec.js");
+    _serializeResult = mod.serializeResult;
+    _deserializeResult = mod.deserializeResult;
+  }
+  return {
+    serializeResult: _serializeResult,
+    deserializeResult: _deserializeResult,
+  };
+}
 
 function debugLoaderCacheLog(message: string): void {
   if (INTERNAL_RANGO_DEBUG) {
@@ -26,55 +53,65 @@ function debugLoaderCacheLog(message: string): void {
   }
 }
 
-function getLoaderCacheKey(
+function getDefaultLoaderCacheKey(
   loaderId: string,
   pathname: string,
   params: Record<string, string>,
 ): string {
-  const paramStr = Object.entries(params)
-    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
-    .join("&");
-
+  const paramStr = sortedRouteParams(params);
   const base = paramStr ? `${pathname}:${paramStr}` : pathname;
   return `loader:${loaderId}:${base}`;
 }
 
-function getLoaderStore(loaderEntry: LoaderEntry): SegmentCacheStore | null {
-  const cacheConfig = loaderEntry.cache;
-  if (!cacheConfig || cacheConfig.options === false) return null;
-  const options = cacheConfig.options;
-
-  // Explicit store from cache() options
-  if (options.store) return options.store;
-
-  // App-level store from request context
-  return getRequestContext()?._cacheStore ?? null;
+/**
+ * Resolve cache key using the shared 3-tier priority.
+ */
+async function resolveLoaderKey(
+  loaderEntry: LoaderEntry,
+  store: import("../../cache/types.js").SegmentCacheStore,
+  loaderId: string,
+  pathname: string,
+  params: Record<string, string>,
+): Promise<string> {
+  const options = loaderEntry.cache!.options;
+  const defaultKey = getDefaultLoaderCacheKey(loaderId, pathname, params);
+  if (options === false) return defaultKey;
+  return resolveCacheKey(options.key, store, defaultKey, "LoaderCache");
 }
 
-function getLoaderTtl(
-  loaderEntry: LoaderEntry,
-  store: SegmentCacheStore,
-): number {
-  const cacheConfig = loaderEntry.cache;
-  if (!cacheConfig || cacheConfig.options === false) return DEFAULT_TTL_SECONDS;
-  const options = cacheConfig.options;
+/**
+ * Resolve tags from cache options (static array or function).
+ * Fails open: a thrown tag callback falls back to no tags rather than
+ * aborting the request. Tags are additive metadata (not identity), so
+ * a missing tag does not cause cache collisions.
+ */
+function resolveTags(loaderEntry: LoaderEntry): string[] | undefined {
+  const options = loaderEntry.cache?.options;
+  if (!options || !options.tags) return undefined;
 
-  if (options.ttl !== undefined) return options.ttl;
-  if (store.defaults?.ttl !== undefined) return store.defaults.ttl;
-  return DEFAULT_TTL_SECONDS;
+  if (typeof options.tags === "function") {
+    const requestCtx = getRequestContext();
+    if (!requestCtx) return undefined;
+    try {
+      return options.tags(requestCtx);
+    } catch (error) {
+      console.error(
+        `[LoaderCache] Tags function failed, caching without tags:`,
+        error,
+      );
+      return undefined;
+    }
+  }
+
+  return options.tags;
 }
 
-function getLoaderSwr(
+function getLoaderStore(
   loaderEntry: LoaderEntry,
-  store: SegmentCacheStore,
-): number | undefined {
+): import("../../cache/types.js").SegmentCacheStore | null {
   const cacheConfig = loaderEntry.cache;
-  if (!cacheConfig || cacheConfig.options === false) return undefined;
-  const options = cacheConfig.options;
-
-  if (options.swr !== undefined) return options.swr;
-  return store.defaults?.swr;
+  if (!cacheConfig || cacheConfig.options === false) return null;
+  return resolveCacheStore(cacheConfig.options.store);
 }
 
 /**
@@ -110,72 +147,39 @@ export function resolveLoaderData<TEnv>(
   }
 
   const loaderId = loaderEntry.loader.$$id;
-  const key = getLoaderCacheKey(loaderId, pathname, ctx.params);
-  const ttl = getLoaderTtl(loaderEntry, store);
-  const swr = getLoaderSwr(loaderEntry, store);
+  const ttl = resolveTtl(options.ttl, store.defaults, DEFAULT_ROUTE_TTL);
+  const swrWindow = resolveSwrWindow(options.swr, store.defaults);
+  const swr = swrWindow || undefined;
+  const tags = resolveTags(loaderEntry);
 
   // Wrap ctx.use() so cache HIT primes the handler's memoization map.
   // ctx.use() closes over the match context's loaderPromises (not request context's).
   // By intercepting ctx.use(), we inject cached data into the correct map.
   const originalUse = ctx.use;
   const dataPromise = (async () => {
-    // Cache lookup
-    try {
-      const cached = await store.getItem!(key);
-
-      if (cached) {
-        const data = JSON.parse(cached.value);
-
-        if (!cached.shouldRevalidate) {
-          debugLoaderCacheLog(`[LoaderCache] HIT: ${key}`);
-          return data;
-        }
-
-        // Stale hit — return stale data, revalidate in background
-        debugLoaderCacheLog(`[LoaderCache] STALE: ${key}`);
-        const requestCtx = getRequestContext();
-        const revalidate = async () => {
-          try {
-            const fresh = await originalUse(loaderEntry.loader);
-            const serialized = JSON.stringify(fresh);
-            await store.setItem!(key, serialized, { ttl, swr });
-          } catch {
-            // Background revalidation failed silently
-          }
-        };
-        if (requestCtx?.waitUntil) {
-          requestCtx.waitUntil(revalidate);
-        } else {
-          revalidate();
-        }
-        return data;
-      }
-    } catch {
-      // Cache lookup failed, fall through to fresh execution
-    }
-
-    // Cache miss — execute loader via ctx.use() (which memoizes it)
-    debugLoaderCacheLog(`[LoaderCache] MISS: ${key}`);
-    const data = await originalUse(loaderEntry.loader);
-
-    // Non-blocking cache write
-    const requestCtx = getRequestContext();
-    const cacheWrite = async () => {
-      try {
-        const serialized = JSON.stringify(data);
-        await store.setItem!(key, serialized, { ttl, swr });
-        debugLoaderCacheLog(`[LoaderCache] Cached: ${key}`);
-      } catch {
-        // Cache write failed silently
-      }
-    };
-    if (requestCtx?.waitUntil) {
-      requestCtx.waitUntil(cacheWrite);
-    } else {
-      await cacheWrite();
-    }
-
-    return data;
+    const codec = await getCodec();
+    const key = await resolveLoaderKey(
+      loaderEntry,
+      store,
+      loaderId,
+      pathname,
+      ctx.params,
+    );
+
+    return readThroughItem({
+      getItem: (k) => store.getItem!(k),
+      setItem: (k, v, o) => store.setItem!(k, v, o),
+      key,
+      execute: () => originalUse(loaderEntry.loader),
+      serialize: (d) => codec.serializeResult(d),
+      deserialize: (v) => codec.deserializeResult(v),
+      storeOptions: { ttl, swr, tags },
+      onHit: () => debugLoaderCacheLog(`[LoaderCache] HIT: ${key}`),
+      onStale: () => debugLoaderCacheLog(`[LoaderCache] STALE: ${key}`),
+      onMiss: () => debugLoaderCacheLog(`[LoaderCache] MISS: ${key}`),
+      onCached: () => debugLoaderCacheLog(`[LoaderCache] Cached: ${key}`),
+      host: getRequestContext(),
+    });
   })();
 
   // Temporarily replace ctx.use() so the handler's call returns cached data.