@ultimat3/http 22.2.1 → 22.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "22.2.1",
+  "version": "22.3.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.2.1",
-    "@ultimat3/i18n": "22.2.1",
-    "@ultimat3/schema": "22.2.1",
-    "@ultimat3/time": "22.2.1"
+    "@ultimat3/core": "22.3.0",
+    "@ultimat3/i18n": "22.3.0",
+    "@ultimat3/schema": "22.3.0",
+    "@ultimat3/time": "22.3.0"
   }
 }

package/src/context.ts

@@ -112,6 +112,11 @@ export interface RequestContext extends Ctx {
    */
   actor: Actor;
   locale: string;
+  /**
+   * The locale a leading `/<locale>/` segment named, set by the `context` stage before the route
+   * is matched. Authoritative: the `locale` stage answers it over every other source.
+   */
+  pathLocale: string | undefined;
   tz: string;
   /** What the CLIENT says it is running, from `config.buildIdHeader`. `assertBuild()` reads it. */
   clientBuildId: string | null;
@@ -228,6 +233,7 @@ export const createRequestContext = (init: RequestContextInit): RequestContext =
     route: undefined,
     actor: anonymousActor(),
     locale: localeConfig().fallback,
+    pathLocale: undefined,
     tz: timeConfig().defaultZone,
     clientBuildId: null,
     input: undefined,

package/src/error-map.ts

@@ -376,6 +376,10 @@ export const ERROR_STATUS = {
   // request that ran the loader, so it needs a row for the same reason the line above does: an
   // unclassified 500 blanks the sentence naming the status and the `redirect()` to use instead.
   X_ROUTE_STATUS_INVALID: 500,
+  // `asset('assets/…')` named a file that is not on disk. The static build refuses it, but an `ssr`
+  // page calls `asset()` INSIDE the request it renders, so it reaches a caller there — a deploy
+  // defect, never the visitor's, hence 500, declared so the cause naming the missing file survives.
+  X_ASSET_MISSING: 500,
   // @ultimat3/mail
   // The deployment configured no transport. It reaches a caller only through an inline
   // `send(…, { sync: true })` inside a request; the queued path dead-letters instead. A server-side

package/src/locale-prefix.ts

@@ -0,0 +1,70 @@
+// The locale a URL names. A leading `/<locale>/` segment is split off BEFORE the route table is
+// matched — so `/en/precios` is the `/precios` route in English and `/fr/x` is still a 404 — and
+// 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 { type LocaleSources, localeConfig, resolveLocale, splitLocalePrefix } from '@ultimat3/i18n';
+import type { RequestContext } from './context';
+
+/** Methods whose redirect may change nothing but the URL. Anything else is a 308, never a 301. */
+const SAFE_METHODS = new Set(['GET', 'HEAD']);
+
+/**
+ * The pathname the router should match, or the redirect that answers the request instead.
+ *
+ * A prefix naming the DEFAULT locale is a duplicate URL (`/es-co/precios` is `/precios`), so it is
+ * answered with a permanent redirect to the unprefixed path rather than served twice. A prefix
+ * naming another routed locale is stripped and recorded on `ctx.pathLocale` — and on `ctx.locale`
+ * at once, so a 404 for `/en/nothing` renders its error page in the language the URL asked for.
+ */
+export function routeLocalePrefix(
+  pathname: string,
+  ctx: RequestContext,
+  basePath: string,
+): string | Response {
+  const prefix = splitLocalePrefix(pathname);
+  if (prefix === undefined) return pathname;
+  if (prefix.isDefault) {
+    const mount = basePath === '/' || basePath === '' ? '' : basePath.replace(/\/$/, '');
+    const location = `${mount}${prefix.path}${ctx.url.search}`;
+    // PERMANENT, and so not `redirect()`, whose statuses are an application's (it refuses 301 on
+    // purpose: a cached permanent redirect cannot be taken back). This one is the framework's URL
+    // scheme, and it IS permanent — the default locale is never prefixed, in any release.
+    return new Response(null, {
+      status: SAFE_METHODS.has(ctx.method) ? 301 : 308,
+      headers: { location },
+    });
+  }
+  ctx.pathLocale = prefix.locale;
+  ctx.locale = prefix.locale;
+  return prefix.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
+ * for `/` is one file and cannot vary by header (the bug this rule closes: a `site/` page answered
+ * in English to an English browser from the process, and in Spanish from the export). Every other
+ * route keeps `resolveLocale`'s own order.
+ */
+export function requestLocale(ctx: RequestContext, sources: LocaleSources): string {
+  if (ctx.pathLocale !== undefined) return ctx.pathLocale;
+  if (ctx.route?.meta.localeSource === 'path') return localeConfig().fallback;
+  return resolveLocale(sources).locale;
+}
+
+/** Whether this response's locale is a function of its URL alone. */
+export const localeFromPath = (ctx: RequestContext): boolean =>
+  ctx.pathLocale !== undefined || ctx.route?.meta.localeSource === 'path';
+
+/** Removes one dimension from `Vary`, case-insensitively, deleting the header when none is left. */
+export const dropVary = (response: Response, name: string): Response => {
+  const existing = response.headers.get('vary');
+  if (existing === null) return response;
+  const kept = existing
+    .split(/,\s*/)
+    .filter((value) => value !== '' && value.toLowerCase() !== name.toLowerCase());
+  if (kept.length === 0) response.headers.delete('vary');
+  else response.headers.set('vary', kept.join(', '));
+  return response;
+};

package/src/preferences.ts

@@ -0,0 +1,38 @@
+// `ctx.locale`, `ctx.tz` and `content-language` for one request: the `locale` stage calls this,
+// and `auth` calls it again once the actor's saved preference is known. WHERE each value is read
+// from is this file's; what a locale or a zone IS stays `@ultimat3/i18n`'s and `@ultimat3/time`'s.
+
+import { resolveTimeZone } from '@ultimat3/time';
+import type { HttpConfig } from './config';
+import type { RequestContext } from './context';
+import { readCookie } from './locale';
+import { requestLocale } from './locale-prefix';
+import type { UltimateRequest } from './request';
+
+/**
+ * `ctx.locale`, `ctx.tz` and `content-language` from every source the request carries — the
+ * cookie, the header and, once `auth` has run, the actor's saved preference. One function for both
+ * stages, so the order is always the owners' (`resolveLocale`, `resolveTimeZone`) and never this
+ * file's.
+ */
+export function resolvePreferences(
+  request: UltimateRequest,
+  ctx: RequestContext,
+  config: HttpConfig,
+): void {
+  const cookies = request.header('cookie');
+  ctx.locale = requestLocale(ctx, {
+    // Documented as a source and never read until 2026-09: an email preview link's `?locale=es`
+    // rendered in the visitor's cookie locale. The ORDER stays `resolveLocale`'s.
+    query: ctx.url.searchParams.get('locale'),
+    header: request.header('accept-language'),
+    cookie: readCookie(cookies, config.locale.cookie),
+    user: ctx.actor.locale,
+  });
+  ctx.tz = resolveTimeZone({
+    cookie: readCookie(cookies, config.tz.cookie),
+    header: request.header(config.tz.header),
+    user: ctx.actor.tz ?? null,
+  }).zone;
+  ctx.headers.set('content-language', ctx.locale);
+}

package/src/router.ts

@@ -71,6 +71,14 @@ export interface RouteMeta {
   readonly rateLimitBucket?: Bucket;
   readonly tags?: readonly string[];
   readonly description?: string;
+  /**
+   * Where this route's locale comes from. `'request'` (the default) is `resolveLocale`'s order —
+   * query → cookie → user → header. `'path'` is the URL alone: a `/<locale>/` prefix names it and
+   * the unprefixed path is ALWAYS the default locale, so the response is a function of its URL and
+   * `Vary: accept-language` is dropped. A prerendered `site/` page is `'path'`: the file a CDN
+   * serves for `/` cannot negotiate, so the served process must not either.
+   */
+  readonly localeSource?: 'path' | 'request';
 }
 
 export type RouteHandler = (

package/src/stages.ts

@@ -12,8 +12,6 @@ import {
   lifecycleState,
   reportError,
 } from '@ultimat3/core';
-import { resolveLocale } from '@ultimat3/i18n';
-import { resolveTimeZone } from '@ultimat3/time';
 import { signInRedirect } from './auth-redirect';
 import { defaultCache, offersSharedCache, PRIVATE_CACHE, reviewedHint } from './cache-policy';
 import { type HttpConfig, stripBasePath } from './config';
@@ -35,9 +33,10 @@ import {
 } from './errors';
 import type { ServerHooks } from './hooks';
 import { acceptsHtml } from './html-render';
-import { readCookie } from './locale';
+import { dropVary, localeFromPath, routeLocalePrefix } from './locale-prefix';
 import { compose, type Middleware } from './middleware';
 import { overlayResponse } from './overlay';
+import { resolvePreferences } from './preferences';
 import { type RateLimitDecision, type RateLimiter, rateLimitSpends } from './rate-limit';
 import { rateLimited } from './rate-limit-errors';
 import type { UltimateRequest } from './request';
@@ -173,8 +172,13 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       if (config.buildId !== null) ctx.headers.set(config.buildIdHeader, config.buildId);
       request.assertBuild();
 
+      // A `/<locale>/` prefix is stripped BEFORE the match, never by middleware: middleware wraps
+      // matched routes only, so `/en/precios` could never reach the `/precios` route through it.
+      // A refusal still names the path as REQUESTED, so a 404 for `/en/x` does not say `/x`.
       const pathname = stripBasePath(ctx.url.pathname, config.basePath);
-      const match = matchRoute(input.table, ctx.method, pathname);
+      const routed = routeLocalePrefix(pathname, ctx, config.basePath);
+      if (routed instanceof Response) return routed;
+      const match = matchRoute(input.table, ctx.method, routed);
       if (!match.ok) {
         if (match.reason === 'not-found') throw routeNotFound(ctx.method, pathname);
         if (match.reason === 'path-invalid') throw pathInvalid(pathname, match.segment);
@@ -457,6 +461,9 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
         if (name === 'vary') addVary(response, [value]);
         else response.headers.set(name, value);
       }
+      // After every contributor: a locale read off the URL makes the body a function of the URL,
+      // and a CDN keying it on `accept-language` too stores one copy per browser for nothing.
+      if (localeFromPath(ctx)) dropVary(response, 'accept-language');
       for (const [name, value] of Object.entries(
         responseSecurityHeaders(config.security, ctx.https),
       )) {
@@ -468,31 +475,3 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
   };
   return table;
 };
-
-/**
- * `ctx.locale`, `ctx.tz` and `content-language` from every source the request carries — the
- * cookie, the header and, once `auth` has run, the actor's saved preference. One function for both
- * stages, so the order is always the owners' (`resolveLocale`, `resolveTimeZone`) and never this
- * file's.
- */
-function resolvePreferences(
-  request: UltimateRequest,
-  ctx: RequestContext,
-  config: HttpConfig,
-): void {
-  const cookies = request.header('cookie');
-  ctx.locale = resolveLocale({
-    // Documented as a source and never read until 2026-09: an email preview link's `?locale=es`
-    // rendered in the visitor's cookie locale. The ORDER stays `resolveLocale`'s.
-    query: ctx.url.searchParams.get('locale'),
-    header: request.header('accept-language'),
-    cookie: readCookie(cookies, config.locale.cookie),
-    user: ctx.actor.locale,
-  }).locale;
-  ctx.tz = resolveTimeZone({
-    cookie: readCookie(cookies, config.tz.cookie),
-    header: request.header(config.tz.header),
-    user: ctx.actor.tz ?? null,
-  }).zone;
-  ctx.headers.set('content-language', ctx.locale);
-}