@volter/twin-upstash 0.1.0

package/dist/qstash/src/semantics/messages.ts

@@ -0,0 +1,249 @@
+// Publishing: `POST /v2/publish/{destination}`, `POST /v2/enqueue/{queueName}/{destination}` and `POST /v2/batch`, and a
+// message's read and cancel. A published message is accepted at once and delivered by the catch-up when it falls due
+// (delivery.ts). A message that carries `Upstash-Workflow-RunId` is a workflow's (workflows.ts): the first of a run starts
+// it, and each after is a step the run's route sends back. The headers a publish reads are the qstash document's
+// (`/v2/publish/{destination}`'s header parameters); the lane reads the ones a customer of its life and Dub send.
+import { createHash } from 'node:crypto';
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { gate } from './account.ts';
+import { acceptWorkflowMessage, isWorkflowMessage } from './workflows.ts';
+import { durationSeconds, everHeld, headersOf, lowerKeys, MESSAGE_FIELDS, mintId, multiValue, nowMs, QUEUE_NAME, refuse, vendorFields, type Row } from './shared.ts';
+
+/** How QStash retries by default: "By default, we retry a failed delivery 3 times." (https://upstash.com/docs/qstash/features/retry) */
+export const DEFAULT_RETRIES = 3;
+
+/** The account the request acts as (the lane's gate has admitted it). */
+export function ownerFor(ctx: SemanticsContext): string {
+  const g = gate(ctx, ctx.call.request);
+  return 'owner' in g ? g.owner : 'world';
+}
+
+/** One message as published: its destination, its headers (lower-cased) and its body, and the queue it is enqueued in. */
+export type Publication = { destination: string; headers: Record<string, string>; body: string; queue?: string | undefined };
+
+/** What a publish answers for one message: its id, and whether it was a duplicate. */
+export type Accepted = { messageId: string; deduplicated?: boolean } | Array<{ messageId: string; url: string; deduplicated?: boolean }> | { error: string; status: number };
+
+/** The `Upstash-Forward-*` headers, their prefix stripped: what the destination receives. */
+export function forwarded(headers: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) if (k.startsWith('upstash-forward-')) out[k.slice('upstash-forward-'.length)] = v;
+  return out;
+}
+
+/** A message's `header`: the headers sent to the API, its Content-Type and the ones it forwards, each name in its canonical
+ *  form, as the message example of https://upstash.com/docs/qstash/overall/llms-txt answers them
+ *  (`"header": { "Content-Type": ["application/json"] }`). */
+export function sentHeader(headers: Record<string, string>): Record<string, string[]> {
+  const canonical = (k: string): string => k.split('-').map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join('-');
+  const sent = { ...(headers['content-type'] ? { 'content-type': headers['content-type'] } : {}), ...forwarded(headers) };
+  return multiValue(Object.fromEntries(Object.entries(sent).map(([k, v]) => [canonical(k), v])));
+}
+
+/** `Upstash-Flow-Control-Value`'s settings ("parallelism=15, rate=10, period=1m"). */
+function flowControl(value: string | undefined): Row {
+  const out: Row = {};
+  for (const part of (value ?? '').split(',')) {
+    const [k, v] = part.split('=').map((s) => s.trim());
+    if (k === 'parallelism' || k === 'rate') out[k] = Number(v);
+    if (k === 'period') out.period = durationSeconds(v) ?? v;
+  }
+  return out;
+}
+
+/** Store one message: the vendor's Message fields, its state (CREATED) and what the lane keeps to deliver it. */
+export async function storeMessage(ctx: SemanticsContext, p: {
+  url: string; headers: Record<string, string>; body: string; owner: string; queue?: string | undefined; scheduleId?: string | undefined;
+  callbackOf?: string | undefined; run?: { id: string; seq: number; call: string; initial: boolean } | undefined; retries?: number | undefined; due?: number | undefined;
+  topic?: { name: string; endpoint?: string | undefined } | undefined;
+}): Promise<string> {
+  const h = p.headers;
+  const ordinal = everHeld(ctx, 'Message');
+  const id = mintId(ctx, 'msg_', 'message', ordinal);
+  const created = nowMs(ctx);
+  const notBefore = h['upstash-not-before'] !== undefined && /^\d+$/.test(h['upstash-not-before']) ? Number(h['upstash-not-before']) * 1000 : undefined;
+  const delay = durationSeconds(h['upstash-delay']) ?? 0;
+  const due = p.due ?? notBefore ?? created + delay * 1000;
+  const retries = p.retries ?? (h['upstash-retries'] !== undefined && /^\d+$/.test(h['upstash-retries']) ? Number(h['upstash-retries']) : DEFAULT_RETRIES);
+  const fields: Row = {
+    messageId: id, url: p.url, method: h['upstash-method'] ?? 'POST', header: sentHeader(h), body: p.body, maxRetries: retries,
+    notBefore: due, createdAt: created,
+    ...(h['upstash-callback'] ? { callback: h['upstash-callback'] } : {}),
+    ...(h['upstash-failure-callback'] ? { failureCallback: h['upstash-failure-callback'] } : {}),
+    ...(p.queue ? { queueName: p.queue } : {}),
+    ...(p.scheduleId ? { scheduleId: p.scheduleId } : {}),
+    ...labelsOf(h),
+    ...(p.topic ? { topicName: p.topic.name, ...(p.topic.endpoint ? { endpointName: p.topic.endpoint } : {}) } : {}),
+    ...(h['upstash-flow-control-key'] ? { flowControlKey: h['upstash-flow-control-key'], ...flowControl(h['upstash-flow-control-value']) } : {}),
+    state: 'CREATED',
+    _owner: p.owner, _due: due, _attempts: 0, _ordinal: ordinal, _published: h,
+    ...(h['content-type'] ? { _content_type: h['content-type'] } : {}),
+    ...(h['upstash-retry-delay'] ? { _retry_delay: h['upstash-retry-delay'] } : {}),
+    ...(h['upstash-deduplication-id'] ? { _dedup: h['upstash-deduplication-id'] } : h['upstash-content-based-deduplication'] === 'true' ? { _dedup: contentKey(p.url, p.body, h) } : {}),
+    ...(h['upstash-timeout'] ? { _timeout: durationSeconds(h['upstash-timeout']) ?? h['upstash-timeout'] } : {}),
+    ...(h['upstash-redact-fields'] ? { _redact: h['upstash-redact-fields'] } : {}),
+    ...(p.callbackOf ? { _callback_of: p.callbackOf } : {}),
+    ...(p.run ? { _run: p.run.id, _seq: p.run.seq, _call: p.run.call, _initial: p.run.initial } : {}),
+  };
+  await ctx.write('Message', id, fields, 'message.create');
+  return id;
+}
+
+/** A message's labels: `Upstash-Label` carries one, or several joined with commas (@upstash/qstash's `serializeLabel`:
+ *  `label.join(",")`); the Message schema answers the first as `label` and all as `labels`. */
+export function labelsOf(h: Record<string, string>): Row {
+  const labels = (h['upstash-label'] ?? '').split(',').map((l) => l.trim()).filter(Boolean);
+  return labels.length ? { label: labels[0], labels } : {};
+}
+
+/** Content-based deduplication: "If you want to deduplicate messages automatically, you can set the
+ *  `Upstash-Content-Based-Deduplication` header to `true`." (https://upstash.com/docs/qstash/features/deduplication). Where
+ *  the page stops and the lane decides: a message's content is its destination, its body and the headers it forwards. */
+function contentKey(url: string, body: string, h: Record<string, string>): string {
+  const fwd = Object.entries(h).filter(([k]) => k.startsWith('upstash-forward-')).sort();
+  return `content:${createHash('sha256').update(JSON.stringify([url, body, fwd])).digest('hex')}`;
+}
+
+/** "The deduplication window is 10 minutes. After that, messages with the same ID or content can be sent again."
+ *  (https://upstash.com/docs/qstash/features/deduplication) */
+const DEDUP_WINDOW_MS = 10 * 60_000;
+
+/** Accept one plain message (no workflow): refuse a destination that is not a URL, answer a duplicate's first id, and
+ *  make the queue a first enqueue names. "Messages can be deduplicated... In case a message is a duplicate, we will accept
+ *  the request and return the messageID of the existing message." (https://upstash.com/docs/qstash/features/deduplication) */
+export async function acceptPlain(ctx: SemanticsContext, p: Publication, owner: string): Promise<Accepted> {
+  if (p.queue !== undefined && !QUEUE_NAME.test(p.queue)) return { error: 'Queue name is invalid. Queue names can only contain alphanumeric characters, hyphens, periods, and underscores.', status: 400 };
+  if (!/^https?:\/\//.test(p.destination)) return acceptToUrlGroup(ctx, p, owner);
+  const dedup = p.headers['upstash-deduplication-id'] ?? (p.headers['upstash-content-based-deduplication'] === 'true' ? contentKey(p.destination, p.body, p.headers) : undefined);
+  if (dedup) {
+    const prior = ctx.rowsRaw('Message').find((m) => m._dedup === dedup && m._owner === owner && nowMs(ctx) - Number(m.createdAt) < DEDUP_WINDOW_MS);
+    if (prior) return { messageId: String(prior.messageId), deduplicated: true };
+  }
+  if (p.queue !== undefined) await ensureQueue(ctx, p.queue);
+  const messageId = await storeMessage(ctx, { url: p.destination, headers: p.headers, body: p.body, owner, queue: p.queue });
+  return { messageId };
+}
+
+/** A message to a URL group: "If the destination is a URL Group, a new message will be created for each endpoint in the
+ *  group." (the spec's publish); the answer lists each endpoint's message and URL (`PublishToUrlGroupResponse`). A name the
+ *  account has no URL group of answers 404 (the spec's publish 404 is the destination not found). */
+export async function acceptToUrlGroup(ctx: SemanticsContext, p: Publication, owner: string): Promise<Accepted> {
+  const group = ctx.rowsRaw('URLGroup').find((g) => g.name === p.destination && g._owner === owner);
+  if (!group) return { error: `URL Group ${p.destination} not found`, status: 404 };
+  if (p.queue !== undefined) await ensureQueue(ctx, p.queue);
+  const out: Array<{ messageId: string; url: string }> = [];
+  for (const e of (group.endpoints ?? []) as Array<{ url: string; name?: string }>) {
+    const messageId = await storeMessage(ctx, { url: e.url, headers: p.headers, body: p.body, owner, queue: p.queue, topic: { name: String(group.name), endpoint: e.name } });
+    out.push({ messageId, url: e.url });
+  }
+  return out;
+}
+
+/** A queue a first enqueue names: "If the queue does not exist, it will be created automatically with default
+ *  parallelism." (the spec's enqueue); a queue delivers in order, one message at a time
+ *  (https://upstash.com/docs/qstash/features/queues). */
+export async function ensureQueue(ctx: SemanticsContext, name: string): Promise<void> {
+  if (ctx.rowsRaw('Queue').some((q) => q.name === name)) return;
+  const at = nowMs(ctx);
+  await ctx.write('Queue', name, { name, createdAt: at, updatedAt: at, parallelism: 1, paused: false, lag: 0 }, 'queue.create');
+}
+
+async function accept(ctx: SemanticsContext, p: Publication, owner: string): Promise<Accepted> {
+  return invalidDestination(ctx, p, owner) ?? (isWorkflowMessage(p.headers) ? acceptWorkflowMessage(ctx, p, owner) : acceptPlain(ctx, p, owner));
+}
+
+/** "Destination can either be a valid URL where the message gets sent to, or a URL Group name." (the spec's publish): a
+ *  URL that does not parse (a page's `https://<YOUR_WORKFLOW_ENDPOINT>/<YOUR-WORKFLOW-ROUTE>`) is refused 400, and a
+ *  workflow's run sent to a name the account holds no URL group of answers the publish's 404 (a plain message's group is
+ *  looked up by acceptToUrlGroup). */
+function invalidDestination(ctx: SemanticsContext, p: Publication, owner: string): Accepted | undefined {
+  if (/^https?:\/\//i.test(p.destination)) return URL.canParse(p.destination) ? undefined : { error: `invalid destination url: ${p.destination}`, status: 400 };
+  const group = ctx.rowsRaw('URLGroup').some((g) => g.name === p.destination && g._owner === owner);
+  return isWorkflowMessage(p.headers) && !group ? { error: `URL Group ${p.destination} not found`, status: 404 } : undefined;
+}
+
+const answer = (ctx: SemanticsContext, a: Accepted): Response =>
+  !Array.isArray(a) && 'error' in a ? refuse(ctx, a.status, a.error) : ctx.reply(a, !Array.isArray(a) && a.deduplicated ? 202 : 200);
+
+/** POST /v2/publish/{destination}. */
+const publish: Semantics = async (ctx) => {
+  const destination = String(ctx.call.params.destination ?? '');
+  return answer(ctx, await accept(ctx, { destination, headers: headersOf(ctx), body: ctx.text ?? '' }, ownerFor(ctx)));
+};
+
+/** POST /v2/enqueue/{queueName}/{destination}. */
+const enqueue: Semantics = async (ctx) => {
+  const destination = String(ctx.call.params.destination ?? '');
+  return answer(ctx, await accept(ctx, { destination, headers: headersOf(ctx), body: ctx.text ?? '', queue: String(ctx.call.params.queueName ?? '') }, ownerFor(ctx)));
+};
+
+/** POST /v2/batch: each entry `{destination, headers, body, queue}` is published as its own message, in order, and the
+ *  answer lists each one's `PublishResponse`. Where the documents stop and the lane decides: an entry that cannot be
+ *  published refuses the whole batch with its reason, before any later entry is published. */
+const batch: Semantics = async (ctx) => {
+  if (!Array.isArray(ctx.body)) return refuse(ctx, 400, 'The request body must be a JSON array of messages.');
+  const owner = ownerFor(ctx);
+  const out: Row[] = [];
+  for (const entry of ctx.body as Row[]) {
+    const destination = typeof entry?.destination === 'string' ? entry.destination : '';
+    if (!destination) return refuse(ctx, 400, 'destination is required');
+    const body = typeof entry.body === 'string' ? entry.body : entry.body === undefined ? '' : JSON.stringify(entry.body);
+    const a = await accept(ctx, { destination, headers: lowerKeys(entry.headers as Row), body, ...(typeof entry.queue === 'string' ? { queue: entry.queue } : {}) }, owner);
+    if (!Array.isArray(a) && 'error' in a) return refuse(ctx, a.status, a.error);
+    out.push(a as Row);
+  }
+  return ctx.reply(out);
+};
+
+/** A message still to be delivered: "Messages are removed from the database shortly after they're delivered, so you will
+ *  not be able to retrieve a message after." (the spec's get). The lane answers 404 once a message is delivered, failed
+ *  or cancelled. */
+function pending(ctx: SemanticsContext, id: string): Row | undefined {
+  const m = ctx.rowsRaw('Message').find((r) => r.messageId === id);
+  return m && ['CREATED', 'ACTIVE', 'RETRY', 'CANCEL_REQUESTED'].includes(String(m.state)) ? m : undefined;
+}
+
+/** GET /v2/messages/{messageId}. */
+const getMessage: Semantics = async (ctx) => {
+  const m = pending(ctx, String(ctx.call.params.messageId));
+  return m ? ctx.reply(redacted(vendorFields(ctx, m, MESSAGE_FIELDS), m)) : refuse(ctx, 404, 'Message not found.');
+};
+
+/** DELETE /v2/messages/{messageId}: "Cancel a pending message"; it is CANCELLED at its next delivery time (debug-logs),
+ *  never delivered. Answered 202 with no body (the spec's 202). */
+const cancelMessage: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.messageId);
+  const m = ctx.rowsRaw('Message').find((r) => r.messageId === id);
+  if (!m) return refuse(ctx, 404, 'Message not found.');
+  const refused = ctx.legal('Message', 'state', 'delete_v2_messages_messageid', m.state, 'CANCEL_REQUESTED', id);
+  if (refused) return ctx.refuse(refused);
+  await ctx.write('Message', String(m.id), { state: 'CANCEL_REQUESTED' }, 'message.cancel');
+  return new Response(null, { status: 202 });
+};
+
+export const messageSemantics: Record<string, Semantics> = {
+  post_v2_publish_destination: publish,
+  post_v2_enqueue_queuename_destination: enqueue,
+  post_v2_batch: batch,
+  get_v2_messages_messageid: getMessage,
+  delete_v2_messages_messageid: cancelMessage,
+};
+
+/** A message's fields as the API answers them after redaction: "QStash allows you to redact specific fields so they appear
+ *  as `REDACTED:<SHA256>` in the dashboard and API. The original values are still used when delivering messages to your
+ *  endpoint." (https://upstash.com/docs/qstash/howto/redact-fields); `Upstash-Redact-Fields` names `body`, `header` (all)
+ *  or `header[<name>]`. Where the page stops and the lane decides: the SHA-256 is of the value, in hex. */
+export function redacted(view: Row, row: Row): Row {
+  const spec = typeof row._redact === 'string' ? row._redact : '';
+  if (!spec) return view;
+  const parts = spec.split(',').map((x) => x.trim());
+  const sha = (v: string): string => `REDACTED:${createHash('sha256').update(v).digest('hex')}`;
+  const out: Row = { ...view };
+  if (parts.includes('body') && typeof out.body === 'string') out.body = sha(out.body);
+  const all = parts.includes('header') || parts.includes('headers');
+  const names = parts.map((x) => /^headers?\[(.+)\]$/.exec(x)?.[1]?.toLowerCase()).filter((x): x is string => !!x);
+  if ((all || names.length) && out.header && typeof out.header === 'object') {
+    out.header = Object.fromEntries(Object.entries(out.header as Record<string, string[]>).map(([k, v]) => [k, all || names.includes(k.toLowerCase()) ? v.map(sha) : v]));
+  }
+  return out;
+}

