@volter/twin-upstash 0.1.0

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

@@ -0,0 +1,61 @@
+// QStash's dead letter queue: "QStash automatically retries messages that fail due to a temporary issue but eventually
+// stops and moves the message to a dead letter queue to be handled manually." "Retry - Republish the message and remove
+// it from the dead letter queue. Republished messages are just like any other message and will be retried automatically if
+// they fail." (https://upstash.com/docs/qstash/features/dlq). A message is filed here by the catch-up when its retries are
+// spent (delivery.ts); an entry leaves when it is retried, or when its retention ends.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { ensureQueue, ownerFor, storeMessage } from './messages.ts';
+import { idsOf, workflowDlq } from './workflows.ts';
+import { matchesFilters, MESSAGE_FIELDS, type Row } from './shared.ts';
+import { redacted } from './messages.ts';
+
+const DLQ_FIELDS = [...MESSAGE_FIELDS, 'dlqId', 'responseStatus', 'responseHeader', 'responseBody', 'responseBodyBase64'];
+
+export function dlqView(ctx: SemanticsContext, e: Row): Row {
+  const own = ctx.own(e);
+  return redacted(Object.fromEntries(DLQ_FIELDS.filter((k) => own[k] !== undefined && own[k] !== null).map((k) => [k, own[k]])), e);
+}
+
+/** QStash's DLQ fields its list and bulk actions filter on, by query parameter (the spec's list and retry parameters). */
+const FILTERS = { url: 'url', topicName: 'topicName', scheduleId: 'scheduleId', queueName: 'queueName', responseStatus: 'responseStatus', label: 'labels', flowControlKey: 'flowControlKey', messageId: 'messageId', callerIp: 'callerIP' };
+
+/** The account's entries a request names: by `dlqIds`, else by its filters (all of them when it names none), oldest first. */
+function selected(ctx: SemanticsContext): Row[] {
+  const owner = ownerFor(ctx);
+  const mine = ctx.rowsRaw('DLQMessage').filter((e) => e._owner === owner);
+  const ids = idsOf(ctx, 'dlqIds');
+  return (ids.length ? mine.filter((e) => ids.includes(String(e.dlqId))) : mine.filter((e) => matchesFilters(ctx, e, FILTERS, '_filed_at')))
+    .sort((a, b) => Number(a._filed_at) - Number(b._filed_at));
+}
+
+/** GET /v2/dlq: QStash's failed messages, the latest to fail first, `{messages}` ("If no cursor is returned, you have reached the
+ *  end"); with `source=workflow`, the Workflow DLQ (the spec patch, from @upstash/workflow's `client.dlq.list`). */
+const list: Semantics = async (ctx) => {
+  if (new URL(ctx.call.request.url).searchParams.get('source') === 'workflow') return workflowDlq(ctx);
+  const count = Number(new URL(ctx.call.request.url).searchParams.get('count') ?? 0);
+  const all = selected(ctx).reverse();
+  return ctx.reply({ messages: (count > 0 ? all.slice(0, count) : all).map((e) => dlqView(ctx, e)) });
+};
+
+/** POST /v2/dlq/retry: each entry the request names (by `dlqIds`, by its filters, or all of them) is republished as a new
+ *  message (its destination, body and headers, in its queue) and leaves the DLQ; answered 201 `{responses: [{messageId}]}`.
+ *  An id the DLQ does not hold answers 404 (the spec's 404). */
+const retry: Semantics = async (ctx) => {
+  const ids = idsOf(ctx, 'dlqIds');
+  const entries = selected(ctx);
+  const missing = ids.find((id) => !entries.some((e) => e.dlqId === id));
+  if (missing) return ctx.refuse({ status: 404, message: `DLQ message ${missing} not found` });
+  const responses: Row[] = [];
+  for (const e of entries as Row[]) {
+    const published = (e._published ?? {}) as Record<string, string>;
+    const queue = typeof e.queueName === 'string' ? e.queueName : undefined;
+    if (queue) await ensureQueue(ctx, queue);
+    const { 'upstash-delay': _delay, 'upstash-not-before': _notBefore, ...headers } = published;
+    const messageId = await storeMessage(ctx, { url: String(e.url), headers, body: String(e.body ?? ''), owner: ownerFor(ctx), queue });
+    await ctx.write('DLQMessage', String(e.id), { deleted: true }, 'dlq.retried');
+    responses.push({ messageId });
+  }
+  return ctx.reply({ responses }, 201);
+};
+
+export const dlqSemantics: Record<string, Semantics> = { get_v2_dlq: list, post_v2_dlq_retry: retry };

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

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

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

@@ -0,0 +1,10 @@
+import { dlqSemantics } from "./dlq.js";
+import { keySemantics } from "./keys.js";
+import { messageSemantics } from "./messages.js";
+import { queueSemantics } from "./queues.js";
+import { scheduleSemantics } from "./schedules.js";
+import { workflowSemantics } from "./workflows.js";
+import { urlGroupSemantics } from "./urlgroups.js";
+export const qstashSemantics = {
+    ...messageSemantics, ...queueSemantics, ...scheduleSemantics, ...dlqSemantics, ...keySemantics, ...workflowSemantics, ...urlGroupSemantics,
+};

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

