@makerkit/workers-outbox 0.0.0-stage → 0.0.2

package/dist/catalog-DzvOuOHQ.d.mts

@@ -0,0 +1,6 @@
+import { SQL } from "drizzle-orm";
+/** Drivers disagree on the result shape, so read through `queryRows`. */
+interface SqlRunner {
+  execute(query: SQL): PromiseLike<unknown>;
+}
+export { SqlRunner as t };

package/dist/catalog-G6w4wb_w.mjs

@@ -0,0 +1,46 @@
+import { sql } from "drizzle-orm";
+// src/drizzle/catalog.ts
+async function queryRows(db, query) {
+	const result = await db.execute(query);
+	if (Array.isArray(result)) return result;
+	return result.rows;
+}
+async function readOutboxCatalog(db) {
+	const columns = await queryRows(db, sql`SELECT c.relname AS "table", a.attname AS "column",
+               format_type(a.atttypid, a.atttypmod) AS "type",
+               a.attnotnull AS "not_null",
+               pg_get_expr(d.adbin, d.adrelid) AS "default"
+        FROM pg_attribute a
+        JOIN pg_class c ON c.oid = a.attrelid
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+        WHERE n.nspname = 'outbox' AND c.relkind = 'r' AND a.attnum > 0 AND NOT a.attisdropped
+        ORDER BY 1, 2`);
+	const constraints = await queryRows(db, sql`SELECT c.relname AS "table", con.conname AS "name", con.contype AS "type",
+               pg_get_constraintdef(con.oid) AS "definition"
+        FROM pg_constraint con
+        JOIN pg_class c ON c.oid = con.conrelid
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = 'outbox' AND con.contype IN ('p', 'u', 'f', 'c')
+        ORDER BY 1, 2`);
+	const indexes = await queryRows(db, sql`SELECT tc.relname AS "table", ic.relname AS "name",
+               pg_get_indexdef(ic.oid) AS "definition", i.indisvalid AS "valid"
+        FROM pg_index i
+        JOIN pg_class ic ON ic.oid = i.indexrelid
+        JOIN pg_class tc ON tc.oid = i.indrelid
+        JOIN pg_namespace n ON n.oid = tc.relnamespace
+        WHERE n.nspname = 'outbox'
+        ORDER BY 1, 2`);
+	return {
+		columns: columns.map((row) => ({
+			table: row.table,
+			column: row.column,
+			type: row.type,
+			notNull: row.not_null,
+			default: row.default
+		})),
+		constraints,
+		indexes
+	};
+}
+export { readOutboxCatalog as n, queryRows as t };

package/dist/cloudflare.d.mts

