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

package/src/cache/read-through-swr.ts

@@ -0,0 +1,178 @@
+/**
+ * SWR Read-Through Engine
+ *
+ * Generic read-through cache with stale-while-revalidate support
+ * for item-level caching (getItem/setItem).
+ *
+ * Flow:
+ * 1. Lookup cached item by key
+ * 2. Fresh hit → deserialize, return
+ * 3. Stale hit → deserialize, return, revalidate in background
+ * 4. Miss → execute, cache write (blocking when no waitUntil), return
+ */
+
+import type { CacheItemResult, CacheItemOptions } from "./types.js";
+import { runBackground } from "./background-task.js";
+import { reportCacheError } from "./cache-error.js";
+import type { CacheErrorReporter } from "./cache-error.js";
+
+// The host carries both the optional waitUntil (for background scheduling) and
+// the CacheErrorReporter seam (for routing degradation errors through onError).
+// loader-cache.ts passes the request context, which provides both.
+type WaitUntilHost = {
+  waitUntil?: (fn: () => Promise<void>) => void;
+} & CacheErrorReporter;
+
+export interface ReadThroughItemConfig<T> {
+  /** Retrieve a cached item by key */
+  getItem: (key: string) => Promise<CacheItemResult | null>;
+  /** Store a serialized item by key */
+  setItem: (
+    key: string,
+    value: string,
+    options?: CacheItemOptions,
+  ) => Promise<void>;
+  /** Cache key */
+  key: string;
+  /** Execute the underlying function/loader on miss or revalidation */
+  execute: () => Promise<T>;
+  /**
+   * Optional wrapper applied to execute() ONLY on the background
+   * stale-revalidation path (not the foreground miss, where the caller's context
+   * is already established). Used to re-establish the request-context ALS, which
+   * a detached waitUntil task loses on workerd. Defaults to calling execute()
+   * directly.
+   */
+  wrapBackground?: (run: () => Promise<T>) => Promise<T>;
+  /** Serialize result for storage. Return null to skip caching. */
+  serialize: (data: T) => Promise<string | null>;
+  /** Deserialize cached value back to the original type */
+  deserialize: (value: string) => Promise<T>;
+  /** Options passed to setItem on cache write */
+  storeOptions: CacheItemOptions;
+  /** Called on fresh cache hit (before returning data) */
+  onHit?: (cached: CacheItemResult) => void;
+  /** Called on stale cache hit (before scheduling background revalidation) */
+  onStale?: (cached: CacheItemResult) => void;
+  /** Called on cache miss (before executing) */
+  onMiss?: () => void;
+  /** Called after successful cache write */
+  onCached?: () => void;
+  /** Host with optional waitUntil for background tasks */
+  host?: WaitUntilHost | null;
+}
+
+/**
+ * Read-through cache with SWR support for item-level caching.
+ *
+ * On fresh hit: returns deserialized cached data.
+ * On stale hit: returns stale data, schedules background revalidation.
+ * On miss: executes, writes to cache (blocking when no waitUntil), returns.
+ */
+export async function readThroughItem<T>(
+  config: ReadThroughItemConfig<T>,
+): Promise<T> {
+  const {
+    getItem,
+    setItem,
+    key,
+    execute,
+    serialize,
+    deserialize,
+    storeOptions,
+    onHit,
+    onStale,
+    onMiss,
+    onCached,
+    host,
+    wrapBackground,
+  } = config;
+
+  // Cache lookup. An infra read failure (getItem) is reported by the store
+  // itself, so here we just degrade to a miss. A deserialize failure is a
+  // corrupt/truncated stored entry, which this layer owns: report it LOUD as
+  // cache-corrupt, then fall through to a fresh execution (the miss-path write
+  // self-heals the bad entry).
+  let cached: CacheItemResult | null = null;
+  try {
+    cached = await getItem(key);
+  } catch {
+    cached = null;
+  }
+
+  if (cached) {
+    try {
+      const data = await deserialize(cached.value);
+
+      if (!cached.shouldRevalidate) {
+        onHit?.(cached);
+        return data;
+      }
+
+      // Stale hit — return stale data, revalidate in background
+      onStale?.(cached);
+      runBackground(
+        host,
+        async () => {
+          try {
+            // Re-establish the caller's context (request-context ALS) for the
+            // detached background execution; the foreground miss below calls
+            // execute() directly since its context is already established.
+            const fresh = await (wrapBackground
+              ? wrapBackground(execute)
+              : execute());
+            const serialized = await serialize(fresh);
+            if (serialized !== null) {
+              await setItem(key, serialized, storeOptions);
+            }
+          } catch (error) {
+            reportCacheError(
+              error,
+              "stale-revalidation",
+              "[read-through] background revalidation",
+              host ?? undefined,
+            );
+          }
+        },
+        true,
+      );
+      return data;
+    } catch (error) {
+      reportCacheError(
+        error,
+        "cache-corrupt",
+        "[read-through] deserialize stored entry",
+        host ?? undefined,
+      );
+      // fall through to fresh execution
+    }
+  }
+
+  // Cache miss
+  onMiss?.();
+  const data = await execute();
+
+  // Non-blocking cache write (blocks when no waitUntil)
+  await runBackground(
+    host,
+    async () => {
+      try {
+        const serialized = await serialize(data);
+        if (serialized !== null) {
+          await setItem(key, serialized, storeOptions);
+          onCached?.();
+        }
+      } catch (error) {
+        reportCacheError(
+          error,
+          "cache-write",
+          "[read-through] cache write",
+          host ?? undefined,
+        );
+      }
+    },
+    true,
+  );
+
+  return data;
+}