package/dist/qstash/src/semantics/queues.d.ts

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare const queueSemantics: Record<string, Semantics>;

package/dist/qstash/src/semantics/queues.js

@@ -0,0 +1,60 @@
+import { nowMs, QUEUE_NAME, refuse } from "./shared.js";
+const INVALID = 'Queue name is invalid. Queue names can only contain alphanumeric characters, hyphens, periods, and underscores.';
+const queueOf = (ctx, name) => ctx.rowsRaw('Queue').find((r) => r.name === name);
+/** A queue as the spec's `Queue` answers it; `lag`, "The number of unprocessed messages that exist in the queue". */
+function view(ctx, q) {
+    const lag = ctx.rowsRaw('Message').filter((m) => m.queueName === q.name && ['CREATED', 'RETRY', 'ACTIVE'].includes(String(m.state))).length;
+    return { name: q.name, createdAt: q.createdAt, updatedAt: q.updatedAt, parallelism: q.parallelism, paused: q.paused === true, lag };
+}
+/** POST /v2/queues {queueName, parallelism}: "Updates or creates a queue" (the spec). Answered 200 with no body. A name
+ *  that is not a queue name answers the spec's 400; a parallelism below 1 ("Must be greater than 0") a 400 of the lane's
+ *  wording. */
+const upsert = async (ctx) => {
+    const b = (ctx.body && typeof ctx.body === 'object' ? ctx.body : {});
+    const name = typeof b.queueName === 'string' ? b.queueName : '';
+    if (!QUEUE_NAME.test(name))
+        return refuse(ctx, 400, INVALID);
+    const parallelism = b.parallelism === undefined ? 1 : Number(b.parallelism);
+    if (!Number.isInteger(parallelism) || parallelism < 1)
+        return refuse(ctx, 400, 'parallelism must be greater than 0');
+    const q = queueOf(ctx, name);
+    const at = nowMs(ctx);
+    await ctx.write('Queue', q ? String(q.id) : name, { name, createdAt: q?.createdAt ?? at, updatedAt: at, parallelism, paused: q?.paused === true }, q ? 'queue.update' : 'queue.create');
+    return new Response(null, { status: 200 });
+};
+/** GET /v2/queues/{queueName}: the queue, or the spec's 404 "Queue not found". */
+const get = async (ctx) => {
+    const q = queueOf(ctx, String(ctx.call.params.queueName));
+    return q ? ctx.reply(view(ctx, q)) : refuse(ctx, 404, 'Queue not found');
+};
+/** POST /v2/queues/{queueName}/pause and /resume: "Pausing a queue stops the delivery of enqueued messages. The queue
+ *  continues to accept new messages, but they will not be delivered until the queue is resumed. If the queue is already
+ *  paused, this action has no effect." and "Resuming a queue starts the delivery of enqueued messages, beginning with the
+ *  earliest undelivered message." (the spec). Answered 200 with no body. Where the spec stops and the lane decides: a
+ *  queue it does not hold answers 404, as its read does. */
+const setPaused = (paused) => async (ctx) => {
+    const q = queueOf(ctx, String(ctx.call.params.queueName));
+    if (!q)
+        return refuse(ctx, 404, 'Queue not found');
+    if (q.paused !== paused)
+        await ctx.write('Queue', String(q.id), { paused, updatedAt: nowMs(ctx) }, paused ? 'queue.pause' : 'queue.resume');
+    return new Response(null, { status: 200 });
+};
+/** DELETE /v2/queues/{queueName}: the queue is gone. Answered 200 with no body (the spec's 200). Where the documentation
+ *  stops and the lane decides: messages already enqueued in it are delivered as they were; a queue the World does not
+ *  hold answers 404. */
+const remove = async (ctx) => {
+    const name = String(ctx.call.params.queueName);
+    const q = queueOf(ctx, name);
+    if (!q)
+        return refuse(ctx, 404, `Queue ${name} not found.`);
+    await ctx.write('Queue', String(q.id), { deleted: true }, 'queue.delete');
+    return new Response(null, { status: 200 });
+};
+export const queueSemantics = {
+    post_v2_queues: upsert,
+    get_v2_queues_queuename: get,
+    post_v2_queues_queuename_pause: setPaused(true),
+    post_v2_queues_queuename_resume: setPaused(false),
+    delete_v2_queues_queuename: remove,
+};

