@ultimat3/http 20.2.1 → 22.0.0

package/src/peer-identity.ts

@@ -30,27 +30,25 @@ export interface PeerIdentity {
   readonly by: string | null;
 }
 
-/** Splits on a separator that is not inside a double-quoted value. `Subject="CN=a,OU=b"`. */
-const splitUnquoted = (value: string, separator: string): readonly string[] => {
+/**
+ * Splits on a separator outside double quotes, keeping the quotes and escapes EXACTLY as written.
+ * Raw on purpose: the element split and the pair split both run over this text, and an element
+ * split that also stripped quotes left `pairsOf` splitting `O=Acme; Inc` a second time, unquoted.
+ * Unescaping happens once, per value, in `unquote`.
+ */
+const splitRaw = (value: string, separator: string): readonly string[] => {
   const out: string[] = [];
   let current = '';
   let quoted = false;
   let escaped = false;
   for (const char of value) {
     if (escaped) {
-      current += char;
       escaped = false;
-      continue;
-    }
-    if (char === '\\') {
+    } else if (char === '\\') {
       escaped = true;
-      continue;
-    }
-    if (char === '"') {
+    } else if (char === '"') {
       quoted = !quoted;
-      continue;
-    }
-    if (char === separator && !quoted) {
+    } else if (char === separator && !quoted) {
       out.push(current.trim());
       current = '';
       continue;
@@ -61,14 +59,20 @@ const splitUnquoted = (value: string, separator: string): readonly string[] => {
   return out.filter((entry) => entry.length > 0);
 };
 
+/** `"CN=checkout\""` → `CN=checkout"`. An unquoted value is taken as written. */
+const unquote = (value: string): string => {
+  if (value.length < 2 || !value.startsWith('"') || !value.endsWith('"')) return value;
+  return value.slice(1, -1).replace(/\\(.)/g, '$1');
+};
+
 /** `Key=Value` pairs, keys lowercased. `URI` and `DNS` may repeat, so values collect. */
 const pairsOf = (element: string): ReadonlyMap<string, readonly string[]> => {
   const out = new Map<string, string[]>();
-  for (const pair of splitUnquoted(element, ';')) {
+  for (const pair of splitRaw(element, ';')) {
     const eq = pair.indexOf('=');
     if (eq <= 0) continue;
     const key = pair.slice(0, eq).trim().toLowerCase();
-    const value = pair.slice(eq + 1).trim();
+    const value = unquote(pair.slice(eq + 1).trim());
     if (value.length === 0) continue;
     const existing = out.get(key);
     if (existing === undefined) out.set(key, [value]);
@@ -86,7 +90,7 @@ export const peerIdentity = (input: ForwardedInput): PeerIdentity | null => {
   const element = forwardedElement(
     input.headers.get(FORWARDED_CLIENT_CERT),
     input.config.trustedProxyHops,
-    splitUnquoted,
+    splitRaw,
   );
   if (element === undefined) return null;
   const pairs = pairsOf(element);

package/src/problem-meta.ts

@@ -47,11 +47,31 @@ const RESERVED_KEYS: ReadonlySet<string> = new Set(['issues', '__proto__']);
 /** Per app-owned code, the `meta` keys its documents carry. A `Map`, for `APP_ERROR_STATUS`'s reason. */
 const DECLARED = new Map<string, readonly string[]>();
 
+/**
+ * The 5xx codes whose `cause` a caller may read. Every other 5xx document carries the code and the
+ * request id and a fixed sentence: `X_DB_STATEMENT_FAILED` has a status row, so the old "blank only
+ * what nobody classified" rule served the Postgres message and the SQL statement in a production
+ * 500. The framework's four are refusals whose cause IS the instruction — back off, retry.
+ */
+const FRAMEWORK_PUBLIC_CAUSE: ReadonlySet<string> = new Set([
+  'X_DRAINING',
+  'X_OVERLOADED',
+  'X_FLIGHT_GATE_OVERLOADED',
+  'X_TIMEOUT',
+]);
+const APP_PUBLIC_CAUSE = new Set<string>();
+
+/** Per code: the `meta` keys, a public cause, or both. A bare list is the keys alone. */
+export type ProblemMetaDeclaration =
+  | readonly string[]
+  | { readonly keys?: readonly string[] | undefined; readonly publicCause?: boolean | undefined };
+
 const sameKeys = (left: readonly string[], right: readonly string[]): boolean =>
   left.length === right.length && left.every((key, at) => key === right[at]);
 
 /**
- * Declare, per code, which `meta` keys the problem document carries. Call it once at boot, in
+ * Declare, per code, which `meta` keys the problem document carries — and, for a 5xx, whether its
+ * `cause` may be shown at all (`{ publicCause: true }`; hidden by default). Call it once at boot, in
  * the module that declares the codes — beside `registerErrorStatus`, and BOTH are needed: a code
  * with no declared status is an unclassified 5xx, and `toProblem` blanks everything but the code
  * and the request id on one of those, `meta` included.
@@ -66,12 +86,21 @@ const sameKeys = (left: readonly string[], right: readonly string[]): boolean =>
  * `X_RATE_LIMITED: ['key']` would publish the limiter's internal key on every 429.
  */
 export const registerProblemMeta = (
-  declarations: Readonly<Record<string, readonly string[]>>,
+  declarations: Readonly<Record<string, ProblemMetaDeclaration>>,
 ): void => {
-  for (const [code, keys] of Object.entries(declarations)) {
+  for (const [code, declaration] of Object.entries(declarations)) {
     if (frameworkOwns(code)) {
       throw problemMetaInvalid(code, 'the framework owns that code, and its meta is operator-only');
     }
+    const listed = Array.isArray(declaration);
+    const keys: readonly string[] = listed
+      ? declaration
+      : ((declaration as { keys?: readonly string[] }).keys ?? []);
+    const publicCause = !listed && (declaration as { publicCause?: boolean }).publicCause === true;
+    if (!listed && keys.length === 0 && publicCause) {
+      APP_PUBLIC_CAUSE.add(code);
+      continue;
+    }
     if (keys.length === 0) {
       throw problemMetaInvalid(code, 'the key list is empty — omit the code instead');
     }
@@ -93,11 +122,19 @@ export const registerProblemMeta = (
       throw problemMetaInvalid(code, `already declared as [${existing.join(', ')}] by this app`);
     }
     DECLARED.set(code, [...keys]);
+    if (publicCause) APP_PUBLIC_CAUSE.add(code);
   }
 };
 
 /** Test seam. Production registers once at boot and never unregisters. */
-export const resetProblemMeta = (): void => DECLARED.clear();
+export const resetProblemMeta = (): void => {
+  DECLARED.clear();
+  APP_PUBLIC_CAUSE.clear();
+};
+
+/** Whether a 5xx document for `code` may carry its authored `cause`. */
+export const hasPublicCause = (code: string): boolean =>
+  FRAMEWORK_PUBLIC_CAUSE.has(code) || APP_PUBLIC_CAUSE.has(code);
 
 /** The keys declared for a code, or `undefined` when nothing was — which is every framework code. */
 export const problemMetaKeysFor = (code: string): readonly string[] | undefined =>

package/src/request-services.ts

@@ -0,0 +1,65 @@
+// A request's registered services (`defineService`), bound to the actor that AUTHENTICATED. The
+// context exists before the `auth` stage names anyone, so core's constructor is told to install
+// nothing and every registered name becomes a lazy member here instead: built on first read, and
+// built again only if the actor, locale or time zone it closed over has since changed.
+
+import type { CtxFacts, ServiceBag } from '@ultimat3/core';
+import { installedServices, registeredServiceNames } from '@ultimat3/core';
+import type { RequestContext } from './context';
+
+interface Built {
+  readonly actor: CtxFacts['actor'];
+  readonly locale: string;
+  readonly tz: string;
+  readonly bag: ServiceBag;
+}
+
+/**
+ * Makes `ctx.services` and each registered `ctx.<name>` lazy. Non-enumerable, so building the
+ * preview a factory reads — the context's facts, no sibling service — never reads one back.
+ * An explicit service (`init.services`) stays what it was: a caller's mock overrides the real one.
+ */
+export function bindRequestServices(ctx: RequestContext, explicit: ServiceBag): void {
+  let built: Built | undefined;
+  const bag = (): ServiceBag => {
+    if (
+      built !== undefined &&
+      built.actor === ctx.actor &&
+      built.locale === ctx.locale &&
+      built.tz === ctx.tz
+    ) {
+      return built.bag;
+    }
+    const preview: CtxFacts = Object.freeze({
+      ...explicit,
+      requestId: ctx.requestId,
+      traceId: ctx.traceId,
+      actor: ctx.actor,
+      locale: ctx.locale,
+      tz: ctx.tz,
+      buildId: ctx.buildId,
+      role: ctx.role,
+      clock: ctx.clock,
+      now: ctx.now,
+      logger: ctx.logger,
+      signal: ctx.signal,
+      deadlineAt: ctx.deadlineAt,
+      services: explicit,
+    });
+    const next = Object.freeze({ ...installedServices(preview), ...explicit });
+    built = { actor: ctx.actor, locale: ctx.locale, tz: ctx.tz, bag: next };
+    return next;
+  };
+  Object.defineProperty(ctx, 'services', { get: bag, enumerable: false, configurable: true });
+  for (const name of registeredServiceNames()) {
+    // Already an own property: a framework field (which keeps its meaning whatever an app named a
+    // service — core's rule) or an explicit `init.services` entry, which core's constructor spread
+    // onto the context and which overrides the registered factory of the same name.
+    if (Object.hasOwn(ctx, name)) continue;
+    Object.defineProperty(ctx, name, {
+      get: () => bag()[name],
+      enumerable: false,
+      configurable: true,
+    });
+  }
+}

package/src/request.ts

@@ -167,7 +167,20 @@ export class UltimateRequest {
       throw bodyInvalid(this.pathname, [`body is ${declared} bytes, limit is ${limit}`]);
     }
     const type = contentTypeOf(this.raw);
-    if (type === '' || declared === 0) return undefined;
+    // An EMPTY form is a form with no fields, never "no input": a button-only `<form>` posts
+    // `content-length: 0`, and reading that as `undefined` failed every schema with 400.
+    const form = type === 'application/x-www-form-urlencoded' || type === 'multipart/form-data';
+    if (type === '') return undefined;
+    // A multipart body is only a FORM with the boundary its header must announce. Checked before
+    // the empty-form shortcut below, so a zero-length body cannot launder a malformed header into
+    // `{}` — without it the parser would have refused, and an empty body must refuse the same.
+    if (
+      type === 'multipart/form-data' &&
+      !/;\s*boundary=[^;\s]/i.test(this.header('content-type') ?? '')
+    ) {
+      throw bodyInvalid(this.pathname, ['multipart/form-data without a boundary parameter']);
+    }
+    if (declared === 0) return form ? {} : undefined;
 
     // One capped read for every content type, multipart included: the parser runs on bytes this
     // process already agreed to hold, never on a stream it hands to the runtime unbounded.
@@ -175,7 +188,7 @@ export class UltimateRequest {
     if ('over' in read) {
       throw bodyInvalid(this.pathname, [`body is at least ${read.over} bytes, limit is ${limit}`]);
     }
-    if (read.bytes.byteLength === 0) return undefined;
+    if (read.bytes.byteLength === 0) return form ? {} : undefined;
 
     if (type === 'multipart/form-data') {
       try {

package/src/response.ts

@@ -110,7 +110,7 @@ export interface CacheHint {
   /** Shared/CDN age. `isr` routes set this and rely on tag purges to revalidate. */
   readonly sMaxAgeSeconds?: number;
   readonly staleWhileRevalidateSeconds?: number;
-  /** Cache tags a purge can target; mirrored into `x-cache-tags`. */
+  /** Cache tags a purge can target, in wire form; emitted as `Surrogate-Key` and `Cache-Tag`. */
   readonly tags?: readonly string[];
   readonly vary?: readonly string[];
 }
@@ -207,8 +207,14 @@ export const SHARED_CACHE_VARY: readonly string[] = ['accept-language', 'cookie'
 /** Mutates the response headers in place — responses are per-request, never shared. */
 export const applyCacheHeaders = (response: Response, hint: CacheHint): Response => {
   response.headers.set('cache-control', cacheControl(hint));
-  if (hint.tags !== undefined && hint.tags.length > 0) {
-    response.headers.set('x-cache-tags', hint.tags.join(','));
+  // The two headers a CDN reads, and only on a response a CDN may hold: Fastly's `Surrogate-Key`
+  // (space-separated) and Cloudflare's `Cache-Tag` (comma-separated), the same wire forms
+  // `@ultimat3/cache`'s purge sends. This wrote `x-cache-tags`, which neither reads — so every
+  // purge by tag "succeeded" and cleared nothing.
+  const shared = hint.mode === 'public' || hint.mode === 'immutable';
+  if (shared && hint.tags !== undefined && hint.tags.length > 0) {
+    response.headers.set('surrogate-key', hint.tags.join(' '));
+    response.headers.set('cache-tag', hint.tags.join(','));
   }
   // `cookie` is not optional on the shared path. A `public` response is stored by a CDN under the
   // URL, and every session in this framework travels in a cookie — so without it the first

package/src/security-headers.ts

@@ -140,3 +140,32 @@ export const securityHeaders = (
   }
   return headers;
 };
+
+/** One frozen record per config object and scheme. Weak, so a discarded config is not retained. */
+const memo = new WeakMap<
+  SecurityConfig,
+  { https?: Readonly<Record<string, string>>; plain?: Readonly<Record<string, string>> }
+>();
+
+/**
+ * What the pipeline stamps on every response: `securityHeaders`, built ONCE per `(config, https)`.
+ * Rebuilding it per request re-joined the CSP and re-hashed `OVERLAY_STYLE` — 20.9 µs, 18.8% of a
+ * trivial GET — for an answer that cannot change while the server runs. Frozen, because every
+ * request shares it; `securityHeaders` stays the builder that hands a caller its own copy.
+ */
+export const responseSecurityHeaders = (
+  config: SecurityConfig,
+  https: boolean,
+): Readonly<Record<string, string>> => {
+  let entry = memo.get(config);
+  if (entry === undefined) {
+    entry = {};
+    memo.set(config, entry);
+  }
+  const slot = https ? 'https' : 'plain';
+  const cached = entry[slot];
+  if (cached !== undefined) return cached;
+  const built = Object.freeze(securityHeaders(config, { https }));
+  entry[slot] = built;
+  return built;
+};

package/src/server.ts

@@ -2,7 +2,7 @@
 // context, tracing and authz must be impossible to skip — a route is a data
 // declaration, never a chance to hand-roll a request handler.
 
-import type { HealthPayload, HealthState, Role } from '@ultimat3/core';
+import type { DrainConfig, HealthPayload, HealthState, Role } from '@ultimat3/core';
 import {
   beginWork,
   configureLifecycle,
@@ -82,6 +82,12 @@ export interface ServerOptions {
    * client picks whichever origin it can actually reach.
    */
   readonly websocket?: WebSocketMount;
+  /**
+   * `app.config.ts`'s `drain` section — pass `appConfig.drain`. Its `readinessGraceMs` is how long
+   * `/readyz` answers 503 before the `accept` phase closes this listener. Omitted, core's own
+   * default holds (0 in development/test, 5000 elsewhere) and an app's `configureLifecycle` stands.
+   */
+  readonly drain?: Partial<DrainConfig>;
 }
 
 /**
@@ -172,6 +178,10 @@ export const createServer = (options: ServerOptions): ServerHandle => {
   // own `fix:` prints — back to 15s on every boot that serves web, silently. "Nobody said" and
   // "the app said 15 seconds" are different claims and `null` is what keeps them apart.
   if (config.drainTimeoutMs !== null) configureLifecycle({ deadlineMs: config.drainTimeoutMs });
+  // Same rule: only a declared grace is applied. Core waits it out between the readiness flip and
+  // the `accept` hook below, so endpoints stop routing here before the socket closes.
+  const readinessGraceMs = options.drain?.readinessGraceMs;
+  if (readinessGraceMs !== undefined) configureLifecycle({ readinessGraceMs });
 
   const mount = options.websocket;
   let server: BunServer | undefined;
@@ -304,8 +314,9 @@ export const createServer = (options: ServerOptions): ServerHandle => {
       // so the test seal can let it through without an allowlist entry per random port.
       stopListening = markListening(server.url.origin);
 
-      // 'accept' runs first on SIGTERM: readyz flips to 503 here, while the socket is
-      // still open, so the load balancer stops sending new work before we close it.
+      // 'accept' runs first on SIGTERM, but only after core's readiness grace: readyz flips to
+      // 503 the moment the drain starts, the socket stays open for `readinessGraceMs`, so the
+      // endpoints controller stops routing here before this closes it — not a 502 in between.
       unregister = onShutdown(
         `http:${role}`,
         async () => {

package/src/stages.ts

@@ -9,21 +9,22 @@ import {
   inflightCount,
   isAnonymous,
   isDraining,
+  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 } from './cache-policy';
+import { defaultCache, offersSharedCache, PRIVATE_CACHE, reviewedHint } from './cache-policy';
 import { type HttpConfig, stripBasePath } from './config';
 import { actorView, elapsedMs, type RequestContext } from './context';
 import { corsHeaders, preflight } from './cors';
-import { checkCsrf, selfOrigin } from './csrf';
+import { checkCsrf, csrfBlocked, selfOrigin } from './csrf';
 import { factsOf, retryAfterOf } from './error-facts';
+import { errorLogLevel } from './error-log-level';
 import { errorPageResponse } from './error-page';
 import {
   bodyInvalid,
-  csrfBlocked,
   draining,
   forbidden,
   methodNotAllowed,
@@ -42,7 +43,7 @@ import { rateLimited } from './rate-limit-errors';
 import type { UltimateRequest } from './request';
 import { addVary, applyCacheHeaders, problem, redirect, SHARED_CACHE_VARY } from './response';
 import { matchRoute, type Route, type RouteHandler, type RouteTable } from './router';
-import { securityHeaders } from './security-headers';
+import { responseSecurityHeaders } from './security-headers';
 import { validate } from './validate';
 
 export type StageName =
@@ -134,10 +135,15 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       // Before the trace, the route match, auth, the body — everything. A refusal that costs as
       // much as a served request is not load shedding, and this is the stage that makes
       // "reject 40% fast, serve 60% at p99" expressible at all.
-      if (isDraining()) {
+      // DRAINING is served, never refused: a request reaching the pipeline mid-drain came in on
+      // a kept-alive connection or before the listener closed, and the readiness grace exists so
+      // it is answered. `connection: close` moves the client's NEXT request to another pod.
+      // Refusing it failed 598 of 7,690 requests in one helm upgrade (kind). Only STOPPED refuses.
+      if (lifecycleState() === 'stopped') {
         ctx.headers.set('retry-after', SHED_RETRY_AFTER_SECONDS);
         throw draining();
       }
+      if (isDraining()) ctx.headers.set('connection', 'close');
       const ceiling = config.maxInflight;
       // `beginWork()` in `server.ts` counted THIS request before the pipeline was entered, so the
       // ceiling is compared against a number that already includes it.
@@ -188,16 +194,7 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
      * get one answer in the framework rather than one per package.
      */
     locale: (request, ctx) => {
-      const cookies = request.header('cookie');
-      ctx.locale = resolveLocale({
-        header: request.header('accept-language'),
-        cookie: readCookie(cookies, config.locale.cookie),
-      }).locale;
-      ctx.tz = resolveTimeZone({
-        cookie: readCookie(cookies, config.tz.cookie),
-        header: request.header(config.tz.header),
-      }).zone;
-      ctx.headers.set('content-language', ctx.locale);
+      resolvePreferences(request, ctx, config);
       return undefined;
     },
 
@@ -206,6 +203,11 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
         // The hook says "anonymous" with null; the context says it with core's anonymous actor,
         // because `asCtx` publishes this object as a `Ctx` and `Ctx.actor` is never null.
         ctx.actor = (await hooks.authenticate(request, ctx)) ?? anonymousActor();
+        // The `user` rung the `locale` stage could not know: re-resolved through the same owners,
+        // so a cookie the reader chose still beats a saved locale where i18n's order says it does.
+        if (ctx.actor.locale !== undefined || ctx.actor.tz !== undefined) {
+          resolvePreferences(request, ctx, config);
+        }
       }
       if (ctx.route?.meta.auth === 'required' && isAnonymous(ctx.actor)) {
         throw unauthenticated(ctx.url.pathname);
@@ -272,7 +274,7 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
         cors: config.cors,
         config: config.csrf,
       });
-      if (!verdict.ok) throw csrfBlocked(ctx.url.pathname, verdict.reason);
+      if (!verdict.ok) throw csrfBlocked(ctx.url.pathname, verdict.reason, ctx.ip);
       return undefined;
     },
 
@@ -319,10 +321,8 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       if (response === undefined) return undefined;
       const declared = response.headers.get('cache-control');
       if (declared === null) {
-        applyCacheHeaders(
-          response,
-          ctx.cache ?? ctx.route?.meta.cache ?? defaultCache(ctx.route, ctx.actor),
-        );
+        const hint = ctx.cache ?? ctx.route?.meta.cache ?? defaultCache(ctx.route, ctx.actor);
+        applyCacheHeaders(response, reviewedHint(hint, ctx.actor));
         return undefined;
       }
       // A declaration is the MODE's intent, never the last word: `@ultimat3/render`'s `ssrHeaders`
@@ -368,7 +368,10 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       // The other half of this is `@ultimat3/schema`'s, and it is the load-bearing one: an issue
       // message must stop echoing the rejected value at all. This change makes the value
       // redactable; it does not make it absent.
-      ctx.logger.error(facts.code, { cause: facts.cause, status: facts.status });
+      ctx.logger[errorLogLevel(facts.status)](facts.code, {
+        cause: facts.cause,
+        status: facts.status,
+      });
       // Before the overlay and before the problem document: a browser with no session has not
       // hit a defect to debug, it has hit a login wall, and the answer to that is the sign-in
       // page. `signInPath` is null until an app declares one, so this is off by default.
@@ -455,7 +458,7 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
         else response.headers.set(name, value);
       }
       for (const [name, value] of Object.entries(
-        securityHeaders(config.security, { https: ctx.https }),
+        responseSecurityHeaders(config.security, ctx.https),
       )) {
         response.headers.set(name, value);
       }
@@ -465,3 +468,31 @@ 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);
+}