An Image Requested Once Before Its Upload Stayed a 404 at the Edge. I Split the Retention Rules by Status Code and Made Upload and Purge a Single Step

// clock.mjs — a clock you advance by hand, so a one-year retention never has to be waited out
export class FakeClock {
  #now = 0;
  now() { return this.#now; }
  advance(sec) { this.#now += sec; }
}

// edge.mjs — a model of the edge cache's retention rule only (not a re-creation of any CDN's internals)
// Key = path + query. A policy picks the retention seconds per response; on expiry the edge refetches.
export class Edge {
  constructor({ clock, origin, policy }) {
    this.clock = clock; this.origin = origin; this.policy = policy;
    this.store = new Map();
    this.originHits = 0;
  }
  get(url) {
    const now = this.clock.now();
    const hit = this.store.get(url);
    if (hit && now < hit.expiresAt) return { ...hit.res, cache: "HIT" };
    const res = this.origin.get(url);       // refetch (MISS or EXPIRED)
    this.originHits += 1;
    const ttl = this.policy(res.status);
    if (ttl > 0) this.store.set(url, { res, expiresAt: now + ttl });
    else this.store.delete(url);
    return { ...res, cache: hit ? "EXPIRED" : "MISS" };
  }
  purge(url) { this.store.delete(url); }
}
 
export class Origin {
  constructor() { this.files = new Map(); this.down = false; }
  upload(path, bytes) { this.files.set(path, bytes); }
  get(url) {
    const path = url.split("?")[0];
    if (this.down) return { status: 503, bytes: 0 };
    return this.files.has(path)
      ? { status: 200, bytes: this.files.get(path) }
      : { status: 404, bytes: 0 };
  }
}

// policies.mjs — the retention rules before and after, as a table of seconds
const YEAR = 365 * 24 * 3600;
export const before = (status) => (status === 200 || status === 404 ? YEAR : 0);         // 404 kept for a year too
export const after  = (status) => (status === 200 ? YEAR : status === 404 ? 60 : 0);     // 404 for 60 s; 5xx never kept

// timeline.mjs — when does an image that was requested once before its upload become visible?
import { FakeClock } from "./clock.mjs";
import { Edge, Origin } from "./edge.mjs";
import { before, after } from "./policies.mjs";
 
function run(name, policy) {
  const clock = new FakeClock(); const origin = new Origin();
  const edge = new Edge({ clock, origin, policy });
  const path = "/img/new_wall_0412.jpg";
  const rows = [];
  const hit = (label) => { const r = edge.get(path); rows.push([label, r.status, r.cache]); return r; };
  hit("prefetch before upload");
  clock.advance(30); origin.upload(path, 480_000);
  hit("right after upload (+30 s)");
  clock.advance(45); hit("+75 s");
  clock.advance(3600); hit("+about 1 hour");
  // count the seconds until it becomes visible
  const probe = new Edge({ clock: new FakeClock(), origin: new Origin(), policy });
  const o = probe.origin; probe.get(path); o.upload(path, 480_000);
  let t = 0; const step = 15;
  while (t < 2 * 365 * 24 * 3600) { probe.clock.advance(step); t += step; if (probe.get(path).status === 200) break; }
  console.log(`\n== ${name}`);
  for (const [l, s, c] of rows) console.log(`  ${l.padEnd(28)} status=${s} cache=${c}`);
  console.log(`  -> seconds from upload until 200: ${t >= 2*365*24*3600 ? "still not 200 after 2 years" : t}`);
}
run("before (404 kept for 1 year)", before);
run("after (404 kept for 60 s)", after);

// load.mjs — shortening the 404 lifetime sends more lookups to the origin. Count the price.
import { FakeClock } from "./clock.mjs";
import { Edge, Origin } from "./edge.mjs";
const YEAR = 365 * 24 * 3600;
const cases = {
  "404 = 1 year ": (s) => (s === 200 || s === 404 ? YEAR : 0),
  "404 = 60 s   ": (s) => (s === 200 ? YEAR : s === 404 ? 60 : 0),
  "404 = no keep": (s) => (s === 200 ? YEAR : 0),
};
console.log("One missing image, one request per second, for 10 minutes (600 requests)");
for (const [name, policy] of Object.entries(cases)) {
  const clock = new FakeClock(); const edge = new Edge({ clock, origin: new Origin(), policy });
  for (let i = 0; i < 600; i++) { edge.get("/img/ghost.jpg"); clock.advance(1); }
  console.log(`  ${name} requests that reached the origin: ${String(edge.originHits).padStart(3)}`);
}
 
console.log("\nOrigin returns 503 for 5 minutes, then recovers (one request per second throughout)");
const five = {
  "5xx kept (wrong)": (s) => (s === 200 ? YEAR : 3600),
  "5xx not kept    ": (s) => (s === 200 ? YEAR : s === 404 ? 60 : 0),
};
for (const [name, policy] of Object.entries(five)) {
  const clock = new FakeClock(); const origin = new Origin(); origin.upload("/img/ok.jpg", 300_000);
  const edge = new Edge({ clock, origin, policy });
  origin.down = true;
  for (let i = 0; i < 300; i++) { edge.get("/img/ok.jpg"); clock.advance(1); }
  origin.down = false;
  const later = [];
  for (const wait of [1, 60, 600]) { clock.advance(wait); later.push(edge.get("/img/ok.jpg").status); }
  console.log(`  ${name} status after recovery (+1 s / +61 s / +661 s): ${later.join(" / ")}`);
}

// probe.mjs — "not on the origin yet" or "the edge is holding a 404"? Two requests tell them apart.
// A plain URL and a URL with a query string (a different cache key) are read side by side.
export function diagnose(edge, path, nonce) {
  const plain = edge.get(path);
  const fresh = edge.get(`${path}?probe=${nonce}`);
  let verdict;
  if (plain.status === 200 && fresh.status === 200) verdict = "ok";
  else if (plain.status === 404 && fresh.status === 404) verdict = "origin-missing";   // really absent: suspect the upload
  else if (plain.status === 404 && fresh.status === 200) verdict = "edge-holding-404"; // the origin has it; the edge holds a memory of 404
  else verdict = `other(${plain.status}/${fresh.status})`;
  return { path, plain: plain.status, fresh: fresh.status, plainCache: plain.cache, verdict };
}

// sweep.mjs — diagnose newly added images in order; purge only those the edge is holding a 404 for
import { FakeClock } from "./clock.mjs";
import { Edge, Origin } from "./edge.mjs";
import { before } from "./policies.mjs";
import { diagnose } from "./probe.mjs";
 
const clock = new FakeClock(); const origin = new Origin();
const edge = new Edge({ clock, origin, policy: before });          // recreate the state under the old rule
const added = ["/img/w_0410.jpg", "/img/w_0411.jpg", "/img/w_0412.jpg", "/img/w_0413.jpg"];
 
edge.get("/img/w_0412.jpg"); edge.get("/img/w_0413.jpg");          // the catalog update arrived first; two were fetched early
clock.advance(40);
for (const p of added.slice(0, 3)) origin.upload(p, 400_000);      // only w_0413 is late
let n = 0;
const report = added.map((p) => diagnose(edge, p, ++n));
for (const r of report) console.log(`${r.path.padEnd(18)} plain=${r.plain}(${r.plainCache}) fresh=${r.fresh} -> ${r.verdict}`);
 
for (const r of report) if (r.verdict === "edge-holding-404") edge.purge(r.path);   // only the held ones, one at a time
console.log("\nAfter purging (w_0413 is still missing on the origin, so I left it alone)");
for (const p of added.slice(0, 3)) console.log(`${p.padEnd(18)} -> ${edge.get(p).status}`);
 
// w_0413 arrives late. Upload only, versus upload and purge as one step
clock.advance(600);
const uploadOnly = (p) => origin.upload(p, 400_000);
const uploadAndPurge = (p) => { origin.upload(p, 400_000); edge.purge(p); };
uploadOnly("/img/w_0413.jpg");
console.log(`\nw_0413, upload only -> ${edge.get("/img/w_0413.jpg").status} (${edge.get("/img/w_0413.jpg").cache})`);
origin.files.delete("/img/w_0413.jpg"); edge.purge("/img/w_0413.jpg"); edge.get("/img/w_0413.jpg"); // rebuild the same situation
uploadAndPurge("/img/w_0413.jpg");
console.log(`w_0413, upload and purge as one step -> ${edge.get("/img/w_0413.jpg").status}`);

// plan.mjs — before changing the retention rules, save the current settings and print the diff and the way back (it touches no real setting)
import { writeFileSync, readFileSync, existsSync } from "node:fs";
 
const current = { 200: "1y", 404: "1y", "5xx": "unset" };  // read the current values off the dashboard and copy them by hand (example values here)
const target  = { 200: "1y", 404: "60s", "5xx": "none" };
 
if (!existsSync("rules.before.json")) writeFileSync("rules.before.json", JSON.stringify(current, null, 2));
const saved = JSON.parse(readFileSync("rules.before.json", "utf8"));   // when rolling back, this file is the source of truth
 
for (const k of Object.keys(target)) {
  const from = saved[k], to = target[k];
  console.log(`${String(k).padEnd(4)} ${from.padEnd(5)} -> ${to.padEnd(5)} ${from === to ? "(unchanged)" : `roll back to: ${from}`}`);
}

// App side: do not prefetch images until the catalog says they are ready
// (give each catalog item a ready flag; the server sets it after upload and purge are done)
type CatalogItem = { id: string; path: string; ready: boolean };
 
export function visibleItems(items: CatalogItem[]): CatalogItem[] {
  return items.filter((i) => i.ready);   // items that are not ready appear neither in the list nor in prefetching
}

curl -sI "https://example.com/img/new_wall.jpg" | grep -iE "^(HTTP|age|cache|x-cache|cf-cache)"