@ultimat3/http 22.7.1 → 22.8.0

package/CLAUDE.md

@@ -200,6 +200,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `stages.ts` | what each stage DOES, one entry per `StageName`, plus the stage vocabulary the other two import |
 | `finalize.ts` | the tail of that lifecycle, guarded: a throw after the handler degrades, never rejects |
 | `router.ts` | trie matcher, precedence static > param > wildcard, `path-invalid` for a segment that will not decode |
+| `navigation.ts` | the client router's server half: the gate `context` runs after the match (a prefetch to a route whose `meta.navigation` did not opt in → `204`; a soft GET to anything but a page of the router's `<app>:<surface>` → `204` + `x-ultimate-location`, before auth or app code) and the `response` stage's rewrite of a 3xx to a router request into the same hand-over, cookies kept |
 | `error-map.ts` | the code → status table, closed, plus the app's half (`registerErrorStatus`) |
 | `error-facts.ts` | every RENDERING of a throwable: `factsOf()`, the problem document (including the issue list and the opacity rule over it), the three terminal lines |
 | `hooks.ts` | the seams: `authenticate`, `authorize`, `devNotices` + the app's `configureAuthenticator()` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "22.7.1",
+  "version": "22.8.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.7.1",
-    "@ultimat3/i18n": "22.7.1",
-    "@ultimat3/schema": "22.7.1",
-    "@ultimat3/time": "22.7.1"
+    "@ultimat3/core": "22.8.0",
+    "@ultimat3/i18n": "22.8.0",
+    "@ultimat3/schema": "22.8.0",
+    "@ultimat3/time": "22.8.0"
   }
 }

package/src/error-map.ts

