@midsummer-ai/sdk 0.0.0-stage → 0.1.0-next.419

package/queues/index.d.mts

@@ -0,0 +1,184 @@
+//#region src/queues/index.d.ts
+/**
+ * Queues: a Team's Queues of Messages, which the SDK reaches by the name an Environment binds each one
+ * under (`midsummer env binding set`).
+ *
+ *   import { queues } from "@midsummer-ai/sdk/queues"
+ *   import { standIn } from "@midsummer-ai/sdk/queues/stand-in"
+ *
+ *   const jobs = queues(standIn({ clock: Date.now }))
+ *   const emails = jobs.queue("emails")
+ *   await emails.send({ to: "ada@example.com" }, { key: `welcome:${userId}` })
+ *   for (const delivery of await emails.receive({ limit: 10 })) {
+ *     try { await mail(delivery.body); await emails.ack(delivery.receipt) }
+ *     catch { await emails.retry(delivery.receipt) }
+ *   }
+ *   const { depth, oldestSentAt } = await emails.stats()
+ *
+ * The Stand-in keeps Messages in memory, for tests and `midsummer dev`. On Midsummer, a Consumer
+ * delivers each Message to a path of your Site (`midsummer queue consumer set`), and `remote` from
+ * `@midsummer-ai/sdk/queues/wire` reaches the real Queues over a transport. Each is held to the cases
+ * in `@midsummer-ai/sdk/queues/contract`; a behaviour that is not a case there is not promised.
+ *
+ * Delivery is at least once. A Message received is hidden from other receivers for its visibility
+ * window; acked, it is gone; retried, or left until the window ends, it is delivered again, a later
+ * time each attempt (10 seconds after the first, doubling, at most 10 minutes). Once it has been
+ * delivered `maxAttempts` times (5 unless the receiver says), a retry or an ended window moves it
+ * to the Queue's dead-letter Queue, `queue.deadLetter`, where it waits to be read and never moves on.
+ * A receipt names one delivery: acking or retrying one whose window has ended does nothing.
+ *
+ * A send with a `key` is made once: sending the same key to the same Queue again, within a day,
+ * returns the first Message's id and sends nothing. Schedules send with one, so a Schedule's minute
+ * sends once however often it is reached.
+ *
+ * Names and bodies are checked here, before anything leaves the caller. Every failure is a
+ * `QueueError`, whose `code` is the one the wire carries.
+ */
+/** Why a Queues call failed: as Storage's codes say (`invalid`, `forbidden`, `quota`, `unavailable` …). */
+type QueueErrorCode = "invalid" | "forbidden" | "quota" | "unavailable";
+declare const queueErrorCodes: ReadonlyArray<QueueErrorCode>;
+declare class QueueError extends Error {
+  readonly code: QueueErrorCode;
+  constructor(code: QueueErrorCode, why: string);
+}
+/** Any value JSON can carry. */
+type Json = string | number | boolean | null | ReadonlyArray<Json> | {
+  readonly [key: string]: Json;
+};
+/** One delivery of a Message: its body as sent, and the receipt that acks or retries it. */
+interface Delivery<Body = Json> {
+  readonly id: string;
+  readonly body: Body;
+  /** When it was sent, in milliseconds since the epoch. */
+  readonly sentAt: number;
+  /** Which delivery this is: 1 the first time it is received. */
+  readonly attempt: number;
+  /** Names this delivery; it acks or retries it until `visibleUntil`, and does nothing after. */
+  readonly receipt: string;
+  /** When the visibility window ends and the Message may be delivered again. */
+  readonly visibleUntil: number;
+}
+interface SendOptions {
+  /** Seconds before it can be received: 0 to 43,200 (12 hours), 0 by default. */
+  readonly delaySeconds?: number;
+  /** Makes the send once: 1 to 128 printable characters. */
+  readonly key?: string;
+}
+interface ReceiveOptions {
+  /** At most this many: 1 to 100, 10 by default. */
+  readonly limit?: number;
+  /** Seconds each delivery is hidden from other receivers: 1 to 43,200, 30 by default. */
+  readonly visibilitySeconds?: number;
+  /** Deliveries after which a retry moves the Message to the dead-letter Queue: 1 to 100, 5 by default. */
+  readonly maxAttempts?: number;
+}
+/**
+ * What a Queue holds now. Each count stops at 1,000, with `more` set when there are more: reading
+ * stats never reads a whole Queue.
+ */
+interface QueueStats {
+  /** Every Message not yet acked: ready, in flight and delayed. */
+  readonly depth: number;
+  /** Messages that can be received now. */
+  readonly ready: number;
+  /** Messages delivered whose visibility window has not ended. */
+  readonly inFlight: number;
+  /** Messages sent with a delay, or retried, that cannot be received yet. */
+  readonly delayed: number;
+  /** When the oldest Message not yet acked was sent; absent when there is none. */
+  readonly oldestSentAt?: number;
+  /** Messages in the dead-letter Queue. */
+  readonly dead: number;
+  readonly more?: true;
+}
+/** The Messages of one Queue. */
+interface Queue {
+  readonly name: string;
+  /** Sends one Message. Its body is any JSON value, at most 128 KiB as JSON. */
+  send(body: Json, options?: SendOptions): Promise<{
+    readonly id: string;
+  }>;
+  /** Sends up to 100 Messages together, received in the order given; ids in the same order. */
+  sendBatch(messages: ReadonlyArray<{
+    readonly body: Json;
+  } & SendOptions>): Promise<{
+    readonly ids: ReadonlyArray<string>;
+  }>;
+  /**
+   * Up to `limit` Messages that can be received now, oldest first. An engine looks at a bounded
+   * number of Messages a call, so it may answer fewer, or none, while it moves exhausted ones to the
+   * dead-letter Queue: receive again.
+   */
+  receive<Body = Json>(options?: ReceiveOptions): Promise<ReadonlyArray<Delivery<Body>>>;
+  /** Ends a Message: it is not delivered again. */
+  ack(receipt: string): Promise<void>;
+  /**
+   * Hands a Message back to be delivered again after `delaySeconds`, or after the backoff when not
+   * given: 10 seconds after the first delivery, doubling, at most 600. Past its `maxAttempts` it
+   * moves to the dead-letter Queue instead.
+   */
+  retry(receipt: string, options?: {
+    readonly delaySeconds?: number;
+  }): Promise<void>;
+  stats(): Promise<QueueStats>;
+  /** Where this Queue's Messages go once they have been delivered `maxAttempts` times. Its own Messages never move on. */
+  readonly deadLetter: Queue;
+}
+interface Queues {
+  /** A Queue by name: 1 to 63 lowercase letters, digits, hyphens and underscores, starting with a letter or digit. */
+  queue(name: string): Queue;
+}
+/** A Message as an engine is given it: its body as JSON text. */
+interface EngineMessage {
+  readonly body: string;
+  readonly delayMs: number;
+  readonly key?: string;
+}
+/** A delivery as an engine returns it: its body as JSON text. */
+interface EngineDelivery extends Omit<Delivery, "body"> {
+  readonly body: string;
+}
+/**
+ * Where Messages live: the Seam under `queues()`. The Stand-in and the real Capability are its
+ * Adapters. Calls arrive checked: a Queue's name is valid (with `.dead` after it for a dead-letter
+ * Queue), bodies are JSON text, times are milliseconds and defaults are filled in.
+ */
+interface QueueEngine {
+  /** Sends the Messages in order and returns their ids, a keyed one's first id when it was sent before. */
+  send(queue: string, messages: ReadonlyArray<EngineMessage>): Promise<ReadonlyArray<string>>;
+  receive(queue: string, options: {
+    readonly limit: number;
+    readonly visibilityMs: number;
+    readonly maxAttempts: number;
+  }): Promise<ReadonlyArray<EngineDelivery>>;
+  ack(queue: string, receipt: string): Promise<void>;
+  /** With no `delayMs`, the backoff after the delivery's attempt (`backoffMs`). */
+  retry(queue: string, receipt: string, delayMs?: number): Promise<void>;
+  stats(queue: string): Promise<QueueStats>;
+}
+/** The suffix that marks a Queue's dead-letter Queue; no Queue's own name has a dot. */
+declare const DEAD = ".dead";
+/** The delay before a Message's next delivery after its `attempt`-th: 10 seconds, doubling, at most 10 minutes. */
+declare function backoffMs(attempt: number): number;
+/** Stats' counts stop at this many. */
+declare const STATS_CAP = 1000;
+declare function invalid(why: string): never;
+declare function checkQueueName(name: string): void;
+/** A name as an engine is given it: a Queue's, or its dead-letter Queue's. */
+declare function checkEngineQueue(queue: string): void;
+declare function checkKey(key: string): void;
+/** Bodies are at most this many bytes of JSON. */
+declare const MAX_BODY: number;
+/** The JSON text of `body`, which must be a JSON value of at most 128 KiB. */
+declare function bodyText(body: unknown): string;
+declare function checkReceipt(receipt: string): void;
+declare function checkDelaySeconds(seconds: number): void;
+declare function checkReceive(options: {
+  readonly limit: number;
+  readonly visibilityMs: number;
+  readonly maxAttempts: number;
+}): void;
+/** Queues over `engine`. */
+declare function queues(engine: QueueEngine): Queues;
+//#endregion
+export { DEAD, Delivery, EngineDelivery, EngineMessage, Json, MAX_BODY, Queue, QueueEngine, QueueError, QueueErrorCode, QueueStats, Queues, ReceiveOptions, STATS_CAP, SendOptions, backoffMs, bodyText, checkDelaySeconds, checkEngineQueue, checkKey, checkQueueName, checkReceipt, checkReceive, invalid, queueErrorCodes, queues };

