pi-roundtable-web 0.24.2 → 0.26.0

package/src/notices/mount.ts

@@ -0,0 +1,292 @@
+import { randomUUID } from "node:crypto";
+import type { SQL } from "bun";
+import type {
+	IdentityService,
+	Logger,
+	Migration,
+	PersonProfiles,
+} from "pi-roundtable";
+import type { AppSocket, Sockets } from "../app/sockets.ts";
+import type { Gate } from "../gate.ts";
+import { onboardingArea } from "../onboarding/api.ts";
+import { OnboardingService, PUSH_STEP } from "../onboarding/service.ts";
+import { builtInSteps } from "../onboarding/steps.ts";
+import { OnboardingWaivers } from "../onboarding/waivers.ts";
+import type { ResolvedOptions } from "../options.ts";
+import { linksArea, peopleArea, profileArea } from "../profile/api.ts";
+import { LinkService } from "../profile/links.ts";
+import { DeviceRoutes, PushApi } from "../push/api.ts";
+import { PushDispatch } from "../push/dispatch.ts";
+import { OutboxSender, type PushTransport } from "../push/drain.ts";
+import type { EndpointPolicy } from "../push/endpoint.ts";
+import {
+	type OutboxKind,
+	PushOutbox,
+	type ReceiptEvent,
+} from "../push/outbox.ts";
+import { PushPrefsStore } from "../push/prefs.ts";
+import type { PushSubscriptions } from "../push/subscriptions.ts";
+import type { OutboxRoute } from "../push/triggers.ts";
+import type { Vapid } from "../push/vapid.ts";
+import { webPushTransport } from "../push/web-push-transport.ts";
+import type { WebAppRegistry } from "../web-app.ts";
+import { ackFrame, noticesArea } from "./api.ts";
+import { NoticeService } from "./service.ts";
+import { NoticeStore } from "./store.ts";
+
+/** The tables of notices, push delivery, preferences and waivers. */
+export const NOTICE_MIGRATIONS: readonly Migration[] = [
+	NoticeStore.migration,
+	PushOutbox.migration,
+	PushPrefsStore.migration,
+	OnboardingWaivers.migration,
+];
+
+/** The words of a push the app sends itself when its row carries none (`push.content: "none"`). */
+const WORDS: Record<OutboxKind, string> = {
+	card: "Card waiting",
+	reply: "New reply",
+	notice: "Notice",
+	test: "Test notification",
+	clear: "",
+};
+
+export interface NoticesMountOptions {
+	database: SQL;
+	logger: Logger;
+	registry: WebAppRegistry;
+	gate: Gate;
+	sockets: Pick<Sockets, "anyVisible" | "deliver">;
+	identity: IdentityService;
+	/** Present on every host that has the identity plugin; the profile page needs it. */
+	profiles?: PersonProfiles;
+	subscriptions: PushSubscriptions;
+	policy: EndpointPolicy;
+	mount: string;
+	routing: "hash" | "path";
+	/** The tiers, content, sender and transports the options resolved to. */
+	push: Pick<
+		ResolvedOptions["push"],
+		| "tiers"
+		| "content"
+		| "preview"
+		| "sender"
+		| "transports"
+		| "subject"
+		| "endpointHosts"
+		| "fetch"
+	>;
+	/** The operator's quiet window for a normal notice; absent = none. */
+	quiet?: (at: number) => boolean;
+	/** The app's own key, present with the internal sender. */
+	vapid?: Vapid;
+	onboarding: ResolvedOptions["onboarding"];
+}
+
+export interface NoticesMount {
+	notices: NoticeService;
+	pushApi: PushApi;
+	/** Present when the app does not sign: the built-in pushes are queued for the external sender. */
+	route?: OutboxRoute;
+	outbox: PushOutbox;
+	/** Sends a socket its notices and the badge once it is ready. */
+	opened(connection: AppSocket): Promise<void>;
+	start(): void;
+	stop(): Promise<void>;
+}
+
+/**
+ * Builds the notices, the push outbox and its in-process sender (internal mode), the onboarding
+ * service and the profile and link routes, and registers them with the web app. A host plugin
+ * reaches the first three through `WEB_APP` once the web service has started.
+ */
+export function mountNotices(options: NoticesMountOptions): NoticesMount {
+	const { database, registry, sockets, identity, logger, push } = options;
+	const outbox = new PushOutbox(database);
+	const prefs = new PushPrefsStore(database);
+	const external = push.sender !== "internal";
+	const enabled = external || push.subject !== undefined;
+	const transports: PushTransport[] = [];
+	if (!external && options.vapid && push.subject)
+		transports.push(
+			webPushTransport({
+				vapid: options.vapid,
+				subject: push.subject,
+				endpointHosts: push.endpointHosts,
+				database,
+				...(push.fetch ? { fetch: push.fetch } : {}),
+				logger,
+			}),
+		);
+	const sender = external
+		? undefined
+		: new OutboxSender({
+				outbox,
+				transports,
+				render: (row) => ({
+					title: row.title ?? WORDS[row.kind],
+					...(row.body ? { body: row.body } : {}),
+				}),
+				logger,
+			});
+	const dispatch = new PushDispatch({
+		outbox,
+		prefs,
+		identity,
+		tiers: push.tiers,
+		content: push.content,
+		preview: push.preview,
+		visible: (principalId) => sockets.anyVisible(principalId),
+		...(options.quiet ? { quiet: options.quiet } : {}),
+		...(sender
+			? { kick: () => void sender.drain().catch(() => undefined) }
+			: {}),
+		enabled,
+		transports: push.transports,
+		logger,
+	});
+	const routing = { mount: options.mount, routing: options.routing };
+	const store = new NoticeStore(database);
+	const notices = new NoticeService({
+		store,
+		dispatch,
+		deliver: (frame, principal) => sockets.deliver(frame, { principal }),
+		routing,
+		logger,
+	});
+	const pushStatus = {
+		status: async (principalId: string) => {
+			const lastReceiptAt = await outbox.lastReceiptAt(principalId);
+			return {
+				devices: (await options.subscriptions.of(principalId)).length,
+				...(lastReceiptAt ? { lastReceiptAt } : {}),
+				waived: await registry.waived(principalId, PUSH_STEP),
+			};
+		},
+	};
+	const waivers = new OnboardingWaivers(database);
+	registry.setWaivers(waivers);
+	const onboarding = new OnboardingService({
+		registry,
+		waivers,
+		gate: options.gate,
+		identity,
+		...(options.profiles ? { profiles: options.profiles } : {}),
+		push: pushStatus,
+		logger,
+	});
+	const links = new LinkService({
+		registry,
+		steps: options.onboarding.links,
+		identity,
+		gate: options.gate,
+		logger,
+	});
+	registry.provide({ notices, onboarding, push: pushStatus });
+	for (const step of builtInSteps({
+		links: options.onboarding.links,
+		push: {
+			mode: options.onboarding.push,
+			waiver: options.onboarding.pushWaiver,
+		},
+		pushTiers: push.tiers,
+		prover: (provider) => registry.prover(provider),
+		identity,
+		outbox,
+	}))
+		registry.registerStep(step);
+	registry.onArea(noticesArea(notices));
+	registry.onArea(onboardingArea(onboarding));
+	registry.onArea(linksArea(links));
+	registry.onArea(
+		peopleArea({
+			profiles: options.profiles ?? { picture: async () => undefined },
+			gate: options.gate,
+		}),
+	);
+	if (options.profiles)
+		registry.onArea(
+			profileArea({
+				profiles: options.profiles,
+				identity,
+				sessionLabel: "Sign-in account",
+			}),
+		);
+	registry.onFrame("ack", ackFrame(notices));
+
+	const receipt = async (
+		principalId: string,
+		tag: string,
+		event: ReceiptEvent,
+	): Promise<boolean> => {
+		const mine = tag.startsWith("test:")
+			? await outbox.has(principalId, "test", tag)
+			: await notices.receipt(tag, principalId, event);
+		if (!mine) return false;
+		await outbox.receipt(principalId, tag, event);
+		// A receipt may finish the push step: the gate asks again.
+		onboarding.changed(principalId);
+		return true;
+	};
+	const pushApi = new PushApi({
+		vapid: {
+			publicKey:
+				push.sender === "internal"
+					? (options.vapid?.publicKey ?? "")
+					: push.sender.external.publicKey,
+		},
+		devices: new DeviceRoutes({
+			policy: options.policy,
+			subscriptions: options.subscriptions,
+			enabled,
+		}),
+		tiers: push.tiers,
+		subscriptions:
+			push.sender === "internal" || !push.sender.external.subscribePath,
+		...(enabled
+			? {
+					test: async (principalId: string) => {
+						if ((await options.subscriptions.of(principalId)).length === 0)
+							return "no-device" as const;
+						const tag = `test:${randomUUID()}`;
+						await dispatch.test(
+							principalId,
+							tag,
+							`${options.mount}/`,
+							await notices.badge(principalId),
+						);
+						return { tag };
+					},
+				}
+			: {}),
+		receipt,
+		prefs,
+	});
+	const route: OutboxRoute | undefined = external
+		? { outbox, content: push.content, badge: (id) => notices.badge(id) }
+		: undefined;
+	let sweeper: ReturnType<typeof setInterval> | undefined;
+	return {
+		notices,
+		pushApi,
+		...(route ? { route } : {}),
+		outbox,
+		opened: async (connection) => {
+			for (const frame of await notices.frames(connection.principal.id))
+				sockets.deliver(frame, { connection });
+		},
+		start: () => {
+			sender?.start();
+			const sweep = () =>
+				Promise.all([store.sweep(), outbox.sweep()]).catch((error: unknown) =>
+					logger.warn({ err: error }, "old notices were not deleted"),
+				);
+			void sweep();
+			sweeper = setInterval(sweep, 3_600_000);
+		},
+		stop: async () => {
+			clearInterval(sweeper);
+			await sender?.stop();
+		},
+	};
+}

