caracms 0.2.0 → 0.3.0

package/src/live/redis.ts

@@ -68,10 +68,24 @@ export interface RedisClient {
 	compareAndSet(key: string, expected: string | null, value: string, options?: { px?: number }): Promise<boolean>;
 	/** Delete `key` only if it holds `expected`. Atomic. For releasing a lock you hold. */
 	compareAndDelete(key: string, expected: string): Promise<boolean>;
+	/**
+	 * Several commands sent together (Redis diet Decision 7): ioredis's pipeline, one
+	 * round trip; the stand-in runs them in order. Replies come back in the commands'
+	 * order. Each command is billed and counted as one. A batch that failed in flight is
+	 * sent again only when every command in it is safe to send twice (see `connectRedis`).
+	 * A command that needs another's answer (an MGET of what a SCAN found) goes in the next batch.
+	 */
+	batch<const C extends readonly BatchCommand[]>(commands: C): Promise<BatchReplies<C>>;
 	/** Close the connection, if any. The client stays usable: the next command reconnects. */
 	close(): Promise<void>;
 }
 
+type BatchName = Exclude<keyof RedisClient, 'batch' | 'close'>;
+/** One command of a batch: its method's name and arguments, `['mget', keys]`, `['hgetall', key]`. */
+export type BatchCommand = { [K in BatchName]: readonly [K, ...Parameters<RedisClient[K]>] }[BatchName];
+/** The replies to a batch, as the methods of the same names give them. */
+export type BatchReplies<C extends readonly BatchCommand[]> = { -readonly [I in keyof C]: C[I] extends readonly [infer K extends BatchName, ...unknown[]] ? Awaited<ReturnType<RedisClient[K]>> : never };
+
 /** Redis couldn't be reached within the budget, or refused a command. `code` is the real socket error's. */
 export class RedisUnavailableError extends Error {
 	readonly code: string | null;
@@ -132,6 +146,86 @@ function withTimeout<T>(promise: Promise<T>, ms: number, what: string): Promise<
 }
 
 type Ioredis = InstanceType<typeof IORedis>;