package/dist/qstash/src/semantics/queues.ts

@@ -0,0 +1,66 @@
+// Queues: "The queue concept in QStash allows ordered delivery (FIFO)." (https://upstash.com/docs/qstash/features/queues).
+// A queue is made by its first enqueue (messages.ts) or its upsert; the lane serves its upsert, its read, its pause and
+// resume, and its removal. How a queue delivers (its order, its parallelism, its pause) is the catch-up's (delivery.ts).
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { nowMs, QUEUE_NAME, refuse, type Row } from './shared.ts';
+
+const INVALID = 'Queue name is invalid. Queue names can only contain alphanumeric characters, hyphens, periods, and underscores.';
+const queueOf = (ctx: SemanticsContext, name: string): Row | undefined => ctx.rowsRaw('Queue').find((r) => r.name === name);
+
+/** A queue as the spec's `Queue` answers it; `lag`, "The number of unprocessed messages that exist in the queue". */
+function view(ctx: SemanticsContext, q: Row): Row {
+  const lag = ctx.rowsRaw('Message').filter((m) => m.queueName === q.name && ['CREATED', 'RETRY', 'ACTIVE'].includes(String(m.state))).length;
+  return { name: q.name, createdAt: q.createdAt, updatedAt: q.updatedAt, parallelism: q.parallelism, paused: q.paused === true, lag };
+}
+
+/** POST /v2/queues {queueName, parallelism}: "Updates or creates a queue" (the spec). Answered 200 with no body. A name
+ *  that is not a queue name answers the spec's 400; a parallelism below 1 ("Must be greater than 0") a 400 of the lane's
+ *  wording. */
+const upsert: Semantics = async (ctx) => {
+  const b = (ctx.body && typeof ctx.body === 'object' ? ctx.body : {}) as Row;
+  const name = typeof b.queueName === 'string' ? b.queueName : '';
+  if (!QUEUE_NAME.test(name)) return refuse(ctx, 400, INVALID);
+  const parallelism = b.parallelism === undefined ? 1 : Number(b.parallelism);
+  if (!Number.isInteger(parallelism) || parallelism < 1) return refuse(ctx, 400, 'parallelism must be greater than 0');
+  const q = queueOf(ctx, name);
+  const at = nowMs(ctx);
+  await ctx.write('Queue', q ? String(q.id) : name, { name, createdAt: q?.createdAt ?? at, updatedAt: at, parallelism, paused: q?.paused === true }, q ? 'queue.update' : 'queue.create');
+  return new Response(null, { status: 200 });
+};
+
+/** GET /v2/queues/{queueName}: the queue, or the spec's 404 "Queue not found". */
+const get: Semantics = async (ctx) => {
+  const q = queueOf(ctx, String(ctx.call.params.queueName));
+  return q ? ctx.reply(view(ctx, q)) : refuse(ctx, 404, 'Queue not found');
+};
+
+/** POST /v2/queues/{queueName}/pause and /resume: "Pausing a queue stops the delivery of enqueued messages. The queue
+ *  continues to accept new messages, but they will not be delivered until the queue is resumed. If the queue is already
+ *  paused, this action has no effect." and "Resuming a queue starts the delivery of enqueued messages, beginning with the
+ *  earliest undelivered message." (the spec). Answered 200 with no body. Where the spec stops and the lane decides: a
+ *  queue it does not hold answers 404, as its read does. */
+const setPaused = (paused: boolean): Semantics => async (ctx) => {
+  const q = queueOf(ctx, String(ctx.call.params.queueName));
+  if (!q) return refuse(ctx, 404, 'Queue not found');
+  if (q.paused !== paused) await ctx.write('Queue', String(q.id), { paused, updatedAt: nowMs(ctx) }, paused ? 'queue.pause' : 'queue.resume');
+  return new Response(null, { status: 200 });
+};
+
+/** DELETE /v2/queues/{queueName}: the queue is gone. Answered 200 with no body (the spec's 200). Where the documentation
+ *  stops and the lane decides: messages already enqueued in it are delivered as they were; a queue the World does not
+ *  hold answers 404. */
+const remove: Semantics = async (ctx) => {
+  const name = String(ctx.call.params.queueName);
+  const q = queueOf(ctx, name);
+  if (!q) return refuse(ctx, 404, `Queue ${name} not found.`);
+  await ctx.write('Queue', String(q.id), { deleted: true }, 'queue.delete');
+  return new Response(null, { status: 200 });
+};
+
+export const queueSemantics: Record<string, Semantics> = {
+  post_v2_queues: upsert,
+  get_v2_queues_queuename: get,
+  post_v2_queues_queuename_pause: setPaused(true),
+  post_v2_queues_queuename_resume: setPaused(false),
+  delete_v2_queues_queuename: remove,
+};