package/src/notices/service.ts

@@ -0,0 +1,294 @@
+import { ConfigError, type Logger } from "pi-roundtable";
+import type { NoticeView, ServerFrame } from "../api-types.ts";
+import type { PushDispatch } from "../push/dispatch.ts";
+import type { Notices, OpenTarget } from "../web-app.ts";
+import type { NoticeFor, NoticeStore } from "./store.ts";
+import { openUrl, type RoutingOptions } from "./urls.ts";
+
+const MAX_TAG = 200;
+const MAX_TITLE = 200;
+const MAX_BODY = 2000;
+const MAX_RECIPIENTS = 500;
+const PAGE_ID = /^[a-z0-9-]{1,40}$/;
+
+export interface NoticeServiceOptions {
+	store: NoticeStore;
+	dispatch: PushDispatch;
+	/** Puts a frame on the open sockets of one person. */
+	deliver(frame: ServerFrame, principalId: string): void;
+	routing: RoutingOptions;
+	logger: Logger;
+}
+
+/** A notice as the bell shows it. */
+export function viewOf(notice: NoticeFor): NoticeView {
+	return {
+		tag: notice.tag,
+		title: notice.title,
+		...(notice.body ? { body: notice.body } : {}),
+		...(notice.open
+			? {
+					open:
+						"room" in notice.open
+							? {
+									room: notice.open.room,
+									...(notice.open.message === undefined
+										? {}
+										: { message: notice.open.message }),
+								}
+							: {
+									page: notice.open.page,
+									...(notice.open.query
+										? { query: { ...notice.open.query } }
+										: {}),
+								},
+				}
+			: {}),
+		urgency: notice.urgency,
+		ackable: notice.ackable,
+		raisedAt: notice.raisedAt.toISOString(),
+		...(notice.ackedAt ? { acked: true as const } : {}),
+	};
+}
+
+const refuse = (message: string): never => {
+	throw new ConfigError(`notices: ${message}`);
+};
+
+function checkOpen(open: OpenTarget | undefined): void {
+	if (!open) return;
+	if ("room" in open) {
+		if (typeof open.room !== "string" || open.room.length === 0)
+			refuse("open.room must be a room key");
+		if (
+			open.message !== undefined &&
+			!(Number.isSafeInteger(open.message) && open.message >= 0)
+		)
+			refuse("open.message must be a message id");
+	} else if (!PAGE_ID.test(open.page))
+		refuse("open.page must match [a-z0-9-]{1,40}");
+}
+
+/**
+ * The notices of the host: person-addressed, with state. A notice is a row the bell shows to its
+ * addressees and, when push is on, a push to their devices; the badge is the count of those that
+ * ask for an answer and have none. Everything a person can do to it (read, answer) is checked
+ * against the addressee list, which only the host changes.
+ */
+export class NoticeService implements Notices {
+	readonly #options: NoticeServiceOptions;
+	readonly #listeners = new Set<(tag: string, principalId: string) => void>();
+
+	constructor(options: NoticeServiceOptions) {
+		this.#options = options;
+	}
+
+	async raise(notice: Parameters<Notices["raise"]>[0]): Promise<void> {
+		const { store } = this.#options;
+		const to = [...new Set(notice.to)];
+		if (notice.tag.length === 0 || notice.tag.length > MAX_TAG)
+			refuse(`the tag must be 1 to ${MAX_TAG} characters`);
+		if (to.length === 0 || to.length > MAX_RECIPIENTS)
+			refuse(`a notice goes to 1 to ${MAX_RECIPIENTS} people`);
+		if (notice.title.length === 0 || notice.title.length > MAX_TITLE)
+			refuse(`the title must be 1 to ${MAX_TITLE} characters`);
+		if ((notice.body?.length ?? 0) > MAX_BODY)
+			refuse(`the body is longer than ${MAX_BODY} characters`);
+		checkOpen(notice.open);
+		this.#checkVia(notice.via);
+		await store.raise(
+			{
+				tag: notice.tag,
+				title: notice.title,
+				...(notice.body ? { body: notice.body } : {}),
+				...(notice.open ? { open: notice.open } : {}),
+				urgency: notice.urgency,
+				ackable: notice.ackable === true,
+			},
+			to,
+		);
+		await Promise.all(
+			to.map((principalId) =>
+				this.#tell(notice.tag, principalId, {
+					push: notice.push !== false,
+					...(notice.via ? { via: notice.via } : {}),
+				}),
+			),
+		);
+	}
+
+	async renotify(
+		tag: string,
+		add: readonly string[] = [],
+		options: { via?: readonly string[] } = {},
+	): Promise<void> {
+		this.#checkVia(options.via);
+		const people = await this.#options.store.renotify(tag, [...new Set(add)]);
+		if (!people) return;
+		await Promise.all(
+			people.map((principalId) =>
+				this.#tell(tag, principalId, {
+					push: true,
+					...(options.via ? { via: options.via } : {}),
+				}),
+			),
+		);
+	}
+
+	async resolve(
+		tag: string,
+		by?: { principalId?: string; reason: string },
+	): Promise<void> {
+		const { store } = this.#options;
+		const before = new Map<string, NoticeFor | undefined>();
+		const open = (await store.pending(tag))?.to ?? [];
+		for (const principalId of open)
+			before.set(principalId, await store.of(tag, principalId));
+		const people = await store.resolve(tag, by);
+		if (!people) return;
+		await Promise.all(
+			people.map((principalId) =>
+				this.#cleared(tag, principalId, before.get(principalId)),
+			),
+		);
+	}
+
+	/** Tells one addressee's pages and devices a notice is gone. */
+	async #cleared(
+		tag: string,
+		principalId: string,
+		was: NoticeFor | undefined,
+	): Promise<void> {
+		const { store, dispatch, routing } = this.#options;
+		this.#options.deliver({ type: "notice_resolved", tag }, principalId);
+		const count = await this.#sendBadge(principalId);
+		// Only a device that was pushed this notice has something to close.
+		if (await store.delivered(tag, principalId))
+			await dispatch.clear(
+				principalId,
+				tag,
+				openUrl(was?.open, routing),
+				count,
+			);
+	}
+
+	pending(tag: string): ReturnType<Notices["pending"]> {
+		return this.#options.store.pending(tag);
+	}
+
+	onAck(listener: (tag: string, principalId: string) => void): () => void {
+		this.#listeners.add(listener);
+		return () => this.#listeners.delete(listener);
+	}
+
+	// ── What the person does ──
+
+	/** The person's open notices and their count. */
+	async listFor(
+		principalId: string,
+	): Promise<{ notices: NoticeView[]; badge: number }> {
+		const { store } = this.#options;
+		const [notices, badge] = await Promise.all([
+			store.openFor(principalId),
+			store.unhandled(principalId),
+		]);
+		return { notices: notices.map(viewOf), badge };
+	}
+
+	/** The person handled a notice; false when it is not theirs, is closed, or asks for no answer. */
+	async ack(tag: string, principalId: string): Promise<boolean> {
+		const { store, dispatch, routing } = this.#options;
+		if (!(await store.ack(tag, principalId))) return false;
+		const notice = await store.of(tag, principalId);
+		if (notice)
+			this.#options.deliver(
+				{ type: "notice", notice: viewOf(notice) },
+				principalId,
+			);
+		const count = await this.#sendBadge(principalId);
+		// Their other devices stop showing it.
+		if (await store.delivered(tag, principalId))
+			await dispatch.clear(
+				principalId,
+				tag,
+				openUrl(notice?.open, routing),
+				count,
+			);
+		for (const listener of this.#listeners) {
+			try {
+				listener(tag, principalId);
+			} catch (error) {
+				this.#options.logger.warn({ err: error, tag }, "an ack listener threw");
+			}
+		}
+		return true;
+	}
+
+	/** Records a receipt from the service worker; false when the notice is not addressed to the person. */
+	receipt(
+		tag: string,
+		principalId: string,
+		event: "received" | "opened",
+	): Promise<boolean> {
+		return this.#options.store.receipt(tag, principalId, event);
+	}
+
+	/** The count the app icon shows for the person: their notices not handled. */
+	badge(principalId: string): Promise<number> {
+		return this.#options.store.unhandled(principalId);
+	}
+
+	/** The frames a socket gets when it opens: every notice that is open for the person, and the count. */
+	async frames(principalId: string): Promise<ServerFrame[]> {
+		const { notices, badge } = await this.listFor(principalId);
+		return [
+			...notices.map((notice): ServerFrame => ({ type: "notice", notice })),
+			{ type: "badge", count: badge },
+		];
+	}
+
+	// ── Inside ──
+
+	#checkVia(via: readonly string[] | undefined): void {
+		if (!via) return;
+		const known = this.#options.dispatch.transports;
+		if (via.length === 0) refuse("via names no transport");
+		for (const name of via)
+			if (!known.includes(name))
+				refuse(
+					`via names ${JSON.stringify(name)}, but the sender has ${known.join(", ")}; list a host transport in push.transports`,
+				);
+	}
+
+	async #sendBadge(principalId: string): Promise<number> {
+		const count = await this.#options.store.unhandled(principalId);
+		this.#options.deliver({ type: "badge", count }, principalId);
+		return count;
+	}
+
+	/** Shows a notice to one addressee and, when asked, pushes it to their devices. */
+	async #tell(
+		tag: string,
+		principalId: string,
+		options: { push: boolean; via?: readonly string[] },
+	): Promise<void> {
+		const { store, dispatch, routing } = this.#options;
+		const notice = await store.of(tag, principalId);
+		if (!notice) return;
+		this.#options.deliver(
+			{ type: "notice", notice: viewOf(notice) },
+			principalId,
+		);
+		const count = await this.#sendBadge(principalId);
+		if (!options.push) return;
+		await dispatch.notice(principalId, {
+			tag,
+			title: notice.title,
+			...(notice.body ? { body: notice.body } : {}),
+			open: openUrl(notice.open, routing),
+			urgency: notice.urgency,
+			badge: count,
+			...(options.via ? { via: options.via } : {}),
+		});
+	}
+}