pi-roundtable-web 0.25.0 → 0.26.1

package/src/host/host-routes.ts

@@ -0,0 +1,396 @@
+import type { HostCardView, RoomMessage, SendWording } from "../api-types.ts";
+import { bad, bodyOf, HttpError } from "../app/api-http.ts";
+import { PAGE_LIMIT } from "../app/room-log.ts";
+import { json } from "../http.ts";
+import type {
+	ActionResult,
+	FormValues,
+	HostRoomKind,
+	RoomHeader,
+	RouteArea,
+	Viewer,
+} from "../web-app.ts";
+import { checkActions, safeLink } from "./forms.ts";
+import { actInRoom, hostRoomOf } from "./frames.ts";
+import { asRoom, type HostContext } from "./host-context.ts";
+import {
+	cardView,
+	checkPicture,
+	readsOf,
+	withExpiredFiles,
+} from "./room-views.ts";
+import type {
+	HostActionResult,
+	HostHeaderView,
+	HostListView,
+	HostMessagesView,
+	HostPageView,
+	HostRoomSummaryView,
+	HostRoomView,
+} from "./views.ts";
+
+/** How many messages a room opens with. */
+const OPEN_LIMIT = 50;
+/** The largest JSON body an action reads: a form's values. */
+const ACT_BODY_BYTES = 512 * 1024;
+
+const nothing = () => new HttpError(404, "There is no such room.");
+
+/** The query of a request's URL. */
+export const queryOf = (request: Request): URLSearchParams =>
+	URL.parse(request.url)?.searchParams ?? new URLSearchParams();
+
+/** An action's answer as the page is sent it: `open` and `url` are kept only when they are places the page may go. */
+export function resultView(result: ActionResult): HostActionResult {
+	if (!result.ok)
+		return {
+			ok: false,
+			error: String(result.error).slice(0, 1_000),
+			...(result.field === undefined ? {} : { field: result.field }),
+		};
+	const open =
+		result.open && "room" in result.open
+			? {
+					room: String(result.open.room),
+					...(result.open.message === undefined
+						? {}
+						: { message: result.open.message }),
+				}
+			: result.open && "page" in result.open
+				? {
+						page: String(result.open.page),
+						...(result.open.query ? { query: { ...result.open.query } } : {}),
+					}
+				: undefined;
+	return {
+		ok: true,
+		...(result.notice === undefined
+			? {}
+			: { notice: String(result.notice).slice(0, 1_000) }),
+		...(open ? { open } : {}),
+		...(result.url !== undefined && safeLink(result.url)
+			? { url: result.url }
+			: {}),
+	};
+}
+
+/** The values of an action's `input`: text, or a list of text, by field name. */
+export function inputOf(value: unknown): FormValues {
+	if (value === undefined) return {};
+	if (typeof value !== "object" || value === null || Array.isArray(value))
+		throw bad("input must be an object.");
+	const input: Record<string, string | readonly string[]> = {};
+	for (const [name, field] of Object.entries(value)) {
+		if (typeof field === "string") input[name] = field;
+		else if (
+			Array.isArray(field) &&
+			field.every((one) => typeof one === "string")
+		)
+			input[name] = field as string[];
+		else throw bad("input holds text or lists of text.");
+	}
+	return input;
+}
+
+/** A host's header, cut down to what the page draws and checked. */
+function headerView(header: RoomHeader): HostHeaderView {
+	checkActions(header.actions, "a room's header");
+	for (const field of header.fields)
+		if (field.link !== undefined && !safeLink(field.link))
+			throw new Error(
+				`a header link ${JSON.stringify(field.link)} must be https or a path of this origin`,
+			);
+	return {
+		title: String(header.title).slice(0, 200),
+		fields: header.fields.slice(0, 40).map((field) => ({
+			label: String(field.label).slice(0, 120),
+			value: String(field.value).slice(0, 2_000),
+			...(field.link ? { link: field.link } : {}),
+		})),
+		actions: structuredClone([...header.actions]),
+		...(header.banner
+			? {
+					banner: {
+						tone: header.banner.tone,
+						text: String(header.banner.text).slice(0, 2_000),
+					},
+				}
+			: {}),
+	};
+}
+
+/**
+ * The REST of the host's rooms below `api/host/`: the list of a kind, a room as it opens, older
+ * messages, and a press on a button. The authority is the kind's `access`, asked again on every
+ * request; to anyone it gives nothing, a room, a kind and a message are all 404.
+ */
+export function hostArea(ctx: HostContext): RouteArea {
+	return {
+		area: "host",
+		handle: async (request, parts, { viewer }) => {
+			const [kindName, id, action] = parts;
+			const { method } = request;
+			if (!kindName) throw nothing();
+			if (!id) {
+				if (method !== "GET") throw new HttpError(405, "Method not allowed.");
+				return json(await list(ctx, viewer, kindName, request));
+			}
+			const room = `${ctx.surface}:${kindName}.${id}`;
+			if (!hostRoomOf(ctx, room)) throw nothing();
+			if (!action && method === "GET")
+				return json(await open(ctx, viewer, room));
+			if (action === "messages" && method === "GET" && parts.length === 3)
+				return json(await older(ctx, viewer, room, request));
+			if (action === "act" && method === "POST" && parts.length === 3)
+				return act(ctx, viewer, room, request);
+			throw new HttpError(404, "There is no such API.");
+		},
+	};
+}
+
+async function list(
+	ctx: HostContext,
+	viewer: Viewer,
+	kindName: string,
+	request: Request,
+): Promise<HostListView> {
+	const kind = ctx.registry.kind(kindName);
+	if (!kind) throw nothing();
+	const params = queryOf(request);
+	const filter = params.get("filter");
+	const cursor = params.get("cursor");
+	const given = await kind.list(viewer, {
+		...(filter === null ? {} : { filter }),
+		...(cursor === null ? {} : { cursor }),
+	});
+	ctx.listed.set(viewer.principalId, kindName, given !== undefined);
+	if (!given) throw nothing();
+	const rooms: HostRoomSummaryView[] = [];
+	for (const summary of given.rooms) {
+		const key = `${ctx.surface}:${kindName}.${summary.id}`;
+		if (!hostRoomOf(ctx, key)) {
+			ctx.logger.warn(
+				{ kind: kindName },
+				"a room of a kind was left out of its list: its id is not 8 to 64 letters, digits, - or _",
+			);
+			continue;
+		}
+		let picture = summary.picture;
+		if (picture) {
+			try {
+				picture = checkPicture(picture);
+			} catch {
+				picture = undefined;
+			}
+		}
+		rooms.push({
+			id: summary.id,
+			key,
+			title: String(summary.title).slice(0, 200),
+			...(summary.subtitle === undefined
+				? {}
+				: { subtitle: String(summary.subtitle).slice(0, 300) }),
+			...(picture ? { picture } : {}),
+			...(summary.lastAt === undefined ? {} : { lastAt: summary.lastAt }),
+			...(summary.attention ? { attention: true } : {}),
+		});
+	}
+	// The app counts what is unread for this person; a number the host gave is replaced.
+	const unread = await ctx.reads.unread(
+		viewer.principalId,
+		rooms.map((room) => room.key),
+	);
+	return {
+		kind: kindName,
+		label: kind.label,
+		rooms: rooms.map((room) => {
+			const count = unread.get(room.key);
+			return count ? { ...room, unread: count } : room;
+		}),
+		...(given.cursor === undefined ? {} : { cursor: given.cursor }),
+	};
+}
+
+async function headerOf(
+	ctx: HostContext,
+	kind: HostRoomKind,
+	viewer: Viewer,
+	id: string,
+): Promise<HostHeaderView> {
+	try {
+		const header = await kind.header?.(viewer, id);
+		if (header) return headerView(header);
+	} catch (error) {
+		ctx.logger.warn(
+			{ kind: kind.kind, err: error },
+			"a room's header could not be read",
+		);
+	}
+	return { title: id, fields: [], actions: [] };
+}
+
+async function open(
+	ctx: HostContext,
+	viewer: Viewer,
+	room: string,
+): Promise<HostRoomView> {
+	const found = hostRoomOf(ctx, room);
+	if (!found) throw nothing();
+	const access = await ctx.access.of(viewer, room);
+	if (!access) throw nothing();
+	const cursor = await ctx.reads.cursorOf(room, viewer.principalId);
+	const [header, page, stored] = await Promise.all([
+		headerOf(ctx, found.kind, viewer, found.id),
+		ctx.log.page(room, undefined, OPEN_LIMIT),
+		ctx.cards.list(room),
+	]);
+	const cards: HostCardView[] = await Promise.all(
+		stored.map((card) => cardView(viewer, found, access, card)),
+	);
+	return {
+		room,
+		kind: found.kind.kind,
+		id: found.id,
+		access: { send: [...access.send], act: access.act },
+		...wordingOf(found.kind.sendWording),
+		header,
+		messages: withExpiredFiles(page.messages, ctx.files),
+		more: page.more,
+		cards,
+		reads: await readsOf(ctx.reads, room, viewer.principalId, ctx.nameOf),
+		...(cursor === undefined ? {} : { cursor }),
+	};
+}
+
+/** The longest label and placeholder a kind may give, in characters. */
+const LABEL_CHARS = 40;
+const PLACEHOLDER_CHARS = 100;
+
+const trimmed = (value: unknown, chars: number): string | undefined =>
+	typeof value === "string"
+		? Array.from(value.trim()).slice(0, chars).join("") || undefined
+		: undefined;
+
+/** The kind's wording of the two ways to write as the page may show it: text only, cut short; nothing when it gave none. */
+function wordingOf(wording: SendWording | undefined): {
+	wording?: SendWording;
+} {
+	const note = trimmed(wording?.note?.placeholder, PLACEHOLDER_CHARS);
+	const label = trimmed(wording?.turn?.label, LABEL_CHARS);
+	const turn = trimmed(wording?.turn?.placeholder, PLACEHOLDER_CHARS);
+	if (!note && !label && !turn) return {};
+	return {
+		wording: {
+			...(note ? { note: { placeholder: note } } : {}),
+			...(label || turn
+				? {
+						turn: {
+							...(label ? { label } : {}),
+							...(turn ? { placeholder: turn } : {}),
+						},
+					}
+				: {}),
+		},
+	};
+}
+
+async function older(
+	ctx: HostContext,
+	viewer: Viewer,
+	room: string,
+	request: Request,
+): Promise<HostMessagesView> {
+	if (!(await ctx.access.of(viewer, room))) throw nothing();
+	const params = queryOf(request);
+	const before = params.get("before");
+	const limit = params.get("limit");
+	const beforeId = before === null ? undefined : Number(before);
+	const count = limit === null ? OPEN_LIMIT : Number(limit);
+	if (
+		(beforeId !== undefined && !Number.isInteger(beforeId)) ||
+		!Number.isInteger(count) ||
+		count < 1 ||
+		count > PAGE_LIMIT
+	)
+		throw bad("before and limit must be whole numbers.");
+	const page = await ctx.log.page(room, beforeId, count);
+	const messages: RoomMessage[] = withExpiredFiles(page.messages, ctx.files);
+	return {
+		messages,
+		more: page.more,
+		reads: await readsOf(ctx.reads, room, viewer.principalId, ctx.nameOf),
+	};
+}
+
+async function act(
+	ctx: HostContext,
+	viewer: Viewer,
+	room: string,
+	request: Request,
+): Promise<Response> {
+	const body = await bodyOf(request, ACT_BODY_BYTES);
+	const { action, card } = body;
+	if (typeof action !== "string" || action === "" || action.length > 200)
+		throw bad("action must be text.");
+	if (card !== undefined && (typeof card !== "string" || card.length > 200))
+		throw bad("card must be text.");
+	const outcome = await actInRoom(ctx, viewer, asRoom(room), {
+		action,
+		...(card === undefined ? {} : { card }),
+		input: inputOf(body.input),
+	});
+	if ("refused" in outcome) {
+		if (outcome.refused === "unknown") throw nothing();
+		throw new HttpError(403, "This is not yours to do.");
+	}
+	return json(resultView(outcome.result));
+}
+
+/** The most query parameters a page is given, and the longest value. */
+const MAX_QUERY = 20;
+const MAX_QUERY_VALUE = 500;
+
+/**
+ * The REST of the host's pages below `api/pages/`: a page's view and the press of one of its
+ * actions. A page the viewer may not see is 404, as `visible` says it afresh on every call.
+ */
+export function pagesArea(ctx: HostContext): RouteArea {
+	return {
+		area: "pages",
+		handle: async (request, parts, { viewer }) => {
+			const [id, action] = parts;
+			const { method } = request;
+			if (!id) throw new HttpError(404, "There is no such page.");
+			if (!action && method === "GET") {
+				const query: Record<string, string> = {};
+				let count = 0;
+				for (const [key, value] of queryOf(request)) {
+					count += 1;
+					if (count > MAX_QUERY || value.length > MAX_QUERY_VALUE)
+						throw bad("The page's query is too long.");
+					query[key] = value;
+				}
+				const view = await ctx.pages.view(viewer, id, query);
+				if (!view) throw new HttpError(404, "There is no such page.");
+				return json(view satisfies HostPageView);
+			}
+			if (action === "act" && method === "POST" && parts.length === 2) {
+				const body = await bodyOf(request, ACT_BODY_BYTES);
+				if (
+					typeof body.action !== "string" ||
+					body.action === "" ||
+					body.action.length > 200
+				)
+					throw bad("action must be text.");
+				const outcome = await ctx.pages.act(viewer, id, {
+					action: body.action,
+					input: inputOf(body.input),
+				});
+				if ("refused" in outcome)
+					throw new HttpError(404, "There is no such page.");
+				return json(resultView(outcome.result));
+			}
+			throw new HttpError(404, "There is no such API.");
+		},
+	};
+}

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]) }
+						: {}),
+				},
+			};
+		}
+	}
+}