fix(web): align /internal/* result cache with the public routes (#143)

README.md

@@ -136,6 +136,19 @@ pnpm --filter @released/web-og dev       # wrangler dev for web-og
 pnpm --filter git-released dev -- <input>    # tsx-run the CLI in place
 ```
 
+Working on OG rendering locally? Put this in `packages/web/.dev.vars`:
+
+```
+PUBLIC_BASE_URL=http://localhost:8787
+```
+
+`/internal/*` (what web-og calls) keys the result cache on the deployment's own
+public origin. `wrangler dev` loads `[vars]`, where `PROD_HOST` is set, so
+without the override the OG path keys on `https://released.blabberate.com` while
+your public routes key on `http://localhost:8787`: two namespaces on one
+machine, and every local OG request pays a full lookup instead of hitting the
+slot the permalink just warmed. Prod and the preview Worker set it themselves.
+
 ### Local checks reference
 
 | Command | What it does | Gate? |

packages/web/src/cache.ts

@@ -15,8 +15,16 @@
 
 import type { CacheStore } from '@released/core';
 
-/** A cached value plus how long ago it was written (seconds). */
-export type CacheEntry<T> = { value: T; ageSeconds: number };
+/** A cached value, how long ago it was written (seconds), and the raw
+ *  `x-cached-at` wall-clock stamp it was derived from (null for an entry
+ *  written before this header existed).
+ *
+ *  `ageSeconds` is floored from a `Date.now()` sample taken at READ time, so two
+ *  entries read one Cache API round trip apart carry ages sampled at two
+ *  different instants — comparing them can invert the true write order when the
+ *  floors straddle a second boundary. `stampedAt` is the write-time instant
+ *  itself, so an ordering test between two entries is exact. */
+export type CacheEntry<T> = { value: T; ageSeconds: number; stampedAt: number | null };
 
 export type WorkerCache = CacheStore & {
   /** Like get(), but also reports the entry's age so callers can judge staleness. */
@@ -53,11 +61,10 @@ export function makeWorkerCache(req: Request, ttlSecondsDefault = 1800): WorkerC
         return null;
       }
       const stamped = Number(res.headers.get('x-cached-at'));
+      const stampedAt = Number.isFinite(stamped) && stamped > 0 ? stamped : null;
       const ageSeconds =
