better-supabase 0.5.0 → 0.6.0

package/dist/blocks/jobs/index.js

@@ -0,0 +1,1051 @@
+import { t as DbException } from "../../db-exception-CnWcYPxL.js";
+import { n as dbError } from "../../errors-B11Duf73.js";
+import { s as nowInstant } from "../../temporal-BJGitm-h.js";
+import { t as temporal } from "../../temporal-required-BVvW7SYJ.js";
+import { a as ok, r as err, s as toDbError, t as AsyncResult } from "../../result-DzUbqgdW.js";
+import { n as allTenantsContext } from "../../plugin-tfXW1-qO.js";
+import { n as validate } from "../../standard-BK0cqJ7y.js";
+import { a as problemResponse } from "../../problem-BreOl8b8.js";
+import { o as tenantFrom, s as tenantPathsFor } from "../../claims-PqzCxaTD.js";
+import { n as nextCronRun, t as assertCron } from "../../cron-DVPUg5k3.js";
+import { A as workerId, C as run, E as sleep, c as errorText, d as isRecord, g as pageOf, i as blockCall, k as toInstant, n as applyTemporal, v as readBodyCapped, w as seconds } from "../../block-helpers-DWHxHsEQ.js";
+import { d as verifyWebhook, l as verifySharedSecret } from "../../verify-DL41hbvY.js";
+import { n as withContext, t as unwrap } from "../../envelope-DqnYGRw7.js";
+//#region src/blocks/jobs/dev.ts
+function devDrainSecret(env, name = "CRON_SECRET") {
+	const current = env[name];
+	if (current) return current;
+	const bytes = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(32));
+	const secret = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+	env[name] = secret;
+	return secret;
+}
+function devDrain(options) {
+	if (!options.secret) throw new TypeError("devDrain needs the drain route's secret, such as devDrainSecret(process.env)");
+	const every = options.every ?? 6e4;
+	if (!Number.isFinite(every) || every <= 0) throw new TypeError("devDrain: every must be a positive number of ms");
+	const doFetch = options.fetch ?? fetch;
+	const report = options.onError ?? ((message) => {
+		console.warn(message);
+	});
+	let running = false;
+	const tick = async () => {
+		if (running || options.signal?.aborted) return;
+		running = true;
+		try {
+			const response = await doFetch(options.url, { headers: { authorization: `Bearer ${options.secret}` } });
+			await response.body?.cancel();
+			if (!response.ok) report(`[jobs] dev drain answered ${String(response.status)}`);
+		} catch (cause) {
+			report(`[jobs] dev drain failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+		} finally {
+			running = false;
+		}
+	};
+	const timer = setInterval(() => {
+		tick();
+	}, every);
+	const stop = () => {
+		clearInterval(timer);
+	};
+	options.signal?.addEventListener("abort", stop, { once: true });
+	return {
+		tick,
+		stop
+	};
+}
+//#endregion
+//#region src/blocks/jobs/jobs.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;
+		}
+	};
+}
+/**
+* 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
+			]);
+		}
+	});
+}
+function defaultType(payload) {
+	if (typeof payload !== "object" || payload === null) return null;
+	const type = payload.type;
+	return typeof type === "string" ? type : null;
+}
+/** Store-then-process webhooks: acknowledge fast, process with retries, never twice. */
+function createWebhookInbox(sql, options) {
+	applyTemporal(options);
+	const worker = options.worker ?? workerId();
+	const format = options.problem;
+	const maxAttempts = options.maxAttempts ?? 8;
+	if (!Number.isInteger(maxAttempts) || maxAttempts < 1) throw new TypeError(`createWebhookInbox maxAttempts must be a positive integer, not ${String(maxAttempts)}`);
+	const maxBodyBytes = options.maxBodyBytes ?? 1048576;
+	if (!Number.isInteger(maxBodyBytes) || maxBodyBytes < 1) throw new TypeError(`createWebhookInbox maxBodyBytes must be a positive integer, not ${String(maxBodyBytes)}`);
+	const verified = async (request, body) => {
+		if (options.verify) return options.verify(request, body);
+		const result = await verifyWebhook({
+			headers: request.headers,
+			body
+		}, options.secrets ?? []);
+		return result.ok ? ok({
+			id: result.data.id,
+			payload: result.data.payload
+		}) : result;
+	};
+	const save = (event) => run(async () => {
+		const [row] = await sql.queryRaw("select * from better_supabase.receive_webhook($1, $2, $3, $4, $5, $6, $7)", [
+			options.source,
+			event.id,
+			event.type === void 0 ? (options.typeOf ?? defaultType)(event.payload) : event.type,
+			JSON.stringify(event.payload),
+			JSON.stringify(event.headers ?? {}),
+			(event.tenant === void 0 ? options.tenantOf?.(event.payload) : event.tenant) ?? null,
+			maxAttempts
+		]);
+		return {
+			id: Number(row.id),
+			duplicate: row.duplicate
+		};
+	});
+	return {
+		store: save,
+		list: (listOptions) => run(async () => {
+			return (await sql.queryRaw("select * from better_supabase.list_webhooks($1, $2, $3, $4)", [
+				listOptions.tenant,
+				options.source,
+				listOptions.status ?? null,
+				listOptions.limit ?? 100
+			])).map((row) => ({
+				id: Number(row.id),
+				messageId: row.message_id,
+				type: row.event_type,
+				status: row.status ?? "pending",
+				attempts: row.attempts,
+				maxAttempts: row.max_attempts ?? maxAttempts,
+				lastError: row.last_error ?? null,
+				tenant: row.tenant ?? null,
+				receivedAt: toInstant(row.received_at),
+				processedAt: row.processed_at === null || row.processed_at === void 0 ? null : toInstant(row.processed_at)
+			}));
+		}),
+		purge: (purgeOptions = {}) => run(async () => {
+			const [row] = await sql.queryRaw("select better_supabase.purge_webhooks($1::interval, $2, $3, $4) as purged", [
+				seconds(purgeOptions.olderThan ?? "30 days"),
+				purgeOptions.includeDead ?? false,
+				purgeOptions.batch ?? 1e4,
+				purgeOptions.tenant ?? null
+			]);
+			return row?.purged ?? 0;
+		}),
+		async receive(request) {
+			const instance = new URL(request.url).pathname;
+			if (request.method !== "POST") return new Response(null, {
+				status: 405,
+				headers: { allow: "POST" }
+			});
+			if (!options.verify && !options.secrets) throw new TypeError(`The inbox for "${options.source}" has no \`secrets\` or \`verify\`, so it only stores events through \`store\``);
+			const body = await readBodyCapped(request.clone(), maxBodyBytes);
+			if (body === void 0) return problemResponse({
+				...dbError("invalid_input", "The body is too large", { code: "WEBHOOK_TOO_LARGE" }),
+				status: 413
+			}, {
+				instance,
+				format
+			});
+			const message = await verified(request, body);
+			if (!message.ok) return problemResponse(message.error, {
+				instance,
+				format
+			});
+			const headers = Object.fromEntries((options.keepHeaders ?? []).flatMap((name) => {
+				const value = request.headers.get(name);
+				return value === null ? [] : [[name.toLowerCase(), value]];
+			}));
+			const stored = await save({
+				id: message.data.id,
+				payload: message.data.payload,
+				headers,
+				...message.data.tenant === void 0 ? {} : { tenant: message.data.tenant }
+			});
+			if (!stored.ok) return problemResponse(stored.error, {
+				instance,
+				format
+			});
+			return Response.json(stored.data, { status: stored.data.duplicate ? 200 : 202 });
+		},
+		async process(handler, processOptions = {}) {
+			let succeeded = 0;
+			let failed = 0;
+			const lease = seconds(processOptions.lease ?? 300);
+			const deadline = processOptions.budgetMs === void 0 ? void 0 : Date.now() + processOptions.budgetMs;
+			for (;;) {
+				if (deadline !== void 0 && Date.now() >= deadline) return {
+					succeeded,
+					failed
+				};
+				const rows = await sql.queryRaw("select * from better_supabase.claim_webhooks($1, $2, $3, $4::interval)", [
+					options.source,
+					worker,
+					processOptions.batch ?? 10,
+					lease
+				]);
+				if (rows.length === 0) return {
+					succeeded,
+					failed
+				};
+				for (const row of rows) {
+					const id = Number(row.id);
+					const attempt = row.attempts;
+					const extend = async () => {
+						const [held] = await sql.queryRaw("select better_supabase.extend_webhook($1, $2, $3, $4::interval) as lease", [
+							id,
+							worker,
+							attempt,
+							lease
+						]);
+						return held?.lease ?? void 0;
+					};
+					const leaseSeconds = await extend();
+					if (leaseSeconds === void 0) continue;
+					const message = {
+						id,
+						source: row.source,
+						messageId: row.message_id,
+						type: row.event_type,
+						payload: row.payload,
+						headers: row.headers,
+						attempts: row.attempts,
+						maxAttempts: row.max_attempts ?? maxAttempts,
+						receivedAt: toInstant(row.received_at),
+						tenant: row.tenant ?? null,
+						progress: row.checkpoint ?? {},
+						async checkpoint(fields) {
+							const [saved] = await sql.queryRaw("select better_supabase.checkpoint_webhook($1, $2, $3, $4) as saved", [
+								id,
+								worker,
+								JSON.stringify(fields),
+								attempt
+							]);
+							return saved?.saved ?? false;
+						}
+					};
+					const heartbeat = setInterval(() => void extend().catch(() => void 0), Math.max(1e3, leaseSeconds * 500));
+					try {
+						const outcome = await handler(message);
+						if (typeof outcome === "object" && outcome !== null && "ok" in outcome && outcome.ok === false) throw new Error(errorText(outcome.error ?? "The handler failed"));
+						const [done] = await sql.queryRaw("select better_supabase.complete_webhook($1, $2, $3) as done", [
+							message.id,
+							worker,
+							attempt
+						]);
+						if (done?.done !== false) succeeded += 1;
+					} catch (cause) {
+						await sql.queryRaw("select better_supabase.fail_webhook($1, $2, $3, null, $4)", [
+							message.id,
+							worker,
+							errorText(cause),
+							attempt
+						]);
+						failed += 1;
+					} finally {
+						clearInterval(heartbeat);
+					}
+				}
+			}
+		}
+	};
+}
+//#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. */
+const millis = (instant) => instant.round({
+	smallestUnit: "millisecond",
+	roundingMode: "floor"
+});
+/** The first run of a schedule written without one, or undefined for a cron the drain can't read. */
+function firstRun(row) {
+	try {
+		return millis(nextCronRun(row.schedule, row.timezone, row.first_after ? toInstant(row.first_after) : nowInstant()));
+	} catch {
+		return;
+	}
+}
+/**
+* The `jobs` SQL module over a service SQL connection. The same
+* functions back both `sql.modules.jobs.options.backend` values (pgmq and table)
+* and both schedulers.
+*/
+function sqlQueueBackend(sql) {
+	return {
+		apiVersion: 1,
+		name: "sql",
+		leases: true,
+		async send(queue, payload, delay, maxAttempts, dedupeKey, dedupe) {
+			const [row] = await sql.queryRaw("select better_supabase.enqueue_job($1, $2, $3, $4, $5, $6) as id", [
+				queue,
+				JSON.stringify(payload ?? {}),
+				delay,
+				maxAttempts,
+				dedupeKey ?? null,
+				dedupe !== "waiting"
+			]);
+			return Number(row.id);
+		},
+		read: (queue, lease, batch) => sql.queryRaw("select * from better_supabase.claim_jobs($1, $2, $3)", [
+			queue,
+			lease,
+			batch
+		]),
+		async complete(job) {
+			const [row] = await sql.queryRaw("select better_supabase.complete_job($1, $2, $3) as done", [
+				job.queue,
+				job.id,
+				job.attempts
+			]);
+			return row?.done ?? false;
+		},
+		async fail(job, error, retryIn) {
+			const [row] = await sql.queryRaw("select better_supabase.fail_job($1, $2, $3, $4, $5) as status", [
+				job.queue,
+				job.id,
+				job.attempts,
+				error,
+				retryIn ?? null
+			]);
+			return row?.status ?? null;
+		},
+		async extend(job, lease) {
+			const [row] = await sql.queryRaw("select better_supabase.extend_job_lease($1, $2, $3, $4) as extended", [
+				job.queue,
+				job.id,
+				job.attempts,
+				lease
+			]);
+			return row?.extended ?? false;
+		},
+		async replay(queue, id) {
+			const [row] = await sql.queryRaw("select better_supabase.replay_dead_job($1, $2) as id", [queue, id]);
+			return row?.id === null || row?.id === void 0 ? null : Number(row.id);
+		},
+		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)
+			};
+		},
+		listDead: (queue, limit, before) => sql.queryRaw("select * from better_supabase.list_dead_jobs($1, $2, $3)", [
+			queue,
+			limit,
+			before ?? null
+		]),
+		async retryDead(queue, ids, limit) {
+			const [row] = await sql.queryRaw("select better_supabase.retry_dead_jobs($1, $2, $3) as retried", [
+				queue,
+				ids === void 0 ? null : [...ids],
+				limit
+			]);
+			return row?.retried ?? 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,
+				cron,
+				queue,
+				JSON.stringify(payload ?? {}),
+				timeZone,
+				nextRun.toString(),
+				tenant ?? null
+			]);
+		},
+		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)
+			}));
+		},
+		async unscheduleTenant(tenant) {
+			const [row] = await sql.queryRaw("select better_supabase.unschedule_tenant($1) as removed", [tenant]);
+			return row?.removed ?? 0;
+		},
+		async unschedule(name) {
+			const [row] = await sql.queryRaw("select better_supabase.unschedule_job($1) as done", [name]);
+			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);
+				if (first === void 0) continue;
+				if (temporal().Instant.compare(first, nowInstant()) <= 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;
+		},
+		async advanceSchedule(name, ran, next) {
+			const [row] = await sql.queryRaw("select better_supabase.advance_schedule($1, $2, $3) as advanced", [
+				name,
+				ran.toString(),
+				next.toString()
+			]);
+			return row?.advanced ?? false;
+		}
+	};
+}
+/** 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`));
+}
+/**
+* Supabase's `pgmq_public` RPCs (Integrations, Queues, "Expose Queues via
+* PostgREST"). No lease check on complete, no retry delay, no deduplication
+* and no schedules: a failed job reappears when its lease ends.
+*/
+function pgmqPublicBackend(client) {
+	const untyped = client;
+	const call = async (fn, args) => {
+		const { data, error } = await untyped.schema("pgmq_public").rpc(fn, args);
+		if (error) {
+			const message = typeof error === "object" && "message" in error ? String(error.message) : String(error);
+			throw new Error(`pgmq_public.${fn}: ${message}`, { cause: error });
+		}
+		return data;
+	};
+	const archive = (job) => call("archive", {
+		queue_name: job.queue,
+		message_id: job.id
+	});
+	return {
+		apiVersion: 1,
+		name: "pgmq_public",
+		leases: false,
+		async send(queue, payload, delay, maxAttempts, dedupeKey) {
+			if (dedupeKey !== void 0) sqlOnly("dedupeKey");
+			const ids = await call("send", {
+				queue_name: queue,
+				message: {
+					payload: payload ?? {},
+					max_attempts: maxAttempts
+				},
+				sleep_seconds: delay
+			});
+			return Number(ids[0]);
+		},
+		async read(queue, lease, batch) {
+			const rows = await call("read", {
+				queue_name: queue,
+				sleep_seconds: lease,
+				n: batch
+			});
+			const live = [];
+			for (const row of rows) if (row.read_ct > (row.message?.max_attempts ?? 5)) await 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,
+				enqueued_at: row.enqueued_at,
+				visible_until: row.vt,
+				message: row.message
+			}));
+		},
+		complete: archive,
+		async fail(job) {
+			if (job.attempts < job.maxAttempts) return "queued";
+			await archive(job);
+			return "dead";
+		},
+		extend: () => Promise.resolve(false),
+		schedule: () => sqlOnly("schedule"),
+		unschedule: () => sqlOnly("unschedule")
+	};
+}
+//#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;
+const TRANSIENT = /* @__PURE__ */ new Set([
+	"network",
+	"timeout",
+	"serialization",
+	"rate_limited"
+]);
+function toJob(queue, row) {
+	const message = row.message ?? {};
+	const { payload, context } = unwrap(message.payload);
+	return {
+		id: Number(row.id),
+		queue,
+		payload,
+		context,
+		attempts: row.attempts,
+		maxAttempts: message.max_attempts ?? 5,
+		enqueuedAt: toInstant(row.enqueued_at),
+		visibleUntil: toInstant(row.visible_until),
+		lastError: message.last_error ?? null
+	};
+}
+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";
+}
+function backendOf(source) {
+	if (isBackend(source)) return source;
+	return isSqlClient(source) ? sqlQueueBackend(source) : pgmqPublicBackend(source);
+}
+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.
+*/
+function createJobs(source, queues, options = {}) {
+	applyTemporal(options);
+	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);
+	const schemaOf = (queue) => {
+		const schema = queues[queue];
+		if (!schema) throw new TypeError(`Unknown queue "${queue}". Queues: ${Object.keys(queues).join(", ")}`);
+		return schema;
+	};
+	const complete = (job) => run(() => transport.complete(job));
+	const fail = (job, error, failOptions = {}) => run(() => transport.fail(job, errorText(error), failOptions.retryIn));
+	const claim = (queue, claimOptions = {}) => run(async () => {
+		schemaOf(queue);
+		return (await transport.read(queue, claimOptions.lease ?? 300, claimOptions.batch ?? 1)).map((row) => toJob(queue, row));
+	});
+	/**
+	* 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.
+	*/
+	const heartbeat = (held, lease) => transport.leases ? setInterval(() => {
+		for (const job of held) run(() => transport.extend(job, lease));
+	}, Math.max(1e3, lease * 1e3 / 2)) : void 0;
+	const handle = async (job, handler, workOptions) => {
+		const controller = new AbortController();
+		try {
+			const payload = await validate(schemaOf(job.queue), job.payload, "payload");
+			if (!payload.ok) {
+				await fail(job, payload.error.message);
+				workOptions.onError?.(payload.error, job);
+				return false;
+			}
+			const context = workOptions.allTenants && job.context.tenant === void 0 ? allTenantsContext(job.context) : job.context;
+			const outcome = await handler(payload.data, {
+				...job,
+				payload: payload.data,
+				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;
+		} catch (cause) {
+			controller.abort();
+			await fail(job, cause);
+			workOptions.onError?.(typeof cause === "object" && cause !== null && "kind" in cause ? cause : toDbError(cause), job);
+			return false;
+		}
+	};
+	const loop = async (queue, handler, workOptions, forever, deadline) => {
+		const concurrency = Math.max(1, workOptions.concurrency ?? 1);
+		const lease = workOptions.lease ?? 300;
+		const firstWait = workOptions.pollInterval ?? 1e3;
+		const maxWait = Math.max(firstWait, workOptions.maxPollInterval ?? 3e4);
+		let succeeded = 0;
+		let failed = 0;
+		const stop = new AbortController();
+		const signal = workOptions.signal ? AbortSignal.any([workOptions.signal, stop.signal]) : stop.signal;
+		const lanes = Array.from({ length: concurrency }, async () => {
+			let wait = firstWait;
+			let misses = 0;
+			while (!signal.aborted) {
+				if (deadline !== void 0 && Date.now() >= deadline) return;
+				const claimed = await claim(queue, {
+					...workOptions,
+					batch: workOptions.batch ?? 1
+				});
+				if (!claimed.ok) {
+					misses += 1;
+					if (misses > CLAIM_RETRIES || !TRANSIENT.has(claimed.error.kind)) {
+						stop.abort();
+						throw new TypeError(claimed.error.message, { cause: claimed.error });
+					}
+					const left = deadline === void 0 ? Infinity : deadline - Date.now();
+					await sleep(Math.min(firstWait * 2 ** (misses - 1), left), signal);
+					continue;
+				}
+				misses = 0;
+				if (claimed.data.length === 0) {
+					if (!forever) return;
+					await sleep(wait, signal);
+					wait = Math.min(maxWait, wait * 2);
+					continue;
+				}
+				wait = firstWait;
+				const held = new Set(claimed.data);
+				const timer = heartbeat(held, lease);
+				try {
+					for (const job of claimed.data) {
+						if (await handle(job, handler, workOptions)) succeeded += 1;
+						else failed += 1;
+						held.delete(job);
+					}
+				} finally {
+					clearInterval(timer);
+				}
+			}
+		});
+		const settled = await Promise.allSettled(lanes);
+		for (const lane of settled) if (lane.status === "rejected") throw lane.reason;
+		return {
+			succeeded,
+			failed
+		};
+	};
+	const runSchedules = async (scheduleOptions) => {
+		if (!transport.dueSchedules || !transport.advanceSchedule) return 0;
+		const due = await transport.dueSchedules(scheduleOptions.lease ?? 60, scheduleOptions.batch ?? 100);
+		let ran = 0;
+		for (const schedule of due) {
+			await transport.send(schedule.queue, schedule.payload, 0, 5, `schedule:${schedule.name}:${schedule.nextRun.toString()}`);
+			const next = millis(nextCronRun(schedule.cron, schedule.timeZone, later(nowInstant(), schedule.nextRun)));
+			if (await transport.advanceSchedule(schedule.name, schedule.nextRun, next)) ran += 1;
+		}
+		return ran;
+	};
+	const prepare = async (name, cron, queue, payload, scheduleOptions, tenantDefault) => {
+		const valid = await validate(schemaOf(queue), payload, "payload");
+		if (!valid.ok) return valid;
+		const timeZone = scheduleOptions.timeZone ?? "UTC";
+		try {
+			nextCronRun(cron, timeZone, nowInstant());
+		} catch (cause) {
+			return err(dbError("validation", errorText(cause), { issues: [{
+				message: errorText(cause),
+				path: [name, "cron"]
+			}] }));
+		}
+		return ok({
+			name,
+			cron,
+			queue,
+			payload: withContext(valid.data, scheduleOptions.context),
+			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, nowInstant())), prepared.tenant);
+	return {
+		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 - nowInstant().epochMilliseconds) / 1e3)) : 0);
+				return run(() => transport.send(queue, withContext(valid.data, enqueueOptions.context), delay, enqueueOptions.maxAttempts ?? 5, enqueueOptions.dedupeKey, enqueueOptions.dedupe));
+			});
+		},
+		claim,
+		complete,
+		fail,
+		extend: (job, lease) => run(() => transport.extend(job, lease)),
+		stats: (names) => run(async () => {
+			const stats = (queue) => transport.stats?.(queue) ?? sqlOnly("stats");
+			const list = names ?? Object.keys(queues);
+			const entries = await Promise.all(list.map(async (queue) => {
+				schemaOf(queue);
+				return [queue, await stats(queue)];
+			}));
+			return Object.fromEntries(entries);
+		}),
+		listDead: (queue, listOptions = {}) => run(async () => {
+			if (!transport.listDead) sqlOnly("listDead");
+			schemaOf(queue);
+			return (await transport.listDead(queue, listOptions.limit ?? 100, pageOf(listOptions).cursor)).map((row) => {
+				const message = row.message ?? {};
+				const { payload, context } = unwrap(message.payload);
+				return {
+					id: Number(row.id),
+					queue,
+					payload,
+					context,
+					attempts: row.attempts,
+					maxAttempts: message.max_attempts ?? 5,
+					lastError: message.last_error ?? null,
+					enqueuedAt: toInstant(row.enqueued_at),
+					diedAt: row.died_at === null ? null : toInstant(row.died_at)
+				};
+			});
+		}),
+		retryDead: (queue, retryOptions = {}) => run(async () => {
+			if (!transport.retryDead) sqlOnly("retryDead");
+			schemaOf(queue);
+			return transport.retryDead(queue, retryOptions.ids, retryOptions.limit ?? 1e3);
+		}),
+		replay: (queue, id) => run(() => {
+			if (!transport.replay) sqlOnly("replay");
+			return transport.replay(queue, id);
+		}),
+		schedule(name, cron, queue, payload, scheduleOptions = {}) {
+			return AsyncResult.from(async () => {
+				const prepared = await prepare(name, cron, queue, payload, scheduleOptions);
+				if (!prepared.ok) return prepared;
+				return run(() => write(prepared.data));
+			});
+		},
+		unschedule: (name) => run(() => transport.unschedule(name)),
+		ensureSchedules(definitions, ensureOptions) {
+			return AsyncResult.from(async () => {
+				const { prefix, tenant } = ensureOptions;
+				if (prefix.length === 0) return err(dbError("invalid_request", "ensureSchedules needs a non-empty prefix"));
+				const names = /* @__PURE__ */ new Set();
+				const prepared = [];
+				for (const definition of definitions) {
+					if (!definition.name.startsWith(prefix) || names.has(definition.name)) return err(dbError("invalid_request", names.has(definition.name) ? `Schedule "${definition.name}" is defined twice` : `Schedule "${definition.name}" does not start with "${prefix}"`));
+					names.add(definition.name);
+					const ready = await prepare(definition.name, definition.cron, definition.queue, definition.payload, definition, tenant);
+					if (!ready.ok) return ready;
+					prepared.push(ready.data);
+				}
+				return run(async () => {
+					if (!transport.listSchedules) sqlOnly("ensureSchedules");
+					const existing = await transport.listSchedules({
+						prefix,
+						...tenant === void 0 ? {} : { tenant }
+					});
+					for (const schedule of prepared) await write(schedule);
+					const removed = [];
+					for (const schedule of existing) {
+						if (names.has(schedule.name)) continue;
+						if (await transport.unschedule(schedule.name)) removed.push(schedule.name);
+					}
+					return {
+						scheduled: [...names],
+						removed
+					};
+				});
+			});
+		},
+		listSchedules: (filter = {}) => run(async () => {
+			if (!transport.listSchedules) sqlOnly("listSchedules");
+			return [...await transport.listSchedules(filter)];
+		}),
+		unscheduleAll: (filter) => run(() => {
+			if (!transport.unscheduleTenant) sqlOnly("unscheduleAll");
+			return transport.unscheduleTenant(filter.tenant);
+		}),
+		runSchedules: (scheduleOptions = {}) => run(() => runSchedules(scheduleOptions)),
+		drain: (queue, handler, drainOptions = {}) => loop(queue, handler, drainOptions, false, drainOptions.budgetMs === void 0 ? void 0 : Date.now() + drainOptions.budgetMs),
+		work: (queue, handler, workOptions = {}) => loop(queue, handler, workOptions, true),
+		drainRoute(routeOptions) {
+			const secret = routeOptions.secret;
+			if (!secret) throw new TypeError("drainRoute needs a secret, such as process.env.CRON_SECRET");
+			for (const queue of Object.keys(routeOptions.handlers)) schemaOf(queue);
+			return async (request) => {
+				const instance = new URL(request.url).pathname;
+				if (request.method !== "GET" && request.method !== "POST") return new Response(null, {
+					status: 405,
+					headers: { allow: "GET, POST" }
+				});
+				if (!verifySharedSecret(request, secret)) return problemResponse(dbError("unauthorized", "The drain route needs its bearer secret"), {
+					instance,
+					format: routeOptions.problem
+				});
+				const deadline = Date.now() + (routeOptions.budgetMs ?? 5e4);
+				const monitor = routeOptions.monitor;
+				let errors = 0;
+				const report = (cause) => {
+					errors += 1;
+					routeOptions.onError?.(toDbError(cause));
+				};
+				const watch = async (fn) => {
+					try {
+						return await fn();
+					} catch (cause) {
+						routeOptions.onError?.(toDbError(cause));
+						return;
+					}
+				};
+				const started = monitor?.onStart ? await watch(() => monitor.onStart?.(request)) : void 0;
+				let scheduled = 0;
+				if (routeOptions.schedules ?? true) {
+					const ran = await run(() => runSchedules({}));
+					if (ran.ok) scheduled = ran.data;
+					else {
+						errors += 1;
+						routeOptions.onError?.(ran.error);
+					}
+				}
+				const results = {};
+				for (const [queue, handler] of Object.entries(routeOptions.handlers)) {
+					if (handler === void 0) continue;
+					if (Date.now() >= deadline) break;
+					try {
+						results[queue] = await loop(queue, handler, routeOptions, false, deadline);
+					} catch (cause) {
+						report(cause);
+						results[queue] = {
+							succeeded: 0,
+							failed: 0
+						};
+					}
+				}
+				const result = {
+					schedules: scheduled,
+					queues: results,
+					budgetExhausted: Date.now() >= deadline,
+					errors
+				};
+				if (monitor?.onFinish) await watch(() => monitor.onFinish?.(result, started));
+				return Response.json(result);
+			};
+		}
+	};
+}
+//#endregion
+//#region src/blocks/jobs/rate-limit.ts
+const isTransport = (source) => "call" in source;
+/**
+* Fixed-window limits for keys that aren't claims, over the `rate-limit`
+* module's counters. Pass a service SQL connection (`ctx.postgresAdmin`,
+* `postgres.admin`), or a service-role `BlockTransport` such as
+* `rpcTransport(adminClient)`.
+*/
+function createRateLimit(source, options = {}) {
+	applyTemporal(options);
+	const hit = isTransport(source) ? overTransport(blockCall(source, void 0, options.mappers)) : overSql(source);
+	return { check: (scope, key, rule) => {
+		if (rule !== void 0 && (!Number.isInteger(rule.max) || rule.max < 1)) return AsyncResult.err(dbError("invalid_input", "A rate limit's max must be a positive integer"));
+		return hit(scope, key, rule?.max ?? null, rule === void 0 ? null : seconds(rule.period));
+	} };
+}
+const overTransport = (call) => (scope, key, max, period) => call("check_rate_limit", {
+	scope,
+	key,
+	max_requests: max ?? void 0,
+	period: period ?? void 0
+}, (value) => {
+	const row = isRecord(value) ? value : {};
+	return {
+		allowed: row["allowed"] === true,
+		remaining: Number(row["remaining"] ?? 0),
+		retryAfter: Number(row["retry_after"] ?? 0)
+	};
+});
+const overSql = (sql) => (scope, key, max, period) => run(async () => {
+	const [row] = await sql.queryRaw("select * from better_supabase.hit_rate_limit($1, $2, $3, $4::interval)", [
+		scope,
+		key,
+		max,
+		period
+	]);
+	return {
+		allowed: row?.allowed ?? false,
+		remaining: row?.remaining ?? 0,
+		retryAfter: row?.retry_after ?? 0
+	};
+});
+/** A `problem+json` 429 with `Retry-After`, for a refused `check`. */
+function rateLimited(decision, options = {}) {
+	const retryAfter = Math.max(1, Math.ceil(decision.retryAfter));
+	return problemResponse(dbError("rate_limited", options.detail ?? `Too many requests. Retry after ${retryAfter} seconds.`, { retryAfter }), {
+		...options.instance === void 0 ? {} : { instance: options.instance },
+		format: options.problem
+	});
+}
+//#endregion
+export { assertCron, createIdempotency, createJobs, createRateLimit, createWebhookInbox, devDrain, devDrainSecret, nextCronRun, pgmqPublicBackend, rateLimited, sqlQueueBackend, withLease };