@ultimat3/http 27.8.0 → 27.9.0

package/CLAUDE.md

@@ -124,7 +124,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   past `bodyLimitBytes`); multipart goes through the same capped bytes. **Bytes with no
   `content-type` are `X_BODY_INVALID`** from `bodyRaw()`, never "no body"; `bodyBytes()` reads them.
 - **A repeated field is a LIST in all three parsers** (`collectFields`).
-- **`matchRoute` never throws**: `router.ts`'s `decodeSegment` answers `path-invalid` →
+- **`matchRoute` never throws**: `route-path.ts`'s `decodeSegment` answers `path-invalid` →
   `X_PATH_INVALID` (400).
 - **`handle()` resolves to a Response or nothing**: request phases are guarded by `execute`, the tail
   by `finalize.ts` — a refusing finalize stage degrades to `X_PIPELINE_FINALIZE_FAILED` with a second
@@ -237,7 +237,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `pipeline.ts` | the ORDER the stages run in — the framework's guarantee — and the one loop that drives a request through them |
 | `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. A request segment is decoded ONCE; a static child is looked up raw, then decoded (`/precios-espa%C3%B1a` is `/precios-españa`). A wildcard takes an EMPTY rest after the node's own routes (`/docs` → `/docs/*path` with `path: ''`, the path `@ultimat3/render`'s static build writes) — `router-spelling.test.ts` |
+| `router.ts` | trie, static > param > wildcard, `path-invalid` for a segment that will not decode. A request segment is decoded ONCE; a static child is looked up raw, then decoded. A wildcard takes an EMPTY rest after the node's own routes (`/docs` → `/docs/*path`, `path: ''`). Segments, decoding and `canonicalPath` are `route-path.ts`'s: `ctx.routePath` is the match's one spelling, `requestAddress(ctx)` what render keys `isr` on |
 | `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: COMPOSES the slices and holds no row of its own |
 | `error-map-http.ts`, `error-map-tier-<0-4>.ts` | the rows, one slice per owning tier (this package's own apart). `bun run new-error-code` appends to the slice its `--package` maps to; a code in two slices is refused there and by `error-map.test.ts` |

package/README.md

@@ -10,6 +10,7 @@ to skip.
 |---|---|
 | server lifecycle, drain, `/healthz` + `/readyz` | `server.ts`; `health-disclosure.ts` owns the `healthDetailPeers` key, its screen and the proxy half — the body rule is `@ultimat3/core`'s |
 | route table, matcher, `describeRoutes()` | `router.ts` |
+| a pathname's segments, their decoding, and its ONE spelling (`canonicalPath`) — shared by the matcher and by every store keyed on an address; `ctx.routePath` and `requestAddress(ctx)` say where a request was matched | `route-path.ts`, `locale-prefix.ts` |
 | the ordered request lifecycle | `pipeline.ts` |
 | typed request (params, query, body) | `request.ts` |
 | response constructors + `problem()` | `response.ts` |

package/package.json

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

package/src/context.ts

@@ -117,6 +117,13 @@ export interface RequestContext extends Ctx {
    * is matched. Authoritative: the `locale` stage answers it over every other source.
    */
   pathLocale: string | undefined;
+  /**
+   * The path the route table MATCHED, in its one spelling (`route-path.ts`'s `canonicalPath`): base
+   * path and routed locale prefix removed, no empty segment, each segment decoded and re-encoded.
+   * Set with `route` by the `context` stage. What a store keyed by address keys on — never
+   * `url.pathname`, which is one of the many spellings the router answers with the same page.
+   */
+  routePath: string | undefined;
   tz: string;
   /** What the CLIENT says it is running, from core's `BUILD_ID_HEADER`. `assertBuild()` reads it. */
   clientBuildId: string | null;