@@ -0,0 +1,117 @@
+import { H as AnyJob, _ as Budget, c as RUNTIME, h as EventSink, i as EnqueueRequest, o as Outbox, u as ScopedEnqueue } from "./create-outbox-C4vdn6Dr.mjs";
+import { r as OutboxDb } from "./types-ClomUJ_8.mjs";
+interface QueueMessage {
+  readonly body: unknown;
+  readonly attempts: number;
+  ack(): void;
+  retry(options?: {
+    delaySeconds?: number;
+  }): void;
+}
+interface QueueBatch {
+  readonly queue: string;
+  readonly messages: readonly QueueMessage[];
+}
+interface QueueHandlerOptions {
+  /**
+   * Wall time shared by every message in one batch. Default 840 s (14 min); at most 870 s,
+   * leaving headroom under Cloudflare's 15-minute consumer limit.
+   */
+  invocationBudgetMs?: number;
+  /** Default: 100 jobs within the invocation budget. Its deadline must hold the longest legal lease (635 s). */
+  nudgeBudget?: Budget;
+  /** Default: 50 jobs within 45 s. */
+  drainBudget?: Budget;
+  /** Default `'default'`; only this lane's kinds are claimed. */
+  lane?: string;
+}
+export declare const messageRetryDelaySeconds: (attempts: number) => number;
+/** A handler failure is a job outcome; only an infrastructure fault retries the message. */
+export declare function createQueueHandler<Env, Ctx = unknown>(outboxFor: (env: Env, ctx: Ctx) => Outbox, options?: QueueHandlerOptions): (batch: QueueBatch, env: Env, ctx: Ctx) => Promise<void>;
+/** One firing of a schedule's cron. */
+interface ScheduleOccurrence {
+  /**
+   * The time this tick was scheduled for (`event.scheduledTime`), not when it ran: a repeated
+   * delivery of the same tick has the same value, so keys derived from it dedupe.
+   */
+  readonly scheduledAt: Date;
+  readonly cron: string;
+}
+/** Enqueues one job per occurrence. */
+interface JobSchedule<T extends AnyJob = AnyJob> {
+  /** Must match one of the Worker's `triggers.crons` exactly, as Cloudflare passes it back. */
+  readonly cron: string;
+  /** Names the schedule in events and in the default dedupe key. Default: the job's kind. */
+  readonly name?: string;
+  readonly job: T;
+  readonly payload: (occurrence: ScheduleOccurrence) => EnqueueRequest<T>['payload'];
+  /** Default `schedule:<name>:<scheduledAt as ISO>`, so a repeated tick finds its job. */
+  readonly dedupeKey?: (occurrence: ScheduleOccurrence) => string;
+  readonly tenantKey?: string | null;
+}
+/** Enqueues any number of jobs per occurrence, in one transaction (e.g. one per tenant). */
+interface RunSchedule {
+  readonly cron: string;
+  readonly name: string;
+  /**
+   * Runs in a transaction on the outbox's connection, so reading app tables needs grants for the
+   * outbox role. Derive every dedupe key from `scheduledAt`, so a repeated tick enqueues nothing new.
+   */
+  readonly run: (occurrence: ScheduleOccurrence & {
+    readonly tx: OutboxDb;
+    readonly enqueue: ScopedEnqueue<readonly AnyJob[]>;
+  }) => Promise<void>;
+}
+type Schedule = JobSchedule<any> | RunSchedule;
+/** Type-checks a schedule's payload against its job. A plain object works too, untyped. */
+export declare function defineSchedule<T extends AnyJob>(schedule: JobSchedule<T>): JobSchedule<T>;
+export declare function defineSchedule(schedule: RunSchedule): RunSchedule;
+interface ScheduledHandlerOptions {
+  /**
+   * Wall time shared by every phase of one tick. Default 840 s; at most 870 s, under
+   * Cloudflare's 15-minute limit for a scheduled invocation.
+   */
+  invocationBudgetMs?: number;
+  /** Default: 50 jobs within 180 s. */
+  budget?: Budget;
+  /** Default 50. */
+  recoveryLimit?: number;
+  /**
+   * Recovery's share of the tick, so a crash backlog can't starve fresh work. Default 120 s.
+   * What doesn't fit stays expired for the next tick. Counted from when recovery starts, and held
+   * back from `schedules` (up to half the invocation), so schedules can't consume it.
+   */
+  recoveryBudgetMs?: number;
+  /** Drained before the catch-all so other kinds can't starve these; keep each ≤ 45 s. */
+  reserved?: readonly {
+    name: string;
+    kinds: readonly string[];
+    budget: Budget;
+  }[];
+  backlog?: Parameters<Outbox[typeof RUNTIME]['monitorBacklog']>[0];
+  retention?: {
+    succeededRetentionMs?: number;
+    terminalRetentionMs?: number;
+    batch?: number;
+    maxBatches?: number;
+  };
+  /**
+   * Recurring jobs. On a tick whose cron matches a schedule's, its jobs are enqueued (keyed by the
+   * tick's scheduled time, so a repeated tick enqueues nothing new) before the sweep runs. A tick
+   * that never fires is skipped, not caught up.
+   */
+  schedules?: readonly Schedule[];
+}
+export declare const DEFAULT_SWEEP_BUDGET: Budget;
+interface ScheduledEventLike {
+  readonly cron?: string;
+  /** Milliseconds since the epoch; Cloudflare sets it. Default: when the tick runs. */
+  readonly scheduledTime?: number;
+}
+/** The durable backstop: each phase is isolated, and the handler always resolves. */
+export declare function createScheduledHandler<Env, Ctx = unknown>(outboxFor: (env: Env, ctx: Ctx) => Outbox, options?: ScheduledHandlerOptions): (event: ScheduledEventLike, env: Env, ctx: Ctx) => Promise<void>;
+/** A dead-lettered nudge loses nothing (cron still drives the job): report and ack. */
+export declare function createDlqHandler(options?: {
+  events?: EventSink;
+}): (batch: QueueBatch) => Promise<void>;
+export type { JobSchedule, QueueBatch, QueueHandlerOptions, QueueMessage, RunSchedule, Schedule, ScheduleOccurrence, ScheduledEventLike, ScheduledHandlerOptions };

package/dist/cloudflare.mjs