+/** The client or a pipeline: the same calls, which a pipeline queues. */
+type Target = Record<string, (...args: unknown[]) => unknown>;
+
+/**
+ * How one command goes to ioredis: whether sending it twice is harmless, the call (to the
+ * client, or queued on a pipeline), and how its reply reads. `send: null`: the answer is
+ * known without asking (`answer`), so nothing is sent.
+ */
+interface Spec {
+	safe: boolean;
+	send: ((t: Target) => unknown) | null;
+	read: (c: Ioredis, reply: unknown) => unknown;
+	answer?: unknown;
+}
+
+const px = (ms: number) => Math.max(1, Math.round(ms));
+const asIs = (_c: Ioredis, reply: unknown) => reply;
+const isOne = (_c: Ioredis, reply: unknown) => reply === 1;
+const known = (answer: unknown): Spec => ({ safe: true, send: null, read: asIs, answer });
+const spec = (safe: boolean, name: string, args: unknown[], read: Spec['read'] = asIs): Spec => ({ safe, send: (t) => t[name]!(...args), read });
+
+function specOf(command: BatchCommand): Spec {
+	switch (command[0]) {
+		case 'get':
+		case 'pttl':
+		case 'hgetall':
+		case 'smembers':
+			return spec(true, command[0], [command[1]]);
+		case 'getdel':
+			return spec(false, 'getdel', [command[1]]);
+		case 'incr':
+			return spec(false, 'incr', [command[1]]);
+		case 'mget':
+			return command[1].length ? spec(true, 'mget', [...command[1]]) : known([]);
+		case 'set': {
+			const [, key, value, o = {}] = command;
+			const args: unknown[] = [key, value];
+			if (o.px !== undefined) args.push('PX', px(o.px));
+			if (o.nx) args.push('NX');
+			return spec(!o.nx, 'set', args, (_c, reply) => reply === 'OK');
+		}
+		case 'del': {
+			const [, ...keys] = command;
+			return keys.length ? spec(true, 'del', keys) : known(0);
+		}
+		case 'pexpire':
+			return spec(true, 'pexpire', [command[1], px(command[2])], isOne);
+		case 'hget':
+			return spec(true, 'hget', [command[1], command[2]]);
+		case 'hset':
+			return spec(true, 'hset', [command[1], command[2]]);
+		case 'hdel':
+		case 'sadd':
+		case 'srem': {
+			const [name, key, ...rest] = command;
+			return rest.length ? spec(true, name, [key, ...rest]) : known(0);
+		}
+		case 'scan': {
+			const pattern = command[1];
+			// The first page goes with the rest of a batch; any further pages follow on the same connection.
+			return spec(true, 'scan', ['0', 'MATCH', pattern, 'COUNT', SCAN_COUNT], async (c, reply) => {
+				let [cursor, page] = reply as [string, string[]];
+				const keys = new Set(page);
+				while (cursor !== '0') {
+					[cursor, page] = await c.scan(cursor, 'MATCH', pattern, 'COUNT', SCAN_COUNT);
+					for (const k of page) keys.add(k);
+				}
+				return [...keys];
+			});
+		}
+		case 'compareAndSet': {
+			const [, key, expected, value, o = {}] = command;
+			return spec(false, 'eval', [CAS_SET, 1, key, expected === null ? '1' : '0', expected ?? '', value, o.px === undefined ? '' : String(px(o.px))], isOne);
+		}
+		case 'compareAndDelete':
+			return spec(false, 'eval', [CAS_DEL, 1, command[1], command[2]], isOne);
+	}
+}
+
+const SCAN_COUNT = 200;
 
 /**
  * The real client. Nothing connects until the first command, and the connection
@@ -249,7 +343,8 @@ export function connectRedis(url: string, options: RedisOptions = {}): RedisClie
 					return await withTimeout(send(c), commandMs, 'Redis command');
 				} catch (error) {
 					const code = errorCode(error);
-					const lost = code === 'CARACMS_TIMEOUT' || /connection is closed|stream isn't writeable|command timed out/i.test(String((error as Error)?.message));
+					// A pipeline answered part way: ioredis aborts the rest ("Command aborted due to connection close").
+					const lost = code === 'CARACMS_TIMEOUT' || /connection is closed|stream isn't writeable|command timed out|aborted due to connection close/i.test(String((error as Error)?.message));
 					if (!lost) throw error; // Redis answered with an error: not ours to retry
 					drop(c);
 					if (!idempotent || Date.now() + backoffMs > deadline) {
@@ -264,45 +359,57 @@ export function connectRedis(url: string, options: RedisOptions = {}): RedisClie
 		}
 	};
 
+	/** One command, through `run`; one whose answer is known without asking (an MGET of no keys) isn't sent. */
+	const one = <T>(command: BatchCommand): Promise<T> => {
+		const s = specOf(command);
+		if (s.send === null) return Promise.resolve(s.answer as T);
+		return run(s.safe, async (c) => (await s.read(c, await s.send!(c as unknown as Target))) as T);
+	};
+
 	return {
-		get: (key) => run(true, (c) => c.get(key)),
-		mget: (keys) => (keys.length ? run(true, (c) => c.mget(...keys)) : Promise.resolve([])),
-		set: (key, value, o = {}) =>
-			run(!o.nx, async (c) => {
-				const args: (string | number)[] = [];
-				if (o.px !== undefined) args.push('PX', Math.max(1, Math.round(o.px)));
-				if (o.nx) args.push('NX');
-				const reply = await (c.set as (...a: unknown[]) => Promise<string | null>)(key, value, ...args);
-				return reply === 'OK';
-			}),
-		getdel: (key) => run(false, (c) => c.getdel(key)),
-		del: (...keys) => (keys.length ? run(true, (c) => c.del(...keys)) : Promise.resolve(0)),
-		incr: (key) => run(false, (c) => c.incr(key)),
-		pexpire: (key, ms) => run(true, async (c) => (await c.pexpire(key, Math.max(1, Math.round(ms)))) === 1),
-		pttl: (key) => run(true, (c) => c.pttl(key)),
-		hget: (key, field) => run(true, (c) => c.hget(key, field)),
-		hset: (key, fields) => run(true, (c) => c.hset(key, fields)),
-		hdel: (key, ...fields) => (fields.length ? run(true, (c) => c.hdel(key, ...fields)) : Promise.resolve(0)),
-		hgetall: (key) => run(true, (c) => c.hgetall(key)),
-		sadd: (key, ...members) => (members.length ? run(true, (c) => c.sadd(key, ...members)) : Promise.resolve(0)),
-		srem: (key, ...members) => (members.length ? run(true, (c) => c.srem(key, ...members)) : Promise.resolve(0)),
-		smembers: (key) => run(true, (c) => c.smembers(key)),
-		scan: (pattern) =>
-			run(true, async (c) => {
-				const keys = new Set<string>();
-				let cursor = '0';
-				do {
-					const [next, batch] = await c.scan(cursor, 'MATCH', pattern, 'COUNT', 200);
-					cursor = next;
-					for (const k of batch) keys.add(k);
-				} while (cursor !== '0');
-				return [...keys];
-			}),
-		compareAndSet: (key, expected, value, o = {}) =>
-			run(false, async (c) =>
-				(await c.eval(CAS_SET, 1, key, expected === null ? '1' : '0', expected ?? '', value, o.px === undefined ? '' : String(Math.max(1, Math.round(o.px))))) === 1,
-			),
-		compareAndDelete: (key, expected) => run(false, async (c) => (await c.eval(CAS_DEL, 1, key, expected)) === 1),
+		get: (key) => one(['get', key]),
+		mget: (keys) => one(['mget', keys]),
+		set: (key, value, o) => one(['set', key, value, o]),
+		getdel: (key) => one(['getdel', key]),
+		del: (...keys) => one(['del', ...keys]),
+		incr: (key) => one(['incr', key]),
+		pexpire: (key, ms) => one(['pexpire', key, ms]),
+		pttl: (key) => one(['pttl', key]),
+		hget: (key, field) => one(['hget', key, field]),
+		hset: (key, fields) => one(['hset', key, fields]),
+		hdel: (key, ...fields) => one(['hdel', key, ...fields]),
+		hgetall: (key) => one(['hgetall', key]),
+		sadd: (key, ...members) => one(['sadd', key, ...members]),
+		srem: (key, ...members) => one(['srem', key, ...members]),
+		smembers: (key) => one(['smembers', key]),
+		scan: (pattern) => one(['scan', pattern]),
+		compareAndSet: (key, expected, value, o) => one(['compareAndSet', key, expected, value, o]),
+		compareAndDelete: (key, expected) => one(['compareAndDelete', key, expected]),
+		// Redis diet Decision 7. ioredis answers a pipeline per command, `[error, reply]`, and
+		// a connection lost part way fills every unanswered one with "Connection is closed.":
+		// it can't say whether those ran (the command may have arrived, its answer not). So
+		// the batch is the unit: sent again whole when every command in it is safe to send
+		// twice, never when any isn't, and then it fails as a single unsafe command does.
+		batch: <const C extends readonly BatchCommand[]>(commands: C): Promise<BatchReplies<C>> => {
+			const specs = commands.map(specOf);
+			const sent = specs.filter((s) => s.send !== null);
+			if (sent.length === 0) return Promise.resolve(specs.map((s) => s.answer) as BatchReplies<C>);
+			return run(
+				sent.every((s) => s.safe),
+				async (c) => {
+					const pipeline = c.pipeline();
+					for (const s of sent) s.send!(pipeline as unknown as Target);
+					const results = await pipeline.exec();
+					if (!results) throw new Error('Redis gave no answer to the batch.');
+					const failed = results.find(([error]) => error);
+					if (failed) throw failed[0];
+					const out: unknown[] = [];
+					let i = 0;
+					for (const s of specs) out.push(s.send === null ? s.answer : await s.read(c, results[i++]![1]));
+					return out as BatchReplies<C>;
+				},
+			);
+		},
 		async close() {
 			if (idleTimer) clearTimeout(idleTimer);
 			idleTimer = null;
@@ -527,6 +634,21 @@ export function memoryRedis(options: { now?: () => number } = {}): MemoryRedis {
 			remove(key);
 			return true;
 		},
+		// Run in order, each counted; like a pipeline, every command runs and the first error is thrown after.
+		async batch<const C extends readonly BatchCommand[]>(commands: C): Promise<BatchReplies<C>> {
+			const out: unknown[] = [];
+			let failure: { error: unknown } | null = null;
+			for (const [name, ...args] of commands) {
+				try {
+					out.push(await (r[name] as (...a: unknown[]) => Promise<unknown>)(...args));
+				} catch (error) {
+					failure ??= { error };
+					out.push(null);
+				}
+			}
+			if (failure) throw failure.error;
+			return out as BatchReplies<C>;
+		},
 		async close() {},
 	};
 	return r;

package/src/live/runtime.ts

@@ -50,6 +50,8 @@ export interface RuntimeOptions {
 	log?: (line: string) => void;
 	runningCommit?: () => string | null;
 	railwayFetch?: typeof fetch;
+	/** Tests: the deploy hook's fetch. */
+	deployHookFetch?: typeof fetch;
 }
 
 /** Build and start a runtime (not shared: tests make their own). */
@@ -69,8 +71,9 @@ export async function createLiveRuntime(options: RuntimeOptions): Promise<LiveRu
 			backend = memory;
 		} else {
 			const tracker = new Tracker(now);
-			const { appId, privateKey, owner, repo } = settings.github;
-			backend = new GitHubBackend(new GitHubClient({ appId, privateKey, owner, repo, now }, tracker), settings.branches);
+			const gh = settings.github;
+			const connection = gh.kind === 'token' ? { token: gh.token, owner: gh.owner, repo: gh.repo, now } : { appId: gh.appId, privateKey: gh.privateKey, owner: gh.owner, repo: gh.repo, now };
+			backend = new GitHubBackend(new GitHubClient(connection, tracker), settings.branches);
 		}
 	}
 	const { main, drafts } = backend.branches;
