better-supabase 0.8.0 → 0.10.0

package/dist/blocks/jobs/index.js

@@ -1,17 +1,23 @@
 import { t as DbException } from "../../db-exception-CnWcYPxL.js";
-import { n as dbError } from "../../errors-2M6CKMP4.js";
-import { s as nowInstant } from "../../temporal-BJGitm-h.js";
-import { t as temporal } from "../../temporal-required-BtynQtM-.js";
-import { a as ok, r as err, s as toDbError, t as AsyncResult } from "../../result-DEqHCMKP.js";
+import { n as dbError } from "../../errors-8i6tSICm.js";
+import { s as nowInstant } from "../../temporal-CB5Fpo5d.js";
+import { t as temporal } from "../../temporal-required-DqRzr7i0.js";
+import { a as ok, r as err, s as toDbError, t as AsyncResult } from "../../result-COkvI9t5.js";
+import { n as isRecord } from "../../guards-6F2bCtQR.js";
 import { n as allTenantsContext } from "../../plugin-tfXW1-qO.js";
-import { n as validate } from "../../standard-DkzZUneg.js";
-import { o as problemResponse } from "../../problem-CJvFeGu7.js";
+import { n as validate } from "../../standard-DZmwmIhV.js";
+import { o as problemResponse } from "../../problem-pIiL3WbE.js";
 import { o as tenantFrom, s as tenantPathsFor } from "../../claims-PqzCxaTD.js";
-import { t as cronRoute } from "../../cron-route-D2AN9SA1.js";
-import { n as nextCronRun, t as assertCron } from "../../cron-D25Ukpxy.js";
-import { D as seconds, E as run, N as toInstant, a as budget, f as leaseHeartbeat, k as sleep, l as errorText, n as applyTemporal, y as pageOf } from "../../block-helpers-Cy3pB96I.js";
-import { i as createWebhookInbox, r as rateLimited, t as createRateLimit } from "../../rate-limit-Bw7HgmFj.js";
-import { n as withContext, t as unwrap } from "../../envelope-DqnYGRw7.js";
+import { n as rateLimitSqlOptions, r as webhookInboxSqlOptions, t as jobsSqlOptions } from "../../options-OJ5zmgr8.js";
+import { t as cronRoute } from "../../cron-route-BsgbJ-g4.js";
+import { i as sqlTransport, r as rpcTransport, t as dbTransport } from "../../block-transport-G4t1umrR.js";
+import { M as seconds, P as sleep, R as toInstant, f as errorText, g as leaseHeartbeat, j as run, n as applyTemporal, o as blockCall, s as budget, w as pageOf } from "../../block-helpers-BfVCR5Fc.js";
+import { n as periodSeconds } from "../../ratelimit-headers-Bsxx0Tj2.js";
+import { n as nextCronRun, t as assertCron } from "../../cron-CUaKTjWC.js";
+import { r as withBlockHooks } from "../../block-hooks-ByKlh8Qy.js";
+import { a as purgeWebhookInbox, i as createWebhookInbox, r as rateLimited, t as createRateLimit } from "../../rate-limit-ByfWNX9N.js";
+import { r as wrapPayload, t as unwrap } from "../../envelope--7d0Q3Se.js";
+import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
 //#region src/blocks/jobs/dev.ts
 function devDrainSecret(env, name = "CRON_SECRET") {
 	const current = env[name];
@@ -56,178 +62,6 @@ function devDrain(options) {
 	};
 }
 //#endregion
