@ultimat3/http 23.0.0 → 25.0.0

package/src/error-page.ts

@@ -5,10 +5,9 @@
 //
 // An app overrides it with a file per status; `ServerHooks.errorPage` is the seam that reads one,
 // because this package cannot see a disk.
-import { singleLine } from '@ultimat3/core';
+import { escapeHtml, singleLine } from '@ultimat3/core';
 import type { InterpolationVars } from '@ultimat3/i18n';
 import { t } from '@ultimat3/i18n';
-import { escapeHtml } from './html-render';
 import { OVERLAY_STYLE } from './overlay-style';
 import { html } from './response';
 
@@ -166,11 +165,11 @@ export function renderErrorPage(input: ErrorPageInput): string {
     <p class="lede">${escapeHtml(t(`errors.${copy.group}.body`, copy.vars))}</p>
     <p>${link(hrefFor(copy, input), t(`errors.${copy.group}.action`))}</p>
     <dl>
-      <dt>code</dt><dd>${escapeHtml(singleLine(input.code))}</dd>${
+      <dt>${escapeHtml(t('errors.page.code'))}</dt><dd>${escapeHtml(singleLine(input.code))}</dd>${
         input.requestId === undefined
           ? ''
           : `
-      <dt>request</dt><dd>${escapeHtml(singleLine(input.requestId))}</dd>`
+      <dt>${escapeHtml(t('errors.page.request'))}</dt><dd>${escapeHtml(singleLine(input.requestId))}</dd>`
       }
     </dl>
   </section>

package/src/error-titles.ts

@@ -0,0 +1,93 @@
+// @ultimat3/http's owned codes, their TITLES and the two retry classes, registered at import — the
+// one module `sideEffects` names, imported bare by the barrel and by `errors.ts`. Its readers are
+// in the SERVER realm (`x errors list`, a problem document, a job's retry), which reaches the
+// barrel. A browser never needs it: core's decoders take an unregistered code's title from the
+// problem body and a 429's `retry-after` from its `Retry-After` header. Until the package declared
+// `sideEffects`, all of http — router, limiter, error maps, 11.5 kB — rode into every action island.
+
+import { registerErrorCodes, registerErrorRetry } from '@ultimat3/core';
+
+/** Codes this package declares and owns. */
+export const HTTP_OWNED_ERROR_CODES = [
+  'X_ROUTE_NOT_FOUND',
+  'X_METHOD_NOT_ALLOWED',
+  'X_PATH_INVALID',
+  'X_BODY_INVALID',
+  'X_RATE_LIMITED',
+  'X_BUILD_SKEW',
+  'X_ROUTE_CONFLICT',
+  'X_SERVER_NOT_STARTED',
+  'X_PIPELINE_NO_RESPONSE',
+  'X_PIPELINE_FINALIZE_FAILED',
+  'X_NO_REQUEST',
+  'X_ERROR_STATUS_INVALID',
+  'X_PROBLEM_META_INVALID',
+  'X_CORS_CONFIG_INVALID',
+  'X_CSP_DIRECTIVE_INVALID',
+  'X_RATE_LIMIT_NOT_SHARED',
+  'X_RATE_LIMIT_BUCKET_CONFLICT',
+  'X_RATE_LIMIT_BUCKET_UNBOUND',
+  'X_RATE_LIMIT_SCOPE_UNSET',
+  'X_RATE_LIMIT_INVALID',
+  'X_RATE_LIMIT_STORE_UNAVAILABLE',
+  'X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN',
+  'X_TRUST_PROXY_UNSET',
+  'X_OVERLOADED',
+  'X_CSRF_BLOCKED',
+  'X_WEBHOOK_SIGNATURE_INVALID',
+  'X_WEBHOOK_SIGNATURE_STALE',
+  'X_BEARER_MOUNT_INVALID',
+] as const;
+
+export type HttpOwnedErrorCode = (typeof HTTP_OWNED_ERROR_CODES)[number];
+
+/** Human title per owned code. Kept next to the codes so one edit updates every surface. */
+export const HTTP_ERROR_TITLES: Readonly<Record<HttpOwnedErrorCode, string>> = {
+  X_ROUTE_NOT_FOUND: 'no route matches this request',
+  X_METHOD_NOT_ALLOWED: 'route exists but not for this method',
+  X_PATH_INVALID: 'a path segment is not valid percent-encoding',
+  X_BODY_INVALID: 'request body failed its schema',
+  X_RATE_LIMITED: 'rate limit exhausted for this key',
+  X_BUILD_SKEW: 'client build id does not match the server build id',
+  X_ROUTE_CONFLICT: 'two routes claim the same path',
+  X_SERVER_NOT_STARTED: 'server handle used before start()',
+  X_PIPELINE_NO_RESPONSE: 'a pipeline stage produced no response',
+  X_PIPELINE_FINALIZE_FAILED: 'a finalize stage threw instead of finishing the response',
+  X_NO_REQUEST: 'the inbound request is not in scope here',
+  X_ERROR_STATUS_INVALID: 'an error code cannot be mapped to that status',
+  X_PROBLEM_META_INVALID: 'a problem document cannot carry that meta declaration',
+  X_CORS_CONFIG_INVALID: 'the cors config can never produce a working response',
+  X_CSP_DIRECTIVE_INVALID: 'a csp extension would emit something other than the directive it names',
+  X_RATE_LIMIT_NOT_SHARED: 'the rate limit is declared fleet-wide and the store is per-process',
+  X_RATE_LIMIT_BUCKET_CONFLICT: 'a route and the config declare different numbers for one bucket',
+  X_RATE_LIMIT_BUCKET_UNBOUND: 'the installed limiter cannot enforce a bucket a route declares',
+  X_RATE_LIMIT_SCOPE_UNSET: 'the deployment has not said where the rate limiter keeps its counters',
+  X_RATE_LIMIT_INVALID: 'a declared rate limit computes to numbers the limiter cannot run on',
+  X_RATE_LIMIT_STORE_UNAVAILABLE: 'the shared rate-limit store did not answer, so nothing decided',
+  X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN: 'the tenant allowance names a bucket nothing declares',
+  X_TRUST_PROXY_UNSET: 'proxy headers are trusted without saying how many proxies are in front',
+  X_OVERLOADED: 'in-flight requests are at the configured ceiling',
+  X_CSRF_BLOCKED: 'an unsafe request that did not prove same-origin',
+  X_WEBHOOK_SIGNATURE_INVALID: 'the inbound webhook is not signed by the holder of this secret',
+  X_WEBHOOK_SIGNATURE_STALE: 'the inbound webhook is signed correctly and is too old to accept',
+  X_BEARER_MOUNT_INVALID: 'a bearer mount declaration cannot be served as written',
+};
+
+// Registered at module load, unconditionally, in one call, so core's registry renders OUR title
+// everywhere. Without this the registry humanises the code (`X_BUILD_SKEW` → "build skew"); with a
+// presence guard, a package that claimed one of these first would silently keep its own title.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(HTTP_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+/**
+ * The two codes this package throws that a client is SUPPOSED to come back from, and both say
+ * when: each carries `retry-after` on the response. Unclassified defaults to `terminal`, which is
+ * right for the rest — a 404, a 422 and a wiring bug all fail the same way forever — but wrong for
+ * a shed request, whose whole contract is "not now". Only codes this package OWNS are listed:
+ * `X_TIMEOUT` and `X_DRAINING` are borrowed, and core classifies its own.
+ */
+registerErrorRetry({
+  X_RATE_LIMITED: 'retry-after',
+  X_OVERLOADED: 'retry-after',
+});

package/src/errors.ts

@@ -1,46 +1,18 @@
 // The HTTP layer's stable error codes. Every throw in this package goes through a
 // factory here so a code, a cause and an exact fix always travel together — the
 // terminal, the dev overlay and `--json` all render the same three strings.
-import {
-  deniedCallerFix,
-  registerErrorCodes,
-  registerErrorRetry,
-  renderFixShellArg,
-  renderThrowable,
-  UltimateError,
-} from '@ultimat3/core';
-
-/** Codes this package declares and owns. */
-export const HTTP_OWNED_ERROR_CODES = [
-  'X_ROUTE_NOT_FOUND',
-  'X_METHOD_NOT_ALLOWED',
-  'X_PATH_INVALID',
-  'X_BODY_INVALID',
-  'X_RATE_LIMITED',
-  'X_BUILD_SKEW',
-  'X_ROUTE_CONFLICT',
-  'X_SERVER_NOT_STARTED',
-  'X_PIPELINE_NO_RESPONSE',
-  'X_PIPELINE_FINALIZE_FAILED',
-  'X_NO_REQUEST',
-  'X_ERROR_STATUS_INVALID',
-  'X_PROBLEM_META_INVALID',
-  'X_CORS_CONFIG_INVALID',
-  'X_CSP_DIRECTIVE_INVALID',
-  'X_RATE_LIMIT_NOT_SHARED',
-  'X_RATE_LIMIT_BUCKET_CONFLICT',
-  'X_RATE_LIMIT_BUCKET_UNBOUND',
-  'X_RATE_LIMIT_SCOPE_UNSET',
-  'X_RATE_LIMIT_INVALID',
-  'X_RATE_LIMIT_STORE_UNAVAILABLE',
-  'X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN',
-  'X_TRUST_PROXY_UNSET',
-  'X_OVERLOADED',
-  'X_CSRF_BLOCKED',
-  'X_WEBHOOK_SIGNATURE_INVALID',
-  'X_WEBHOOK_SIGNATURE_STALE',
-  'X_BEARER_MOUNT_INVALID',
-] as const;
+import { deniedCallerFix, renderFixShellArg, renderThrowable, UltimateError } from '@ultimat3/core';
+// The owned code list, its titles and its retry classes are `error-titles.ts` — the one module
+// `sideEffects` lists, imported bare here and from the barrel — so this module is side-effect-free
+// and a chunk keeps only the classes it constructs. Re-exported: every name still reads from here.
+import './error-titles';
+import { HTTP_OWNED_ERROR_CODES } from './error-titles';
+
+export {
+  HTTP_ERROR_TITLES,
+  HTTP_OWNED_ERROR_CODES,
+  type HttpOwnedErrorCode,
+} from './error-titles';
 
 /**
  * Codes this package throws but does NOT own. `X_FORBIDDEN` belongs to `@ultimat3/policy` and
@@ -71,60 +43,8 @@ export const HTTP_BORROWED_ERROR_CODES = [
 /** Every code http can throw: the ones it owns plus the two it borrows. */
 export const HTTP_ERROR_CODES = [...HTTP_OWNED_ERROR_CODES, ...HTTP_BORROWED_ERROR_CODES] as const;
 
-export type HttpOwnedErrorCode = (typeof HTTP_OWNED_ERROR_CODES)[number];
 export type HttpErrorCode = (typeof HTTP_ERROR_CODES)[number];
 
-/** Human title per owned code. Kept next to the codes so one edit updates every surface. */
-export const HTTP_ERROR_TITLES: Readonly<Record<HttpOwnedErrorCode, string>> = {
-  X_ROUTE_NOT_FOUND: 'no route matches this request',
-  X_METHOD_NOT_ALLOWED: 'route exists but not for this method',
-  X_PATH_INVALID: 'a path segment is not valid percent-encoding',
-  X_BODY_INVALID: 'request body failed its schema',
-  X_RATE_LIMITED: 'rate limit exhausted for this key',
-  X_BUILD_SKEW: 'client build id does not match the server build id',
-  X_ROUTE_CONFLICT: 'two routes claim the same path',
-  X_SERVER_NOT_STARTED: 'server handle used before start()',
-  X_PIPELINE_NO_RESPONSE: 'a pipeline stage produced no response',
-  X_PIPELINE_FINALIZE_FAILED: 'a finalize stage threw instead of finishing the response',
-  X_NO_REQUEST: 'the inbound request is not in scope here',
-  X_ERROR_STATUS_INVALID: 'an error code cannot be mapped to that status',
-  X_PROBLEM_META_INVALID: 'a problem document cannot carry that meta declaration',
-  X_CORS_CONFIG_INVALID: 'the cors config can never produce a working response',
-  X_CSP_DIRECTIVE_INVALID: 'a csp extension would emit something other than the directive it names',
-  X_RATE_LIMIT_NOT_SHARED: 'the rate limit is declared fleet-wide and the store is per-process',
-  X_RATE_LIMIT_BUCKET_CONFLICT: 'a route and the config declare different numbers for one bucket',
-  X_RATE_LIMIT_BUCKET_UNBOUND: 'the installed limiter cannot enforce a bucket a route declares',
-  X_RATE_LIMIT_SCOPE_UNSET: 'the deployment has not said where the rate limiter keeps its counters',
-  X_RATE_LIMIT_INVALID: 'a declared rate limit computes to numbers the limiter cannot run on',
-  X_RATE_LIMIT_STORE_UNAVAILABLE: 'the shared rate-limit store did not answer, so nothing decided',
-  X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN: 'the tenant allowance names a bucket nothing declares',
-  X_TRUST_PROXY_UNSET: 'proxy headers are trusted without saying how many proxies are in front',
-  X_OVERLOADED: 'in-flight requests are at the configured ceiling',
-  X_CSRF_BLOCKED: 'a credentialed write arrived from an origin that is not allowed to make it',
-  X_WEBHOOK_SIGNATURE_INVALID: 'the inbound webhook is not signed by the holder of this secret',
-  X_WEBHOOK_SIGNATURE_STALE: 'the inbound webhook is signed correctly and is too old to accept',
-  X_BEARER_MOUNT_INVALID: 'a bearer mount declaration cannot be served as written',
-};
-
-// Registered at module load, unconditionally, in one call, so core's registry renders OUR title
-// everywhere. Without this the registry humanises the code (`X_BUILD_SKEW` → "build skew"); with a
-// presence guard, a package that claimed one of these first would silently keep its own title.
-registerErrorCodes(
-  Object.fromEntries(Object.entries(HTTP_ERROR_TITLES).map(([code, title]) => [code, { title }])),
-);
-
-/**
- * The two codes this package throws that a client is SUPPOSED to come back from, and both say
- * when: each carries `retry-after` on the response. Unclassified defaults to `terminal`, which is
- * right for the rest — a 404, a 422 and a wiring bug all fail the same way forever — but wrong for
- * a shed request, whose whole contract is "not now". Only codes this package OWNS are listed:
- * `X_TIMEOUT` and `X_DRAINING` are borrowed, and core classifies its own.
- */
-registerErrorRetry({
-  X_RATE_LIMITED: 'retry-after',
-  X_OVERLOADED: 'retry-after',
-});
-
 // No `docs:` below. `UltimateError` fills it from `describeErrorCode(code).docs`, which is
 // `@ultimat3/core`'s `ERROR_DOCS_URL` — one page for every code, never one per code, because
 // `wiki/` is the framework's only public documentation surface and a code lives there in a TABLE
@@ -166,7 +86,7 @@ export const routeNotFound = (method: string, pathname: string): HttpError =>
     code: 'X_ROUTE_NOT_FOUND',
     // The value itself still travels, in the field that is read rather than run.
     cause: `no route registered for ${method} ${pathname}`,
-    fix: `x routes list --json   # then: x g route ${renderFixShellArg(pathname, '<the path the cause names>')}`,
+    fix: `x routes --json   # then: x g route ${renderFixShellArg(pathname, '<the path the cause names>')}`,
   });
 
 export const methodNotAllowed = (
@@ -274,7 +194,7 @@ export const serverNotStarted = (member: string): HttpError =>
   new HttpError({
     code: 'X_SERVER_NOT_STARTED',
     cause: `${member} was read before start() bound a socket`,
-    fix: 'call createServer({ ... }).start() before reading url()',
+    fix: 'call httpServer({ ... }).start() before reading url()',
   });
 
 export const pipelineNoResponse = (stage: string): HttpError =>
@@ -297,7 +217,7 @@ export const finalizeFailed = (stage: string, cause: unknown): HttpError =>
     // runs a `Proxy`'s `getPrototypeOf` trap and `.message` runs a getter, so both reads go
     // through core's total `renderThrowable` — the fast path was the last unguarded one here.
     cause: `the "${stage}" stage threw while finishing the response: ${renderThrowable(cause)}`,
-    fix: 'return a Response built here — json(), text(), html() or redirect() from @ultimat3/http; one whose headers cannot be set, like Response.redirect(), cannot take the final headers',
+    fix: 'return a Response built here — jsonResponse(), textResponse(), html() or redirect() from @ultimat3/http; one whose headers cannot be set, like Response.redirect(), cannot take the final headers',
   });
 
 /**
@@ -361,7 +281,7 @@ export const routeConflict = (path: string, detail: string): HttpError =>
   new HttpError({
     code: 'X_ROUTE_CONFLICT',
     cause: `${path} conflicts with an already registered route: ${detail}`,
-    fix: `x routes list --json   # remove or rename one of the two routes at ${path}`,
+    fix: `x routes --json   # remove or rename one of the two routes at ${path}`,
   });
 
 /**
@@ -379,6 +299,36 @@ export const trustProxyUnset = (): HttpError =>
     fix: 'set TRUSTED_PROXY_HOPS in the deployment environment to the number of proxies that append to x-forwarded-for — 1 for a single ingress or ALB, 2 for a CDN in front of one — and leave it unset for a process that is reached directly; an embedder calling defineHttpConfig itself passes { trustProxy: true, trustedProxyHops: 1 }',
   });
 
+/**
+ * `http.drainTimeoutMs`, deleted in 25.0.0. It was a second knob for the budget `drain.deadlineMs`
+ * owns: applied after `lifecycleForRole` on the web role only, so the web role and every other
+ * role could drain on different budgets from one app config. Refused by key PRESENCE — a JS caller
+ * or a spread still handing it over gets the edit, never a silently ignored number.
+ */
+export const drainTimeoutDeleted = (): HttpError =>
+  new HttpError({
+    code: 'X_CONFIG_INVALID',
+    cause:
+      'http.drainTimeoutMs was deleted in 25.0.0: drain.deadlineMs is the one drain budget, for every role, and a second key for the web role alone is two answers to how long SIGTERM waits',
+    fix: 'drain: { deadlineMs: 25_000 }   # in app.config.ts: drain.deadlineMs is the one budget every role, web included, drains on — and delete drainTimeoutMs from configureHttp({ … })',
+    meta: { option: 'drainTimeoutMs', replacement: 'drain.deadlineMs' },
+  });
+
+/**
+ * `http.buildIdHeader`, deleted in 25.0.0. The pipeline read the client's build claim from it and
+ * stamped its own back under it, while the typed client, the service worker and `DEFAULT_CORS`
+ * all spelled core's `BUILD_ID_HEADER` — so a renamed header was a server listening for a header
+ * no client of it sent, and skew detection off in silence. Refused by key PRESENCE.
+ */
+export const buildIdHeaderDeleted = (): HttpError =>
+  new HttpError({
+    code: 'X_CONFIG_INVALID',
+    cause:
+      'http.buildIdHeader was deleted in 25.0.0: the build-id header is core BUILD_ID_HEADER (x-ultimate-build), which every client sends, and a renamed one is a header no client of this server sends',
+    fix: "import { BUILD_ID_HEADER } from '@ultimat3/core'   # the one build-id header, not configurable — and delete buildIdHeader from configureHttp({ … })",
+    meta: { option: 'buildIdHeader', replacement: 'BUILD_ID_HEADER' },
+  });
+
 /**
  * A numeric knob that is not a count, refused where `app.config.ts` still names it.
  *

package/src/forwarded.ts

@@ -43,10 +43,25 @@ export const forwardedElement = (
   return list[index];
 };
 
-/** The plain-list form: `x-forwarded-for`, `x-forwarded-proto`. */
+/** The plain-list form: `x-forwarded-for`. */
 export const forwardedValue = (header: string | null, hops: number): string | undefined =>
   forwardedElement(header, hops);
 