@@ -234,6 +241,7 @@ export const requestContext = (init: RequestContextInit): RequestContext => {
     actor: anonymousActor(),
     locale: localeConfig().fallback,
     pathLocale: undefined,
+    routePath: undefined,
     tz: timeConfig().defaultZone,
     clientBuildId: null,
     input: undefined,

package/src/error-map-tier-1.ts

@@ -80,4 +80,6 @@ export const TIER_1_ERROR_STATUS = {
   // 409 with the rest of promotion's refusals: an earlier call moved these bytes (a doubled or
   // retried confirm), a state the caller answers by reading the row that holds `meta.attachedKey`.
   X_STORAGE_ALREADY_PROMOTED: 409,
+  // @ultimat3/seo — a sitemap entry carries a lastmod or a locale the sitemap cannot write
+  X_SITEMAP_ENTRY_INVALID: 500,
 } satisfies Readonly<Record<string, number>>;

package/src/error-map-tier-4.ts

@@ -129,4 +129,8 @@ export const TIER_4_ERROR_STATUS = {
   X_PWA_PUSH_PAYLOAD_TOO_LARGE: 500,
   // @ultimat3/pwa — the push endpoint is not on a push service this app sends to
   X_PWA_PUSH_HOST_UNLISTED: 422,
+  // @ultimat3/ai — an agent repeated one tool call with one result and was stopped
+  X_AGENT_TOOL_LOOP: 500,
+  // @ultimat3/ai — an agent ran past its declared deadline and was stopped
+  X_AGENT_DEADLINE: 504,
 } satisfies Readonly<Record<string, number>>;

package/src/index.ts

@@ -106,6 +106,8 @@ export type { Authenticator, AuthzDecision, ServerHooks } from './hooks';
 export { configureAuthenticator, configuredAuthenticator, resetAuthenticator } from './hooks';
 export type { LocaleConfig, TimeZoneConfig } from './locale';
 export { DEFAULT_LOCALE_CONFIG } from './locale';
+export type { RequestAddress } from './locale-prefix';
+export { requestAddress } from './locale-prefix';
 export type { Middleware } from './middleware';
 export { compose } from './middleware';
 export type { NavigationPurpose } from './navigation';
@@ -194,6 +196,7 @@ export {
   textResponse,
   withHeaders,
 } from './response';
+export { canonicalPath } from './route-path';
 export type {
   HttpMethod,
   MatchResult,

package/src/locale-prefix.ts

@@ -3,9 +3,10 @@
 // it is authoritative over query, cookie, user and header. Which locales route, and how a path is
 // spelled in one, are `@ultimat3/i18n`'s; this file only applies them to a request.
 
+import { localeSegment } from '@ultimat3/core';
 import { type LocaleSources, localeConfig, resolveLocale, splitLocalePrefix } from '@ultimat3/i18n';
 import type { RequestContext } from './context';
-import { normalizePath } from './router';
+import { normalizePath } from './route-path';
 
 /** Methods whose redirect may change nothing but the URL. Anything else is a 308, never a 301. */
 const SAFE_METHODS = new Set(['GET', 'HEAD']);
@@ -44,6 +45,37 @@ export function routeLocalePrefix(
   return prefix.path;
 }
 
+/** A matched request's address, in the one spelling every pathname the router treats alike shares. */
+export interface RequestAddress {
+  /**
+   * The locale prefix the URL named, then the path the table matched — NO base path. What a store
+   * keys on: `@ultimat3/i18n`'s `unlocalizedPath` reads the route's own path straight back out of
+   * it, which it cannot do through a mount.
+   */
+  readonly path: string;
+  /** `path` under the mount: the pathname the request's URL carries, respelled. */
+  readonly pathname: string;
+}
+
+/**
+ * Where a matched request IS, from what the `context` stage recorded when it matched
+ * (`ctx.routePath`, `ctx.pathLocale`) — `undefined` before that. `/blog//a/`, `/blog/%61` and
+ * `/blog/a` are one address: it is what a shared document is keyed by and rendered AT, so a page
+ * that builds its `canonical` from the URL it was handed is never given whichever spelling
+ * happened to arrive first. Nothing is redirected; the request is answered where it was asked.
+ */
+export function requestAddress(ctx: RequestContext): RequestAddress | undefined {
+  if (ctx.routePath === undefined) return undefined;
+  const { basePath } = ctx.config;
+  const mount = basePath === '/' || basePath === '' ? '' : basePath.replace(/\/$/, '');
+  // The prefix PUT BACK, exactly as it was split off — never `localizedPath`, which re-spells a
+  // path already carrying a locale segment: `/en/en/x` (the `/:lang/x` route, in English) is not
+  // `/en/x`. A locale's root is the directory, `/en/`, as `localizedPath` and the export spell it.
+  const prefix = ctx.pathLocale === undefined ? '' : `/${localeSegment(ctx.pathLocale)}`;
+  const path = prefix !== '' && ctx.routePath === '/' ? `${prefix}/` : `${prefix}${ctx.routePath}`;
+  return { path, pathname: path === '/' && mount !== '' ? mount : `${mount}${path}` };
+}
+
 /**
  * The request's locale. The path first, always; then a route that takes its locale from the path
  * alone gets the DEFAULT for an unprefixed URL — no negotiation, because the document a CDN serves

package/src/route-path.ts

@@ -0,0 +1,61 @@
+// A request pathname as the route table reads it: its segments, each one's decoded text, and the
+// ONE spelling every pathname the router treats as the same address shares. The router matches on
+// these functions and a store keyed by path (`@ultimat3/render`'s `isr`) keys on the same ones, so
+// "routes to the same page" and "is the same entry" cannot be decided by two normalisers.
+
+/** The non-empty segments: `/a/b/` and `//a//b` are both `['a', 'b']`. */
+export const pathSegments = (path: string): readonly string[] =>
+  path.split('/').filter((segment) => segment.length > 0);
+
+/** `/a/b/` and `//a//b` both normalise to `/a/b`; `/` stays `/`. Segments are kept as written. */
+export const normalizePath = (path: string): string => {
+  const segments = pathSegments(path);
+  return segments.length === 0 ? '/' : `/${segments.join('/')}`;
+};
+
+/**
+ * `undefined` instead of the bare `URIError` `decodeURIComponent('%ZZ')` throws. A pathname is
+ * whatever the client typed, and an exception from the match would leave the pipeline with
+ * `X_INTERNAL` — a 500, and a page for the on-call, for a request only the caller can fix.
+ */
+export const decodeSegment = (segment: string): string | undefined => {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return undefined;
+  }
+};
+
+/** What `encodeURIComponent` escapes and a path segment may carry as written (RFC 3986 `pchar`). */
+const SEGMENT_SAFE = /%(?:24|26|2B|2C|3A|3B|3D|40)/g;
+
+/**
+ * One segment in its one spelling: decoded as the router decodes it, then every character a path
+ * segment may not carry literally percent-encoded, upper-case hex. So `%61bc` is `abc`, `caf%c3%a9`
+ * is `caf%C3%A9`, and `a%2fb` is `a%2Fb` — a `/` INSIDE a segment stays encoded, because the router
+ * hands it to one param (`a/b`) and never splits on it. `@ : + , ; = $ &` stay as written, which is
+ * how `URL.pathname` spells them: an address that needs no escape is its own canonical form.
+ *
+ * A segment that will not decode (`%ZZ`) is kept as written. The router refuses it for a param
+ * (`path-invalid`), so it reaches a page only as a static segment spelled exactly that way.
+ */
+export const canonicalSegment = (segment: string): string => {
+  const decoded = decodeSegment(segment);
+  if (decoded === undefined) return segment;
+  try {
+    return encodeURIComponent(decoded).replace(SEGMENT_SAFE, decodeURIComponent);
+  } catch {
+    // A lone surrogate: not text a URL can carry, and never what `URL.pathname` hands over.
+    return segment;
+  }
+};
+
+/**
+ * A pathname in the one spelling shared by every pathname the router matches identically: no empty
+ * segment, no trailing slash, each segment `canonicalSegment`'s. Idempotent. Dot segments are not
+ * this function's — `URL` resolved them (`%2e%2e` included) before a pathname existed.
+ */
+export const canonicalPath = (path: string): string => {
+  const segments = pathSegments(path);
+  return segments.length === 0 ? '/' : `/${segments.map(canonicalSegment).join('/')}`;
+};

package/src/router.ts

@@ -17,6 +17,8 @@ import type { Bucket } from './rate-limit';
 import type { UltimateRequest } from './request';
 import type { CacheHint } from './response';
 import { assertRouteCache } from './route-cache';
+// Segments and their decoding are `route-path.ts`'s, shared with every store keyed by a path.
+import { decodeSegment, normalizePath, pathSegments } from './route-path';
 import type { Schema } from './validate';
 
 export type HttpMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
@@ -163,17 +165,6 @@ const node = (): TrieNode => ({
   routes: new Map(),
 });
 
-/** `/a/b/` and `//a//b` both normalise to `/a/b`; `/` stays `/`. */
-export const normalizePath = (path: string): string => {
-  const trimmed = path.split('/').filter((segment) => segment.length > 0);
-  return trimmed.length === 0 ? '/' : `/${trimmed.join('/')}`;
-};
-
-const segmentsOf = (path: string): readonly string[] =>
-  normalizePath(path)
-    .split('/')
-    .filter((segment) => segment.length > 0);
-
 export const httpRouter = (routes: readonly Route[]): RouteTable => {
   const root = node();
   for (const route of routes) {
@@ -182,7 +173,7 @@ export const httpRouter = (routes: readonly Route[]): RouteTable => {
     // log line once per request and a response that quietly falls back to heuristic caching.
     assertRouteCache(route.meta.cache, route.meta.name, route.path);
     let current = root;
-    const segments = segmentsOf(route.path);
+    const segments = pathSegments(route.path);
     for (const [index, segment] of segments.entries()) {
       if (segment.startsWith(':')) {
         const name = segment.slice(1);
@@ -233,19 +224,6 @@ interface Search {
   undecodable: string | undefined;
 }
 
-/**
- * `undefined` instead of the bare `URIError` `decodeURIComponent('%ZZ')` throws. A pathname is
- * whatever the client typed, and an exception from the match would leave the pipeline with
- * `X_INTERNAL` — a 500, and a page for the on-call, for a request only the caller can fix.
- */
-const decodeSegment = (segment: string): string | undefined => {
-  try {
-    return decodeURIComponent(segment);
-  } catch {
-    return undefined;
-  }
-};
-
 /** Terminal nodes reachable for `segments`, in precedence order. */
 const candidates = (
   current: TrieNode,
@@ -311,7 +289,7 @@ const routeFor = (candidate: Candidate, method: HttpMethod): Route | undefined =
   (method === 'HEAD' ? candidate.node.routes.get('GET') : undefined);
 
 export const matchRoute = (table: RouteTable, method: string, pathname: string): MatchResult => {
-  const segments = segmentsOf(pathname);
+  const segments = pathSegments(pathname);
   const search: Search = { out: [], undecodable: undefined };
   candidates(table.root, segments, 0, {}, search);
   const found = search.out;
@@ -354,7 +332,7 @@ export interface RouteDescription {
 const compare = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
 
 const paramsOf = (path: string): readonly string[] =>
-  segmentsOf(path)
+  pathSegments(path)
     .filter((segment) => segment.startsWith(':') || segment.startsWith('*'))
     .map((segment) => segment.slice(1));
 

package/src/stages.ts

@@ -47,6 +47,7 @@ import {
 } from './rate-limit-stage';
 import type { UltimateRequest } from './request';
 import { addVary, problem, redirect } from './response';
+import { canonicalPath } from './route-path';
 import { matchRoute, type Route, type RouteHandler, type RouteTable } from './router';
 import { responseSecurityHeaders } from './security-headers';
 import { validateBody } from './validate';
@@ -199,6 +200,8 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       }
       ctx.route = match.route;
       ctx.params = match.params;
+      // The address in its one spelling, from the very string the table was just asked about.
+      ctx.routePath = canonicalPath(routed);
       // 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);
     },