@statorjs/stator 2.10.0-next.0 → 2.10.0

package/src/server/http.ts

@@ -19,10 +19,17 @@ import { renderRoute } from './render.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
 import { buildRouteRequest } from './route-request.ts'
 import { isStatorQueryRoute, type RouteDefinition } from './routing.ts'
-import { CLAIMS_KEY, getOrCreateSessionId, getSessionState } from './session.ts'
+import {
+  CLAIMS_KEY,
+  getOrCreateSessionId,
+  getSessionState,
+  peekSessionId,
+  resumeSession,
+  sessionUse,
+} from './session.ts'
 import { withSessionLock } from './session-lock.ts'
 import { SessionRuntime } from './session-runtime.ts'
-import { fanOut, registerConnection, unregisterConnection } from './sse.ts'
+import { enqueue, fanOut, registerConnection, unregisterConnection } from './sse.ts'
 
 const httpLog = scopedLogger('http')
 
@@ -64,8 +71,18 @@ export interface HttpConfig {
   /** The app's discovered `middleware.ts` definition (if any). `withDefaults`
    *  controls whether the framework security stack is prepended. */
   middleware?: MiddlewareDefinition
+  /** Layer-3 derived Cache-Control: emitted on GET responses the framework can
+   *  PROVE anonymous-identical (no session reads declared, no session use or
+   *  claims read while handling, nothing hand-set). Absent → never emitted
+   *  (the dev servers leave it off so editing always re-renders). */
+  caching?: { sMaxAge: number; staleWhileRevalidate: number }
 }
 