@@ -86,7 +89,12 @@ export async function createLiveRuntime(options: RuntimeOptions): Promise<LiveRu
 		log,
 		runningCommit: options.runningCommit,
 		timings: settings.timings,
-		railway: settings.railway ? { ...settings.railway, fetch: options.railwayFetch } : null,
+		bakedCommit: settings.bakedCommit,
+		redeployer: settings.deployHook
+			? { kind: 'hook', url: settings.deployHook, fetch: options.deployHookFetch }
+			: settings.railway
+				? { kind: 'railway', ...settings.railway, fetch: options.railwayFetch }
+				: null,
 	});
 	// The copy only: the startup check waits for the live editor (editor.ts), which fills
 	// `commitPending` first, so a merge from main never runs ahead of pending autosaves (Decision 8).

package/src/live/status-cache.ts

@@ -0,0 +1,219 @@
+/**
+ * The status poll's write-through cache (Redis diet Decisions 1–5).
+ *
+ * Every Redis write a site makes goes through its one server, so what the status route
+ * reads can be kept here and updated (or dropped) by the writes themselves, instead of
+ * being asked of Redis on every poll.
+ *
+ * - **What it holds is Redis as last read or written here, by key**: strings, hashes,
+ *   sets, and scans (every key under a prefix, `caracms:autosave:`, with its value).
+ *   Records, never views made from them: whether a lock holds, or which notices are a
+ *   person's, is worked out per poll (Watch-outs).
+ * - **Only the status route reads it** (Decision 3). Writes, create, delete, move, the
+ *   sweep, Publish and sign-in read Redis directly.
+ * - **An entry is re-read once it's `statusCacheMs` old, counted from its last Redis
+ *   read** (Decision 1): a write-through keeps it current but doesn't make it younger, so
+ *   what bypasses this server (the other server during a deploy, a key expiring, a hand
+ *   edit) shows within that time (Decision 4).
+ * - **The writes are the modules'** (Decision 2): autosaves.ts, locks.ts, git.ts and
+ *   notices.ts tell it each write as it lands. A write it can apply exactly (a value just
+ *   set, a field just written) updates the entry; anything else (a compare-and-swap that
+ *   lost, so the value is unknown) drops it. A write to an entry not held is only noted.
+ * - **Refreshes are single-flight** (Decision 5): a poll needing an entry another poll is
+ *   already reading waits for that read. The ones it's missing go in one batch (SCANs
+ *   with the rest, then their MGETs). A refresh that fails caches nothing, and nothing
+ *   refreshes on a timer: with no poll there's no Redis read, so Redis can sleep.
+ * - **A write that lands while an entry is being read** may be missing from what the
+ *   read brings back: that entry is kept for the polls waiting on it, but as already
+ *   old, so the next poll reads it again.
+ */
+import type { BatchCommand, RedisClient } from './redis.ts';
+
+type Entry =
+	| { kind: 'string'; value: string | null; at: number }
+	| { kind: 'hash'; value: Map<string, string>; at: number }
+	| { kind: 'set'; value: Set<string>; at: number }
+	| { kind: 'scan'; value: Map<string, string>; at: number };
+
+type Kind = Entry['kind'];
+
+/** What a poll reads: keys by kind, and scans by key prefix (`caracms:lock:`). */
+export interface StatusReads {
+	scans?: readonly string[];
+	hashes?: readonly string[];
+	sets?: readonly string[];
+	strings?: readonly string[];
+}
+
+/** One poll's view of the cache. Its entries are the cache's own, so the poll's later write-throughs show in it. */
+export interface StatusSnapshot {
+	/** Every key under the prefix, with its value. */
+	scan(prefix: string): ReadonlyMap<string, string>;
+	hash(key: string): ReadonlyMap<string, string>;
+	set(key: string): ReadonlySet<string>;
+	string(key: string): string | null;
+}
+
+const name = (kind: Kind, key: string) => `${kind} ${key}`;
+
+export class StatusCache {
+	private readonly redis: RedisClient;
+	private readonly maxAgeMs: number;
+	private readonly now: () => number;
+	private readonly entries = new Map<string, Entry>();
+	private readonly reading = new Map<string, Promise<Map<string, Entry>>>();
+	/** Write-throughs so far, and the count at each entry's latest (for a read that a write overtook). */
+	private writes = 0;
+	private readonly written = new Map<string, number>();
+
+	constructor(options: { redis: RedisClient; maxAgeMs: number; now: () => number }) {
+		this.redis = options.redis;
+		this.maxAgeMs = options.maxAgeMs;
+		this.now = options.now;
+	}
+
+	/** What a poll reads, from memory where it's fresh enough, else from Redis (one batch, shared with any poll waiting on the same). */
+	async read(reads: StatusReads): Promise<StatusSnapshot> {
+		const wanted: [Kind, string][] = [
+			...(reads.scans ?? []).map((k) => ['scan', k] as [Kind, string]),
+			...(reads.hashes ?? []).map((k) => ['hash', k] as [Kind, string]),
+			...(reads.sets ?? []).map((k) => ['set', k] as [Kind, string]),
+			...(reads.strings ?? []).map((k) => ['string', k] as [Kind, string]),
+		];
+		const now = this.now();
+		const waits = new Set<Promise<Map<string, Entry>>>();
+		const missing: [Kind, string][] = [];
+		for (const [kind, key] of wanted) {
+			const n = name(kind, key);
+			const inFlight = this.reading.get(n);
+			if (inFlight) waits.add(inFlight);
+			else {
+				const e = this.entries.get(n);
+				if (!e || now - e.at >= this.maxAgeMs) missing.push([kind, key]);
+			}
+		}
+		if (missing.length) {
+			const read = this.refresh(missing);
+			for (const [kind, key] of missing) this.reading.set(name(kind, key), read);
+			const done = () => {
+				for (const [kind, key] of missing) if (this.reading.get(name(kind, key)) === read) this.reading.delete(name(kind, key));
+				if (this.reading.size === 0) this.written.clear();
+			};
+			read.then(done, done);
+			waits.add(read);
+		}
+		const fetched = new Map<string, Entry>();
+		for (const got of await Promise.all(waits)) for (const [n, e] of got) fetched.set(n, e);
+		// The cache's own entry where it still has one (later write-throughs land in it), else what the read brought back,
+		// pinned now: a drop while the poll is still in its writes leaves it the records it read, never none.
+		const pinned = new Map<string, Entry | undefined>(wanted.map(([kind, key]) => [name(kind, key), this.entries.get(name(kind, key)) ?? fetched.get(name(kind, key))]));
+		const pick = (kind: Kind, key: string) => pinned.get(name(kind, key));
+		return {
+			scan: (prefix) => (pick('scan', prefix)?.value as Map<string, string> | undefined) ?? new Map(),
+			hash: (key) => (pick('hash', key)?.value as Map<string, string> | undefined) ?? new Map(),
+			set: (key) => (pick('set', key)?.value as Set<string> | undefined) ?? new Set(),
+			string: (key) => (pick('string', key)?.value as string | null | undefined) ?? null,
+		};
+	}
+
+	/** Read these entries from Redis: one batch, then one more for the scans' MGETs. */
+	private async refresh(entries: [Kind, string][]): Promise<Map<string, Entry>> {
+		const started = this.writes;
+		const at = this.now();
+		const commands = entries.map(([kind, key]): BatchCommand => {
+			if (kind === 'scan') return ['scan', `${key}*`];
+			if (kind === 'hash') return ['hgetall', key];
+			if (kind === 'set') return ['smembers', key];
+			return ['get', key];
+		});
+		const replies = (await this.redis.batch(commands)) as unknown[];
+		const scanned = entries.flatMap(([kind], i) => (kind === 'scan' && (replies[i] as string[]).length ? [i] : []));
+		const values = scanned.length ? ((await this.redis.batch(scanned.map((i): BatchCommand => ['mget', replies[i] as string[]]))) as (string | null)[][]) : [];
+		const out = new Map<string, Entry>();
+		entries.forEach(([kind, key], i) => {
+			const n = name(kind, key);
+			// Written since this read began: kept for now, but already old.
+			const age = (this.written.get(n) ?? 0) > started ? -Infinity : at;
+			let entry: Entry;
+			if (kind === 'scan') {
+				const keys = replies[i] as string[];
+				const got = values[scanned.indexOf(i)] ?? [];
+				const map = new Map<string, string>();
+				keys.forEach((k, j) => {
+					const v = got[j];
+					if (v !== null && v !== undefined) map.set(k, v);
+				});
+				entry = { kind, value: map, at: age };
+			} else if (kind === 'hash') entry = { kind, value: new Map(Object.entries(replies[i] as Record<string, string>)), at: age };
+			else if (kind === 'set') entry = { kind, value: new Set(replies[i] as string[]), at: age };
+			else entry = { kind, value: replies[i] as string | null, at: age };
+			this.entries.set(n, entry);
+			out.set(n, entry);
+		});
+		return out;
+	}
+
+	// ── Write-throughs (the modules call these once a write has landed) ─────────────
+
+	/** Note a write to these entry names; return the ones held. */
+	private touch(names: string[]): Entry[] {
+		this.writes++;
+		const held: Entry[] = [];
+		for (const n of names) {
+			// Only a read in flight needs to know (`refresh`); with none, nothing is remembered.
+			if (this.reading.size) this.written.set(n, this.writes);
+			const e = this.entries.get(n);
+			if (e) held.push(e);
+		}
+		return held;
+	}
+
+	/** The scan entries (held or not) whose prefix this key is under. */
+	private scansOf(key: string): string[] {
+		const out: string[] = [];
+		for (const n of [...this.entries.keys(), ...this.reading.keys()]) if (n.startsWith('scan ') && key.startsWith(n.slice(5))) out.push(n);
+		return [...new Set(out)];
+	}
+
+	/** A string key now holds `value` (null: deleted). */
+	string(key: string, value: string | null): void {
+		for (const e of this.touch([name('string', key), ...this.scansOf(key)])) {
+			if (e.kind === 'string') e.value = value;
+			else if (e.kind === 'scan') {
+				if (value === null) e.value.delete(key);
+				else e.value.set(key, value);
+			}
+		}
+	}
+
+	/** A hash's fields were set, or deleted. */
+	hash(key: string, set: Record<string, string>, del: readonly string[] = []): void {
+		for (const e of this.touch([name('hash', key)])) {
+			if (e.kind !== 'hash') continue;
+			for (const [f, v] of Object.entries(set)) e.value.set(f, v);
+			for (const f of del) e.value.delete(f);
+		}
+	}
+
+	/** Members were added to a set. */
+	add(key: string, ...members: string[]): void {
+		for (const e of this.touch([name('set', key)])) if (e.kind === 'set') for (const m of members) e.value.add(m);
+	}
+
+	/** The key changed in a way not known here (a compare-and-swap that lost): forget it, and any scan it's under. */
+	drop(key: string): void {
+		const names = [...(['string', 'hash', 'set'] as const).map((k) => name(k, key)), ...this.scansOf(key)];
+		this.touch(names);
+		for (const n of names) this.entries.delete(n);
+	}
+}
+
+/** Run a write to `key`; one that fails (lost in flight, so it may or may not have landed) drops the key from the cache. */
+export async function landed<T>(cache: StatusCache | null, key: string, write: () => Promise<T>): Promise<T> {
+	try {
+		return await write();
+	} catch (error) {
+		cache?.drop(key);
+		throw error;
+	}
+}

