@ultimat3/render 27.8.0 → 27.8.1

package/CLAUDE.md

@@ -77,7 +77,7 @@ axiom 6). Never `cli` (upward).
 | "Is this a TTL?" has one reader | `parseTtlMs` in `duration.ts`, below `modes.ts` and `render-isr.ts`. |
 | A build-time frame reads a throw with `renderThrowable` | `render-html.ts`, `render-static.ts`, `css-modules.ts`, `module-loader.ts`, `route-data.ts`. `bun run error-render` cannot see a value laundered through a local helper. |
 | `X_ROUTE_LOAD_FAILED` computes its pathname BEFORE the try | `pathnameOf` never throws on a relative `ctx.url`. |
-| The ISR key | `isrKey(url, locale)` — pathname, the negotiated locale in the reserved `__x_locale` parameter, then the sorted query. The locale is REQUIRED. The time zone is deliberately not a dimension. `toResult` emits `vary: accept-language`, and `surrogate-key`/`cache-tag` from `@ultimat3/cache`'s `surrogateKeys()` over the route's `revalidateTags` — kept only while the response stays shared: http's `applyCacheHeaders` strips both on a rewrite to `private`/`no-store`. `registry.ts`'s `assertPurgeableTags` screens the tags at registration (`X_ROUTE_MODE_INVALID`); the rest of the shared key is `@ultimat3/http`'s `cache-headers` stage. The one shipped emitter of purge keys; file and mounted routes are both screened, so `toResult` never refuses on the request path |
+| The ISR key | `isrKey(url, locale)` — the path in http's `canonicalPath` spelling (no base path), the locale in the reserved `__x_locale` parameter, the sorted query. A key no route owns is never stored. The locale is REQUIRED. The time zone is deliberately not a dimension. `toResult` emits `vary: accept-language`, and `surrogate-key`/`cache-tag` from `@ultimat3/cache`'s `surrogateKeys()` over the route's `revalidateTags` — kept only while the response stays shared: http's `applyCacheHeaders` strips both on a rewrite to `private`/`no-store`. `registry.ts`'s `assertPurgeableTags` screens the tags at registration (`X_ROUTE_MODE_INVALID`); the rest of the shared key is `@ultimat3/http`'s `cache-headers` stage. File and mounted routes are both screened |
 | A bust that lands MID-render | fenced with `@ultimat3/cache`'s `sampleFence({ key, tags })`, taken before `render()` and asked before `store.set`. `registerPath` runs BEFORE the render. |
 | ISR regeneration | `@ultimat3/core`'s `singleFlight`, `deadlineMs` = `regenerateDeadlineMs` (`DEFAULT_ISR_REGENERATE_DEADLINE_MS`, 30 s; `finiteCount` ≥ 1, no opt-out), `schedule` injectable. Past it the PATH is free; the hung render runs on, and `latest` (by identity) drops its result once a newer run started. `render-isr-flight.test.ts`, on a hand-fired scheduler. |
 | Which route a stored ISR path is | exact path first, else the MOST SPECIFIC pattern: `route-pattern.ts`'s `compilePattern` (never a second compiler), sorted on `CompiledPattern.specificity`. Never table order: `describePages()` sorts `*` before `:`. |

package/README.md

@@ -557,7 +557,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `checkSurfaceBoundary`, `assertSurfaceBoundary`, `surfaceOf` | the hard boundary |
 | `renderStatic`†, `enumeratePrerender`† | build-time render, content hashing |
 | `isrController`†, `invalidateAndRevalidate`† | SWR + single-flight + tag triggers |
-| `isrKey`†, `isrRequestUrl`†, `undeclaredQuery`† | the one derivation of an `isr` store key, and the request URL narrowed to `revalidate.query` |
+| `isrKey`†, `isrRequestUrl`†, `undeclaredQuery`†, `isrRouteFor`† | the one derivation of an `isr` store key — the path in `@ultimat3/http`'s `canonicalPath` spelling, so every spelling the router answers with a page is that page's one entry — the request URL narrowed to `revalidate.query`, and the route a key reads back as (a key no route owns is never stored) |
 | `noStore`, `routeNoStoreOf` | a loader's "do not keep this answer" — a mark on the data, like `withStatus`; read by `isr` |
 | `renderSsr`†, `streamResult`† | the per-request modes |
 | `renderToHtml`†, `renderComponent`†, `stylesFor`† | the server JSX writer and the surface's css |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "27.8.0",
+  "version": "27.8.1",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -40,11 +40,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "27.8.0",
-    "@ultimat3/core": "27.8.0",
-    "@ultimat3/http": "27.8.0",
-    "@ultimat3/i18n": "27.8.0",
-    "@ultimat3/seo": "27.8.0",
+    "@ultimat3/cache": "27.8.1",
+    "@ultimat3/core": "27.8.1",
+    "@ultimat3/http": "27.8.1",
+    "@ultimat3/i18n": "27.8.1",
+    "@ultimat3/seo": "27.8.1",
     "sass": "1.105.1"
   }
 }

package/src/render-isr-key.ts

