cursedbelt 2.7.0 → 3.0.0

package/src/server/notifications/hub.ts

@@ -1,245 +0,0 @@
-/**
- * Live delivery for the notification center — the half that makes a bell badge
- * change without anybody clicking anything.
- *
- * The center already has the seam (`NotificationSink`); what was missing was a
- * transport behind it. This is that transport, as **SSE** rather than a
- * WebSocket, and the reason is the shape of the traffic: notifications are
- * server→client only, they must survive a laptop lid closing, and a browser
- * reconnects an `EventSource` by itself. A WebSocket would mean writing the
- * reconnect loop, the heartbeat and the backoff that `EventSource` already has
- * — and `cursedbelt/server/ws` remains the right answer for anything the client
- * needs to send back up.
- *
- * 🔴 **A hub is a cache of who is listening, never a queue.** A notification is
- * already durable (it is a row) before a sink is called, so a subscriber that
- * is asleep, disconnected or behind a proxy that ate the stream loses nothing:
- * the next list/poll returns the same row. That is why every emit here is
- * fire-and-forget and a failing subscriber is dropped rather than retried — the
- * poll transport in `cursedbelt/react/notifications` is the backstop, and it is
- * not optional.
- */
-import type { AppNotification, NotificationSink } from "cwip/notifications";
-
-/** What a subscriber receives. `unread` rides alongside so a bell badge never
- *  has to make a second request to learn its own number. */
-export type NotificationHubEvent =
-	| { kind: "notification"; notification: AppNotification }
-	| { kind: "unread"; userId: string; count: number };
-
-export type NotificationHubListener = (event: NotificationHubEvent) => void;
-
-export interface NotificationHubOptions {
-	/**
-	 * Comment-line heartbeat cadence, in ms. Default 25s — under the 30s idle
-	 * timeout nginx and Cloudflare both default to, which is what silently kills
-	 * an otherwise healthy SSE stream. 0 disables it (tests).
-	 */
-	heartbeatMs?: number;
-	/**
-	 * Max concurrent streams per user. Default 8. A tab is a stream, and a
-	 * browser left open for a week accumulates them; without a cap one person's
-	 * tab habit is an unbounded server-side array.
-	 */
-	maxStreamsPerUser?: number;
-	/** Reported when a listener throws. Never rethrown — see the module doc. */
-	onError?: (error: unknown, context: string) => void;
-}
-
-export interface NotificationHub {
-	/**
-	 * Hand this to `createNotificationCenter({ sink })`. Every `notify*` then
-	 * reaches the connected tabs of exactly the addressed user.
-	 */
-	readonly sink: NotificationSink;
-	/** Register a listener for one user's events. Returns an unsubscribe fn. */
-	subscribe(userId: string, listener: NotificationHubListener): () => void;
-	/** An SSE `Response` for one user — the thing a route returns. */
-	stream(userId: string, options?: { signal?: AbortSignal }): Response;
-	/** How many live subscribers a user has (all users when omitted). */
-	subscriberCount(userId?: string): number;
-	/** Drop every subscriber and stop every heartbeat (shutdown, and tests). */
-	close(): void;
-}
-
-const SSE_HEADERS: Record<string, string> = {
-	"content-type": "text/event-stream; charset=utf-8",
-	"cache-control": "no-store, no-transform",
-	connection: "keep-alive",
-	// nginx buffers proxied responses by default, which turns a live stream into
-	// one delivered when it ends. The fleet's box is behind nginx; this is the
-	// header that opts out, and it is inert everywhere else.
-	"x-accel-buffering": "no",
-};
-
-const encodeEvent = (event: NotificationHubEvent): string => {
-	const name = event.kind;
-	const data = event.kind === "notification" ? event.notification : { count: event.count };
-	return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
-};
-
-export function createNotificationHub(options: NotificationHubOptions = {}): NotificationHub {
-	const heartbeatMs = options.heartbeatMs ?? 25_000;
-	const maxStreamsPerUser = options.maxStreamsPerUser ?? 8;
-	const onError = options.onError ?? (() => {});
-	/** userId → listeners. An empty set is deleted, so the map never grows with
-	 *  the user table — only with who is actually connected right now. */
-	const listeners = new Map<string, Set<NotificationHubListener>>();
-	let closed = false;
-
-	const emit = (userId: string, event: NotificationHubEvent): void => {
-		const set = listeners.get(userId);
-		if (!set) return;
-		// Snapshot: a listener may unsubscribe itself while being called (a
-		// stream that has just been cancelled does exactly that).
-		for (const listener of [...set]) {
-			try {
-				listener(event);
-			} catch (error) {
-				onError(error, "notificationHub.listener");
-				set.delete(listener);
-			}
-		}
-		if (set.size === 0) listeners.delete(userId);
-	};
-
-	const subscribe: NotificationHub["subscribe"] = (userId, listener) => {
-		if (closed) return () => {};
-		let set = listeners.get(userId);
-		if (!set) {
-			set = new Set();
-			listeners.set(userId, set);
-		}
-		// Oldest-first eviction: the tab that has been open longest is the one
-		// least likely to be looked at, and dropping it costs nothing (the poll
-		// backstop still runs there).
-		while (set.size >= maxStreamsPerUser) {
-			const oldest = set.values().next().value;
-			if (!oldest) break;
-			set.delete(oldest);
-			try {
-				oldest({ kind: "unread", userId, count: -1 });
-			} catch (error) {
-				onError(error, "notificationHub.evict");
-			}
-		}
-		set.add(listener);
-		return () => {
-			const current = listeners.get(userId);
-			if (!current) return;
-			current.delete(listener);
-			if (current.size === 0) listeners.delete(userId);
-		};
-	};
-
-	return {
-		sink: {
-			onNotification(notification) {
-				emit(notification.userId, { kind: "notification", notification });
-			},
-			onUnread(userId, count) {
-				emit(userId, { kind: "unread", userId, count });
-			},
-		},
-
-		subscribe,
-
-		stream(userId, streamOptions = {}) {
-			let unsubscribe: (() => void) | undefined;
-			let heartbeat: ReturnType<typeof setInterval> | undefined;
-			let onAbort: (() => void) | undefined;
-			const encoder = new TextEncoder();
-
-			const body = new ReadableStream<Uint8Array>({
-				start(controller) {
-					let live = true;
-					const send = (chunk: string) => {
-						if (!live) return;
-						try {
-							controller.enqueue(encoder.encode(chunk));
-						} catch (error) {
-							// The peer went away between our check and the write. Tear the
-							// subscription down rather than logging once per event forever.
-							live = false;
-							onError(error, "notificationHub.enqueue");
-							teardown();
-						}
-					};
-					const teardown = () => {
-						live = false;
-						unsubscribe?.();
-						unsubscribe = undefined;
-						if (heartbeat) clearInterval(heartbeat);
-						heartbeat = undefined;
-						if (onAbort) streamOptions.signal?.removeEventListener("abort", onAbort);
-						onAbort = undefined;
-					};
-
-					// A comment line first: it flushes proxy buffers and tells the
-					// client the stream is genuinely open before anything happens.
-					send(": connected\n\n");
-					unsubscribe = subscribe(userId, (event) => {
-						// The eviction poke (count -1) is not a real event — it means
-						// "this stream lost its slot", so close rather than report it.
-						if (event.kind === "unread" && event.count < 0) {
-							teardown();
-							try {
-								controller.close();
-							} catch {
-								/* already closed */
-							}
-							return;
-						}
-						send(encodeEvent(event));
-					});
-					if (heartbeatMs > 0) {
-						heartbeat = setInterval(() => send(": ping\n\n"), heartbeatMs);
-						// Never hold the process open for a heartbeat — a satellite that
-						// is shutting down must not wait out someone's open tab.
-						(heartbeat as unknown as { unref?: () => void }).unref?.();
-					}
-					if (streamOptions.signal) {
-						onAbort = () => {
-							teardown();
-							try {
-								controller.close();
-							} catch {
-								/* already closed */
-							}
-						};
-						streamOptions.signal.addEventListener("abort", onAbort, { once: true });
-					}
-				},
-				cancel() {
-					unsubscribe?.();
-					unsubscribe = undefined;
-					if (heartbeat) clearInterval(heartbeat);
-					heartbeat = undefined;
-				},
-			});
-
-			return new Response(body, { status: 200, headers: SSE_HEADERS });
-		},
-
-		subscriberCount(userId) {
-			if (userId !== undefined) return listeners.get(userId)?.size ?? 0;
-			let total = 0;
-			for (const set of listeners.values()) total += set.size;
-			return total;
-		},
-
-		close() {
-			closed = true;
-			for (const [userId, set] of [...listeners]) {
-				for (const listener of [...set]) {
-					try {
-						listener({ kind: "unread", userId, count: -1 });
-					} catch (error) {
-						onError(error, "notificationHub.close");
-					}
-				}
-			}
-			listeners.clear();
-		},
-	};
-}

