pi-roundtable-web 0.25.0 → 0.26.1

package/src/push/outbox.ts

@@ -0,0 +1,218 @@
+import type { SQL } from "bun";
+import type { Migration } from "pi-roundtable";
+
+/**
+ * What a push is about; a sender renders its words from it. A `clear` row has no words: it tells
+ * the devices a notice is gone (close its notification, set the count), and a transport that has
+ * no such thing skips it.
+ */
+export type OutboxKind = "card" | "reply" | "notice" | "test" | "clear";
+
+/**
+ * One push to one person, queued for a sender. It carries what a sender needs to word and address
+ * the push, and no host-room content: `title` and `body` are present only with `push.content`
+ * `full`.
+ */
+export interface OutboxRow {
+	id: number;
+	kind: OutboxKind;
+	/** Pushes with one tag replace each other on a device; a notice's tag is its dedupe key. */
+	tag: string;
+	principalId: string;
+	/** Where a tap goes: a path under the app's origin. */
+	open: string;
+	urgency: "normal" | "high";
+	/** The count the app icon shows after this push: the person's notices not handled. */
+	badge: number;
+	title?: string;
+	body?: string;
+	/** The transports that may carry the row, in order; absent = all the sender has, in order. */
+	via?: readonly string[];
+	createdAt: Date;
+}
+
+export type NewOutboxRow = Omit<OutboxRow, "id" | "createdAt">;
+
+/** What a transport said of one delivery. */
+export type DeliveryResult = "sent" | "gone" | "failed" | "skipped";
+
+interface Row {
+	id: string | number;
+	kind: OutboxKind;
+	tag: string;
+	principal_id: string;
+	open: string;
+	urgency: "normal" | "high";
+	badge: number;
+	title: string | null;
+	body: string | null;
+	via: string[] | null;
+	created_at: Date;
+}
+
+const rowOf = (row: Row): OutboxRow => ({
+	id: Number(row.id),
+	kind: row.kind,
+	tag: row.tag,
+	principalId: row.principal_id,
+	open: row.open,
+	urgency: row.urgency,
+	badge: row.badge,
+	...(row.title === null ? {} : { title: row.title }),
+	...(row.body === null ? {} : { body: row.body }),
+	...(row.via === null ? {} : { via: row.via }),
+	createdAt: row.created_at,
+});
+
+/** A claimed row that no sender finished is claimed again after this long. */
+const CLAIM_LEASE_SECONDS = 60;
+/** Finished rows, deliveries and receipts are kept this long, in days. */
+export const OUTBOX_KEEP_DAYS = 30;
+/** A device that returned a receipt this recently counts as working. */
+export const RECEIPT_WINDOW_DAYS = 30;
+
+/** A receipt the service worker posted: the notification arrived, or was opened. */
+export type ReceiptEvent = "received" | "opened";
+
+/**
+ * The queue between the app and the process that signs and sends pushes (`web_push_outbox`), what
+ * the sender did with each row (`web_push_deliveries`), and the receipts the service worker posts
+ * back (`web_push_receipts`). The app and an external sender both use it: the sender needs only to
+ * read and update the outbox and insert deliveries.
+ */
+export class PushOutbox {
+	readonly #sql: SQL;
+
+	constructor(sql: SQL) {
+		this.#sql = sql;
+	}
+
+	static readonly migration: Migration = {
+		name: "web-push-outbox",
+		up: async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS web_push_outbox (
+					id bigserial PRIMARY KEY,
+					kind text NOT NULL,
+					tag text NOT NULL,
+					principal_id text NOT NULL,
+					open text NOT NULL,
+					urgency text NOT NULL,
+					badge integer NOT NULL DEFAULT 0,
+					title text,
+					body text,
+					via text[],
+					created_at timestamptz NOT NULL DEFAULT now(),
+					claimed_at timestamptz,
+					done_at timestamptz
+				)`;
+			await sql`CREATE INDEX IF NOT EXISTS web_push_outbox_open ON web_push_outbox (id) WHERE done_at IS NULL`;
+			await sql`CREATE INDEX IF NOT EXISTS web_push_outbox_done ON web_push_outbox (done_at)`;
+			await sql`
+				CREATE TABLE IF NOT EXISTS web_push_deliveries (
+					outbox_id bigint NOT NULL,
+					transport text NOT NULL,
+					endpoint_hash text,
+					result text NOT NULL,
+					at timestamptz NOT NULL DEFAULT now()
+				)`;
+			await sql`CREATE INDEX IF NOT EXISTS web_push_deliveries_outbox ON web_push_deliveries (outbox_id)`;
+			await sql`
+				CREATE TABLE IF NOT EXISTS web_push_receipts (
+					principal_id text NOT NULL,
+					tag text NOT NULL,
+					event text NOT NULL,
+					at timestamptz NOT NULL DEFAULT now()
+				)`;
+			await sql`CREATE INDEX IF NOT EXISTS web_push_receipts_principal ON web_push_receipts (principal_id, at DESC)`;
+		},
+	};
+
+	/** Queues a push; returns its id. */
+	async enqueue(row: NewOutboxRow): Promise<number> {
+		const [made]: { id: string | number }[] = await this.#sql`
+			INSERT INTO web_push_outbox (kind, tag, principal_id, open, urgency, badge, title, body, via)
+			VALUES (${row.kind}, ${row.tag}, ${row.principalId}, ${row.open}, ${row.urgency},
+				${row.badge}, ${row.title ?? null}, ${row.body ?? null},
+				${row.via ? this.#sql.array([...row.via], "TEXT") : null})
+			RETURNING id`;
+		if (!made) throw new Error("the push outbox did not return an id");
+		return Number(made.id);
+	}
+
+	/** Takes up to `limit` rows no sender holds, oldest first; a row held longer than the lease is taken again. */
+	async claim(limit: number): Promise<OutboxRow[]> {
+		const rows: Row[] = await this.#sql`
+			UPDATE web_push_outbox SET claimed_at = now()
+			WHERE id IN (
+				SELECT id FROM web_push_outbox
+				WHERE done_at IS NULL
+					AND (claimed_at IS NULL OR claimed_at < now() - make_interval(secs => ${CLAIM_LEASE_SECONDS}))
+				ORDER BY id LIMIT ${limit}
+				FOR UPDATE SKIP LOCKED)
+			RETURNING *`;
+		return rows.map(rowOf).sort((a, b) => a.id - b.id);
+	}
+
+	/** Records what the transports said of a row and finishes it. */
+	async finish(
+		id: number,
+		deliveries: readonly { transport: string; result: DeliveryResult }[],
+	): Promise<void> {
+		await this.#sql.begin(async (tx) => {
+			for (const delivery of deliveries)
+				await tx`
+					INSERT INTO web_push_deliveries (outbox_id, transport, result)
+					VALUES (${id}, ${delivery.transport}, ${delivery.result})`;
+			await tx`UPDATE web_push_outbox SET done_at = now() WHERE id = ${id}`;
+		});
+	}
+
+	/** Whether the person has a queued push of this kind and tag, which makes a receipt for it theirs. */
+	async has(
+		principalId: string,
+		kind: OutboxKind,
+		tag: string,
+	): Promise<boolean> {
+		const [found]: { n: number }[] = await this.#sql`
+			SELECT count(*)::int AS n FROM web_push_outbox
+			WHERE principal_id = ${principalId} AND kind = ${kind} AND tag = ${tag}`;
+		return (found?.n ?? 0) > 0;
+	}
+
+	async receipt(
+		principalId: string,
+		tag: string,
+		event: ReceiptEvent,
+	): Promise<void> {
+		await this.#sql`
+			INSERT INTO web_push_receipts (principal_id, tag, event)
+			VALUES (${principalId}, ${tag}, ${event})`;
+	}
+
+	/** When a device of the person last posted a receipt, within the window; undefined for none. */
+	async lastReceiptAt(
+		principalId: string,
+		withinDays = RECEIPT_WINDOW_DAYS,
+	): Promise<Date | undefined> {
+		const [found]: { at: Date | null }[] = await this.#sql`
+			SELECT max(at) AS at FROM web_push_receipts
+			WHERE principal_id = ${principalId}
+				AND at > now() - make_interval(days => ${withinDays})`;
+		return found?.at ?? undefined;
+	}
+
+	/** Deletes finished rows, their deliveries and old receipts; returns how many rows went. */
+	async sweep(): Promise<number> {
+		const gone: { id: string | number }[] = await this.#sql`
+			DELETE FROM web_push_outbox
+			WHERE done_at < now() - make_interval(days => ${OUTBOX_KEEP_DAYS}) RETURNING id`;
+		await this.#sql`
+			DELETE FROM web_push_deliveries d WHERE NOT EXISTS (
+				SELECT 1 FROM web_push_outbox o WHERE o.id = d.outbox_id)`;
+		await this.#sql`
+			DELETE FROM web_push_receipts
+			WHERE at < now() - make_interval(days => ${OUTBOX_KEEP_DAYS})`;
+		return gone.length;
+	}
+}

package/src/push/prefs.ts

@@ -0,0 +1,118 @@
+import type { SQL } from "bun";
+import type { Migration } from "pi-roundtable";
+import { minutesOfDay, QuietClock, type QuietWindow } from "./quiet-hours.ts";
+
+/** A person's own quiet hours: no push for a normal notice in the window, on their time zone's clock. */
+export interface PushPrefs {
+	/** `HH:MM`, where the window begins. */
+	quietStart: string;
+	/** `HH:MM`, where it ends; before `start` when it crosses midnight. */
+	quietEnd: string;
+	/** The IANA zone the times are read in. */
+	timeZone: string;
+}
+
+interface Row {
+	quiet_start: string;
+	quiet_end: string;
+	time_zone: string;
+}
+
+/** Why a preference was refused, in words the page shows. */
+export class PrefsRefused extends Error {}
+
+/** Checks the three fields; throws `PrefsRefused` for a time that is not `HH:MM`, equal times or an unknown zone. */
+export function checkPrefs(value: unknown): PushPrefs {
+	const given = value as Partial<PushPrefs> | null;
+	if (
+		typeof given !== "object" ||
+		given === null ||
+		typeof given.quietStart !== "string" ||
+		typeof given.quietEnd !== "string" ||
+		typeof given.timeZone !== "string"
+	)
+		throw new PrefsRefused(
+			"Quiet hours need quietStart, quietEnd and timeZone.",
+		);
+	if (
+		minutesOfDay(given.quietStart) === undefined ||
+		minutesOfDay(given.quietEnd) === undefined
+	)
+		throw new PrefsRefused("Quiet hours are times like 22:00 and 07:30.");
+	if (given.quietStart === given.quietEnd)
+		throw new PrefsRefused("The two times of the quiet hours must differ.");
+	try {
+		new QuietClock(
+			{ start: given.quietStart, end: given.quietEnd },
+			given.timeZone,
+		);
+	} catch {
+		throw new PrefsRefused("That time zone is not known.");
+	}
+	return {
+		quietStart: given.quietStart,
+		quietEnd: given.quietEnd,
+		timeZone: given.timeZone,
+	};
+}
+
+/** The people's quiet hours, in `web_push_prefs`. */
+export class PushPrefsStore {
+	readonly #sql: SQL;
+
+	constructor(sql: SQL) {
+		this.#sql = sql;
+	}
+
+	static readonly migration: Migration = {
+		name: "web-push-prefs",
+		up: async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS web_push_prefs (
+					principal_id text PRIMARY KEY,
+					quiet_start text NOT NULL,
+					quiet_end text NOT NULL,
+					time_zone text NOT NULL
+				)`;
+		},
+	};
+
+	async get(principalId: string): Promise<PushPrefs | undefined> {
+		const [row]: Row[] = await this.#sql`
+			SELECT quiet_start, quiet_end, time_zone FROM web_push_prefs
+			WHERE principal_id = ${principalId}`;
+		return row
+			? {
+					quietStart: row.quiet_start,
+					quietEnd: row.quiet_end,
+					timeZone: row.time_zone,
+				}
+			: undefined;
+	}
+
+	/** Stores the person's quiet hours, or removes them with `undefined`. */
+	async set(principalId: string, prefs: PushPrefs | undefined): Promise<void> {
+		if (!prefs) {
+			await this
+				.#sql`DELETE FROM web_push_prefs WHERE principal_id = ${principalId}`;
+			return;
+		}
+		await this.#sql`
+			INSERT INTO web_push_prefs (principal_id, quiet_start, quiet_end, time_zone)
+			VALUES (${principalId}, ${prefs.quietStart}, ${prefs.quietEnd}, ${prefs.timeZone})
+			ON CONFLICT (principal_id) DO UPDATE SET
+				quiet_start = EXCLUDED.quiet_start, quiet_end = EXCLUDED.quiet_end,
+				time_zone = EXCLUDED.time_zone`;
+	}
+
+	/** Whether the moment is inside the person's quiet hours; false when they set none. */
+	async quietAt(principalId: string, at: number): Promise<boolean> {
+		const prefs = await this.get(principalId);
+		if (!prefs) return false;
+		const window: QuietWindow = {
+			start: prefs.quietStart,
+			end: prefs.quietEnd,
+		};
+		return new QuietClock(window, prefs.timeZone).quietAt(at);
+	}
+}

package/src/push/sender.ts

@@ -18,7 +18,11 @@ export interface PushPayload {
 	url?: string;
 	/** Notifications with one tag replace each other on the device. */
 	tag: string;
-	kind: "card" | "cap" | "reply" | "notice";
+	kind: "card" | "cap" | "reply" | "notice" | "test" | "clear";
+	/** The count the app icon shows after this push; absent = leave it. */
+	badge?: number;
+	/** `high` asks the device to keep the notification until it is dealt with. */
+	urgency?: "normal" | "high";
 }
 
 /** The part of a stored subscription the sender needs. */
@@ -83,7 +87,8 @@ export class PushSender {
 					"content-encoding": "aes128gcm",
 					"content-type": "application/octet-stream",
 					ttl: String(TTL_SECONDS),
-					urgency: payload.kind === "reply" ? "normal" : "high",
+					urgency:
+						payload.urgency ?? (payload.kind === "reply" ? "normal" : "high"),
 				},
 				body,
 				// A push service never redirects; a redirect would walk past the allowlist.

package/src/push/triggers.ts

@@ -1,4 +1,5 @@
 import type { IdentityService, Logger } from "pi-roundtable";
+import type { NewOutboxRow, PushOutbox } from "./outbox.ts";
 import type { PushPayload, PushSender, SendResult } from "./sender.ts";
 import type { PushSubscriptions, Subscription } from "./subscriptions.ts";
 
@@ -7,12 +8,26 @@ export const PREVIEW_CHARS = 120;
 /** Replies in one room closer together than this share a notification. */
 const REPLY_QUIET_MS = 15_000;
 
+/**
+ * Where the push goes when the app does not sign it: the outbox an external sender empties. The
+ * app then holds no VAPID key and a row carries a title and a preview only with `content: "full"`.
+ */
+export interface OutboxRoute {
+	outbox: Pick<PushOutbox, "enqueue">;
+	content: "full" | "none";
+	/** The count the app icon shows for the person: their notices not handled. */
+	badge(principalId: string): Promise<number>;
+}
+
 export interface PushServiceOptions {
 	subscriptions: Pick<
 		PushSubscriptions,
 		"all" | "delivered" | "forget" | "failed"
 	>;
-	sender: Pick<PushSender, "send">;
+	/** Signs and sends in this process; absent when `route` queues the pushes for an external sender. */
+	sender?: Pick<PushSender, "send">;
+	/** Queue the pushes instead of signing them here; absent = sign and send in this process. */
+	route?: OutboxRoute;
 	identity: Pick<IdentityService, "tierOf">;
 	/** Whether a page of this person is in view now; their devices are not pushed while one is. */
 	visible(principalId: string): boolean;
@@ -33,6 +48,8 @@ export interface PushServiceOptions {
 	 * card is. Default never.
 	 */
 	muted?: (room: string) => Promise<boolean>;
+	/** Whether a room is a host's: those reach phones only through notices, never through a card or reply push. */
+	hostRoom?: (room: string) => boolean;
 }
 
 /** What a trigger says; the service shapes it into a notification. */
@@ -72,6 +89,7 @@ export class PushService {
 
 	/** A card opened in a room: an approval or a question waits for an owner. */
 	card(room: string, title: string, longRunningCap: boolean): Promise<void> {
+		if (this.#options.hostRoom?.(room)) return Promise.resolve();
 		return this.#push({
 			kind: longRunningCap ? "cap" : "card",
 			title: longRunningCap ? "Long-running cap reached" : "Card waiting",
@@ -83,6 +101,7 @@ export class PushService {
 
 	/** An agent posted in a room, such as a finished job's report or an answer nobody was watching for. */
 	async reply(room: string, author: string, text: string): Promise<void> {
+		if (this.#options.hostRoom?.(room)) return;
 		const now = this.#now();
 		if (this.#options.quiet?.(now)) return;
 		if (await this.#muted(room)) return;
@@ -142,12 +161,15 @@ export class PushService {
 				...(preview && event.text ? { body: previewOf(event.text) } : {}),
 			};
 			const targets = await this.#targets(event.principalId);
+			if (this.#options.route) {
+				await this.#queue(this.#options.route, event, payload, targets);
+				return;
+			}
+			const { sender } = this.#options;
+			if (!sender) return;
 			await Promise.all(
 				targets.map(async (target) =>
-					this.#settle(
-						target,
-						await this.#options.sender.send(target, payload),
-					),
+					this.#settle(target, await sender.send(target, payload)),
 				),
 			);
 		} catch (error) {
@@ -155,6 +177,35 @@ export class PushService {
 		}
 	}
 
+	/** One outbox row for each person the push reaches; the sender finds their devices. */
+	async #queue(
+		route: OutboxRoute,
+		event: Event,
+		payload: PushPayload,
+		targets: readonly Subscription[],
+	): Promise<void> {
+		const people = [...new Set(targets.map((target) => target.principalId))];
+		await Promise.all(
+			people.map(async (principalId) => {
+				const row: NewOutboxRow = {
+					kind: payload.kind === "cap" ? "card" : payload.kind,
+					tag: payload.tag,
+					principalId,
+					open: payload.url ?? "",
+					urgency: payload.kind === "reply" ? "normal" : "high",
+					badge: await route.badge(principalId),
+					...(route.content === "full"
+						? {
+								title: event.title,
+								...(payload.body ? { body: payload.body } : {}),
+							}
+						: {}),
+				};
+				await route.outbox.enqueue(row);
+			}),
+		);
+	}
+
 	async #targets(principalId?: string): Promise<Subscription[]> {
 		const owners = new Map<string, boolean>();
 		const isOwner = async (id: string): Promise<boolean> => {

package/src/push/vapid.ts

@@ -71,6 +71,25 @@ async function importStored(stored: Stored, path: string): Promise<Vapid> {
 	return { publicKey: stored.publicKey, privateKey };
 }
 
+/**
+ * The VAPID keys in `path`, which must exist: for a sender process that holds the key the app
+ * never sees. A missing or unreadable file stops it, since a new key would not match the one the
+ * devices subscribed against.
+ */
+export async function readVapid(path: string): Promise<Vapid> {
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT")
+			throw new Error(
+				`${path} does not exist; the sender needs the VAPID key file the devices subscribed against`,
+			);
+		throw error;
+	}
+	return importStored(parse(raw, path), path);
+}
+
 /**
  * The VAPID keys in `path`, made on first use with WebCrypto and kept readable by this user
  * alone. Subscriptions are bound to the public key, so the file must outlive a restart; a file

package/src/push/web-push-transport.ts

@@ -0,0 +1,106 @@
+import type { SQL } from "bun";
+import type { Logger } from "pi-roundtable";
+import type { PushTransport } from "./drain.ts";
+import { EndpointPolicy } from "./endpoint.ts";
+import { type PushPayload, PushSender } from "./sender.ts";
+import { PushSubscriptions } from "./subscriptions.ts";
+import { readVapid, type Vapid } from "./vapid.ts";
+
+/** The name of the Web Push transport, which a notice's `via` may name. */
+export const WEB_PUSH = "web-push";
+
+export interface WebPushTransportOptions {
+	/** The key the devices subscribed against. Read when the first push is sent; it must exist. */
+	vapidFile?: string;
+	/** The key itself, when the caller already holds it (the app's own sender). */
+	vapid?: Vapid;
+	/** The VAPID `sub`: a `mailto:` or `https:` contact for the push services. */
+	subject: string;
+	/** Push services besides the browsers' own, as `push.endpointHosts` writes them. */
+	endpointHosts?: readonly string[];
+	database: SQL;
+	/** The HTTP client; default `fetch`. */
+	fetch?: typeof fetch;
+	logger?: Logger;
+}
+
+/** A logger that says nothing, for a sender run without one. */
+const silent: Logger = {
+	debug: () => undefined,
+	info: () => undefined,
+	warn: () => undefined,
+	error: () => undefined,
+	fatal: () => undefined,
+	child: () => silent,
+};
+
+/** What a push says on a device, from the row and the words the sender gave it. */
+export function payloadOf(
+	row: Parameters<PushTransport["send"]>[0],
+	rendered: Parameters<PushTransport["send"]>[1],
+): PushPayload {
+	return {
+		kind: row.kind,
+		title: rendered.title,
+		...(rendered.body ? { body: rendered.body } : {}),
+		tag: row.tag,
+		url: row.open,
+		badge: row.badge,
+		urgency: row.urgency,
+	};
+}
+
+/**
+ * Web Push to all the devices a person subscribed. It reads their subscriptions, posts a sealed
+ * payload to each under the VAPID key, forgets a device the push service says is gone, and counts
+ * a failure against one that keeps failing. `sent` when at least one device took it; `gone` when
+ * every device was gone; `skipped` when the person has no device.
+ */
+export function webPushTransport(
+	options: WebPushTransportOptions,
+): PushTransport {
+	const subscriptions = new PushSubscriptions(options.database);
+	const policy = new EndpointPolicy(options.endpointHosts);
+	const logger = options.logger ?? silent;
+	let sender: Promise<PushSender> | undefined;
+	const senderOf = (): Promise<PushSender> => {
+		sender ??= (async () => {
+			const vapid =
+				options.vapid ??
+				(options.vapidFile ? await readVapid(options.vapidFile) : undefined);
+			if (!vapid) throw new Error("webPushTransport needs vapidFile or vapid");
+			return new PushSender({
+				vapid,
+				subject: options.subject,
+				policy,
+				...(options.fetch ? { fetch: options.fetch } : {}),
+				logger,
+			});
+		})();
+		return sender;
+	};
+	return {
+		name: WEB_PUSH,
+		async send(row, rendered, signal) {
+			const devices = await subscriptions.of(row.principalId);
+			if (devices.length === 0) return "skipped";
+			const push = await senderOf();
+			const payload = payloadOf(row, rendered);
+			let sent = 0;
+			let gone = 0;
+			for (const device of devices) {
+				if (signal.aborted) break;
+				const result = await push.send(device, payload);
+				if (result === "sent") {
+					sent += 1;
+					await subscriptions.delivered(device.endpoint);
+				} else if (result === "gone") {
+					gone += 1;
+					await subscriptions.forget(device.endpoint);
+				} else await subscriptions.failed(device.endpoint);
+			}
+			if (sent > 0) return "sent";
+			return gone === devices.length ? "gone" : "failed";
+		},
+	};
+}

package/src/push-sender/index.ts

@@ -0,0 +1,14 @@
+// The entry `pi-roundtable-web/push-sender`: the process that signs and sends the web app's pushes
+// when the app holds no VAPID key (`push.sender: { external }`). The app queues each push as a row
+// in `web_push_outbox`; this empties it through transports (Web Push here, a host's own beside it).
+
+export type { PushTransport } from "../push/drain.ts";
+export type { DeliveryResult, OutboxKind, OutboxRow } from "../push/outbox.ts";
+export { WEB_PUSH, webPushTransport } from "../push/web-push-transport.ts";
+export type { PushSenderOptions } from "./run.ts";
+export { runPushSender } from "./run.ts";
+export {
+	SESSION_COOKIE,
+	webSessionClaims,
+	webSessionPrincipal,
+} from "./session.ts";