@@ -0,0 +1,13 @@
+// The QStash lane's handlers, by operationId (the IR's `method_path` slugs: neither document names its operations).
+import type { Semantics } from '@volter/world-core';
+import { dlqSemantics } from './dlq.ts';
+import { keySemantics } from './keys.ts';
+import { messageSemantics } from './messages.ts';
+import { queueSemantics } from './queues.ts';
+import { scheduleSemantics } from './schedules.ts';
+import { workflowSemantics } from './workflows.ts';
+import { urlGroupSemantics } from './urlgroups.ts';
+
+export const qstashSemantics: Record<string, Semantics> = {
+  ...messageSemantics, ...queueSemantics, ...scheduleSemantics, ...dlqSemantics, ...keySemantics, ...workflowSemantics, ...urlGroupSemantics,
+};

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

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

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

@@ -0,0 +1,9 @@
+import { accountOf, rollKeys } from "./account.js";
+import { ownerFor } from "./messages.js";
+export const keySemantics = {
+    get_v2_keys: async (ctx) => {
+        const a = accountOf(ctx, ownerFor(ctx));
+        return ctx.reply({ current: a.current, next: a.next });
+    },
+    post_v2_keys_rotate: async (ctx) => ctx.reply(await rollKeys(ctx, ownerFor(ctx))),
+};

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

@@ -0,0 +1,14 @@
+// The account's signing keys (account.ts): GET /v2/keys reads them, POST /v2/keys/rotate rolls them. "When you roll your
+// keys, the current key will be replaced with the next key and a new next key will be generated."
+// (https://upstash.com/docs/qstash/howto/roll-signing-keys); both answer `SigningKeys` `{current, next}`.
+import type { Semantics } from '@volter/world-core';
+import { accountOf, rollKeys } from './account.ts';
+import { ownerFor } from './messages.ts';
+
+export const keySemantics: Record<string, Semantics> = {
+  get_v2_keys: async (ctx) => {
+    const a = accountOf(ctx, ownerFor(ctx));
+    return ctx.reply({ current: a.current, next: a.next });
+  },
+  post_v2_keys_rotate: async (ctx) => ctx.reply(await rollKeys(ctx, ownerFor(ctx))),
+};

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

@@ -0,0 +1,74 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type Row } from './shared.js';
+/** How QStash retries by default: "By default, we retry a failed delivery 3 times." (https://upstash.com/docs/qstash/features/retry) */
+export declare const DEFAULT_RETRIES = 3;
+/** The account the request acts as (the lane's gate has admitted it). */
+export declare function ownerFor(ctx: SemanticsContext): string;
+/** 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 declare function forwarded(headers: Record<string, string>): Record<string, string>;
+/** 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 declare function sentHeader(headers: Record<string, string>): Record<string, string[]>;
+/** Store one message: the vendor's Message fields, its state (CREATED) and what the lane keeps to deliver it. */
+export declare 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>;
+/** 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 declare function labelsOf(h: Record<string, string>): Row;
+/** 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 declare function acceptPlain(ctx: SemanticsContext, p: Publication, owner: string): Promise<Accepted>;
+/** 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 declare function acceptToUrlGroup(ctx: SemanticsContext, p: Publication, owner: string): Promise<Accepted>;
+/** 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 declare function ensureQueue(ctx: SemanticsContext, name: string): Promise<void>;
+export declare const messageSemantics: Record<string, Semantics>;
+/** 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 declare function redacted(view: Row, row: Row): Row;

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

@@ -0,0 +1,233 @@
+// 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 { gate } from "./account.js";
+import { acceptWorkflowMessage, isWorkflowMessage } from "./workflows.js";
+import { durationSeconds, everHeld, headersOf, lowerKeys, MESSAGE_FIELDS, mintId, multiValue, nowMs, QUEUE_NAME, refuse, vendorFields } from "./shared.js";
+/** 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) {
+    const g = gate(ctx, ctx.call.request);
+    return 'owner' in g ? g.owner : 'world';
+}
+/** The `Upstash-Forward-*` headers, their prefix stripped: what the destination receives. */
+export function forwarded(headers) {
+    const out = {};
+    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) {
+    const canonical = (k) => 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) {
+    const out = {};
+    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, p) {
+    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 = {
+        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) {
+    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, body, h) {
+    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, p, owner) {
+    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, p, owner) {
+    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 = [];
+    for (const e of (group.endpoints ?? [])) {
+        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, name) {
+    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, p, owner) {
+    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, p, owner) {
+    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, a) => !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 = 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 = 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 = 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 = [];
+    for (const entry of ctx.body) {
+        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), 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);
+    }
+    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, id) {
+    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 = 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 = 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 = {
+    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) {
+    const spec = typeof row._redact === 'string' ? row._redact : '';
+    if (!spec)
+        return view;
+    const parts = spec.split(',').map((x) => x.trim());
+    const sha = (v) => `REDACTED:${createHash('sha256').update(v).digest('hex')}`;
+    const out = { ...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);
+    if ((all || names.length) && out.header && typeof out.header === 'object') {
+        out.header = Object.fromEntries(Object.entries(out.header).map(([k, v]) => [k, all || names.includes(k.toLowerCase()) ? v.map(sha) : v]));
+    }
+    return out;
+}