-//#region src/blocks/jobs/idempotency.ts
-async function sha256(text) {
-	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
-	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
-}
-const AUTH_COOKIE = /^sb-.+-auth-token(?:\.\d+)?$/;
-/** A hash of the credentials the request carries, or `''` without any. */
-async function callerScope(request) {
-	const authorization = request.headers.get("authorization");
-	const cookies = (request.headers.get("cookie") ?? "").split(";").map((pair) => pair.trim()).filter((pair) => AUTH_COOKIE.test(pair.split("=", 1)[0] ?? "")).sort();
-	const credential = authorization ?? cookies.join(";");
-	return credential === "" ? "" : `caller:${await sha256(credential)}`;
-}
-/** HTTP idempotency keys (IETF `Idempotency-Key` header) over the `idempotency` SQL module. */
-function createIdempotency(sql, options = {}) {
-	applyTemporal(options);
-	const headerName = options.header ?? "idempotency-key";
-	const format = options.problem;
-	const ttl = seconds(options.ttl ?? "24 hours");
-	const lock = seconds(options.lock ?? "1 minute");
-	const begin = (key, fingerprint, scope = "") => run(async () => {
-		const [row] = await sql.queryRaw("select * from better_supabase.begin_idempotent($1, $2, $3, $4::interval, $5::interval)", [
-			scope,
-			key,
-			fingerprint,
-			ttl,
-			lock
-		]);
-		return {
-			state: row.state,
-			status: row.status_code,
-			body: row.response,
-			holder: row.holder ?? void 0
-		};
-	});
-	const complete = (key, holder, status, body, scope = "") => run(async () => {
-		const [row] = await sql.queryRaw("select better_supabase.complete_idempotent($1, $2, $3, $4, $5) as done", [
-			scope,
-			key,
-			holder,
-			status,
-			JSON.stringify(body)
-		]);
-		return row?.done === true;
-	});
-	const release = (key, holder, scope = "") => run(async () => {
-		const [row] = await sql.queryRaw("select better_supabase.release_idempotent($1, $2, $3) as done", [
-			scope,
-			key,
-			holder
-		]);
-		return row?.done === true;
-	});
-	return {
-		begin,
-		complete,
-		release,
-		async handle(request, handler) {
-			const key = request.headers.get(headerName);
-			const instance = new URL(request.url).pathname;
-			if (!key) return options.required ? problemResponse(dbError("invalid_request", `The ${headerName} header is required`, { code: "IDEMPOTENCY_KEY_MISSING" }), {
-				instance,
-				format
-			}) : handler(request);
-			if (key.length > 255) return problemResponse(dbError("invalid_request", `The ${headerName} header is too long`, { code: "IDEMPOTENCY_KEY_INVALID" }), {
-				instance,
-				format
-			});
-			const scope = typeof options.scope === "function" ? options.scope(request) : options.scope ?? await callerScope(request);
-			const body = await request.clone().text();
-			const fingerprint = await sha256(`${request.method} ${instance}\n${body}`);
-			const started = await begin(key, fingerprint, scope);
-			if (!started.ok) return problemResponse(started.error, {
-				instance,
-				format
-			});
-			const { state, holder = "" } = started.data;
-			switch (state) {
-				case "replay": {
-					const stored = started.data.body;
-					return new Response(stored.body, {
-						status: started.data.status ?? 200,
-						headers: {
-							...stored.contentType ? { "content-type": stored.contentType } : {},
-							"idempotency-replayed": "true"
-						}
-					});
-				}
-				case "running": return problemResponse(dbError("conflict", "A request with this idempotency key is still running", { code: "IDEMPOTENCY_KEY_IN_USE" }), {
-					instance,
-					format,
-					headers: { "retry-after": "1" }
-				});
-				case "mismatch": return problemResponse(dbError("validation", "This idempotency key was used for a different request", {
-					code: "IDEMPOTENCY_KEY_REUSED",
-					issues: [{
-						message: "Use a new key for a new request",
-						path: [headerName]
-					}]
-				}), {
-					instance,
-					format
-				});
-				case "started": break;
-				default: throw new TypeError(`Unknown idempotency state ${String(state)}`);
-			}
-			let response;
-			try {
-				response = await handler(request);
-			} catch (cause) {
-				await release(key, holder, scope);
-				throw cause;
-			}
-			if (response.status >= 500) {
-				await release(key, holder, scope);
-				return response;
-			}
-			const stored = {
-				body: await response.clone().text(),
-				contentType: response.headers.get("content-type")
-			};
-			await complete(key, holder, response.status, stored, scope);
-			return response;
-		}
-	};
-}
-//#endregion
-//#region src/blocks/jobs/lease.ts
-/**
-* Runs `fn` while holding the lease on `key`, one holder at a time, and
-* releases it afterwards, also when `fn` throws. `{ acquired: false }` while
-* another holder has it. A lease that expires mid-run is taken by the next
-* caller; call `lease.extend()` for long work.
-*/
-function withLease(sql, key, fn, options = {}) {
-	const scope = options.scope ?? "";
-	const ttl = options.seconds ?? 60;
-	return run(async () => {
-		const [row] = await sql.queryRaw("select better_supabase.acquire_lease($1, $2, $3) as holder", [
-			key,
-			ttl,
-			scope
-		]);
-		const holder = row?.holder;
-		if (!holder) return { acquired: false };
-		const lease = {
-			holder,
-			extend: (next = ttl) => run(async () => {
-				const [extended] = await sql.queryRaw("select better_supabase.extend_lease($1, $2, $3, $4) as done", [
-					key,
-					holder,
-					next,
-					scope
-				]);
-				return extended?.done === true;
-			})
-		};
-		try {
-			return {
-				acquired: true,
-				value: await fn(lease)
-			};
-		} finally {
-			await sql.queryRaw("select better_supabase.release_lease($1, $2, $3)", [
-				key,
-				holder,
-				scope
-			]);
-		}
-	});
-}
-//#endregion
 //#region src/blocks/jobs/backends.ts
 const instantOrNull = (value) => value === null ? null : toInstant(value);
 /** Schedule times are stored to the millisecond, the precision `Date` reads back. */
@@ -244,8 +78,64 @@ function firstRun(row, now) {
 	}
 }
 /**
+* The due schedules among claimed rows. A row written in SQL without a next
+* run gets its first run here; one not due yet is moved to it with `advance`.
+*/
+async function dueOf(rows, now, advance) {
+	const due = [];
+	for (const row of rows) {
+		const schedule = {
+			name: row.job_name,
+			cron: row.schedule,
+			timeZone: row.timezone,
+			queue: row.queue,
+			payload: row.payload
+		};
+		if (row.next_run !== null) {
+			due.push({
+				...schedule,
+				nextRun: toInstant(row.next_run)
+			});
+			continue;
+		}
+		const first = firstRun(row, now);
+		if (first === void 0) continue;
+		if (temporal().Instant.compare(first, now()) <= 0) due.push({
+			...schedule,
+			nextRun: first
+		});
+		else await advance(row.job_name, first);
+	}
+	return due;
+}
+const scheduleInfo = (row) => ({
+	name: row.job_name,
+	cron: row.schedule,
+	timeZone: row.timezone,
+	queue: row.queue,
+	tenant: row.tenant,
+	nextRun: instantOrNull(row.next_run),
+	lastRun: instantOrNull(row.last_run),
+	leasedUntil: instantOrNull(row.locked_until),
+	createdAt: instantOrNull(row.created_at)
+});
+const statsOf = (row) => ({
+	ready: Number(row?.ready ?? 0),
+	inFlight: Number(row?.in_flight ?? 0),
+	delayed: Number(row?.delayed ?? 0),
+	dead: Number(row?.dead ?? 0),
+	oldestAgeSeconds: row?.oldest_age_seconds === null || row?.oldest_age_seconds === void 0 ? null : Number(row.oldest_age_seconds)
+});
+const onceOf = (row) => {
+	if (!row) throw new TypeError("enqueue_job_once returned no row");
+	return {
+		id: Number(row.id),
+		duplicate: row.duplicate
+	};
+};
+/**
 * The `jobs` SQL module over a service SQL connection. The same
-* functions back both `sql.modules.jobs.options.backend` values (pgmq and table)
+* functions back both `blocks.jobs.options.backend` values (pgmq and table)
 * and both schedulers. `now` dates a schedule's first run.
 */
 function sqlQueueBackend(sql, now = nowInstant) {
@@ -264,6 +154,16 @@ function sqlQueueBackend(sql, now = nowInstant) {
 			]);
 			return Number(row.id);
 		},
