@rangojs/router 0.0.0-experimental.0f44aca1

package/src/router/segment-resolution/static-store.ts

@@ -0,0 +1,67 @@
+/**
+ * Static Store
+ *
+ * Lazy-initialized static store for production Static handler interception.
+ * Manages the build-time static manifest lookup for pre-rendered components.
+ */
+
+import type { ReactNode } from "react";
+import { _getRequestContext } from "../../server/request-context.js";
+import type { StaticStore } from "../../prerender/store.js";
+
+// Lazy-initialized static store for production Static handler interception.
+// Remains undefined until first check; null means checked but no manifest.
+// When no __STATIC_MANIFEST exists (dev mode), set to null eagerly to avoid
+// the dynamic import() in ensureStaticDeps() which disrupts AsyncLocalStorage
+// in workerd/Cloudflare runtime.
+let _staticStore: StaticStore | null | undefined =
+  typeof globalThis !== "undefined" && globalThis.__STATIC_MANIFEST
+    ? undefined
+    : null;
+let _deserializeComponent: ((encoded: string) => Promise<unknown>) | undefined;
+
+async function ensureStaticDeps(): Promise<void> {
+  if (_staticStore === undefined) {
+    const { createStaticStore } = await import("../../prerender/store.js");
+    _staticStore = createStaticStore();
+  }
+  if (!_deserializeComponent && _staticStore) {
+    const { deserializeComponent } =
+      await import("../../cache/segment-codec.js");
+    _deserializeComponent = deserializeComponent;
+  }
+}
+
+/**
+ * Try to load a pre-rendered Static component from the build-time store.
+ * Returns the deserialized React element, or undefined if not available.
+ * Also replays any handle data captured at build time into the request's HandleStore.
+ *
+ * @param handlerId - The handler's $$id used to look up the static store entry.
+ * @param segmentId - The runtime segment shortCode. Handle data is replayed under
+ *   this key so that useHandle's segmentOrder matching works correctly.
+ */
+export async function tryStaticLookup(
+  handlerId: string,
+  segmentId: string,
+): Promise<ReactNode | undefined> {
+  // Fast path: already checked and no manifest available (dev mode or no Static handlers).
+  // Avoids await which can disrupt AsyncLocalStorage in workerd/Cloudflare runtime.
+  if (_staticStore === null) return undefined;
+  await ensureStaticDeps();
+  if (!_staticStore || !_deserializeComponent) return undefined;
+  const entry = await _staticStore.get(handlerId);
+  if (!entry) return undefined;
+
+  // Replay handle data captured during build-time rendering.
+  // The data was keyed by handlerId at build time; replay under segmentId
+  // so it matches the segment order used by useHandle on the client.
+  if (entry.handles && Object.keys(entry.handles).length > 0) {
+    const handleStore = _getRequestContext()?._handleStore;
+    if (handleStore) {
+      handleStore.replaySegmentData(segmentId, entry.handles);
+    }
+  }
+
+  return _deserializeComponent(entry.encoded) as Promise<ReactNode>;
+}

package/src/router/segment-resolution.ts

@@ -0,0 +1,21 @@
+// Barrel re-export -- see segment-resolution/ for implementations.
+export { handleHandlerResult } from "./segment-resolution/helpers.js";
+export {
+  resolveLoaders,
+  type ResolveSegmentOptions,
+  resolveSegment,
+  resolveOrphanLayout,
+  resolveParallelEntry,
+  resolveAllSegments,
+  resolveLoadersOnly,
+} from "./segment-resolution/fresh.js";
+export {
+  resolveLoadersWithRevalidation,
+  resolveLoadersOnlyWithRevalidation,
+  buildEntryRevalidateMap,
+  resolveParallelSegmentsWithRevalidation,
+  resolveEntryHandlerWithRevalidation,
+  resolveSegmentWithRevalidation,
+  resolveOrphanLayoutWithRevalidation,
+  resolveAllSegmentsWithRevalidation,
+} from "./segment-resolution/revalidation.js";

package/src/router/segment-wrappers.ts

