pi-roundtable-web 0.24.2 → 0.26.0

package/src/host/pages.ts

@@ -0,0 +1,266 @@
+import type { EventSink, Logger } from "pi-roundtable";
+import { PluginError } from "pi-roundtable";
+import type { FileDir } from "../app/files.ts";
+import { viewerOfSocket } from "../app/socket.ts";
+import type { AppSocket, Sockets } from "../app/sockets.ts";
+import type {
+	ActionResult,
+	FormValues,
+	HostPage,
+	HostPages,
+	PageSection,
+	Viewer,
+	WebAppRegistry,
+} from "../web-app.ts";
+import { checkActions, checkCard, safeLink } from "./forms.ts";
+import { markdownImageType } from "./rooms-service.ts";
+import type { HostPageView, PageSectionView } from "./views.ts";
+
+/** The most sections a page has, rows a list has, and characters a text section has. */
+const MAX_SECTIONS = 50;
+const MAX_ROWS = 500;
+const MAX_TEXT = 100_000;
+const COALESCE_MS = 100;
+
+export interface HostPagesOptions {
+	registry: Pick<WebAppRegistry, "page" | "hostPages">;
+	sockets: Pick<Sockets, "each" | "deliver">;
+	files: FileDir;
+	maxFileBytes: number;
+	events: Pick<EventSink, "action"> | undefined;
+	now(): number;
+	logger: Logger;
+}
+
+/** The file binding of an image a page keeps: the page's id after this prefix. */
+export const PAGE_BINDING = "page:";
+
+/** What a press on a page reached. */
+export type PageOutcome =
+	| { result: ActionResult }
+	| { refused: "unknown" | "forbidden" };
+
+/**
+ * The host's pages (`WebApp.pages`): each viewed, acted on and refreshed only for those the page's
+ * own `visible` says it is for, asked again on every call. What a page returns is checked and
+ * cut to size here, because it comes from a plugin.
+ */
+export class HostPagesService implements HostPages {
+	readonly #options: HostPagesOptions;
+	readonly #pending = new Map<string, ReturnType<typeof setTimeout>>();
+
+	constructor(options: HostPagesOptions) {
+		this.#options = options;
+	}
+
+	/** The page when the viewer may see it now; a page that cannot say is not visible. */
+	async visible(viewer: Viewer, id: string): Promise<HostPage | undefined> {
+		const page = this.#options.registry.page(id);
+		if (!page) return undefined;
+		try {
+			return (await page.visible(viewer)) ? page : undefined;
+		} catch (error) {
+			this.#options.logger.warn(
+				{ page: id, err: error },
+				"a page's visibility was not read",
+			);
+			return undefined;
+		}
+	}
+
+	async view(
+		viewer: Viewer,
+		id: string,
+		query: Readonly<Record<string, string>>,
+	): Promise<HostPageView | undefined> {
+		const page = await this.visible(viewer, id);
+		if (!page) return undefined;
+		const view = await page.view(viewer, query);
+		if (view.sections.length > MAX_SECTIONS)
+			throw new PluginError(
+				`web app: a page has at most ${MAX_SECTIONS} sections`,
+			);
+		return {
+			id,
+			title: String(view.title).slice(0, 200),
+			sections: view.sections.map((section) => sectionView(section, id)),
+		};
+	}
+
+	async act(
+		viewer: Viewer,
+		id: string,
+		press: { action: string; input?: FormValues },
+	): Promise<PageOutcome> {
+		const page = await this.visible(viewer, id);
+		if (!page?.act) return { refused: "unknown" };
+		let result: ActionResult;
+		try {
+			result = await page.act(viewer, press.action, press.input ?? {});
+		} catch (error) {
+			this.#options.logger.warn(
+				{ page: id, err: error },
+				"a page action failed",
+			);
+			result = { ok: false, error: "The action could not be done." };
+		}
+		this.#options.events?.action?.({
+			kind: "act",
+			actor: viewer.speakerId,
+			principalId: viewer.principalId,
+			channel: `page:${id}`,
+			ok: result.ok,
+			at: new Date(this.#options.now()),
+		});
+		return { result };
+	}
+
+	changed(id?: string): void {
+		const ids =
+			id === undefined
+				? this.#options.registry.hostPages().map((page) => page.id)
+				: [id];
+		for (const page of ids) {
+			if (this.#pending.has(page)) continue;
+			// Calls that come together tell the viewers once.
+			this.#pending.set(
+				page,
+				setTimeout(() => {
+					this.#pending.delete(page);
+					this.#tell(page);
+				}, COALESCE_MS),
+			);
+		}
+	}
+
+	#tell(id: string): void {
+		const { sockets } = this.#options;
+		sockets.each(
+			(connection) => connection.started === true,
+			(connection: AppSocket) => {
+				const viewer = viewerOfSocket(connection);
+				this.visible(viewer, id).then(
+					(page) => {
+						if (page)
+							sockets.deliver(
+								{ type: "page_changed", page: id },
+								{ connection },
+							);
+					},
+					() => undefined,
+				);
+			},
+		);
+	}
+
+	async saveAsset(
+		page: string,
+		file: { name: string; type: string; bytes: Uint8Array | ReadableStream },
+	): Promise<string> {
+		if (!this.#options.registry.page(page))
+			throw new PluginError(`web app: there is no page ${page}`);
+		const chunks: Uint8Array[] = [];
+		if (file.bytes instanceof Uint8Array) chunks.push(file.bytes);
+		else {
+			const reader = file.bytes.getReader();
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				chunks.push(value as Uint8Array);
+			}
+		}
+		const size = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+		if (size === 0 || size > this.#options.maxFileBytes)
+			throw new PluginError(
+				`web app: a page image is 1 to ${this.#options.maxFileBytes} bytes`,
+			);
+		const bytes = new Uint8Array(size);
+		let at = 0;
+		for (const chunk of chunks) {
+			bytes.set(chunk, at);
+			at += chunk.byteLength;
+		}
+		const type = markdownImageType(bytes);
+		if (!type)
+			throw new PluginError("web app: a page image is a PNG, JPEG or WebP");
+		return this.#options.files.put(file.name, type, bytes, undefined, {
+			room: `${PAGE_BINDING}${page}`,
+		}).id;
+	}
+
+	stop(): void {
+		for (const timer of this.#pending.values()) clearTimeout(timer);
+		this.#pending.clear();
+	}
+}
+
+function cut(text: string): string {
+	return text.length > MAX_TEXT ? text.slice(0, MAX_TEXT) : text;
+}
+
+function sectionView(section: PageSection, page: string): PageSectionView {
+	switch (section.kind) {
+		case "markdown":
+			return { kind: "markdown", text: cut(String(section.text)) };
+		case "list": {
+			if (section.rows.length > MAX_ROWS)
+				throw new PluginError(`web app: a list has at most ${MAX_ROWS} rows`);
+			return {
+				kind: "list",
+				...(section.title === undefined
+					? {}
+					: { title: String(section.title).slice(0, 200) }),
+				rows: section.rows.map((row) => {
+					if (row.open !== undefined && !safeLink(row.open))
+						throw new PluginError(
+							`web app: a row's open ${JSON.stringify(row.open)} must be https or a path of this origin`,
+						);
+					return {
+						title: String(row.title).slice(0, 300),
+						...(row.subtitle === undefined
+							? {}
+							: { subtitle: String(row.subtitle).slice(0, 500) }),
+						...(row.open === undefined ? {} : { open: row.open }),
+						...(row.attention ? { attention: true } : {}),
+						...(row.actions?.length
+							? {
+									actions: structuredClone([
+										...checkActions(row.actions, `page ${page}`),
+									]),
+								}
+							: {}),
+					};
+				}),
+			};
+		}
+		case "form":
+			checkActions(
+				[{ id: "form", label: "form", form: section.form }],
+				`page ${page}`,
+			);
+			return {
+				kind: "form",
+				form: structuredClone(section.form),
+				action: String(section.action),
+			};
+		case "card": {
+			checkCard(section.card);
+			const { title, body, tone, state, links, buttons } = section.card;
+			return {
+				kind: "card",
+				card: {
+					title,
+					body,
+					...(tone ? { tone } : {}),
+					...(state ? { state } : {}),
+					...(links?.length
+						? { links: links.map((link) => ({ ...link })) }
+						: {}),
+					...(buttons?.length && (state === undefined || state === "open")
+						? { buttons: structuredClone([...buttons]) }
+						: {}),
+				},
+			};
+		}
+	}
+}

