caracms 0.2.0 → 0.3.1

package/src/live/github.ts

@@ -1,6 +1,9 @@
 /**
- * GitHub as the site's App (M4 Phase 1; lifted from M1's spike, `spikes/git/src/github.ts`).
+ * GitHub as the site's App or a fine-grained token (M4 Phase 1, lifted from M1's spike,
+ * `spikes/git/src/github.ts`; the token from runs-anywhere Decision 3).
  *
+ * - **A fine-grained token** (`CARACMS_GITHUB_TOKEN`) is the bearer as it is. GitHub sends
+ *   its expiry on every response, which is kept for the editor (Decision 5).
  * - **The App's JWT**: RS256, signed with the App's private key, `iat` backdated a
  *   minute for clock drift, nine minutes long (GitHub's limit is ten).
  * - **An installation token scoped to the one repo**: the installation is found with
@@ -14,16 +17,18 @@
  *   that stops answering fails the operation instead of holding it (and Publish's or
  *   the check's callers) forever.
  *
- * The private key is never logged.
+ * - **Access problems** (Decision 5): every response is watched for a refused credential
+ *   (401), a write refused for lack of a permission (403 "not accessible"), and, for a
+ *   token, an expiry within 14 days. `accessProblem()` says which holds now; a later
+ *   success clears the first two.
+ *
+ * The private key and the token are never logged.
  */
 import { createSign } from 'node:crypto';
 
 const API = 'https://api.github.com';
 
-export interface AppConnection {
-	appId: string;
-	/** The PEM. Railway variables often carry it with literal `\n`s; those are turned back into newlines. */
-	privateKey: string;
+interface ConnectionBase {
 	owner: string;
 	repo: string;
 	/** For tests. Default: global fetch. */
@@ -34,6 +39,63 @@ export interface AppConnection {
 	timeoutMs?: number;
 }
 
+export interface AppConnection extends ConnectionBase {
+	appId: string;
+	/** The PEM. Railway variables often carry it with literal `\n`s; those are turned back into newlines. */
+	privateKey: string;
+}
+
+/** A fine-grained personal access token on the one repo (Decision 3). */
+export interface TokenConnection extends ConnectionBase {
+	token: string;
+}
+
+export type GitHubConnection = AppConnection | TokenConnection;
+
+/**
+ * What's wrong with GitHub access right now (Decision 5), shown in the editor while it holds.
+ * `credential` says which one the site uses, so the sentence names the right fix.
+ */
+export type GitHubAccessProblem =
+	| { kind: 'refused'; credential: 'app' | 'token' }
+	| { kind: 'permission'; credential: 'app' | 'token'; permission: string }
+	| { kind: 'expiring'; credential: 'token'; expires: string };
+
+/** A token expiring within this long shows in the editor (Decision 5). */
+export const TOKEN_EXPIRY_WARNING_MS = 14 * 24 * 60 * 60_000;
+
+/** The permission every write needs; Deployments read is optional and never shown (Decision 10). */
+const CONTENTS_PERMISSION = 'Contents: Read and write';
+
+/**
+ * `github-authentication-token-expiration`: "2026-11-03 10:00:00 UTC" or "… -0700".
+ * Null when it doesn't parse.
+ */
+export function parseTokenExpiry(value: string | null): number | null {
+	const m = value && /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}(?::\d{2})?)\s*(UTC|Z|[+-]\d{2}:?\d{2})?$/i.exec(value.trim());
+	if (!m) return null;
+	const zone = !m[3] || /^(utc|z)$/i.test(m[3]) ? 'Z' : m[3].replace(/^([+-]\d{2}):?(\d{2})$/, '$1:$2');
+	const at = Date.parse(`${m[1]}T${m[2]}${zone}`);
+	return Number.isNaN(at) ? null : at;
+}
+
+/** The sentence the editor shows for an access problem, for the developer it's forwarded to. */
+export function accessProblemMessage(problem: GitHubAccessProblem): string {
+	const what = problem.credential === 'token' ? 'GitHub token (CARACMS_GITHUB_TOKEN)' : 'GitHub App';
+	switch (problem.kind) {
+		case 'refused':
+			return problem.credential === 'token'
+				? `GitHub refused this site's ${what}: it may have expired or been revoked. Changes can't be saved to GitHub until a developer makes a new fine-grained token and sets it.`
+				: `GitHub refused this site's ${what}: it may have been uninstalled from the repo or suspended. Changes can't be saved to GitHub until a developer reinstalls it.`;
+		case 'permission':
+			return `GitHub refused a change because this site's ${what} lacks the "${problem.permission}" permission. A developer can add it in the ${problem.credential === 'token' ? "token's settings" : "App's settings"}.`;
+		case 'expiring': {
+			const date = new Date(problem.expires).toLocaleDateString('en-IE', { day: 'numeric', month: 'long', year: 'numeric', timeZone: 'UTC' });
+			return `This site's ${what} expires on ${date}. After that, changes can't be saved to GitHub: a developer can regenerate it, or make a new one, and set it before then.`;
+		}
+	}
+}
+
 /** A GitHub request that takes longer than this fails (its caller treats it as any failure). */
 export const GITHUB_TIMEOUT_MS = 20_000;
 