package/src/cache/segment-codec.ts

@@ -0,0 +1,248 @@
+/**
+ * Segment Codec
+ *
+ * RSC serialization/deserialization for cached segments.
+ * Handles the Flight protocol stream <-> string conversion
+ * and the segment-level encode/decode lifecycle.
+ */
+
+/// <reference types="@vitejs/plugin-rsc/types" />
+
+import type { ResolvedSegment } from "../types.js";
+import type { SerializedSegmentData } from "./types.js";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
+import {
+  renderToReadableStream,
+  createTemporaryReferenceSet,
+} from "@vitejs/plugin-rsc/rsc";
+import { createFromReadableStream } from "@vitejs/plugin-rsc/rsc";
+
+/**
+ * Convert a ReadableStream to a string.
+ */
+export async function streamToString(
+  stream: ReadableStream<Uint8Array>,
+): Promise<string> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let result = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    result += decoder.decode(value, { stream: true });
+  }
+
+  result += decoder.decode(); // flush
+  return result;
+}
+
+/**
+ * Convert a string to a ReadableStream.
+ */
+export function stringToStream(str: string): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  const uint8 = encoder.encode(str);
+
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(uint8);
+      controller.close();
+    },
+  });
+}
+
+/**
+ * RSC-serialize a value using React Server Components stream.
+ * Used for serializing loaderData, layout, loading components etc.
+ *
+ * Returns undefined for null/undefined inputs (component fields that are absent).
+ * For contexts where null is a valid result (loader caching, "use cache"),
+ * use serializeResult() instead which preserves null through RSC Flight.
+ */
+export async function rscSerialize(
+  value: unknown,
+): Promise<string | undefined> {
+  if (value === undefined || value === null) return undefined;
+
+  const temporaryReferences = createTemporaryReferenceSet();
+  const stream = renderToReadableStream(value, { temporaryReferences });
+  return streamToString(stream);
+}
+
+/**
+ * RSC-deserialize a value from a stored string.
+ */
+export async function rscDeserialize<T>(
+  encoded: string | undefined,
+): Promise<T | undefined> {
+  if (!encoded) return undefined;
+
+  const temporaryReferences = createTemporaryReferenceSet();
+  const stream = stringToStream(encoded);
+  return createFromReadableStream<T>(stream, { temporaryReferences });
+}
+
+/**
+ * RSC-serialize any value including null.
+ * Unlike rscSerialize(), this does NOT skip null — it serializes it through
+ * RSC Flight so that a loader returning null produces a valid cached entry
+ * rather than a permanent cache miss.
+ *
+ * Returns null only on serialization failure.
+ */
+export async function serializeResult(value: unknown): Promise<string | null> {
+  try {
+    const temporaryReferences = createTemporaryReferenceSet();
+    const stream = renderToReadableStream(value, { temporaryReferences });
+    return await streamToString(stream);
+  } catch (error) {
+    // Returning null silently turns a non-serializable cache value into a
+    // permanent miss with no trace. Surface it on the internal debug channel so
+    // a failed serialize is diagnosable on wrangler tail, but keep returning
+    // null so the caller falls through to an uncached render rather than throws.
+    if (INTERNAL_RANGO_DEBUG) {
+      console.warn("[segment-codec] serializeResult failed:", error);
+    }
+    return null;
+  }
+}
+
+/**
+ * RSC-deserialize a cached result string.
+ * Counterpart to serializeResult() — always receives a non-empty string.
+ */
+export async function deserializeResult<T>(encoded: string): Promise<T> {
+  const temporaryReferences = createTemporaryReferenceSet();
+  const stream = stringToStream(encoded);
+  return createFromReadableStream<T>(stream, { temporaryReferences });
+}
+
+/**
+ * RSC-deserialize a single encoded component string back to a React element.
+ * Used by the static handler runtime to revive pre-rendered components.
+ * Identical to deserializeResult<unknown>.
+ */
+export const deserializeComponent: (encoded: string) => Promise<unknown> =
+  deserializeResult;
+
+/**
+ * Serialize segments for storage.
+ * Each segment's component, layout, loading, and loaderData are RSC-serialized.
+ * Metadata is preserved as-is.
+ */
+export async function serializeSegments(
+  segments: ResolvedSegment[],
+): Promise<SerializedSegmentData[]> {
+  return Promise.all(
+    segments.map(async (segment): Promise<SerializedSegmentData> => {
+      const temporaryReferences = createTemporaryReferenceSet();
+
+      // Await component if it's a Promise (intercepts with loading keep component as Promise)
+      const componentResolved =
+        segment.component instanceof Promise
+          ? await segment.component
+          : segment.component;
+
+      // Serialize the component to RSC stream
+      const stream = renderToReadableStream(componentResolved, {
+        temporaryReferences,
+      });
+
+      // RSC-serialize loading: "null" string distinguishes explicit null from undefined
+      const encodedLoading =
+        segment.loading !== undefined
+          ? segment.loading === null
+            ? "null"
+            : await rscSerialize(segment.loading)
+          : undefined;
+
+      // Await loaderData / loaderDataPromise if they're Promises
+      const loaderDataResolved =
+        segment.loaderData instanceof Promise
+          ? await segment.loaderData
+          : segment.loaderData;
+      const loaderDataPromiseResolved =
+        segment.loaderDataPromise instanceof Promise
+          ? await segment.loaderDataPromise
+          : segment.loaderDataPromise;
+
+      // Parallelize stream-to-string and RSC serialization of sub-fields
+      const [
+        encoded,
+        encodedLayout,
+        encodedLoaderData,
+        encodedLoaderDataPromise,
+      ] = await Promise.all([
+        streamToString(stream),
+        segment.layout ? rscSerialize(segment.layout) : undefined,
+        rscSerialize(loaderDataResolved),
+        rscSerialize(loaderDataPromiseResolved),
+      ]);
+
+      return {
+        encoded,
+        encodedLayout,
+        encodedLoading,
+        encodedLoaderData,
+        encodedLoaderDataPromise,
+        metadata: {
+          id: segment.id,
+          type: segment.type,
+          namespace: segment.namespace,
+          index: segment.index,
+          params: segment.params,
+          slot: segment.slot,
+          belongsToRoute: segment.belongsToRoute,
+          layoutName: segment.layoutName,
+          parallelName: segment.parallelName,
+          loaderId: segment.loaderId,
+          loaderIds: segment.loaderIds,
+          transition: segment.transition,
+          mountPath: segment.mountPath,
+        },
+      };
+    }),
+  );
+}
+
+/**
+ * Deserialize segments from storage.
+ * Reconstructs ResolvedSegment objects from RSC-serialized data.
+ */
+export async function deserializeSegments(
+  data: SerializedSegmentData[],
+): Promise<ResolvedSegment[]> {
+  return Promise.all(
+    data.map(async (item): Promise<ResolvedSegment> => {
+      const temporaryReferences = createTemporaryReferenceSet();
+
+      // Handle the "null" sentinel for loading before RSC deserialization.
+      // During serialization, loading: null is stored as the string "null" to
+      // distinguish it from undefined.
+      const loadingIsNullSentinel = item.encodedLoading === "null";
+
+      const [component, layout, loaderData, loaderDataPromise, loadingData] =
+        await Promise.all([
+          createFromReadableStream(stringToStream(item.encoded), {
+            temporaryReferences,
+          }),
+          rscDeserialize(item.encodedLayout),
+          rscDeserialize(item.encodedLoaderData),
+          rscDeserialize(item.encodedLoaderDataPromise),
+          loadingIsNullSentinel
+            ? (null as any)
+            : rscDeserialize(item.encodedLoading),
+        ]);
+
+      return {
+        ...item.metadata,
+        component,
+        layout,
+        loading: loadingData,
+        loaderData,
+        loaderDataPromise,
+      } as ResolvedSegment;
+    }),
+  );
+}