pi-roundtable-web 0.24.2 → 0.26.0

package/src/app/files.ts

@@ -73,6 +73,16 @@ interface Meta {
 	name: string;
 	type: string;
 	size: number;
+	/** The host room the file is bound to: only someone who may read that room is served it. */
+	room?: string;
+	/** Epoch milliseconds after which the sweep deletes the file; absent = the file is kept. */
+	expiresAt?: number;
+}
+
+/** What binds a stored file to a host room. */
+export interface FileBinding {
+	room: string;
+	expiresAt?: number;
 }
 
 /** A file being written as its bytes arrive; `finish` makes it a stored file, `abort` leaves nothing. */
@@ -85,6 +95,13 @@ export interface FileWriter {
 	abort(): Promise<void>;
 }
 
+const bindingFields = (
+	binding: FileBinding,
+): Pick<Meta, "room" | "expiresAt"> => ({
+	room: binding.room,
+	...(binding.expiresAt === undefined ? {} : { expiresAt: binding.expiresAt }),
+});
+
 /**
  * A directory of files kept by id, each with a small record of its name and type beside it.
  * Both stores of the app, the files of replies and sent messages and the uploads waiting for a
@@ -101,20 +118,61 @@ export class FileDir {
 		return join(this.dir, id);
 	}
 
-	/** Keeps the bytes under a new id. */
+	/** Keeps the bytes under a new id, bound to a host room when `binding` is given. */
 	put(
 		name: string,
 		type: string,
 		bytes: Uint8Array,
 		id = crypto.randomUUID(),
+		binding?: FileBinding,
 	): RoomFile {
 		mkdirSync(this.dir, { recursive: true, mode: 0o700 });
-		const meta: Meta = { name: safeName(name), type, size: bytes.byteLength };
+		const meta: Meta = {
+			name: safeName(name),
+			type,
+			size: bytes.byteLength,
+			...(binding ? bindingFields(binding) : {}),
+		};
 		writeFileSync(this.#path(id), bytes, { mode: 0o600 });
 		writeFileSync(`${this.#path(id)}.json`, JSON.stringify(meta), {
 			mode: 0o600,
 		});
-		return { id, ...meta };
+		return { id, name: meta.name, type, size: meta.size };
+	}
+
+	#read(id: string): Meta | undefined {
+		if (!isFileId(id)) return undefined;
+		try {
+			return JSON.parse(readFileSync(`${this.#path(id)}.json`, "utf8")) as Meta;
+		} catch {
+			return undefined;
+		}
+	}
+
+	/** The room a file is bound to and when it expires; undefined for a file that is bound to none. */
+	binding(id: string): FileBinding | undefined {
+		const meta = this.#read(id);
+		return meta?.room === undefined
+			? undefined
+			: {
+					room: meta.room,
+					...(meta.expiresAt === undefined
+						? {}
+						: { expiresAt: meta.expiresAt }),
+				};
+	}
+
+	/** Binds a stored file to a host room, or changes its expiry; false when there is no such file. */
+	bind(id: string, binding: FileBinding): boolean {
+		const meta = this.#read(id);
+		if (!meta || !existsSync(this.#path(id))) return false;
+		const { room: _room, expiresAt: _expiresAt, ...plain } = meta;
+		writeFileSync(
+			`${this.#path(id)}.json`,
+			JSON.stringify({ ...plain, ...bindingFields(binding) }),
+			{ mode: 0o600 },
+		);
+		return true;
 	}
 
 	/** Starts a file under a new id whose bytes arrive in pieces, so it is never held whole. */
@@ -161,12 +219,20 @@ export class FileDir {
 	}
 
 	meta(id: string): RoomFile | undefined {
+		const meta = this.#read(id);
+		return meta && { id, name: meta.name, type: meta.type, size: meta.size };
+	}
+
+	/** Whether the file's bytes are still stored. */
+	has(id: string): boolean {
+		return isFileId(id) && existsSync(this.#path(id));
+	}
+
+	/** How long ago the file was written, in milliseconds; undefined when there is none. */
+	ageOf(id: string, now: number): number | undefined {
 		if (!isFileId(id)) return undefined;
 		try {
-			const meta = JSON.parse(
-				readFileSync(`${this.#path(id)}.json`, "utf8"),
-			) as Meta;
-			return { id, name: meta.name, type: meta.type, size: meta.size };
+			return now - statSync(this.#path(id)).mtimeMs;
 		} catch {
 			return undefined;
 		}

package/src/app/layout-routes.ts

@@ -0,0 +1,239 @@
+import type { Speaker } from "pi-roundtable";
+import type { ApiError, LayoutView } from "../api-types.ts";
+import type { Authenticated } from "../auth/authenticator.ts";
+import { json } from "../http.ts";
+import {
+	createFolder,
+	LayoutError,
+	placeFolder,
+	placeRoom,
+	removeFolder,
+	renameFolder,
+	setPinned,
+	shown,
+} from "../layout-order.ts";
+import type { PushMutes } from "../push/mutes.ts";
+import { readLimited } from "../request-body.ts";
+import type { LayoutStore } from "./layout.ts";
+import type { ResolvedRoom } from "./rooms.ts";
+
+/** The largest JSON body of a layout write: 4 KiB. */
+const MAX_BODY_BYTES = 4 * 1024;
+const FOLDER_ID = /^folder\.[0-9a-f-]{36}$/;
+
+/** A refusal with the status the owner is answered with. */
+class LayoutRefusal extends Error {
+	constructor(
+		readonly status: number,
+		message: string,
+	) {
+		super(message);
+	}
+}
+
+const bad = (message: string) => new LayoutRefusal(400, message);
+
+/** A refusal of the pure layout edits as the answer the owner reads. */
+function refusalOf(error: LayoutError): LayoutRefusal {
+	switch (error.code) {
+		case "bad-name":
+			return new LayoutRefusal(
+				400,
+				"Give the folder a name of 1 to 40 characters.",
+			);
+		case "no-folder":
+			return new LayoutRefusal(404, "There is no such folder.");
+		case "duplicate":
+			return new LayoutRefusal(409, "A folder of that name exists.");
+		case "full":
+			return new LayoutRefusal(409, "There are 50 folders already.");
+	}
+}
+
+async function bodyOf(request: Request): Promise<Record<string, unknown>> {
+	const raw = await readLimited(request, MAX_BODY_BYTES);
+	if (!raw) throw new LayoutRefusal(413, "The body is too large.");
+	let value: unknown;
+	try {
+		value = JSON.parse(raw.toString("utf8"));
+	} catch {
+		throw bad("The body is not JSON.");
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value))
+		throw bad("The body is not an object.");
+	return value as Record<string, unknown>;
+}
+
+/** `before` of a body: a key or id, none for the end; anything else is refused. */
+function beforeOf(body: Record<string, unknown>): string | null {
+	const { before } = body;
+	if (before === undefined || before === null) return null;
+	if (typeof before !== "string") throw bad("before must be a key or null.");
+	return before;
+}
+
+export interface LayoutRoutesOptions {
+	layout: LayoutStore;
+	/** The rooms whose push the owners muted. */
+	mutes: Pick<PushMutes, "setMany">;
+	/** The keys of the rooms that may be placed: the active agents' and groups' rooms but Home. */
+	placeable(): ReadonlySet<string>;
+	/** Home's key, which stays at the top. */
+	home(): string | undefined;
+	/** Reads the person's tier again; refuses with 403 when they are no owner. */
+	owner(admission: Authenticated): Promise<Speaker>;
+	/** Called after a change the other pages should refetch. */
+	changed(): void;
+}
+
+/**
+ * The room list's arrangement over HTTP: `GET api/rooms` carries it, `api/folders` makes, renames,
+ * places and removes folders, and `PUT api/rooms/<key>/folder` and `…/pin` place one room. Every
+ * write is an owner's (tier read again) and answers with the whole layout, so the writing page
+ * and the others converge on what the server stored.
+ */
+export class LayoutRoutes {
+	readonly #options: LayoutRoutesOptions;
+
+	constructor(options: LayoutRoutesOptions) {
+		this.#options = options;
+	}
+
+	/** The layout as readers see it: only the rooms that exist. */
+	async view(): Promise<LayoutView> {
+		const rooms = this.#options.placeable();
+		return shown(await this.#options.layout.view(), (key) => rooms.has(key));
+	}
+
+	/** `api/folders` and `api/folders/<id>`; `parts` is the path split after the mount. */
+	async folders(
+		request: Request,
+		parts: string[],
+		admission: Authenticated,
+	): Promise<Response> {
+		return this.#guard(async () => {
+			const { method } = request;
+			const [, , id, action] = parts;
+			if (parts.length > 4 || (parts.length === 4 && action !== "mute"))
+				throw new LayoutRefusal(404, notAnApi);
+			if (action === "mute") return this.#muteFolder(request, id, admission);
+			if (!id) {
+				if (method !== "POST") throw new LayoutRefusal(405, notAllowed);
+				await this.#options.owner(admission);
+				const { name } = await bodyOf(request);
+				if (typeof name !== "string")
+					throw new LayoutRefusal(
+						400,
+						"Give the folder a name of 1 to 40 characters.",
+					);
+				const folder = `folder.${crypto.randomUUID()}`;
+				return json(
+					await this.#write((layout) => createFolder(layout, folder, name)),
+					201,
+				);
+			}
+			if (method !== "PATCH" && method !== "DELETE")
+				throw new LayoutRefusal(405, notAllowed);
+			await this.#options.owner(admission);
+			if (!FOLDER_ID.test(id))
+				throw new LayoutRefusal(404, "There is no such folder.");
+			if (method === "DELETE")
+				return json(await this.#write((layout) => removeFolder(layout, id)));
+			const body = await bodyOf(request);
+			const { name } = body;
+			if (name !== undefined && typeof name !== "string")
+				throw bad("name must be text.");
+			const placed = "before" in body;
+			if (name === undefined && !placed) throw bad("Give a name or a place.");
+			const before = beforeOf(body);
+			return json(
+				await this.#write((layout) => {
+					let next = layout;
+					if (name !== undefined) next = renameFolder(next, id, name);
+					if (placed) next = placeFolder(next, id, before);
+					return next;
+				}),
+			);
+		});
+	}
+
+	/**
+	 * `PUT api/folders/<id>/mute`: mutes or unmutes every room in the folder as one step, through the
+	 * rooms' own mutes. A room moved into the folder later keeps its own mute.
+	 */
+	async #muteFolder(
+		request: Request,
+		id: string | undefined,
+		admission: Authenticated,
+	): Promise<Response> {
+		if (request.method !== "PUT") throw new LayoutRefusal(405, notAllowed);
+		const owner = await this.#options.owner(admission);
+		const folder = (await this.view()).folders.find((one) => one.id === id);
+		if (!folder) throw new LayoutRefusal(404, "There is no such folder.");
+		const { muted } = await bodyOf(request);
+		if (typeof muted !== "boolean") throw bad("muted must be true or false.");
+		await this.#options.mutes.setMany(folder.rooms, muted, owner.principalId);
+		this.#options.changed();
+		return json({ muted, rooms: folder.rooms });
+	}
+
+	/** `PUT api/rooms/<key>/folder` and `…/pin`, for a room that resolved. */
+	async place(
+		request: Request,
+		room: ResolvedRoom,
+		action: "folder" | "pin",
+		admission: Authenticated,
+	): Promise<Response> {
+		return this.#guard(async () => {
+			await this.#options.owner(admission);
+			if (room.kind === "thread") throw bad("A thread stays under its room.");
+			if (room.key === this.#options.home())
+				throw bad("Home stays at the top.");
+			const body = await bodyOf(request);
+			const before = beforeOf(body);
+			if (action === "pin") {
+				const { pinned } = body;
+				if (typeof pinned !== "boolean")
+					throw bad("pinned must be true or false.");
+				return json(
+					await this.#write((layout) =>
+						setPinned(layout, room.key, pinned, before),
+					),
+				);
+			}
+			const { folder } = body;
+			if (folder !== null && typeof folder !== "string")
+				throw bad("folder must be a folder id or null.");
+			return json(
+				await this.#write((layout) =>
+					placeRoom(layout, room.key, folder, before),
+				),
+			);
+		});
+	}
+
+	/** Stores an edit, tells the other pages, and answers with the layout as readers see it. */
+	async #write(edit: (layout: LayoutView) => LayoutView): Promise<LayoutView> {
+		const stored = await this.#options.layout.change(edit);
+		this.#options.changed();
+		const rooms = this.#options.placeable();
+		return shown(stored, (key) => rooms.has(key));
+	}
+
+	async #guard(run: () => Promise<Response>): Promise<Response> {
+		try {
+			return await run();
+		} catch (error) {
+			const refusal = error instanceof LayoutError ? refusalOf(error) : error;
+			if (refusal instanceof LayoutRefusal)
+				return json(
+					{ error: refusal.message } satisfies ApiError,
+					refusal.status,
+				);
+			throw error;
+		}
+	}
+}
+
+const notAllowed = "Method not allowed.";
+const notAnApi = "There is no such API.";