+/**
+ * `x-forwarded-proto`, which proxies OVERWRITE far more often than they append (nginx's `$scheme`,
+ * an ALB, Traefik): behind two hops it holds one value while `x-forwarded-for` holds two. A full
+ * chain is read exactly like an address. A SHORTER one is not a forgery here: an overwrite erased
+ * everything client-ward of it, so every entry left was written by a trusted hop, and the
+ * outermost of them — index 0 — is the one that saw the client's leg. A client value survives only
+ * when no trusted hop writes the header at all, the same exposure `hops: 1` has always had.
+ */
+export const forwardedProto = (header: string | null, hops: number): string | undefined => {
+  if (header === null || hops < 1) return undefined;
+  const list = plainSplit(header, ',');
+  if (list.length === 0) return undefined;
+  return list[Math.max(0, list.length - hops)];
+};
+
 /**
  * `1.2.3.4:5678` and `[::1]:443` are both legal in an `x-forwarded-for` entry; the port is the
  * proxy's bookkeeping and would make every connection its own rate-limit bucket.
@@ -71,21 +86,32 @@ export interface ForwardedInput {
   readonly urlProtocol: string;
 }
 
-/** The address the rate limiter keys on and the audit trail records. */
-export const clientAddress = (input: ForwardedInput): string | null => {
-  const forwarded = forwardedValue(input.headers.get(FORWARDED_FOR), input.config.trustedProxyHops);
-  if (forwarded === undefined) return input.socketAddress;
+/**
+ * The caller a DECLARED proxy named, or `undefined` when none did — an undeclared deployment, no
+ * header, a chain shorter than the declaration. Split out for the one reader that must tell "the
+ * proxy named nobody" from "the socket is the caller" (`health-disclosure.ts`).
+ */
+export const forwardedClientAddress = (
+  headers: Headers,
+  config: HttpConfig,
+): string | undefined => {
+  const forwarded = forwardedValue(headers.get(FORWARDED_FOR), config.trustedProxyHops);
+  if (forwarded === undefined) return undefined;
   const address = withoutPort(forwarded);
-  return address.length > 0 ? address : input.socketAddress;
+  return address.length > 0 ? address : undefined;
 };
 
+/** The address the rate limiter keys on and the audit trail records. */
+export const clientAddress = (input: ForwardedInput): string | null =>
+  forwardedClientAddress(input.headers, input.config) ?? input.socketAddress;
+
 /**
- * Whether the CLIENT's leg of the connection was TLS. Read at the same hop index as the address,
- * because `x-forwarded-proto` is as forgeable as `x-forwarded-for` — and this one decides whether
- * a two-year `includeSubDomains` HSTS policy goes out.
+ * Whether the CLIENT's leg of the connection was TLS. Hop-indexed like the address, because
+ * `x-forwarded-proto` is as forgeable as `x-forwarded-for` — and this one decides whether a
+ * two-year `includeSubDomains` HSTS policy goes out. `forwardedProto` says why a short list counts.
  */
 export const clientUsedHttps = (input: ForwardedInput): boolean => {
-  const forwarded = forwardedValue(
+  const forwarded = forwardedProto(
     input.headers.get(FORWARDED_PROTO),
     input.config.trustedProxyHops,
   );

package/src/health-disclosure.ts

@@ -0,0 +1,66 @@
+// Who `/healthz` and `/readyz` tell the detail to on the WEB role: the `healthDetailPeers` config
+// key, its screen, and the trusted-proxy half. The body rule and the peer-list match are core's
+// (`health-disclosure.ts` there), shared with the sync role's own listener — one rule, two callers.
+
+import {
+  type AddressClass,
+  classifyAddress,
+  healthPeerListed,
+  renderCauseValue,
+} from '@ultimat3/core';
+import type { HttpConfig } from './config';
+import { HttpError } from './errors';
+import { forwardedClientAddress } from './forwarded';
+
+/** Every class an entry may name. A `Record` so a class core adds is a build error here. */
+const ADDRESS_CLASSES = Object.freeze<Record<AddressClass, true>>({
+  loopback: true,
+  private: true,
+  'link-local': true,
+  ula: true,
+  cgnat: true,
+  unspecified: true,
+  reserved: true,
+  public: true,
+});
+
+const isAddressClass = (entry: string): entry is AddressClass =>
+  Object.hasOwn(ADDRESS_CLASSES, entry);
+
+/** Beside its one caller: `errors.ts` is at the 500-line ceiling (`server.ts` does the same). */
+const healthDetailPeersInvalid = (value: unknown): HttpError =>
+  new HttpError({
+    code: 'X_CONFIG_INVALID',
+    cause: `http.healthDetailPeers holds ${renderCauseValue(value)}; it must be a list whose every entry is an address class (${Object.keys(ADDRESS_CLASSES).join(', ')}) or one IP address literal — a range, a hostname or a misspelt class would match nobody, and the health endpoints would silently withhold from the peer it was written for`,
+    fix: "configureHttp({ healthDetailPeers: ['loopback', 'private'] })",
+  });
+
+/** The declared list, or the refusal naming the entry no address can ever match. */
+export const assertHealthDetailPeers = (peers: readonly string[]): readonly string[] => {
+  const declared: unknown = peers;
+  if (!Array.isArray(declared)) throw healthDetailPeersInvalid(declared);
+  for (const entry of declared as readonly unknown[]) {
+    if (typeof entry !== 'string') throw healthDetailPeersInvalid(entry);
+    if (!isAddressClass(entry) && classifyAddress(entry) === undefined) {
+      throw healthDetailPeersInvalid(entry);
+    }
+  }
+  return [...(declared as readonly string[])];
+};
+
+/**
+ * Whether this caller is told the detail. The SOCKET must be listed — and, when a declared proxy
+ * named a caller, that caller too: a proxy on this box makes every socket loopback, and a direct
+ * caller forging `x-forwarded-for` still arrives on a socket nobody listed. Undeclared, the
+ * header is not read at all.
+ */
+export const disclosesHealthDetail = (input: {
+  readonly config: HttpConfig;
+  readonly headers: Headers;
+  readonly socketAddress: string | null;
+}): boolean => {
+  const peers = input.config.healthDetailPeers;
+  if (!healthPeerListed(peers, input.socketAddress)) return false;
+  const forwarded = forwardedClientAddress(input.headers, input.config);
+  return forwarded === undefined || healthPeerListed(peers, forwarded);
+};

package/src/hooks.ts

@@ -40,12 +40,13 @@ export interface ServerHooks {
   /**
    * The app's OWN error page for a status, served byte for byte, or `undefined` to render the
    * framework's. A seam and not a config value because the answer lives on a disk this package
-   * cannot see: `@ultimat3/cli` reads `apps/web/site/errors/<status>.html`, per request, so a file
-   * dropped into a running server takes effect without a restart — the rule `/favicon.ico`
-   * already follows for the same class of file.
+   * cannot see: `@ultimat3/cli` reads `apps/web/site/errors/<status>.html` — per request under
+   * `x dev`, so a file dropped into a running server takes effect without a restart (the rule
+   * `/favicon.ico` already follows), and once per status in a container.
    *
-   * Consulted only on the production HTML path: a dev process answers a browser with the overlay,
-   * and an agent gets the problem document in both.
+   * Asked on the HTML path only — an agent gets the problem document in both environments. In
+   * production for every status; in dev for a 4xx alone (the page a visitor will see), with the
+   * overlay when it answers `undefined`. A dev 5xx is always the overlay and never asks.
    */
   readonly errorPage?: (
     status: number,

package/src/html-render.ts

@@ -1,20 +1,6 @@
-// The two questions every HTML answer this package renders has to ask, in one place: is the caller
-// a browser, and how does a value become markup. Both were the dev overlay's private helpers while
-// the production error page needs the identical answers — a second accept sniff would let a client
-// get the overlay in dev and JSON in production, and a second escape set is one hole away.
-
-/**
- * `'` is escaped even though every attribute the renderers write is double-quoted: the escape set
- * is what the next author reads as the guarantee, and a single-quoted attribute written later
- * would inherit a hole nothing here would have flagged.
- */
-export const escapeHtml = (value: string): string =>
-  value
-    .replaceAll('&', '&')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll("'", '&#39;');
+// Is the caller a browser? One sniff for every HTML answer this package renders — the dev overlay
+// and the production error page need the identical answer, and a second sniff would let a client
+// get the overlay in dev and JSON in production. How a value becomes markup is core's `escapeHtml`.
 
 /**
  * Does this caller render HTML? One sniff, three readers — the dev overlay, the production error

package/src/index.ts

@@ -1,17 +1,16 @@
 // The public surface of @ultimat3/http. Explicit, never `export *`: what is not
 // listed here is an implementation detail and may change without a major bump.
 
-export type { RenderMode } from '@ultimat3/core';
-// The wire format is `@ultimat3/core`'s and is RE-EXPORTED, never re-declared: it is one module at
-// the tier both halves can reach, because `@ultimat3/jobs` signs a delivery, this package verifies
-// one, and neither may import the other. Re-exported here so a receiver route needs one import.
-export {
-  isCanonicalWebhookField,
-  WEBHOOK_ID_HEADER,
-  WEBHOOK_SIGNATURE_HEADER,
-  WEBHOOK_SIGNATURE_VERSION,
-  WEBHOOK_TOPIC_HEADER,
-} from '@ultimat3/core';
+// Imported bare, and the one module `sideEffects` lists: the codes' titles and the `retry-after`
+// class of a 429 and a 503 are read by `UltimateError`, which never imports this module — so a
+// server realm that reaches the barrel registers them whatever it constructs. `SIDE_EFFECTS_ANCHORS`
+// carries the argument and `bun run side-effects` enforces it.
+import './error-titles';
+
+export type { PgExecutor, RenderMode } from '@ultimat3/core';
+// No core VALUE is re-exported here (`X_HELPER_COPY`, `bun run flight-copies`): the webhook wire
+// format (`WEBHOOK_*`, `isCanonicalWebhookField`), `escapeHtml` and `readCookie` are imported from
+// `@ultimat3/core`, their one home, by every caller.
 export type { AppHttpConfig, BootOwnedHttpKey } from './app-config';
 export { configuredHttp, configureHttp, mergeHttpConfig, resetHttpConfig } from './app-config';
 export { NEXT_PARAM, nextAfterSignIn, signInRedirect } from './auth-redirect';
@@ -28,8 +27,8 @@ export type { ActorView, RequestContext, RequestContextInit } from './context';
 export {
   actorView,
   asCtx,
-  createRequestContext,
   elapsedMs,
+  requestContext,
   useRequestBodyBytes,
   useRequestContext,
   useRequestCookie,
@@ -42,7 +41,7 @@ export { allowedOrigin, corsHeaders, DEFAULT_CORS, originListed, preflight } fro
 export type { CsrfCheckInput, CsrfConfig, CsrfMode, CsrfVerdict } from './csrf';
 export { checkCsrf, csrfBlocked, selfOrigin } from './csrf';
 export type { Deadline } from './deadline';
-export { REQUEST_TIMEOUT_HEADER, resolveTimeoutMs, startDeadline } from './deadline';
+export { resolveTimeoutMs, startDeadline } from './deadline';
 export type { ErrorFacts, ProblemDocument } from './error-facts';
 export {
   factsOf,
@@ -105,9 +104,8 @@ export {
 } from './forwarded';
 export type { Authenticator, AuthzDecision, ServerHooks } from './hooks';
 export { configureAuthenticator, configuredAuthenticator, resetAuthenticator } from './hooks';
-export { escapeHtml } from './html-render';
 export type { LocaleConfig, TimeZoneConfig } from './locale';
-export { DEFAULT_LOCALE_CONFIG, readCookie } from './locale';
+export { DEFAULT_LOCALE_CONFIG } from './locale';
 export type { Middleware } from './middleware';
 export { compose } from './middleware';
 export type { NavigationPurpose } from './navigation';
@@ -124,7 +122,7 @@ export { OVERLAY_STYLE } from './overlay-style';
 export type { PeerIdentity } from './peer-identity';
 export { peerIdentity } from './peer-identity';
 export type { HandleInit, Pipeline, PipelineDeps } from './pipeline';
-export { createPipeline, PIPELINE_STAGES } from './pipeline';
+export { httpPipeline, PIPELINE_STAGES } from './pipeline';
 export type { ProblemMeta, ProblemMetaDeclaration, ProblemMetaValue } from './problem-meta';
 export { MAX_PROBLEM_META_BYTES, registerProblemMeta } from './problem-meta';
 export type {
@@ -141,11 +139,11 @@ export type {
 } from './rate-limit';
 export {
   assertRateLimitScope,
-  createRateLimiter,
   DEFAULT_MAX_RATE_LIMIT_KEYS,
   DEFAULT_RATE_LIMIT,
   memoryRateLimitStore,
   rateLimitDecision,
+  rateLimiter,
   rateLimitSpends,
   resolveRateLimitConfig,
   toBucket,
@@ -161,11 +159,18 @@ export {
   rateLimitStoreUnavailable,
   tenantBucketUnknown,
 } from './rate-limit-errors';
-export type {
-  PgExecutor,
-  PostgresRateLimitStore,
-  PostgresRateLimitStoreOptions,
-} from './rate-limit-postgres';
+export { publishRateLimit, rateLimitHeaders } from './rate-limit-headers';
+export type { AdoptRateLimitStoreOptions } from './rate-limit-installed';
+export {
+  adoptRateLimitStore,
+  assertInstalledRateLimitScope,
+  installedRateLimitStore,
+  installRateLimitStore,
+  resetRateLimitStore,
+} from './rate-limit-installed';
+export type { RateLimitPeek } from './rate-limit-peek';
+export { rateLimitPeek, refilledTokens } from './rate-limit-peek';
+export type { PostgresRateLimitStore, PostgresRateLimitStoreOptions } from './rate-limit-postgres';
 export {
   postgresRateLimitStore,
   SQL_RATE_LIMIT_TABLE,
@@ -173,18 +178,20 @@ export {
 export { setRedirect, takeRedirect } from './redirect';
 export type { QueryValues } from './request';
 export { UltimateRequest } from './request';
+export type { RequestFacts, RequestFactsInput } from './request-facts';
+export { requestFacts } from './request-facts';
 export type { CacheHint, RedirectIntent, RedirectStatus } from './response';
 export {
   applyCacheHeaders,
   cacheControl,
   html,
-  json,
+  jsonResponse,
   NO_STORE,
   noContent,
   problem,
   redirect,
   stream,
-  text,
+  textResponse,
   withHeaders,
 } from './response';
 export type {
@@ -199,9 +206,9 @@ export type {
   RouteTable,
 } from './router';
 export {
-  createRouter,
   describeRoutes,
   HTTP_METHODS,
+  httpRouter,
   matchRoute,
 } from './router';
 export type { SecurityConfig } from './security-headers';
@@ -213,12 +220,14 @@ export type {
   UpgradeTarget,
   WebSocketMount,
 } from './server';
-export { createServer } from './server';
+export { httpServer } from './server';
+export type { DeleteCookieOptions } from './set-cookie';
+export { deleteCookie, setCookie } from './set-cookie';
 // The stage vocabulary comes from its declaration site, beside the fourteen implementations it
 // names; `PIPELINE_STAGES` — the ORDER — stays `pipeline.ts`'s.
 export type { Stage, StageDoc, StageName, StagePhase, StageRun } from './stages';
 export type { InferOutput, Schema, ValidationOutcome } from './validate';
-export { formatIssue, validate, validateSync } from './validate';
+export { formatIssue, validateBody, validateSync } from './validate';
 export type { VerifiedWebhook, WebhookVerifyOptions } from './webhook-verify';
 export {
   DEFAULT_WEBHOOK_BODY_LIMIT,