pi-roundtable-web 0.25.0 → 0.26.1

package/src/push/api.ts

@@ -1,14 +1,18 @@
 import { createHash } from "node:crypto";
-import type { IdentityService } from "pi-roundtable";
+import type { Tier } from "pi-roundtable";
 import type {
 	PushDevicesView,
 	PushDeviceView,
 	PushKeyView,
+	PushPrefsView,
+	PushTestView,
 } from "../api-types.ts";
 import type { Authenticated } from "../auth/authenticator.ts";
 import { ConsoleHttpError as HttpError, json } from "../http.ts";
 import { readLimited } from "../request-body.ts";
 import type { EndpointPolicy } from "./endpoint.ts";
+import type { ReceiptEvent } from "./outbox.ts";
+import { checkPrefs, PrefsRefused, type PushPrefs } from "./prefs.ts";
 import type { PushSubscriptions } from "./subscriptions.ts";
 import type { Vapid } from "./vapid.ts";
 
@@ -21,15 +25,6 @@ const MAX_LABEL_CHARS = 80;
 const P256DH_BYTES = 65;
 const AUTH_BYTES = 16;
 
-export interface PushApiOptions {
-	vapid: Pick<Vapid, "publicKey">;
-	policy: EndpointPolicy;
-	subscriptions: Pick<PushSubscriptions, "of" | "save" | "remove">;
-	identity: Pick<IdentityService, "tierOf">;
-	/** False when the server has no VAPID contact: devices cannot be added, since nothing would reach them. */
-	enabled: boolean;
-}
-
 /** What identifies a device in a list without handing its endpoint around: the endpoint's SHA-256, hex. */
 const deviceId = (endpoint: string): string =>
 	createHash("sha256").update(endpoint).digest("hex");
@@ -57,56 +52,41 @@ async function bodyOf(request: Request): Promise<Record<string, unknown>> {
 	return value as Record<string, unknown>;
 }
 
+export interface DeviceRoutesOptions {
+	policy: EndpointPolicy;
+	subscriptions: Pick<PushSubscriptions, "of" | "save" | "remove">;
+	/** False when the server has no VAPID contact: devices cannot be added, since nothing would reach them. */
+	enabled: boolean;
+}
+
 /**
- * The push routes under `<mount>/api/push/`: the key a browser subscribes against, and the
- * signed-in owner's own devices: list, add, remove. A device is only ever read or removed by the
- * person who added it, and an endpoint is accepted only on a push service the policy allows.
+ * A person's own devices: list, add, remove. A device is only ever read or removed by the person
+ * who added it, and an endpoint is accepted only on a push service the policy allows. The app
+ * serves these under `api/push/subscriptions`, and an external sender under its own path.
  */
