caracms 0.0.0-stage → 0.2.0

package/src/live/editor.ts

@@ -0,0 +1,465 @@
+/**
+ * Live mode's editor server (M4 Phase 2): the live drafts store, the sweep, locks and
+ * presence, and the handlers behind `/_caracms/status`, `lock`, `publish`, `history`,
+ * `try-again` and `notice` (the routes in ../editor/routes/ are one line each).
+ *
+ * One per process, beside the runtime (`liveEditor`), or made by tests
+ * (`createLiveEditor`) on a runtime from `createLiveRuntime` with the in-memory
+ * backend, the Redis stand-in and a fake clock.
+ *
+ * Every handler takes the request and the signed-in person (Phase 3's guard puts it
+ * in `locals`; locals.ts). **No person is a 401 `{ error: 'signed-out' }`**: defence in
+ * depth, the guard is the real check. A request that isn't GET also has to come from
+ * this site (write.ts → checkOrigin). Redis out past its budget is a 503 `unavailable`.
+ *
+ * **A poll asks GitHub for nothing** beyond `git.check()` (once a minute) and the
+ * deployment reads while a publish is in flight (git.ts, every 10 s at most).
+ *
+ * State lives in Redis and git (two servers run during a deploy); what's held here
+ * is the sweep's "am I ticking" and git.ts's caches.
+ */
+import { SITE_SETTINGS_FILE, type ResolvedSite } from '../config.ts';
+import { brandFrom, editorBrand } from '../editor/brand.ts';
+import type { DraftsStore } from '../editor/server/drafts-store.ts';
+import { handleCreate, handleDelete } from '../editor/server/create.ts';
+import { checkOrigin, confinePath, fileVersion, handleWrite, tabOf, WriteRefused } from '../editor/server/write.ts';
+import { missingAltIn } from '../editor/server/media/alt.ts';
+import type {
+	ApiError,
+	HistoryResponse,
+	LockRefusal,
+	LockResponse,
+	MissingAltView,
+	NoticeView,
+	PublishResponse,
+	PublishView,
+	StatusResponse,
+	TryAgainResponse,
+	WaitingView,
+} from '../editor/types.ts';
+import { Autosaves } from './autosaves.ts';
+import { lastChangeOf, liveDraftsStore, unavailable } from './drafts-store.ts';
+import { movesIn, titleOf } from './git.ts';
+import { parseRedirects, type Redirect } from '../redirects.ts';
+import { Locks } from './locks.ts';
+import { displayName, type Person } from './messages.ts';
+import type { LiveSettings } from './mode.ts';
+import { RedisUnavailableError } from './redis.ts';
+import { liveRuntime, type LiveRuntime } from './runtime.ts';
+import { Sweep, type Schedule } from './sweep.ts';
+
+type Handler = (request: Request, person: Person | null) => Promise<Response>;
+
+export interface LiveEditor {
+	readonly runtime: Pick<LiveRuntime, 'site' | 'settings' | 'git' | 'redis' | 'timings' | 'now'>;
+	readonly autosaves: Autosaves;
+	readonly locks: Locks;
+	readonly sweep: Sweep;
+	readonly store: DraftsStore;
+	write: Handler;
+	/** M5a Phase 3: POST /_caracms/create and /_caracms/delete over the live store (the routes call the store the same way). */
+	create: Handler;
+	delete: Handler;
+	status: Handler;
+	lock: Handler;
+	publish: Handler;
+	history: Handler;
+	tryAgain: Handler;
+	notice: Handler;
+}
+
+export interface LiveEditorOptions {
+	/** The sweep's timer (tests drive it by hand). */
+	schedule?: Schedule;
+	sleep?: (ms: number) => Promise<void>;
+	log?: (line: string) => void;
+	prefix?: string;
+}
+
+const HEADERS = { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' };
+const json = (status: number, body: unknown) => new Response(JSON.stringify(body), { status, headers: HEADERS });
+const sameEmail = (a: Person, b: Person) => a.email.toLowerCase() === b.email.toLowerCase();
+
+/** A notice id: `kept:<file>:<commit>` or `stood:<commit>:<file>:<email>`, no spaces or controls, capped. */
+const NOTICE_ID = /^(kept|stood):[^\s\p{C}]+$/u;
+const NOTICE_ID_MAX = 512;
+
+interface StoodNotice {
+	id: string;
+	for: string;
+	file: string;
+	title: string;
+	by: Person;
+	at: string;
+}
+
+/** Map a site file to its document (collection and path), or nulls. */
+/** Site Settings' redirects, from its text (none when it's missing or unreadable). */
+function redirectsIn(text: string | null): Redirect[] {
+	try {
+		return parseRedirects((JSON.parse(text ?? '{}') as { redirects?: unknown }).redirects);
+	} catch {
+		return [];
+	}
+}
+
+function docOf(site: Pick<ResolvedSite, 'root' | 'collections'>, file: string): { collection: string | null; path: string | null } {
+	try {
+		const c = confinePath(site as ResolvedSite, file);
+		return { collection: c.collection, path: c.path };
+	} catch {
+		return { collection: null, path: null };
+	}
+}
+
+export async function createLiveEditor(
+	runtime: Pick<LiveRuntime, 'site' | 'settings' | 'git' | 'redis' | 'timings' | 'now'>,
+	options: LiveEditorOptions = {},
+): Promise<LiveEditor> {
+	const { site, settings, git, redis, timings, now } = runtime;
+	const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+	const prefix = options.prefix ?? 'caracms:';
+	const log = options.log ?? ((line: string) => console.log(`[caracms] ${line}`));
+	const autosaves = new Autosaves(redis, timings, now, prefix);
+	const locks = new Locks(redis, timings, now, async (file) => (await autosaves.get(file)) !== null, prefix);
+	const sweep = new Sweep({ redis, git, autosaves, locks, timings, now, schedule: options.schedule, sleep: options.sleep, log, prefix });
+	const store = liveDraftsStore({ site, git, autosaves, locks, sweep, now });
+	// Publish's step 1 and Decision 8's "commit every pending autosave first".
+	git.commitPending = async () => {
+		await sweep.commitAll();
+	};
+	// Decision 11: a file main changed that no editor has a record for reads "only merges"
+	// (`by: null`, known), not unknown. An editor's record is never overwritten.
+	git.tookIn = async (files) => {
+		const at = new Date(now()).toISOString();
+		for (const { file, text } of files) await autosaves.setChangedIfAbsent(file, { by: null, version: fileVersion(text), at });
+	};
+	await sweep.start().catch((error: unknown) => log(`sweep: the startup check failed (${error instanceof Error ? error.message : String(error)}); the next autosave starts it`));
+	// Decision 8's startup check, here and not in the runtime's start: only now is the
+	// hook above in place, so a merge from main commits every pending autosave first.
+	await git.check({ force: true }).catch((error: unknown) => log(`check at startup: ${error instanceof Error ? error.message : String(error)}`));
+
+	const keys = {
+		publishLock: `${prefix}publish:lock`,
+		dismissed: `${prefix}dismissed`,
+		notices: `${prefix}notices`,
+	};
+
+	/** Common gate: a person, the same origin for anything but GET, Redis outages as 503. */
+	const handler =
+		(methods: string[], fn: (request: Request, person: Person) => Promise<Response>): Handler =>
+		async (request, person) => {
+			try {
+				if (!methods.includes(request.method)) {
+					return new Response(JSON.stringify({ error: `This route takes ${methods.join(' or ')}.` } satisfies ApiError), {
+						status: 405,
+						headers: { ...HEADERS, Allow: methods.join(', ') },
+					});
+				}
+				if (!person) return json(401, { error: 'signed-out', code: 'signed-out' } satisfies ApiError);
+				if (request.method !== 'GET') checkOrigin(request);
+				return await fn(request, person);
+			} catch (error) {
+				const refused = error instanceof RedisUnavailableError ? unavailable(error) : error;
+				if (refused instanceof WriteRefused) return json(refused.status, { error: refused.message, ...refused.body });
+				log(`${new URL(request.url).pathname} failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+				return json(502, { error: `That didn't work (${error instanceof Error ? error.message : String(error)}).` } satisfies ApiError);
+			}
+		};
+
+	const readBody = async (request: Request): Promise<Record<string, unknown>> => {
+		const raw = await request.text();
+		if (raw.length > 16_384) throw new WriteRefused(413, 'That body is too large.');
+		try {
+			const body = JSON.parse(raw || '{}') as unknown;
+			if (body && typeof body === 'object' && !Array.isArray(body)) return body as Record<string, unknown>;
+		} catch {
+			/* below */
+		}
+		throw new WriteRefused(400, 'Send a JSON object.');
+	};
+
+	/** Is there a document at this file: in the copy, or a new one's autosave, and not deleted (M5a)? */
+	const exists = async (file: string): Promise<boolean> => {
+		const save = (await autosaves.get(file))?.value;
+		return save ? !save.gone : git.read(file) !== null;
+	};
+
+	/** A document file that exists (the copy, or a new document's autosave), or a 400/404. */
+	const documentFile = async (file: unknown): Promise<string> => {
+		const target = confinePath(site, file);
+		if (!(await exists(file as string))) throw new WriteRefused(404, `${site.collections[target.collection]!.label}: no document "${target.path}".`);
+		return file as string;
+	};
+
+	// The alt list per waiting document, kept while its text stays the same (the poll asks every 5 s).
+	const altKept = new Map<string, { text: string; list: MissingAltView[] }>();
+	const missingAltOf = (file: string, collection: string | null, text: string | null): MissingAltView[] => {
+		if (text === null) return [];
+		const kept = altKept.get(file);
+		if (kept && kept.text === text) return kept.list;
+		const list = missingAltIn(site, collection, text);
+		if (altKept.size > 500) altKept.clear();
+		altKept.set(file, { text, list });
+		return list;
+	};
+
+	const publishView = async (): Promise<PublishView> => {
+		const running = (await redis.get(keys.publishLock)) !== null;
+		let st;
+		try {
+			st = await git.publishStatus();
+		} catch (error) {
+			log(`publish status: ${error instanceof Error ? error.message : String(error)}`);
+			const record = await git.lastPublish();
+			st = { state: record ? ('publishing' as const) : ('none' as const), record, assumed: false, canTryAgain: false };
+		}
+		return { state: st.state, running, record: st.record, assumed: st.assumed, canTryAgain: st.canTryAgain, hasToken: settings.railway !== null };
+	};
+
+	const notices = async (person: Person): Promise<NoticeView[]> => {
+		const dismissed = new Set(await redis.smembers(keys.dismissed));
+		const out: NoticeView[] = [];
+		for (const n of git.keptDraftNotices()) {
+			const id = `kept:${n.file}:${n.commit}`;
+			if (!dismissed.has(id)) out.push({ id, kind: 'draft-kept', file: n.file, title: git.titleFor(n.file) });
+		}
+		for (const raw of Object.values(await redis.hgetall(keys.notices))) {
+			try {
+				const n = JSON.parse(raw) as StoodNotice;
+				if (n.for === person.email.toLowerCase()) out.push({ id: n.id, kind: 'published-as-it-stood', file: n.file, title: n.title, by: n.by, at: n.at });
+			} catch {
+				/* skip */
+			}
+		}
+		return out;
+	};
+
+	// The write route: M3's handler over the live store, which answers 401 with no person.
+	const write: Handler = (request, person) => handleWrite(request, store, { person });
+	// M5a Phase 3: creating and deleting, the same way (editor/server/create.ts over the live store).
+	const create: Handler = (request, person) => handleCreate(request, store, { person });
+	const remove: Handler = (request, person) => handleDelete(request, store, { person });
+
+	const status = handler(['GET'], async (request, person) => {
+		const url = new URL(request.url);
+		const tab = tabOf(request);
+		const asked = url.searchParams.get('file');
+		let file: string | null = null;
+		// Any document path: one deleted since the tab opened it is answered with who deleted it (M5a), not a 404.
+		if (asked) {
+			confinePath(site, asked);
+			file = asked;
+		}
+		// The heartbeat and presence ride on the poll (Decisions 9 and 13). `input` is how long
+		// ago someone typed, clicked or scrolled in the tab: an idle tab stops renewing its lock,
+		// so it lapses by itself (Take over, 2026-10-15). A tab that doesn't say is treated as active.
+		const input = Number(url.searchParams.get('input'));
+		const active = !url.searchParams.has('input') || !(input >= timings.lockIdleMs);
+		if (tab) {
+			await locks.present(tab, person, file);
+			if (file && active) await locks.beat(file, tab, person);
+		}
+		// Decision 8's check, throttled to once a minute and shared inside git.ts. Started, not
+		// awaited: the poll answers with what's known, and never waits on GitHub.
+		void git.check().catch((error: unknown) => log(`check: ${error instanceof Error ? error.message : String(error)}`));
+
+		const saves = (await autosaves.all()).map((r) => r.value);
+		if (saves.length) sweep.poke(); // they may have come in on the other server during a deploy
+		const pending = new Set(saves.map((a) => a.file));
+		const presence = await locks.presence();
+		const lockViews = [...(await locks.all())]
+			.filter(([f, r]) => locks.holds(r.lock, pending.has(f)))
+			.map(([f, r]) => locks.view(f, r.lock, tab, person));
+
+		// "Editing now" (the mockup's "Aoife is still in it"): someone other than this tab holds the lock.
+		const editingNow = (f: string): Person[] => {
+			const l = lockViews.find((x) => x.file === f);
+			return l && l.mine !== 'this-tab' ? [l.person] : [];
+		};
+		const waiting = new Map<string, WaitingView>();
+		for (const w of git.waiting()) waiting.set(w.file, { ...w, ...docOf(site, w.file), uncommitted: false, editingNow: editingNow(w.file), missingAlt: [] });
+		for (const a of saves) {
+			// M5a: new, deleted or changed, against main. Made and deleted again since the last Publish: not waiting.
+			const change = git.changeOf(a.file, a.text);
+			if (change === null) {
+				waiting.delete(a.file);
+				continue;
+			}
+			const at = new Date(a.updatedAt).toISOString();
+			const w: WaitingView = waiting.get(a.file) ?? {
+				file: a.file,
+				change,
+				...docOf(site, a.file),
+				title: '',
+				editors: [],
+				changedAt: null,
+				keptDraft: false,
+				uncommitted: false,
+				editingNow: editingNow(a.file),
+				missingAlt: [],
+			};
+			w.change = change;
+			w.title = a.gone ? a.gone.title : titleOf(a.file, a.text);
+			w.uncommitted = true;
+			w.editors = [{ person: a.editor, at }, ...w.editors.filter((e) => !sameEmail(e.person, a.editor))];
+			if (!w.changedAt || at > w.changedAt) w.changedAt = at;
+			waiting.set(a.file, w);
+		}
+		// M5b Decision 9: each image with no alt text, from the document as it will publish (the
+		// autosave's text, else the copy's). A deleted document has none.
+		const textNow = new Map(saves.map((a) => [a.file, a.text]));
+		for (const w of waiting.values()) {
+			w.missingAlt = w.change === 'deleted' ? [] : missingAltOf(w.file, w.collection, textNow.has(w.file) ? (textNow.get(w.file) ?? null) : git.read(w.file));
+		}
+		// Pre-M7 item 8: a moved document is one entry, on its new file, with its old address.
+		// Read from the moves as recorded, not Site Settings' redirects: removing the redirect leaves it a move.
+		const readNow = (f: string) => (textNow.has(f) ? (textNow.get(f) ?? null) : git.read(f));
+		const moves = movesIn(site, [...waiting.keys()], readNow, await autosaves.moves());
+		const redirects = moves.from.size ? redirectsIn(readNow(SITE_SETTINGS_FILE)) : [];
+		for (const [file, from] of moves.from) {
+			const w = waiting.get(file)!;
+			w.movedFrom = from;
+			w.movedRedirect = redirects.some((r) => r.from === from);
+		}
+		for (const file of moves.to.keys()) waiting.delete(file);
+		const list = [...waiting.values()].sort((a, b) => (b.changedAt ?? '').localeCompare(a.changedAt ?? '') || a.file.localeCompare(b.file));
+
+		let open: StatusResponse['open'] = null;
+		if (file) {
+			const lock = lockViews.find((l) => l.file === file) ?? null;
+			// M5a Decision 12: a viewer learns the document was deleted, and by whom, on this poll.
+			let deleted: NonNullable<StatusResponse['open']>['deleted'] = null;
+			if (!(await exists(file))) {
+				const record = await autosaves.changed(file);
+				deleted = record?.gone ? { by: record.by, at: record.at } : { by: null, at: null };
+			}
+			open = { file, state: Locks.state(lock), lock, lastChange: await lastChangeOf({ git, autosaves }, file), deleted };
+		}
+		const body: StatusResponse = {
+			mode: 'live',
+			you: person,
+			tab,
+			now: new Date(now()).toISOString(),
+			timeZone: site.timeZone,
+			open,
+			waiting: list,
+			locks: lockViews,
+			presence,
+			notices: await notices(person),
+			publish: await publishView(),
+			// M5a Decision 10: from the committed copy, never an autosave.
+			brand: editorBrand(brandFrom(git.read(SITE_SETTINGS_FILE), site)),
+		};
+		return json(200, body);
+	});
+
+	const lock = handler(['POST'], async (request, person) => {
+		const tab = tabOf(request);
+		if (!tab) throw new WriteRefused(400, 'Lock requests name their tab (X-Caracms-Tab).', { code: 'no-tab' });
+		const body = await readBody(request);
+		// A release needs no document (a deleter's tab lets go of one it deleted, M5a); take and take over do.
+		const file = body.action === 'release' ? (confinePath(site, body.file), body.file as string) : await documentFile(body.file);
+		if (body.action === 'release') {
+			const r = await locks.release(file, tab, person);
+			const view = r && locks.holds(r.lock, (await autosaves.get(file)) !== null) ? locks.view(file, r.lock, tab, person) : null;
+			return json(200, { state: Locks.state(view), lock: view } satisfies LockResponse);
+		}
+		if (body.action === 'take-over') {
+			// Take over: the lock moves first, so the old holder's tab can't write again; then
+			// their autosave is committed under their name, and this tab opens from `drafts`.
+			const r = await locks.takeOver(file, tab, person);
+			if (r.from && !sameEmail(r.from.person, person)) log(`${person.email} took over ${file} from ${r.from.person.email}`);
+			// Another server mid-sweep (a deploy) makes a commit a no-op: try a few times, or
+			// this tab's first write would replace their autosave and their name with it.
+			for (let attempt = 0; attempt < 5 && (await autosaves.get(file)) !== null; attempt++) {
+				if ((await sweep.commitFiles([file])).ran) break;
+				await sleep(500);
+			}
+			return json(200, { state: 'yours', lock: locks.view(file, r.lock, tab, person) } satisfies LockResponse);
+		}
+		if (body.action !== 'take') throw new WriteRefused(400, 'action must be "take", "take-over" or "release".');
+		const r = await locks.take(file, tab, person);
+		const view = locks.view(file, r.lock, tab, person);
+		if (!r.ok) {
+			return json(409, {
+				error: `${displayName(view.person)} is editing this document.`,
+				code: 'locked',
+				lock: view,
+				state: 'theirs',
+				lastChange: await lastChangeOf({ git, autosaves }, file),
+			} satisfies LockRefusal);
+		}
+		return json(200, { state: 'yours', lock: view } satisfies LockResponse);
+	});
+
+	const publish = handler(['POST'], async (_request, person) => {
+		const before = await locks.presence();
+		const result = await git.publish(person);
+		if (result.kind === 'published') {
+			// "Aoife published Home as it stood at 14:20" for whoever had a published document open (Decision 10 step 1).
+			const { record } = result;
+			const fields: Record<string, string> = {};
+			for (const p of before) {
+				const i = record.files.indexOf(p.file);
+				if (i === -1) continue;
+				for (const someone of p.people) {
+					if (sameEmail(someone, person)) continue;
+					const id = `stood:${record.commit}:${p.file}:${someone.email.toLowerCase()}`;
+					const notice: StoodNotice = { id, for: someone.email.toLowerCase(), file: p.file, title: result.fileTitles[i] ?? titleOf(p.file, null), by: person, at: record.at };
+					fields[id] = JSON.stringify(notice);
+				}
+			}
+			if (Object.keys(fields).length) {
+				await redis.hset(keys.notices, fields);
+				await redis.pexpire(keys.notices, timings.autosaveTtlMs);
+			}
+		}
+		return json(200, { result: result.kind, publish: await publishView() } satisfies PublishResponse);
+	});
+
+	const history = handler(['GET'], async () => {
+		const entries = await git.history({ refresh: true });
+		return json(200, { timeZone: site.timeZone, entries } satisfies HistoryResponse);
+	});
+
+	const tryAgain = handler(['POST'], async () => {
+		if (!settings.railway) return json(409, { ok: false, error: 'No CARACMS_RAILWAY_TOKEN: a developer can redeploy from Railway.' } satisfies TryAgainResponse);
+		const st = await publishView();
+		if (st.state !== 'failed') return json(409, { ok: false, error: 'The last publish hasn\'t failed, so there\'s nothing to try again.' } satisfies TryAgainResponse);
+		const r = await git.tryAgain();
+		return r.ok ? json(200, { ok: true } satisfies TryAgainResponse) : json(502, { ok: false, error: r.reason } satisfies TryAgainResponse);
+	});
+
+	// Dismiss: only a notice this person is shown now (a draft-kept notice is shared, so
+	// anyone signed in sees it and may dismiss it; "published as it stood" is per person).
+	const notice = handler(['POST'], async (request, person) => {
+		const body = await readBody(request);
+		const id = body.id;
+		if (typeof id !== 'string' || id.length > NOTICE_ID_MAX || !NOTICE_ID.test(id)) throw new WriteRefused(400, '"id" must be a notice\'s id.');
+		const shown = (await notices(person)).find((n) => n.id === id);
+		if (!shown) throw new WriteRefused(404, 'There\'s no such notice for you to dismiss.');
+		if (shown.kind === 'draft-kept') {
+			await redis.sadd(keys.dismissed, id);
+			await redis.pexpire(keys.dismissed, timings.autosaveTtlMs);
+		} else await redis.hdel(keys.notices, id);
+		return json(200, { ok: true });
+	});
+
+	return { runtime, autosaves, locks, sweep, store, write, create, delete: remove, status, lock, publish, history, tryAgain, notice };
+}
+
+const SHARED = Symbol.for('caracms.liveEditor');
+type Shared = { [SHARED]?: Promise<LiveEditor> };
+
+/** The process's live editor, beside the shared runtime (runtime.ts → liveRuntime). */
+export function liveEditor(site: ResolvedSite, settings: LiveSettings): Promise<LiveEditor> {
+	const g = globalThis as Shared;
+	g[SHARED] ??= liveRuntime(site, settings)
+		.then((rt) => createLiveEditor(rt))
+		.catch((error: unknown) => {
+			delete g[SHARED];
+			throw error;
+		});
+	return g[SHARED];
+}