package/src/server/notifications/index.ts

@@ -1,77 +0,0 @@
-/**
- * `cursedbelt/server/notifications` — the SERVER half of the fleet's one
- * notification primitive.
- *
- * ── What was already here, and what was missing ─────────────────────────────
- * The dispatch engine has lived in `cwip/notifications` for months (a
- * persistent per-user row, `groupKey` coalescing, unread counts, deep links, a
- * live-delivery sink) and the whole client has lived in
- * `cursedbelt/react/notifications` (store, bell, feed, inbox, poll transport).
- * What did NOT exist was a way to MOUNT any of it: the only mounted surface in
- * the fleet was `orch-ui/services/notifications`, written against
- * `@satellites/satellite-rpc` inside a package only the orchestrator consumes.
- * So a satellite wanting a bell had two options, and both were wrong — adopt
- * orch's rpc layer, or write the routes again.
- *
- * This module is the third: ordinary Hono routes, an SSE hub behind the sink
- * the center already had, and a migration for apps using cursedbelt's runner.
- *
- *   const notifications = createNotificationService({ db });
- *   notifications.mount(app, { authorize: (c) => userOf(c)?.id ?? null });
- *
- * and on the client:
- *
- *   const { store } = createNotificationsBinding();   // cursedbelt/react/notifications
- *   <NotificationBell store={store} />
- *
- * ── The three properties worth knowing ──────────────────────────────────────
- * 1. **A notification is a row before it is an event.** Delivery is a cache of
- *    who is listening; the poll transport is the backstop and is not optional.
- *    Nothing is lost by a closed laptop.
- * 2. **Coalescing is a database constraint, not a debounce.** The partial
- *    unique index on `(user_id, group_key) WHERE group_key IS NOT NULL AND
- *    done = 0` is what makes "twenty of the same thing" one row with a count,
- *    even under concurrent producers.
- * 3. **The routes address the session's user and nothing else.** There is no
- *    route that notifies somebody else; producing is server-side code calling
- *    `center.notify*`.
- */
-export { createNotificationHub } from "./hub";
-export type {
-	NotificationHub,
-	NotificationHubEvent,
-	NotificationHubListener,
-	NotificationHubOptions,
-} from "./hub";
-export { NOTIFICATION_MIGRATIONS, NOTIFICATIONS_TABLE } from "./migrations";
-export { mountNotificationRoutes } from "./routes";
-export type { NotificationRouteCenter, NotificationRoutesOptions } from "./routes";
-export { createNotificationService } from "./service";
-export type {
-	CreateNotificationServiceOptions,
-	NotificationService,
-	NotificationServiceMountOptions,
-} from "./service";
-// Re-exported so a server consumer needs ONE import for the whole contract —
-// the same courtesy `server/sharing` extends over `cursedbelt/sharing`. The
-// engine remains cwip's; this is a door, not a copy.
-export {
-	createNotificationCenter,
-	createMemoryNotificationStore,
-	createSqliteNotificationStore,
-	migrateNotificationsSchema,
-} from "cwip/notifications";
-export type {
-	AppNotification,
-	ListNotificationsQuery,
-	NotificationAudience,
-	NotificationCenter,
-	NotificationCenterOptions,
-	NotificationDraft,
-	NotificationFilter,
-	NotificationPage,
-	NotificationSeverity,
-	NotificationSink,
-	NotificationStore,
-	Notifier,
-} from "cwip/notifications";

