@rangojs/router 0.0.0-experimental.2

package/src/rsc/helpers.ts

@@ -0,0 +1,64 @@
+/**
+ * RSC Handler Helpers
+ *
+ * Utility functions for RSC request handling.
+ */
+
+import { getRequestContext } from "../server/request-context.js";
+
+/**
+ * Check if a request body has content to decode
+ */
+export function hasBodyContent(body: FormData | string): boolean {
+  if (body instanceof FormData) {
+    let hasContent = false;
+    body.forEach(() => {
+      hasContent = true;
+    });
+    return hasContent;
+  }
+  return typeof body === "string" && body.length > 0;
+}
+
+/**
+ * Create a Response with headers merged from the request context's stub response.
+ * This ensures headers/cookies set during middleware or handler execution are included.
+ * Also triggers any registered onResponse callbacks.
+ */
+export function createResponseWithMergedHeaders(
+  body: BodyInit | null,
+  init: ResponseInit
+): Response {
+  const ctx = getRequestContext();
+  if (!ctx) {
+    return new Response(body, init);
+  }
+
+  // Merge headers from stub response into the new response
+  const mergedHeaders = new Headers(init.headers);
+  ctx.res.headers.forEach((value, name) => {
+    if (name.toLowerCase() === "set-cookie") {
+      mergedHeaders.append(name, value);
+    } else if (!mergedHeaders.has(name)) {
+      // Only set if not already present in init.headers
+      mergedHeaders.set(name, value);
+    }
+  });
+
+  // Use ctx.res.status if it was set (e.g., 404 for notFound, 500 for error)
+  // Otherwise use the status from init
+  const status = ctx.res.status !== 200 ? ctx.res.status : init.status;
+
+  let response = new Response(body, {
+    ...init,
+    status,
+    headers: mergedHeaders,
+  });
+
+  // Run onResponse callbacks - each can inspect/modify the response
+  for (const callback of ctx._onResponseCallbacks) {
+    response = callback(response) ?? response;
+  }
+
+  return response;
+}

package/src/rsc/index.ts

