@volter/world-core 2.0.0

package/src/derived.ts

@@ -0,0 +1,176 @@
+// THE DERIVED DISPATCH — the generated wire's router (docs/contributing/architecture.md, "The derived
+// pack"). A derived pack's surface (`src/generated/surface.gen.json`, written by scripts/derive-pack.ts)
+// names every operation the vendor publishes. This matches a request to one of them and hands it to its
+// owner: the pack's semantics handler for that operationId when there is one, otherwise the pack's
+// existing fetch, which keeps serving everything not yet moved (and every route outside the spec, such
+// as the `/twin` door). `owners` says, per operation, which of the two serves it: the count a pack's
+// move is measured by. Workerd-clean: no fs, no clock, nothing at import.
+
+/** The slice of a generated surface the dispatch reads. */
+export type DerivedOperation = {
+  id: string;
+  method: string;
+  path: string;
+  class: string;
+  resource?: string;
+  /** query values that tell this operation from another at the same method and path */
+  discriminator?: Record<string, string | null>;
+  /** request headers that name the operation, for a wire whose operations share a path (AWS JSON's X-Amz-Target) */
+  headers?: Record<string, string | null>;
+  /** the status the vendor answers success with (201 for a create, 204 for an empty answer) */
+  successStatus?: number;
+  /** a form-encoded operation's number and boolean fields, by bracket path (`items.[].quantity`, `metadata.*`) */
+  scalars?: Readonly<Record<string, string | undefined>>;
+  /** what the success answer is: a resource, a list of them, and the envelope key holding it */
+  answers?: { resource: string; list: boolean; key?: string };
+  /** the path its own server puts before it, where the operation names a server other than the surface's */
+  basePath?: string;
+};
+/** `basePath` is what the vendor's server URL puts before every operation path; `spanning` names the
+ *  path parameters whose values may hold slashes (a git ref, a file path), which no spec says. */
+export type DerivedSurface = { version: string; basePath?: string; spanning?: ReadonlyArray<string>; operations: ReadonlyArray<DerivedOperation> };
+
+/** What a semantics handler receives: the request, the operation it matched, and its path parameters. */
+export type DerivedCall = { request: Request; operation: DerivedOperation; params: Record<string, string> };
+export type DerivedHandler = (call: DerivedCall) => Promise<Response>;
+
+/** What the derived core made of an operation: an answer, or why it cannot model it. */
+export type DerivedCoreOutcome = { served: Response } | { unmodeled: string };
+
+export type DerivedFetchOptions = {
+  surface: DerivedSurface;
+  /** Semantics handlers by operationId. A handler naming an operation the surface lacks is refused. */
+  handlers?: Record<string, DerivedHandler>;
+  /** The derived core, and which operations it owns (those of the resources the manifest declares). */
+  core?: { owns: (operation: DerivedOperation) => boolean; serve: (call: DerivedCall) => Promise<DerivedCoreOutcome> };
+  /** An RPC wire: every method is reached by any HTTP method (Slack's clients POST reads too). */
+  anyMethod?: boolean;
+  /** The pack's existing fetch while it moves: everything no handler or core owns, and what the core cannot model. */
+  legacy?: (request: Request) => Promise<Response>;
+  /** What every operation a handler or the core serves passes through (read-only refusal, version
+   *  checks, idempotent replay); the pack's existing fetch keeps its own while it moves. */
+  around?: (call: DerivedCall, next: () => Promise<Response>) => Promise<Response>;
+  /** The vendor's answer for an operation nothing models: the pack's gap. */
+  gap: (request: Request, operation: DerivedOperation | undefined, reason: string) => Response;
+};
+
+class Unmodeled extends Error {}
+
+type Route = { operation: DerivedOperation; pattern: RegExp; names: string[]; literals: number };
+
+function compile(operation: DerivedOperation, basePath: string, spanning: ReadonlySet<string>): Route {
+  const names: string[] = [];
+  let literals = 0;
+  const body = ((operation.basePath ?? basePath) + operation.path)
+    .split('/')
+    .map((seg) => {
+      const m = /^\{([^}]+)\}$/.exec(seg);
+      if (m) {
+        names.push(m[1]!);
+        // a parameter the vendor lets hold slashes (a ref, a file path) takes the rest of its segments
+        return spanning.has(m[1]!) ? '(.+?)' : '([^/]+)';
+      }
+      literals++;
+      // a segment templated in part (OpenAPI's `/report.{format}`, Tinybird's `/v0/pipes/{pipe}.json`) holds its
+      // labels between its literal text, and counts as literal: it is more specific than a bare label
+      return seg.split(/(\{[^}]+\})/).map((part) => {
+        const label = /^\{([^}]+)\}$/.exec(part);
+        if (!label) return part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        names.push(label[1]!);
+        return '([^/]+?)';
+      }).join('');
+    })
+    .join('/');
+  return { operation, pattern: new RegExp(`^${body}/?$`), names, literals };
+}
+
+const compiled = new WeakMap<DerivedSurface, Map<string, Route[]>>(); // cache: compiled routes per surface; a surface is immutable generated data
+
+/** Routes per method, most literal segments first, so `/v1/customers/search` wins over `/v1/customers/{customer}`. */
+export function compileSurface(surface: DerivedSurface): Map<string, Route[]> {
+  const hit = compiled.get(surface);
+  if (hit) return hit;
+  const byMethod = new Map<string, Route[]>();
+  for (const operation of surface.operations) {
+    const method = operation.method.toUpperCase();
+    const list = byMethod.get(method) ?? [];
+    list.push(compile(operation, surface.basePath ?? '', new Set(surface.spanning ?? [])));
+    byMethod.set(method, list);
+  }
+  // most literal segments first; among equals, an operation with a query discriminator before the one without
+  const disc = (r: Route): number => Object.keys(r.operation.discriminator ?? {}).length + Object.keys(r.operation.headers ?? {}).length;
+  for (const list of byMethod.values()) list.sort((a, b) => b.literals - a.literals || disc(b) - disc(a) || a.operation.path.localeCompare(b.operation.path));
+  compiled.set(surface, byMethod);
+  return byMethod;
+}
+
+export function matchOperation(routes: Map<string, Route[]>, method: string, pathname: string, query?: URLSearchParams, headers?: Headers): { operation: DerivedOperation; params: Record<string, string> } | undefined {
+  for (const route of routes.get(method.toUpperCase()) ?? []) {
+    const m = route.pattern.exec(pathname);
+    if (!m) continue;
+    // a null value asks only that the key be present (S3's UploadPart, `uploadId`)
+    if (Object.entries(route.operation.discriminator ?? {}).some(([k, v]) => (v === null ? !query?.has(k) : query?.get(k) !== v))) continue;
+    if (Object.entries(route.operation.headers ?? {}).some(([k, v]) => (v === null ? !headers?.has(k) : headers?.get(k) !== v))) continue;
+    const params: Record<string, string> = {};
+    try {
+      route.names.forEach((name, i) => {
+        params[name] = decodeURIComponent(m[i + 1]!);
+      });
+    } catch {
+      // a malformed escape matches no operation: whoever serves unmatched requests answers it
+      return undefined;
+    }
+    return { operation: route.operation, params };
+  }
+  return undefined;
+}
+
+export type DerivedOwner = 'handler' | 'core' | 'legacy' | 'gap';
+
+export type DerivedFetch = ((request: Request) => Promise<Response>) & {
+  /** Per operationId, who serves it: a semantics handler, the derived core, the pack's existing
+   *  fetch while it moves, or nothing (the vendor's gap). */
+  owners(): Record<string, DerivedOwner>;
+};
+
+export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
+  const handlers = options.handlers ?? {};
+  const known = new Set(options.surface.operations.map((o) => o.id));
+  const unknown = Object.keys(handlers).filter((id) => !known.has(id));
+  if (unknown.length) throw new Error(`derived dispatch: handlers name operations the surface does not have: ${unknown.sort().join(', ')}`);
+  const routes = compileSurface(options.surface);
+  const fallback = (request: Request, operation: DerivedOperation | undefined, reason: string): Promise<Response> =>
+    options.legacy ? options.legacy(request) : Promise.resolve(options.gap(request, operation, reason));
+  const fetch = (async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const matched = options.anyMethod
+      ? [...routes.keys()].map((m) => matchOperation(routes, m, url.pathname, url.searchParams, request.headers)).find(Boolean)
+      : matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
+    if (!matched) return fallback(request, undefined, 'no operation at this path');
+    const call: DerivedCall = { request, operation: matched.operation, params: matched.params };
+    const around = options.around ?? ((_c: DerivedCall, next: () => Promise<Response>) => next());
+    const handler = handlers[matched.operation.id];
+    if (handler) return around(call, () => handler(call));
+    if (options.core?.owns(matched.operation)) {
+      // the core reads the body; a clone keeps it for whatever serves an operation the core cannot
+      // model, and that case leaves `around` by a throw, so nothing it records (an idempotent
+      // answer) is recorded for a request the core did not serve
+      try {
+        return await around(call, async () => {
+          const outcome = await options.core!.serve({ ...call, request: request.clone() });
+          if ('served' in outcome) return outcome.served;
+          throw new Unmodeled(outcome.unmodeled);
+        });
+      } catch (error) {
+        if (error instanceof Unmodeled) return fallback(request, matched.operation, error.message);
+        throw error;
+      }
+    }
+    return fallback(request, matched.operation, 'no handler');
+  }) as DerivedFetch;
+  fetch.owners = () =>
+    Object.fromEntries(
+      options.surface.operations.map((o) => [o.id, handlers[o.id] ? 'handler' : options.core?.owns(o) ? 'core' : options.legacy ? 'legacy' : 'gap'] as const),
+    );
+  return fetch;
+}