package/queues/index.mjs

@@ -0,0 +1,126 @@
+//#region src/queues/index.ts
+const queueErrorCodes = [
+	"invalid",
+	"forbidden",
+	"quota",
+	"unavailable"
+];
+var QueueError = class extends Error {
+	code;
+	constructor(code, why) {
+		super(why);
+		this.code = code;
+		this.name = "QueueError";
+	}
+};
+/** The suffix that marks a Queue's dead-letter Queue; no Queue's own name has a dot. */
+const DEAD = ".dead";
+/** The delay before a Message's next delivery after its `attempt`-th: 10 seconds, doubling, at most 10 minutes. */
+function backoffMs(attempt) {
+	return Math.min(1e4 * 2 ** Math.max(0, attempt - 1), 6e5);
+}
+/** Stats' counts stop at this many. */
+const STATS_CAP = 1e3;
+function invalid(why) {
+	throw new QueueError("invalid", why);
+}
+const whole = (n, low, high) => typeof n === "number" && Number.isSafeInteger(n) && n >= low && n <= high;
+function checkQueueName(name) {
+	if (!/^[a-z0-9][a-z0-9_-]{0,62}$/.test(name)) invalid(`"${name}" is not a Queue name: 1 to 63 lowercase letters, digits, hyphens and underscores, starting with a letter or digit`);
+}
+/** A name as an engine is given it: a Queue's, or its dead-letter Queue's. */
+function checkEngineQueue(queue) {
+	checkQueueName(queue.endsWith(".dead") ? queue.slice(0, -5) : queue);
+}
+function checkKey(key) {
+	if (!/^[\x21-\x7e]{1,128}$/.test(key)) invalid("a send's key is 1 to 128 printable characters, without spaces");
+}
+/** Bodies are at most this many bytes of JSON. */
+const MAX_BODY = 131072;
+const encoder = new TextEncoder();
+/** The JSON text of `body`, which must be a JSON value of at most 128 KiB. */
+function bodyText(body) {
+	let text;
+	try {
+		text = JSON.stringify(body);
+	} catch {
+		invalid("the body is not a JSON value");
+	}
+	if (text === void 0) invalid("the body is not a JSON value");
+	const bytes = encoder.encode(text).length;
+	if (bytes > 131072) invalid(`the body is ${bytes} bytes of JSON; at most 131,072`);
+	return text;
+}
+function checkReceipt(receipt) {
+	if (!/^[A-Za-z0-9._-]{1,200}$/.test(receipt)) invalid("that is not a receipt");
+}
+function checkDelaySeconds(seconds) {
+	if (!whole(seconds, 0, 43200)) invalid("a delay is a whole number of seconds, 0 to 43,200");
+}
+function checkReceive(options) {
+	if (!whole(options.limit, 1, 100)) invalid("a receive's limit is 1 to 100");
+	if (!whole(options.visibilityMs, 1e3, 432e5) || options.visibilityMs % 1e3 !== 0) invalid("a visibility window is a whole number of seconds, 1 to 43,200");
+	if (!whole(options.maxAttempts, 1, 100)) invalid("maxAttempts is 1 to 100");
+}
+/** Queues over `engine`. */
+function queues(engine) {
+	const queueOf = (name, engineName, dead) => {
+		const queue = {
+			name,
+			async send(body, options = {}) {
+				const { ids } = await queue.sendBatch([{
+					body,
+					...options
+				}]);
+				return { id: ids[0] };
+			},
+			async sendBatch(messages) {
+				if (messages.length < 1 || messages.length > 100) invalid("a batch sends 1 to 100 Messages");
+				const checked = messages.map(({ body, delaySeconds = 0, key }) => {
+					checkDelaySeconds(delaySeconds);
+					if (key !== void 0) checkKey(key);
+					return {
+						body: bodyText(body),
+						delayMs: delaySeconds * 1e3,
+						...key !== void 0 ? { key } : {}
+					};
+				});
+				return { ids: await engine.send(engineName, checked) };
+			},
+			async receive(options = {}) {
+				const call = {
+					limit: options.limit ?? 10,
+					visibilityMs: (options.visibilitySeconds ?? 30) * 1e3,
+					maxAttempts: options.maxAttempts ?? 5
+				};
+				checkReceive(call);
+				return (await engine.receive(engineName, call)).map((delivery) => ({
+					...delivery,
+					body: JSON.parse(delivery.body)
+				}));
+			},
+			async ack(receipt) {
+				checkReceipt(receipt);
+				return engine.ack(engineName, receipt);
+			},
+			async retry(receipt, options = {}) {
+				checkReceipt(receipt);
+				if (options.delaySeconds !== void 0) checkDelaySeconds(options.delaySeconds);
+				return engine.retry(engineName, receipt, options.delaySeconds === void 0 ? void 0 : options.delaySeconds * 1e3);
+			},
+			stats() {
+				return engine.stats(engineName);
+			},
+			get deadLetter() {
+				return dead ?? queue;
+			}
+		};
+		return queue;
+	};
+	return { queue(name) {
+		checkQueueName(name);
+		return queueOf(name, name, queueOf(`${name}${DEAD}`, `${name}${DEAD}`));
+	} };
+}
+//#endregion
+export { DEAD, MAX_BODY, QueueError, STATS_CAP, backoffMs, bodyText, checkDelaySeconds, checkEngineQueue, checkKey, checkQueueName, checkReceipt, checkReceive, invalid, queueErrorCodes, queues };