@@ -0,0 +1,300 @@
+import { a as emptyReport, c as createEmitter, l as MAX_LEASE_MS, n as RUNTIME, o as serializeError, s as isTransientDbError } from "./create-outbox-BTMmdvLs.mjs";
+import "./backlog-Bd62tjCT.mjs";
+// src/cloudflare/limits.ts
+/** The most an invocation budget may claim of the platform window. */
+const MAX_INVOCATION_BUDGET_MS = 87e4;
+// src/cloudflare/message-codec.ts
+const MAX_BODY_PREVIEW = 500;
+function decodeMessage(body) {
+	if (typeof body !== "object" || body === null) return reject("malformed", body);
+	const candidate = body;
+	if (candidate["v"] !== 1) return reject("unknown_version", body);
+	if (candidate["type"] === "nudge") {
+		const ids = candidate["ids"];
+		if (Array.isArray(ids) && ids.length > 0 && ids.every((id) => typeof id === "string")) return {
+			ok: true,
+			message: {
+				v: 1,
+				type: "nudge",
+				ids
+			}
+		};
+		return reject("malformed", body);
+	}
+	if (candidate["type"] === "drain" && typeof candidate["lane"] === "string") return {
+		ok: true,
+		message: {
+			v: 1,
+			type: "drain",
+			lane: candidate["lane"]
+		}
+	};
+	return reject("malformed", body);
+}
+function reject(reason, body) {
+	return {
+		ok: false,
+		reason,
+		body: previewBody(body)
+	};
+}
+/** A message body as bounded text for an event: its JSON form, or its string form if it has none. */
+function previewBody(body) {
+	let text;
+	try {
+		text = JSON.stringify(body) ?? String(body);
+	} catch {
+		text = String(body);
+	}
+	return text.slice(0, MAX_BODY_PREVIEW);
+}
+// src/cloudflare/queue-handler.ts
+const DEFAULT_DRAIN_BUDGET = {
+	maxJobs: 50,
+	deadlineMs: 45e3
+};
+const messageRetryDelaySeconds = (attempts) => Math.min(300, 5 * 2 ** Math.max(0, attempts - 1));
+/** A handler failure is a job outcome; only an infrastructure fault retries the message. */
+function createQueueHandler(outboxFor, options = {}) {
+	const invocationBudgetMs = options.invocationBudgetMs ?? 84e4;
+	if (!Number.isInteger(invocationBudgetMs) || invocationBudgetMs < 635e3 || invocationBudgetMs > 87e4) throw new Error(`createQueueHandler: invocationBudgetMs must be an integer in [${MAX_LEASE_MS}, ${MAX_INVOCATION_BUDGET_MS}], got ${invocationBudgetMs}`);
+	const nudgeBudget = options.nudgeBudget ?? {
+		maxJobs: 100,
+		deadlineMs: invocationBudgetMs
+	};
+	const drainBudget = options.drainBudget ?? DEFAULT_DRAIN_BUDGET;
+	const lane = options.lane ?? "default";
+	if (nudgeBudget.deadlineMs < 635e3 || nudgeBudget.deadlineMs > invocationBudgetMs) throw new Error(`createQueueHandler: nudgeBudget.deadlineMs must be in [${MAX_LEASE_MS}, ${invocationBudgetMs}] (the longest legal lease, the invocation budget), got ${nudgeBudget.deadlineMs}`);
+	if (drainBudget.deadlineMs > invocationBudgetMs) throw new Error(`createQueueHandler: drainBudget.deadlineMs must not exceed invocationBudgetMs (${invocationBudgetMs}), got ${drainBudget.deadlineMs}`);
+	return async (batch, env, ctx) => {
+		const runtime = outboxFor(env, ctx)[RUNTIME];
+		const started = runtime.nowMs();
+		const deadlineAt = started + invocationBudgetMs;
+		const within = (budget) => ({
+			...budget,
+			deadlineMs: Math.max(0, Math.min(budget.deadlineMs, invocationBudgetMs - (runtime.nowMs() - started)))
+		});
+		for (const message of batch.messages) {
+			const decoded = decodeMessage(message.body);
+			if (!decoded.ok) {
+				runtime.emit({
+					type: "message_rejected",
+					reason: decoded.reason,
+					body: decoded.body
+				});
+				message.ack();
+				continue;
+			}
+			const { message: body } = decoded;
+			runtime.emit({
+				type: "message_received",
+				messageType: body.type,
+				ids: body.type === "nudge" ? body.ids : [],
+				attempts: message.attempts
+			});
+			try {
+				if (body.type === "nudge") await runtime.processNudge(body.ids, within(nudgeBudget), { lane }, { deadlineAt });
+				else {
+					const budget = within(drainBudget);
+					const report = await runtime.drain(budget, "drain", { lane }, { deadlineAt });
+					const progressed = report.claimed > report.errored;
+					const starved = budget.deadlineMs < drainBudget.deadlineMs && report.reachedDeadline;
+					if ((progressed || starved) && await runtime.hasBacklog({ lane }, { deadlineAt })) await runtime.continueDrain(lane, { deadlineAt });
+				}
+				message.ack();
+			} catch (error) {
+				const delaySeconds = messageRetryDelaySeconds(message.attempts);
+				runtime.emit({
+					type: "message_retried",
+					messageType: body.type,
+					delaySeconds,
+					attempts: message.attempts,
+					error: serializeError(error)
+				});
+				message.retry({ delaySeconds });
+			}
+		}
+	};
+}
+// src/cloudflare/schedules.ts
+function defineSchedule(schedule) {
+	return schedule;
+}
+const nameOf = (schedule) => "run" in schedule ? schedule.name : schedule.name ?? schedule.job.kind;
+/** Rejects what can't work, at handler creation rather than on the first tick. */
+function validateSchedules(schedules) {
+	const names = /* @__PURE__ */ new Set();
+	for (const schedule of schedules) {
+		const name = nameOf(schedule);
+		if (typeof schedule.cron !== "string" || schedule.cron.trim() === "") throw new Error(`createScheduledHandler: schedule ${JSON.stringify(name)} needs a cron`);
+		if ("run" in schedule === "job" in schedule) throw new Error(`createScheduledHandler: schedule ${JSON.stringify(name)} needs either job + payload, or run`);
+		if (!name) throw new Error("createScheduledHandler: a run schedule needs a name");
+		if (names.has(name)) throw new Error(`createScheduledHandler: two schedules are named ${JSON.stringify(name)}`);
+		names.add(name);
+	}
+}
+/** Waits between attempts; a transient failure retries within the tick, as dedupe makes it safe. */
+const RETRY_DELAYS_MS = [1e3, 4e3];
+/** Runs every schedule whose cron is this tick's, each in its own transaction. Never throws. */
+async function runSchedules(outbox, schedules, cron, scheduledAtMs, deadlineAt) {
+	const runtime = outbox[RUNTIME];
+	const scheduledAt = new Date(scheduledAtMs);
+	const due = schedules.filter((schedule) => schedule.cron === cron);
+	for (const schedule of due) {
+		const name = nameOf(schedule);
+		const occurrence = {
+			scheduledAt,
+			cron: schedule.cron
+		};
+		const tally = {
+			created: 0,
+			existing: 0,
+			rejected: 0
+		};
+		for (let attempt = 1;; attempt++) {
+			tally.created = tally.existing = tally.rejected = 0;
+			try {
+				const { pending } = await runtime.withConnection((connection) => runtime.collectTransaction(connection.db, async (tx, enqueue) => {
+					const counted = async (job, request) => {
+						const result = await enqueue(job, request);
+						count(tally, result);
+						return result;
+					};
+					if ("run" in schedule) {
+						await schedule.run({
+							...occurrence,
+							tx,
+							enqueue: counted
+						});
+						return;
+					}
+					const result = await counted(schedule.job, {
+						payload: schedule.payload(occurrence),
+						dedupeKey: schedule.dedupeKey?.(occurrence) ?? `schedule:${name}:${scheduledAt.toISOString()}`,
+						...schedule.tenantKey === void 0 ? {} : { tenantKey: schedule.tenantKey }
+					});
+					if (result.status !== "created" && result.status !== "exists") throw new Error(`schedule ${name}: enqueue returned ${result.status}`);
+				}), deadlineAt);
+				runtime.emit({
+					type: "schedule_ran",
+					name,
+					cron: schedule.cron,
+					scheduledAt: scheduledAt.toISOString(),
+					...tally,
+					attempts: attempt
+				});
+				await runtime.nudgePending(pending, deadlineAt);
+				break;
+			} catch (error) {
+				const delay = RETRY_DELAYS_MS[attempt - 1];
+				if (isTransientDbError(error) && delay !== void 0 && runtime.nowMs() + delay < deadlineAt) {
+					await runtime.sleep(delay);
+					continue;
+				}
+				runtime.emit({
+					type: "schedule_failed",
+					severity: "error",
+					name,
+					cron: schedule.cron,
+					scheduledAt: scheduledAt.toISOString(),
+					attempts: attempt,
+					error: serializeError(error)
+				});
+				break;
+			}
+		}
+	}
+}
+function count(tally, result) {
+	if (result.status === "created") tally.created++;
+	else if (result.status === "exists") tally.existing++;
+	else tally.rejected++;
+}
+// src/cloudflare/scheduled-handler.ts
+const DEFAULT_SWEEP_BUDGET = {
+	maxJobs: 50,
+	deadlineMs: 18e4
+};
+/** The durable backstop: each phase is isolated, and the handler always resolves. */
+function createScheduledHandler(outboxFor, options = {}) {
+	const budget = options.budget ?? DEFAULT_SWEEP_BUDGET;
+	const recoveryLimit = options.recoveryLimit ?? 50;
+	const recoveryBudgetMs = options.recoveryBudgetMs ?? 12e4;
+	const invocationBudgetMs = options.invocationBudgetMs ?? 84e4;
+	const schedules = options.schedules ?? [];
+	validateSchedules(schedules);
+	if (!Number.isInteger(invocationBudgetMs) || invocationBudgetMs < 1 || invocationBudgetMs > 87e4) throw new Error(`createScheduledHandler: invocationBudgetMs must be an integer in [1, ${MAX_INVOCATION_BUDGET_MS}], got ${invocationBudgetMs}`);
+	if (!Number.isInteger(recoveryBudgetMs) || recoveryBudgetMs < 1) throw new Error(`createScheduledHandler: recoveryBudgetMs must be a positive integer, got ${recoveryBudgetMs}`);
+	const recoveryReserveMs = Math.min(recoveryBudgetMs, Math.floor(invocationBudgetMs / 2));
+	const retention = {
+		succeededRetentionMs: options.retention?.succeededRetentionMs ?? 6048e5,
+		terminalRetentionMs: options.retention?.terminalRetentionMs ?? 7776e6,
+		batch: options.retention?.batch ?? 1e3,
+		maxBatches: options.retention?.maxBatches ?? 10
+	};
+	return async (event, env, ctx) => {
+		const outbox = outboxFor(env, ctx);
+		const runtime = outbox[RUNTIME];
+		const cron = event.cron ?? null;
+		const phase = async (name, work) => {
+			try {
+				return await work();
+			} catch (error) {
+				runtime.emit({
+					type: "phase_failed",
+					phase: name,
+					cron,
+					error: serializeError(error)
+				});
+				return;
+			}
+		};
+		const startedAt = runtime.nowMs();
+		const deadlineAt = startedAt + invocationBudgetMs;
+		const within = { deadlineAt };
+		if (schedules.length > 0) await runSchedules(outbox, schedules, cron, event.scheduledTime ?? startedAt, deadlineAt - recoveryReserveMs);
+		const recovery = await phase("recover", () => runtime.recover(recoveryLimit, { deadlineAt: Math.min(deadlineAt, runtime.nowMs() + recoveryBudgetMs) }));
+		for (const slice of options.reserved ?? []) await phase("reserved", () => runtime.drain(slice.budget, "sweep", { kinds: slice.kinds }, within));
+		const report = await phase("drain", () => runtime.drain(budget, "sweep", {}, within));
+		await phase("handoff", () => runtime.handoff(budget.deadlineMs, 100, within));
+		const deleted = await phase("cleanup", () => runtime.cleanup(retention, within));
+		let continued = false;
+		if (report && report.claimed > report.errored) continued = await phase("drain", async () => {
+			let any = false;
+			for (const lane of runtime.lanes()) if (await runtime.hasBacklog({ lane }, within) && await runtime.continueDrain(lane, within)) any = true;
+			return any;
+		}) ?? false;
+		if (options.backlog) {
+			const backlogOptions = options.backlog;
+			await phase("backlog", () => runtime.monitorBacklog({
+				...backlogOptions,
+				...within
+			}));
+		}
+		runtime.emit({
+			type: "sweep_finished",
+			cron,
+			recovered: recovery ? recovery.retrying + recovery.dead : 0,
+			report: report ?? emptyReport(),
+			deleted: deleted ?? 0,
+			continued
+		});
+	};
+}
+// src/cloudflare/dlq-handler.ts
+/** A dead-lettered nudge loses nothing (cron still drives the job): report and ack. */
+function createDlqHandler(options = {}) {
+	const emit = createEmitter(options.events);
+	return async (batch) => {
+		for (const message of batch.messages) {
+			emit({
+				type: "dlq_message",
+				queue: batch.queue,
+				attempts: message.attempts,
+				body: previewBody(message.body)
+			});
+			message.ack();
+		}
+	};
+}
+export { DEFAULT_SWEEP_BUDGET, createDlqHandler, createQueueHandler, createScheduledHandler, defineSchedule, messageRetryDelaySeconds };