package/src/emit.ts

@@ -0,0 +1,242 @@
+// The DELIVER verb (`emit`) — fire a vendor-shaped, SIGNED webhook/event at the app under
+// test, synthesized from CURRENT TWIN STATE, without hand-constructing the envelope or the
+// signature. The engine here is vendor-agnostic; everything vendor-shaped (which event types
+// exist, which twin resource supplies `data.object`, where registered endpoints + signing
+// secrets live in state, how a delivery is signed) is a pack's knowledge, declared as a
+// `TwinEmitter` and registered on its `TwinPack.emitter` (same argument as `browserRouting`:
+// vendor knowledge in the descriptor, kernel stays vendor-agnostic).
+//
+// The operator surface is the PACK's bin (`world-stripe emit …`), exactly like the mirror
+// UIs — the kernel never imports packs, so `volter-twin emit <service>` only works when a
+// consumer registered the pack in-process, and otherwise fails loudly pointing at the
+// vendor bin. Unlike the twin's own background emission on state changes (fire-and-forget,
+// vendor-faithful), an explicit DELIVER is an operator asking for exactly this delivery, so
+// every failure here is LOUD: unknown event type, unknown subject, no registered endpoint,
+// and non-2xx delivery responses all throw / report instead of being swallowed.
+
+/** One event type a pack can synthesize, and the twin resource type that supplies its payload. */
+export type EmittableEvent = {
+  type: string;
+  /** twin resource type whose current state becomes the event payload (`data.object` for Stripe). */
+  subjectType: string;
+  description?: string;
+};
+
+/** A delivery destination registered IN TWIN STATE (at rest — the emit CLI runs in its own
+ *  process, so in-memory registries don't count; endpoints must be resolvable from the root). */
+export type EmitEndpoint = {
+  /** the vendor resource id of the registration (e.g. Stripe `we_…`), when it has one. */
+  id?: string;
+  url: string;
+  /** event-type subscriptions; `*` wildcards supported. Absent ⇒ subscribed to everything. */
+  enabledEvents?: string[];
+};
+
+/** A fully built, signed delivery for one endpoint: exact body bytes + headers to POST. */
+export type SynthesizedDelivery = {
+  /** the exact payload string — the signature covers THESE bytes, do not re-serialize. */
+  payload: string;
+  headers: Record<string, string>;
+  /** the synthesized event envelope (for reporting/assertions). */
+  event: Record<string, unknown>;
+};
+
+/** What a pack declares to support `emit` — see `TwinPack.emitter`. All state reads take the
+ *  same `root` every pack verb takes, so the CLI composes with worlds unchanged. */
+export type TwinEmitter = {
+  vendor: string;
+  /** the emittable catalog (drives `--list` and the unknown-event error). */
+  events(): EmittableEvent[];
+  /** endpoints registered in twin state (e.g. Stripe webhook_endpoint rows). */
+  endpoints(root?: string): EmitEndpoint[];
+  /** subject ids present in state for a subject type (drives `--list` + unknown-subject errors). */
+  subjects(subjectType: string, root?: string): string[];
+  /** synthesize the signed delivery for one endpoint. MUST throw loudly on an unknown subject. */
+  synthesize(opts: { type: string; subjectId: string; endpoint: EmitEndpoint; root?: string; occurredAt?: string }): SynthesizedDelivery;
+};
+
+export type EmitDeliveryResult = {
+  endpoint: EmitEndpoint;
+  ok: boolean;
+  /** HTTP status when the POST completed; absent when the request itself failed. */
+  status?: number;
+  error?: string;
+  event: Record<string, unknown>;
+};
+
+export type EmitReport = {
+  vendor: string;
+  type: string;
+  subjectId: string;
+  deliveries: EmitDeliveryResult[];
+  /** true only when EVERY delivery reached its endpoint and got a 2xx back. */
+  ok: boolean;
+};
+
+/** Vendor wildcard subscription match (Stripe semantics: `*` matches all;
+ *  `invoice.*` matches every invoice event; otherwise exact). */
+export function eventSubscriptionMatches(pattern: string, type: string): boolean {
+  if (pattern === '*') return true;
+  if (pattern.endsWith('.*')) return type.startsWith(pattern.slice(0, -1));
+  return pattern === type;
+}
+
+function endpointSubscribed(endpoint: EmitEndpoint, type: string): boolean {
+  if (!endpoint.enabledEvents || endpoint.enabledEvents.length === 0) return true;
+  return endpoint.enabledEvents.some((p) => eventSubscriptionMatches(p, type));
+}
+
+/** The `--list` view: everything emittable right now — event types, the subject ids present in
+ *  state for each subject type, and the registered endpoints. Pure state read. */
+export function listEmittable(emitter: TwinEmitter, root?: string): {
+  vendor: string;
+  events: Array<EmittableEvent & { subjects: string[] }>;
+  endpoints: EmitEndpoint[];
+} {
+  const subjectsByType = new Map<string, string[]>();
+  const events = emitter.events().map((e) => {
+    let subjects = subjectsByType.get(e.subjectType);
+    if (!subjects) {
+      subjects = emitter.subjects(e.subjectType, root);
+      subjectsByType.set(e.subjectType, subjects);
+    }
+    return { ...e, subjects };
+  });
+  return { vendor: emitter.vendor, events, endpoints: emitter.endpoints(root) };
+}
+
+/**
+ * DELIVER: synthesize the event for (`type`, `subjectId`) from current twin state and POST it,
+ * signed, to every registered endpoint subscribed to that event type (or the one endpoint
+ * `endpoint` names by url or id). Loud failures:
+ *   • event type the pack can't synthesize → throws, listing the emittable types;
+ *   • unknown subject id → the pack's synthesize throws (listing available ids);
+ *   • no registered/subscribed endpoint → throws (register one via the vendor API first);
+ *   • a delivery that errors or comes back non-2xx → reported per-endpoint, report.ok=false.
+ * `fetchFn` is the delivery seam (tests inject; default real fetch).
+ */
+export async function emitTwinEvent(
+  emitter: TwinEmitter,
+  opts: {
+    type: string;
+    subjectId: string;
+    root?: string;
+    /** restrict delivery to the endpoint with this url or vendor id. */
+    endpoint?: string;
+    occurredAt?: string;
+    fetchFn?: (url: string, init: { method: string; headers: Record<string, string>; body: string }) => Promise<{ status: number }>;
+  },
+): Promise<EmitReport> {
+  const catalog = emitter.events();
+  const known = catalog.find((e) => e.type === opts.type);
+  if (!known) {
+    throw new Error(
+      `emit: the ${emitter.vendor} pack cannot synthesize "${opts.type}". Emittable event types:\n  ${catalog.map((e) => `${e.type} (subject: ${e.subjectType})`).join('\n  ')}`,
+    );
+  }
+
+  const all = emitter.endpoints(opts.root);
+  if (all.length === 0) {
+    throw new Error(
+      `emit: no ${emitter.vendor} webhook endpoint is registered in twin state — nothing to deliver to. ` +
+        `Register one through the vendor API first (for Stripe: POST /v1/webhook_endpoints with url + enabled_events).`,
+    );
+  }
+  let targets = all.filter((e) => endpointSubscribed(e, opts.type));
+  if (opts.endpoint) {
+    targets = targets.filter((e) => e.url === opts.endpoint || e.id === opts.endpoint);
+    if (targets.length === 0) {
+      throw new Error(
+        `emit: no registered endpoint matches "${opts.endpoint}" for event "${opts.type}". Registered endpoints:\n  ${all.map((e) => `${e.id ?? '-'} ${e.url} [${(e.enabledEvents ?? ['*']).join(', ')}]`).join('\n  ')}`,
+      );
+    }
+  }
+  if (targets.length === 0) {
+    throw new Error(
+      `emit: ${all.length} endpoint(s) registered but none subscribes to "${opts.type}". Registered endpoints:\n  ${all.map((e) => `${e.id ?? '-'} ${e.url} [${(e.enabledEvents ?? ['*']).join(', ')}]`).join('\n  ')}`,
+    );
+  }
+
+  const fetchFn = opts.fetchFn ?? (async (url: string, init: { method: string; headers: Record<string, string>; body: string }) => {
+    const res = await fetch(url, init);
+    return { status: res.status };
+  });
+
+  const deliveries: EmitDeliveryResult[] = [];
+  for (const endpoint of targets) {
+    // synthesize PER ENDPOINT: signatures are per-endpoint secrets (real Stripe signs each
+    // delivery with the destination endpoint's own whsec). Unknown subject throws here — loudly.
+    const built = emitter.synthesize({ type: opts.type, subjectId: opts.subjectId, endpoint, ...(opts.root !== undefined ? { root: opts.root } : {}), ...(opts.occurredAt !== undefined ? { occurredAt: opts.occurredAt } : {}) });
+    try {
+      const res = await fetchFn(endpoint.url, { method: 'POST', headers: built.headers, body: built.payload });
+      deliveries.push({ endpoint, ok: res.status >= 200 && res.status < 300, status: res.status, event: built.event, ...(res.status >= 200 && res.status < 300 ? {} : { error: `endpoint responded ${res.status}` }) });
+    } catch (error) {
+      deliveries.push({ endpoint, ok: false, error: error instanceof Error ? error.message : String(error), event: built.event });
+    }
+  }
+  return { vendor: emitter.vendor, type: opts.type, subjectId: opts.subjectId, deliveries, ok: deliveries.every((d) => d.ok) };
+}
+
+/**
+ * Shared CLI glue so every pack's `emit` verb behaves identically:
+ *   world-<vendor> emit --list [--root DIR] [--json]
+ *   world-<vendor> emit <event.type> <subject-id> [--root DIR] [--endpoint URL|ID] [--at ISO] [--json]
+ * Returns the process exit code (0 delivered; 1 loud failure / any failed delivery; 2 usage).
+ */
+export async function runEmitCli(
+  emitter: TwinEmitter,
+  argv: string[],
+  io: { out: (s: string) => void; err: (s: string) => void } = { out: (s) => process.stdout.write(s), err: (s) => process.stderr.write(s) },
+): Promise<number> {
+  const flags = new Map<string, string>();
+  const positional: string[] = [];
+  let list = false;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    if (a === '--list') list = true;
+    else if (a === '--json') json = true;
+    else if (a.startsWith('--')) {
+      flags.set(a, argv[i + 1] ?? '');
+      i += 1;
+    } else positional.push(a);
+  }
+  const root = flags.get('--root');
+
+  if (list) {
+    const view = listEmittable(emitter, root);
+    if (json) {
+      io.out(`${JSON.stringify(view, null, 2)}\n`);
+    } else {
+      io.out(`emittable ${view.vendor} events (synthesized from current twin state):\n`);
+      for (const e of view.events) {
+        io.out(`  ${e.type}  (subject: ${e.subjectType}${e.subjects.length ? ` — ${e.subjects.join(', ')}` : ' — none in state'})\n`);
+      }
+      io.out(view.endpoints.length === 0
+        ? 'no webhook endpoints registered — deliveries have nowhere to go.\n'
+        : `endpoints:\n${view.endpoints.map((e) => `  ${e.id ?? '-'} ${e.url} [${(e.enabledEvents ?? ['*']).join(', ')}]`).join('\n')}\n`);
+    }
+    return 0;
+  }
+
+  const [type, subjectId] = positional;
+  if (!type || !subjectId) {
+    io.err(`Usage: world-${emitter.vendor} emit --list [--root DIR] [--json]\n       world-${emitter.vendor} emit <event.type> <subject-id> [--root DIR] [--endpoint URL|ID] [--at ISO] [--json]\n`);
+    return 2;
+  }
+  try {
+    const endpointFlag = flags.get('--endpoint');
+    const at = flags.get('--at');
+    const report = await emitTwinEvent(emitter, { type, subjectId, ...(root !== undefined ? { root } : {}), ...(endpointFlag !== undefined ? { endpoint: endpointFlag } : {}), ...(at !== undefined ? { occurredAt: at } : {}) });
+    if (json) io.out(`${JSON.stringify(report, null, 2)}\n`);
+    else {
+      for (const d of report.deliveries) {
+        io.out(`${d.ok ? 'delivered' : 'FAILED'} ${report.type} (${String(d.event.id ?? '')}) → ${d.endpoint.url}${d.status !== undefined ? ` [${d.status}]` : ''}${d.error ? ` — ${d.error}` : ''}\n`);
+      }
+    }
+    return report.ok ? 0 : 1;
+  } catch (error) {
+    io.err(`${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+}