@rangojs/router 0.0.0-experimental.124 → 0.0.0-experimental.126

package/src/router/router-interfaces.ts

@@ -9,6 +9,7 @@ import type { NonceProvider } from "../rsc/types.js";
 import type { ExecutionContext } from "../server/request-context.js";
 import type { SerializedSegmentData } from "../cache/types.js";
 import type { MiddlewareEntry, MiddlewareFn } from "./middleware.js";
+import type { ExtractParams } from "../types/route-config.js";
 import { RSC_ROUTER_BRAND } from "./router-registry.js";
 import type { RangoOptions, RootLayoutProps } from "./router-options.js";
 import type { DefaultVars } from "../types/global-namespace.js";
@@ -105,9 +106,14 @@ export interface Rango<
    * createRouter({ document: RootLayout })
    *   .use(loggerMiddleware)           // All routes
    *   .use("/api/*", rateLimiter)      // Pattern match
+   *   .use("/users/:id", (ctx) => {})  // ctx.params.id is typed
    *   .routes(urlpatterns)
    * ```
    */
+  use<Pattern extends string>(
+    pattern: Pattern,
+    middleware: MiddlewareFn<TEnv, ExtractParams<Pattern>>,
+  ): Rango<TEnv, TRoutes>;
   use(
     patternOrMiddleware: string | MiddlewareFn<TEnv>,
     middleware?: MiddlewareFn<TEnv>,
@@ -225,6 +231,10 @@ export interface RangoInternal<
   /**
    * Add global middleware that runs on all routes
    */
+  use<Pattern extends string>(
+    pattern: Pattern,
+    middleware: MiddlewareFn<TEnv, ExtractParams<Pattern>>,
+  ): Rango<TEnv, TRoutes>;
   use(
     patternOrMiddleware: string | MiddlewareFn<TEnv>,
     middleware?: MiddlewareFn<TEnv>,

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

@@ -27,59 +27,17 @@ import {
   tryStaticSlot,
   resolveLayoutComponent,
   resolveWithErrorBoundary,
+  warnOnStreamedResponse,
 } from "./helpers.js";
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
-import { resolveSink, safeEmit } from "../telemetry.js";
+import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
 import {
   track,
   RangoContext,
   runInsideLoaderScope,
 } from "../../server/context.js";
 
-// ---------------------------------------------------------------------------
-// Streamed handler telemetry
-// ---------------------------------------------------------------------------
-
-/**
- * Attach a fire-and-forget rejection observer to a streamed handler promise.
- * React catches the actual error via its error boundary; this only emits
- * the handler.error telemetry event.
- */
-function observeStreamedHandler(
-  promise: Promise<ReactNode>,
-  segmentId: string,
-  segmentType: string,
-  pathname?: string,
-  routeKey?: string,
-  params?: Record<string, string>,
-): void {
-  let routerCtx;
-  try {
-    routerCtx = getRouterContext();
-  } catch {
-    return;
-  }
-  if (!routerCtx?.telemetry) return;
-  const sink = resolveSink(routerCtx.telemetry);
-  const reqId = routerCtx.requestId;
-  promise.catch((err: unknown) => {
-    const errorObj = err instanceof Error ? err : new Error(String(err));
-    safeEmit(sink, {
-      type: "handler.error",
-      timestamp: performance.now(),
-      requestId: reqId,
-      segmentId,
-      segmentType,
-      error: errorObj,
-      handledByBoundary: true,
-      pathname,
-      routeKey,
-      params,
-    });
-  });
-}
-
 // ---------------------------------------------------------------------------
 // Fresh path (full match, no revalidation)
 // ---------------------------------------------------------------------------
@@ -133,18 +91,32 @@ export async function resolveLoaders<TEnv>(
 
   // Loading disabled: still start all loaders in parallel, but only emit
   // settled promises so handlers don't stream loading placeholders.
-  const pendingLoaderData = loaderEntries.map((loaderEntry) => {
+  //
+  // Wrap each loader promise with wrapLoaderPromise BEFORE awaiting. The wrapped
+  // promise resolves to a LoaderDataResult and never rejects, routing a failed
+  // loader to its own per-loader error boundary. Awaiting the RAW promises here
+  // instead would (1) propagate a rejection to the segment-level boundary,
+  // collapsing the whole entry and discarding successful sibling data, and
+  // (2) leave the other in-flight raw promises without a .catch, producing
+  // unhandled rejections. Mirrors the loading path and intercept-resolution.
+  const pendingLoaderData = loaderEntries.map((loaderEntry, i) => {
+    const { loader } = loaderEntry;
+    const segmentId = `${shortCode}D${i}.${loader.$$id}`;
     const start = performance.now();
-    const promise = runInsideLoaderScope(() =>
-      resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+    const wrapped = deps.wrapLoaderPromise(
+      runInsideLoaderScope(() =>
+        resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+      ),
+      entry,
+      segmentId,
+      ctx.pathname,
     );
-    return { promise, start, loaderId: loaderEntry.loader.$$id };
+    return { wrapped, start, segmentId, loaderId: loader.$$id };
   });
-  await Promise.all(pendingLoaderData.map((p) => p.promise));
+  await Promise.all(pendingLoaderData.map((p) => p.wrapped));
 
   return loaderEntries.map((loaderEntry, i) => {
     const { loader } = loaderEntry;
-    const segmentId = `${shortCode}D${i}.${loader.$$id}`;
     const pending = pendingLoaderData[i]!;
     if (ms && !ms.metrics.some((m) => m.label === `loader:${loader.$$id}`)) {
       // All loaders ran in parallel via Promise.all — each span covers
@@ -160,19 +132,14 @@ export async function resolveLoaders<TEnv>(
       );
     }
     return {
-      id: segmentId,
+      id: pending.segmentId,
       namespace: entry.id,
       type: "loader" as const,
       index: i,
       component: null,
       params: ctx.params,
       loaderId: loader.$$id,
-      loaderData: deps.wrapLoaderPromise(
-        pending.promise,
-        entry,
-        segmentId,
-        ctx.pathname,
-      ),
+      loaderData: pending.wrapped,
       belongsToRoute,
     };
   });
@@ -297,6 +264,7 @@ export async function resolveSegment<TEnv>(
       if (entry.loading) {
         const result = handleHandlerResult(handler(context));
         if (result instanceof Promise) {
+          warnOnStreamedResponse(result, entry.id);
           result.finally(doneRouteHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
             segmentId: entry.shortCode,

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

@@ -52,6 +52,40 @@ export function handleHandlerResult(
   return result;
 }
 
+/**
+ * Dev-only: warn when a handler on a route that declares loading() resolves or
+ * rejects with a Response (e.g. redirect()).
+ *
+ * On a non-loading route a returned/thrown Response short-circuits to an HTTP
+ * redirect. But when the route declares loading(), the handler result is
+ * streamed (not awaited at the resolution boundary), so the Response surfaces
+ * only during RSC serialization and is rendered into the stream instead of
+ * becoming a 302/308 — a silent failure mode. Issue redirects from middleware,
+ * a loader, or a synchronous handler return instead. Compiled out in production.
+ */
+export function warnOnStreamedResponse(
+  result: Promise<unknown>,
+  entryId: string,
+): void {
+  if (process.env.NODE_ENV === "production") return;
+  // A Response can surface either as a rejection (handleHandlerResult rethrows a
+  // resolved Response) or as a resolved value (the raw parallel-slot handler is
+  // not run through handleHandlerResult). Check both so every streamed path is
+  // covered. Each handler is an independent observer; it does not consume the
+  // rejection for the trackHandler/observeStreamedHandler chains.
+  const check = (value: unknown) => {
+    if (value instanceof Response) {
+      console.warn(
+        `[rango] Handler for "${entryId}" returned a Response (e.g. ` +
+          `redirect()), but it declares loading(): the Response is rendered ` +
+          `into the RSC stream, NOT sent as an HTTP redirect. Issue redirects ` +
+          `from middleware, a loader, or a synchronous handler return.`,
+      );
+    }
+  };
+  result.then(check, check);
+}
+
 // ---------------------------------------------------------------------------
 // Static handler interception
 // ---------------------------------------------------------------------------

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

@@ -8,7 +8,7 @@
  * 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
+ *   3. loader:{loaderId}:{host}{pathname}:{sortedParams} — default
  *
  * Values are serialized via RSC Flight (serializeResult/deserializeResult),
  * supporting ReactNode, Promises, null, and all RSC-serializable types.
@@ -19,7 +19,7 @@
  */
 
 import type { LoaderEntry } from "../../server/context.js";
-import type { HandlerContext } from "../../types.js";
+import type { HandlerContext, InternalHandlerContext } from "../../types.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import { getRequestContext } from "../../server/request-context.js";
 import { sortedRouteParams } from "../../cache/cache-key-utils.js";
@@ -57,12 +57,13 @@ function debugLoaderCacheLog(message: string): void {
 
 function getDefaultLoaderCacheKey(
   loaderId: string,
+  host: string,
   pathname: string,
   params: Record<string, string>,
 ): string {
   const paramStr = sortedRouteParams(params);
   const base = paramStr ? `${pathname}:${paramStr}` : pathname;
-  return `loader:${loaderId}:${base}`;
+  return `loader:${loaderId}:${host}${base}`;
 }
 
 /**
@@ -76,7 +77,13 @@ async function resolveLoaderKey(
   params: Record<string, string>,
 ): Promise<string> {
   const options = loaderEntry.cache!.options;
-  const defaultKey = getDefaultLoaderCacheKey(loaderId, pathname, params);
+  // The host is part of the loader cache identity, matching the route-level
+  // cache (cache-scope getCacheKeyBase: `${host}${pathname}`) and "use cache"
+  // (cache-runtime pushes ctx.url.host). Without it, a multi-tenant host router
+  // serving the same pathname for different hosts would leak one host's cached
+  // loader data to another.
+  const host = getRequestContext()?.url?.host ?? "localhost";
+  const defaultKey = getDefaultLoaderCacheKey(loaderId, host, pathname, params);
   if (options === false) return defaultKey;
   return resolveCacheKey(options.key, store, defaultKey, "LoaderCache");
 }
@@ -139,15 +146,30 @@ export function resolveLoaderData<TEnv>(
   const swrWindow = resolveSwrWindow(options.swr, store.defaults);
   const swr = swrWindow || undefined;
   const tags = resolveTags(loaderEntry);
-  // Loader tags are config-derived, so they are the complete set whether this is
-  // a cache hit or miss; record them every time so a document built from this
-  // loader is tagged for invalidation.
   recordRequestTags(tags);
 
-  // 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;
+  // A handler that later awaits this same loader via ctx.use(loader) must get
+  // THIS memoized promise, not a fresh execution. Rather than rebind ctx.use
+  // once per cached loader (O(N) chained wrappers + a synchronous
+  // capture-before-overwrite invariant), install a single stable interceptor on
+  // the first cached loader that consults a per-ctx override table, then just
+  // prime the table for each subsequent cached loader. The captured pre-
+  // interceptor `originalUse` (whatever setup mode installed it) runs the
+  // cache-miss execute, so a loader never awaits its own in-flight promise.
+  const internal = ctx as InternalHandlerContext<any, TEnv>;
+  let overrides = internal._loaderCacheOverrides;
+  if (!overrides) {
+    overrides = internal._loaderCacheOverrides = new Map();
+    const originalUse = ctx.use;
+    internal._loaderCacheOriginalUse = originalUse;
+    ctx.use = ((item: any) => {
+      const cached = overrides!.get(item?.$$id);
+      if (cached) return cached;
+      return originalUse(item);
+    }) as typeof ctx.use;
+  }
+  const runMiss = internal._loaderCacheOriginalUse!;
+
   const dataPromise = (async () => {
     const codec = await getCodec();
     const key = await resolveLoaderKey(
@@ -162,7 +184,7 @@ export function resolveLoaderData<TEnv>(
       getItem: (k) => store.getItem!(k),
       setItem: (k, v, o) => store.setItem!(k, v, o),
       key,
-      execute: () => originalUse(loaderEntry.loader),
+      execute: () => runMiss(loaderEntry.loader),
       serialize: (d) => codec.serializeResult(d),
       deserialize: (v) => codec.deserializeResult(v),
       storeOptions: { ttl, swr, tags },
@@ -174,17 +196,7 @@ export function resolveLoaderData<TEnv>(
     });
   })();
 
-  // Temporarily replace ctx.use() so the handler's call returns cached data.
-  // This is needed because ctx.use() closes over the match context's loaderPromises
-  // map which is separate from the request context. By wrapping use(), we intercept
-  // the handler's call and return the shared dataPromise.
-  const wrappedUse = ((item: any) => {
-    if (item === loaderEntry.loader || item?.$$id === loaderId) {
-      return dataPromise;
-    }
-    return originalUse(item);
-  }) as typeof ctx.use;
-  ctx.use = wrappedUse;
+  overrides.set(loaderId, dataPromise);
 
   return dataPromise;
 }