@@ -0,0 +1,289 @@
+import type { EntryData, InterceptEntry } from "../server/context";
+import type {
+  HandlerContext,
+  ResolvedSegment,
+  ShouldRevalidateFn,
+} from "../types";
+import type { SegmentResolutionDeps } from "./types.js";
+
+import {
+  resolveAllSegments as _resolveAllSegments,
+  resolveLoadersOnly as _resolveLoadersOnly,
+  resolveLoadersOnlyWithRevalidation as _resolveLoadersOnlyWithRevalidation,
+  buildEntryRevalidateMap as _buildEntryRevalidateMap,
+  resolveAllSegmentsWithRevalidation as _resolveAllSegmentsWithRevalidation,
+} from "./segment-resolution.js";
+
+import {
+  findInterceptForRoute as _findInterceptForRoute,
+  resolveInterceptEntry as _resolveInterceptEntry,
+  resolveInterceptLoadersOnly as _resolveInterceptLoadersOnly,
+} from "./intercept-resolution.js";
+
+import type { InterceptSelectorContext } from "../server/context";
+
+export interface SegmentWrappers<TEnv = any> {
+  resolveAllSegments: (
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    loaderPromises: Map<string, Promise<any>>,
+    options?: { skipLoaders?: boolean },
+  ) => Promise<ResolvedSegment[]>;
+  resolveLoadersOnly: (
+    entries: EntryData[],
+    context: HandlerContext<any, TEnv>,
+  ) => Promise<ResolvedSegment[]>;
+  resolveLoadersOnlyWithRevalidation: (
+    entries: EntryData[],
+    context: HandlerContext<any, TEnv>,
+    clientSegmentIds: Set<string>,
+    prevParams: Record<string, string>,
+    request: Request,
+    prevUrl: URL,
+    nextUrl: URL,
+    routeKey: string,
+    actionContext?: {
+      actionId?: string;
+      actionUrl?: URL;
+      actionResult?: any;
+      formData?: FormData;
+    },
+    stale?: boolean,
+  ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
+  buildEntryRevalidateMap: (
+    entries: EntryData[],
+  ) => Map<
+    string,
+    { entry: EntryData; revalidate: ShouldRevalidateFn<any, any>[] }
+  >;
+  resolveAllSegmentsWithRevalidation: (
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    clientSegmentSet: Set<string>,
+    prevParams: Record<string, string>,
+    request: Request,
+    prevUrl: URL,
+    nextUrl: URL,
+    loaderPromises: Map<string, Promise<any>>,
+    actionContext:
+      | {
+          actionId?: string;
+          actionUrl?: URL;
+          actionResult?: any;
+          formData?: FormData;
+        }
+      | undefined,
+    interceptResult: { intercept: InterceptEntry; entry: EntryData } | null,
+    localRouteName: string,
+    pathname: string,
+  ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
+  findInterceptForRoute: (
+    targetRouteKey: string,
+    fromEntry: EntryData | null,
+    selectorContext?: InterceptSelectorContext | null,
+    isAction?: boolean,
+  ) => { intercept: InterceptEntry; entry: EntryData } | null;
+  resolveInterceptEntry: (
+    interceptEntry: InterceptEntry,
+    parentEntry: EntryData,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    belongsToRoute?: boolean,
+    revalidationContext?: any,
+  ) => Promise<ResolvedSegment[]>;
+  resolveInterceptLoadersOnly: (
+    interceptEntry: InterceptEntry,
+    parentEntry: EntryData,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    belongsToRoute?: boolean,
+    revalidationContext?: any,
+  ) => Promise<{
+    loaderDataPromise: Promise<any[]> | any[];
+    loaderIds: string[];
+  } | null>;
+}
+
+/**
+ * Create thin wrapper functions that bind segmentDeps to extracted
+ * segment resolution and intercept resolution functions.
+ *
+ * These maintain the same signatures as the original inline functions
+ * so that RouterContext and call sites don't need to change.
+ */
+export function createSegmentWrappers<TEnv = any>(
+  segmentDeps: SegmentResolutionDeps<TEnv>,
+): SegmentWrappers<TEnv> {
+  function resolveAllSegments(
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    loaderPromises: Map<string, Promise<any>>,
+    options?: { skipLoaders?: boolean },
+  ): ReturnType<typeof _resolveAllSegments> {
+    return _resolveAllSegments(
+      entries,
+      routeKey,
+      params,
+      context,
+      loaderPromises,
+      segmentDeps,
+      options,
+    );
+  }
+
+  function resolveLoadersOnly(
+    entries: EntryData[],
+    context: HandlerContext<any, TEnv>,
+  ): ReturnType<typeof _resolveLoadersOnly> {
+    return _resolveLoadersOnly(entries, context, segmentDeps);
+  }
+
+  function resolveLoadersOnlyWithRevalidation(
+    entries: EntryData[],
+    context: HandlerContext<any, TEnv>,
+    clientSegmentIds: Set<string>,
+    prevParams: Record<string, string>,
+    request: Request,
+    prevUrl: URL,
+    nextUrl: URL,
+    routeKey: string,
+    actionContext?: {
+      actionId?: string;
+      actionUrl?: URL;
+      actionResult?: any;
+      formData?: FormData;
+    },
+    stale?: boolean,
+  ): ReturnType<typeof _resolveLoadersOnlyWithRevalidation> {
+    return _resolveLoadersOnlyWithRevalidation(
+      entries,
+      context,
+      clientSegmentIds,
+      prevParams,
+      request,
+      prevUrl,
+      nextUrl,
+      routeKey,
+      segmentDeps,
+      actionContext,
+      stale,
+    );
+  }
+
+  function buildEntryRevalidateMap(
+    entries: EntryData[],
+  ): ReturnType<typeof _buildEntryRevalidateMap> {
+    return _buildEntryRevalidateMap(entries);
+  }
+
+  function resolveAllSegmentsWithRevalidation(
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    clientSegmentSet: Set<string>,
+    prevParams: Record<string, string>,
+    request: Request,
+    prevUrl: URL,
+    nextUrl: URL,
+    loaderPromises: Map<string, Promise<any>>,
+    actionContext:
+      | {
+          actionId?: string;
+          actionUrl?: URL;
+          actionResult?: any;
+          formData?: FormData;
+        }
+      | undefined,
+    interceptResult: { intercept: InterceptEntry; entry: EntryData } | null,
+    localRouteName: string,
+    pathname: string,
+  ): ReturnType<typeof _resolveAllSegmentsWithRevalidation> {
+    return _resolveAllSegmentsWithRevalidation(
+      entries,
+      routeKey,
+      params,
+      context,
+      clientSegmentSet,
+      prevParams,
+      request,
+      prevUrl,
+      nextUrl,
+      loaderPromises,
+      actionContext,
+      interceptResult,
+      localRouteName,
+      pathname,
+      segmentDeps,
+    );
+  }
+
+  function findInterceptForRoute(
+    targetRouteKey: string,
+    fromEntry: EntryData | null,
+    selectorContext: InterceptSelectorContext | null = null,
+    isAction: boolean = false,
+  ): ReturnType<typeof _findInterceptForRoute> {
+    return _findInterceptForRoute(
+      targetRouteKey,
+      fromEntry,
+      selectorContext,
+      isAction,
+    );
+  }
+
+  function resolveInterceptEntry(
+    interceptEntry: InterceptEntry,
+    parentEntry: EntryData,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    belongsToRoute: boolean = true,
+    revalidationContext?: any,
+  ): ReturnType<typeof _resolveInterceptEntry> {
+    return _resolveInterceptEntry(
+      interceptEntry,
+      parentEntry,
+      params,
+      context,
+      belongsToRoute,
+      segmentDeps,
+      revalidationContext,
+    );
+  }
+
+  function resolveInterceptLoadersOnly(
+    interceptEntry: InterceptEntry,
+    parentEntry: EntryData,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    belongsToRoute: boolean = true,
+    revalidationContext: any,
+  ): ReturnType<typeof _resolveInterceptLoadersOnly> {
+    return _resolveInterceptLoadersOnly(
+      interceptEntry,
+      parentEntry,
+      params,
+      context,
+      belongsToRoute,
+      segmentDeps,
+      revalidationContext,
+    );
+  }
+
+  return {
+    resolveAllSegments: resolveAllSegments,
+    resolveLoadersOnly: resolveLoadersOnly,
+    resolveLoadersOnlyWithRevalidation: resolveLoadersOnlyWithRevalidation,
+    buildEntryRevalidateMap: buildEntryRevalidateMap,
+    resolveAllSegmentsWithRevalidation: resolveAllSegmentsWithRevalidation,
+    findInterceptForRoute: findInterceptForRoute,
+    resolveInterceptEntry: resolveInterceptEntry,
+    resolveInterceptLoadersOnly: resolveInterceptLoadersOnly,
+  };
+}

package/src/router/telemetry-otel.ts

@@ -0,0 +1,299 @@
+/**
+ * OpenTelemetry Adapter for Router Telemetry
+ *
+ * Maps internal TelemetrySink events to OTel spans. The core router
+ * remains OTel-agnostic — this adapter bridges the gap by accepting
+ * a standard OTel Tracer and producing spans/events from it.
+ *
+ * Usage:
+ *   import { trace } from "@opentelemetry/api";
+ *   import { createOTelSink } from "@rangojs/router";
+ *
+ *   const router = createRouter({
+ *     telemetry: createOTelSink(trace.getTracer("my-app")),
+ *   });
+ */
+
+import type { TelemetrySink, TelemetryEvent } from "./telemetry.js";
+
+// ---------------------------------------------------------------------------
+// Minimal OTel-compatible types (structurally typed, no import needed)
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal Span interface compatible with @opentelemetry/api Span.
+ * Only the methods used by the adapter are declared.
+ */
+export interface OTelSpan {
+  setAttribute(key: string, value: string | number | boolean): OTelSpan | void;
+  addEvent(
+    name: string,
+    attributes?: Record<string, string | number | boolean>,
+  ): OTelSpan | void;
+  setStatus(status: { code: number; message?: string }): OTelSpan | void;
+  recordException(exception: Error): void;
+  end(): void;
+}
+
+/**
+ * Minimal Tracer interface compatible with @opentelemetry/api Tracer.
+ */
+export interface OTelTracer {
+  startSpan(
+    name: string,
+    options?: {
+      attributes?: Record<string, string | number | boolean>;
+    },
+  ): OTelSpan;
+}
+
+// OTel SpanStatusCode constants (mirrors @opentelemetry/api values)
+const STATUS_OK = 1;
+const STATUS_ERROR = 2;
+
+// ---------------------------------------------------------------------------
+// Span correlation helpers
+// ---------------------------------------------------------------------------
+
+// Build correlation keys using requestId.
+// getRequestId() always returns a value (generated internally when no
+// header is present), so concurrent requests to the same path each get
+// their own correlation key and never mis-correlate.
+
+function requestKey(event: {
+  requestId?: string;
+  pathname: string;
+  transaction: string;
+}): string {
+  return `${event.requestId ?? ""}:${event.pathname}:${event.transaction}`;
+}
+
+function loaderKey(event: {
+  requestId?: string;
+  segmentId: string;
+  loaderName: string;
+  pathname: string;
+}): string {
+  return `${event.requestId ?? ""}:${event.segmentId}:${event.loaderName}:${event.pathname}`;
+}
+
+function pushSpan(
+  map: Map<string, OTelSpan[]>,
+  key: string,
+  span: OTelSpan,
+): void {
+  let stack = map.get(key);
+  if (!stack) {
+    stack = [];
+    map.set(key, stack);
+  }
+  stack.push(span);
+}
+
+function popSpan(
+  map: Map<string, OTelSpan[]>,
+  key: string,
+): OTelSpan | undefined {
+  const stack = map.get(key);
+  if (!stack || stack.length === 0) return undefined;
+  const span = stack.pop()!;
+  if (stack.length === 0) map.delete(key);
+  return span;
+}
+
+// ---------------------------------------------------------------------------
+// Adapter factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a TelemetrySink that maps router lifecycle events to OTel spans.
+ *
+ * Span mapping:
+ *   - request.start / request.end / request.error  → "rango.request" span
+ *   - loader.start / loader.end / loader.error      → "rango.loader" span
+ *   - handler.error                                  → "rango.handler.error" instant span
+ *   - cache.decision                                 → "rango.cache.decision" instant span
+ *   - revalidation.decision                          → "rango.revalidation.decision" instant span
+ *
+ * Attributes use the `rango.*` namespace for router-specific data and
+ * `http.method` / `http.route` for HTTP semantics.
+ */
+export function createOTelSink(tracer: OTelTracer): TelemetrySink {
+  const requestSpans = new Map<string, OTelSpan[]>();
+  const loaderSpans = new Map<string, OTelSpan[]>();
+
+  return {
+    emit(event: TelemetryEvent): void {
+      switch (event.type) {
+        // -----------------------------------------------------------------
+        // Request lifecycle
+        // -----------------------------------------------------------------
+
+        case "request.start": {
+          const span = tracer.startSpan("rango.request", {
+            attributes: {
+              "http.method": event.method,
+              "http.route": event.pathname,
+              "rango.transaction": event.transaction,
+              "rango.is_partial": event.isPartial,
+            },
+          });
+          pushSpan(requestSpans, requestKey(event), span);
+          break;
+        }
+
+        case "request.end": {
+          const span = popSpan(requestSpans, requestKey(event));
+          if (span) {
+            span.setAttribute("rango.duration_ms", event.durationMs);
+            span.setAttribute("rango.segment_count", event.segmentCount);
+            span.setAttribute("rango.cache.hit", event.cacheHit);
+            span.setStatus({ code: STATUS_OK });
+            span.end();
+          }
+          break;
+        }
+
+        case "request.error": {
+          const span = popSpan(requestSpans, requestKey(event));
+          if (span) {
+            span.setAttribute("rango.duration_ms", event.durationMs);
+            span.setAttribute("rango.phase", event.phase);
+            span.recordException(event.error);
+            span.setStatus({
+              code: STATUS_ERROR,
+              message: event.error.message,
+            });
+            span.end();
+          }
+          break;
+        }
+
+        // -----------------------------------------------------------------
+        // Loader lifecycle
+        // -----------------------------------------------------------------
+
+        case "loader.start": {
+          const span = tracer.startSpan("rango.loader", {
+            attributes: {
+              "rango.segment_id": event.segmentId,
+              "rango.loader_name": event.loaderName,
+              "http.route": event.pathname,
+            },
+          });
+          pushSpan(loaderSpans, loaderKey(event), span);
+          break;
+        }
+
+        case "loader.end": {
+          const key = loaderKey(event);
+          const span = popSpan(loaderSpans, key);
+          if (span) {
+            span.setAttribute("rango.duration_ms", event.durationMs);
+            span.setAttribute("rango.loader.ok", event.ok);
+            span.setStatus({ code: event.ok ? STATUS_OK : STATUS_ERROR });
+            span.end();
+          }
+          break;
+        }
+
+        case "loader.error": {
+          const key = loaderKey(event);
+          const span = popSpan(loaderSpans, key);
+          if (span) {
+            span.setAttribute(
+              "rango.handled_by_boundary",
+              event.handledByBoundary,
+            );
+            span.recordException(event.error);
+            span.setStatus({
+              code: STATUS_ERROR,
+              message: event.error.message,
+            });
+            span.end();
+          } else {
+            // No matching start — create a standalone error span
+            const errorSpan = tracer.startSpan("rango.loader", {
+              attributes: {
+                "rango.segment_id": event.segmentId,
+                "rango.loader_name": event.loaderName,
+                "http.route": event.pathname,
+                "rango.handled_by_boundary": event.handledByBoundary,
+              },
+            });
+            errorSpan.recordException(event.error);
+            errorSpan.setStatus({
+              code: STATUS_ERROR,
+              message: event.error.message,
+            });
+            errorSpan.end();
+          }
+          break;
+        }
+
+        // -----------------------------------------------------------------
+        // Handler errors (instant span)
+        // -----------------------------------------------------------------
+
+        case "handler.error": {
+          const attrs: Record<string, string | number | boolean> = {
+            "rango.handled_by_boundary": event.handledByBoundary,
+          };
+          if (event.segmentId) attrs["rango.segment_id"] = event.segmentId;
+          if (event.segmentType)
+            attrs["rango.segment_type"] = event.segmentType;
+          if (event.pathname) attrs["http.route"] = event.pathname;
+          if (event.routeKey) attrs["rango.route_key"] = event.routeKey;
+          if (event.params) {
+            attrs["rango.params"] = JSON.stringify(event.params);
+          }
+
+          const span = tracer.startSpan("rango.handler.error", {
+            attributes: attrs,
+          });
+          span.recordException(event.error);
+          span.setStatus({ code: STATUS_ERROR, message: event.error.message });
+          span.end();
+          break;
+        }
+
+        // -----------------------------------------------------------------
+        // Cache decision (instant span)
+        // -----------------------------------------------------------------
+
+        case "cache.decision": {
+          const attrs: Record<string, string | number | boolean> = {
+            "http.route": event.pathname,
+            "rango.route_key": event.routeKey,
+            "rango.cache.hit": event.hit,
+            "rango.cache.should_revalidate": event.shouldRevalidate,
+          };
+          if (event.source) attrs["rango.cache.source"] = event.source;
+
+          const span = tracer.startSpan("rango.cache.decision", {
+            attributes: attrs,
+          });
+          span.end();
+          break;
+        }
+
+        // -----------------------------------------------------------------
+        // Revalidation decision (instant span)
+        // -----------------------------------------------------------------
+
+        case "revalidation.decision": {
+          const span = tracer.startSpan("rango.revalidation.decision", {
+            attributes: {
+              "rango.segment_id": event.segmentId,
+              "http.route": event.pathname,
+              "rango.route_key": event.routeKey,
+              "rango.revalidate": event.shouldRevalidate,
+            },
+          });
+          span.end();
+          break;
+        }
+      }
+    },
+  };
+}