Skip to content
Merged
28 changes: 19 additions & 9 deletions src/server/codex-catalog-cache.ts
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ export function createCodexCatalogFetch(
) {
const memory = new Map<string, Entry>();
const invalidated = new Set<string>();
const replayNoted = new Set<string>();
const offSpec304Noted = new Set<string>();
const clock = options.now ?? Date.now;
const maxAge = options.maxAgeMs ?? 6 * 60 * 60 * 1000;
const fresh = (entry: unknown): entry is Entry =>
Expand Down Expand Up @@ -214,14 +214,24 @@ export function createCodexCatalogFetch(
if ([500, 502, 503, 504].includes(status)) return fresh(entry) ? cached(`temporary HTTP ${status}`, result) : result;
if (status === 304) {
if (!entry) return result;
// A 304 answers a CONDITIONAL request; this wrapper never
// sends If-None-Match, so a persistent one means the gateway
// revalidates unconditional GETs — and savedAt keeps resetting
// below, which would pin this cached catalog forever without
// any trace. Log once per credential so the loop is visible.
if (!replayNoted.has(key)) {
replayNoted.add(key);
log("warn", `[model-catalog] upstream answered 304 to an unconditional GET; replaying cached catalog as a full 200; age=${Math.floor((clock() - entry.savedAt) / 1000)}s`);
// A 304 only means "not modified" when THIS request was
// conditional — the wrapper itself never sends a validator,
// but the end client may have added if-none-match /
// if-modified-since and that negotiated 304 replays the
// cached 200 legitimately. An UNCONDITIONAL 304 is off-spec
// (some transparent middleboxes answer it anyway): treat it
// like any other unexpected status — drop the cache, pass
// the oddity through — instead of extending freshness on a
// phantom hit whose real headers we would also discard.
if (!headers.has("if-none-match") && !headers.has("if-modified-since")) {
// A gateway looping on this off-spec answer would otherwise
// stay invisible; one warn per credential makes it traceable.
if (!offSpec304Noted.has(key)) {
offSpec304Noted.add(key);
log("warn", `[model-catalog] upstream answered 304 to an unconditional GET; dropping cached catalog and passing the response through; age=${Math.floor((clock() - entry.savedAt) / 1000)}s`);
}
await invalidate();
return result;
}
await remember({ ...entry, savedAt: clock() });
discard(result);
Expand Down
18 changes: 16 additions & 2 deletions tests/codex-catalog-cache.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -127,15 +127,29 @@ test("malformed/empty/oversized successful catalog is forwarded but never rescue
}
});

test("temporary HTTP outages recover; 304 revalidation is a complete 200 catalog", async () => {
test("temporary HTTP outages recover; a NEGOTIATED 304 revalidation is a complete 200 catalog", async () => {
const f = createCodexCatalogFetch({ directory: null });
await send(f, async () => result());
for (const status of [500, 502, 503, 504]) assert.equal(await (await send(f, async () => result("outage", status))).response.text(), text);
const recovered = await send(f, async () => result(null, 304));
// The client revalidated (conditional header on the request), so the
// 304 replays the cached catalog as a full 200.
const conditional = { ...init, headers: { ...init.headers, "if-none-match": '"synthetic-v1"' } };
const recovered = await send(f, async () => result(null, 304), url, conditional);
assert.equal(recovered.response.status, 200);
assert.deepEqual(await recovered.response.json(), catalog);
});

test("an UNCONDITIONAL 304 is off-spec: no phantom hit — pass it through and drop the cache", async () => {
const f = createCodexCatalogFetch({ directory: null });
await send(f, async () => result());
// No if-none-match / if-modified-since on the request: nothing was
// revalidated, so a 304 from a broken middlebox must not extend
// freshness or masquerade as the catalog.
const odd = await send(f, async () => result(null, 304));
assert.equal(odd.response.status, 304, "the off-spec response is passed through untouched");
await assert.rejects(() => send(f, offline), /synthetic offline/, "cache invalidated, no phantom rescue");
});

test("outage does not renew cache age; expired and cold caches fail honestly", async () => {
let clock = 1000;
const f = createCodexCatalogFetch({
Expand Down
Loading