-        Number.isFinite(stamped) && stamped > 0
-          ? Math.max(0, Math.floor((Date.now() - stamped) / 1000))
-          : 0;
-      return { value, ageSeconds };
+        stampedAt === null ? 0 : Math.max(0, Math.floor((Date.now() - stampedAt) / 1000));
+      return { value, ageSeconds, stampedAt };
     },
 
     async put<T>(key: string, value: T, ttlSeconds?: number): Promise<void> {

packages/web/test/cache.test.ts

@@ -109,6 +109,10 @@ describe('makeWorkerCache', () => {
     expect(entry?.value).toEqual({ x: 7 });
     expect(entry?.ageSeconds).toBeGreaterThanOrEqual(41);
     expect(entry?.ageSeconds).toBeLessThanOrEqual(44);
+    // The raw write-time stamp is reported too: `ageSeconds` is floored from a
+    // read-time `Date.now()`, so an ordering test between two entries read at
+    // different instants needs the stamp itself (resolve.ts writtenNoEarlierThan).
+    expect(entry?.stampedAt).toBe(cachedAt);
   });
 
   it('getEntry returns null when there is no cached entry', async () => {
@@ -127,5 +131,8 @@ describe('makeWorkerCache', () => {
     const cache = makeWorkerCache(new Request('https://released-web.lukaso.workers.dev/'));
     const entry = await cache.getEntry('k');
     expect(entry?.ageSeconds).toBe(0);
+    // ...and reports the stamp as absent rather than inventing one, so an
+    // ordering test falls back to ages instead of comparing against a fake 0.
+    expect(entry?.stampedAt).toBeNull();
   });
 });

packages/web/test/integration.test.ts

@@ -36,7 +36,7 @@ const INTERNAL_SECRET = 'test-shared-secret';
 // typed `unknown`, not LookupResult (a full LookupResult isn't required to exercise
 // the route, and the seeded fixtures below don't populate one).
 async function seedFederatedResult(sha: string, result: unknown) {
-  const key = await cacheKey('res', 'gitlab.gnome.org/GNOME/gimp', `sha:${sha}`);
+  const key = await cacheKey('res', 'gitlab.gnome.org/GNOME/gimp', `sha:${sha}`, 'cull', 'nopre');
   cacheStore.set(
     `https://released.example/__cache__/${encodeURIComponent(key)}`,
     new Response(JSON.stringify(result), { headers: { 'content-type': 'application/json' } }),
@@ -600,9 +600,10 @@ describe('web Worker — issue/PR internal endpoints (#79)', () => {
       releaseNotesHtml: null,
       rateLimit: null,
     };
-    // Seed the slot the route reads: cacheKey('res', `${host}/${projectPath}`,
-    // `issue:${number}`) — mirroring the commit endpoint's `sha:${sha}` key.
-    const key = await cacheKey('res', 'github.com/honojs/hono', 'issue:11');
+    // Seed the slot the route reads. Since #143 that is the SAME key the public
+    // /i/ permalink writes: cacheKey('res', `${host}/${projectPath}`,
+    // `issue#${number}`, 'cull', 'nopre') — see routes/internal.ts.
+    const key = await cacheKey('res', 'github.com/honojs/hono', 'issue#11', 'cull', 'nopre');
     cacheStore.set(
       `https://released.example/__cache__/${encodeURIComponent(key)}`,
       new Response(JSON.stringify(seeded), { headers: { 'content-type': 'application/json' } }),
@@ -631,7 +632,7 @@ describe('web Worker — issue/PR internal endpoints (#79)', () => {
       releaseNotesHtml: null,
       rateLimit: null,
     };
-    const key = await cacheKey('res', 'github.com/honojs/hono', 'pr:17');
+    const key = await cacheKey('res', 'github.com/honojs/hono', 'pr#17', 'cull', 'nopre');
     cacheStore.set(
       `https://released.example/__cache__/${encodeURIComponent(key)}`,
       new Response(JSON.stringify(seeded), { headers: { 'content-type': 'application/json' } }),
@@ -664,7 +665,7 @@ describe('web Worker — issue/PR internal endpoints (#79)', () => {
       rateLimit: null,
     };
     // Proves the route keys the cache by host on the (Hono-decoded) projectPath.
-    const key = await cacheKey('res', 'gitlab.gnome.org/GNOME/glib', 'issue:1234');
+    const key = await cacheKey('res', 'gitlab.gnome.org/GNOME/glib', 'issue#1234', 'cull', 'nopre');
     cacheStore.set(
       `https://released.example/__cache__/${encodeURIComponent(key)}`,
       new Response(JSON.stringify(seeded), { headers: { 'content-type': 'application/json' } }),
@@ -705,7 +706,7 @@ describe('web Worker — issue/PR internal endpoints (#79)', () => {
       rateLimit: null,
     };
     // Seed the slot the FIXED route keys on (Hono already decoded bad%25 → bad%).
-    const key = await cacheKey('res', 'gitlab.gnome.org/bad%', 'issue:1');
+    const key = await cacheKey('res', 'gitlab.gnome.org/bad%', 'issue#1', 'cull', 'nopre');
     cacheStore.set(
       `https://released.example/__cache__/${encodeURIComponent(key)}`,
       new Response(JSON.stringify(seeded), { headers: { 'content-type': 'application/json' } }),
@@ -721,7 +722,7 @@ describe('web Worker — issue/PR internal endpoints (#79)', () => {
 
   it('GET /internal/issue/... fails CLOSED when INTERNAL_SECRET is unset (no web-og fallback)', async () => {
     cacheStore.clear();
-    const key = await cacheKey('res', 'github.com/honojs/hono', 'issue:11');
+    const key = await cacheKey('res', 'github.com/honojs/hono', 'issue#11', 'cull', 'nopre');
     cacheStore.set(
       `https://released.example/__cache__/${encodeURIComponent(key)}`,
       new Response(