experimental-a2 0.0.0

package/dist/recovery-vercel.d.ts

@@ -0,0 +1,60 @@
+import { i as Clock } from "./log-Dg1I8NRr.js";
+import { A2Recovery } from "./server.js";
+//#region src/recovery-vercel.d.ts
+/**
+ * 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.
+ */
+declare class RecoveryUnsettled extends Error {}
+/** The message a2 puts on the queue. Application state lives in the log. */
+type RecoveryMessage = {
+  contract: string;
+  sessionId: string;
+  /** Whole-second epoch time this watchdog was scheduled to become visible. */
+  dueAt?: number;
+};
+type QueueDeliveryMetadata = {
+  messageId: string;
+  deliveryCount: number;
+};
+/**
+ * What this module needs from a queue — `@vercel/queue`'s `send` and
+ * `handleCallback` match it structurally.
+ */
+type QueueTransport = {
+  send(topic: string, message: RecoveryMessage, options?: {
+    delaySeconds?: number;
+    idempotencyKey?: string;
+  }): Promise<unknown>;
+  /**
+   * Wrap the delivery handler into a route. The handler throws
+   * `RecoveryUnsettled` when the session needs redelivery — transports
+   * with a polite reschedule (visibility change) should use it there
+   * instead of surfacing an error; anything else thrown is a genuine
+   * failure and should stay loud.
+   */
+  handleCallback(handler: (message: RecoveryMessage, metadata: QueueDeliveryMetadata) => Promise<void>): (req: Request) => Promise<Response>;
+  /** Is this send error the idempotency-key collision? (= success) */
+  isDuplicate(error: unknown): boolean;
+};
+type VercelQueuesOptions = {
+  /** Queue topic. One topic serves every contract. Default `'a2'`. */
+  topic?: string;
+  /**
+   * Fallback delay when an arm does not supply an absolute due time.
+   * Core A2 arms lease windows explicitly. Default 5.
+   */
+  delaySeconds?: number;
+  /** Injectable transport (tests). Default: `@vercel/queue`. */
+  transport?: QueueTransport;
+  /** Injectable clock for due-time calculations (tests). */
+  clock?: Clock;
+};
+declare function vercelQueues(options?: VercelQueuesOptions): A2Recovery;
+//#endregion
+export { QueueDeliveryMetadata, QueueTransport, RecoveryMessage, RecoveryUnsettled, VercelQueuesOptions, vercelQueues };

package/dist/recovery-vercel.js