@@ -0,0 +1,56 @@
+/**
+ * RSC Router - RSC Handler Entry Point
+ *
+ * This module provides the RSC request handler for server-side rendering,
+ * server actions, loader fetching, and progressive enhancement.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { createRSCHandler } from "rsc-router/rsc";
+ * import { router } from "./router.js";
+ *
+ * export default createRSCHandler({ router });
+ * ```
+ */
+
+// Re-export handler
+export { createRSCHandler } from "./handler.js";
+
+// Re-export types
+export type {
+  RscPayload,
+  ReactFormState,
+  RSCDependencies,
+  SSRRenderOptions,
+  SSRModule,
+  LoadSSRModule,
+  CreateRSCHandlerOptions,
+  HandlerCacheConfig,
+  NonceProvider,
+} from "./types.js";
+
+// Re-export HandleStore types for consumers who need custom handling
+export {
+  createHandleStore,
+  type HandleStore,
+  type HandleData,
+} from "../server/handle-store.js";
+
+// Re-export request context utilities for server-side access to env/request/params
+export {
+  getRequestContext,
+  requireRequestContext,
+  setRequestContextParams,
+} from "../server/request-context.js";
+
+// Re-export cache store types and implementations
+export type {
+  SegmentCacheStore,
+  CachedEntryData,
+  CachedEntryResult,
+  SegmentCacheProvider,
+  SegmentHandleData,
+} from "../cache/types.js";
+
+export { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
+export { CFCacheStore, type CFCacheStoreOptions } from "../cache/cf/index.js";

package/src/rsc/nonce.ts

@@ -0,0 +1,18 @@
+/**
+ * Nonce generation for Content Security Policy (CSP)
+ */
+
+/**
+ * Generate a cryptographic nonce for CSP.
+ * Returns a 16-byte random value encoded as base64.
+ */
+export function generateNonce(): string {
+  const array = new Uint8Array(16);
+  crypto.getRandomValues(array);
+  // Convert to base64
+  let binary = "";
+  for (let i = 0; i < array.length; i++) {
+    binary += String.fromCharCode(array[i]);
+  }
+  return btoa(binary);
+}

package/src/rsc/types.ts

@@ -0,0 +1,237 @@
+/**
+ * RSC Handler Types
+ *
+ * Type definitions for the RSC request handler, payload structures,
+ * and SSR integration.
+ */
+
+import type { ResolvedSegment, SlotState } from "../types.js";
+import type { HandleData } from "../server/handle-store.js";
+import type { RSCRouter } from "../router.js";
+import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
+
+/**
+ * RSC payload sent to the client
+ */
+export interface RscPayload {
+  root: React.ReactNode | Promise<React.ReactNode>;
+  metadata?: {
+    pathname: string;
+    segments: ResolvedSegment[];
+    isPartial?: boolean;
+    isError?: boolean;
+    matched?: string[];
+    diff?: string[];
+    slots?: Record<string, SlotState>;
+    /** Root layout component for browser-side re-renders (client component reference) */
+    rootLayout?: React.ComponentType<{ children: React.ReactNode }>;
+    /** Handle data accumulated across route segments (async generator that yields on each push) */
+    handles?: AsyncGenerator<HandleData, void, unknown>;
+    /** RSC version string for cache invalidation */
+    version?: string;
+    /** Theme configuration for FOUC prevention */
+    themeConfig?: ResolvedThemeConfig | null;
+    /** Initial theme from cookie (for SSR hydration) */
+    initialTheme?: Theme;
+    /** Route map for useHref() - maps route names to URL patterns */
+    routeMap?: Record<string, string>;
+    /** Current matched route name (for local name resolution in useHref) */
+    routeName?: string;
+  };
+  returnValue?: { ok: boolean; data: unknown };
+  formState?: unknown;
+}
+
+/**
+ * React form state type for useActionState progressive enhancement
+ */
+export type ReactFormState = unknown;
+
+/**
+ * RSC dependencies from @vitejs/plugin-rsc/rsc
+ */
+export interface RSCDependencies {
+  /**
+   * renderToReadableStream from @vitejs/plugin-rsc/rsc
+   */
+  renderToReadableStream: <T>(
+    payload: T,
+    options?: { temporaryReferences?: unknown }
+  ) => ReadableStream<Uint8Array>;
+
+  /**
+   * decodeReply from @vitejs/plugin-rsc/rsc
+   */
+  decodeReply: (
+    body: FormData | string,
+    options?: { temporaryReferences?: unknown }
+  ) => Promise<unknown[]>;
+
+  /**
+   * createTemporaryReferenceSet from @vitejs/plugin-rsc/rsc
+   */
+  createTemporaryReferenceSet: () => unknown;
+
+  /**
+   * loadServerAction from @vitejs/plugin-rsc/rsc
+   */
+  loadServerAction: (actionId: string) => Promise<Function>;
+
+  /**
+   * decodeAction from @vitejs/plugin-rsc/rsc
+   * Decodes a FormData into a bound action function (for useActionState forms)
+   */
+  decodeAction: (body: FormData) => Promise<() => Promise<unknown>>;
+
+  /**
+   * decodeFormState from @vitejs/plugin-rsc/rsc
+   * Decodes the action result into a ReactFormState for useActionState progressive enhancement
+   */
+  decodeFormState: (
+    actionResult: unknown,
+    body: FormData
+  ) => Promise<ReactFormState | null>;
+}
+
+/**
+ * Options for SSR HTML rendering
+ */
+export interface SSRRenderOptions {
+  /**
+   * Form state for useActionState progressive enhancement.
+   * This is the result of decodeFormState() and should be passed to
+   * react-dom's renderToReadableStream to enable useActionState to
+   * receive the action result during SSR.
+   */
+  formState?: ReactFormState | null;
+
+  /**
+   * Nonce for Content Security Policy (CSP)
+   */
+  nonce?: string;
+}
+
+/**
+ * SSR module interface for HTML rendering
+ */
+export interface SSRModule {
+  renderHTML: (
+    rscStream: ReadableStream<Uint8Array>,
+    options?: SSRRenderOptions
+  ) => Promise<ReadableStream<Uint8Array>>;
+}
+
+/**
+ * Function to load SSR module dynamically
+ */
+export type LoadSSRModule = () => Promise<SSRModule>;
+
+/**
+ * Cache configuration for handler.
+ * TTL is configured via store.defaults or cache() boundaries.
+ */
+export interface HandlerCacheConfig {
+  /** Cache store implementation */
+  store: import("../cache/types.js").SegmentCacheStore;
+  /** Enable/disable caching (default: true) */
+  enabled?: boolean;
+}
+
+/**
+ * Nonce provider function type.
+ * Can return a nonce string, or true to auto-generate one.
+ */
+export type NonceProvider<TEnv = unknown> = (
+  request: Request,
+  env: TEnv
+) => string | true | Promise<string | true>;
+
+/**
+ * Options for creating an RSC handler
+ */
+export interface CreateRSCHandlerOptions<
+  TEnv = unknown,
+  TRoutes extends Record<string, string> = Record<string, string>,
+> {
+  /**
+   * The RSC router instance
+   */
+  router: RSCRouter<TEnv, TRoutes>;
+
+  /**
+   * RSC dependencies from @vitejs/plugin-rsc/rsc.
+   * Defaults to the exports from @vitejs/plugin-rsc/rsc.
+   */
+  deps?: RSCDependencies;
+
+  /**
+   * Function to load the SSR module for HTML rendering.
+   * Defaults to: () => import.meta.viteRsc.loadModule("ssr", "index")
+   */
+  loadSSRModule?: LoadSSRModule;
+
+  /**
+   * Cache configuration for segment caching.
+   *
+   * Can be a static config object or a function that receives the env
+   * (useful for accessing Cloudflare bindings).
+   *
+   * If not provided, caching is disabled. TTL is configured via store.defaults
+   * or cache() boundaries in the route definition.
+   *
+   * @example Static config
+   * ```typescript
+   * cache: {
+   *   store: new MemorySegmentCacheStore({ defaults: { ttl: 60 } }),
+   * }
+   * ```
+   *
+   * @example Dynamic config with env
+   * ```typescript
+   * cache: (env) => ({
+   *   store: new KVSegmentCacheStore(env.Bindings.MY_CACHE, { defaults: { ttl: 60 } }),
+   * })
+   * ```
+   */
+  cache?: HandlerCacheConfig | ((env: TEnv) => HandlerCacheConfig);
+
+  /**
+   * RSC version string included in metadata.
+   * The browser sends this back on partial requests to detect version mismatches.
+   *
+   * Defaults to the auto-generated VERSION from `rsc-router:version` virtual module.
+   * Only set this if you need a custom versioning strategy.
+   *
+   * @default VERSION from rsc-router:version
+   */
+  version?: string;
+
+  /**
+   * Nonce provider for Content Security Policy (CSP).
+   *
+   * Can be:
+   * - A function that returns a nonce string
+   * - A function that returns `true` to auto-generate a nonce
+   * - Undefined to disable nonce (default)
+   *
+   * The nonce will be applied to inline scripts injected by the RSC payload.
+   * It's also available to middleware via `ctx.get('nonce')`.
+   *
+   * @example Auto-generate nonce
+   * ```tsx
+   * createRSCHandler({
+   *   router,
+   *   nonce: () => true,
+   * });
+   * ```
+   *
+   * @example Custom nonce from request context
+   * ```tsx
+   * createRSCHandler({
+   *   router,
+   *   nonce: (request, env) => env.nonce,
+   * });
+   * ```
+   */
+  nonce?: NonceProvider<TEnv>;
+}