@@ -4,6 +4,7 @@
  * the controller, which only ever holds the key this file derived.
  */
 
+import { canonicalPath } from '@ultimat3/http';
 import { unlocalizedPath } from '@ultimat3/i18n';
 
 /**
@@ -57,6 +58,13 @@ export function undeclaredQuery(url: URL, query: readonly string[] | null): read
  * The ISR store key for one URL: pathname, the negotiated LOCALE, and the query, **params
  * sorted**. The URL is `isrRequestUrl`'s — already narrowed to the route's declared parameters.
  *
+ * The pathname is keyed in its ONE spelling — `@ultimat3/http`'s `canonicalPath`, built from the
+ * functions the router segments and decodes a request with, never a second normaliser. The router
+ * answers `/blog//a/`, `/blog/%61` and `/blog/a` with one page; keyed raw, each was an entry of
+ * its own (a 20-letter slug has a million percent-spellings, and the store holds 1,000), and one
+ * the route table could not read back (`/blog//a`) was stored with no ttl and no tags, which no
+ * bust reached: a withdrawn page stayed up at that spelling for the life of the process.
+ *
  * Exported because deriving it is the caller's job and there may only be ONE derivation — a
  * server that keyed on `url.pathname` while the store believed it held a whole URL is the shape
  * of #171. Sorting makes `?a=1&b=2` and `?b=2&a=1` one entry rather than two renders of one page.
@@ -72,7 +80,7 @@ export function isrKey(url: URL, locale: string): string {
   const params = new URLSearchParams(url.search);
   params.set(ISR_LOCALE_PARAM, locale);
   params.sort();
-  return `${url.pathname}?${params.toString()}`;
+  return `${canonicalPath(url.pathname)}?${params.toString()}`;
 }
 
 /**

package/src/render-isr.ts

@@ -108,6 +108,24 @@ export function isrController(options: IsrControllerOptions = {}): IsrController
 
   const descriptorFor = (key: string): RouteDescriptor | undefined => isrRouteFor(routes(), key);
 
+  /**
+   * A key NO route owns is rendered for the request that asked and never stored. Its ttl and tags
+   * are its route's, so stored it had neither: fresh for ever, on no tag edge, and found by no
+   * bust — the one page a purge could not take down. `@ultimat3/cli` keys every request on the
+   * path the router matched, so this is a caller that derived a key some other way. Told once.
+   */
+  let toldUnowned = false;
+  function tellUnowned(path: string): void {
+    if (toldUnowned) return;
+    toldUnowned = true;
+    logger.warn('isr.key.unowned', {
+      path,
+      cause:
+        'no route in the table matches this key, so it has no ttl and no tags to be revalidated by — it was rendered and not stored',
+      fix: 'isrKey(url, locale)   // key on the URL the router matched, base path removed; never on a hand-built string',
+    });
+  }
+
   /**
    * A rendered page joins the invalidation graph under its route's tags, so `/blog/a` and
    * `/blog/b` are separately addressable and a `tag.post` bust does not touch `/team`.
@@ -192,7 +210,8 @@ export function isrController(options: IsrControllerOptions = {}): IsrController
           status: finiteStatus('IsrRenderFn', rendered.status),
         };
         const current = latest.get(path) === run;
-        const unstorable = isServerError(rendered.status) || rendered.noStore === true;
+        const unstorable =
+          descriptor === undefined || isServerError(rendered.status) || rendered.noStore === true;
         // Kept only when nothing invalidated the page while it rendered — in this process (the
         // fence) or in any other (the store's) — and no newer run started. Refused, never
         // published stale-flagged: the next request re-renders from rows that include the write.
@@ -203,6 +222,8 @@ export function isrController(options: IsrControllerOptions = {}): IsrController
           // store holds stays (still stale, so the next request tries again); a miss has none, and
           // answers this 5xx to its own request only.
           logger.warn('isr.render.unstored', { path, status: String(rendered.status) });
+        } else if (descriptor === undefined) {
+          tellUnowned(path);
         } else if (rendered.noStore === true) {
           // The loader's answer is not a failure, so the copy held is no longer the page.
           if (current) store.delete(path);
@@ -331,7 +352,9 @@ export function isrController(options: IsrControllerOptions = {}): IsrController
           ageMs: Math.max(0, now() - entry.generatedAt),
         });
       let cached = store.get(path);
-      if (cached !== undefined && pastMaxStale(cached, policy)) {
+      // A copy under a key no route owns (a shared store an earlier release wrote) is not served:
+      // nothing could have invalidated it since.
+      if (cached !== undefined && (descriptor === undefined || pastMaxStale(cached, policy))) {
         store.delete(path);
         cached = undefined;
       }

package/src/server.ts

@@ -47,6 +47,7 @@ export {
 } from './render-isr';
 export { DEFAULT_ISR_FAILURE_COOLDOWN_MS } from './render-isr-cooldown';
 export { ISR_LOCALE_PARAM, isrKey, isrRequestUrl, undeclaredQuery } from './render-isr-key';
+export { isrRouteFor } from './render-isr-routes';
 export type {
   IsrEntry,
   IsrState,