package/src/app/layout.ts

@@ -0,0 +1,133 @@
+import type { SQL } from "bun";
+import type { Migration } from "pi-roundtable";
+import type { LayoutView } from "../api-types.ts";
+import { forgetRoom } from "../layout-order.ts";
+
+/** What the layout routes need of the stored arrangement; `RoomLayout` is the database's. */
+export interface LayoutStore {
+	/** Everything stored, including rooms that no longer exist. */
+	view(): Promise<LayoutView>;
+	/**
+	 * Applies an edit to the stored layout as one step that no other edit overlaps, and returns the
+	 * result. An edit that throws changes nothing.
+	 */
+	change(edit: (layout: LayoutView) => LayoutView): Promise<LayoutView>;
+	/**
+	 * Drops a room's pin and its place in a folder, for a room that is deleted for good (an archived
+	 * agent returns to its place when it comes back, so archiving does not call this).
+	 */
+	forget(room: string): Promise<void>;
+}
+
+interface FolderRow {
+	id: string;
+	name: string;
+}
+interface RoomRow {
+	room: string;
+	folder: string;
+}
+
+/**
+ * The arrangement of the room list, shared by every owner and device: the pinned rooms
+ * (`web_room_pins`), the folders (`web_room_folders`) and the rooms in them
+ * (`web_room_folder_rooms`). Positions are dense (0..n-1) within each list and rewritten on every
+ * change under one advisory lock, so two devices editing at once cannot leave a gap or a duplicate.
+ * Rows of rooms that no longer exist are kept, so a re-created agent returns to its place.
+ */
+export class RoomLayout implements LayoutStore {
+	readonly #sql: SQL;
+
+	constructor(sql: SQL) {
+		this.#sql = sql;
+	}
+
+	static readonly migration: Migration = {
+		name: "web-room-layout",
+		up: async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS web_room_folders (
+					id text PRIMARY KEY,
+					name text NOT NULL,
+					position integer NOT NULL,
+					created_at timestamptz NOT NULL DEFAULT now()
+				)`;
+			await sql`
+				CREATE TABLE IF NOT EXISTS web_room_folder_rooms (
+					room text PRIMARY KEY,
+					folder text NOT NULL REFERENCES web_room_folders (id) ON DELETE CASCADE,
+					position integer NOT NULL
+				)`;
+			await sql`CREATE INDEX IF NOT EXISTS web_room_folder_rooms_folder ON web_room_folder_rooms (folder, position)`;
+			await sql`
+				CREATE TABLE IF NOT EXISTS web_room_pins (
+					room text PRIMARY KEY,
+					position integer NOT NULL
+				)`;
+		},
+	};
+
+	async forget(room: string): Promise<void> {
+		await this.change((layout) => forgetRoom(layout, room));
+	}
+
+	async view(): Promise<LayoutView> {
+		// The three SELECTs share one snapshot, so an edit that commits between them is seen whole or not at all.
+		return this.#sql.begin("isolation level repeatable read, read only", read);
+	}
+
+	async change(edit: (layout: LayoutView) => LayoutView): Promise<LayoutView> {
+		return this.#sql.begin(async (tx) => {
+			await tx`SELECT pg_advisory_xact_lock(hashtextextended('web-room-layout', 0))`;
+			const before = await read(tx);
+			const after = edit(before);
+			if (JSON.stringify(after) !== JSON.stringify(before))
+				await write(tx, after);
+			return after;
+		});
+	}
+}
+
+async function read(tx: SQL): Promise<LayoutView> {
+	const folders: FolderRow[] = await tx`
+		SELECT id, name FROM web_room_folders ORDER BY position, created_at, id`;
+	const inside: RoomRow[] = await tx`
+		SELECT room, folder FROM web_room_folder_rooms ORDER BY folder, position`;
+	const pins: { room: string }[] = await tx`
+		SELECT room FROM web_room_pins ORDER BY position`;
+	return {
+		pins: pins.map((row) => row.room),
+		folders: folders.map((folder) => ({
+			id: folder.id,
+			name: folder.name,
+			rooms: inside
+				.filter((row) => row.folder === folder.id)
+				.map((r) => r.room),
+		})),
+	};
+}
+
+/** Rewrites the three tables to match the layout, positions dense. */
+async function write(tx: SQL, layout: LayoutView): Promise<void> {
+	await tx`DELETE FROM web_room_folder_rooms`;
+	await tx`DELETE FROM web_room_pins`;
+	const ids = layout.folders.map((folder) => folder.id);
+	if (ids.length === 0) await tx`DELETE FROM web_room_folders`;
+	else await tx`DELETE FROM web_room_folders WHERE id NOT IN ${tx(ids)}`;
+	for (const [position, folder] of layout.folders.entries())
+		await tx`
+			INSERT INTO web_room_folders (id, name, position)
+			VALUES (${folder.id}, ${folder.name}, ${position})
+			ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, position = EXCLUDED.position`;
+	const pins = layout.pins.map((room, position) => ({ room, position }));
+	if (pins.length > 0) await tx`INSERT INTO web_room_pins ${tx(pins)}`;
+	const placed = layout.folders.flatMap((folder) =>
+		folder.rooms.map((room, position) => ({
+			room,
+			folder: folder.id,
+			position,
+		})),
+	);
+	if (placed.length > 0)
+		await tx`INSERT INTO web_room_folder_rooms ${tx(placed)}`;
+}

package/src/app/presence.ts

@@ -46,7 +46,7 @@ export class Presence {
 		return { type: "presence", agents };
 	}
 
-	/** Sends the table to every socket once changes settle, if it changed. */
+	/** Sends the table to the owners' sockets once changes settle, if it changed. */
 	schedule(): void {
 		if (this.#pending || this.#stopped) return;
 		this.#pending = setTimeout(() => {
@@ -62,7 +62,7 @@ export class Presence {
 		const text = JSON.stringify(frame.agents);
 		if (text === this.#last || this.#stopped) return;
 		this.#last = text;
-		this.#options.sockets.broadcast(frame);
+		this.#options.sockets.deliver(frame, { owners: true });
 	}
 
 	stop(): void {

package/src/app/prompt-routes.ts

@@ -0,0 +1,167 @@
+import type {
+	PromptDocuments,
+	PromptDocumentView,
+	PromptVersion,
+} from "pi-roundtable";
+import { PromptConflictError } from "pi-roundtable";
+import type {
+	PromptConflict,
+	PromptHistoryView,
+	PromptRevert,
+	PromptSave,
+	PromptsView,
+	PromptVersionView,
+	PromptView,
+} from "../api-types.ts";
+import { json } from "../http.ts";
+import { bad, bodyOf, HttpError } from "./api-http.ts";
+import type { OwnerOf } from "./team-routes.ts";
+
+/** The most bytes a character takes in a JSON body: a control character is escaped as `\u00XX`. */
+const BYTES_PER_CHAR = 6;
+/** What a body carries besides the texts: the braces, the keys and some room. */
+const BODY_OVERHEAD = 4 * 1024;
+
+/**
+ * The largest body of a write to a document: the new text, at most `maxChars` characters, and
+ * `base`, the text in force when the edit began, which may be longer (a file version has no limit).
+ */
+const bodyLimit = (document: PromptDocumentView): number =>
+	(Math.max(document.maxChars, document.text.length, document.fileText.length) +
+		document.maxChars) *
+		BYTES_PER_CHAR +
+	BODY_OVERHEAD;
+
+export interface PromptApiOptions {
+	prompts: Pick<PromptDocuments, "list" | "get" | "set" | "revert" | "history">;
+}
+
+const viewOf = (document: PromptDocumentView): PromptView => ({
+	id: document.id,
+	label: document.label,
+	...(document.description ? { description: document.description } : {}),
+	differs: document.differs,
+	...(document.broken ? { broken: document.broken } : {}),
+	...(document.override
+		? {
+				override: {
+					by: document.override.by,
+					at: document.override.at.toISOString(),
+				},
+			}
+		: {}),
+	text: document.text,
+	fileText: document.fileText,
+	maxChars: document.maxChars,
+});
+
+/** The answer to a write, or 409 with the document as it is now when it was not the text the writer saw. */
+async function changed(
+	write: () => Promise<PromptDocumentView>,
+): Promise<Response> {
+	try {
+		return json(viewOf(await write()));
+	} catch (error) {
+		if (!(error instanceof PromptConflictError)) throw error;
+		const refused = new HttpError(
+			409,
+			"This prompt changed while you were editing it.",
+		);
+		return json(
+			{
+				error: refused.message,
+				conflict: "changed",
+				current: viewOf(error.current),
+			} satisfies PromptConflict,
+			refused.status,
+		);
+	}
+}
+
+export const promptVersionView = (
+	version: PromptVersion,
+): PromptVersionView => ({
+	id: version.id,
+	action: version.action,
+	text: version.text,
+	previous: version.previous,
+	by: version.by,
+	at: version.at.toISOString(),
+});
+
+/**
+ * The app's REST for the prompt documents: the main prompts the owner edits outside the files.
+ * Every call, a read too, is an owner's (the tier read again); a write is also checked for the
+ * console's `Origin` before it gets here. A save names the text it was edited from, and a document
+ * that changed meanwhile answers 409 with what is there now.
+ */
+export class PromptApi {
+	readonly #options: PromptApiOptions;
+
+	constructor(options: PromptApiOptions) {
+		this.#options = options;
+	}
+
+	async handle(
+		request: Request,
+		parts: string[],
+		owner: OwnerOf,
+	): Promise<Response> {
+		const { method } = request;
+		const [, , id, action] = parts;
+		const { prompts } = this.#options;
+		if (!id) {
+			if (method !== "GET") throw new HttpError(405, "Method not allowed.");
+			await owner();
+			return json({
+				documents: prompts
+					.list()
+					.map(
+						({ differs, id: key, label, description, override, broken }) => ({
+							id: key,
+							label,
+							...(description ? { description } : {}),
+							differs,
+							...(broken ? { broken } : {}),
+							...(override
+								? {
+										override: {
+											by: override.by,
+											at: override.at.toISOString(),
+										},
+									}
+								: {}),
+						}),
+					),
+			} satisfies PromptsView);
+		}
+		// The tier is read before the id is looked up, so a person below the owner learns of no id.
+		const speaker = await owner();
+		const document = prompts.get(id);
+		if (!document) throw new HttpError(404, "There is no such prompt.");
+		if (!action && method === "GET") return json(viewOf(document));
+		if (!action && method === "PUT") {
+			const body = await bodyOf(request, bodyLimit(document));
+			const { text, base } = body;
+			if (typeof text !== "string") throw bad("text must be text.");
+			if (typeof base !== "string")
+				throw bad("base must be the text the prompt was edited from.");
+			const save: PromptSave = { text, base };
+			// The registry compares `base` where the write waits its turn, so two saves cannot both pass.
+			return changed(() => prompts.set(id, save.text, speaker.name, save.base));
+		}
+		if (action === "revert" && method === "POST" && parts.length === 4) {
+			const body = await bodyOf(request, bodyLimit(document));
+			if (typeof body.base !== "string")
+				throw bad("base must be the text the prompt was reverted from.");
+			const revert: PromptRevert = { base: body.base };
+			return changed(() => prompts.revert(id, speaker.name, revert.base));
+		}
+		if (action === "history" && method === "GET" && parts.length === 4) {
+			return json({
+				versions: (await prompts.history(id)).map(promptVersionView),
+			} satisfies PromptHistoryView);
+		}
+		throw new HttpError(404, "There is no such API.");
+	}
+}