package/src/host/reads.ts

@@ -0,0 +1,155 @@
+import type { SQL } from "bun";
+import type { Migration } from "pi-roundtable";
+
+/** Where one person has read a room up to. */
+export interface ReadMark {
+	principalId: string;
+	/** The id of the newest message they have read. */
+	upTo: number;
+	/** ISO time. */
+	at: string;
+}
+
+interface MarkRow {
+	principal_id: string;
+	last_read_id: string | number | bigint;
+	read_at: Date;
+}
+
+/**
+ * The read cursors, one per person and room, kept in `web_room_reads`. A cursor only moves
+ * forward: reading an older message again, or a second device that is behind, changes nothing.
+ * A message counts as unread for a person when it is newer than their cursor and is not a line the
+ * server wrote (a divider, a yolo approval), which is nobody's to read.
+ */
+export class RoomReads {
+	readonly #sql: SQL;
+
+	constructor(sql: SQL) {
+		this.#sql = sql;
+	}
+
+	static readonly migration: Migration = {
+		name: "web-room-reads",
+		up: async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS web_room_reads (
+					room text NOT NULL,
+					principal_id text NOT NULL,
+					last_read_id bigint NOT NULL,
+					read_at timestamptz NOT NULL DEFAULT now(),
+					PRIMARY KEY (room, principal_id)
+				)`;
+		},
+	};
+
+	/**
+	 * Moves the person's cursor in the room up to `upTo`, no further than the room's newest
+	 * message. The mark when the cursor moved, undefined when it stayed where it was.
+	 */
+	async advance(
+		room: string,
+		principalId: string,
+		upTo: number,
+	): Promise<ReadMark | undefined> {
+		const [row]: MarkRow[] = await this.#sql`
+			INSERT INTO web_room_reads (room, principal_id, last_read_id)
+			SELECT ${room}, ${principalId}, LEAST(${upTo}::bigint, newest.id)
+			FROM (SELECT COALESCE(max(id), 0) AS id FROM web_room_messages WHERE room = ${room}) AS newest
+			WHERE newest.id > 0
+			ON CONFLICT (room, principal_id) DO UPDATE
+				SET last_read_id = EXCLUDED.last_read_id, read_at = now()
+				WHERE web_room_reads.last_read_id < EXCLUDED.last_read_id
+			RETURNING principal_id, last_read_id, read_at`;
+		return row && markOf(row);
+	}
+
+	/** The person's cursor in the room, or undefined when they never read it. */
+	async cursorOf(
+		room: string,
+		principalId: string,
+	): Promise<number | undefined> {
+		const [row]: { last_read_id: string | number | bigint }[] = await this.#sql`
+			SELECT last_read_id FROM web_room_reads
+			WHERE room = ${room} AND principal_id = ${principalId}`;
+		return row === undefined ? undefined : Number(row.last_read_id);
+	}
+
+	/** Everyone's cursor in the room: who has read up to where. */
+	async marks(room: string): Promise<ReadMark[]> {
+		const rows: MarkRow[] = await this.#sql`
+			SELECT principal_id, last_read_id, read_at FROM web_room_reads
+			WHERE room = ${room} ORDER BY read_at`;
+		return rows.map(markOf);
+	}
+
+	/**
+	 * How many messages each room holds past the person's cursor. A person who never read a room
+	 * has every message to read, unless `baseline` names the room: its cursor is then set to the
+	 * newest message the first time it is asked, so what was there before they could have read
+	 * anything counts as read. Rooms with nothing unread are left out.
+	 */
+	async unread(
+		principalId: string,
+		rooms: readonly string[],
+		baseline: ReadonlySet<string> = new Set(),
+	): Promise<Map<string, number>> {
+		const counts = new Map<string, number>();
+		if (rooms.length === 0) return counts;
+		const start = rooms.filter((room) => baseline.has(room));
+		if (start.length > 0) {
+			await this.#sql`
+				INSERT INTO web_room_reads (room, principal_id, last_read_id)
+				SELECT room, ${principalId}, max(id) FROM web_room_messages
+				WHERE room IN ${this.#sql(start)} GROUP BY room
+				ON CONFLICT (room, principal_id) DO NOTHING`;
+			// A room with nothing in it yet starts at the beginning, so what is first said there is unread.
+			const held: { room: string }[] = await this.#sql`
+				SELECT room FROM web_room_reads
+				WHERE principal_id = ${principalId} AND room IN ${this.#sql(start)}`;
+			const have = new Set(held.map((row) => row.room));
+			const empty = start
+				.filter((room) => !have.has(room))
+				.map((room) => ({
+					room,
+					principal_id: principalId,
+					last_read_id: 0,
+				}));
+			if (empty.length > 0)
+				await this.#sql`
+					INSERT INTO web_room_reads ${this.#sql(empty)}
+					ON CONFLICT (room, principal_id) DO NOTHING`;
+		}
+		const rows: { room: string; unread: string | number | bigint }[] =
+			await this.#sql`
+			SELECT m.room, count(*) AS unread
+			FROM web_room_messages m
+			LEFT JOIN web_room_reads r ON r.room = m.room AND r.principal_id = ${principalId}
+			WHERE m.room IN ${this.#sql(rooms)} AND m.kind <> 'system'
+				AND m.id > COALESCE(r.last_read_id, 0)
+			GROUP BY m.room`;
+		for (const row of rows) counts.set(row.room, Number(row.unread));
+		return counts;
+	}
+
+	/** Forgets the cursors of rooms that are gone. */
+	async removeRoom(room: string): Promise<void> {
+		await this.#sql`DELETE FROM web_room_reads WHERE room = ${room}`;
+	}
+
+	/** Forgets the cursors of rooms of a kind whose messages are all gone. */
+	async sweepOrphans(prefix: string): Promise<void> {
+		await this.#sql`
+			DELETE FROM web_room_reads r
+			WHERE starts_with(r.room, ${prefix})
+				AND NOT EXISTS (SELECT 1 FROM web_room_messages m WHERE m.room = r.room)`;
+	}
+}
+
+function markOf(row: MarkRow): ReadMark {
+	return {
+		principalId: row.principal_id,
+		upTo: Number(row.last_read_id),
+		at: row.read_at.toISOString(),
+	};
+}

package/src/host/retention.ts

@@ -0,0 +1,41 @@
+import type { HostContext } from "./host-context.ts";
+
+const DAY_MS = 86_400_000;
+
+/** What one sweep of the host kinds' retention removed. */
+export interface HostSweep {
+	messages: number;
+	cards: number;
+	files: number;
+}
+
+/**
+ * Deletes what the registered kinds no longer keep: for a kind with `retention`, its messages and
+ * cards older than `textDays` (counted from the message's own time, so an import dated long ago
+ * goes at once), and the files those messages carried. Files have their own expiry, which the
+ * stored files' sweep applies; a message whose files went first keeps its row and says "file expired".
+ */
+export async function sweepHostKinds(
+	ctx: Pick<
+		HostContext,
+		"registry" | "surface" | "log" | "cards" | "reads" | "files" | "now"
+	>,
+): Promise<HostSweep> {
+	const total: HostSweep = { messages: 0, cards: 0, files: 0 };
+	for (const kind of ctx.registry.kinds()) {
+		if (!kind.retention) continue;
+		const prefix = `${ctx.surface}:${kind.kind}.`;
+		const before = new Date(ctx.now() - kind.retention.textDays * DAY_MS);
+		const gone = await ctx.log.sweepKind(prefix, before);
+		total.messages += gone.length;
+		for (const message of gone)
+			for (const file of message.files)
+				if (ctx.files.binding(file.id)?.room === message.room) {
+					ctx.files.remove(file.id);
+					total.files += 1;
+				}
+		total.cards += await ctx.cards.sweepKind(prefix, before);
+		await ctx.reads.sweepOrphans(prefix);
+	}
+	return total;
+}

package/src/host/room-views.ts

@@ -0,0 +1,137 @@
+import type { ChannelKey } from "pi-roundtable";
+import type {
+	HostCardView,
+	PictureRef,
+	ReadMarkView,
+	RoomMessage,
+} from "../api-types.ts";
+import type { FileDir } from "../app/files.ts";
+import type {
+	HostRoomKind,
+	RoomAccess,
+	StoredHostCard,
+	Viewer,
+} from "../web-app.ts";
+import { pressable } from "./forms.ts";
+import type { RoomReads } from "./reads.ts";
+
+const FILE_ID =
+	/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const COLOR = /^#[0-9a-fA-F]{6}$/;
+
+/** Throws when a picture is not one the page may draw: a stored file, a person, or initials. */
+export function checkPicture(picture: PictureRef): PictureRef {
+	const bad = (): never => {
+		throw new Error(
+			"a picture is a stored file, a principal, or initials with a #rrggbb color; never an outside URL",
+		);
+	};
+	if (typeof picture !== "object" || picture === null) return bad();
+	if ("file" in picture)
+		return typeof picture.file === "string" && FILE_ID.test(picture.file)
+			? { file: picture.file }
+			: bad();
+	if ("principal" in picture)
+		return typeof picture.principal === "string" &&
+			picture.principal.length > 0 &&
+			picture.principal.length <= 200
+			? { principal: picture.principal }
+			: bad();
+	if ("initials" in picture)
+		return typeof picture.initials === "string" &&
+			picture.initials.length >= 1 &&
+			picture.initials.length <= 4 &&
+			typeof picture.color === "string" &&
+			COLOR.test(picture.color)
+			? { initials: picture.initials, color: picture.color }
+			: bad();
+	return bad();
+}
+
+/**
+ * The messages as the page is shown them: a file whose bytes retention deleted is taken out of the
+ * message's files and counted in `expiredFiles`, so the page says "file expired" instead of
+ * offering a download that answers 404.
+ */
+export function withExpiredFiles(
+	messages: readonly RoomMessage[],
+	files: Pick<FileDir, "has">,
+): RoomMessage[] {
+	return messages.map((message) => {
+		if (message.files.length === 0) return message;
+		const present = message.files.filter((file) => files.has(file.id));
+		const gone = message.files.length - present.length;
+		return gone === 0
+			? message
+			: { ...message, files: present, expiredFiles: gone };
+	});
+}
+
+/** A host room a key names. */
+export interface FoundRoom {
+	kind: HostRoomKind;
+	id: string;
+}
+
+/**
+ * The buttons of a host card this viewer may press: none once the card is settled, none without
+ * `access.act`, and otherwise the card's own, narrowed by the kind's `buttons` when it has one.
+ */
+export function buttonsFor(
+	viewer: Viewer,
+	found: FoundRoom,
+	access: RoomAccess,
+	card: StoredHostCard,
+): NonNullable<StoredHostCard["buttons"]> {
+	const all = card.buttons ?? [];
+	if (!access.act || !pressable(card) || all.length === 0) return [];
+	if (!found.kind.buttons) return all;
+	const allowed = new Set(found.kind.buttons(viewer, found.id, card));
+	return all.filter((button) => allowed.has(button.id));
+}
+
+/** A host card as one viewer sees it. */
+export function cardView(
+	viewer: Viewer,
+	found: FoundRoom,
+	access: RoomAccess,
+	card: StoredHostCard,
+): HostCardView {
+	const buttons = buttonsFor(viewer, found, access, card);
+	return {
+		id: card.id,
+		room: card.room,
+		title: card.title,
+		body: card.body,
+		...(card.tone ? { tone: card.tone } : {}),
+		...(card.state ? { state: card.state } : {}),
+		...(card.links?.length
+			? { links: card.links.map((link) => ({ ...link })) }
+			: {}),
+		...(buttons.length
+			? { buttons: buttons.map((button) => structuredClone(button)) }
+			: {}),
+		at: card.createdAt.toISOString(),
+		updatedAt: card.updatedAt.toISOString(),
+	};
+}
+
+/** Where the others have read a room up to, each with a name; the viewer's own mark is left out. */
+export async function readsOf(
+	reads: Pick<RoomReads, "marks">,
+	room: ChannelKey | string,
+	viewerPrincipal: string,
+	nameOf: (principalId: string) => Promise<string>,
+): Promise<ReadMarkView[]> {
+	const marks = (await reads.marks(room)).filter(
+		(mark) => mark.principalId !== viewerPrincipal,
+	);
+	return Promise.all(
+		marks.map(async (mark) => ({
+			principal: mark.principalId,
+			name: await nameOf(mark.principalId),
+			upTo: mark.upTo,
+			at: mark.at,
+		})),
+	);
+}