package/dist/qstash/src/semantics/schedules.d.ts

@@ -0,0 +1,19 @@
+import type { Semantics } from '@volter/world-core';
+type Field = Set<number>;
+type Cron = {
+    minute: Field;
+    hour: Field;
+    dom: Field;
+    month: Field;
+    dow: Field;
+    domAny: boolean;
+    dowAny: boolean;
+    zone: string;
+};
+/** A cron expression's fields and zone, or undefined when it is not one the lane reads. */
+export declare function parseCron(expr: string): Cron | undefined;
+/** The first minute after `afterMs` the cron fires at, its fields read on the wall clock of its zone. Day of month and day
+ *  of week, both restricted, fire on either (the classic cron rule). A day or hour that cannot match is skipped whole. */
+export declare function nextFire(expr: string, afterMs: number): number | undefined;
+export declare const scheduleSemantics: Record<string, Semantics>;
+export {};

package/dist/qstash/src/semantics/schedules.js

@@ -0,0 +1,125 @@
+import { ownerFor, labelsOf, sentHeader } from "./messages.js";
+import { durationSeconds, everHeld, headersOf, mintId, nowMs, refuse } from "./shared.js";
+function field(spec, min, max) {
+    const out = new Set();
+    for (const part of spec.split(',')) {
+        const m = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/.exec(part);
+        if (!m)
+            return undefined;
+        const [lo, hi] = m[1] === '*' ? [min, max] : m[1].includes('-') ? m[1].split('-').map(Number) : [Number(m[1]), m[2] ? max : Number(m[1])];
+        const step = m[2] ? Number(m[2]) : 1;
+        if (lo < min || hi > max || lo > hi || step < 1)
+            return undefined;
+        for (let v = lo; v <= hi; v += step)
+            out.add(v);
+    }
+    return out;
+}
+/** A cron expression's fields and zone, or undefined when it is not one the lane reads. */
+export function parseCron(expr) {
+    const tz = /^CRON_TZ=(\S+)\s+/.exec(expr.trim());
+    const zone = tz?.[1] ?? 'UTC';
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: zone });
+    }
+    catch {
+        return undefined;
+    }
+    const parts = expr.trim().replace(/^CRON_TZ=\S+\s+/, '').split(/\s+/);
+    if (parts.length !== 5)
+        return undefined;
+    const [mi, h, dom, mo, dow] = parts;
+    const f = { minute: field(mi, 0, 59), hour: field(h, 0, 23), dom: field(dom, 1, 31), month: field(mo, 1, 12), dow: field(dow.replace(/\b7\b/g, '0'), 0, 6) };
+    if (!f.minute || !f.hour || !f.dom || !f.month || !f.dow)
+        return undefined;
+    return { minute: f.minute, hour: f.hour, dom: f.dom, month: f.month, dow: f.dow, domAny: dom === '*', dowAny: dow === '*', zone };
+}
+/** The wall clock in a zone at an instant: month, day of month, day of week, hour, minute. */
+function wall(ms, zone) {
+    const parts = Object.fromEntries(new Intl.DateTimeFormat('en-US', { timeZone: zone, hourCycle: 'h23', month: 'numeric', day: 'numeric', weekday: 'short', hour: 'numeric', minute: 'numeric' })
+        .formatToParts(new Date(ms)).map((x) => [x.type, x.value]));
+    const dow = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].indexOf(String(parts.weekday));
+    return { month: Number(parts.month), dom: Number(parts.day), dow, hour: Number(parts.hour) % 24, minute: Number(parts.minute) };
+}
+/** The first minute after `afterMs` the cron fires at, its fields read on the wall clock of its zone. Day of month and day
+ *  of week, both restricted, fire on either (the classic cron rule). A day or hour that cannot match is skipped whole. */
+export function nextFire(expr, afterMs) {
+    const c = parseCron(expr);
+    if (!c)
+        return undefined;
+    let t = Math.floor(afterMs / 60_000) * 60_000 + 60_000;
+    const end = t + 366 * 86_400_000;
+    for (let skip = skipFrom(c, t); skip > 0 && t < end; skip = skipFrom(c, t))
+        t += skip;
+    return t < end ? t : neverFires();
+}
+/** How far past the minute `t` the cron's next candidate is: 0 when it fires at `t`, the rest of the day when the day
+ *  cannot match, the rest of the hour when the hour cannot, else a minute. */
+function skipFrom(c, t) {
+    const w = wall(t, c.zone);
+    const dayOk = c.domAny && c.dowAny ? true : c.domAny ? c.dow.has(w.dow) : c.dowAny ? c.dom.has(w.dom) : c.dom.has(w.dom) || c.dow.has(w.dow);
+    if (!c.month.has(w.month) || !dayOk)
+        return (60 - w.minute) * 60_000 + (23 - w.hour) * 3_600_000;
+    if (!c.hour.has(w.hour))
+        return (60 - w.minute) * 60_000;
+    return c.minute.has(w.minute) ? 0 : 60_000;
+}
+/** A cron no minute of the coming year meets (`0 0 30 2 *`, the 30th of February): it has no next time. */
+function neverFires() {
+    return undefined;
+}
+/** POST /v2/schedules/{destination}: a schedule of the message the request describes (its body, its `Upstash-*` headers),
+ *  answered `{scheduleId}`. `Upstash-Schedule-Id` names a schedule to create or overwrite (the spec's parameter). */
+const createSchedule = async (ctx) => {
+    const destination = String(ctx.call.params.destination ?? '');
+    const h = headersOf(ctx);
+    const cron = h['upstash-cron'];
+    if (!cron)
+        return refuse(ctx, 400, 'Upstash-Cron header is required');
+    const owner = ownerFor(ctx);
+    if (!/^https?:\/\//.test(destination) && !ctx.rowsRaw('URLGroup').some((g) => g.name === destination && g._owner === owner))
+        return refuse(ctx, 404, `URL Group ${destination} not found`);
+    const next = nextFire(cron, nowMs(ctx));
+    if (next === undefined)
+        return refuse(ctx, 400, `invalid cron expression: ${cron}`);
+    const id = h['upstash-schedule-id'] ?? mintId(ctx, 'scd_', 'schedule', everHeld(ctx, 'Schedule'));
+    const retries = h['upstash-retries'] !== undefined && /^\d+$/.test(h['upstash-retries']) ? Number(h['upstash-retries']) : 3;
+    const fields = {
+        scheduleId: id, cron, destination, createdAt: nowMs(ctx), method: h['upstash-method'] ?? 'POST', header: sentHeader(h), body: ctx.text ?? '',
+        retries, ...(durationSeconds(h['upstash-delay']) ? { delay: durationSeconds(h['upstash-delay']) } : {}),
+        ...(h['upstash-callback'] ? { callback: h['upstash-callback'] } : {}), ...(h['upstash-failure-callback'] ? { failureCallback: h['upstash-failure-callback'] } : {}),
+        isPaused: false, nextScheduleTime: next, ...labelsOf(h),
+        ...(h['upstash-queue-name'] ? { _queue: h['upstash-queue-name'] } : {}),
+        _owner: owner, _published: h,
+    };
+    await ctx.write('Schedule', id, fields, 'schedule.create');
+    return ctx.reply({ scheduleId: id });
+};
+const scheduleOf = (ctx) => ctx.rowsRaw('Schedule').find((s) => s.scheduleId === String(ctx.call.params.scheduleId));
+/** POST /v2/schedules/{scheduleId}/pause, and the PATCH the vendor's clients send (the spec patch): its cron is ignored from
+ *  now on. Answered 200 with no body. */
+const pause = async (ctx) => {
+    const s = scheduleOf(ctx);
+    if (!s)
+        return refuse(ctx, 404, 'Schedule not found.');
+    const refused = ctx.legal('Schedule', 'isPaused', ctx.call.operation.id, s.isPaused === true);
+    if (refused)
+        return ctx.refuse(refused);
+    if (s.isPaused !== true)
+        await ctx.write('Schedule', String(s.id), { isPaused: true }, 'schedule.pause');
+    return new Response(null, { status: 200 });
+};
+/** DELETE /v2/schedules/{scheduleId}: it fires no more. Answered 200 with no body. */
+const remove = async (ctx) => {
+    const s = scheduleOf(ctx);
+    if (!s)
+        return refuse(ctx, 404, 'Schedule not found.');
+    await ctx.write('Schedule', String(s.id), { deleted: true }, 'schedule.delete');
+    return new Response(null, { status: 200 });
+};
+export const scheduleSemantics = {
+    post_v2_schedules_destination: createSchedule,
+    post_v2_schedules_scheduleid_pause: pause,
+    patch_v2_schedules_scheduleid_pause: pause,
+    delete_v2_schedules_scheduleid: remove,
+};