@protobase/server 0.8.1 → 0.9.0

package/dist/webhooks/webhooks.js

@@ -0,0 +1,233 @@
+import { dispatchJobName } from "../changes/capture-sql.js";
+import { coalesce } from "../changes/coalesce.js";
+import { eventMatcher } from "../changes/match-events.js";
+import { deleteOutbox, readOutbox } from "../changes/outbox.js";
+import { resourceChange } from "../changes/resource-change.js";
+import { callerRecords } from "../functions/records.js";
+import { defineJob } from "../jobs/define-job.js";
+import { FatalJobError } from "../jobs/run-job.js";
+import { maxTries, nextRetryDelay } from "./retry-schedule.js";
+import { subscriberEvents } from "./subscriber-view.js";
+import { attemptDelivery } from "./attempt.js";
+import { subscriptionProblems, subscriptionRouter } from "./route-events.js";
+import { tableSubscriptionName } from "./table/options.js";
+import { sendTestJob } from "./table/schema-sql.js";
+import { testEvent } from "./test-event.js";
+//#region src/webhooks/webhooks.ts
+/** Outbox rows one dispatch reads at a time. */
+const batchSize = 500;
+/** Receivers tried at once by one dispatch. */
+const parallelAttempts = 16;
+const mapLimit = async (items, limit, run) => {
+	const results = new Array(items.length);
+	let next = 0;
+	const lane = async () => {
+		while (next < items.length) {
+			const index = next++;
+			results[index] = await run(items[index]);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, lane));
+	return results;
+};
+/** The key of an unordered delivery: one waiting retry per event and subscription. */
+const deliveryKey = (payload) => `${payload.event.id}:${payload.subscription}`;
+/** The group of an ordered delivery: one at a time per subscription and record. */
+const deliveryGroup = ({ subscription, change }) => `${subscription.name}:${change.resource}:${change.key}`;
+/**
+* Resource events delivered to the config's subscriptions, as three jobs the app's workers run:
+*
+* - `changes.dispatch`, which `capture()` enqueues once per writing transaction, in one ordered group so one runs at a
+*   time: it turns the committed outbox rows into events, makes the first try of every unordered delivery itself,
+*   queues the failures and the ordered deliveries, and deletes the rows in that same transaction. A process that dies
+*   before that commits leaves the rows, and the job's retry delivers them again, under the same `webhook-id`.
+* - `webhooks.deliver`, one try of an unordered delivery; a failure queues the next try on the Standard Webhooks
+*   schedule, or Retry-After, and the last one is kept as failed.
+* - `webhooks.deliver-ordered`, the ordered deliveries of one dispatch for one subscription and record, retried with
+*   doubling waits up to a day, holding back the record's later deliveries to that subscription meanwhile.
+*
+* With `table`, also `webhooks.send-test`, which Send test event queues, and with its log `webhooks.prune-log`, daily.
+*
+* No jobs without a resource with events; the subscriptions must name declared events.
+*/
+const createWebhooks = ({ deps, subscriptions, functions, schema, log, table }) => {
+	const entries = deps.registry.entries;
+	const models = entries.map((entry) => entry.model);
+	const problems = subscriptionProblems(subscriptions, models, Object.keys(functions));
+	if (problems.length > 0) throw new Error(problems.join("; "));
+	if (!models.some((model) => model.events)) return { jobs: [] };
+	const matchers = new Map(entries.map((entry) => [entry.name, eventMatcher(entry.model, entry.source.eventMatches?.() ?? {})]));
+	const keyColumns = (resource) => {
+		const model = deps.registry.find(resource)?.model;
+		return model ? model.primaryKey.map((name) => model.fields[name].column) : [];
+	};
+	const byName = new Map(subscriptions.map((subscription) => [subscription.name, subscription]));
+	const records = (session) => callerRecords(deps, session);
+	const tableId = (subscription) => subscription.name.startsWith("ui:") ? subscription.name.slice(3) : void 0;
+	const attempt = async (subscription, event, db, tried, signal) => {
+		const id = tableId(subscription);
+		const started = performance.now();
+		const checkUrl = id === void 0 ? void 0 : table?.checkUrl;
+		const result = await attemptDelivery(subscription, event, {
+			db,
+			functions,
+			records,
+			attempt: tried,
+			signal,
+			...checkUrl && { checkUrl }
+		});
+		if (id !== void 0) await table.subscriptions.record(db, id, event, tried, result, performance.now() - started);
+		return result;
+	};
+	const current = async (db) => {
+		if (!table) return subscriptions;
+		const rows = (await table.subscriptions.load(db)).filter((row) => subscriptionProblems([row], models, []).length === 0);
+		return [...subscriptions, ...rows];
+	};
+	const report = (subscription, event, tried, result) => {
+		const what = `webhook ${subscription} ${event.type} ${event.id}`;
+		if (result.ok) log(`${what} delivered${result.status ? ` (${result.status})` : ""}${tried > 1 ? ` on try ${tried}` : ""}`);
+		else log(`${what} failed on try ${tried}: ${result.error}`);
+	};
+	const subscriptionOf = async (name, db) => {
+		const id = name.startsWith("ui:") ? name.slice(3) : void 0;
+		const found = id === void 0 ? byName.get(name) : await table?.subscriptions.find(db, id);
+		if (!found) throw new FatalJobError(`The subscription "${name}" no longer exists`);
+		if (found.options.enabled === false) throw new FatalJobError(`The subscription "${name}" is disabled`);
+		return found;
+	};
+	const deliver = defineJob({
+		name: "webhooks.deliver",
+		maxAttempts: 3,
+		retryDelay: "30 seconds",
+		timeout: "1 minute",
+		concurrency: parallelAttempts,
+		run: async (payload, { db, signal }) => {
+			const subscription = await subscriptionOf(payload.subscription, db);
+			const result = await attempt(subscription, payload.event, db, payload.attempt, signal);
+			report(payload.subscription, payload.event, payload.attempt, result);
+			if (result.ok) return;
+			const delay = result.final ? void 0 : nextRetryDelay(payload.attempt, result.retryAfterMs);
+			if (delay === void 0) throw new FatalJobError(result.error);
+			await deliver.enqueue(db, {
+				...payload,
+				attempt: payload.attempt + 1,
+				lastError: result.error
+			}, {
+				key: deliveryKey(payload),
+				delay
+			});
+		}
+	});
+	const deliverOrdered = defineJob({
+		name: "webhooks.deliver-ordered",
+		ordered: true,
+		maxAttempts: maxTries,
+		retryDelay: "5 seconds",
+		maxRetryDelay: "24 hours",
+		timeout: "5 minutes",
+		concurrency: parallelAttempts,
+		run: async (payload, { db, signal, job }) => {
+			const subscription = await subscriptionOf(payload.subscription, db);
+			for (const event of payload.events) {
+				const result = await attempt(subscription, event, db, job.attempt, signal);
+				report(payload.subscription, event, job.attempt, result);
+				if (result.ok) continue;
+				if (result.final) throw new FatalJobError(result.error);
+				throw new Error(result.error);
+			}
+		}
+	});
+	const deliveriesOf = async (changes, db) => {
+		const route = subscriptionRouter(await current(db), models);
+		const eventOf = subscriberEvents(deps);
+		const deliveries = [];
+		for (const change of changes) for (const { subscription, event } of route(change, matchers.get(change.resource)(change))) {
+			const shaped = await eventOf(subscription, change, event);
+			if (shaped) deliveries.push({
+				subscription,
+				event: shaped,
+				change
+			});
+		}
+		return deliveries;
+	};
+	const dispatchBatch = async (db, signal) => {
+		const rows = await readOutbox(db, schema, models, batchSize);
+		if (rows.length === 0) return 0;
+		const changes = coalesce(rows, keyColumns).flatMap((change) => {
+			const entry = deps.registry.find(change.resource);
+			return entry ? [resourceChange(entry.model, change)] : [];
+		});
+		const deliveries = await deliveriesOf(changes, db);
+		const now = deliveries.filter(({ subscription }) => !subscription.options.ordered);
+		const results = await mapLimit(now, parallelAttempts, ({ subscription, event }) => attempt(subscription, event, db, 1, signal));
+		await db.transaction().execute(async (trx) => {
+			for (const [index, delivery] of now.entries()) {
+				const result = results[index];
+				if (result.ok) continue;
+				const delay = result.final ? void 0 : nextRetryDelay(1, result.retryAfterMs);
+				if (delay === void 0) continue;
+				const payload = {
+					subscription: delivery.subscription.name,
+					event: delivery.event,
+					attempt: 2,
+					lastError: result.error
+				};
+				await deliver.enqueue(trx, payload, {
+					key: deliveryKey(payload),
+					delay
+				});
+			}
+			const groups = /* @__PURE__ */ new Map();
+			for (const delivery of deliveries.filter(({ subscription }) => subscription.options.ordered)) {
+				const group = deliveryGroup(delivery);
+				const payload = groups.get(group) ?? {
+					subscription: delivery.subscription.name,
+					events: []
+				};
+				payload.events.push(delivery.event);
+				groups.set(group, payload);
+			}
+			for (const [group, payload] of groups) await deliverOrdered.enqueue(trx, payload, { group });
+			await deleteOutbox(trx, schema, rows.map((row) => row.id));
+		});
+		for (const [index, { subscription, event }] of now.entries()) report(subscription.name, event, 1, results[index]);
+		return rows.length;
+	};
+	const dispatch = defineJob({
+		name: dispatchJobName,
+		ordered: true,
+		maxAttempts: 1e6,
+		retryDelay: "1 second",
+		maxRetryDelay: "1 minute",
+		timeout: "5 minutes",
+		run: async (_payload, { db, signal }) => {
+			while (await dispatchBatch(db, signal) === batchSize && !signal.aborted);
+		}
+	});
+	const sendTest = defineJob({
+		name: sendTestJob,
+		maxAttempts: 1,
+		timeout: "1 minute",
+		run: async (payload, { db, signal }) => {
+			const subscription = await subscriptionOf(tableSubscriptionName(payload.subscription), db);
+			const event = await testEvent(deps, records, subscription);
+			report(subscription.name, event, 1, await attempt(subscription, event, db, 1, signal));
+		}
+	});
+	const pruneLog = defineJob({
+		name: "webhooks.prune-log",
+		schedule: "17 3 * * *",
+		run: async (_payload, { db }) => table.subscriptions.prune(db)
+	});
+	return { jobs: [
+		dispatch,
+		deliver,
+		deliverOrdered,
+		...table ? [sendTest] : [],
+		...table?.subscriptions.deliveryLog ? [pruneLog] : []
+	] };
+};
+//#endregion
+export { createWebhooks };