package/queues/stand-in.d.mts

@@ -0,0 +1,7 @@
+import { QueueEngine } from "./index.mjs";
+//#region src/queues/stand-in.d.ts
+declare function standIn(options: {
+  readonly clock: () => number;
+}): QueueEngine;
+//#endregion
+export { standIn };

package/queues/stand-in.mjs

@@ -0,0 +1,110 @@
+import { DEAD, STATS_CAP, backoffMs } from "./index.mjs";
+//#region src/queues/stand-in.ts
+/**
+* Queues' Stand-in: the Capability's behaviour in memory, for `midsummer dev` and tests. It holds no
+* engine code and passes the contract (`@midsummer-ai/sdk/queues/contract`) except durability and scale.
+*
+*   const jobs = queues(standIn({ clock: Date.now }))
+*
+* A Queue exists from its first send. Everything is lost when the process ends.
+*/
+/** Keys a keyed send is remembered for. */
+const KEY_MS = 864e5;
+function standIn(options) {
+	const { clock } = options;
+	const queues = /* @__PURE__ */ new Map();
+	const keys = /* @__PURE__ */ new Map();
+	let sequence = 0;
+	const queueOf = (name) => {
+		let held = queues.get(name);
+		if (!held) queues.set(name, held = []);
+		return held;
+	};
+	const order = (a, b) => a.visibleAt - b.visibleAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+	const nextId = (at) => `${at.toString(36).padStart(9, "0")}${(sequence++).toString(36).padStart(6, "0")}`;
+	/** Moves `held` to its dead-letter Queue when its last delivery was its last; returns whether it did. */
+	const deadLetter = (queue, held) => {
+		if (queue.endsWith(".dead") || held.maxAttempts === void 0 || held.attempts < held.maxAttempts) return false;
+		const list = queueOf(queue);
+		list.splice(list.indexOf(held), 1);
+		const { receipt: _receipt, maxAttempts: _max, ...rest } = held;
+		queueOf(`${queue}${DEAD}`).push({
+			...rest,
+			visibleAt: clock()
+		});
+		return true;
+	};
+	/** The Message a receipt still names: none once its window has ended, though it was not delivered again yet. */
+	const delivered = (queue, receipt) => queues.get(queue)?.find((held) => held.receipt === receipt && held.visibleAt > clock());
+	return {
+		async send(queue, messages) {
+			const now = clock();
+			return messages.map((message) => {
+				const remembered = message.key === void 0 ? void 0 : keys.get(`${queue}\n${message.key}`);
+				if (remembered && now - remembered.at < KEY_MS) return remembered.id;
+				const id = nextId(now);
+				queueOf(queue).push({
+					id,
+					body: message.body,
+					sentAt: now,
+					visibleAt: now + message.delayMs,
+					attempts: 0
+				});
+				if (message.key !== void 0) keys.set(`${queue}\n${message.key}`, {
+					id,
+					at: now
+				});
+				return id;
+			});
+		},
+		async receive(queue, { limit, visibilityMs, maxAttempts }) {
+			const now = clock();
+			const out = [];
+			for (const held of [...queues.get(queue) ?? []].sort(order)) {
+				if (out.length === limit || held.visibleAt > now) break;
+				if (held.receipt !== void 0 && deadLetter(queue, held)) continue;
+				held.attempts += 1;
+				held.visibleAt = now + visibilityMs;
+				held.receipt = `${held.id}.${crypto.randomUUID().replaceAll("-", "")}`;
+				held.maxAttempts = maxAttempts;
+				out.push({
+					id: held.id,
+					body: held.body,
+					sentAt: held.sentAt,
+					attempt: held.attempts,
+					receipt: held.receipt,
+					visibleUntil: held.visibleAt
+				});
+			}
+			return out;
+		},
+		async ack(queue, receipt) {
+			const held = delivered(queue, receipt);
+			if (held) queueOf(queue).splice(queueOf(queue).indexOf(held), 1);
+		},
+		async retry(queue, receipt, delayMs) {
+			const held = delivered(queue, receipt);
+			if (!held || deadLetter(queue, held)) return;
+			held.visibleAt = clock() + (delayMs ?? backoffMs(held.attempts));
+			delete held.receipt;
+			delete held.maxAttempts;
+		},
+		async stats(queue) {
+			const now = clock();
+			const held = queues.get(queue) ?? [];
+			const counted = [...held].sort((a, b) => a.sentAt - b.sentAt).slice(0, STATS_CAP);
+			const dead = (queues.get(`${queue}.dead`) ?? []).length;
+			return {
+				depth: counted.length,
+				ready: counted.filter((m) => m.visibleAt <= now).length,
+				inFlight: counted.filter((m) => m.receipt !== void 0 && m.visibleAt > now).length,
+				delayed: counted.filter((m) => m.receipt === void 0 && m.visibleAt > now).length,
+				...counted[0] ? { oldestSentAt: counted[0].sentAt } : {},
+				dead: Math.min(dead, STATS_CAP),
+				...held.length > 1e3 || dead > 1e3 ? { more: true } : {}
+			};
+		}
+	};
+}
+//#endregion
+export { standIn };