package/src/live/status.ts

@@ -62,7 +62,11 @@ export interface PublishRecord {
 	tryAgainAt: string | null;
 }
 
-export type PublishState = 'publishing' | 'live' | 'failed';
+/**
+ * `slow` (runs-anywhere Decision 10): still not live well after it was made, or after its
+ * last Try again, with no failure known: "taking longer than usual. It may have failed."
+ */
+export type PublishState = 'publishing' | 'live' | 'failed' | 'slow';
 
 /** One GitHub Deployment and its newest status (null: no status yet). */
 export interface DeploymentFact {
@@ -76,7 +80,7 @@ const FINAL = new Set(['success', 'failure', 'error', 'inactive']);
 
 export interface PublishFacts {
 	record: PublishRecord;
-	/** The running server's commit (RAILWAY_GIT_COMMIT_SHA / CARACMS_RUNNING_COMMIT), or null with no deploy pipeline. */
+	/** The running server's commit (mode.ts → `runningCommitFrom`), or null with none known. */
 	running: string | null;
 	/** Is `running` the publish commit or a descendant of it? null when not known (not asked). */
 	runningIncludesPublish: boolean | null;
@@ -84,6 +88,9 @@ export interface PublishFacts {
 	laterOnMain: ReadonlySet<string>;
 	/** The repo's deployments, any order. */
 	deployments: DeploymentFact[];
+	/** Now (ms), and how long a publish may take before it reads as `slow` (`LiveTimings.publishSlowMs`). Either unset: never slow. */
+	now?: number;
+	slowAfterMs?: number;
 }
 
 /**
@@ -94,6 +101,10 @@ export interface PublishFacts {
  * - **failed**: the newest deployment that has *answered*, for the publish commit or
  *   a later commit on `main` (since the last Try again), says `failure` or `error`.
  *   A deployment stuck `in_progress` is never read as finished or failed.
+ * - **slow** (runs-anywhere Decision 10): not live and not failed, `slowAfterMs` after the
+ *   publish was made, or after its last Try again (`tryAgainAt`). Without deployments a
+ *   failure can never be known, and on Railway a skipped deploy stays `in_progress` for
+ *   good; a running commit that isn't in the repo never includes the publish either.
  * - **publishing**: otherwise.
  */
 export function publishState(f: PublishFacts): { state: PublishState; assumed: boolean } {
@@ -105,5 +116,6 @@ export function publishState(f: PublishFacts): { state: PublishState; assumed: b
 		.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
 	const newest = answered[0];
 	if (newest && (newest.state === 'failure' || newest.state === 'error')) return { state: 'failed', assumed: false };
+	if (f.now !== undefined && f.slowAfterMs !== undefined && f.now - Date.parse(f.record.tryAgainAt ?? f.record.at) >= f.slowAfterMs) return { state: 'slow', assumed: false };
 	return { state: 'publishing', assumed: false };
 }

package/src/live/timings.ts

@@ -29,6 +29,22 @@ export interface LiveTimings {
 	autosaveTtlMs: number;
 	/** Decision 13: each tab polls the status this often (the editor's POLL_MS; /admin passes it to the page). */
 	pollMs: number;
+	/** Runs-anywhere Decision 10: a publish not live this long after it was made (or its last Try again) reads as taking longer than usual. */
+	publishSlowMs: number;
+	/** Runs-anywhere (Watch-outs): Publish's request answers by this long, well inside Cloudflare's 100 s; the Publish carries on past it. */
+	publishAnswerMs: number;
+	/** Redis diet Decision 1: the status poll's cached reads are re-read from Redis once this old (counted from the last Redis read). */
+	statusCacheMs: number;
+	/** Redis diet Decision 6: a tab's heartbeat goes only once its lock's last beat is this old (or to take the lock back). */
+	beatEveryMs: number;
+	/** Redis diet Decision 8: a visible tab with no input this long polls at `slowPollMs` (/admin passes it to the page). */
+	idleSlowAfterMs: number;
+	/** Redis diet Decision 8: an idle tab's poll interval (/admin passes it to the page). */
+	slowPollMs: number;
+	/** Redis diet Decision 10: once the tab holds the document, a keep goes this long after the last change (/admin passes it to the page). */
+	keepDelayMs: number;
+	/** Redis diet Decision 10: …and never later than this after the first change not yet sent (/admin passes it to the page). */
+	keepCapMs: number;
 }
 
 export const DEFAULT_TIMINGS: LiveTimings = {
@@ -44,4 +60,12 @@ export const DEFAULT_TIMINGS: LiveTimings = {
 	presenceMs: 15_000,
 	autosaveTtlMs: 7 * 24 * 60 * 60_000,
 	pollMs: 5000,
+	publishSlowMs: 15 * 60_000,
+	publishAnswerMs: 60_000,
+	statusCacheMs: 30_000,
+	beatEveryMs: 30_000,
+	idleSlowAfterMs: 2 * 60_000,
+	slowPollMs: 30_000,
+	keepDelayMs: 3000,
+	keepCapMs: 15_000,
 };

package/src/media.ts

@@ -25,7 +25,7 @@
  */
 import { createHmac } from 'node:crypto';
 import type { ImageFormat } from './fields.ts';
-import type { RenderImage } from './media-value.ts';
+import { renderMedia, type RenderImage } from './media-value.ts';
 
 /** The srcset width ladder every fluid image draws from (Decision 2). 1920 at the top: imgproxy doesn't upscale. */
 export const IMAGE_WIDTHS: readonly number[] = [160, 320, 480, 640, 960, 1280, 1920];
@@ -253,3 +253,28 @@ export function brandImageUrl(key: string, cssHeight: number, config: MediaConfi
 	if (config.kind !== 'ready') return null;
 	return imageUrl(config.settings, key, { height: cssHeight * 2 });
 }
+
+/**
+ * Urban Return port, Decision 20: one URL for a Site Settings image, for the page's frame
+ * (a header, a footer, a layout), which has no block's `cms` for `<Media>`. Exported from
+ * `caracms/content`:
+ *
+ *   const settings = await siteSettings(site, Astro.locals);
+ *   const url = settingsImageUrl(settings.megaPhoto, { width: 640, height: 400 });
+ *
+ * `value` is the field as `siteSettings` gives it (resolved, M9), or the stored value. The
+ * rules are `<Media>`'s: the signed imgproxy URL, `fit` to one side, `fill` to both with the
+ * focal point's gravity, a GIF or an SVG passed through unresized, WebP; under
+ * `CARACMS_MEDIA=memory` the in-memory media's URL. No size: `fit` at the ladder's top rung.
+ * Null for an empty value (or a clip, or a file's key) and when the media isn't set up.
+ */
+export function settingsImageUrl(value: unknown, options: { width?: number; height?: number } = {}): string | null {
+	const image = renderMedia(value, { only: 'image' });
+	if (!image || image.kind !== 'image') return null;
+	const config = readMediaConfig();
+	if (config.kind !== 'ready') return null;
+	const width = options.width ?? 0;
+	const height = options.height ?? 0;
+	const sized = width > 0 || height > 0 ? { width, height } : { width: IMAGE_WIDTHS[IMAGE_WIDTHS.length - 1]! };
+	return imageUrl(config.settings, image.key, { ...sized, focal: image.focal });
+}