package/dist/write-pipeline.js

@@ -4,7 +4,7 @@ import { tenantScope } from "./tenant.js";
 import { requestAccess, requireOperation, targetFilter, writableFields } from "./request-access.js";
 import { writeTransaction } from "./transactions.js";
 import { attachFiles } from "./files/attach.js";
-import { actorSettings } from "./changes/actor.js";
+import { actorSettings, wakeDispatch } from "./changes/actor.js";
 import { validateBody } from "./validate-body.js";
 import { assertWritten, checkPrecondition, decide, denied, firstKeyField, missing, notifier, shown } from "./write-shared.js";
 import { applyUpdate, planUpdate } from "./write-update.js";
@@ -90,7 +90,9 @@ const writeIn = async (trx, deps, access, request) => {
 const runWrite = async (deps, entry, session, request) => {
 	const access = await requestAccess(deps, entry, session);
 	requireOperation(access, request.operation === "undelete" ? "update" : request.operation);
-	return writeTransaction(deps.db, deps.statementTimeoutMs, (trx) => writeIn(trx, deps, access, request), actorSettings(deps, session));
+	const result = await writeTransaction(deps.db, deps.statementTimeoutMs, (trx) => writeIn(trx, deps, access, request), actorSettings(deps, session));
+	wakeDispatch(deps);
+	return result;
 };
 //#endregion
 export { runWrite, writeIn };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -30,18 +30,20 @@
   },
   "dependencies": {
     "@better-auth/passkey": "^1.7.7",
-    "@protobase/layout": "0.8.1",
-    "@protobase/query": "0.8.1",
-    "@protobase/schema": "0.8.1",
+    "@protobase/layout": "0.9.0",
+    "@protobase/query": "0.9.0",
+    "@protobase/schema": "0.9.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@simplewebauthn/server": "^13.3.1",
     "better-auth": "^1.7.7",
+    "cron-parser": "^5.10.1",
     "file-type": "^22.1.1",
     "hono": "^4.13.13",
     "image-size": "^2.0.4",
     "jose": "^6.2.12",
     "kysely": "^0.29.6",
     "nodemailer": "^10.0.16",
+    "pg-boss": "12.37.1",
     "zod": "^4.6.5"
   }
 }