@rangojs/router 0.0.0-experimental.002d056c

package/src/server/cookie-store.ts

@@ -0,0 +1,190 @@
+/**
+ * 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 } from "./request-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");
+  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 "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.
+ */
+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`,
+    );
+  }
+}
+
+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");
+  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;
+}
+
+/**
+ * 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

@@ -0,0 +1,37 @@
+/**
+ * Fetchable loader store - internal registry for fetchable loader functions.
+ *
+ * Extracted into its own module to avoid circular dependencies between
+ * loader.rsc.ts and request-context.ts. This module has no imports from
+ * either, so both can safely import from here.
+ *
+ * Populated by createLoader() in loader.rsc.ts.
+ * Read by request-context.ts (for ctx.use()) and loader-registry.ts (for GET-based fetching).
+ */
+
+import type { LoaderFn } from "../types.js";
+import type { MiddlewareFn } from "../router/middleware.js";
+
+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, fetchable });
+}
+
+export function getFetchableLoader(
+  id: string,
+): LoaderRegistryEntry | undefined {
+  return fetchableLoaderRegistry.get(id);
+}

package/src/server/handle-store.ts

@@ -0,0 +1,308 @@
+/**
+ * Handle data structure: handleName -> segmentId -> entries[]
+ *
+ * @example
+ * ```ts
+ * {
+ *   "breadcrumbs": {
+ *     "$root.layout": [{ label: "Home", href: "/" }],
+ *     "shop.layout": [{ label: "Shop", href: "/shop" }],
+ *   }
+ * }
+ * ```
+ */
+export type HandleData = Record<string, Record<string, unknown[]>>;
+
+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;
+}
+
+/**
+ * Deep clone handle data to create a snapshot.
+ * @internal
+ */
+function cloneHandleData(data: HandleData): HandleData {
+  const clone: HandleData = {};
+  for (const handleName in data) {
+    clone[handleName] = {};
+    for (const segmentId in data[handleName]) {
+      clone[handleName][segmentId] = [...data[handleName][segmentId]];
+    }
+  }
+  return clone;
+}
+
+/**
+ * HandleStore tracks pending handler promises and stores handle data.
+ *
+ * Combines two responsibilities:
+ * 1. Promise tracking - know when all handlers have resolved
+ * 2. Data storage - collect handle data pushed by handlers
+ * 3. Streaming - emit handle data via async iterator on each push
+ */
+export interface HandleStore {
+  /**
+   * Track a handler promise (non-blocking).
+   * Returns the promise unchanged - just registers it for tracking.
+   */
+  track<T>(promise: Promise<T>): Promise<T>;
+
+  /**
+   * 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.
+   * Each push triggers an emission on the stream.
+   */
+  push(handleName: string, segmentId: string, data: unknown): void;
+
+  /**
+   * Get all collected handle data after all handlers have settled.
+   * Waits for `settled`, then returns the finalized data.
+   */
+  getData(): Promise<HandleData>;
+
+  /**
+   * Get an async iterator that yields handle data on each push.
+   * The iterator completes when all handlers have settled.
+   * Each yield contains the full accumulated state (not just the delta).
+   */
+  stream(): AsyncGenerator<HandleData, void, unknown>;
+
+  /**
+   * Get handle data for a specific segment (for caching).
+   * Returns data in format: { handleName: [values...] }
+   */
+  getDataForSegment(segmentId: string): Record<string, unknown[]>;
+
+  /**
+   * 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;
+}
+
+/**
+ * Create a new HandleStore instance.
+ *
+ * @example
+ * ```ts
+ * const handleStore = createHandleStore();
+ *
+ * // In router - track without awaiting
+ * const component = handleStore.track(entry.handler(context));
+ *
+ * // In handler - push handle data (value, promise, or async callback result)
+ * handleStore.push("breadcrumbs", segmentId, { label: "Home", href: "/" });
+ * handleStore.push("meta", segmentId, fetchMetaAsync()); // promise
+ *
+ * // Stream handle data progressively
+ * for await (const handles of handleStore.stream()) {
+ *   console.log("Handle update:", handles);
+ * }
+ * ```
+ */
+export function createHandleStore(): HandleStore {
+  const data: 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();
+  }
+
+  // Queue for pending emissions and resolver for waiting consumer
+  let pendingEmissions: HandleData[] = [];
+  let emissionResolver: (() => void) | null = null;
+  let completed = false;
+
+  // Signal that a new emission is available
+  function signalEmission() {
+    if (emissionResolver) {
+      const resolver = emissionResolver;
+      emissionResolver = null;
+      resolver();
+    }
+  }
+
+  // Wait for the next emission or completion
+  function waitForEmission(): Promise<void> {
+    if (pendingEmissions.length > 0 || completed) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      emissionResolver = resolve;
+    });
+  }
+
+  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.
+      const onSettle = () => {
+        inflightCount--;
+        notifyDrain();
+      };
+      promise.then(onSettle, onSettle);
+      return promise;
+    },
+
+    seal() {
+      sealInternal();
+    },
+
+    get settled(): Promise<void> {
+      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] = {};
+      }
+      if (!data[handleName][segmentId]) {
+        data[handleName][segmentId] = [];
+      }
+      data[handleName][segmentId].push(value);
+
+      // Queue a snapshot for emission
+      pendingEmissions.push(cloneHandleData(data));
+      signalEmission();
+    },
+
+    getData(): Promise<HandleData> {
+      sealInternal();
+      return this.settled.then(() => cloneHandleData(data));
+    },
+
+    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
+      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;
+      }
+
+      // 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;
+        }
+      }
+
+      // 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) {
+        yield cloneHandleData(data);
+      }
+    },
+
+    getDataForSegment(segmentId: string): Record<string, unknown[]> {
+      const result: Record<string, unknown[]> = {};
+      for (const handleName in data) {
+        if (data[handleName][segmentId]) {
+          result[handleName] = [...data[handleName][segmentId]];
+        }
+      }
+      return result;
+    },
+
+    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.
+        data[handleName][segmentId] = [...segmentHandles[handleName]];
+      }
+      // Trigger emission for streaming
+      pendingEmissions.push(cloneHandleData(data));
+      signalEmission();
+    },
+  };
+}

package/src/server/loader-registry.ts

@@ -0,0 +1,133 @@
+/**
+ * Server-side loader registry for GET-based fetching
+ *
+ * Loaders are loaded lazily via dynamic imports when first requested.
+ * The RSC handler looks up loaders by $$id to execute them.
+ */
+
+import type { LoaderFn } from "../types.js";
+import {
+  getFetchableLoader,
+  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
+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;
+
+/**
+ * Set the lazy loader imports map (called by the loader manifest)
+ */
+export function setLoaderImports(
+  imports: Record<string, LazyLoaderImport>,
+): void {
+  lazyLoaderImports = new Map(Object.entries(imports));
+}
+
+/**
+ * Get a loader by $$id, loading it lazily if needed
+ * This is the primary method for the RSC handler to get loaders
+ *
+ * In production: IDs are hashed, looked up via the lazy import map
+ * In dev: IDs are "filePath#exportName", resolved via dynamic import
+ */
+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)
+  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)
+  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();
+
+        // 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);
+      }
+    }
+  }
+
+  // Dev mode fallback: parse the ID and use Vite's dynamic import
+  // ID format in dev: "src/path/to/file.ts#ExportName"
+  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}`);
+
+      // 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);
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Register a loader by its $$id (injected by Vite plugin)
+ * This is called during module loading to cache loaders
+ */
+export function registerLoaderById(loader: {
+  $$id: string;
+  fn?: LoaderFn<any, any, any>;
+}): void {
+  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,
+      middleware: [],
+      fetchable: false,
+    });
+  }
+}