+		async sendOnce(queue, payload, delay, maxAttempts, dedupeKey) {
+			const [row] = await sql.queryRaw("select * from better_supabase.enqueue_job_once($1, $2, $3, $4, $5)", [
+				queue,
+				JSON.stringify(payload ?? {}),
+				dedupeKey,
+				delay,
+				maxAttempts
+			]);
+			return onceOf(row);
+		},
 		read: (queue, lease, batch) => sql.queryRaw("select * from better_supabase.claim_jobs($1, $2, $3)", [
 			queue,
 			lease,
@@ -302,13 +202,7 @@ function sqlQueueBackend(sql, now = nowInstant) {
 		},
 		async stats(queue) {
 			const [row] = await sql.queryRaw("select * from better_supabase.job_queue_stats($1)", [queue]);
-			return {
-				ready: Number(row?.ready ?? 0),
-				inFlight: Number(row?.in_flight ?? 0),
-				delayed: Number(row?.delayed ?? 0),
-				dead: Number(row?.dead ?? 0),
-				oldestAgeSeconds: row?.oldest_age_seconds === null || row?.oldest_age_seconds === void 0 ? null : Number(row.oldest_age_seconds)
-			};
+			return statsOf(row);
 		},
 		listDead: (queue, limit, before) => sql.queryRaw("select * from better_supabase.list_dead_jobs($1, $2, $3)", [
 			queue,
@@ -323,6 +217,15 @@ function sqlQueueBackend(sql, now = nowInstant) {
 			]);
 			return row?.retried ?? 0;
 		},
+		async purge(queue, args) {
+			const named = Object.entries({
+				older_than: args.olderThan,
+				batch: args.batch,
+				dead_older_than: args.deadOlderThan
+			}).filter(([, value]) => value !== void 0);
+			const [row] = await sql.queryRaw(`select better_supabase.purge_job_archive(${["queue => $1", ...named.map(([name], index) => `${name} => $${String(index + 2)}`)].join(", ")}) as purged`, [queue, ...named.map(([, value]) => value)]);
+			return row?.purged ?? 0;
+		},
 		async schedule(name, cron, queue, payload, timeZone, nextRun, tenant) {
 			await sql.queryRaw("select better_supabase.schedule_job($1, $2, $3, $4, $5, $6, $7)", [
 				name,
@@ -335,17 +238,7 @@ function sqlQueueBackend(sql, now = nowInstant) {
 			]);
 		},
 		async listSchedules(filter) {
-			return (await sql.queryRaw("select * from better_supabase.list_schedules($1, $2)", [filter.prefix ?? null, filter.tenant ?? null])).map((row) => ({
-				name: row.job_name,
-				cron: row.schedule,
-				timeZone: row.timezone,
-				queue: row.queue,
-				tenant: row.tenant,
-				nextRun: instantOrNull(row.next_run),
-				lastRun: instantOrNull(row.last_run),
-				leasedUntil: instantOrNull(row.locked_until),
-				createdAt: instantOrNull(row.created_at)
-			}));
+			return (await sql.queryRaw("select * from better_supabase.list_schedules($1, $2)", [filter.prefix ?? null, filter.tenant ?? null])).map(scheduleInfo);
 		},
 		async unscheduleTenant(tenant) {
 			const [row] = await sql.queryRaw("select better_supabase.unschedule_tenant($1) as removed", [tenant]);
@@ -356,32 +249,9 @@ function sqlQueueBackend(sql, now = nowInstant) {
 			return row?.done ?? false;
 		},
 		async dueSchedules(lease, batch) {
-			const rows = await sql.queryRaw("select * from better_supabase.claim_due_schedules($1, $2)", [lease, batch]);
-			const due = [];
-			for (const row of rows) {
-				const schedule = {
-					name: row.job_name,
-					cron: row.schedule,
-					timeZone: row.timezone,
-					queue: row.queue,
-					payload: row.payload
-				};
-				if (row.next_run !== null) {
-					due.push({
-						...schedule,
-						nextRun: toInstant(row.next_run)
-					});
-					continue;
-				}
-				const first = firstRun(row, now);
-				if (first === void 0) continue;
-				if (temporal().Instant.compare(first, now()) <= 0) due.push({
-					...schedule,
-					nextRun: first
-				});
-				else await sql.queryRaw("select better_supabase.advance_schedule($1, null, $2)", [row.job_name, first.toString()]);
-			}
-			return due;
+			return dueOf(await sql.queryRaw("select * from better_supabase.claim_due_schedules($1, $2)", [lease, batch]), now, async (name, first) => {
+				await sql.queryRaw("select better_supabase.advance_schedule($1, null, $2)", [name, first.toString()]);
+			});
 		},
 		async advanceSchedule(name, ran, next) {
 			const [row] = await sql.queryRaw("select better_supabase.advance_schedule($1, $2, $3) as advanced", [
@@ -393,6 +263,142 @@ function sqlQueueBackend(sql, now = nowInstant) {
 		}
 	};
 }
+/** The named arguments of each `jobs` function, in call order. */
+const PARAMS = {
+	enqueue_job: [
+		"queue",
+		"payload",
+		"delay",
+		"max_attempts",
+		"dedupe_key",
+		"dedupe_running"
+	],
+	enqueue_job_once: [
+		"queue",
+		"payload",
+		"dedupe_key",
+		"delay",
+		"max_attempts"
+	],
+	claim_jobs: [
+		"queue",
+		"lease",
+		"batch"
+	],
+	complete_job: [
+		"queue",
+		"job_id",
+		"attempt"
+	],
+	fail_job: [
+		"queue",
+		"job_id",
+		"attempt",
+		"error",
+		"retry_in"
+	],
+	extend_job_lease: [
+		"queue",
+		"job_id",
+		"attempt",
+		"lease"
+	],
+	replay_dead_job: ["queue", "job_id"],
+	job_queue_stats: ["queue"],
+	list_dead_jobs: [
+		"queue",
+		"max_rows",
+		"before_id"
+	],
+	retry_dead_jobs: [
+		"queue",
+		"ids",
+		"batch"
+	],
+	schedule_job: [
+		"job_name",
+		"schedule",
+		"queue",
+		"payload",
+		"timezone",
+		"next_run",
+		"tenant"
+	],
+	unschedule_job: ["job_name"],
+	list_schedules: ["name_prefix", "for_tenant"],
+	unschedule_tenant: ["tenant"],
+	claim_due_schedules: ["lease", "batch"],
+	advance_schedule: [
+		"job_name",
+		"ran",
+		"next_run"
+	],
+	purge_job_archive: [
+		"queue",
+		"older_than",
+		"batch",
+		"dead_older_than"
+	]
+};
+/**
+* The rows a set-returning function answered with. PostgREST and `dbTransport`
+* return an array; a single object is one row.
+*/
+function transportRows(fn, value) {
+	if (value === null || value === void 0) return [];
+	if (Array.isArray(value)) return value;
+	if (isRecord(value)) return [value];
+	throw new TypeError(`${fn} returned ${typeof value}, not rows: pass a SqlClient instead of sqlTransport for set-returning functions`);
+}
+/**
+* The `jobs` SQL module over a `BlockTransport`, with named arguments: a
+* service-role `rpcTransport(supabase, { schema: "api" })` reaches the
+* wrappers `blocks.jobs.api` writes, so stats, dead letters, replays
+* and schedules work without a direct Postgres connection. Over Postgres,
+* pass the `SqlClient` to `createJobs` instead.
+*/
+function transportQueueBackend(transport, options = {}) {
+	const schema = options.schema ?? "better_supabase";
+	const now = options.now ?? nowInstant;
+	const call = (fn, ...args) => transport.call(schema, fn, Object.fromEntries(PARAMS[fn].flatMap((name, index) => index < args.length ? [[name, args[index]]] : [])));
+	const rows = async (fn, ...args) => transportRows(fn, await call(fn, ...args));
+	const bool = async (fn, ...args) => await call(fn, ...args) === true;
+	const count = async (fn, ...args) => Number(await call(fn, ...args) ?? 0);
+	const id = (value) => value === null || value === void 0 ? null : Number(value);
+	return {
+		apiVersion: 1,
+		name: "transport",
+		leases: true,
+		async send(queue, payload, delay, maxAttempts, dedupeKey, dedupe) {
+			const sent = id(await call("enqueue_job", queue, payload ?? {}, delay, maxAttempts, dedupeKey ?? null, dedupe !== "waiting"));
+			if (sent === null) throw new TypeError("enqueue_job returned no id");
+			return sent;
+		},
+		sendOnce: async (queue, payload, delay, maxAttempts, dedupeKey) => onceOf((await rows("enqueue_job_once", queue, payload ?? {}, dedupeKey, delay, maxAttempts))[0]),
+		read: (queue, lease, batch) => rows("claim_jobs", queue, lease, batch),
+		complete: (job) => bool("complete_job", job.queue, job.id, job.attempts),
+		async fail(job, error, retryIn) {
+			const status = await call("fail_job", job.queue, job.id, job.attempts, error, retryIn ?? null);
+			return status === "queued" || status === "dead" ? status : null;
+		},
+		extend: (job, lease) => bool("extend_job_lease", job.queue, job.id, job.attempts, lease),
+		replay: async (queue, jobId) => id(await call("replay_dead_job", queue, jobId)),
+		stats: async (queue) => statsOf((await rows("job_queue_stats", queue))[0]),
+		listDead: (queue, limit, before) => rows("list_dead_jobs", queue, limit, before ?? null),
+		retryDead: (queue, ids, limit) => count("retry_dead_jobs", queue, ids === void 0 ? null : [...ids], limit),
+		purge: (queue, args) => count("purge_job_archive", queue, args.olderThan, args.batch, args.deadOlderThan),
+		async schedule(name, cron, queue, payload, timeZone, nextRun, tenant) {
+			await call("schedule_job", name, cron, queue, payload ?? {}, timeZone, nextRun.toString(), tenant ?? null);
+		},
+		unschedule: (name) => bool("unschedule_job", name),
+		listSchedules: async (filter) => (await rows("list_schedules", filter.prefix ?? null, filter.tenant ?? null)).map(scheduleInfo),
+		unscheduleTenant: (tenant) => count("unschedule_tenant", tenant),
+		dueSchedules: async (lease, batch) => dueOf(await rows("claim_due_schedules", lease, batch), now, async (name, first) => {
+			await call("advance_schedule", name, null, first.toString());
+		}),
+		advanceSchedule: (name, ran, next) => bool("advance_schedule", name, ran.toString(), next.toString())
+	};
+}
 /** Throws for a feature the transport doesn't support. */
 function sqlOnly(feature) {
 	throw new DbException(dbError("invalid_request", `${feature} needs a SQL connection; pgmq_public (PostgREST) does not support it`));
@@ -438,12 +444,12 @@ function pgmqPublicBackend(client) {
 				sleep_seconds: lease,
 				n: batch
 			});
-			const live = [];
-			for (const row of rows) if (row.read_ct > (row.message?.max_attempts ?? 5)) await call("archive", {
+			const dead = (row) => row.read_ct > (row.message?.max_attempts ?? 5);
+			const live = rows.filter((row) => !dead(row));
+			await Promise.all(rows.filter(dead).map((row) => call("archive", {
 				queue_name: queue,
 				message_id: row.msg_id
-			});
-			else live.push(row);
+			})));
 			return live.map((row) => ({
 				id: row.msg_id,
 				attempts: row.read_ct,
@@ -464,9 +470,300 @@ function pgmqPublicBackend(client) {
 	};
 }
 //#endregion
+//#region src/blocks/jobs/idempotency.ts
+async function sha256(text) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+const AUTH_COOKIE = /^sb-.+-auth-token(?:\.\d+)?$/;
+/** A hash of the credentials the request carries, or `''` without any. */
+async function callerScope(request) {
+	const authorization = request.headers.get("authorization");
+	const cookies = (request.headers.get("cookie") ?? "").split(";").map((pair) => pair.trim()).filter((pair) => AUTH_COOKIE.test(pair.split("=", 1)[0] ?? "")).sort();
+	const credential = authorization ?? cookies.join(";");
+	return credential === "" ? "" : `caller:${await sha256(credential)}`;
+}
+function sqlCalls$1(sql) {
+	return {
+		begin: (scope, key, fingerprint, ttl, lock) => run(async () => {
+			const [row] = await sql.queryRaw("select * from better_supabase.begin_idempotent($1, $2, $3, $4::interval, $5::interval)", [
+				scope,
+				key,
+				fingerprint,
+				ttl,
+				lock
+			]);
+			return row;
+		}),
+		complete: (scope, key, holder, status, body) => run(async () => {
+			const [row] = await sql.queryRaw("select better_supabase.complete_idempotent($1, $2, $3, $4, $5) as done", [
+				scope,
+				key,
+				holder,
+				status,
+				JSON.stringify(body)
+			]);
+			return row?.done === true;
+		}),
+		extend: (scope, key, holder, lock) => run(async () => {
+			const [row] = await sql.queryRaw("select better_supabase.extend_idempotent($1, $2, $3, $4::interval) as done", [
+				scope,
+				key,
+				holder,
+				lock
+			]);
+			return row?.done === true;
+		}),
+		release: (scope, key, holder) => run(async () => {
+			const [row] = await sql.queryRaw("select better_supabase.release_idempotent($1, $2, $3) as done", [
+				scope,
+				key,
+				holder
+			]);
+			return row?.done === true;
+		}),
+		purge: () => run(async () => {
+			const [row] = await sql.queryRaw("select better_supabase.purge_idempotency_keys() as purged");
+			return row?.purged ?? 0;
+		})
+	};
+}
+function transportCalls$1(transport, schema, mappers) {
+	const call = blockCall(transport, schema, mappers);
+	return {
+		begin: (scope, key, fingerprint, ttl, lock) => call("begin_idempotent", {
+			scope,
+			key,
+			request_hash: fingerprint,
+			ttl,
+			lock
+		}, (value) => transportRows("begin_idempotent", value)[0]),
+		complete: (scope, key, holder, status, body) => call("complete_idempotent", {
+			scope,
+			key,
+			holder,
+			status_code: status,
+			response: body
+		}, (value) => value === true),
+		extend: (scope, key, holder, lock) => call("extend_idempotent", {
+			scope,
+			key,
+			holder,
+			lock
+		}, (value) => value === true),
+		release: (scope, key, holder) => call("release_idempotent", {
+			scope,
+			key,
+			holder
+		}, (value) => value === true),
+		purge: () => call("purge_idempotency_keys", {}, (value) => Number(value ?? 0))
+	};
+}
+/**
+* HTTP idempotency keys (IETF `Idempotency-Key` header) over the
+* `idempotency` SQL module: a service SQL connection, or a service-role
+* `rpcTransport` over the wrappers `blocks.idempotency.api` writes.
+*/
+function createIdempotency(options) {
+	applyTemporal(options);
+	const headerName = options.header ?? "idempotency-key";
+	const format = options.problem;
+	const ttl = seconds(options.ttl ?? "24 hours");
+	const lock = seconds(options.lock ?? "1 minute");
+	const lockSeconds = periodSeconds(options.lock ?? 60) ?? 2;
+	const calls = options.transport === void 0 ? sqlCalls$1(options.sql) : transportCalls$1(options.transport, options.schema, options.mappers);
+	const hooked = withBlockHooks({
+		purge: () => calls.purge(),
+		purgeJob: () => async () => hooked.purge().orThrow(),
+		begin: (key, fingerprint, scope = "") => calls.begin(scope, key, fingerprint, ttl, lock).andThen((row) => row ? AsyncResult.ok({
+			state: row.state,
+			status: row.status_code,
+			body: row.response,
+			holder: row.holder ?? void 0
+		}) : AsyncResult.err(dbError("unexpected", "begin_idempotent returned no row"))),
+		extend: (key, holder, scope = "") => calls.extend(scope, key, holder, lock),
+		complete: (key, holder, status, body, scope = "") => calls.complete(scope, key, holder, status, body),
+		release: (key, holder, scope = "") => calls.release(scope, key, holder),
+		async handle(request, handler) {
+			const key = request.headers.get(headerName);
+			const url = new URL(request.url);
+			const instance = url.pathname;
+			if (!key) return options.required ? problemResponse(dbError("invalid_request", `The ${headerName} header is required`, { code: "IDEMPOTENCY_KEY_MISSING" }), {
+				instance,
+				format
+			}) : handler(request);
+			if (key.length > 255) return problemResponse(dbError("invalid_request", `The ${headerName} header is too long`, { code: "IDEMPOTENCY_KEY_INVALID" }), {
+				instance,
+				format
+			});
+			const scope = typeof options.scope === "function" ? options.scope(request) : options.scope ?? await callerScope(request);
+			const body = await request.clone().text();
+			const fingerprint = await sha256(`${request.method} ${instance}${url.search}\n${body}`);
+			const started = await hooked.begin(key, fingerprint, scope);
+			if (!started.ok) return problemResponse(started.error, {
+				instance,
+				format
+			});
+			const { state, holder = "" } = started.data;
+			switch (state) {
+				case "replay": {
+					const stored = started.data.body;
+					return new Response(stored.body, {
+						status: started.data.status ?? 200,
+						headers: {
+							...stored.contentType ? { "content-type": stored.contentType } : {},
+							"idempotency-replayed": "true"
+						}
+					});
+				}
+				case "running": return problemResponse(dbError("conflict", "A request with this idempotency key is still running", { code: "IDEMPOTENCY_KEY_IN_USE" }), {
+					instance,
+					format,
+					headers: { "retry-after": "1" }
+				});
+				case "mismatch": return problemResponse(dbError("validation", "This idempotency key was used for a different request", {
+					code: "IDEMPOTENCY_KEY_REUSED",
+					issues: [{
+						message: "Use a new key for a new request",
+						path: [headerName]
+					}]
+				}), {
+					instance,
+					format
+				});
+				case "started": break;
+				default: throw new TypeError(`Unknown idempotency state ${String(state)}`);
+			}
+			let renewing = true;
+			const stopHeartbeat = leaseHeartbeat(lockSeconds, () => {
+				if (!renewing) return;
+				hooked.extend(key, holder, scope).then((extended) => {
+					if (extended.ok && !extended.data) renewing = false;
+				});
+			});
+			try {
+				let response;
+				try {
+					response = await handler(request);
+				} catch (cause) {
+					await hooked.release(key, holder, scope);
+					throw cause;
+				}
+				if (response.status >= 500) {
+					await hooked.release(key, holder, scope);
+					return response;
+				}
+				const stored = {
+					body: await response.clone().text(),
+					contentType: response.headers.get("content-type")
+				};
+				const completed = await hooked.complete(key, holder, response.status, stored, scope);
+				if (!completed.ok || !completed.data) return problemResponse(completed.ok ? dbError("conflict", "The idempotency key's lock expired before the response was saved", { code: "IDEMPOTENCY_KEY_LOST" }) : completed.error, {
+					instance,
+					format,
+					headers: { "retry-after": "1" }
+				});
+				return response;
+			} finally {
+				stopHeartbeat();
+			}
+		}
+	}, options.hooks, {
+		block: "idempotency",
+		...options.logger ? { logger: options.logger } : {}
+	});
+	return hooked;
+}
+//#endregion
+//#region src/blocks/jobs/lease.ts
+function sqlCalls(sql) {
+	return {
+		async acquire(key, ttl, scope) {
+			const [row] = await sql.queryRaw("select better_supabase.acquire_lease($1, $2, $3) as holder", [
+				key,
+				ttl,
+				scope
+			]);
+			return row?.holder ?? null;
+		},
+		async extend(key, holder, ttl, scope) {
+			const [row] = await sql.queryRaw("select better_supabase.extend_lease($1, $2, $3, $4) as done", [
+				key,
+				holder,
+				ttl,
+				scope
+			]);
+			return row?.done === true;
+		},
+		async release(key, holder, scope) {
+			await sql.queryRaw("select better_supabase.release_lease($1, $2, $3)", [
+				key,
+				holder,
+				scope
+			]);
+		}
+	};
+}
+function transportCalls(transport, schema) {
+	return {
+		async acquire(key, ttl, scope) {
+			const holder = await transport.call(schema, "acquire_lease", {
+				key,
+				seconds: ttl,
+				scope
+			});
+			return typeof holder === "string" ? holder : null;
+		},
+		extend: async (key, holder, ttl, scope) => await transport.call(schema, "extend_lease", {
+			key,
+			holder,
+			seconds: ttl,
+			scope
+		}) === true,
+		async release(key, holder, scope) {
+			await transport.call(schema, "release_lease", {
+				key,
+				holder,
+				scope
+			});
+		}
+	};
+}
+/**
+* Runs `fn` while holding the lease on `key`, one holder at a time, and
+* releases it afterwards, also when `fn` throws. `{ acquired: false }` while
+* another holder has it. A lease that expires mid-run is taken by the next
+* caller; call `lease.extend()` for long work. Takes a service SQL
+* connection, or a service-role `rpcTransport` over the wrappers
+* `blocks.idempotency.api` writes.
+*/
+function withLease(source, key, fn, options = {}) {
+	const scope = options.scope ?? "";
+	const ttl = options.seconds ?? 60;
+	const calls = "call" in source ? transportCalls(source, options.schema ?? "better_supabase") : sqlCalls(source);
+	return run(async () => {
+		const holder = await calls.acquire(key, ttl, scope);
+		if (!holder) return { acquired: false };
+		const lease = {
+			holder,
+			extend: (next = ttl) => run(() => calls.extend(key, holder, next, scope))
+		};
+		try {
+			return {
+				acquired: true,
+				value: await fn(lease)
+			};
+		} finally {
+			await calls.release(key, holder, scope);
+		}
+	});
+}
+//#endregion
 //#region src/blocks/jobs/queue.ts
 /** Transient claim errors in a row a lane retries, with backoff, before the loop throws. */
 const CLAIM_RETRIES = 3;
+/** The abort reason of a job whose lease couldn't be extended. */
+const LEASE_LOST = Symbol("lease lost");
 const TRANSIENT = /* @__PURE__ */ new Set([
 	"network",
 	"timeout",
@@ -489,31 +786,48 @@ function toJob(queue, row) {
 	};
 }
 const QUEUE_NAME = /^[a-z_][a-z0-9_]{0,46}$/;
-function isBackend(source) {
-	return "apiVersion" in source;
-}
-function isSqlClient(source) {
-	return typeof source.queryRaw === "function";
+/**
+* `transport` with every call made through `blockCall`, so a rejection is
+* mapped to a `DbError` (with the app's `mappers` first), as in every block.
+*/
+function mappedTransport(transport, mappers) {
+	return { async call(schema, fn, args) {
+		const result = await blockCall(transport, schema, mappers)(fn, args, (value) => value);
+		if (!result.ok) throw new DbException(result.error);
+		return result.data;
+	} };
 }
-function backendOf(source, now) {
-	if (isBackend(source)) return source;
-	return isSqlClient(source) ? sqlQueueBackend(source, now) : pgmqPublicBackend(source);
+function backendOf(options, now) {
+	if (options.backend) return options.backend;
+	if (options.sql) return sqlQueueBackend(options.sql, now);
+	if (options.client && options.schema) return transportQueueBackend(mappedTransport(rpcTransport(options.client, { schema: options.schema }), options.mappers), {
+		now,
+		schema: options.schema
+	});
+	if (options.client) return pgmqPublicBackend(options.client);
+	if (options.transport) return transportQueueBackend(mappedTransport(options.transport, options.mappers), {
+		now,
+		...options.schema ? { schema: options.schema } : {}
+	});
+	throw new TypeError("createJobs needs a backend, sql, client or transport to store jobs");
 }
 const later = (a, b) => temporal().Instant.compare(a, b) >= 0 ? a : b;
 /**
 * Typed jobs on Supabase Queues (pgmq), over the `jobs` SQL module.
 *
 * Pass a service SQL connection (`postgres.admin`, `ctx.sql`) for the full
-* feature set, a service-role Supabase client to go through the
-* `pgmq_public` RPCs where no direct connection exists (edge functions), or
-* any `QueueBackend`. Queue names are lowercase letters, digits and
-* underscores.
+* feature set, a service-role `rpcTransport` over the wrappers
+* `blocks.jobs.api` writes for the same features over the Data API (or a
+* service-role Supabase client with `schema` set to that schema), a
+* service-role Supabase client to go through the `pgmq_public` RPCs, or any
+* `QueueBackend`. Queue names are lowercase letters, digits and underscores.
 */
-function createJobs(source, queues, options = {}) {
+function createJobs(options) {
 	applyTemporal(options);
+	const queues = options.queues ?? {};
 	const now = options.now ?? nowInstant;
 	for (const name of Object.keys(queues)) if (!QUEUE_NAME.test(name)) throw new TypeError(`Queue "${name}": pgmq queue names are lowercase letters, digits and underscores (at most 47)`);
-	const transport = backendOf(source, now);
+	const transport = backendOf(options, now);
 	const schemaOf = (queue) => {
 		const schema = queues[queue];
 		if (!schema) throw new TypeError(`Unknown queue "${queue}". Queues: ${Object.keys(queues).join(", ")}`);
@@ -528,12 +842,20 @@ function createJobs(source, queues, options = {}) {
 	/**
 	* Extends the lease of every job in `held` at half the lease, so jobs
 	* waiting their turn in a claimed batch don't expire before they run.
+	* A job whose lease can't be extended is aborted: another worker may
+	* already hold it.
 	*/
 	const heartbeat = (held, lease) => transport.leases ? leaseHeartbeat(lease, () => {
-		for (const job of held) run(() => transport.extend(job, lease));
+		for (const [job, controller] of held) run(() => transport.extend(job, lease)).then((extended) => {
+			if (!extended.ok || !extended.data) controller.abort(LEASE_LOST);
+		});
 	}) : void 0;
-	const handle = async (job, handler, workOptions) => {
-		const controller = new AbortController();
+	const leaseLost = (job, workOptions) => {
+		workOptions.onError?.(dbError("conflict", `The lease on job ${String(job.id)} in "${job.queue}" was lost, so another worker may run it`, { code: "JOB_LEASE_LOST" }), job);
+		return false;
+	};
+	const handle = async (job, handler, workOptions, controller = new AbortController()) => {
+		if (controller.signal.reason === LEASE_LOST) return leaseLost(job, workOptions);
 		try {
 			const payload = await validate(schemaOf(job.queue), job.payload, "payload");
 			if (!payload.ok) {
@@ -548,9 +870,15 @@ function createJobs(source, queues, options = {}) {
 				context
 			}, controller.signal);
 			if (typeof outcome === "object" && outcome !== null && "ok" in outcome && outcome.ok === false && "error" in outcome) throw outcome.error;
-			await complete(job);
-			return true;
+			if (controller.signal.reason === LEASE_LOST) return leaseLost(job, workOptions);
+			const completed = await complete(job);
+			if (!completed.ok) {
+				workOptions.onError?.(completed.error, job);
+				return false;
+			}
+			return completed.data || leaseLost(job, workOptions);
 		} catch (cause) {
+			if (controller.signal.reason === LEASE_LOST) return leaseLost(job, workOptions);
 			controller.abort();
 			await fail(job, cause);
 			workOptions.onError?.(typeof cause === "object" && cause !== null && "kind" in cause ? cause : toDbError(cause), job);
@@ -592,11 +920,11 @@ function createJobs(source, queues, options = {}) {
 					continue;
 				}
 				wait = firstWait;
-				const held = new Set(claimed.data);
+				const held = new Map(claimed.data.map((job) => [job, new AbortController()]));
 				const stopHeartbeat = heartbeat(held, lease);
 				try {
 					for (const job of claimed.data) {
-						if (await handle(job, handler, workOptions)) succeeded += 1;
+						if (await handle(job, handler, workOptions, held.get(job))) succeeded += 1;
 						else failed += 1;
 						held.delete(job);
 					}
@@ -635,23 +963,70 @@ function createJobs(source, queues, options = {}) {
 				path: [name, "cron"]
 			}] }));
 		}
+		const wrapped = wrapPayload(valid.data, scheduleOptions.context);
+		if (!wrapped.ok) return wrapped;
 		return ok({
 			name,
 			cron,
 			queue,
-			payload: withContext(valid.data, scheduleOptions.context),
+			payload: wrapped.data,
 			timeZone,
 			tenant: scheduleOptions.tenant ?? (scheduleOptions.context ? tenantFrom(scheduleOptions.context, tenantPathsFor(void 0)) : void 0) ?? tenantDefault
 		});
 	};
 	const write = (prepared) => transport.schedule(prepared.name, prepared.cron, prepared.queue, prepared.payload, prepared.timeZone, millis(nextCronRun(prepared.cron, prepared.timeZone, now())), prepared.tenant);
-	return {
+	const purge = (purgeOptions = {}) => run(async () => {
+		if (!transport.purge) sqlOnly("purge");
+		const backendPurge = transport.purge.bind(transport);
+		const interval = (value) => value === void 0 ? void 0 : seconds(value);
+		return (await Promise.all((purgeOptions.queues ?? Object.keys(queues)).map((queue) => {
+			schemaOf(queue);
+			return backendPurge(queue, {
+				olderThan: interval(purgeOptions.olderThan),
+				deadOlderThan: interval(purgeOptions.deadOlderThan),
+				batch: purgeOptions.batch
+			});
+		}))).reduce((sum, count) => sum + count, 0);
+	});
+	const delayOf = (enqueueOptions) => {
+		const delay = enqueueOptions.delay;
+		if (delay !== void 0 && (!Number.isInteger(delay) || delay < 0)) return err(dbError("validation", "delay is a whole number of seconds", { issues: [{
+			message: "Expected a non-negative integer",
+			path: ["delay"]
+		}] }));
+		return ok(delay ?? (enqueueOptions.runAt ? Math.max(0, Math.ceil((enqueueOptions.runAt.epochMilliseconds - now().epochMilliseconds) / 1e3)) : 0));
+	};
+	/** The validated payload in its envelope, and the delay, for `enqueue` and `enqueueOnce`. */
+	const prepareSend = async (queue, payload, enqueueOptions) => {
+		const valid = await validate(schemaOf(queue), payload, "payload");
+		if (!valid.ok) return valid;
+		const delay = delayOf(enqueueOptions);
+		if (!delay.ok) return delay;
+		const message = wrapPayload(valid.data, enqueueOptions.context, { ...enqueueOptions.ticket === void 0 ? {} : { ticket: enqueueOptions.ticket } });
+		if (!message.ok) return message;
+		return ok({
+			message: message.data,
+			delay: delay.data
+		});
+	};
+	return withBlockHooks({
 		enqueue(queue, payload, enqueueOptions = {}) {
 			return AsyncResult.from(async () => {
-				const valid = await validate(schemaOf(queue), payload, "payload");
-				if (!valid.ok) return valid;
-				const delay = enqueueOptions.delay ?? (enqueueOptions.runAt ? Math.max(0, Math.ceil((enqueueOptions.runAt.epochMilliseconds - now().epochMilliseconds) / 1e3)) : 0);
-				return run(() => transport.send(queue, withContext(valid.data, enqueueOptions.context), delay, enqueueOptions.maxAttempts ?? 5, enqueueOptions.dedupeKey, enqueueOptions.dedupe));
+				const prepared = await prepareSend(queue, payload, enqueueOptions);
+				if (!prepared.ok) return prepared;
+				const { message, delay } = prepared.data;
+				return run(() => transport.send(queue, message, delay, enqueueOptions.maxAttempts ?? 5, enqueueOptions.dedupeKey, enqueueOptions.dedupe));
+			});
+		},
+		enqueueOnce(queue, payload, enqueueOptions) {
+			return AsyncResult.from(async () => {
+				const prepared = await prepareSend(queue, payload, enqueueOptions);
+				if (!prepared.ok) return prepared;
+				const { message, delay } = prepared.data;
+				return run(() => {
+					if (!transport.sendOnce) sqlOnly("enqueueOnce");
+					return transport.sendOnce(queue, message, delay, enqueueOptions.maxAttempts ?? 5, enqueueOptions.dedupeKey);
+				});
 			});
 		},
 		claim,
@@ -691,6 +1066,8 @@ function createJobs(source, queues, options = {}) {
 			schemaOf(queue);
 			return transport.retryDead(queue, retryOptions.ids, retryOptions.limit ?? 1e3);
 		}),
+		purge,
+		purgeJob: (purgeOptions) => async () => purge(purgeOptions).orThrow(),
 		replay: (queue, id) => run(() => {
 			if (!transport.replay) sqlOnly("replay");
 			return transport.replay(queue, id);
@@ -802,7 +1179,44 @@ function createJobs(source, queues, options = {}) {
 				return Response.json(result);
 			});
 		}
-	};
+	}, options.hooks, {
+		block: "jobs",
+		...options.logger ? { logger: options.logger } : {}
+	});
 }
 //#endregion
-export { assertCron, createIdempotency, createJobs, createRateLimit, createWebhookInbox, devDrain, devDrainSecret, nextCronRun, pgmqPublicBackend, rateLimited, sqlQueueBackend, withLease };
+//#region src/blocks/jobs/manifest.ts
+/** The `jobs` block's manifest (ADR 0029). */
+const jobsBlock = defineBlock({
+	name: "jobs",
+	sql: ["jobs"],
+	options: { jobs: jobsSqlOptions },
+	create: createJobs,
+	category: "automation",
+	recipes: ["job-runs-table"]
+});
+/** The `idempotency` block's manifest (ADR 0029). */
+const idempotencyBlock = defineBlock({
+	name: "idempotency",
+	sql: ["idempotency"],
+	create: createIdempotency,
+	category: "developer"
+});
+/** The `rate-limit` block's manifest (ADR 0029). */
+const rateLimitBlock = defineBlock({
+	name: "rate-limit",
+	sql: ["rate-limit"],
+	options: { "rate-limit": rateLimitSqlOptions },
+	create: createRateLimit,
+	category: "developer"
+});
+/** The `webhook-inbox` block's manifest (ADR 0029). */
+const webhookInboxBlock = defineBlock({
+	name: "webhook-inbox",
+	sql: ["webhook-inbox"],
+	options: { "webhook-inbox": webhookInboxSqlOptions },
+	create: createWebhookInbox,
+	category: "developer"
+});
+//#endregion
+export { assertCron, createIdempotency, createJobs, createRateLimit, createWebhookInbox, dbTransport, devDrain, devDrainSecret, idempotencyBlock, jobsBlock, nextCronRun, pgmqPublicBackend, purgeWebhookInbox, rateLimitBlock, rateLimited, rpcTransport, sqlQueueBackend, sqlTransport, transportQueueBackend, webhookInboxBlock, withLease };