caracms 0.0.0-stage → 0.2.0

package/src/live/autosaves.ts

@@ -0,0 +1,306 @@
+/**
+ * Autosaves in Redis (M4 Decision 4), and the two small records beside them.
+ *
+ * - **`caracms:autosave:<file>`**: the whole document as the tab last sent it, with the
+ *   base it was edited from, its text (`applyEdits(base, document)`), its editor and
+ *   tab, and two times for the sweep: the first write since the last commit (the
+ *   five-minute cap) and the newest write (the idle time). Expires after a week, as a
+ *   backstop (`autosaveTtlMs`).
+ * - **`caracms:committed:<file>`**: what the sweep last committed from a tab's editing
+ *   session (its tab, its base, and the text it committed). The next commit from the
+ *   same session merges against that text, not the session's first base, so the
+ *   session's own earlier commit isn't mistaken for a change made elsewhere (no false
+ *   "also changed outside the editor" notice).
+ * - **`caracms:changed:<file>`**: who last changed the document and the version their
+ *   autosave left (Decision 11). Set by every autosave; a merge from `main` or the sweep
+ *   committing that person's own autosave leaves it alone. **It never expires** (one
+ *   small key per file), so it outlives Publish; only a flush loses it.
+ *
+ * **Creating and deleting** (M5a Decisions 11 and 12) go through the same autosave:
+ *
+ * - **A new document** is an autosave with `created: { over }`: `over` is what `drafts`
+ *   had at that path when it was created (null; or the file a pending deletion was
+ *   removing, when a document deleted since the last Publish is made again). Until the
+ *   sweep commits it, `over` is the merge's ancestor, not `base` (which is the new
+ *   document's first text, the base the creator's tab edits against). Later writes
+ *   carry `created` on until the commit.
+ * - **A deletion** is a "gone" autosave: `text` and `document` are null, and
+ *   `gone: { title }` keeps the document's title from before the removal (the waiting
+ *   list's and the commit message's name for it when `main` can't say). `base` is the
+ *   text the deleter's tab was on, so the merge's ancestor is worked out as for any
+ *   autosave. The sweep commits it as a removed file.
+ * - **`caracms:changed:`** records a deletion too (`gone: true`), so a viewer's tab
+ *   learns who deleted the document after the sweep has committed it.
+ *
+ * **Moves** (pre-M7 item 8): **`caracms:moves`**, a hash from a moved document's old
+ * file to its new file, kept until the move is published (`movesKey`). A move records
+ * itself here rather than being read off Site Settings' redirects, so it stays one
+ * "Moved" entry (and one headline item) whether or not the editor keeps the redirect.
+ * A move of a document moved since the last Publish extends its record (old → newest);
+ * moving it back to where it was drops the record, as does deleting it. A record only
+ * counts while its old file is gone and its new file is there (`movesIn`, git.ts).
+ *
+ * Paths are site-relative (`content/pages/index.json`). Values are JSON text.
+ */
+import type { AnyDocument } from '../document.ts';
+import type { Person } from './messages.ts';
+import type { RedisClient } from './redis.ts';
+import type { LiveTimings } from './timings.ts';
+
+export interface Autosave {
+	file: string;
+	/** The text the tab's edits were made against (the write body's `base`). */
+	base: string;
+	/**
+	 * What `drafts` had under this autosave, when `base` isn't it: a write made against
+	 * the text of an autosave the sweep hadn't committed yet (opened over it: a move's
+	 * Site Settings, say) keeps the replaced autosave's ancestor here. The merge's
+	 * ancestor when no session record applies (`ancestorFor`); absent, it's `base`.
+	 */
+	ancestor?: string;
+	/** Any kind of document (M5a). Null: the document is deleted (`gone`). */
+	document: AnyDocument | null;
+	/** `applyEdits(base, document)`: what the document reads as now. Null: deleted (`gone`). */
+	text: string | null;
+	editor: Person;
+	tab: string;
+	/** ms since the epoch: the first write since the last commit. */
+	firstAt: number;
+	/** ms since the epoch: the newest write. */
+	updatedAt: number;
+	/** The tab's own write sequence (`X-Caracms-Seq`), when it sent one: a lower one from the same tab is older. */
+	seq?: number | null;
+	/**
+	 * Ready for the sweep at once, with no idle wait (M5a Decision 10): Site Settings'
+	 * autosave, so `editors` and `brand` apply on the sweep's next tick. The sweep
+	 * commits it on that tick whatever its age (sweep.ts → `ready`).
+	 */
+	sweepAtOnce?: boolean;
+	/**
+	 * M5a: this autosave creates the document (Decision 11). `over` is the file `drafts`
+	 * had at that path then (usually null): the merge's ancestor until it's committed.
+	 */
+	created?: { over: string | null };
+	/** M5a: the document is deleted (Decision 12): `text` and `document` are null. `title` is its title before the removal. */
+	gone?: { title: string };
+}
+
+export interface Committed {
+	tab: string;
+	base: string;
+	/** The session's own text as committed (before any merge); null for a deletion. */
+	text: string | null;
+	at: number;
+	/** The editor's address, lower-cased (absent on records written before it was added). */
+	editor?: string;
+}
+
+/** Where an autosave's merge ancestor came from (sweep.ts logs anything but `session`/`base`). */
+export type AncestorFrom = 'session' | 'own-commit' | 'base' | 'created' | 'base, record from another tab' | 'base, record from someone else';
+
+export interface ChangeRecord {
+	/** Null: only merges from `main` have changed it (no editor has, since the record began). */
+	by: Person | null;
+	version: string;
+	/** ISO. */
+	at: string;
+	/** M5a: this change deleted the document (`by` deleted it). */
+	gone?: boolean;
+}
+
+/** A value with the raw text it was read as, for compare-and-swap. */
+export interface Read<T> {
+	raw: string;
+	value: T;
+}
+
+/** The Redis hash of moves waiting to publish (old file → new file). */
+export const movesKey = (prefix: string) => `${prefix}moves`;
+
+const parse = <T>(raw: string | null): T | null => {
+	if (raw === null) return null;
+	try {
+		return JSON.parse(raw) as T;
+	} catch {
+		return null;
+	}
+};
+
+export class Autosaves {
+	readonly redis: RedisClient;
+	readonly timings: LiveTimings;
+	readonly now: () => number;
+	readonly prefix: string;
+
+	constructor(redis: RedisClient, timings: LiveTimings, now: () => number, prefix = 'caracms:') {
+		this.redis = redis;
+		this.timings = timings;
+		this.now = now;
+		this.prefix = prefix;
+	}
+
+	key = (file: string) => `${this.prefix}autosave:${file}`;
+	private committedKey = (file: string) => `${this.prefix}committed:${file}`;
+	private changedKey = (file: string) => `${this.prefix}changed:${file}`;
+
+	async get(file: string): Promise<Read<Autosave> | null> {
+		const raw = await this.redis.get(this.key(file));
+		const value = parse<Autosave>(raw);
+		return raw !== null && value ? { raw, value } : null;
+	}
+
+	/** Every autosave: one SCAN and one MGET. */
+	async all(): Promise<Read<Autosave>[]> {
+		const keys = await this.redis.scan(`${this.prefix}autosave:*`);
+		if (keys.length === 0) return [];
+		const raws = await this.redis.mget(keys);
+		const out: Read<Autosave>[] = [];
+		raws.forEach((raw) => {
+			const value = parse<Autosave>(raw);
+			if (raw !== null && value) out.push({ raw, value });
+		});
+		return out;
+	}
+
+	/** Store it only if the autosave is still what was read (`null`: only if there's none), so a write that read an older one never replaces a newer. */
+	putIf(read: Read<Autosave> | null, autosave: Autosave): Promise<boolean> {
+		return this.redis.compareAndSet(this.key(autosave.file), read?.raw ?? null, JSON.stringify(autosave), { px: this.timings.autosaveTtlMs });
+	}
+
+	/** Delete it only if it's still what was read (a newer write wins). */
+	removeIf(read: Read<Autosave>): Promise<boolean> {
+		return this.redis.compareAndDelete(this.key(read.value.file), read.raw);
+	}
+
+	/** Replace it only if it's still what was read. */
+	replaceIf(read: Read<Autosave>, next: Autosave): Promise<boolean> {
+		return this.redis.compareAndSet(this.key(next.file), read.raw, JSON.stringify(next), { px: this.timings.autosaveTtlMs });
+	}
+
+	async committed(file: string): Promise<Committed | null> {
+		return parse<Committed>(await this.redis.get(this.committedKey(file)));
+	}
+
+	async setCommitted(file: string, record: Committed): Promise<void> {
+		await this.redis.set(this.committedKey(file), JSON.stringify(record), { px: this.timings.autosaveTtlMs });
+	}
+
+	async changed(file: string): Promise<ChangeRecord | null> {
+		return parse<ChangeRecord>(await this.redis.get(this.changedKey(file)));
+	}
+
+	/** Several files' records in one MGET (the documents list's "Last edited"), in the order asked; none: null. */
+	async changedMany(files: readonly string[]): Promise<(ChangeRecord | null)[]> {
+		if (files.length === 0) return [];
+		return (await this.redis.mget(files.map(this.changedKey))).map((raw) => parse<ChangeRecord>(raw));
+	}
+
+	/** No expiry: one small key per file, overwritten on each change, so "who changed it" is never forgotten while Redis keeps its data. */
+	async setChanged(file: string, record: ChangeRecord): Promise<void> {
+		await this.redis.set(this.changedKey(file), JSON.stringify(record));
+	}
+
+	/**
+	 * Record a change only if the file has no record yet (SET NX): a merge or fast-forward
+	 * from `main` leaves `{ by: null }` ("only merges"), and never overwrites an editor's.
+	 */
+	async setChangedIfAbsent(file: string, record: Omit<ChangeRecord, 'by'> & { by: Person | null }): Promise<void> {
+		await this.redis.set(this.changedKey(file), JSON.stringify(record), { nx: true });
+	}
+
+	/** Pre-M7 item 8: the moves waiting to publish, old file → new file. */
+	async moves(): Promise<Map<string, string>> {
+		return new Map(Object.entries(await this.redis.hgetall(movesKey(this.prefix))));
+	}
+
+	/**
+	 * A document moved from `from` to `to`. Moved since the last Publish already (a record
+	 * ends at `from`): that record now ends at `to`, or goes when `to` is where it started
+	 * (moved back). Otherwise a new record, only when `from` is live (`wasLive`): a page
+	 * made since the last Publish is just a new page at its new address.
+	 */
+	async recordMove(from: string, to: string, wasLive: boolean): Promise<void> {
+		const moves = await this.moves();
+		const earlier = [...moves].find(([, t]) => t === from)?.[0];
+		if (earlier !== undefined) {
+			if (earlier === to) await this.redis.hdel(movesKey(this.prefix), earlier);
+			else await this.redis.hset(movesKey(this.prefix), { [earlier]: to });
+		} else if (wasLive) await this.redis.hset(movesKey(this.prefix), { [from]: to });
+	}
+
+	/** A deleted document's move, if it was moved, is no move any more: it's a deletion. */
+	async forgetMoveTo(file: string): Promise<void> {
+		const moves = await this.moves();
+		const olds = [...moves].filter(([, t]) => t === file).map(([o]) => o);
+		if (olds.length) await this.redis.hdel(movesKey(this.prefix), ...olds);
+	}
+
+	/** The merge's ancestor for an autosave (Decision 6). See `ancestorFor`. */
+	async ancestorOf(autosave: Autosave): Promise<string | null> {
+		return (await this.ancestorFor(autosave)).text;
+	}
+
+	/**
+	 * The merge's ancestor for an autosave (Decision 6), so the editor's own earlier
+	 * commit from the same editing session is never read as a change made elsewhere:
+	 *
+	 * - **The same tab, the same base** (the session's last commit): that commit's text.
+	 * - **The same person and base, another tab id** (held edits re-sent from a reloaded
+	 *   or new tab, Use mine): per top-level key, the person's own committed value for
+	 *   each key this draft changed, and the base's value for every key it didn't. So
+	 *   their own commit isn't a conflict, and a key their other tab changed and this
+	 *   draft never touched is still taken from `drafts`, not undone.
+	 * - Otherwise (no record, another base, someone else): what `drafts` had under it (its
+	 *   `ancestor`, else its own base).
+	 * - **A new document not committed yet** (M5a, `created`): what `drafts` had at its
+	 *   path when it was made (`created.over`, usually null: the file didn't exist).
+	 */
+	async ancestorFor(autosave: Autosave): Promise<{ text: string | null; from: AncestorFrom }> {
+		if (autosave.created) return { text: autosave.created.over, from: 'created' };
+		const c = await this.committed(autosave.file);
+		const start = autosave.ancestor ?? autosave.base;
+		if (!c || c.base !== autosave.base) return { text: start, from: 'base' };
+		if (c.tab === autosave.tab) return { text: c.text, from: 'session' };
+		if (c.editor !== autosave.editor.email.toLowerCase()) return { text: start, from: 'base, record from someone else' };
+		if (autosave.text === null || c.text === null) return { text: start, from: 'base, record from another tab' };
+		const own = ownAncestor(autosave.base, autosave.text, c.text);
+		return own === null ? { text: start, from: 'base, record from another tab' } : { text: own, from: 'own-commit' };
+	}
+}
+
+const equal = (x: unknown, y: unknown): boolean => {
+	if (x === y) return true;
+	if (typeof x !== 'object' || typeof y !== 'object' || x === null || y === null || Array.isArray(x) !== Array.isArray(y)) return false;
+	const xk = Object.keys(x);
+	const yk = Object.keys(y);
+	return xk.length === yk.length && xk.every((k) => Object.hasOwn(y, k) && equal((x as Record<string, unknown>)[k], (y as Record<string, unknown>)[k]));
+};
+
+const object = (text: string): Record<string, unknown> | null => {
+	try {
+		const v = JSON.parse(text) as unknown;
+		return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+	} catch {
+		return null;
+	}
+};
+
+/**
+ * The per-key ancestor for a draft whose person already committed from the same base
+ * in another tab: the committed value where the draft changed a key, the base's where
+ * it didn't. Only values matter (merge.ts reads the ancestor's values, never its text),
+ * so it's plain JSON. Null when any side isn't a JSON object.
+ */
+function ownAncestor(base: string, draft: string, committed: string): string | null {
+	const b = object(base);
+	const d = object(draft);
+	const c = object(committed);
+	if (!b || !d || !c) return null;
+	const out: Record<string, unknown> = {};
+	for (const key of new Set([...Object.keys(b), ...Object.keys(c), ...Object.keys(d)])) {
+		const changed = Object.hasOwn(d, key) !== Object.hasOwn(b, key) || !equal(d[key], b[key]);
+		const from = changed ? c : b;
+		if (Object.hasOwn(from, key)) out[key] = from[key];
+	}
+	return JSON.stringify(out, null, 2);
+}