@ultimat3/http 22.6.2 → 22.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "22.6.2",
+  "version": "22.7.1",
   "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.6.2",
-    "@ultimat3/i18n": "22.6.2",
-    "@ultimat3/schema": "22.6.2",
-    "@ultimat3/time": "22.6.2"
+    "@ultimat3/core": "22.7.1",
+    "@ultimat3/i18n": "22.7.1",
+    "@ultimat3/schema": "22.7.1",
+    "@ultimat3/time": "22.7.1"
   }
 }

package/src/cache-policy.ts

@@ -49,3 +49,16 @@ export const defaultCache = (route: Route | undefined, actor: Actor): CacheHint
  */
 export const reviewedHint = (hint: CacheHint, actor: Actor): CacheHint =>
   hint.mode === 'public' && !isAnonymous(actor) ? PRIVATE_CACHE : hint;
+
+const REPLAYABLE_METHODS: ReadonlySet<string> = new Set(['GET', 'HEAD']);
+
+/**
+ * Whether a shared cache could ever replay this EXCHANGE to someone else. Only a safe method's
+ * answer can be (a CDN keys on the URL, and a POST's answer is a function of its body), and never
+ * a 4xx/5xx: a `401` + `WWW-Authenticate` is a challenge to THIS caller, an RFC 6749 §5.1 error
+ * must be `no-store`, and the next request may well succeed. The route default and a declared
+ * shared offer were both decided without the method or the status, so an anonymous `POST /mcp`
+ * refused `401` went out `public, s-maxage=60, stale-while-revalidate=600`.
+ */
+export const replayableExchange = (method: string, status: number): boolean =>
+  REPLAYABLE_METHODS.has(method.toUpperCase()) && status < 400;

package/src/cache-stage.ts

@@ -0,0 +1,47 @@
+// Single responsibility: the `cache-headers` stage's final answer — the one owner of what a
+// response may be cached as. Split out of `stages.ts` when the exchange rule (method + status)
+// joined the route default, the declared hint and the review of a handler's own header.
+
+import { isAnonymous } from '@ultimat3/core';
+import {
+  defaultCache,
+  offersSharedCache,
+  PRIVATE_CACHE,
+  replayableExchange,
+  reviewedHint,
+} from './cache-policy';
+import type { RequestContext } from './context';
+import { addVary, applyCacheHeaders, NO_STORE, SHARED_CACHE_VARY } from './response';
+
+export const finalizeCacheHeaders = (response: Response, ctx: RequestContext): void => {
+  const declared = response.headers.get('cache-control');
+  // The EXCHANGE first, before any hint or declaration: a POST's answer or a refusal is never
+  // a shared cache's to replay, whatever the route or the handler offered (`replayableExchange`).
+  // `pragma: no-cache` beside it is RFC 6749 §5.1's pair for a token endpoint's answer, and
+  // costs nothing anywhere else. Only an OFFER is overruled — a handler's own `private` or
+  // `no-store` already says less than this would.
+  if (!replayableExchange(ctx.method, response.status)) {
+    if (declared === null || offersSharedCache(declared)) {
+      applyCacheHeaders(response, NO_STORE);
+      if (!response.headers.has('pragma')) response.headers.set('pragma', 'no-cache');
+    }
+    return;
+  }
+  if (declared === null) {
+    const hint = ctx.cache ?? ctx.route?.meta.cache ?? defaultCache(ctx.route, ctx.actor);
+    applyCacheHeaders(response, reviewedHint(hint, ctx.actor));
+    return;
+  }
+  // A declaration is the MODE's intent, never the last word: `@ultimat3/render`'s `ssrHeaders`
+  // offers any route without a `policy` to a CDN for 30 seconds, and `meta.auth` is
+  // `'public' | 'required'` — so the page that greets a signed-in visitor by name is a
+  // `'public'` route whose own header says `s-maxage`. This stage is the one owner of the
+  // final answer, which is why it REVIEWS what the handler wrote instead of standing down;
+  // the rule beside it was otherwise unreachable for every page route in every app.
+  if (!offersSharedCache(declared)) return;
+  if (!isAnonymous(ctx.actor)) {
+    applyCacheHeaders(response, PRIVATE_CACHE);
+    return;
+  }
+  addVary(response, SHARED_CACHE_VARY);
+};

package/src/error-map.ts

@@ -392,6 +392,10 @@ export const ERROR_STATUS = {
   // 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/seo — a `meta.links` entry an `ssr` page's `meta()` built from data: an unsafe href,
+  // a preload with no `as`. Thrown while that request renders its head, so it reaches the caller —
+  // an authoring defect, never the visitor's, hence 500 with the cause naming the link intact.
+  X_SEO_LINK_INVALID: 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/stages.ts

@@ -13,7 +13,7 @@ import {
   reportError,
 } from '@ultimat3/core';
 import { signInRedirect } from './auth-redirect';
-import { defaultCache, offersSharedCache, PRIVATE_CACHE, reviewedHint } from './cache-policy';
+import { finalizeCacheHeaders } from './cache-stage';
 import { type HttpConfig, stripBasePath } from './config';
 import { actorView, elapsedMs, type RequestContext } from './context';
 import { corsHeaders, preflight } from './cors';
@@ -40,7 +40,7 @@ import { resolvePreferences } from './preferences';
 import { type RateLimitDecision, type RateLimiter, rateLimitSpends } from './rate-limit';
 import { rateLimited } from './rate-limit-errors';
 import type { UltimateRequest } from './request';
-import { addVary, applyCacheHeaders, problem, redirect, SHARED_CACHE_VARY } from './response';
+import { addVary, problem, redirect } from './response';
 import { matchRoute, type Route, type RouteHandler, type RouteTable } from './router';
 import { responseSecurityHeaders } from './security-headers';
 import { validate } from './validate';
@@ -324,26 +324,7 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
     },
 
     'cache-headers': (_request, ctx) => {
-      const response = ctx.response;
-      if (response === undefined) return undefined;
-      const declared = response.headers.get('cache-control');
-      if (declared === null) {
-        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`
-      // offers any route without a `policy` to a CDN for 30 seconds, and `meta.auth` is
-      // `'public' | 'required'` — so the page that greets a signed-in visitor by name is a
-      // `'public'` route whose own header says `s-maxage`. This stage is the one owner of the
-      // final answer, which is why it REVIEWS what the handler wrote instead of standing down;
-      // the rule beside it was otherwise unreachable for every page route in every app.
-      if (!offersSharedCache(declared)) return undefined;
-      if (!isAnonymous(ctx.actor)) {
-        applyCacheHeaders(response, PRIVATE_CACHE);
-        return undefined;
-      }
-      addVary(response, SHARED_CACHE_VARY);
+      if (ctx.response !== undefined) finalizeCacheHeaders(ctx.response, ctx);
       return undefined;
     },