package/src/server/notifications/migrations.ts

@@ -1,39 +0,0 @@
-/**
- * The notification table, as a migration an app runs inside its OWN database.
- *
- * Same reasoning as `../sharing/migrations.ts`: the SCHEMA is shared, the DATA
- * is local. A notification is about one app's rows and is read on the same page
- * that reads them, so a central notification service would put a network hop in
- * front of a badge count — and the first thing an app would do is cache it.
- *
- * 🔴 The DDL itself is NOT written here. `cwip/notifications` already owns it
- * (`migrateNotificationsSchema`, which the sqlite store calls on construction),
- * and a second copy in this file is a schema that agrees with the store until
- * the day it doesn't. This module exists to give apps that use cursedbelt's
- * migration RUNNER an ordered, once-only entry for it — the DDL is idempotent,
- * so both routes converge on one table.
- */
-import type { Database } from "bun:sqlite";
-import { migrateNotificationsSchema, type NotificationDb } from "cwip/notifications";
-import type { Migration } from "../migration/types";
-
-export const NOTIFICATIONS_TABLE = "notifications";
-
-/**
- * Ordered migrations for the notification table.
- *
- *   applyRecommendedPragmas(db);
- *   runMigrations(db, [...APP_MIGRATIONS, ...NOTIFICATION_MIGRATIONS]);
- *
- * An app that instead constructs `createSqliteNotificationStore(db)` gets the
- * same table without this — the store migrates on construction. Running both is
- * harmless and is the normal state of an app that adopted the store first.
- */
-export const NOTIFICATION_MIGRATIONS: readonly Migration[] = [
-	{
-		name: "0001_notifications",
-		up(db: Database): void {
-			migrateNotificationsSchema(db as unknown as NotificationDb, NOTIFICATIONS_TABLE);
-		},
-	},
-];

