@kedge/testing 0.0.0-stage → 0.9.0

package/src/scenario.ts

@@ -0,0 +1,438 @@
+// A scenario DSL for workerd tests (K11): products, checkouts, placement,
+// expiry, cancellation, and the relay's release and shortage deliveries,
+// through the same stores, planning and runs the deployment uses, with every
+// D1 request counted. A merchant's agent
+// writes the business case; the DSL keeps the mechanics identical to
+// production, so a passing scenario means the deployed path works.
+import {
+  acquireSql,
+  BREAK,
+  type CartLine,
+  type CheckoutPlan,
+  type Consent,
+  capacityRequest,
+  Extensions,
+  factGuardSql,
+  installSql,
+  type JsonRecord,
+  type KedgeConfig,
+  KedgeError,
+  type OrderView,
+  planCheckout,
+  pluginReadSets,
+  priceCartView,
+  RELAY_LIMITS,
+  statementTexts,
+  type TestRuntime,
+  type TzTable,
+  testRuntime,
+  toSnapshot,
+  UTC_TZ,
+} from "@kedge/core";
+import {
+  D1CapacityStore,
+  D1CatalogStore,
+  D1CheckoutStore,
+  D1OrderStore,
+  D1RelayStore,
+  markedBatch,
+  runMarked,
+  runRelease,
+  runShortage,
+} from "@kedge/db";
+import { countRequests, type RequestCounter } from "./requests";
+
+/** What one pass of the relay's D1-only deliveries did. */
+export interface RelayPass {
+  delivered: number;
+  /** Failed and due again later. */
+  retried: number;
+  /** Failed on their last attempt: dead letters for staff. */
+  failed: number;
+  /** A plugin or handler missing from this config: kept pending, never dropped. */
+  orphaned: number;
+  /** `stock.shortage` events the pass emitted. */
+  shortages: number;
+}
+
+export interface ScenarioOptions {
+  db: D1Database;
+  config?: KedgeConfig;
+  runtime?: TestRuntime;
+  /** How long a pending order holds its stock; default 15 minutes. */
+  holdMs?: number;
+  /** The store's compiled timezone rules (P0.4 §4); UTC by default, matching a fresh database. */
+  tz?: TzTable;
+}
+
+/**
+ * A line as a scenario writes it: a plain item by default, or any kind with
+ * a parent (by index in the same list), a period and custom fields (P0.3).
+ */
+export interface ScenarioLine {
+  variantId: string;
+  quantity?: number;
+  kind?: string;
+  /** Index of the parent line in the same list. */
+  parent?: number;
+  quantityMode?: "own" | "per_parent";
+  quantityPerParent?: number;
+  periodStart?: number;
+  periodEnd?: number;
+  custom?: JsonRecord;
+}
+
+/** Scenario lines as cart lines, ids `cl_<index>`, per_parent quantities derived. */
+export function cartLines(lines: readonly ScenarioLine[]): CartLine[] {
+  return lines.map((l, i) => {
+    const parent = l.parent === undefined ? undefined : lines[l.parent];
+    const mode = l.quantityMode ?? "own";
+    const per = mode === "per_parent" ? (l.quantityPerParent ?? 1) : null;
+    return {
+      id: `cl_${i}`,
+      variantId: l.variantId,
+      kind: l.kind ?? "item",
+      parentId: l.parent === undefined ? null : `cl_${l.parent}`,
+      quantityMode: mode,
+      quantity: mode === "per_parent" ? (parent?.quantity ?? 1) * (per ?? 1) : (l.quantity ?? 1),
+      quantityPerParent: per,
+      periodStart: l.periodStart ?? null,
+      periodEnd: l.periodEnd ?? null,
+      custom: l.custom ?? {},
+    };
+  });
+}
+
+export interface CheckoutOutcome {
+  plan: CheckoutPlan;
+  order: OrderView;
+  /** D1 requests the checkout attempt made: 2 when nothing failed (claim, commit). */
+  requests: number;
+}
+
+export interface Scenario {
+  readonly db: D1Database;
+  readonly requests: RequestCounter;
+  readonly runtime: TestRuntime;
+  readonly extensions: Extensions;
+  /** P0.4's capacity administration, as staff would use it (pools, base changes, conversion). */
+  readonly capacity: D1CapacityStore;
+  /** Applies each configured plugin's migrations, generated SQL and install row, as `kedge generate` composes them. */
+  install(): Promise<void>;
+  product(opts?: {
+    price?: number;
+    stock?: number;
+    currency?: string;
+    /** Line kinds the variant may be sold as (P0.3 §2.2). */
+    kinds?: string[];
+    /** False for a component-free variant (a service). */
+    inventory?: boolean;
+  }): Promise<string>;
+  /**
+   * A product whose one item is tracked by date: stocked per location, then
+   * converted, so each location gets a pool with that base (P0.4 §2.1).
+   */
+  datedProduct(opts?: {
+    price?: number;
+    stock?: Record<string, number>;
+    kinds?: string[];
+    bucketMinutes?: number;
+  }): Promise<{ variantId: string; itemId: string; pools: string[] }>;
+  /** The cron's capacity maintenance and shortage discovery, until both are idle. */
+  maintain(): Promise<{ retired: number; ended: number; shortages: number }>;
+  /** The total a cart view would show for these lines: the `expected_total` a shopper sends. */
+  quote(email: string | null, lines: ScenarioLine[], currency?: string, customerId?: string | null): Promise<number>;
+  /** One checkout attempt: claim, plan, commit. Throws the KedgeError checkout would return. */
+  checkout(
+    email: string | null,
+    lines: ScenarioLine[],
+    opts?: {
+      expectedTotal?: number;
+      currency?: string;
+      cartId?: string;
+      /** Plays a signed-in customer; checkouts are guests otherwise, as every cart is until auth (P0.5). */
+      customerId?: string | null;
+      /** Runs between the claim and the commit: the window another shopper, or staff, can act in. */
+      beforeCommit?: () => Promise<void>;
+      /** The cart's own `order` custom fields, its consents and locale (P0.3). */
+      custom?: JsonRecord;
+      consents?: Record<string, Consent>;
+      locale?: string;
+    },
+  ): Promise<CheckoutOutcome>;
+  place(orderId: string): Promise<{ placed: boolean; order: OrderView }>;
+  /** Moves the clock past the order's hold and runs expiry. */
+  expire(orderId: string): Promise<void>;
+  cancel(orderId: string): Promise<void>;
+  /**
+   * Runs every due release delivery through the relay, once each, as the
+   * clock and the queue consumer would (p0.6a §2.6): a failed one backs off,
+   * so a second call runs it again only once it is due.
+   */
+  drainReleases(): Promise<RelayPass>;
+  setPluginState(plugin: string, state: "active" | "disabled"): Promise<void>;
+  rows<T = Record<string, unknown>>(sql: string, ...binds: unknown[]): Promise<T[]>;
+}
+
+// Each scenario gets its own seed, so ids from two scenarios in one store never collide.
+let seeds = 0;
+
+export function scenario(opts: ScenarioOptions): Scenario {
+  const runtime = opts.runtime ?? testRuntime(1_700_000_000_000, 1000 + ++seeds);
+  const extensions = Extensions.resolve(opts.config ?? {});
+  const requests = countRequests(opts.db);
+  const db = requests.db;
+  const { clock, ids, keys } = runtime;
+  const catalog = new D1CatalogStore(db, ids, clock, extensions.errors);
+  const checkout = new D1CheckoutStore(db, extensions.errors, 500, { sleep: async () => {} });
+  const orders = new D1OrderStore(db, ids, clock, extensions.errors);
+  const tz = opts.tz ?? UTC_TZ;
+  const capacity = new D1CapacityStore(db, ids, clock, tz, keys);
+  let commandKeys = 0;
+  const holdMs = opts.holdMs ?? 15 * 60_000;
+  let generation = 0;
+  const raw = opts.db;
+  const store = new D1RelayStore(raw, extensions.errors);
+  // Rows the triggers write are due by the database's clock, which a scenario's
+  // clock may trail: whichever is later is "now" to the relay.
+  const relayNow = () => Math.max(clock.now(), Date.now());
+
+  /**
+   * One pass of the relay's D1-only deliveries, to a stop: the clock's lease
+   * steps, then each claimed release and pending `core.shortage` delivery run
+   * as runtime-cf's consumer runs it. Subscriber deliveries that need a
+   * handler context or the journal (a plugin's subscriber, a finalization)
+   * stay leased, as a queue nobody consumes would leave them.
+   */
+  async function relay(): Promise<RelayPass> {
+    const pass: RelayPass = { delivered: 0, retried: 0, failed: 0, orphaned: 0, shortages: 0 };
+    const shortages = () =>
+      raw
+        .prepare("SELECT count(*) AS n FROM outbox_event WHERE type = 'stock.shortage'")
+        .first<{ n: number }>()
+        .then((r) => r?.n ?? 0);
+    const before = await shortages();
+    for (;;) {
+      const now = relayNow();
+      await capacity.handoffPage(now);
+      const leased = await store.leasePage(now);
+      if (leased.length === 0) break;
+      for (const msg of leased) {
+        if (msg.k === "sub") {
+          const row = await raw
+            .prepare("SELECT registration, state FROM subscriber_obligation WHERE seq = ?")
+            .bind(msg.seq)
+            .first<{ registration: string; state: string }>();
+          if (row?.registration !== "core.shortage" || row.state !== "pending") continue;
+        } else if (msg.k !== "rel") continue;
+        const claimed = await store.claim(msg, relayNow());
+        if (!claimed) continue;
+        if (msg.k === "sub") {
+          await runShortage(store, capacity, claimed.run, claimed.row, relayNow);
+          continue;
+        }
+        const outcome = await runRelease(store, raw, claimed.run, claimed.row, extensions, relayNow);
+        if (outcome === "delivered") pass.delivered++;
+        else if (outcome === "orphaned") pass.orphaned++;
+        else if (outcome === "failed") {
+          if (claimed.run.attempts >= RELAY_LIMITS.DELIVERY_ATTEMPTS_MAX) pass.failed++;
+          else pass.retried++;
+        }
+      }
+    }
+    pass.shortages = (await shortages()) - before;
+    return pass;
+  }
+
+  // A migration runs as one batch, as wrangler applies it: its marker (p0.5 §7.1) must clear within it.
+  const exec = async (text: string) => {
+    const statements = text.split(BREAK).flatMap((s) => statementTexts(s));
+    if (statements.length > 0) await raw.batch(statements.map((st) => raw.prepare(st)));
+  };
+
+  return {
+    db,
+    requests,
+    runtime,
+    extensions,
+    capacity,
+    async install() {
+      for (const [name, instance] of extensions.plugins) {
+        const def = instance.definition;
+        for (const m of def.migrations ?? []) await exec(m.sql);
+        await exec(
+          [...factGuardSql(def), ...acquireSql(def), installSql(def, `inst_${name}`, clock.now())].join(BREAK),
+        );
+      }
+    },
+    async product({ price = 1000, stock = 10, currency = "USD", kinds, inventory } = {}) {
+      const p = await catalog.createProduct({
+        title: "Product",
+        handle: `p-${ids.next("product")}`,
+        variants: [
+          {
+            sku: `SKU-${ids.next("variant")}`,
+            title: "Variant",
+            prices: { [currency]: price },
+            stock: inventory === false ? {} : { loc_default: stock },
+            allowedKinds: kinds,
+            inventory,
+          },
+        ],
+      });
+      return p.variantIds[0] as string;
+    },
+    async datedProduct({ price = 1000, stock = { loc_default: 1 }, kinds, bucketMinutes = 1440 } = {}) {
+      const p = await catalog.createProduct({
+        title: "Dated",
+        handle: `d-${ids.next("product")}`,
+        variants: [
+          {
+            sku: `SKU-${ids.next("variant")}`,
+            title: "Dated",
+            prices: { USD: price },
+            stock,
+            allowedKinds: kinds,
+          },
+        ],
+      });
+      const variantId = p.variantIds[0] as string;
+      const row = await raw
+        .prepare("SELECT inventory_item_id FROM variant_inventory_item WHERE variant_id = ?")
+        .bind(variantId)
+        .first<{ inventory_item_id: string }>();
+      const itemId = row?.inventory_item_id as string;
+      const converted = await capacity.convert(
+        { principal: "stf_scenario", key: `scenario-${++commandKeys}-${variantId}` },
+        itemId,
+        { to: "dated", bucketMinutes, reason: "scenario" },
+      );
+      return { variantId, itemId, pools: converted.pools };
+    },
+    async maintain() {
+      const total = { retired: 0, ended: 0, shortages: 0 };
+      for (let i = 0; i < 50; i++) {
+        const m = await capacity.maintain();
+        total.retired += m.retired;
+        total.ended += m.ended;
+        if (m.retired === 0 && m.ended === 0 && !m.more) break;
+      }
+      // Shortage scans are core's subscriber now (p0.6a §2.7), delivered by the relay.
+      total.shortages = (await relay()).shortages;
+      return total;
+    },
+    async quote(email, lines, currency = "USD", customerId = null) {
+      const variantIds = [...new Set(lines.map((l) => l.variantId))];
+      const reads = pluginReadSets(extensions, { cartId: "cart_quote", email, customerId, currency, variantIds });
+      const r = await catalog.pricing(variantIds, currency, reads);
+      const priced = await priceCartView({
+        currency,
+        email,
+        lines: cartLines(lines),
+        tax: r.tax,
+        variants: new Map(r.variants.map((v) => [v.variantId, v])),
+        extensions,
+        snapshot: toSnapshot(extensions, r.plugins, { tz, now: clock.now() }),
+        actor: "storefront",
+        customerId,
+      });
+      return priced.totals.total;
+    },
+    async checkout(email, lines, o = {}) {
+      const currency = o.currency ?? "USD";
+      const customerId = o.customerId ?? null;
+      const expectedTotal = o.expectedTotal ?? (await this.quote(email, lines, currency, customerId));
+      const cartId = o.cartId ?? ids.next("cart");
+      const attemptId = ids.next("checkoutAttempt");
+      const variantIds = [...new Set(lines.map((l) => l.variantId))];
+      // Counted per call, so a beforeCommit interleaving isn't charged to this
+      // attempt. Concurrent scenarios share the counter: assert counts on
+      // uncontended checkouts only.
+      const claimed = await requests.during(() =>
+        checkout.claim({
+          cartId,
+          generation: ++generation,
+          attemptId,
+          variantIds,
+          currency,
+          locale: o.locale,
+          now: clock.now(),
+          reads: pluginReadSets(extensions, { cartId, email, customerId, currency, variantIds }),
+          capacity: capacityRequest(extensions, currency, cartLines(lines)),
+        }),
+      );
+      const claim = claimed.value;
+      if (claim.existingOrderId) throw new KedgeError("CONFLICT", "This cart already has an order");
+      const plan = await planCheckout(
+        {
+          cartId,
+          attemptId,
+          currency,
+          email,
+          lines: cartLines(lines),
+          expectedTotal,
+          variants: new Map(claim.variants.map((v) => [v.variantId, v])),
+          levels: claim.levels,
+          now: clock.now(),
+          holdMs,
+          extensions,
+          snapshot: toSnapshot(extensions, claim.plugins, { tz, now: clock.now() }),
+          customerId,
+          tax: claim.tax,
+          policies: claim.policies,
+          consents: o.consents,
+          custom: o.custom,
+          locale: o.locale,
+          capacity: claim.capacity,
+          tz,
+        },
+        ids,
+      );
+      if (o.beforeCommit) await o.beforeCommit();
+      const committed = await requests.during(() => checkout.commit(plan));
+      const used = claimed.requests + committed.requests;
+      const order = (await orders.get(plan.order.id)) as OrderView;
+      return { plan, order, requests: used };
+    },
+    place: (orderId) => orders.place(orderId, "stf_scenario"),
+    async expire(orderId) {
+      const row = await raw
+        .prepare(`SELECT expires_at FROM "order" WHERE id = ?`)
+        .bind(orderId)
+        .first<{ expires_at: number }>();
+      if (row && clock.now() < row.expires_at) clock.set(row.expires_at + 1);
+      await orders.expireDue(clock.now(), 500);
+    },
+    async cancel(orderId) {
+      await markedBatch(raw, "scenario.cancel", [
+        raw.prepare(`UPDATE "order" SET status = 'canceled' WHERE id = ?`).bind(orderId),
+      ]);
+    },
+    drainReleases: () => relay(),
+    async setPluginState(plugin, state) {
+      await runMarked(
+        raw,
+        raw
+          .prepare("UPDATE plugin_state SET state = ?, changed_at = ? WHERE plugin = ?")
+          .bind(state, clock.now(), plugin),
+      );
+    },
+    async rows<T>(q: string, ...binds: unknown[]) {
+      return (
+        await raw
+          .prepare(q)
+          .bind(...binds)
+          .all<T>()
+      ).results;
+    },
+  };
+}
+
+/** Runs `n` copies of `fn` at once and sorts the outcomes. */
+export async function concurrently<T>(n: number, fn: (i: number) => Promise<T>) {
+  const settled = await Promise.allSettled(Array.from({ length: n }, (_, i) => fn(i)));
+  return {
+    fulfilled: settled.flatMap((s) => (s.status === "fulfilled" ? [s.value] : [])),
+    rejected: settled.flatMap((s) => (s.status === "rejected" ? [s.reason as unknown] : [])),
+  };
+}

package/src/vitest.ts

@@ -0,0 +1,11 @@
+// The one line a merchant's test suite carries (K11): after every test, every
+// invariant holds. Never edited per store; a plugin that needs an exception
+// has found a missing primitive.
+import { afterEach, expect } from "vitest";
+import { checkInvariants } from "./invariants";
+
+export function describeKedgeInvariants(db: () => D1Database): void {
+  afterEach(async () => {
+    expect(await checkInvariants(db())).toEqual([]);
+  });
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.