@@ -0,0 +1,120 @@
+import { i as serverInternals, t as DRAIN_TIMINGS } from "./internal-Dm8Ejnud.js";
+import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
+import { n as SYSTEM_CLOCK } from "./log-yJbXUf72.js";
+//#region src/recovery-vercel.ts
+/**
+* a2/recovery-vercel — queue-backed recovery over Vercel Queues.
+*
+* `vercelQueues()` returns an `A2Recovery` (a2-implementation.md §9):
+*
+* - `arm` rounds the requested watchdog time up to a one-second slot.
+*   One message per `(contract, session, dueAt)` coalesces appends,
+*   lease renewals, and racing callbacks. `DuplicateMessageError` is
+*   success because that due-time slot is already durable.
+* - `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 RecoveryUnsettled = class extends Error {};
+/** Vercel Queues rejects shorter visibility changes. */
+const MIN_VISIBILITY_SECONDS = 30;
+/** Redelivery backoff for retry states: base, 2×, 4×… bounded. */
+const unsettledBackoffSeconds = (delaySeconds, deliveryCount) => Math.min(Math.max(delaySeconds * 2 ** Math.max(deliveryCount - 1, 0), MIN_VISIBILITY_SECONDS), 60);
+const vercelQueueTransport = async (delaySeconds) => {
+	const queue = await import("@vercel/queue").catch(() => {
+		throw new Error("a2/recovery-vercel needs the '@vercel/queue' package (optional peer dependency) — install it, or inject a transport");
+	});
+	return {
+		send: (topic, message, options) => queue.send(topic, message, options),
+		handleCallback: (handler) => queue.handleCallback(handler, {
+			visibilityTimeoutSeconds: MIN_VISIBILITY_SECONDS,
+			retry: (error, metadata) => error instanceof RecoveryUnsettled ? { afterSeconds: unsettledBackoffSeconds(delaySeconds, metadata.deliveryCount) } : void 0
+		}),
+		isDuplicate: (error) => error instanceof queue.DuplicateMessageError
+	};
+};
+function vercelQueues(options = {}) {
+	const topic = options.topic ?? "a2";
+	const delaySeconds = options.delaySeconds ?? 5;
+	const clock = options.clock ?? SYSTEM_CLOCK;
+	const transport = retryableLazy(() => options.transport ? Promise.resolve(options.transport) : vercelQueueTransport(delaySeconds)).get;
+	const sendWatchdog = async (opts) => {
+		const t = await transport();
+		const nowMs = clock.now().getTime();
+		const requestedDueAt = opts.dueAt ?? nowMs + delaySeconds * 1e3;
+		const dueAt = Math.ceil(requestedDueAt / 1e3) * 1e3;
+		const recoveryId = `${opts.contract}:${opts.sessionId}:watchdog:${dueAt}`;
+		try {
+			await t.send(topic, {
+				contract: opts.contract,
+				sessionId: opts.sessionId,
+				dueAt
+			}, {
+				delaySeconds: Math.max(0, Math.ceil((dueAt - nowMs) / 1e3)),
+				idempotencyKey: recoveryId
+			});
+		} catch (err) {
+			if (t.isDuplicate(err)) return;
+			throw err;
+		}
+	};
+	const successorDueAt = (message) => {
+		const minimumDueAt = clock.now().getTime() + DRAIN_TIMINGS.leaseTtlMs + DRAIN_TIMINGS.recoveryGraceMs;
+		if (message.dueAt === void 0) return minimumDueAt;
+		const beats = Math.max(1, Math.ceil((minimumDueAt - message.dueAt) / DRAIN_TIMINGS.leaseHeartbeatMs));
+		return message.dueAt + beats * DRAIN_TIMINGS.leaseHeartbeatMs;
+	};
+	return {
+		async arm({ contract, sessionId, dueAt }) {
+			await sendWatchdog({
+				contract,
+				sessionId,
+				...dueAt !== void 0 ? { dueAt } : {}
+			});
+		},
+		handler(...servers) {
+			const byContract = /* @__PURE__ */ new Map();
+			for (const server of servers) byContract.set(server.contract.name, server);
+			return async (req) => {
+				return (await transport()).handleCallback(async (message) => {
+					const server = byContract.get(message.contract);
+					if (!server) throw new Error(`a2 recovery: no server for contract '${message.contract}' — pass it to recovery.handler(...)`);
+					const internals = serverInternals.get(server);
+					const nextDueAt = successorDueAt(message);
+					const result = internals ? await internals.recoveryDrain(message.sessionId, { recoveryDueAt: nextDueAt }) : {
+						...await server.drain(message.sessionId),
+						outcome: "unknown",
+						processed: 0
+					};
+					if (result.settled) return;
+					if (result.outcome === "busy" || result.outcome === "handed_off") {
+						if (result.recoveryArm) await result.recoveryArm;
+						else await sendWatchdog({
+							contract: message.contract,
+							sessionId: message.sessionId,
+							dueAt: nextDueAt
+						});
+						return;
+					}
+					throw new RecoveryUnsettled(`a2 recovery: session '${message.sessionId}' of '${message.contract}' not settled yet (${result.outcome}) — rescheduled for redelivery`);
+				})(req);
+			};
+		}
+	};
+}
+//#endregion
+export { RecoveryUnsettled, vercelQueues };

package/dist/retryable-lazy-DZWmHpii.js

@@ -0,0 +1,19 @@
+//#region src/retryable-lazy.ts
+const retryableLazy = (initialize) => {
+	let current = null;
+	const get = () => {
+		if (current) return current;
+		const attempt = Promise.resolve().then(initialize);
+		current = attempt;
+		attempt.catch(() => {
+			if (current === attempt) current = null;
+		});
+		return attempt;
+	};
+	return {
+		get,
+		peek: () => current
+	};
+};
+//#endregion
+export { retryableLazy as t };