package/queues/wire.d.mts

@@ -0,0 +1,9 @@
+import { Transport } from "../wire.mjs";
+import { QueueEngine } from "./index.mjs";
+//#region src/queues/wire.d.ts
+/** The engine on the far side of `transport`. */
+declare function remote(transport: Transport): QueueEngine;
+/** Answers frames from `remote` with `engine`, checking each again: a frame comes from the network. */
+declare function serve(engine: QueueEngine): (frame: Uint8Array) => Promise<Uint8Array>;
+//#endregion
+export { type Transport, remote, serve };

package/queues/wire.mjs

@@ -0,0 +1,199 @@
+import { decodeFrame, encodeFrame } from "../wire.mjs";
+import { QueueError, checkEngineQueue, checkKey, checkReceipt, checkReceive, queueErrorCodes } from "./index.mjs";
+import { z } from "zod";
+//#region src/queues/wire.ts
+/**
+* Queues' wire: how a Queues call crosses a network. `remote(transport)` is the engine a client uses;
+* `serve(engine)` replies on the other side. A server implements `serve` over its own engine and
+* nothing else, so the contract run through the wire holds for it too.
+*
+*   const jobs = queues(remote({ send: (frame) => env.QUEUES.send(frame) }))   // in a Site
+*   handle.onFrame(serve(engine))                                              // on the platform
+*
+* Frames are Storage's (`@midsummer-ai/sdk/wire`): a 4-byte little-endian length and that many bytes of
+* JSON header, here with no body after it. One request frame gets one answer frame. Changing a frame
+* changes the contract with every server.
+*/
+const request = z.discriminatedUnion("op", [
+	z.object({
+		op: z.literal("queue.send"),
+		queue: z.string(),
+		messages: z.array(z.object({
+			body: z.string(),
+			delayMs: z.number(),
+			key: z.string().optional()
+		}).strict()).min(1).max(100)
+	}).strict(),
+	z.object({
+		op: z.literal("queue.receive"),
+		queue: z.string(),
+		limit: z.number(),
+		visibilityMs: z.number(),
+		maxAttempts: z.number()
+	}).strict(),
+	z.object({
+		op: z.literal("queue.ack"),
+		queue: z.string(),
+		receipt: z.string()
+	}).strict(),
+	z.object({
+		op: z.literal("queue.retry"),
+		queue: z.string(),
+		receipt: z.string(),
+		delayMs: z.number().optional()
+	}).strict(),
+	z.object({
+		op: z.literal("queue.stats"),
+		queue: z.string()
+	}).strict()
+]);
+const delivery = z.object({
+	id: z.string(),
+	body: z.string(),
+	sentAt: z.number(),
+	attempt: z.number(),
+	receipt: z.string(),
+	visibleUntil: z.number()
+}).strict();
+const stats = z.object({
+	depth: z.number(),
+	ready: z.number(),
+	inFlight: z.number(),
+	delayed: z.number(),
+	oldestSentAt: z.number().optional(),
+	dead: z.number(),
+	more: z.literal(true).optional()
+}).strict();
+const answer = z.union([
+	z.object({
+		error: z.enum(queueErrorCodes),
+		why: z.string()
+	}).strict(),
+	z.object({ ids: z.array(z.string()) }).strict(),
+	z.object({ deliveries: z.array(delivery) }).strict(),
+	z.object({ stats }).strict(),
+	z.object({ done: z.literal(true) }).strict()
+]);
+/** The engine on the far side of `transport`. */
+function remote(transport) {
+	const call = async (header) => {
+		let frame;
+		try {
+			frame = await transport.send(encodeFrame(header));
+		} catch (error) {
+			if (error instanceof QueueError) throw error;
+			if (error instanceof Error && "code" in error && (error.code === "forbidden" || error.code === "unavailable")) throw new QueueError(error.code, "Queues could not be reached");
+			throw new QueueError("unavailable", "Queues could not be reached");
+		}
+		let parsed;
+		try {
+			parsed = answer.parse(decodeFrame(frame).header);
+		} catch {
+			throw new QueueError("unavailable", "Queues answered something that is not a Queues answer");
+		}
+		if ("error" in parsed) throw new QueueError(parsed.error, parsed.why);
+		return parsed;
+	};
+	const expect = (answered, key) => {
+		if (!(key in answered)) throw new QueueError("unavailable", "Queues answered another call");
+		return answered[key];
+	};
+	return {
+		async send(queue, messages) {
+			return expect(await call({
+				op: "queue.send",
+				queue,
+				messages: [...messages]
+			}), "ids");
+		},
+		async receive(queue, options) {
+			return expect(await call({
+				op: "queue.receive",
+				queue,
+				...options
+			}), "deliveries");
+		},
+		async ack(queue, receipt) {
+			await call({
+				op: "queue.ack",
+				queue,
+				receipt
+			});
+		},
+		async retry(queue, receipt, delayMs) {
+			await call({
+				op: "queue.retry",
+				queue,
+				receipt,
+				...delayMs === void 0 ? {} : { delayMs }
+			});
+		},
+		async stats(queue) {
+			return expect(await call({
+				op: "queue.stats",
+				queue
+			}), "stats");
+		}
+	};
+}
+const encoder = new TextEncoder();
+/** Answers frames from `remote` with `engine`, checking each again: a frame comes from the network. */
+function serve(engine) {
+	return async (frame) => {
+		try {
+			let header;
+			try {
+				header = decodeFrame(frame).header;
+			} catch {
+				throw new QueueError("invalid", "the frame is not a frame");
+			}
+			const parsed = request.safeParse(header);
+			if (!parsed.success) throw new QueueError("invalid", "the request frame is not a Queues call");
+			const call = parsed.data;
+			checkEngineQueue(call.queue);
+			switch (call.op) {
+				case "queue.send":
+					for (const message of call.messages) {
+						if (message.key !== void 0) checkKey(message.key);
+						if (!Number.isSafeInteger(message.delayMs) || message.delayMs < 0 || message.delayMs > 432e5) throw new QueueError("invalid", "a delay is 0 to 43,200 seconds");
+						if (encoder.encode(message.body).length > 131072) throw new QueueError("invalid", "a body is at most 131,072 bytes of JSON");
+						try {
+							JSON.parse(message.body);
+						} catch {
+							throw new QueueError("invalid", "a body is not JSON");
+						}
+					}
+					return encodeFrame({ ids: await engine.send(call.queue, call.messages.map(({ body, delayMs, key }) => ({
+						body,
+						delayMs,
+						...key === void 0 ? {} : { key }
+					}))) });
+				case "queue.receive":
+					checkReceive(call);
+					return encodeFrame({ deliveries: await engine.receive(call.queue, {
+						limit: call.limit,
+						visibilityMs: call.visibilityMs,
+						maxAttempts: call.maxAttempts
+					}) });
+				case "queue.ack":
+					checkReceipt(call.receipt);
+					await engine.ack(call.queue, call.receipt);
+					return encodeFrame({ done: true });
+				case "queue.retry":
+					checkReceipt(call.receipt);
+					if (call.delayMs !== void 0 && (!Number.isSafeInteger(call.delayMs) || call.delayMs < 0 || call.delayMs > 432e5)) throw new QueueError("invalid", "a delay is 0 to 43,200 seconds");
+					await engine.retry(call.queue, call.receipt, call.delayMs);
+					return encodeFrame({ done: true });
+				case "queue.stats": return encodeFrame({ stats: await engine.stats(call.queue) });
+			}
+		} catch (error) {
+			if (error instanceof QueueError) return encodeFrame({
+				error: error.code,
+				why: error.message
+			});
+			throw error;
+		}
+	};
+}
+//#endregion
+export { remote, serve };