@@ -85,8 +85,9 @@ export const ERROR_STATUS = {
   X_WEBHOOK_SIGNATURE_STALE: 401,
   // Boot refusals of the app's HTTP declaration (a bearer mount, an action's pinned path or the
   // app's path style or a path derived before it, the openapi block, the MCP oauth block or an
-  // idempotent tool shadowing its key argument, a page's `post`) — never a request's
-  // answer; 500 if one ever escaped into a response: the deployment is wrong, the caller is not.
+  // idempotent tool shadowing its key argument, a page's `post` or `navigation`) — never a request's
+  // answer; 500 if one ever escaped into a response (`x dev` re-evaluating an edited route module):
+  // the deployment is wrong, the caller is not.
   X_BEARER_MOUNT_INVALID: 500,
   X_ACTION_HTTP_PATH_INVALID: 500,
   X_ACTION_PATH_STYLE_INVALID: 500,
@@ -95,6 +96,7 @@ export const ERROR_STATUS = {
   X_MCP_OAUTH_INVALID: 500,
   X_MCP_IDEMPOTENCY_KEY_SHADOWED: 500,
   X_ROUTE_POST_INVALID: 500,
+  X_ROUTE_NAVIGATION_INVALID: 500,
   // @ultimat3/action — the code every primitive throws when the CALLER's input fails the schema
   // the primitive declared. 400 because that is what the published OpenAPI operation promises for
   // it, and because a missing row made a typo'd uuid a 500: the caller was told the server broke,

package/src/index.ts

@@ -110,6 +110,8 @@ export type { LocaleConfig, TimeZoneConfig } from './locale';
 export { DEFAULT_LOCALE_CONFIG, readCookie } from './locale';
 export type { Middleware } from './middleware';
 export { compose } from './middleware';
+export type { NavigationPurpose } from './navigation';
+export { navigationGate, navigationPurpose, redirectForRouter, relocate } from './navigation';
 export type { OverlayMeta, OverlayNotice } from './overlay';
 export { overlayResponse, wantsOverlay } from './overlay';
 export { OVERLAY_STYLE } from './overlay-style';
@@ -186,6 +188,7 @@ export type {
   RouteDescription,
   RouteHandler,
   RouteMeta,
+  RouteNavigation,
   RouteParams,
   RouteTable,
 } from './router';

package/src/navigation.ts

@@ -0,0 +1,79 @@
+// The server half of client navigation: which router requests a route may answer at all, and a
+// redirect answered to a router request turned into something it can act on without a second
+// execution. Read by two stages — `context` (the gate, before auth and before any app code) and
+// `response` (the rewrite, after everything) — so every route is covered, pages or not.
+//
+// Why here and not in the router: a request the browser was never asked to make (a prefetch)
+// must run NOTHING on a route that did not ask for it, and a GET some app records evidence on (a
+// download, a click, a token open) must run exactly once. Only the server can promise either.
+
+import {
+  CLIENT_NAVIGATION_HEADER,
+  CLIENT_NAVIGATION_LOCATION_HEADER,
+  CLIENT_NAVIGATION_SURFACE_HEADER,
+} from '@ultimat3/core';
+import type { RouteNavigation } from './router';
+
+export type NavigationPurpose = 'soft' | 'prefetch';
+
+/** `soft`, `prefetch`, or `null` for every request the router did not make. */
+export function navigationPurpose(request: Request): NavigationPurpose | null {
+  const said = request.headers.get(CLIENT_NAVIGATION_HEADER);
+  return said === 'soft' || said === 'prefetch' ? said : null;
+}
+
+const SAFE = new Set(['GET', 'HEAD']);
+
+/** "Load this with a real navigation" — never stored anywhere, it answers one request. */
+export function relocate(location: string, headers?: Headers): Response {
+  const out = new Headers(headers);
+  out.delete('location');
+  out.delete('content-type');
+  out.delete('content-length');
+  out.set(CLIENT_NAVIGATION_LOCATION_HEADER, location);
+  out.set('cache-control', 'no-store');
+  return new Response(null, { status: 204, headers: out });
+}
+
+/**
+ * Before the route runs. A GET the router made to anything but a page of ITS surface is answered
+ * here: a prefetch with an empty `204` (it may not run the route, and it has nothing to swap), a
+ * soft visit with `204` + `x-ultimate-location` naming the same URL, which the router loads as a
+ * document — so the route runs once, for the real navigation. A POST is never gated: it is the
+ * form's submission, and the rewrite below keeps its redirect to one execution.
+ */
+export function navigationGate(
+  request: Request,
+  method: string,
+  url: URL,
+  navigation: RouteNavigation | undefined,
+): Response | undefined {
+  const purpose = navigationPurpose(request);
+  if (purpose === null || !SAFE.has(method)) return undefined;
+  const surface = request.headers.get(CLIENT_NAVIGATION_SURFACE_HEADER);
+  const ours = navigation !== undefined && navigation.surface === surface;
+  if (ours && (purpose === 'soft' || navigation.prefetch)) return undefined;
+  if (purpose === 'prefetch') return new Response(null, { status: 204, headers: NO_STORE });
+  return relocate(url.href);
+}
+
+const NO_STORE = { 'cache-control': 'no-store' } as const;
+
+/**
+ * After everything. A redirect answered to a router request — a 303 after a form, a sign-in wall,
+ * a load's `setRedirect`, an OAuth hop to another origin — becomes `204` + `x-ultimate-location`,
+ * cookies kept. Followed by `fetch`, the target would run inside a request the router may then
+ * throw away (another surface, another origin that CORS refuses) and be asked for again; handed
+ * over, the router either follows it as its own next request or lets the browser load it, once.
+ */
+export function redirectForRouter(
+  request: Request,
+  response: Response,
+  base: URL,
+): Response | undefined {
+  if (navigationPurpose(request) === null) return undefined;
+  if (response.status < 300 || response.status > 399) return undefined;
+  const location = response.headers.get('location');
+  if (location === null) return undefined;
+  return relocate(new URL(location, base).href, response.headers);
+}

package/src/pipeline.ts

@@ -46,7 +46,7 @@ export const PIPELINE_STAGES: readonly StageDoc[] = [
   {
     name: 'context',
     phase: 'request',
-    why: 'creates the ambient context and binds the matched route; build skew is checked here because a stale client must be told to reload before it gets a 404 for a route it no longer knows',
+    why: "creates the ambient context and binds the matched route; build skew is checked here because a stale client must be told to reload before it gets a 404 for a route it no longer knows — and a client-router request the route may not answer (a prefetch it did not opt into, a soft visit to anything but a page of that router's surface) is answered here, before auth or any app code runs",
   },
   {
     name: 'locale',
@@ -92,7 +92,7 @@ export const PIPELINE_STAGES: readonly StageDoc[] = [
   {
     name: 'response',
     phase: 'finalize',
-    why: 'last: CORS, security headers, server-timing and the accumulated context headers are merged onto whatever the stages produced',
+    why: 'last: a redirect answered to a client-router request becomes 204 + x-ultimate-location (the router follows it once, never fetch), then CORS, security headers, server-timing and the accumulated context headers are merged onto whatever the stages produced',
   },
 ];
 

package/src/router.ts

@@ -33,6 +33,13 @@ export const HTTP_METHODS: readonly HttpMethod[] = [
 
 export type RouteParams = Readonly<Record<string, string>>;
 
+/** Which router may swap this page in, and whether it may be fetched before a click. */
+export interface RouteNavigation {
+  /** `<app>:<surface>` — the router's own document must carry the same. */
+  readonly surface: string;
+  readonly prefetch: boolean;
+}
+
 export interface RouteMeta {
   /** Stable id used by rate-limit keys, traces and the manifest. */
   readonly name: string;
@@ -79,6 +86,13 @@ export interface RouteMeta {
    * serves for `/` cannot negotiate, so the served process must not either.
    */
   readonly localeSource?: 'path' | 'request';
+  /**
+   * Present ONLY on a page the client router may swap in: its `<app>:<surface>` and whether it
+   * may be prefetched. Absent — every action, query, asset, storage and app route, and a page
+   * declared `navigation: 'document'` — a router request is answered before the route runs
+   * (`navigation.ts`'s gate): `204` to a prefetch, `204` + `x-ultimate-location` to a soft visit.
+   */
+  readonly navigation?: RouteNavigation;
   /**
    * THIS route's authenticator, in place of the app's `configureAuthenticator()` — never beside
    * it. A route that states one is reached only through the credential it names: a bearer mount

package/src/stages.ts

@@ -35,6 +35,7 @@ import type { ServerHooks } from './hooks';
 import { acceptsHtml } from './html-render';
 import { dropVary, localeFromPath, routeLocalePrefix } from './locale-prefix';
 import { compose, type Middleware } from './middleware';
+import { navigationGate, redirectForRouter } from './navigation';
 import { overlayResponse } from './overlay';
 import { resolvePreferences } from './preferences';
 import { type RateLimitDecision, type RateLimiter, rateLimitSpends } from './rate-limit';
@@ -187,7 +188,8 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       }
       ctx.route = match.route;
       ctx.params = match.params;
-      return undefined;
+      // Before auth and every app hook: a router request a route may not answer runs nothing.
+      return navigationGate(request.raw, ctx.method, ctx.url, match.route.meta.navigation);
     },
 
     /**
@@ -434,6 +436,12 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
     },
 
     response: (request, ctx) => {
+      // First, so everything below lands on the answer the router actually gets.
+      const handedOver =
+        ctx.response === undefined
+          ? undefined
+          : redirectForRouter(request.raw, ctx.response, ctx.url);
+      if (handedOver !== undefined) ctx.response = handedOver;
       const response = ctx.response;
       if (response === undefined) return undefined;
       for (const [name, value] of ctx.headers) response.headers.set(name, value);