experimental-a2 0.2.0 → 0.4.0

package/dist/scheduler-vercel.js

@@ -0,0 +1,226 @@
+import { f as classifySchedulerSendFailure, t as DRAIN_TIMINGS, u as assertSchedulerTargets, v as serverInternals } from "./internal-aEotMzu_.js";
+import { n as deliverSchedulerAppend } from "./server-CcNnFnoW.js";
+import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
+import { n as SYSTEM_CLOCK } from "./store-N8PXxDAS.js";
+import { t as normalizeSchedulerTask } from "./scheduler-task-BpzhPnRS.js";
+import { createHash } from "node:crypto";
+//#region src/scheduler-vercel.ts
+/**
+* experimental-a2/scheduler-vercel — queue-backed scheduler over Vercel Queues.
+*
+* `vercelQueues()` returns an `A2Scheduler` (a2-implementation.md §9):
+*
+* - drain tasks round the requested watchdog time up to a one-second slot.
+*   One message per `(topic, contract, session, dueAt)` coalesces appends,
+*   claim renewals and racing callbacks. `DuplicateMessageError` is
+*   success because that due-time slot is already durable.
+* - append tasks hash their stable task id with the topic for provider
+*   deduplication. Their six-day maximum delay leaves a full day for
+*   delivery and retries inside the provider's seven-day retention.
+*   They target the publishing deployment unless explicitly configured
+*   as deploymentless. Drain tasks always remain deployment-scoped.
+* - `handler(...servers)` is the delivery route: look up the server for
+*   the contract named in the message and drain it. Settled drains ack;
+*   contention arms a later watchdog before acking; handler failure keeps
+*   the current message and redelivers with backoff.
+*
+* `@vercel/queue` is an optional peer dependency, imported lazily. The
+* `transport` option is the injection seam — tests run a real little
+* in-memory queue through the same interface.
+*/
+/**
+* The "not settled yet" signal for a stalled handler — an expected state,
+* not a transport failure. The default transport classifies it in
+* `@vercel/queue`'s `retry` option and reschedules the delivery quietly
+* (`{ afterSeconds }` → visibility change → 200 response, no error log)
+* instead of letting it surface as a thrown 500. Busy deliveries use a
+* fresh watchdog instead. Custom transports should treat this class the
+* same way when their protocol has a polite reschedule.
+*/
+var DrainUnsettled = class extends Error {};
+/** Vercel Queues rejects shorter visibility changes. */
+const MIN_VISIBILITY_SECONDS = 30;
+/** Vercel Queues' maximum message retention and delivery delay. */
+const MAX_RETENTION_SECONDS = 604800;
+/** Leave the final retention day for delivery and retries. */
+const MAX_DELAY_SECONDS = 518400;
+const TOPIC_PATTERN = /^[A-Za-z0-9_-]+$/;
+const RETRYABLE_HTTP_CLIENT_STATUSES = /* @__PURE__ */ new Set([
+	408,
+	409,
+	425,
+	429
+]);
+/** The SDK's send path maps these statuses to name-only error instances. */
+const TERMINAL_VERCEL_SEND_ERROR_NAMES = /* @__PURE__ */ new Set([
+	"BadRequestError",
+	"UnauthorizedError",
+	"ForbiddenError"
+]);
+const recordOf = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+const httpStatusOf = (error) => {
+	try {
+		const record = recordOf(error);
+		if (!record) return void 0;
+		const response = recordOf(record["response"]);
+		const statuses = [
+			record["status"],
+			record["statusCode"],
+			response?.["status"]
+		].filter((value) => typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599);
+		const [status] = statuses;
+		if (status === void 0) return void 0;
+		return statuses.every((candidate) => candidate === status) ? status : void 0;
+	} catch {
+		return;
+	}
+};
+const errorNameOf = (error) => {
+	try {
+		const name = recordOf(error)?.["name"];
+		return typeof name === "string" ? name : void 0;
+	} catch {
+		return;
+	}
+};
+const classifyVercelSendFailure = (error) => {
+	const status = httpStatusOf(error);
+	const terminal = status === void 0 ? TERMINAL_VERCEL_SEND_ERROR_NAMES.has(errorNameOf(error) ?? "") : status >= 400 && status < 500 && !RETRYABLE_HTTP_CLIENT_STATUSES.has(status);
+	return classifySchedulerSendFailure(error, terminal ? "terminal" : "retryable");
+};
+const digestId = (parts) => `a2_${createHash("sha256").update(JSON.stringify(parts)).digest("hex")}`;
+/** Base of the unsettled redelivery backoff, doubled per delivery. */
+const UNSETTLED_BACKOFF_BASE_SECONDS = 5;
+/** Redelivery backoff for retry states: base, 2×, 4×… bounded. */
+const unsettledBackoffSeconds = (deliveryCount) => Math.min(Math.max(UNSETTLED_BACKOFF_BASE_SECONDS * 2 ** Math.max(deliveryCount - 1, 0), MIN_VISIBILITY_SECONDS), 60);
+const vercelQueueTransport = async () => {
+	const queue = await import("@vercel/queue").catch(() => {
+		throw classifySchedulerSendFailure(/* @__PURE__ */ new Error("experimental-a2/scheduler-vercel needs the '@vercel/queue' package (optional peer dependency) — install it, or inject a transport"), "terminal");
+	});
+	const deploymentClient = new queue.QueueClient();
+	const deploymentlessClient = new queue.QueueClient({ deploymentId: null });
+	return {
+		send: (topic, message, options, routing) => {
+			const deployment = routing?.deployment ?? "deployment";
+			const body = {
+				...message,
+				_a2Vercel: {
+					version: 1,
+					deployment
+				}
+			};
+			return (deployment === "deploymentless" ? deploymentlessClient : deploymentClient).send(topic, body, options);
+		},
+		handleCallback: (handler) => {
+			const callbackOptions = {
+				visibilityTimeoutSeconds: MIN_VISIBILITY_SECONDS,
+				retry: (error, metadata) => error instanceof DrainUnsettled ? { afterSeconds: unsettledBackoffSeconds(metadata.deliveryCount) } : void 0
+			};
+			const deploymentHandler = deploymentClient.handleCallback(handler, callbackOptions);
+			const deploymentlessHandler = deploymentlessClient.handleCallback(handler, callbackOptions);
+			return async (req) => {
+				let delivered;
+				try {
+					delivered = await req.clone().json();
+				} catch {
+					return deploymentlessHandler(req);
+				}
+				const metadata = recordOf(recordOf(delivered)?.["_a2Vercel"]);
+				return (metadata?.["version"] === 1 ? metadata["deployment"] : void 0) === "deployment" ? deploymentHandler(req) : deploymentlessHandler(req);
+			};
+		},
+		isDuplicate: (error) => error instanceof queue.DuplicateMessageError
+	};
+};
+function vercelQueues(options = {}) {
+	const topic = options.topic ?? "a2";
+	if (typeof topic !== "string" || !TOPIC_PATTERN.test(topic)) throw new TypeError("vercelQueues() topic must match [A-Za-z0-9_-]+");
+	const scheduledAppends = options.scheduledAppends ?? "deployment";
+	if (scheduledAppends !== "deployment" && scheduledAppends !== "deploymentless") throw new TypeError("vercelQueues() scheduledAppends must be 'deployment' or 'deploymentless'");
+	const clock = options.clock ?? SYSTEM_CLOCK;
+	const transport = retryableLazy(() => options.transport ? Promise.resolve(options.transport) : vercelQueueTransport()).get;
+	const sendTask = async (task) => {
+		const nowMs = clock.now().getTime();
+		const requestedDueAt = task.dueAt;
+		if (!Number.isFinite(requestedDueAt)) throw classifySchedulerSendFailure(/* @__PURE__ */ new TypeError("vercel scheduler dueAt must be a finite number"), "terminal");
+		const dueAt = requestedDueAt <= nowMs ? Math.floor(nowMs / 1e3) * 1e3 : Math.ceil(requestedDueAt / 1e3) * 1e3;
+		const deliveryTargetAt = task.kind === "append" ? requestedDueAt : dueAt;
+		const deliveryDelaySeconds = Math.max(0, Math.ceil((deliveryTargetAt - nowMs) / 1e3));
+		if (deliveryDelaySeconds > MAX_DELAY_SECONDS) throw classifySchedulerSendFailure(/* @__PURE__ */ new RangeError("vercelQueues() tasks cannot be delayed more than 6 days"), "terminal");
+		const deployment = task.kind === "append" ? scheduledAppends : "deployment";
+		const message = {
+			...task,
+			dueAt
+		};
+		const idempotencyKey = task.kind === "drain" ? digestId([
+			"a2:scheduler-vercel:drain:v1",
+			topic,
+			task.contract,
+			task.sessionId,
+			String(dueAt)
+		]) : digestId([
+			"a2:scheduler-vercel:append:v1",
+			topic,
+			task.id
+		]);
+		const t = await transport();
+		try {
+			await t.send(topic, message, {
+				delaySeconds: deliveryDelaySeconds,
+				idempotencyKey,
+				retentionSeconds: MAX_RETENTION_SECONDS
+			}, { deployment });
+		} catch (err) {
+			if (t.isDuplicate(err)) return;
+			throw classifyVercelSendFailure(err);
+		}
+	};
+	const successorDueAt = (message) => {
+		const minimumDueAt = clock.now().getTime() + DRAIN_TIMINGS.claimTtlMs + DRAIN_TIMINGS.watchdogGraceMs;
+		const beats = Math.max(1, Math.ceil((minimumDueAt - message.dueAt) / DRAIN_TIMINGS.claimHeartbeatMs));
+		return message.dueAt + beats * DRAIN_TIMINGS.claimHeartbeatMs;
+	};
+	return {
+		async schedule(task) {
+			await sendTask(task);
+		},
+		handler(...servers) {
+			assertSchedulerTargets(servers, { allowStructural: true });
+			const byContract = /* @__PURE__ */ new Map();
+			for (const server of servers) byContract.set(server.contract.name, server);
+			return async (req) => {
+				return (await transport()).handleCallback(async (delivered) => {
+					const task = normalizeSchedulerTask(delivered);
+					if (!task) throw new TypeError("a2 scheduler received an invalid task");
+					const server = byContract.get(task.contract);
+					if (!server) throw new Error(`a2 scheduler: no server for contract '${task.contract}' — pass it to schedulerHandler(...)`);
+					const internals = serverInternals.get(server);
+					if (task.kind === "append") {
+						await deliverSchedulerAppend(server, task);
+						return;
+					}
+					const nextDueAt = successorDueAt(task);
+					const result = internals ? await internals.schedulerDrain(task.sessionId, { watchdogDueAt: nextDueAt }) : {
+						...await server.drain(task.sessionId),
+						outcome: "unknown"
+					};
+					if (result.settled) return;
+					if (result.outcome === "busy") {
+						if (result.schedulerArm) await result.schedulerArm;
+						else await sendTask({
+							version: 1,
+							kind: "drain",
+							contract: task.contract,
+							sessionId: task.sessionId,
+							dueAt: nextDueAt
+						});
+						return;
+					}
+					throw new DrainUnsettled(`a2 scheduler: session '${task.sessionId}' of '${task.contract}' not settled yet (${result.outcome}) — rescheduled for redelivery`);
+				})(req);
+			};
+		}
+	};
+}
+//#endregion
+export { DrainUnsettled, vercelQueues };