+/** Placeholder sid for session-free page renders — `loadGraph` loads only
+ *  session-lifecycle machines, so on app-only routes this never reaches the
+ *  store; it exists to keep SessionRuntime's signature honest. */
+const ANONYMOUS_SID = '@anonymous'
+
 const eventSchema = z.object({
   machine: z.string(),
   event: z
@@ -113,14 +130,20 @@ function compileMatcher(route: DiscoveredRoute): RouteMatcher {
   return { route, regex: new RegExp(`^${pattern}$`) }
 }
 
+/** One matcher's result against a literal path: the route plus its
+ *  extracted path params. */
+interface PathMatch {
+  route: DiscoveredRoute
+  params: Record<string, string>
+}
+
 /**
- * Match a literal URL path against compiled matchers. Returns the matched
- * route + extracted params, or null if nothing matches.
+ * Match a literal URL path against every compiled matcher that matches it,
+ * in `matchers`' own (priority-sorted) order — every candidate a 404-
+ * cascading GET dispatch might need to try, not just the first.
  */
-function matchPath(
-  matchers: RouteMatcher[],
-  literalPath: string,
-): { route: DiscoveredRoute; params: Record<string, string> } | null {
+function matchAllPaths(matchers: RouteMatcher[], literalPath: string): PathMatch[] {
+  const matches: PathMatch[] = []
   for (const m of matchers) {
     const result = m.regex.exec(literalPath)
     if (!result) continue
@@ -128,9 +151,65 @@ function matchPath(
     m.route.paramNames.forEach((name, i) => {
       params[name] = decodeURIComponent(result[i + 1] ?? '')
     })
-    return { route: m.route, params }
+    matches.push({ route: m.route, params })
   }
-  return null
+  return matches
+}
+
+/**
+ * Match a literal URL path against compiled matchers. Returns the FIRST
+ * matched route + extracted params, or null if nothing matches — for call
+ * sites resolving an already-known route key (the SSE/event endpoints),
+ * where there is exactly one right answer and no cascading question.
+ */
+function matchPath(matchers: RouteMatcher[], literalPath: string): PathMatch | null {
+  return matchAllPaths(matchers, literalPath)[0] ?? null
+}
+
+/** True when any segment of a urlPath is a rest/catch-all (`*name`). */
+function isRestPattern(urlPath: string): boolean {
+  return urlPath.split('/').some((seg) => seg.startsWith('*'))
+}
+
+/** True when any segment of a urlPath is a suffixed param (`:name.ext`) —
+ *  the file-extension-routing pattern (`[id].json.ts` → `/p/:id.json`). */
+function isSuffixedParamPattern(urlPath: string): boolean {
+  return urlPath.split('/').some((seg) => seg.startsWith(':') && seg.includes('.'))
+}
+
+/**
+ * Candidates a 404-cascading GET dispatch may actually try, in priority
+ * order.
+ *
+ * Two matches can structurally overlap for one literal URL in ways that
+ * were never meant to form a "try something more general" chain:
+ *
+ *   - A suffixed param (`/p/:id.json`, from `[id].json.ts`) and its bare
+ *     sibling (`/p/:id`) — `compileMatcher`'s bare `:id` regex doesn't
+ *     exclude dots, so both structurally match `/p/abc.json`. The suffix
+ *     is the author's own explicit, dedicated handler for exactly that
+ *     extension (`sortRoutes`'s own doc comment: "so `/p/:id.json` wins
+ *     `/p/abc.json` before `/p/:id` can swallow it") — nothing ranked
+ *     below it, bare OR rest, is a MORE correct answer than what was
+ *     written on purpose for this exact case. (A rest/catch-all can't
+ *     even carry a suffix of its own — `filePathToRoute` rejects
+ *     `[...name].ext` outright — so it's exactly as wrong a fallback here
+ *     as bare is: confirmed against a real app, examples/live-poll's
+ *     `/p/:id.json` data route + `/p/:id` HTML page pair, where a 404
+ *     from the JSON route cascading into the page handed back HTML for a
+ *     request that explicitly asked for JSON.) So a winning suffixed
+ *     match is unconditionally terminal — no cascading at all, into
+ *     anything, once it's the one that matched.
+ *   - Anything bare/static vs. a rest/catch-all IS a legitimate fallback
+ *     chain (`routes/media/[...path].ts`, this feature's original
+ *     motivating case) — a catch-all stays cascade-eligible unless the
+ *     winning match was itself suffixed.
+ */
+function cascadeCandidates<T extends PathMatch>(all: T[]): T[] {
+  if (all.length === 0) return all
+  const winner = all[0]!
+  if (isSuffixedParamPattern(winner.route.urlPath)) return [winner]
+  return [winner, ...all.slice(1).filter((m) => isRestPattern(m.route.urlPath))]
 }
 
 /** Parse a route key like "GET /p/abc-123" into method + literal path. */
@@ -179,10 +258,13 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
   })
 
   // Context bridge — expose resolved config to every middleware (cors, app
-  // middleware) that follows, off `stator(c)`. Runs first. Also establishes the
-  // session once and eager-loads its claims (for a returning session), so the
-  // whole request shares one sid + claims snapshot; dirty claims persist at the
-  // end, to the current (possibly rotated) sid.
+  // middleware) that follows, off `stator(c)`. Runs first. Sessions are LAZY
+  // (the cacheable-read-path layer 1): an arriving cookie RESUMES its session
+  // (claims eager-loaded, no cookie write), but first contact establishes
+  // nothing — creation happens only at a dispatch, a session-machine read, an
+  // SSE connect, or an explicit session op. Anonymous reads therefore carry
+  // no Set-Cookie and stay CDN-cacheable. Dirty claims persist at the end,
+  // to the current (possibly rotated or just-established) sid.
   app.use('*', async (c, next) => {
     c.set('stator', {
       origin: config.origin,
@@ -194,14 +276,15 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     c.set('statorStore', config.store)
     // Stash the signing key so the cookie jar's signed methods can reach it.
     if (config.secret !== undefined) c.set('statorSecret', config.secret)
-    const { sessionId, isNew } = getOrCreateSessionId(c)
-    const session = getSessionState(c)
-    if (!isNew && session) {
-      session.claims = (await config.store.persistence.get(sessionId, CLAIMS_KEY)) ?? undefined
+    sessionUse(c)
+    const resumed = resumeSession(c)
+    if (resumed) {
+      resumed.claims = (await config.store.persistence.get(resumed.sid, CLAIMS_KEY)) ?? undefined
     }
     await next()
-    // Same session object (rotation mutates `.sid` in place), so persist to the
-    // current — possibly rotated — id.
+    // Re-read: the session may have been established mid-request. Rotation
+    // mutates `.sid` in place, so this persists to the current id.
+    const session = getSessionState(c)
     if (session?.claimsDirty) {
       await config.store.persistence.set(session.sid, CLAIMS_KEY, session.claims, {
         ttlSeconds: config.store.sessionTtlSeconds,
@@ -260,7 +343,9 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
       const payload = await buildInspectPayload({
         store: config.store,
         routes: config.routes,
-        sessionId: getSessionState(c)?.sid,
+        // Inspecting IS session use — the route shows the caller's own
+        // session, so establish one for a first-contact dev visit.
+        sessionId: getOrCreateSessionId(c).sessionId,
         buildId: config.buildId,
       })
       c.header('Cache-Control', 'no-cache')
@@ -423,7 +508,7 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
       // otherwise never reach this page.
       const sync = initialSyncPatches(renderState, runtime)
       if (sync.length > 0) {
-        await conn.send(JSON.stringify({ patches: sync }))
+        enqueue(conn, JSON.stringify({ patches: sync }))
       }
 
       // Heartbeat every 25s. This is a real DATA message, not a comment, on
@@ -433,9 +518,11 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
       // ever arrives, no error fires) unless liveness is OBSERVABLE. The
       // runtime tracks last-message time and reconnects when pings stop.
       const keepAlive = setInterval(() => {
-        void conn.send('{"ping":true}').catch(() => {
-          // Stream closed; the abort handler cleans up.
-        })
+        // Through the same queue fan-out uses, so it is bounded like any other
+        // write: a half-open socket never settles its writes, and the heartbeat
+        // is what reaps it when the app is otherwise idle and no dispatch would
+        // ever notice.
+        enqueue(conn, '{"ping":true}')
       }, config.ssePingMs ?? 25_000)
 
       try {
@@ -547,7 +634,9 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
         // `touched`) — so it isn't re-created and re-fired next request.
         await runtime.persistTouched(new Set([...touched, ...runtime.entryFiredMachines()]))
 
-        await fanOut(touched, {
+        // Queues patches on every affected channel and returns; no socket is
+        // awaited under the lock.
+        const { originatorQueued } = await fanOut(touched, {
           sessionId,
           originClientId: c.req.header('X-Stator-Client'),
         })
@@ -557,7 +646,15 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
         // normal event path in server/effects.ts.
         scheduleSessionEffects(runtime, config.store, sessionId)
 
-        const envelope = { patches, directives: [], committed: touched.size > 0 }
+        // This page's patches normally ride the response. When its live
+        // channel already had a backlog, fan-out queued them behind it instead
+        // (two channels to one page must not reorder a positional list op), so
+        // the response carries none.
+        const envelope = {
+          patches: originatorQueued ? [] : patches,
+          directives: [],
+          committed: touched.size > 0,
+        }
         if (body.eventId) record(sessionId, body.eventId, JSON.stringify(envelope))
         return c.json(envelope)
       } finally {
@@ -579,24 +676,61 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     })
   }
 
+  // 404 cascades by default: a matched GET route that 404s doesn't
+  // permanently claim the path — a lower-priority `[...name]`/`404`
+  // catch-all (if one exists) gets a turn, same priority order `matchers`
+  // is already sorted in. Only once every candidate 404s does the LAST
+  // (lowest-priority) one's response actually go out — so a route's own
+  // not-found body/headers/status still reach the client, this just stops
+  // the FIRST match from being final when a catch-all could actually
+  // serve it. `cascadeCandidates` (not the full `matchAllPaths` list) is
+  // what narrows "the next matching route" to specifically mean a
+  // catch-all — see its own doc comment for why that boundary matters.
   app.get('*', async (c, next) => {
-    const matched = matchPath(matchers, c.req.path)
-    if (!matched?.route.GET) return next()
-    const getRoute = matched.route.GET
-    // Brand decides the GET plane: data routes never touch the HTML path
-    // (no client-runtime injection, no live meta — a raw Response out).
-    if (isStatorQueryRoute(getRoute)) {
-      return runQueryRoute(c, matched.route, getRoute, config.store, matched.params)
-    }
-    return handleGet(
-      c,
-      matched.route,
-      getRoute,
-      matched.params,
-      config.store,
-      config.headExtras,
-      config.buildId,
+    const candidates = cascadeCandidates(
+      matchAllPaths(matchers, c.req.path).filter(
+        (
+          m,
+        ): m is PathMatch & {
+          route: DiscoveredRoute & { GET: NonNullable<DiscoveredRoute['GET']> }
+        } => !!m.route.GET,
+      ),
     )
+    if (candidates.length === 0) return next()
+
+    let lastNotFound: (() => Response) | undefined
+    for (const matched of candidates) {
+      const getRoute = matched.route.GET
+      // Brand decides the GET plane: data routes never touch the HTML path
+      // (no client-runtime injection, no live meta — a raw Response out).
+      if (isStatorQueryRoute(getRoute)) {
+        const response = await runQueryRoute(
+          c,
+          matched.route,
+          getRoute,
+          config.store,
+          matched.params,
+          config.caching,
+        )
+        if (response.status !== 404) return response
+        lastNotFound = () => response
+        continue
+      }
+
+      const candidate = await renderGetCandidate(
+        c,
+        matched.route,
+        getRoute,
+        matched.params,
+        config.store,
+        config.headExtras,
+        config.buildId,
+        config.caching,
+      )
+      if (candidate.status !== 404) return candidate.commit()
+      lastNotFound = candidate.commit
+    }
+    return lastNotFound ? lastNotFound() : next()
   })
 
   return app
@@ -660,7 +794,24 @@ function injectIntoDocument(html: string, parts: { head?: string; bodyEnd?: stri
   return out
 }
 
-async function handleGet(
+/** A rendered GET candidate, not yet committed to the shared Hono `Context`.
+ *  Cascading (see `matchAllPaths`/the GET dispatch loop) speculatively tries
+ *  several routes for one path — `applyRenderedEffects` writes headers,
+ *  cookies, and status directly onto `c`, cumulatively, so calling it for a
+ *  candidate that turns out to 404 would leak into whatever candidate wins
+ *  next (worse: `applyRenderedEffects` only calls `c.status(...)` when the
+ *  status isn't 200, so a losing 404 candidate followed by a winning 200 one
+ *  would ship 200 content under a stale 404 status — confirmed the hard way
+ *  designing this). Splitting render (safe to call speculatively, side-effect
+ *  free on `c`) from commit (writes to `c`, only ever called once, for
+ *  whichever candidate the dispatch loop actually decided to serve) is what
+ *  makes cascading safe. */
+interface GetCandidate {
+  status: number
+  commit: () => Response
+}
+
+async function renderGetCandidate(
   c: Context,
   discovered: DiscoveredRoute,
   route: RouteDefinition,
@@ -668,64 +819,100 @@ async function handleGet(
   store: MachineStore,
   headExtras?: (filePath: string) => string | Promise<string>,
   buildId?: string,
-): Promise<Response> {
-  {
-    const { sessionId } = getOrCreateSessionId(c)
-    const literalPath = c.req.path
-    const routeKey = `GET ${literalPath}`
-    const request = { ...buildRouteRequest(c, discovered.paramNames), params }
-
-    const runtime = new SessionRuntime(sessionId, store)
-    try {
-      await runtime.loadGraph(route.reads)
-      const result = await renderRoute(route, routeKey, sessionId, runtime, request)
-      let html = result.html
-
-      const headHtml: string[] = []
-      if (headExtras) {
-        const extra = await headExtras(discovered.filePath)
-        if (extra) headHtml.push(extra)
-      }
-      if (route.live) {
-        headHtml.push('<meta name="stator-live" content="true">')
-        // The build this page was rendered against — the client echoes it on
-        // /__sse connect so the server can reload a page from a stale build.
-        // `buildId` is a framework-generated UUID (no HTML-special chars).
-        if (buildId) {
-          headHtml.push(`<meta name="stator-build" content="${buildId}">`)
-        }
+  caching?: { sMaxAge: number; staleWhileRevalidate: number },
+): Promise<GetCandidate> {
+  // Lazy layer 1: only a session-machine read forces establishment. An
+  // app-only (or read-free) page renders against the resumed sid when a
+  // cookie arrived, or an inert placeholder — loadGraph loads session
+  // machines only, so the placeholder never reaches the store.
+  const needsSession = route.reads.some((def) => def.lifecycle === 'session')
+  const sessionId = needsSession
+    ? getOrCreateSessionId(c).sessionId
+    : (peekSessionId(c) ?? ANONYMOUS_SID)
+  const literalPath = c.req.path
+  const routeKey = `GET ${literalPath}`
+  const request = { ...buildRouteRequest(c, discovered.paramNames), params }
+
+  const runtime = new SessionRuntime(sessionId, store)
+  try {
+    await runtime.loadGraph(route.reads)
+    const result = await renderRoute(route, routeKey, sessionId, runtime, request)
+    let html = result.html
+
+    const headHtml: string[] = []
+    if (headExtras) {
+      const extra = await headExtras(discovered.filePath)
+      if (extra) headHtml.push(extra)
+    }
+    if (route.live) {
+      headHtml.push('<meta name="stator-live" content="true">')
+      // The build this page was rendered against — the client echoes it on
+      // /__sse connect so the server can reload a page from a stale build.
+      // `buildId` is a framework-generated UUID (no HTML-special chars).
+      if (buildId) {
+        headHtml.push(`<meta name="stator-build" content="${buildId}">`)
       }
+    }
 
-      // Auto-inject the client runtime (delegated events + patch application).
-      // Apps never hand-include it — a forgotten <script> is a silently dead
-      // page (events fire nothing, no patches apply). Idempotent: skipped if the
-      // document already references it, so a layout that still carries the tag
-      // (or two passes sharing a doc) never loads it twice.
-      const bodyHtml: string[] = []
-      if (!html.includes('/static/client.js')) {
-        bodyHtml.push('<script src="/static/client.js"></script>')
-      }
+    // Auto-inject the client runtime (delegated events + patch application).
+    // Apps never hand-include it — a forgotten <script> is a silently dead
+    // page (events fire nothing, no patches apply). Idempotent: skipped if the
+    // document already references it, so a layout that still carries the tag
+    // (or two passes sharing a doc) never loads it twice.
+    const bodyHtml: string[] = []
+    if (!html.includes('/static/client.js')) {
+      bodyHtml.push('<script src="/static/client.js"></script>')
+    }
 
-      html = injectIntoDocument(html, {
-        head: headHtml.join(''),
-        bodyEnd: bodyHtml.join(''),
-      })
-      applyRenderedEffects(c, result.response)
-
-      // A fresh machine that fired its initial entry effect on load must be
-      // persisted (so the next request hydrates instead of re-firing) and its
-      // effect scheduled off-lock, after the response. The common GET (no entry
-      // effect) skips both and stays a pure read.
-      const entryFired = runtime.entryFiredMachines()
-      if (entryFired.size > 0) {
-        await runtime.persistTouched(entryFired)
-        scheduleSessionEffects(runtime, store, sessionId)
-      }
+    html = injectIntoDocument(html, {
+      head: headHtml.join(''),
+      bodyEnd: bodyHtml.join(''),
+    })
+
+    // Fired regardless of whether this candidate ends up winning: an entry
+    // effect firing is a fact about the MACHINE having been loaded for the
+    // first time (shared, cross-cutting state), not about which route's
+    // response the caller ultimately serves — a discarded losing candidate
+    // still genuinely loaded whatever it read.
+    const entryFired = runtime.entryFiredMachines()
+    if (entryFired.size > 0) {
+      await runtime.persistTouched(entryFired)
+      scheduleSessionEffects(runtime, store, sessionId)
+    }
 
-      return c.html(html)
-    } finally {
-      runtime.dispose()
+    // Layer 3 — derived Cache-Control: the page is PROVABLY anonymous-
+    // identical (no session reads declared, no session use or claims read
+    // during handling) and the route didn't hand-set the header. The
+    // framework says what it can prove; hand-set always wins. Computed here
+    // but only ever WRITTEN from `commit`, below — this render may be a
+    // losing, discarded candidate under cascading, and only the winner's
+    // headers may reach `c` (the same reason `applyRenderedEffects` is
+    // deferred to `commit` rather than called here).
+    const use = sessionUse(c)
+    const deriveCacheControl =
+      !!caching &&
+      !needsSession &&
+      !use.used &&
+      !use.claimsRead &&
+      result.response.status < 300 &&
+      result.response.cookies.length === 0 &&
+      !result.response.headers.has('cache-control')
+
+    return {
+      status: result.response.status,
+      commit: () => {
+        applyRenderedEffects(c, result.response)
+        if (deriveCacheControl) {
+          c.header(
+            'Cache-Control',
+            `public, max-age=0, s-maxage=${caching!.sMaxAge}, stale-while-revalidate=${caching!.staleWhileRevalidate}`,
+          )
+        }
+        return c.html(html)
+      },
     }
+  } finally {
+    runtime.dispose()
   }
 }
 

package/src/server/query-route.ts

@@ -12,7 +12,7 @@ import type {
   QueryRouteResult,
   RouteContext,
 } from './routing.ts'
-import { getOrCreateSessionId } from './session.ts'
+import { getOrCreateSessionId, peekSessionId, sessionUse } from './session.ts'
 import { withSessionLock } from './session-lock.ts'
 import { SessionRuntime } from './session-runtime.ts'
 
@@ -24,6 +24,7 @@ const queryLog = scopedLogger('query')
 const DATA_CONTENT_TYPES: Record<string, string> = {
   '.json': 'application/json; charset=utf-8',
   '.xml': 'application/xml; charset=utf-8',
+  '.atom': 'application/atom+xml; charset=utf-8',
   '.txt': 'text/plain; charset=utf-8',
   '.ics': 'text/calendar; charset=utf-8',
   '.csv': 'text/csv; charset=utf-8',
@@ -55,8 +56,30 @@ export async function runQueryRoute(
   /** Path params from the framework's own matcher (the GET catch-all
    *  bypasses Hono's per-route param extraction). */
   params?: Record<string, string>,
+  /** Layer-3 derived Cache-Control values (absent → never emitted). */
+  caching?: { sMaxAge: number; staleWhileRevalidate: number },
 ): Promise<Response> {
-  const { sessionId } = getOrCreateSessionId(c)
+  // Lazy layer 1: only session-machine reads establish; an app-only data
+  // route (a feed, a sitemap) renders sessionless and stays CDN-cacheable.
+  const needsSession = route.reads.some((def) => def.lifecycle === 'session')
+
+  // The revision ledger: when the route declares a cheap fingerprint, the
+  // ETag derives from it and a match answers 304 BEFORE the handler — the
+  // designed upgrade the body-hash ETag always pointed at. The fingerprint
+  // runs outside any session machinery, so the derived-caching proof holds.
+  let revisionEtag: string | undefined
+  if (route.revision) {
+    const rev = await route.revision()
+    revisionEtag = `"r-${createHash('sha1').update(String(rev)).digest('base64url').slice(0, 16)}"`
+    if ((c.req.header('if-none-match') ?? '').includes(revisionEtag)) {
+      const notModified = new Response(null, { status: 304, headers: { ETag: revisionEtag } })
+      applyDerivedCaching(c, notModified, { caching, needsSession })
+      return notModified
+    }
+  }
+  const sessionId = needsSession
+    ? getOrCreateSessionId(c).sessionId
+    : (peekSessionId(c) ?? '@anonymous')
   const request = params
     ? { ...buildRouteRequest(c, discovered.paramNames), params }
     : buildRouteRequest(c, discovered.paramNames)
@@ -99,12 +122,54 @@ export async function runQueryRoute(
       scheduleSessionEffects(runtime, store, sessionId)
     }
 
-    return synthesizeDataResponse(c, result)
+    const res = synthesizeDataResponse(c, result)
+    // A revision route's responses carry the revision ETag (overriding the
+    // body hash) so the cheap 304 path and full responses validate against
+    // one token.
+    if (revisionEtag) {
+      try {
+        res.headers.set('etag', revisionEtag)
+      } catch {
+        // Immutable headers (proxied Response) — the handler's call.
+      }
+    }
+    applyDerivedCaching(c, res, { caching, needsSession })
+    return res
   } finally {
     runtime.dispose()
   }
 }
 
+/** Layer 3 — derived Cache-Control, same proof as pages: no session reads
+ *  declared, no session use/claims read while handling, handler set nothing
+ *  itself. Applied to 200 and 304 alike (a 304's headers update the cached
+ *  entry's lifetime). */
+function applyDerivedCaching(
+  c: Context,
+  res: Response,
+  opts: { caching?: { sMaxAge: number; staleWhileRevalidate: number }; needsSession: boolean },
+): void {
+  const use = sessionUse(c)
+  if (
+    !opts.caching ||
+    opts.needsSession ||
+    use.used ||
+    use.claimsRead ||
+    res.status >= 400 ||
+    res.headers.has('cache-control')
+  ) {
+    return
+  }
+  try {
+    res.headers.set(
+      'cache-control',
+      `public, max-age=0, s-maxage=${opts.caching.sMaxAge}, stale-while-revalidate=${opts.caching.staleWhileRevalidate}`,
+    )
+  } catch {
+    // Immutable headers (proxied Response) — the handler's call.
+  }
+}
+
 /** The URL's extension (`/rss.xml` → `.xml`). A leading dot alone
  *  (`/.well-known`) is not an extension. */
 function urlExtension(path: string): string | undefined {