@ultimat3/http 22.9.1 → 22.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "22.9.1",
+  "version": "22.10.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.9.1",
-    "@ultimat3/i18n": "22.9.1",
-    "@ultimat3/schema": "22.9.1",
-    "@ultimat3/time": "22.9.1"
+    "@ultimat3/core": "22.10.0",
+    "@ultimat3/i18n": "22.10.0",
+    "@ultimat3/schema": "22.10.0",
+    "@ultimat3/time": "22.10.0"
   }
 }

package/src/error-facts.ts

@@ -21,6 +21,11 @@ export interface ErrorFacts {
   readonly title: string;
   readonly cause: string;
   readonly fix: string;
+  /**
+   * The remote caller's fix (`UltimateErrorInit.callerFix`), branded errors only — `fix`'s trust
+   * rule. A production problem document carries it in place of `fix`; the terminal never does.
+   */
+  readonly callerFix: string | undefined;
   readonly docs: string;
   readonly status: number;
   /** Present only when the process is in dev mode; never sent to a client in prod. */
@@ -88,6 +93,7 @@ export const factsOf = (error: unknown): ErrorFacts => {
       (FRAMEWORK_CODE.test(code)
         ? `x errors explain ${code} --json   # then fix the throwing call site`
         : 'x errors list --json   # then fix the throwing call site'),
+    callerFix: isUltimateError(error) ? str(error, 'callerFix') : undefined,
     // Core's one constant, never a per-code URL: `wiki/` is the only public documentation surface
     // and a code lives there in a table row, which has no anchor. An `UltimateError` already
     // resolved this at construction, so the fallback only fires for a throwable the framework did
@@ -322,7 +328,10 @@ export const toProblem = (
     instance: meta.instance,
     code: facts.code,
     cause: hidden ? INTERNAL_CAUSE : facts.cause,
-    fix: facts.fix,
+    // The CALLER's fix outside dev: a production client cannot run `x policy explain`, and the
+    // developer's line stays in the log this request wrote. Dev keeps the developer's, because the
+    // reader of a dev response is the developer.
+    fix: meta.dev === true ? facts.fix : (facts.callerFix ?? facts.fix),
     docs: facts.docs,
     requestId: meta.requestId,
     ...(issues === undefined ? {} : { issues }),

package/src/errors.ts

@@ -2,6 +2,7 @@
 // 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,
@@ -139,6 +140,8 @@ export class HttpError extends UltimateError {
     code: HttpErrorCode;
     cause: string;
     fix: string;
+    /** A remote caller's fix, when `fix` needs the app's CLI — `UltimateErrorInit.callerFix`. */
+    callerFix?: string;
     /**
      * Facts an operator needs and a CALLER must not be handed. `toProblem` renders code, cause,
      * fix and docs — never this — so the rate limiter's internal key rides here instead of in a
@@ -146,12 +149,7 @@ export class HttpError extends UltimateError {
      */
     meta?: Readonly<Record<string, unknown>>;
   }) {
-    super({
-      code: init.code,
-      cause: init.cause,
-      fix: init.fix,
-      ...(init.meta === undefined ? {} : { meta: init.meta }),
-    });
+    super({ ...init }); // an `UltimateErrorInit`: optional fields attached only when present
   }
 }
 
@@ -256,6 +254,9 @@ export const forbidden = (pathname: string, reason: string, policy?: string): Ht
       policy !== undefined && POLICY_SUBJECT.test(policy)
         ? `x policy explain ${policy} --json   # shows which clause denied`
         : `x routes --json   # find ${pathname}, then read the policy it declares`,
+    callerFix: deniedCallerFix(
+      policy !== undefined && POLICY_SUBJECT.test(policy) ? policy : undefined,
+    ),
   });
 
 export const buildSkew = (clientBuildId: string, serverBuildId: string): HttpError =>

package/src/locale-prefix.ts

@@ -57,6 +57,16 @@ export function requestLocale(ctx: RequestContext, sources: LocaleSources): stri
 export const localeFromPath = (ctx: RequestContext): boolean =>
   ctx.pathLocale !== undefined || ctx.route?.meta.localeSource === 'path';
 
+/**
+ * Whether `Accept-Language` can decide this response's locale — the one condition under which
+ * `Vary: accept-language` is true. Not when the URL names the locale (above), and not when the app's
+ * locale order leaves the header out (`configureLocales({ order: ['query', 'cookie', 'user'] })`):
+ * every renderer adds the dimension by default, and a CDN keying on a header nothing reads stores
+ * one copy of the page per browser language for nothing.
+ */
+export const acceptLanguageConsulted = (ctx: RequestContext): boolean =>
+  !localeFromPath(ctx) && localeConfig().order.includes('header');
+
 /** 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');

package/src/stages.ts

@@ -33,7 +33,7 @@ import {
 } from './errors';
 import type { ServerHooks } from './hooks';
 import { acceptsHtml } from './html-render';
-import { dropVary, localeFromPath, routeLocalePrefix } from './locale-prefix';
+import { acceptLanguageConsulted, dropVary, routeLocalePrefix } from './locale-prefix';
 import { compose, type Middleware } from './middleware';
 import { navigationGate, redirectForRouter } from './navigation';
 import { overlayResponse } from './overlay';
@@ -453,9 +453,10 @@ 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');
+      // After every contributor: a locale read off the URL — or an app whose locale order never
+      // reads the header — makes `accept-language` a key nothing varies on, and a CDN keying on it
+      // stores one copy per browser for nothing.
+      if (!acceptLanguageConsulted(ctx)) dropVary(response, 'accept-language');
       for (const [name, value] of Object.entries(
         responseSecurityHeaders(config.security, ctx.https),
       )) {