package/src/server/notifications/routes.ts

@@ -1,177 +0,0 @@
-/**
- * The plain-HTTP surface for the notification center.
- *
- * ── Why this exists (2026-08-11) ────────────────────────────────────────────
- * The engine (`cwip/notifications`), the store and the whole client
- * (`cursedbelt/react/notifications`) were already fleet-wide. The only mounted
- * SERVER surface was `orch-ui/services/notifications`, written against
- * `@satellites/satellite-rpc` and living inside a package only the orchestrator
- * consumes — so every other satellite's route to a notification was "adopt
- * orch's rpc layer" or "write it again". This is that surface as ordinary
- * routes on an ordinary Hono app, one mount call, no rpc.
- *
- * The route table mirrors the rpc one 1:1 on purpose: the two are the same
- * contract in two dialects, and a client written against either sees the same
- * fields. `mutations` are POST/DELETE and `queries` are GET, so the GET-only
- * enforcement middleware some satellites run stays meaningful.
- *
- *   GET    {base}                → { items, hasMore }   ?filter=&limit=&offset=
- *   GET    {base}/unread-count   → { count }
- *   GET    {base}/stream         → SSE (live delivery; needs a hub)
- *   GET    {base}/:id            → { notification }
- *   POST   {base}/read-all       → { changed }
- *   POST   {base}/done-all       → { changed }
- *   POST   {base}/:id/read       → { changed }   body { read?: boolean }
- *   POST   {base}/:id/done       → { changed }   body { done?: boolean }
- *   DELETE {base}/:id            → { changed }
- *
- * 🔴 **Every handler addresses `authorize(c)`'s user and never a body field.**
- * The center is user-scoped at the store level, but a route that took a
- * `userId` parameter would make that scoping decorative — so there is no such
- * parameter anywhere below, and there is deliberately no route that notifies
- * somebody else. Producing notifications is server-side business logic calling
- * `center.notify*` directly; a browser can only ever read and acknowledge its
- * OWN inbox.
- */
-import type { Context, Hono } from "hono";
-import type { NotificationCenter, NotificationFilter } from "cwip/notifications";
-import type { NotificationHub } from "./hub";
-
-/** The slice of the center these routes use — `createNotificationCenter(...)`
- *  satisfies it, and so does any app-specific facade over one. */
-export type NotificationRouteCenter = Pick<
-	NotificationCenter,
-	"list" | "get" | "unreadCount" | "markRead" | "markAllRead" | "setDone" | "doneAll" | "remove"
->;
-
-export interface NotificationRoutesOptions {
-	center: NotificationRouteCenter;
-	/**
-	 * Resolve the caller to a user id, or null to refuse with 401. This is the
-	 * app's session model and the ONLY thing that decides whose inbox is served.
-	 */
-	authorize: (c: Context) => string | null | Promise<string | null>;
-	/** Live delivery. Omit it and `{base}/stream` is not mounted at all — a
-	 *  route that answers 200 with a stream that never emits is worse than a
-	 *  404 the client can fall back from. */
-	hub?: NotificationHub;
-	/** Path prefix. Default `/api/notifications`. */
-	basePath?: string;
-	/** Largest page a caller may ask for. Default 200. */
-	maxLimit?: number;
-}
-
-const NO_STORE = { "cache-control": "no-store" } as const;
-
-const FILTERS: readonly NotificationFilter[] = ["unread", "all", "done"];
-
-const parseFilter = (raw: string | undefined): NotificationFilter | undefined =>
-	FILTERS.find((f) => f === raw);
-
-/** Query integers are untrusted text: a NaN or a negative offset must become
- *  the default, never reach SQL, and never be an error the caller has to handle. */
-const parseInt_ = (raw: string | undefined, min: number, max: number): number | undefined => {
-	if (raw === undefined || raw === "") return undefined;
-	const value = Number.parseInt(raw, 10);
-	if (!Number.isFinite(value)) return undefined;
-	return Math.min(max, Math.max(min, value));
-};
-
-/** A body that is absent, malformed, or oversized is `{}` — every field these
- *  routes read is optional with a documented default, so there is nothing a
- *  caller could usefully be told about a bad one. */
-const readFlag = async (c: Context, key: "read" | "done"): Promise<boolean> => {
-	try {
-		const raw = await c.req.text();
-		if (!raw || raw.length > 1024) return true;
-		const body = JSON.parse(raw) as Record<string, unknown> | null;
-		const value = body?.[key];
-		return typeof value === "boolean" ? value : true;
-	} catch {
-		return true;
-	}
-};
-
-export function mountNotificationRoutes(app: Hono, options: NotificationRoutesOptions): void {
-	const base = options.basePath ?? "/api/notifications";
-	const maxLimit = options.maxLimit ?? 200;
-	const { center, hub } = options;
-
-	/** Every handler starts here. Returns the user id, or the 401 to return. */
-	const whoOr401 = async (c: Context): Promise<string | Response> => {
-		const userId = await options.authorize(c);
-		if (!userId) return c.json({ error: "unauthorized" }, 401, NO_STORE);
-		return userId;
-	};
-
-	app.get(base, async (c) => {
-		const who = await whoOr401(c);
-		if (typeof who !== "string") return who;
-		const page = await center.list({
-			userId: who,
-			filter: parseFilter(c.req.query("filter")),
-			limit: parseInt_(c.req.query("limit"), 1, maxLimit),
-			offset: parseInt_(c.req.query("offset"), 0, Number.MAX_SAFE_INTEGER),
-		});
-		return c.json(page, 200, NO_STORE);
-	});
-
-	app.get(`${base}/unread-count`, async (c) => {
-		const who = await whoOr401(c);
-		if (typeof who !== "string") return who;
-		return c.json({ count: await center.unreadCount(who) }, 200, NO_STORE);
-	});
-
-	// Mounted only when there is something to stream — see the option's doc.
-	if (hub) {
-		app.get(`${base}/stream`, async (c) => {
-			const who = await whoOr401(c);
-			if (typeof who !== "string") return who;
-			// The request's own abort signal is what ends the stream when the tab
-			// closes; without it the subscription outlives the socket.
-			return hub.stream(who, { signal: c.req.raw.signal });
-		});
-	}
-
-	app.post(`${base}/read-all`, async (c) => {
-		const who = await whoOr401(c);
-		if (typeof who !== "string") return who;
-		return c.json({ changed: await center.markAllRead(who) }, 200, NO_STORE);
-	});
-
-	app.post(`${base}/done-all`, async (c) => {
-		const who = await whoOr401(c);
-		if (typeof who !== "string") return who;
-		return c.json({ changed: await center.doneAll(who) }, 200, NO_STORE);
-	});
-
-	app.post(`${base}/:id/read`, async (c) => {
-		const who = await whoOr401(c);
-		if (typeof who !== "string") return who;
-		const read = await readFlag(c, "read");
-		return c.json({ changed: await center.markRead(who, c.req.param("id"), read) }, 200, NO_STORE);
-	});
-
-	app.post(`${base}/:id/done`, async (c) => {
-		const who = await whoOr401(c);
-		if (typeof who !== "string") return who;
-		const done = await readFlag(c, "done");
-		return c.json({ changed: await center.setDone(who, c.req.param("id"), done) }, 200, NO_STORE);
-	});
-
-	app.delete(`${base}/:id`, async (c) => {
-		const who = await whoOr401(c);
-		if (typeof who !== "string") return who;
-		return c.json({ changed: await center.remove(who, c.req.param("id")) }, 200, NO_STORE);
-	});
-
-	// LAST: `/:id` would otherwise swallow `/unread-count` and `/stream`, and
-	// the failure is a 404-shaped `{ notification: null }` rather than an error.
-	app.get(`${base}/:id`, async (c) => {
-		const who = await whoOr401(c);
-		if (typeof who !== "string") return who;
-		const notification = await center.get(who, c.req.param("id"));
-		if (!notification) return c.json({ error: "not found" }, 404, NO_STORE);
-		return c.json({ notification }, 200, NO_STORE);
-	});
-}