@@ -143,6 +205,8 @@ export class GitHubClient {
 	readonly tracker: Tracker;
 	readonly owner: string;
 	readonly repo: string;
+	/** Which credential this client signs in with. */
+	readonly credential: 'app' | 'token';
 	private readonly appId: string;
 	private readonly key: string;
 	private readonly fetcher: typeof fetch;
@@ -151,10 +215,23 @@ export class GitHubClient {
 	private token = '';
 	private tokenExpires = 0;
 	private signingIn: Promise<void> | null = null;
+	/** Decision 5: what the last responses said about access. */
+	private refused = false;
+	private missingPermission: string | null = null;
+	private personalTokenExpires: number | null = null;
 
-	constructor(connection: AppConnection, tracker: Tracker) {
-		this.appId = connection.appId;
-		this.key = connection.privateKey.includes('\\n') ? connection.privateKey.replace(/\\n/g, '\n') : connection.privateKey;
+	constructor(connection: GitHubConnection, tracker: Tracker) {
+		if ('token' in connection) {
+			this.credential = 'token';
+			this.appId = '';
+			this.key = '';
+			this.token = connection.token;
+			this.tokenExpires = Number.POSITIVE_INFINITY;
+		} else {
+			this.credential = 'app';
+			this.appId = connection.appId;
+			this.key = connection.privateKey.includes('\\n') ? connection.privateKey.replace(/\\n/g, '\n') : connection.privateKey;
+		}
 		this.owner = connection.owner;
 		this.repo = connection.repo;
 		this.fetcher = connection.fetch ?? fetch;
@@ -163,6 +240,37 @@ export class GitHubClient {
 		this.tracker = tracker;
 	}
 
+	/** What's wrong with GitHub access now, the most serious first; null when nothing is (Decision 5). */
+	accessProblem(): GitHubAccessProblem | null {
+		if (this.refused) return { kind: 'refused', credential: this.credential };
+		if (this.missingPermission) return { kind: 'permission', credential: this.credential, permission: this.missingPermission };
+		const expires = this.personalTokenExpires;
+		if (this.credential === 'token' && expires !== null && expires - this.now() < TOKEN_EXPIRY_WARNING_MS) {
+			return { kind: 'expiring', credential: 'token', expires: new Date(expires).toISOString() };
+		}
+		return null;
+	}
+
+	/**
+	 * Keep what a response says about access. A 401 is a refused credential. A write
+	 * refused for lack of a permission (`notPermitted`: a 403 or a GraphQL error saying
+	 * "not accessible") is a missing permission, except on Deployments (optional,
+	 * Decision 10); a rate limit's 403 isn't one. Any success clears a refusal; a
+	 * successful write clears a missing permission.
+	 */
+	private observe(res: Response, path: string, write: boolean, notPermitted: boolean, hadErrors = false): void {
+		if (this.credential === 'token') {
+			const expires = parseTokenExpiry(res.headers.get('github-authentication-token-expiration'));
+			if (expires !== null) this.personalTokenExpires = expires;
+		}
+		if (res.status === 401) this.refused = true;
+		else if (res.ok && !notPermitted) {
+			this.refused = false;
+			if (write && !hadErrors) this.missingPermission = null; // a GraphQL 200 carrying errors didn't land
+		}
+		if (notPermitted && write && !/\/deployments/.test(path)) this.missingPermission = CONTENTS_PERMISSION;
+	}
+
 	get nameWithOwner() {
 		return `${this.owner}/${this.repo}`;
 	}
@@ -176,6 +284,7 @@ export class GitHubClient {
 		const jwt = appJwt(this.appId, this.key, Math.floor(this.now() / 1000));
 		const install = (await this.request('GET', this.repoPath('/installation'), undefined, jwt).catch((error: unknown) => {
 			if (error instanceof HttpError && error.status === 404) {
+				this.refused = true;
 				throw new Error(`The GitHub App (id ${this.appId}) isn't installed on ${this.nameWithOwner}. Install it on that repo.`);
 			}
 			throw error;
@@ -188,8 +297,9 @@ export class GitHubClient {
 		this.tokenExpires = Date.parse(tok.expires_at);
 	}
 
-	/** The installation token, refreshed five minutes before it expires. */
+	/** The installation token, refreshed five minutes before it expires; a personal token as it is. */
 	private async auth(): Promise<string> {
+		if (this.credential === 'token') return this.token;
 		if (!this.token || this.now() > this.tokenExpires - 5 * 60_000) {
 			this.signingIn ??= this.signIn().finally(() => {
 				this.signingIn = null;
@@ -207,6 +317,7 @@ export class GitHubClient {
 	async bytes(path: string): Promise<Buffer> {
 		const res = await this.fetcher(`${API}${path}`, { headers: this.headers(await this.auth()), redirect: 'follow', signal: this.signal() });
 		this.tracker.record({ endpoint: `GET ${shorten(path.replace(/^\/repos\/[^/]+\/[^/]+/, '').replace(/\?.*$/, ''))}`, status: res.status, creating: false });
+		this.observe(res, path, false, false);
 		if (!res.ok) throw new HttpError(res.status, `GET ${path} -> ${res.status}`, await res.text().catch(() => ''));
 		return Buffer.from(await res.arrayBuffer());
 	}
@@ -234,7 +345,8 @@ export class GitHubClient {
 			signal: this.signal(),
 		});
 		const endpointPath = path.replace(/^\/repos\/[^/]+\/[^/]+/, '').replace(/\?.*$/, '');
-		this.tracker.record({ endpoint: `${method} ${shorten(endpointPath)}`, status: res.status, creating: !notCreating && isContentCreating(method, path, false) });
+		const creating = !notCreating && isContentCreating(method, path, false);
+		this.tracker.record({ endpoint: `${method} ${shorten(endpointPath)}`, status: res.status, creating });
 		const text = await res.text();
 		let json: unknown = null;
 		try {
@@ -242,14 +354,15 @@ export class GitHubClient {
 		} catch {
 			json = text;
 		}
+		const message = (json as { message?: string } | null)?.message ?? text.slice(0, 200);
+		this.observe(res, path, creating, res.status === 403 && /not accessible/i.test(message));
 		if (!res.ok) {
-			const message = (json as { message?: string } | null)?.message ?? text.slice(0, 200);
 			throw new HttpError(res.status, `${method} ${endpointPath} -> ${res.status}: ${message}`, json);
 		}
 		return json;
 	}
 
-	/** GraphQL as the installation. Throws GraphQLError when the answer has `errors`. */
+	/** GraphQL as the installation (or the token). Throws GraphQLError when the answer has `errors`. */
 	async graphql<T = unknown>(query: string, variables: Record<string, unknown>, name: string): Promise<T> {
 		const isMutation = /^\s*mutation\b/.test(query);
 		const res = await this.fetcher(`${API}/graphql`, {
@@ -264,6 +377,8 @@ export class GitHubClient {
 			if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')) throw error; // timed out mid-body
 			return {};
 		})) as { data?: T; errors?: { type?: string; message?: string }[] };
+		const notPermitted = (json.errors ?? []).some((e) => e.type === 'FORBIDDEN' || /not accessible/i.test(e.message ?? ''));
+		this.observe(res, '/graphql', isMutation, notPermitted, (json.errors?.length ?? 0) > 0);
 		if (!res.ok && !json.errors) throw new HttpError(res.status, `graphql ${name} -> ${res.status}`, json);
 		if (json.errors?.length) throw new GraphQLError(json.errors);
 		return json.data as T;

package/src/live/locks.ts

@@ -28,11 +28,16 @@
  *
  * **Presence** (`caracms:presence`, a hash by tab): each poll records the person and the
  * document their tab has open; someone is "on" a document while a tab of theirs
- * polled with it in the last `presenceMs`.
+ * polled with it within that record's hold: twice the tab's poll interval plus 3 s
+ * (Redis diet Decision 9), so a slow tab stays on and a closed fast one goes quickly.
+ *
+ * **The status cache** (status-cache.ts, Redis diet Decision 2): every write here tells
+ * it what landed, so the status poll can read locks and presence from memory.
  */
 import type { LockState, LockView, PresenceView } from '../editor/types.ts';
 import type { Person } from './messages.ts';
 import type { RedisClient } from './redis.ts';
+import { landed, type StatusCache } from './status-cache.ts';
 import type { LiveTimings } from './timings.ts';
 
 export interface LockRecord {
@@ -48,7 +53,7 @@ export interface LockRecord {
 	deleted?: true;
 }
 
-interface ReadLock {
+export interface ReadLock {
 	raw: string;
 	lock: LockRecord;
 }
@@ -57,11 +62,16 @@ interface PresenceRecord {
 	person: Person;
 	file: string | null;
 	at: number;
+	/** ms the record holds after `at` (Redis diet Decision 9). Absent (written before it was added): `presenceMs`. */
+	hold?: number;
 }
 
 /** How long a releasing lock with no autosave yet waits for the tab's last write. */
 export const RELEASE_GRACE_MS = 5_000;
 
+/** Redis diet Decision 9: a presence record holds for twice the tab's poll interval plus this. */
+export const PRESENCE_SLACK_MS = 3_000;
+
 const sameEmail = (a: Person, b: Person) => a.email.toLowerCase() === b.email.toLowerCase();
 
 export type AcquireResult = { ok: true; lock: LockRecord } | { ok: false; lock: LockRecord };
@@ -73,17 +83,38 @@ export class Locks {
 	readonly prefix: string;
 	/** Whether the document has an autosave not yet committed. */
 	private readonly pending: (file: string) => Promise<boolean>;
+	private readonly cache: StatusCache | null;
 
-	constructor(redis: RedisClient, timings: LiveTimings, now: () => number, pending: (file: string) => Promise<boolean>, prefix = 'caracms:') {
+	constructor(
+		redis: RedisClient,
+		timings: LiveTimings,
+		now: () => number,
+		pending: (file: string) => Promise<boolean>,
+		prefix = 'caracms:',
+		cache: StatusCache | null = null,
+	) {
 		this.redis = redis;
 		this.timings = timings;
 		this.now = now;
 		this.pending = pending;
 		this.prefix = prefix;
+		this.cache = cache;
 	}
 
 	key = (file: string) => `${this.prefix}lock:${file}`;
-	private presenceKey = () => `${this.prefix}presence`;
+	/** What every lock key starts with (the status cache scans it). */
+	get keyPrefix(): string {
+		return this.key('');
+	}
+	readonly presenceKey = () => `${this.prefix}presence`;
+
+	/** A compare-and-swap on a lock key, and the status cache told what came of it. */
+	private async swap(file: string, expected: string | null, raw: string): Promise<boolean> {
+		const ok = await landed(this.cache, this.key(file), () => this.redis.compareAndSet(this.key(file), expected, raw, { px: this.timings.autosaveTtlMs }));
+		if (ok) this.cache?.string(this.key(file), raw);
+		else this.cache?.drop(this.key(file));
+		return ok;
+	}
 
 	private parse(raw: string | null): ReadLock | null {
 		if (raw === null) return null;
@@ -101,14 +132,19 @@ export class Locks {
 
 	/** Every lock key: one SCAN and one MGET. */
 	async all(): Promise<Map<string, ReadLock>> {
-		const keys = await this.redis.scan(`${this.prefix}lock:*`);
-		const out = new Map<string, ReadLock>();
-		if (keys.length === 0) return out;
+		const keys = await this.redis.scan(`${this.keyPrefix}*`);
+		if (keys.length === 0) return new Map();
 		const raws = await this.redis.mget(keys);
-		keys.forEach((k, i) => {
-			const read = this.parse(raws[i] ?? null);
-			if (read) out.set(k.slice(this.key('').length), read);
-		});
+		return this.allFrom(keys.map((k, i) => [k, raws[i] ?? null]));
+	}
+
+	/** The locks among these keys and values (a scan of `keyPrefix`), by file. */
+	allFrom(entries: Iterable<readonly [string, string | null]>): Map<string, ReadLock> {
+		const out = new Map<string, ReadLock>();
+		for (const [k, raw] of entries) {
+			const read = this.parse(raw);
+			if (read) out.set(k.slice(this.keyPrefix.length), read);
+		}
 		return out;
 	}
 
@@ -125,7 +161,7 @@ export class Locks {
 	}
 
 	private put(file: string, expected: string | null, lock: LockRecord): Promise<boolean> {
-		return this.redis.compareAndSet(this.key(file), expected, JSON.stringify(lock), { px: this.timings.autosaveTtlMs });
+		return this.swap(file, expected, JSON.stringify(lock));
 	}
 
 	private static mine(lock: LockRecord, tab: string, person: Person) {
@@ -161,18 +197,32 @@ export class Locks {
 	 * is still here), except for a lock the tab's own delete released. A lapsed lock that still names this tab is re-taken (a tab back
 	 * from hidden). Nothing is taken that the tab never held.
 	 */
-	async beat(file: string, tab: string, person: Person): Promise<ReadLock | null> {
+	async beat(file: string, tab: string, person: Person, known?: ReadLock | null): Promise<ReadLock | null> {
 		for (let attempt = 0; attempt < 3; attempt++) {
-			const cur = await this.read(file);
+			// `known`: the lock as the status cache has it, the first try's expected value (Redis diet Decision 6).
+			const cur = attempt === 0 && known !== undefined ? known : await this.read(file);
 			if (!cur || !Locks.mine(cur.lock, tab, person)) return cur;
 			// A poll in flight when the tab deleted the document must not un-release its lock (M5a).
 			const next = { ...cur.lock, beat: this.now(), releasing: cur.lock.deleted ? cur.lock.releasing : null };
 			const raw = JSON.stringify(next);
-			if (await this.redis.compareAndSet(this.key(file), cur.raw, raw, { px: this.timings.autosaveTtlMs })) return { raw, lock: next };
+			if (await this.swap(file, cur.raw, raw)) return { raw, lock: next };
 		}
 		return this.read(file);
 	}
 
+	/**
+	 * Redis diet Decision 6: does the status poll need to beat for this tab? Only when the
+	 * lock (as the cache has it) is the tab's own and its last beat is `beatEveryMs` old
+	 * (a lapsed one is older still: it's taken back), or it's marked releasing and not
+	 * deleted (a tab back from `pagehide`: the beat clears it). A lock that isn't the
+	 * tab's, or none, needs no beat: the beat takes nothing the tab never held.
+	 */
+	needsBeat(cached: ReadLock | null, tab: string, person: Person): boolean {
+		if (!cached || !Locks.mine(cached.lock, tab, person)) return false;
+		if (cached.lock.releasing !== null && !cached.lock.deleted) return true;
+		return this.now() - cached.lock.beat >= this.timings.beatEveryMs;
+	}
+
 	/** Edit here: move your own lock to this tab at once, or take a free one. Someone else's refuses. */
 	async take(file: string, tab: string, person: Person): Promise<AcquireResult> {
 		for (let attempt = 0; attempt < 5; attempt++) {
@@ -218,7 +268,10 @@ export class Locks {
 	/** Delete a lock that no longer holds (the sweep, after a commit). */
 	async dropIfFree(file: string): Promise<void> {
 		const cur = await this.read(file);
-		if (cur && !(await this.live(cur, file))) await this.redis.compareAndDelete(this.key(file), cur.raw);
+		if (cur && !(await this.live(cur, file))) {
+			if (await landed(this.cache, this.key(file), () => this.redis.compareAndDelete(this.key(file), cur.raw))) this.cache?.string(this.key(file), null);
+			else this.cache?.drop(this.key(file));
+		}
 	}
 
 	view(file: string, lock: LockRecord, tab: string | null, person: Person): LockView {
@@ -238,19 +291,28 @@ export class Locks {
 
 	// ── Presence ────────────────────────────────────────────────────────────────
 
-	/** Record a poll: this tab, this person, this document (or none). */
-	async present(tab: string, person: Person, file: string | null): Promise<void> {
-		const record: PresenceRecord = { person, file, at: this.now() };
-		await this.redis.hset(this.presenceKey(), { [tab]: JSON.stringify(record) });
+	/**
+	 * Record a poll: this tab, this person, this document (or none). `intervalMs`: how long
+	 * until the tab's next poll; the record holds for twice that plus 3 s (Decision 9).
+	 */
+	async present(tab: string, person: Person, file: string | null, intervalMs = this.timings.pollMs): Promise<void> {
+		const record: PresenceRecord = { person, file, at: this.now(), hold: 2 * intervalMs + PRESENCE_SLACK_MS };
+		const fields = { [tab]: JSON.stringify(record) };
+		await landed(this.cache, this.presenceKey(), () => this.redis.hset(this.presenceKey(), fields));
+		this.cache?.hash(this.presenceKey(), fields);
 	}
 
-	/** Who is on which document now (polled with it in the last `presenceMs`). Long-gone tabs are pruned. */
+	/** Who is on which document now (polled with it within the record's hold). Long-gone tabs are pruned. */
 	async presence(): Promise<PresenceView[]> {
-		const all = await this.redis.hgetall(this.presenceKey());
+		return this.presenceFrom(Object.entries(await this.redis.hgetall(this.presenceKey())));
+	}
+
+	/** `presence()` over the hash's fields as read (the status cache's, on a poll). */
+	async presenceFrom(fields: Iterable<readonly [string, string]>): Promise<PresenceView[]> {
 		const now = this.now();
 		const byFile = new Map<string, Person[]>();
 		const gone: string[] = [];
-		for (const [tab, raw] of Object.entries(all)) {
+		for (const [tab, raw] of fields) {
 			let r: PresenceRecord;
 			try {
 				r = JSON.parse(raw) as PresenceRecord;
@@ -258,8 +320,9 @@ export class Locks {
 				gone.push(tab);
 				continue;
 			}
-			if (now - r.at > this.timings.presenceMs) {
-				if (now - r.at > this.timings.lockLapseMs) gone.push(tab);
+			const hold = typeof r.hold === 'number' ? r.hold : this.timings.presenceMs;
+			if (now - r.at > hold) {
+				if (now - r.at > Math.max(hold, this.timings.lockLapseMs)) gone.push(tab);
 				continue;
 			}
 			if (!r.file) continue;
@@ -267,7 +330,10 @@ export class Locks {
 			if (!people.some((p) => sameEmail(p, r.person))) people.push(r.person);
 			byFile.set(r.file, people);
 		}
-		if (gone.length) await this.redis.hdel(this.presenceKey(), ...gone);
+		if (gone.length) {
+			await landed(this.cache, this.presenceKey(), () => this.redis.hdel(this.presenceKey(), ...gone));
+			this.cache?.hash(this.presenceKey(), {}, gone);
+		}
 		return [...byFile].map(([file, people]) => ({ file, people }));
 	}
 }