@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.130

package/src/route-definition/redirect.ts

@@ -0,0 +1,135 @@
+import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+import {
+  requireRequestContext,
+  getRequestContext,
+  _getRequestContext,
+} from "../server/request-context.js";
+import { markExternalRedirect } from "../redirect-origin.js";
+
+/**
+ * Create a soft redirect Response for middleware short-circuit
+ *
+ * Returns a Response that signals a client-side navigation to the target URL.
+ * Unlike Response.redirect() which causes a full page reload, this redirect
+ * is handled by the router for SPA-style navigation.
+ *
+ * Supports an optional state parameter to carry location state through the
+ * redirect. On the target page, state can be read via useLocationState()
+ * (use { flash: true } in createLocationState for read-once flash messages).
+ *
+ * @param url - The URL to redirect to
+ * @param statusOrOptions - HTTP status code (default: 302) or options object
+ *
+ * @example
+ * ```typescript
+ * // Simple redirect
+ * middleware((ctx, next) => {
+ *   if (!ctx.get('user')) {
+ *     return redirect('/login');
+ *   }
+ *   next();
+ * })
+ *
+ * // Redirect with state
+ * return redirect('/dashboard', {
+ *   state: [Flash({ text: "Item saved!" })],
+ * });
+ *
+ * // Redirect with custom status and state
+ * return redirect('/login', {
+ *   status: 303,
+ *   state: [Flash({ text: "Session expired" })],
+ * });
+ *
+ * // Off-host redirect (opt out of the same-origin guard). Without
+ * // `external: true`, a cross-origin target is blocked and replaced with the
+ * // app root, matching the client's open-redirect protection.
+ * return redirect('https://accounts.example.com/oauth', { external: true });
+ * ```
+ */
+export function redirect(url: string, status?: number): Response;
+export function redirect(
+  url: string,
+  options: {
+    status?: number;
+    state?: LocationStateEntry | LocationStateEntry[];
+    external?: boolean;
+  },
+): Response;
+export function redirect(
+  url: string,
+  statusOrOptions?:
+    | number
+    | {
+        status?: number;
+        state?: LocationStateEntry | LocationStateEntry[];
+        external?: boolean;
+      },
+): Response {
+  const status =
+    typeof statusOrOptions === "number"
+      ? statusOrOptions
+      : (statusOrOptions?.status ?? 302);
+  const state =
+    typeof statusOrOptions === "object" ? statusOrOptions?.state : undefined;
+  const external =
+    typeof statusOrOptions === "object" ? statusOrOptions?.external : undefined;
+
+  if (state) {
+    const ctx = requireRequestContext();
+    ctx.setLocationState(state);
+
+    if (process.env.NODE_ENV !== "production") {
+      const reqCtx = getRequestContext();
+      // Warn only on true full-page SSR loads. SPA partial requests and server
+      // actions both deliver state through Flight payloads, so suppress for those.
+      if (
+        reqCtx &&
+        !reqCtx.originalUrl.searchParams.has("_rsc_partial") &&
+        !reqCtx.request.headers.has("rsc-action") &&
+        !reqCtx.originalUrl.searchParams.has("_rsc_action")
+      ) {
+        console.warn(
+          `[Router] redirect() with state during a full-page (SSR) request to "${url}". ` +
+            "Location state is only delivered during SPA navigations and will be lost on this request.",
+        );
+      }
+    }
+  }
+
+  // Auto-prefix root-relative URLs with basename for app-local redirects.
+  // Treat the URL as already-prefixed when the basename is followed by a path
+  // separator, a query, a fragment, or end-of-string, so "/admin?tab=x" and
+  // "/admin#frag" are not double-prefixed into "/admin/admin?tab=x".
+  const bn = _getRequestContext()?._basename;
+  let resolvedUrl = url;
+  if (
+    bn &&
+    url.startsWith("/") &&
+    url !== bn &&
+    !url.startsWith(bn + "/") &&
+    !url.startsWith(bn + "?") &&
+    !url.startsWith(bn + "#")
+  ) {
+    resolvedUrl = url === "/" ? bn : bn + url;
+  }
+
+  const headers: Record<string, string> = {
+    Location: resolvedUrl,
+    "X-RSC-Redirect": "soft",
+  };
+
+  const response = new Response(null, { status, headers });
+
+  // Mark an explicit off-host redirect with an out-of-band brand so the
+  // same-origin guard (rsc/redirect-guard.ts) lets it through. The brand is a
+  // WeakSet membership on this Response object -- NOT a wire header -- so the
+  // opt-in cannot be forged by an attacker-controlled upstream response a
+  // proxy-style response route might copy. The internal redirect-rebuild paths
+  // transfer the brand; the guard reads and clears it (see markExternalRedirect).
+  if (external) {
+    markExternalRedirect(response);
+  }
+
+  return response;
+}

package/src/route-definition/resolve-handler-use.ts