-export class PushApi {
-	readonly #options: PushApiOptions;
+export class DeviceRoutes {
+	readonly #options: DeviceRoutesOptions;
 
-	constructor(options: PushApiOptions) {
+	constructor(options: DeviceRoutesOptions) {
 		this.#options = options;
 	}
 
-	/** Answers `api/push/...`; undefined for any other path. */
+	/**
+	 * Answers a request about the person's devices: `id` is the device in the path, if any. Throws
+	 * `ConsoleHttpError`, which the caller turns into a response.
+	 */
 	async handle(
 		request: Request,
-		parts: readonly string[],
-		admission: Authenticated,
-	): Promise<Response | undefined> {
-		const [head, area, name, id] = parts;
-		if (head !== "api" || area !== "push") return undefined;
-		try {
-			const principalId = await this.#owner(admission);
-			const { method } = request;
-			if (name === "key" && !id && method === "GET")
-				return json({
-					key: this.#options.vapid.publicKey,
-				} satisfies PushKeyView);
-			if (name !== "subscriptions")
-				throw new HttpError(404, "There is no such API.");
-			if (!id && method === "GET")
-				return json(await this.#devices(principalId));
-			if (!id && method === "POST")
-				return await this.#add(request, principalId);
-			if (!id && method === "DELETE")
-				return await this.#removeEndpoint(request, principalId);
-			if (id && method === "DELETE")
-				return await this.#removeId(id, principalId);
-			throw new HttpError(405, "Method not allowed.");
-		} catch (error) {
-			if (error instanceof HttpError)
-				return json({ error: error.message }, error.status);
-			throw error;
-		}
-	}
-
-	async #owner(admission: Authenticated): Promise<string> {
-		const { principal } = admission.visitor;
-		if ((await this.#options.identity.tierOf(principal.id)) !== "owner")
-			throw new HttpError(403, "Only an owner may do this.");
-		return principal.id;
+		id: string | undefined,
+		principalId: string,
+	): Promise<Response> {
+		const { method } = request;
+		if (!id && method === "GET") return json(await this.#devices(principalId));
+		if (!id && method === "POST") return await this.#add(request, principalId);
+		if (!id && method === "DELETE")
+			return await this.#removeEndpoint(request, principalId);
+		if (id && method === "DELETE") return await this.#removeId(id, principalId);
+		throw new HttpError(405, "Method not allowed.");
 	}
 
 	async #devices(principalId: string): Promise<PushDevicesView> {
@@ -188,3 +168,160 @@ export class PushApi {
 		return json({ ok: true });
 	}
 }
+
+export interface PushApiOptions {
+	/** The key browsers subscribe against; an external sender's is the one the operator configured. */
+	vapid: Pick<Vapid, "publicKey">;
+	devices: DeviceRoutes;
+	/** The tiers whose people may use push. */
+	tiers: readonly Tier[];
+	/** False when the sender serves the subscription routes itself: here they answer 404. */
+	subscriptions: boolean;
+	/** Queues a test push to the person's devices; returns its tag. Undefined when push is not set up. */
+	test?(principalId: string): Promise<PushTestView | "no-device">;
+	/** Records a receipt the service worker posted; false when the tag is not the person's. */
+	receipt(
+		principalId: string,
+		tag: string,
+		event: ReceiptEvent,
+	): Promise<boolean>;
+	prefs: {
+		get(principalId: string): Promise<PushPrefs | undefined>;
+		set(principalId: string, prefs: PushPrefs | undefined): Promise<void>;
+	};
+}
+
+const EVENTS: readonly string[] = ["received", "opened"];
+
+/**
+ * The push routes under `<mount>/api/push/`: the key a browser subscribes against, the person's
+ * devices, a test push, the receipts the service worker posts back, and their quiet hours. All of
+ * it is the signed-in person's own: the principal is the session's, never one a request names.
+ */
+export class PushApi {
+	readonly #options: PushApiOptions;
+
+	constructor(options: PushApiOptions) {
+		this.#options = options;
+	}
+
+	/** Answers `api/push/...`; undefined for any other path. */
+	async handle(
+		request: Request,
+		parts: readonly string[],
+		admission: Authenticated,
+	): Promise<Response | undefined> {
+		const [head, area, name, id] = parts;
+		if (head !== "api" || area !== "push") return undefined;
+		try {
+			const { principal, tier } = admission.visitor;
+			const { method } = request;
+			// A receipt is the person's own whatever their tier: the notice or the test it names must be theirs.
+			if (name === "receipts" && !id && method === "POST")
+				return await this.#receipt(request, principal.id);
+			this.#allowed(tier);
+			if (name === "key" && !id && method === "GET")
+				return json({
+					key: this.#options.vapid.publicKey,
+				} satisfies PushKeyView);
+			if (name === "subscriptions" && this.#options.subscriptions)
+				return await this.#options.devices.handle(request, id, principal.id);
+			if (name === "test" && !id && method === "POST")
+				return await this.#test(principal.id);
+			if (name === "prefs" && !id)
+				return await this.#prefs(request, principal.id);
+			throw new HttpError(404, "There is no such API.");
+		} catch (error) {
+			if (error instanceof HttpError)
+				return json({ error: error.message }, error.status);
+			throw error;
+		}
+	}
+
+	/** The person's tier may use push; the tier is the one this request was admitted at. */
+	#allowed(tier: Tier): void {
+		if (this.#options.tiers.includes(tier)) return;
+		if (this.#options.tiers.length === 1 && this.#options.tiers[0] === "owner")
+			throw new HttpError(403, "Only an owner may do this.");
+		throw new HttpError(403, "Push is not available to you.");
+	}
+
+	async #test(principalId: string): Promise<Response> {
+		if (!this.#options.test)
+			throw new HttpError(
+				503,
+				"Push is not set up: set push.subject on the server.",
+			);
+		const made = await this.#options.test(principalId);
+		if (made === "no-device")
+			throw new HttpError(
+				409,
+				"This account has no device that gets push yet. Turn it on first.",
+			);
+		return json(made);
+	}
+
+	async #receipt(request: Request, principalId: string): Promise<Response> {
+		const body = await bodyOf(request);
+		const { tag, event } = body;
+		if (
+			typeof tag !== "string" ||
+			tag.length === 0 ||
+			tag.length > 200 ||
+			typeof event !== "string" ||
+			!EVENTS.includes(event)
+		)
+			throw new HttpError(400, "A receipt needs a tag and received or opened.");
+		const taken = await this.#options.receipt(
+			principalId,
+			tag,
+			event as ReceiptEvent,
+		);
+		if (!taken) throw new HttpError(404, "There is no such notification.");
+		return json({ ok: true });
+	}
+
+	async #prefs(request: Request, principalId: string): Promise<Response> {
+		const { prefs } = this.#options;
+		if (request.method === "GET") return json(await this.#view(principalId));
+		if (request.method !== "PUT")
+			throw new HttpError(405, "Method not allowed.");
+		const body = await bodyOf(request);
+		if (!("quiet" in body))
+			throw new HttpError(400, "Send quiet: {start, end, timeZone} or null.");
+		if (body.quiet === null) await prefs.set(principalId, undefined);
+		else {
+			const quiet = body.quiet as Partial<
+				Record<"start" | "end" | "timeZone", unknown>
+			> | null;
+			try {
+				await prefs.set(
+					principalId,
+					checkPrefs({
+						quietStart: quiet?.start,
+						quietEnd: quiet?.end,
+						timeZone: quiet?.timeZone,
+					}),
+				);
+			} catch (error) {
+				if (error instanceof PrefsRefused)
+					throw new HttpError(400, error.message);
+				throw error;
+			}
+		}
+		return json(await this.#view(principalId));
+	}
+
+	async #view(principalId: string): Promise<PushPrefsView> {
+		const prefs = await this.#options.prefs.get(principalId);
+		return prefs
+			? {
+					quiet: {
+						start: prefs.quietStart,
+						end: prefs.quietEnd,
+						timeZone: prefs.timeZone,
+					},
+				}
+			: {};
+	}
+}

package/src/push/dispatch.ts

@@ -0,0 +1,156 @@
+import type { IdentityService, Logger, Tier } from "pi-roundtable";
+import type { NewOutboxRow, OutboxKind, PushOutbox } from "./outbox.ts";
+import type { PushPrefsStore } from "./prefs.ts";
+import { previewOf } from "./triggers.ts";
+
+export interface PushDispatchOptions {
+	outbox: Pick<PushOutbox, "enqueue">;
+	prefs: Pick<PushPrefsStore, "quietAt">;
+	identity: Pick<IdentityService, "tierOf" | "speakerFor">;
+	/** The tiers whose people receive push. */
+	tiers: readonly Tier[];
+	/** `full` queues a title (and a preview with `preview`); `none` queues the kind, tag and count only. */
+	content: "full" | "none";
+	preview: boolean;
+	/** Whether a page of the person is in view now. */
+	visible(principalId: string): boolean;
+	/** The operator's quiet window, which holds back a normal notice; absent = none. */
+	quiet?: (at: number) => boolean;
+	/** Starts the in-process sender at once; absent when a separate process drains the outbox. */
+	kick?: () => void;
+	/** Whether push is set up at all (a VAPID contact, or an external sender). */
+	enabled: boolean;
+	/** The transports the sender has, which a notice's `via` may name. */
+	transports: readonly string[];
+	logger: Logger;
+	/** The clock, in milliseconds; default `Date.now`. */
+	now?: () => number;
+}
+
+/** What a notice says when it is queued for a person. */
+export interface NoticePush {
+	tag: string;
+	title: string;
+	body?: string;
+	/** The path a tap opens. */
+	open: string;
+	urgency: "normal" | "high";
+	badge: number;
+	via?: readonly string[];
+}
+
+/** Why a push was not queued; the notice itself is in the bell all the same. */
+export type Withheld = "off" | "tier" | "visible" | "quiet" | "failed";
+
+/**
+ * Decides whether a notice becomes a push for a person and queues it. A person gets it only when
+ * push is set up, their tier may receive it, and (for a normal notice) no page of theirs is in
+ * view and it is not their quiet hours or the operator's; a `high` notice ignores the last two.
+ * Whatever the content setting, the row carries a title and preview only with `content: "full"`.
+ */
+export class PushDispatch {
+	readonly #options: PushDispatchOptions;
+
+	constructor(options: PushDispatchOptions) {
+		this.#options = options;
+	}
+
+	/** The transports the sender has; a notice's `via` must name only these. */
+	get transports(): readonly string[] {
+		return this.#options.transports;
+	}
+
+	async notice(
+		principalId: string,
+		notice: NoticePush,
+	): Promise<"queued" | Withheld> {
+		const { logger } = this.#options;
+		try {
+			if (!this.#options.enabled) return "off";
+			if (!(await this.#mayReceive(principalId))) return "tier";
+			if (notice.urgency === "normal") {
+				if (this.#options.visible(principalId)) return "visible";
+				const at = (this.#options.now ?? Date.now)();
+				if (this.#options.quiet?.(at)) return "quiet";
+				if (await this.#options.prefs.quietAt(principalId, at)) return "quiet";
+			}
+			await this.#queue(principalId, "notice", notice);
+			return "queued";
+		} catch (error) {
+			logger.warn({ err: error, tag: notice.tag }, "a notice was not queued");
+			return "failed";
+		}
+	}
+
+	/** Tells the person's devices a notice is gone: closes its notification and sets the count. */
+	async clear(
+		principalId: string,
+		tag: string,
+		open: string,
+		badge: number,
+	): Promise<void> {
+		try {
+			if (!this.#options.enabled) return;
+			await this.#queue(principalId, "clear", {
+				tag,
+				title: "",
+				open,
+				urgency: "normal",
+				badge,
+			});
+		} catch (error) {
+			this.#options.logger.warn(
+				{ err: error, tag },
+				"a notice was not cleared on the devices",
+			);
+		}
+	}
+
+	/** A test push to the person's own devices; it is not held back by quiet hours or an open page. */
+	async test(principalId: string, tag: string, open: string, badge: number) {
+		await this.#queue(principalId, "test", {
+			tag,
+			title: "Test notification",
+			body: "Notifications work on this device.",
+			open,
+			urgency: "normal",
+			badge,
+		});
+	}
+
+	async #mayReceive(principalId: string): Promise<boolean> {
+		const { identity, tiers } = this.#options;
+		const lasting = await identity.tierOf(principalId);
+		if (lasting) return tiers.includes(lasting);
+		try {
+			return tiers.includes((await identity.speakerFor(principalId)).tier);
+		} catch {
+			return false;
+		}
+	}
+
+	async #queue(
+		principalId: string,
+		kind: OutboxKind,
+		notice: NoticePush,
+	): Promise<void> {
+		const { content, preview, outbox, kick } = this.#options;
+		const row: NewOutboxRow = {
+			kind,
+			tag: notice.tag,
+			principalId,
+			open: notice.open,
+			urgency: notice.urgency,
+			badge: notice.badge,
+			...(content === "full" && kind !== "clear"
+				? {
+						title: notice.title,
+						...(preview && notice.body ? { body: previewOf(notice.body) } : {}),
+					}
+				: {}),
+			...(notice.via ? { via: notice.via } : {}),
+		};
+		await outbox.enqueue(row);
+		kick?.();
+	}
+}

package/src/push/drain.ts

@@ -0,0 +1,139 @@
+import type { Logger } from "pi-roundtable";
+import type { DeliveryResult, OutboxRow, PushOutbox } from "./outbox.ts";
+
+/** How a transport carries a push; a host adds its own beside `web-push`. */
+export interface PushTransport {
+	/** The name a notice's `via` uses, such as `web-push`. */
+	name: string;
+	send(
+		row: OutboxRow,
+		rendered: { title: string; body?: string },
+		signal: AbortSignal,
+	): Promise<DeliveryResult>;
+}
+
+export interface OutboxSenderOptions {
+	outbox: Pick<PushOutbox, "claim" | "finish" | "sweep">;
+	/** Tried in order for each row until one says `sent`. */
+	transports: readonly PushTransport[];
+	/** Words a row. With push.content `none` a row carries no text, so this is where it comes from. */
+	render(row: OutboxRow): { title: string; body?: string };
+	logger: Logger;
+	/** How often the outbox is looked at; default 1 s. */
+	intervalMs?: number;
+	/** How long one transport may take for one row; default 20 s. */
+	transportTimeoutMs?: number;
+	/** The most rows taken at once; default 20. */
+	batch?: number;
+}
+
+const SWEEP_EVERY_MS = 3_600_000;
+
+/**
+ * The loop that empties the push outbox: it takes queued rows, words each with `render`, offers it
+ * to the row's transports in order until one says `sent`, and records what each said. A transport
+ * that throws or runs out of time counts as `failed`; one row never stops the others.
+ */
+export class OutboxSender {
+	readonly #options: OutboxSenderOptions;
+	#timer: ReturnType<typeof setInterval> | undefined;
+	#sweeper: ReturnType<typeof setInterval> | undefined;
+	#running: Promise<number> | undefined;
+	#stopped = false;
+
+	constructor(options: OutboxSenderOptions) {
+		this.#options = options;
+	}
+
+	start(): void {
+		this.#stopped = false;
+		this.#timer = setInterval(() => {
+			this.drain().catch((error: unknown) =>
+				this.#options.logger.warn(
+					{ err: error },
+					"the push outbox was not read",
+				),
+			);
+		}, this.#options.intervalMs ?? 1000);
+		this.#sweeper = setInterval(() => {
+			this.#options.outbox
+				.sweep()
+				.catch((error: unknown) =>
+					this.#options.logger.warn(
+						{ err: error },
+						"old pushes were not deleted",
+					),
+				);
+		}, SWEEP_EVERY_MS);
+	}
+
+	async stop(): Promise<void> {
+		this.#stopped = true;
+		clearInterval(this.#timer);
+		clearInterval(this.#sweeper);
+		await this.#running?.catch(() => undefined);
+	}
+
+	/** Takes and sends what is queued now; returns how many rows it finished. Calls do not overlap. */
+	drain(): Promise<number> {
+		this.#running ??= this.#drain().finally(() => {
+			this.#running = undefined;
+		});
+		return this.#running;
+	}
+
+	async #drain(): Promise<number> {
+		let finished = 0;
+		for (;;) {
+			if (this.#stopped) return finished;
+			const rows = await this.#options.outbox.claim(this.#options.batch ?? 20);
+			if (rows.length === 0) return finished;
+			for (const row of rows) {
+				await this.#one(row);
+				finished += 1;
+			}
+		}
+	}
+
+	async #one(row: OutboxRow): Promise<void> {
+		const { transports, logger } = this.#options;
+		const chosen = row.via
+			? row.via.flatMap((name) => {
+					const found = transports.find((t) => t.name === name);
+					return found ? [found] : [];
+				})
+			: transports;
+		const deliveries: { transport: string; result: DeliveryResult }[] = [];
+		let rendered: { title: string; body?: string };
+		try {
+			// A row that clears a notice has no words.
+			rendered =
+				row.kind === "clear" ? { title: "" } : this.#options.render(row);
+		} catch (error) {
+			logger.warn({ err: error, kind: row.kind }, "a push was not worded");
+			await this.#options.outbox.finish(row.id, [
+				{ transport: "render", result: "failed" },
+			]);
+			return;
+		}
+		for (const transport of chosen) {
+			let result: DeliveryResult;
+			try {
+				result = await transport.send(
+					row,
+					rendered,
+					AbortSignal.timeout(this.#options.transportTimeoutMs ?? 20_000),
+				);
+			} catch (error) {
+				logger.warn(
+					{ err: error, transport: transport.name },
+					"a push transport failed",
+				);
+				result = "failed";
+			}
+			deliveries.push({ transport: transport.name, result });
+			if (result === "sent") break;
+		}
+		await this.#options.outbox.finish(row.id, deliveries);
+	}
+}