package/s3.d.mts

@@ -0,0 +1,43 @@
+import { m as StorageEngine } from "./index-sgdyoA2P.mjs";
+//#region src/s3.d.ts
+/** What one access key may do. */
+interface S3Credential {
+  /** The secret access key that signs its requests. */
+  readonly secret: string;
+  /** `read`: list, get and head. `write`: everything. */
+  readonly access: "read" | "write";
+  /**
+   * The Buckets it may use, by name, each with the name the engine knows it by. When not set, every
+   * Bucket, under its own name, as under `midsummer dev`.
+   */
+  readonly buckets?: Readonly<Record<string, string>>;
+  /** Buckets, by name, whose writes are paused (their Team reached its budget): reads go on, writes are `QuotaExceeded`. */
+  readonly paused?: ReadonlyArray<string>;
+}
+interface S3Options {
+  /**
+   * The credential of an access key id, or `null` for one that is unknown or revoked. `named` is the
+   * Buckets the request names (its own and a copy's source); the credential may then answer only
+   * those of its `buckets`. Without it (a request listing the key's Buckets), every one.
+   */
+  credentials(accessKeyId: string, named?: ReadonlyArray<string>): S3Credential | null | Promise<S3Credential | null>;
+  /** Hostnames whose subdomains are Buckets, as `avatars.<host>`. Path-style addressing always works. */
+  readonly hosts?: ReadonlyArray<string>;
+  /**
+   * The path the handler is mounted at, such as `/s3`: Buckets are addressed after it, and clients
+   * take it as part of their endpoint (`https://api.example.com/s3`). Signatures cover the whole path.
+   */
+  readonly base?: string;
+  readonly clock: () => number;
+  /**
+   * Told, once a Bucket has served a request, the name the engine knows that Bucket by and the class
+   * S3 bills the request in. A request that is not signed, is refused access, is replied to
+   * `NotImplemented`, deletes (deletes are free), or names no Bucket is not counted.
+   */
+  readonly counted?: (bucket: string, kind: RequestClass) => void;
+}
+/** How S3 bills a request: `a` for what writes or lists (PUT, POST, COPY, LIST), `b` for what reads (GET, HEAD). */
+type RequestClass = "a" | "b";
+declare function s3(engine: StorageEngine, options: S3Options): (request: Request) => Promise<Response>;
+//#endregion
+export { RequestClass, S3Credential, S3Options, s3 };