@@ -0,0 +1,161 @@
+import type { AllUseItems } from "../route-types.js";
+import { isPrerenderHandler, isPassthroughHandler } from "../prerender.js";
+import { isStaticHandler } from "../static-handler.js";
+
+/**
+ * Extract the .use callback from any handler shape.
+ *
+ * Checks definition brands first (objects with __brand), then plain functions.
+ * ReactNode handlers return undefined (no .use possible).
+ */
+export function resolveHandlerUse(handler: unknown): (() => any[]) | undefined {
+  if (handler == null) return undefined;
+
+  // Check branded definitions first — they're objects but also have typeof "object"
+  if (isPassthroughHandler(handler)) {
+    return (handler as any).use;
+  }
+  if (isPrerenderHandler(handler)) {
+    return (handler as any).use;
+  }
+  if (isStaticHandler(handler)) {
+    return (handler as any).use;
+  }
+  // Loader definitions from createLoader() — branded objects with optional .use
+  if (typeof handler === "object" && (handler as any).__brand === "loader") {
+    return (handler as any).use;
+  }
+  // Plain handler function
+  if (typeof handler === "function") {
+    return (handler as any).use;
+  }
+  // ReactNode or other — no .use
+  return undefined;
+}
+
+/**
+ * Allowed item types per mount site.
+ * Mirrors the RouteUseItem / ParallelUseItem / InterceptUseItem / LayoutUseItem unions
+ * from route-types.ts for runtime validation.
+ */
+const MOUNT_SITE_ALLOWED_TYPES: Record<string, Set<string>> = {
+  path: new Set([
+    "layout",
+    "parallel",
+    "intercept",
+    "middleware",
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "cache",
+    "transition",
+  ]),
+  // Response routes (path.json, path.text, etc.) — mirrors ResponseRouteUseItem
+  response: new Set(["middleware", "cache"]),
+  route: new Set([
+    "layout",
+    "parallel",
+    "intercept",
+    "middleware",
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "cache",
+    "transition",
+  ]),
+  // layout allows AllUseItems — no validation needed, but included for completeness
+  layout: new Set([
+    "layout",
+    "route",
+    "middleware",
+    "revalidate",
+    "parallel",
+    "intercept",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "cache",
+    "transition",
+    "include",
+  ]),
+  parallel: new Set([
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "transition",
+  ]),
+  intercept: new Set([
+    "middleware",
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "layout",
+    "route",
+    "when",
+    "transition",
+  ]),
+  // LoaderUseItem — only revalidate + cache can attach to a loader entry
+  loader: new Set(["revalidate", "cache"]),
+};
+
+/**
+ * Validate that items from handler.use() are valid for the given mount site.
+ * Throws a descriptive error if any item is not allowed.
+ */
+export function validateHandlerUseItems(
+  items: AllUseItems[],
+  mountSite: string,
+): void {
+  const allowed = MOUNT_SITE_ALLOWED_TYPES[mountSite];
+  if (!allowed) return;
+  for (const item of items) {
+    if (item == null) continue;
+    if (!allowed.has((item as any).type)) {
+      throw new Error(
+        `handler.use() returned ${(item as any).type}() which is not valid inside ${mountSite}(). ` +
+          `Allowed types: ${[...allowed].join(", ")}.`,
+      );
+    }
+  }
+}
+
+/**
+ * Create a merged use callback from handler.use and explicit use.
+ * handler.use items come first (defaults), explicit items second (overrides).
+ * Returns undefined if both are absent.
+ */
+export function mergeHandlerUse(
+  handlerUse: (() => any[]) | undefined,
+  explicitUse: (() => any[]) | undefined,
+  mountSite: string,
+): (() => any[]) | undefined {
+  if (!handlerUse && !explicitUse) return undefined;
+  // Validation asymmetry (intentional, pre-1.0): only handler.use() items are
+  // checked against the mount-site allow-list (validateHandlerUseItems below).
+  // Explicit use() items pass through unvalidated on both the explicit-only
+  // branch here and the merged branch, so a structurally-valid-but-prohibited
+  // item (e.g. middleware() inside a parallel slot) is not rejected at this seam.
+  // Documented rather than enforced for now; revisit before 1.0 (#569).
+  if (!handlerUse) return explicitUse;
+  if (!explicitUse) {
+    return () => {
+      const items = handlerUse().flat(3);
+      validateHandlerUseItems(items, mountSite);
+      return items;
+    };
+  }
+  return () => {
+    const hItems = handlerUse().flat(3);
+    validateHandlerUseItems(hItems, mountSite);
+    return [...hItems, ...explicitUse()];
+  };
+}

package/src/route-definition/use-item-types.ts

@@ -0,0 +1,32 @@
+import type { AllUseItems, WhenItem } from "../route-types.js";
+
+/**
+ * The set of valid use-item `type` discriminants — the single runtime source of
+ * truth for "is this a well-formed use item?" shape validation.
+ *
+ * Declared via a `Record<...>` so that adding a member to the union without
+ * updating this map is a compile error. `when` is included because when() items
+ * are valid inside intercept() even though WhenItem is not part of AllUseItems
+ * (it lives only in InterceptUseItem). This is shape validation only; per-mount-
+ * site rules remain the narrower hand-written tables in resolve-handler-use.ts.
+ */
+const USE_ITEM_TYPES: Record<AllUseItems["type"] | WhenItem["type"], true> = {
+  layout: true,
+  route: true,
+  middleware: true,
+  revalidate: true,
+  parallel: true,
+  intercept: true,
+  loader: true,
+  loading: true,
+  errorBoundary: true,
+  notFoundBoundary: true,
+  when: true,
+  cache: true,
+  transition: true,
+  include: true,
+};
+
+export const ALL_USE_ITEM_TYPES: ReadonlySet<string> = new Set(
+  Object.keys(USE_ITEM_TYPES),
+);