npm - @tokenoftrust/storefront-runner - Versions diffs - 1.3.4-rc.4 → 1.4.0 - Mend

@tokenoftrust/storefront-runner 1.3.4-rc.4 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (224) hide show

package/apps/storefront/src/lib/tot/query.ts CHANGED Viewed

@@ -4,6 +4,7 @@
  * PLP behaviour is identical whichever backend is active.
  */
 import type {
+  CatalogCollection,
   CatalogProduct,
   Facet,
   FacetValue,
@@ -236,6 +237,37 @@ export function sortProducts(
   }
 }
+/**
+ * Return the number of ACTIVE products a collection contains. Membership is
+ * resolved BOTH ways to match FixtureToTClient.listProducts (collection ->
+ * product_handles) AND the product-side back-reference (product.collections),
+ * so a collection counts as populated whichever direction the migration wrote.
+ */
+export function activeMemberCount(
+  collection: CatalogCollection,
+  activeProducts: CatalogProduct[],
+): number {
+  const handles = new Set(collection.product_handles);
+  return activeProducts.filter(
+    (p) => handles.has(p.handle) || p.collections.includes(collection.handle),
+  ).length;
+}
+/**
+ * Drop "empty synthesized collections" — the shells the migration emits for a
+ * source smart/manual collection whose every member is a draft or was dropped.
+ * They must never reach public SEO surfaces (sitemap, llms.txt, the collections
+ * directory + its JSON-LD): a crawlable URL that resolves to zero products is a
+ * dead end that dilutes crawl budget and structured data. A collection survives
+ * iff at least one ACTIVE product belongs to it.
+ */
+export function nonEmptyCollections(
+  collections: CatalogCollection[],
+  activeProducts: CatalogProduct[],
+): CatalogCollection[] {
+  return collections.filter((c) => activeMemberCount(c, activeProducts) > 0);
+}
 export function paginate<T>(
   items: T[],
   query: ListProductsQuery,

package/apps/storefront/src/lib/webhooks/cloudflareQueueDispatcher.ts ADDED Viewed

@@ -0,0 +1,82 @@
+/**
+ * Cloudflare Queues adapter for the `WebhookDispatcher` seam — PrivateApps
+ * epic, D4 (Chunk C). NOT V1's production path (see `dispatcher.ts`'s header
+ * for the full `d4-design-resolutions` context + the `@astrojs/cloudflare` v14
+ * investigation): `InMemoryDispatcher` is what actually runs deliveries today.
+ * This file exists so the Queues-backed path is built and unit-tested ahead of
+ * the infra decision to provision a real Queue — `getDispatcher.ts` only
+ * selects it when `env.WEBHOOK_DELIVERY_QUEUE` is bound, and no such binding
+ * is declared in `wrangler.toml` yet, so that branch is dead code for now.
+ *
+ * Local minimal interfaces below (not `@cloudflare/workers-types`, which
+ * isn't a dependency here) mirror how `../d1/catalog.ts`'s `D1Like` avoids a
+ * types dep on the real Cloudflare D1Database shape — same idea, for Queues.
+ */
+import { computeBackoffDelaySeconds } from "./dispatcher.js";
+import type { DispatchJob, AttemptDeliveryFn, WebhookDispatcher } from "./dispatcher.js";
+/** The slice of a Cloudflare Queue producer binding we use. */
+export interface CloudflareQueueSender<Body = DispatchJob> {
+  send(body: Body, options?: { delaySeconds?: number }): Promise<void>;
+}
+/** The slice of a Cloudflare Queue consumer message we use. */
+export interface CloudflareQueueMessage<Body = DispatchJob> {
+  readonly body: Body;
+  /** The queue's own native redelivery count (distinct from the delivery row's `attempts`). */
+  readonly attempts: number;
+  ack(): void;
+  retry(options?: { delaySeconds?: number }): void;
+}
+/** The slice of a Cloudflare Queue consumer batch we use. */
+export interface CloudflareQueueBatch<Body = DispatchJob> {
+  readonly messages: ReadonlyArray<CloudflareQueueMessage<Body>>;
+}
+/** `enqueue()` calls `env.WEBHOOK_DELIVERY_QUEUE.send()` — `notBefore` (if in the future) becomes the send's `delaySeconds`. */
+export class CloudflareQueueDispatcher implements WebhookDispatcher {
+  constructor(private readonly queue: CloudflareQueueSender) {}
+  async enqueue(job: DispatchJob): Promise<void> {
+    const delaySeconds = job.notBefore ? secondsUntil(job.notBefore) : undefined;
+    await this.queue.send(job, delaySeconds ? { delaySeconds } : undefined);
+  }
+}
+function secondsUntil(iso: string): number | undefined {
+  const ms = Date.parse(iso) - Date.now();
+  return ms > 0 ? Math.ceil(ms / 1000) : undefined;
+}
+/**
+ * The Queue CONSUMER logic a Worker `queue(batch, env, ctx)` export would call
+ * per batch, once the entry-wiring TODO in `dispatcher.ts`'s header is
+ * resolved — exported as a plain function (not tied to a `queue()` export
+ * signature) so it's unit-testable against a fake batch/message with no real
+ * Queues binding or Worker runtime involved.
+ *
+ * Judgment call: the retry delay uses `message.attempts` — the QUEUE's own
+ * native redelivery counter — via `computeBackoffDelaySeconds`, not the
+ * `nextAttemptAt` `attemptDelivery` already computed from the delivery row's
+ * own attempt count. Those two counters normally march together, but a
+ * message the queue redelivers for a reason unrelated to `attemptDelivery`
+ * (e.g. an uncaught throw) would only bump `message.attempts`, not the row —
+ * this keeps the seam correct against the queue's actual retry accounting.
+ * `attemptDelivery` has already written the delivery's own terminal/interim
+ * state to the store either way; `ack`/`retry` here only affect the QUEUE
+ * message, never the delivery's own state.
+ */
+export async function queue(batch: CloudflareQueueBatch, attempt: AttemptDeliveryFn): Promise<void> {
+  for (const message of batch.messages) {
+    const outcome = await attempt(message.body.deliveryId);
+    if (outcome.kind === "retrying") {
+      message.retry({ delaySeconds: computeBackoffDelaySeconds(message.attempts) });
+    } else {
+      // delivered, or dead-lettered (max attempts / install unavailable) —
+      // the delivery's own state is already terminal; nothing more for the
+      // queue to do with this message.
+      message.ack();
+    }
+  }
+}

package/apps/storefront/src/lib/webhooks/deliveryEngine.ts ADDED Viewed

@@ -0,0 +1,245 @@
+/**
+ * Delivery engine — PrivateApps epic, D4 (Chunk C). `attemptDelivery` is the
+ * ONE HTTP attempt a dispatcher (`dispatcher.ts`) drives per job: resolve the
+ * delivery + its event data, resolve the target install, refuse to deliver to
+ * a dead/suspended install (this is how suspension kills webhook delivery),
+ * build + sign the CloudEvents envelope, POST it with a bounded timeout,
+ * classify the outcome, and fold it into the store via `recordAttempt` +
+ * `transitionState`. Retry/DLQ policy (how many attempts, what backoff) is
+ * `dispatcher.ts`'s `computeBackoffDelaySeconds`/`MAX_DELIVERY_ATTEMPTS` —
+ * this module applies that policy, it doesn't redefine it.
+ *
+ * Fails closed: an unconfigured signing key, or a registry that can't be
+ * reached, throws {@link DeliveryEngineError} out of `attemptDelivery` — never
+ * a silently-recorded "delivered". Only an actual signed HTTP round trip (or
+ * the deliberate no-POST terminal cases below) ever writes a store outcome.
+ *
+ * SSRF defense-in-depth (belt to `../apps/registryService.ts`'s write-time
+ * `endpointGuard.ts` suspenders): `deliverSigned` re-validates
+ * `install.webhookEndpoint` right before every POST — catching a row that
+ * predates the guard, or a future write path that forgets to call it — and
+ * `postWithTimeout` sends with `redirect: "manual"` so a validated https/
+ * public target can't 302 its way to an internal one; either case never
+ * reads as `delivered`.
+ */
+import { WebhookDeliveryStore, type WebhookDelivery, type WebhookEvent, type WebhookTopic } from "./deliveryStore.js";
+import type { AppInstall } from "../apps/registryService.js";
+import { loadWebhookSigningConfig, type WebhookSigningConfig } from "./webhookSigningKey.js";
+import { signWebhookRequest, type SignWebhookRequestResult } from "./signing.js";
+import { buildCloudEventEnvelope } from "./events.js";
+import { computeBackoffDelaySeconds, MAX_DELIVERY_ATTEMPTS, type AttemptOutcome } from "./dispatcher.js";
+import { validateWebhookEndpoint } from "./endpointGuard.js";
+/** Bounded per-attempt timeout — a hung receiver must not hold a dispatcher slot open indefinitely. */
+const DEFAULT_TIMEOUT_MS = 10_000;
+/** The minimal registry seam the engine needs: resolving the target install by id. Satisfied by `AppRegistryService`. */
+export interface InstallResolver {
+  get(installId: string): Promise<AppInstall | null>;
+}
+export interface AttemptDeliveryDeps {
+  store: WebhookDeliveryStore;
+  registry: InstallResolver;
+  /** Defaults to `loadWebhookSigningConfig` (env-backed). Override in tests to avoid touching real env/keys. */
+  loadSigningConfig?: () => Promise<WebhookSigningConfig>;
+  /** Defaults to the global `fetch`. Override in tests with a fake. */
+  fetchImpl?: typeof fetch;
+  /** Injected clock. Defaults to `() => new Date()`. */
+  now?: () => Date;
+  /** Per-attempt HTTP timeout, in ms. Defaults to {@link DEFAULT_TIMEOUT_MS}. */
+  timeoutMs?: number;
+}
+/** Thrown when the engine itself can't run the attempt at all (fail-closed) — never a delivery outcome. */
+export class DeliveryEngineError extends Error {
+  constructor(
+    message: string,
+    readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = "DeliveryEngineError";
+  }
+}
+/**
+ * `app.uninstalled` is exempt from the active-status check — it's the
+ * defined farewell delivery, fired AFTER `registry.uninstall()` has already
+ * flipped the install to `uninstalled` (Chunk D's `emit.ts` deliberately
+ * still creates a delivery row for it), so refusing it here on status alone
+ * would silently swallow every uninstall notification. It still refuses a
+ * missing install or one with no endpoint, and every OTHER topic still
+ * refuses a non-active (suspended/uninstalled) install exactly as before.
+ */
+function isDeadInstall(install: AppInstall | null, topic: WebhookTopic): boolean {
+  if (!install || !install.webhookEndpoint) return true;
+  if (topic === "app.uninstalled") return false;
+  return install.status !== "active";
+}
+/** Run one HTTP delivery attempt for `deliveryId`, folding the outcome into the store. */
+export async function attemptDelivery(deliveryId: string, deps: AttemptDeliveryDeps): Promise<AttemptOutcome> {
+  const { store, registry } = deps;
+  const now = deps.now ?? (() => new Date());
+  const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const loadSigningConfig = deps.loadSigningConfig ?? loadWebhookSigningConfig;
+  const delivery = await store.getDelivery(deliveryId);
+  if (!delivery) {
+    throw new DeliveryEngineError(`Webhook delivery "${deliveryId}" not found.`);
+  }
+  // Terminal already — a stale/duplicate enqueue racing an outcome that
+  // already settled this delivery. No-op rather than re-attempt or throw.
+  if (delivery.state === "delivered") return { kind: "delivered" };
+  if (delivery.state === "dead-lettered") return { kind: "dead-lettered", reason: "max_attempts" };
+  const event = await store.getEvent(delivery.eventId);
+  if (!event) {
+    throw new DeliveryEngineError(`Webhook event "${delivery.eventId}" for delivery "${deliveryId}" not found.`);
+  }
+  let install: AppInstall | null;
+  try {
+    install = await registry.get(delivery.installId);
+  } catch (cause) {
+    throw new DeliveryEngineError(`Cannot resolve install "${delivery.installId}" for delivery "${deliveryId}".`, cause);
+  }
+  if (isDeadInstall(install, delivery.topic)) {
+    // Don't deliver to a dead/suspended install, or one with no endpoint
+    // configured — no POST attempt, no recordAttempt row; go straight to the
+    // one terminal-failure state the store has. This is how suspension kills
+    // webhook delivery.
+    await store.transitionState({ deliveryId, toState: "dead-lettered" });
+    return { kind: "dead-lettered", reason: "install_unavailable" };
+  }
+  let signingConfig: WebhookSigningConfig;
+  try {
+    signingConfig = await loadSigningConfig();
+  } catch (cause) {
+    throw new DeliveryEngineError(`Cannot sign webhook delivery "${deliveryId}": signing key unavailable.`, cause);
+  }
+  return deliverSigned(delivery, event, install!, signingConfig, { now, timeoutMs, fetchImpl, store });
+}
+async function deliverSigned(
+  delivery: WebhookDelivery,
+  event: WebhookEvent,
+  install: AppInstall,
+  signingConfig: WebhookSigningConfig,
+  ctx: {
+    now: () => Date;
+    timeoutMs: number;
+    fetchImpl: typeof fetch;
+    store: WebhookDeliveryStore;
+  },
+): Promise<AttemptOutcome> {
+  const { deliveryId } = delivery;
+  const attemptNo = delivery.attempts + 1;
+  const startedAt = ctx.now().toISOString();
+  // Defense-in-depth re-check (see module header): refuse to POST to an
+  // endpoint that wouldn't pass write-time validation today, even though it
+  // passed at install/update time. This gets its own dead-letter reason and
+  // a recorded attempt row (unlike `isDeadInstall`'s bare skip above) so
+  // support triage can tell "the target refused delivery" apart from "the
+  // target was never an allowed one".
+  const endpointCheck = validateWebhookEndpoint(install.webhookEndpoint!);
+  if (!endpointCheck.ok) {
+    await ctx.store.recordAttempt({
+      deliveryId,
+      attemptNo,
+      startedAt,
+      durationMs: 0,
+      httpStatus: null,
+      errorClass: "endpoint_blocked",
+    });
+    await ctx.store.transitionState({ deliveryId, toState: "dead-lettered" });
+    return { kind: "dead-lettered", reason: "endpoint_blocked" };
+  }
+  const envelope = buildCloudEventEnvelope({
+    deliveryId,
+    tenantId: delivery.tenantId,
+    topic: delivery.topic,
+    dataschemaVersion: event.dataschemaVersion,
+    data: event.payload,
+    appInstallId: delivery.installId,
+    retryCount: delivery.attempts,
+    now: ctx.now,
+  });
+  const body = JSON.stringify(envelope);
+  const { headers } = await signWebhookRequest({
+    method: "POST",
+    url: install.webhookEndpoint!,
+    body,
+    key: signingConfig.key,
+    kid: signingConfig.kid,
+  });
+  const { httpStatus, errorClass } = await postWithTimeout(
+    ctx.fetchImpl,
+    install.webhookEndpoint!,
+    body,
+    headers,
+    ctx.timeoutMs,
+  );
+  await ctx.store.recordAttempt({
+    deliveryId,
+    attemptNo,
+    startedAt,
+    durationMs: Date.now() - Date.parse(startedAt),
+    httpStatus,
+    errorClass,
+  });
+  if (httpStatus != null && httpStatus >= 200 && httpStatus < 300) {
+    await ctx.store.transitionState({ deliveryId, toState: "delivered" });
+    return { kind: "delivered" };
+  }
+  if (attemptNo >= MAX_DELIVERY_ATTEMPTS) {
+    await ctx.store.transitionState({ deliveryId, toState: "dead-lettered" });
+    return { kind: "dead-lettered", reason: "max_attempts" };
+  }
+  const nextAttemptAt = new Date(ctx.now().getTime() + computeBackoffDelaySeconds(attemptNo) * 1000).toISOString();
+  await ctx.store.transitionState({ deliveryId, toState: "retrying", nextAttemptAt });
+  return { kind: "retrying", nextAttemptAt };
+}
+async function postWithTimeout(
+  fetchImpl: typeof fetch,
+  url: string,
+  body: string,
+  signedHeaders: SignWebhookRequestResult["headers"],
+  timeoutMs: number,
+): Promise<{ httpStatus: number | null; errorClass: string | null }> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(url, {
+      method: "POST",
+      headers: { "content-type": "application/cloudevents+json", ...signedHeaders },
+      body,
+      signal: controller.signal,
+      // Manual redirects: a validated, public https target must not be able
+      // to 302 its way to an internal one. `isSuccessAttempt`/the 2xx check
+      // above already treat a 3xx as non-delivered (only 200-299 counts as
+      // `delivered`); this just stops `fetch` from silently following it
+      // there and reading back THAT response instead.
+      redirect: "manual",
+    });
+    const errorClass = res.status >= 300 && res.status < 400 ? "redirect_blocked" : null;
+    return { httpStatus: res.status, errorClass };
+  } catch (cause) {
+    const errorClass = cause instanceof Error && cause.name === "AbortError" ? "timeout" : "network_error";
+    return { httpStatus: null, errorClass };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/apps/storefront/src/lib/webhooks/deliveryMapper.ts ADDED Viewed

@@ -0,0 +1,34 @@
+/**
+ * Maps the internal `WebhookDelivery` read model to the D4 contract's
+ * `Delivery` shape (`docs/private-apps/contract/openapi.yaml`, schema
+ * `Delivery` — `additionalProperties: false`). Drops every internal field
+ * the contract doesn't declare (installId, tenantId, lastErrorClass,
+ * nextAttemptAt, createdAt) so an app only ever sees the documented surface —
+ * same discipline `catalogMapper.ts`'s `toContractProduct` keeps for D3.
+ */
+import type { WebhookDelivery } from "./deliveryStore.js";
+export interface ContractDelivery {
+  deliveryId: string;
+  eventId: string;
+  topic: WebhookDelivery["topic"];
+  state: WebhookDelivery["state"];
+  attempts: number;
+  lastStatus?: number;
+  lastTraceId?: string;
+  updatedAt: string;
+}
+/** Project one `WebhookDelivery` into the contract's `Delivery` — nothing else survives. */
+export function toContractDelivery(d: WebhookDelivery): ContractDelivery {
+  return {
+    deliveryId: d.deliveryId,
+    eventId: d.eventId,
+    topic: d.topic,
+    state: d.state,
+    attempts: d.attempts,
+    lastStatus: d.lastStatus ?? undefined,
+    lastTraceId: d.lastTraceId ?? undefined,
+    updatedAt: d.updatedAt,
+  };
+}