@volter/twin-upstash 0.1.0

package/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/qstash/src/semantics/schedules.ts

@@ -0,0 +1,132 @@
+// Schedules: "you can create a schedule, and we will publish the message in the given period. To create a schedule, you
+// simply need to add the `Upstash-Cron` header to your `publish` request." "By default, we evaluate cron expressions in
+// `UTC`." (https://upstash.com/docs/qstash/features/schedules). The catch-up publishes a schedule's message each time
+// its cron fires (delivery.ts); a paused schedule's trigger "will simply be ignored" (the spec's pause).
+//
+// "If you want to run your schedule in a specific timezone, see the section on Timezones": a `CRON_TZ=<IANA zone>` prefix
+// evaluates the expression in that zone ("CRON_TZ=America/New_York 0 4 * * *", the same page). `Upstash-Queue-Name` enqueues
+// each message the schedule publishes into that queue (the page's "Scheduling to a Queue").
+// Where the documentation stops and the lane decides: the cron is the five standard fields (minute, hour, day of month,
+// month, day of week) with `*`, lists, ranges and steps; a zone the runtime does not know answers 400; a
+// schedule is first due at its cron's first minute after it is made ("It can take up to 60 seconds for the schedule to be
+// loaded on an active node and triggered for the first time": the lane loads it at once).
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { ownerFor, labelsOf, sentHeader } from './messages.ts';
+import { durationSeconds, everHeld, headersOf, mintId, nowMs, refuse, type Row } from './shared.ts';
+
+type Field = Set<number>;
+
+function field(spec: string, min: number, max: number): Field | undefined {
+  const out = new Set<number>();
+  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) as [number, 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;
+}
+
+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 function parseCron(expr: string): Cron | undefined {
+  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 as [string, string, string, string, string];
+  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: number, zone: string): { month: number; dom: number; dow: number; hour: number; minute: number } {
+  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: string, afterMs: number): number | undefined {
+  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: Cron, t: number): number {
+  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(): undefined {
+  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: Semantics = 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: Row = {
+    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: SemanticsContext): Row | undefined => 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: Semantics = 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: Semantics = 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: Record<string, Semantics> = {
+  post_v2_schedules_destination: createSchedule,
+  post_v2_schedules_scheduleid_pause: pause,
+  patch_v2_schedules_scheduleid_pause: pause,
+  delete_v2_schedules_scheduleid: remove,
+};

package/qstash/src/semantics/shared.ts

@@ -0,0 +1,121 @@
+// What the QStash lane's handlers share: the refusals, the request's headers, durations, ids and the views of stored
+// subjects in the documents' shapes. Where the documents stop and the lane decides, the comment beside the rule says so.
+import { createHash } from 'node:crypto';
+import type { SemanticsContext } from '@volter/world-core';
+
+export type Row = Record<string, unknown>;
+
+/** A refusal in the documents' `Error` schema, `{"error": "<message>"}`. */
+export const refuse = (ctx: SemanticsContext, status: number, message: string): Response => ctx.refuse({ status, message });
+
+/** The request's headers, lower-cased. */
+export function headersOf(ctx: SemanticsContext): Record<string, string> {
+  const out: Record<string, string> = {};
+  ctx.call.request.headers.forEach((v, k) => { out[k.toLowerCase()] = v; });
+  return out;
+}
+
+export function lowerKeys(h: Record<string, unknown> | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(h ?? {})) if (v !== undefined && v !== null) out[k.toLowerCase()] = String(v);
+  return out;
+}
+
+/** A header map as the documents answer one: each name to its list of values. */
+export function multiValue(h: Record<string, string> | undefined): Record<string, string[]> {
+  return Object.fromEntries(Object.entries(h ?? {}).map(([k, v]) => [k, [v]]));
+}
+
+/** A multi-valued map to single values (the first of each). */
+export function singleValue(h: Record<string, unknown> | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(h ?? {})) {
+    const first = Array.isArray(v) ? v[0] : v;
+    if (first !== undefined && first !== null) out[k.toLowerCase()] = String(first);
+  }
+  return out;
+}
+
+/** A duration as the delay page writes it: "The format for the duration is `<number><unit>`" (10s, 3m, 2h, 7d;
+ *  https://upstash.com/docs/qstash/features/delay), in seconds. A bare number is taken as seconds (the lane's decision:
+ *  the client's `delay` option is a number of seconds, which it writes as `<n>s`). Anything else is undefined. */
+export function durationSeconds(raw: unknown): number | undefined {
+  if (typeof raw === 'number' && Number.isFinite(raw) && raw >= 0) return raw;
+  if (typeof raw !== 'string') return undefined;
+  const s = raw.trim();
+  if (/^\d+$/.test(s)) return Number(s);
+  const m = /^(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/.exec(s);
+  if (!m || s === '') return undefined;
+  return Number(m[1] ?? 0) * 86_400 + Number(m[2] ?? 0) * 3600 + Number(m[3] ?? 0) * 60 + Number(m[4] ?? 0);
+}
+
+/** The World's instant as Unix milliseconds. */
+export const nowMs = (ctx: SemanticsContext): number => Date.parse(ctx.occurredAt);
+export const iso = (ms: number): string => new Date(ms).toISOString();
+
+const hex = (s: string): string => createHash('sha256').update(s).digest('hex');
+const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+/** An id of QStash's form (`msg_…`, `scd_…`, `wfr_…`) derived from the World's instant, the kind and how many of it
+ *  the World already holds, so a World mints the same ids every run. The characters are the twin's. */
+export function mintId(ctx: SemanticsContext, prefix: string, kind: string, count: number): string {
+  const h = hex(`qstash:${kind}:${ctx.occurredAt}:${count}`);
+  let out = '';
+  for (let i = 0; out.length < 26; i += 1) out += ALPHABET[parseInt(h.slice((i * 2) % 60, (i * 2) % 60 + 2), 16) % ALPHABET.length];
+  return `${prefix}${out}`;
+}
+
+/** Every subject of a stored type, the tombstoned ones too (an id is never minted twice). */
+export const everHeld = (ctx: SemanticsContext, resource: string): number => ctx.rowsRaw(resource, { withDeleted: true }).length;
+
+/** A stored subject's vendor fields: none of the kernel's, none of the lane's bookkeeping (`_`), and `state` only
+ *  where the document's schema carries it. */
+export function vendorFields(ctx: SemanticsContext, row: Row, keep: readonly string[]): Row {
+  const own = ctx.own(row);
+  const out: Row = {};
+  for (const k of keep) if (own[k] !== undefined && own[k] !== null) out[k] = own[k];
+  return out;
+}
+
+/** The `Message` schema's fields (the qstash document). */
+export const MESSAGE_FIELDS = ['messageId', 'url', 'topicName', 'endpointName', 'method', 'header', 'body', 'bodyBase64', 'maxRetries', 'notBefore', 'createdAt',
+  'callback', 'failureCallback', 'queueName', 'scheduleId', 'callerIP', 'label', 'labels', 'flowControlKey', 'rate', 'period', 'parallelism'] as const;
+
+/** A queue name: "Queue names can only contain alphanumeric characters, hyphens, periods, and underscores." (the spec's
+ *  pause and resume 400). */
+export const QUEUE_NAME = /^[A-Za-z0-9._-]+$/;
+
+/** The body of a request as the text it was sent. */
+export const textOf = (ctx: SemanticsContext): string => ctx.text ?? '';
+
+/** Base64 of a text, as QStash carries bodies and step results. */
+export const b64 = (s: string): string => Buffer.from(s, 'utf8').toString('base64');
+
+/** A query parameter's values, repeated or comma-separated ("Multiple values can be passed either by repeating the query
+ *  parameter (`label=label_1&label=label_2`) or as a single comma-separated value (`label=label_1,label_2`)", the spec's bulk
+ *  cancel). */
+export function queryValues(ctx: SemanticsContext, name: string): string[] {
+  return new URL(ctx.call.request.url).searchParams.getAll(name).flatMap((v) => v.split(',')).map((s) => s.trim()).filter(Boolean);
+}
+
+/** A bulk request's filter over stored subjects: each filter the request names, by the field it reads (a date range reads
+ *  `dateField`), "a workflow run matches if its value equals any of the given values (OR logic), and multiple filters are
+ *  combined with AND logic" (the spec's bulk cancel). `prefix` names the fields matched by prefix (a workflow URL without
+ *  `workflowUrlExactMatch`). Where the documentation stops and the lane decides: a filter whose field a subject lacks
+ *  excludes it. */
+export function matchesFilters(ctx: SemanticsContext, row: Row, fields: Record<string, string>, dateField: string, prefix: string[] = []): boolean {
+  const q = new URL(ctx.call.request.url).searchParams;
+  for (const [param, field] of Object.entries(fields)) {
+    const wanted = queryValues(ctx, param);
+    if (!wanted.length) continue;
+    const have = Array.isArray(row[field]) ? (row[field] as unknown[]).map(String) : row[field] === undefined || row[field] === null ? [] : [String(row[field])];
+    const hit = prefix.includes(param) ? have.some((h) => wanted.some((w) => h.startsWith(w))) : have.some((h) => wanted.includes(h));
+    if (!hit) return false;
+  }
+  const at = Number(row[dateField]);
+  const from = q.get('fromDate'); const to = q.get('toDate');
+  if (from !== null && !(at >= Number(from))) return false;
+  if (to !== null && !(at <= Number(to))) return false;
+  return true;
+}
+

package/qstash/src/semantics/urlgroups.ts

@@ -0,0 +1,69 @@
+// URL groups (the API calls them topics): "a URL Group is just a namespace where you can publish messages to, the same way
+// as publishing a message to an endpoint directly" and "When you publish a message to a URL Group, it will be fanned out and
+// sent to all the subscribed endpoints." (https://upstash.com/docs/qstash/features/url-groups). A message published to a group
+// is one message per endpoint (messages.ts); the lane serves the group's upsert of endpoints, its read, its list, the
+// removal of endpoints and the group's deletion.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { ownerFor } from './messages.ts';
+import { nowMs, refuse, type Row } from './shared.ts';
+
+type Endpoint = { url: string; name?: string };
+
+const groupOf = (ctx: SemanticsContext, name: string, owner: string): Row | undefined =>
+  ctx.rowsRaw('URLGroup').find((g) => g.name === name && g._owner === owner);
+
+function view(ctx: SemanticsContext, g: Row): Row {
+  const own = ctx.own(g);
+  return { name: own.name, createdAt: own.createdAt, updatedAt: own.updatedAt, endpoints: own.endpoints ?? [] };
+}
+
+function endpointsOf(ctx: SemanticsContext): Endpoint[] | undefined {
+  const list = (ctx.body as { endpoints?: unknown } | undefined)?.endpoints;
+  if (!Array.isArray(list)) return undefined;
+  return list.map((e) => e as Row).filter((e) => typeof e.url === 'string' || typeof e.name === 'string')
+    .map((e) => ({ ...(typeof e.url === 'string' ? { url: e.url } : { url: '' }), ...(typeof e.name === 'string' ? { name: e.name } : {}) }));
+}
+
+/** POST /v2/topics/{urlGroupName}/endpoints: "Add one or multiple endpoints to a URL Group. If the URL Group does not
+ *  exist, it will be created." (the spec). An endpoint the
+ *  group already has (the same URL) is replaced by the one sent. Answered 200 with no body. */
+const upsert: Semantics = async (ctx) => {
+  const name = String(ctx.call.params.urlGroupName);
+  const sent = endpointsOf(ctx);
+  if (!sent || !sent.length || sent.some((e) => !/^https?:\/\//.test(e.url))) return refuse(ctx, 400, 'endpoints must be a non-empty list of {url, name?} with an http or https url');
+  const owner = ownerFor(ctx);
+  const g = groupOf(ctx, name, owner);
+  const kept = ((g?.endpoints ?? []) as Endpoint[]).filter((e) => !sent.some((s) => s.url === e.url));
+  const at = nowMs(ctx);
+  await ctx.write('URLGroup', g ? String(g.id) : `${owner}:${name}`, { name, createdAt: g?.createdAt ?? at, updatedAt: at, endpoints: [...kept, ...sent], _owner: owner }, g ? 'url_group.update' : 'url_group.create');
+  return new Response(null, { status: 200 });
+};
+
+/** DELETE /v2/topics/{urlGroupName}/endpoints: the endpoints named (by URL or by name) leave the group. Answered 200. */
+const removeEndpoints: Semantics = async (ctx) => {
+  const g = groupOf(ctx, String(ctx.call.params.urlGroupName), ownerFor(ctx));
+  if (!g) return refuse(ctx, 404, `URL Group ${String(ctx.call.params.urlGroupName)} not found`);
+  const sent = endpointsOf(ctx) ?? [];
+  const endpoints = ((g.endpoints ?? []) as Endpoint[]).filter((e) => !sent.some((s) => (s.url && s.url === e.url) || (s.name !== undefined && s.name === e.name)));
+  await ctx.write('URLGroup', String(g.id), { endpoints, updatedAt: nowMs(ctx) }, 'url_group.update');
+  return new Response(null, { status: 200 });
+};
+
+export const urlGroupSemantics: Record<string, Semantics> = {
+  post_v2_topics_urlgroupname_endpoints: upsert,
+  delete_v2_topics_urlgroupname_endpoints: removeEndpoints,
+  get_v2_topics_urlgroupname: async (ctx) => {
+    const g = groupOf(ctx, String(ctx.call.params.urlGroupName), ownerFor(ctx));
+    return g ? ctx.reply(view(ctx, g)) : refuse(ctx, 404, `URL Group ${String(ctx.call.params.urlGroupName)} not found`);
+  },
+  get_v2_topics: async (ctx) => {
+    const owner = ownerFor(ctx);
+    return ctx.reply(ctx.rowsRaw('URLGroup').filter((g) => g._owner === owner).sort((a, b) => String(a.name).localeCompare(String(b.name))).map((g) => view(ctx, g)));
+  },
+  delete_v2_topics_urlgroupname: async (ctx) => {
+    const g = groupOf(ctx, String(ctx.call.params.urlGroupName), ownerFor(ctx));
+    if (!g) return refuse(ctx, 404, `URL Group ${String(ctx.call.params.urlGroupName)} not found`);
+    await ctx.write('URLGroup', String(g.id), { deleted: true }, 'url_group.delete');
+    return new Response(null, { status: 200 });
+  },
+};