@tokenoftrust/storefront-runner 0.1.0

package/packages/public-runtime/src/search.ts

@@ -0,0 +1,45 @@
+/**
+ * Slim per-product search document — the storefront's prebuilt search projection.
+ * The ETL emits an array of these per tenant;
+ * the storefront builds its Fuse index from them instead of pulling the full
+ * catalog per request. Keep this SMALL — it's loaded into the Worker and (later)
+ * stored in KV; full product detail is fetched per-handle only for what's shown.
+ *
+ * NOTE on store shape: a Fuse-able blob is the right shape for typo-tolerant
+ * SEARCH. Faceted filtering/listing is a different read model (D1/SQL). Don't
+ * grow this into a facet store.
+ */
+import type { CatalogProduct, ProductStatus } from "./product.js";
+
+export interface SearchDoc {
+  handle: string;
+  title: string;
+  vendor?: string;
+  product_type?: string;
+  tags: string[];
+  description_text: string;
+  /** Lowest variant price (the "from" price). */
+  price_min: number;
+  currency: string;
+  /** First usable image URL, if any. */
+  image?: string;
+  status: ProductStatus;
+}
+
+/** Project a full CatalogProduct down to the slim search document. */
+export function toSearchDoc(p: CatalogProduct): SearchDoc {
+  const doc: SearchDoc = {
+    handle: p.handle,
+    title: p.title,
+    tags: p.tags,
+    description_text: p.description_text,
+    price_min: p.price_range.min,
+    currency: p.price_range.currency,
+    status: p.status,
+  };
+  if (p.vendor) doc.vendor = p.vendor;
+  if (p.product_type) doc.product_type = p.product_type;
+  const img = p.images.find((i) => i.url) ?? p.images[0];
+  if (img?.url) doc.image = img.url;
+  return doc;
+}

package/packages/public-runtime/src/tenant-assets.ts

@@ -0,0 +1,444 @@
+/**
+ * Versioned tenant static-asset store (decision `assets-r2-versioned`).
+ *
+ * Tenant static assets (`tenants/<id>/public/**` — logo, CSS, ~36 binaries) are
+ * served from **R2, version-scoped**, replacing the build-time
+ * `copy-tenant-assets.mjs` baking for extracted/versioned tenants. A **version**
+ * is an immutable snapshot: every asset for a version lives under one R2 key
+ * namespace `tenants/<id>/<versionId>/<rel>`, and a per-tenant, per-channel
+ * pointer selects which snapshot `live` vs `test` serves. A pointer flip switches
+ * every asset in lockstep — the same channel→version model the content publish
+ * spine (`customization-versioning.ts`) uses, applied to the static tree that
+ * `reconcile` reports as `publicAssets` ("mapped but NOT KV-served, served
+ * separately").
+ *
+ * Pure + runtime-portable (Web Crypto, `atob`, no `node:*`) so it runs in the
+ * Astro/Cloudflare Worker, the publish/ingest pipeline, and unit tests alike. The
+ * concrete R2 binding is injected via the structural `R2BucketLike` seam (a real
+ * `R2Bucket` satisfies it; `MemoryR2Bucket` backs dev + tests).
+ *
+ * ── versionId contract (assumption to reconcile with teammate `publish`) ──────
+ * The snapshot `versionId` is supplied by the publish pipeline (so a version's
+ * assets and content share ONE id and flip together). When publish has not
+ * defined one, `computeAssetsVersionId` derives a deterministic id from the asset
+ * set (sha256 over the sorted `<rel>:sha256(bytes)` list) — self-contained and
+ * idempotent. The channel→version pointer is a dedicated KV record
+ * (`cust:assets-pointer:<id>` → `{ live, test, rev }`) so it composes with, but
+ * does not collide with, the content `PointerRecord`. See
+ * `docs/versioned-assets-contract.md`.
+ */
+import type { CustomizationEnv } from "./customization-preview.js";
+
+/** sha256 as lowercase hex, via Web Crypto (Workers + Node 20+). Kept local so
+ * this renderer-safe module stays free of the control-plane versioning layer. */
+async function sha256Hex(content: string | Uint8Array): Promise<string> {
+  const bytes =
+    typeof content === "string" ? new TextEncoder().encode(content) : content;
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    bytes as unknown as BufferSource,
+  );
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+// ---------------------------------------------------------------------------
+// R2 seam — structural subset a real R2Bucket satisfies (no workers-types dep)
+// ---------------------------------------------------------------------------
+
+export interface R2ObjectLike {
+  /** Streaming body (real R2). Null for a HEAD-style object. */
+  body: ReadableStream<Uint8Array> | null;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  /** Byte length, when the store knows it. */
+  size?: number;
+}
+
+export interface R2BucketLike {
+  get(key: string): Promise<R2ObjectLike | null>;
+  put(
+    key: string,
+    value: ArrayBuffer | ArrayBufferView | ReadableStream | string,
+  ): Promise<unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Channel→version pointer (one snapshot versionId per channel)
+// ---------------------------------------------------------------------------
+
+/** Per-tenant asset pointer: the live/test snapshot versionId + a CAS token. */
+export interface AssetsPointer {
+  tenantId: string;
+  /** Optimistic-concurrency token; bumped on every successful write. */
+  rev: number;
+  /** Snapshot versionId selected for the live channel (null = none published). */
+  live: string | null;
+  /** Snapshot versionId selected for the test channel. */
+  test: string | null;
+}
+
+export function emptyAssetsPointer(tenantId: string): AssetsPointer {
+  return { tenantId, rev: 0, live: null, test: null };
+}
+
+/** KV key for a tenant's asset pointer (mirrors the `cust:*` layout). */
+export function assetsPointerKey(tenantId: string): string {
+  return `cust:assets-pointer:${tenantId}`;
+}
+
+/** Resolve the snapshot versionId a channel serves (null = nothing published). */
+export function resolveAssetVersion(
+  pointer: AssetsPointer,
+  channel: CustomizationEnv,
+): string | null {
+  return channel === "test" ? pointer.test : pointer.live;
+}
+
+// ---------------------------------------------------------------------------
+// R2 key scheme + path normalization
+// ---------------------------------------------------------------------------
+
+/** Reject empty, absolute, or traversal-bearing relative paths. */
+function isSafeRel(rel: string): boolean {
+  if (!rel || rel.startsWith("/")) return false;
+  return !rel.split("/").some((seg) => seg === ".." || seg === ".");
+}
+
+/**
+ * R2 object key for one asset of a version: `tenants/<id>/<versionId>/<rel>`.
+ * Throws on an unsafe `rel` (empty / absolute / `..`) so a crafted request can
+ * never escape the version namespace.
+ */
+export function tenantAssetKey(
+  tenantId: string,
+  versionId: string,
+  rel: string,
+): string {
+  if (!isSafeRel(rel)) {
+    throw new Error(`unsafe tenant-asset path: ${JSON.stringify(rel)}`);
+  }
+  return `tenants/${tenantId}/${versionId}/${rel}`;
+}
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Normalize a source path to the tenant's public-relative path (the `<rel>` in
+ * the R2 key), or null when the path is not a public asset for this tenant.
+ * Accepts both the colocated workspace shape (`tenants/<id>/public/<rel>`, from
+ * seed's `buildSeedFiles`) and the mapped artifact shape
+ * (`apps/storefront/public/tenants/<id>/<rel>`, reconcile's `publicAssets`).
+ */
+export function toPublicRel(tenantId: string, path: string): string | null {
+  const id = escapeRe(tenantId);
+  // apps/storefront/public/tenants/<id>/<rel>  (mapped artifact)
+  const m1 = path.match(new RegExp(`(?:^|/)public/tenants/${id}/(.+)$`))?.[1];
+  if (m1 && isSafeRel(m1)) return m1;
+  // tenants/<id>/public/<rel>  (colocated workspace)
+  const m2 = path.match(new RegExp(`(?:^|/)tenants/${id}/public/(.+)$`))?.[1];
+  if (m2 && isSafeRel(m2)) return m2;
+  return null;
+}
+
+/**
+ * Parse a request pathname `/tenants/<id>/<rel...>` into its tenant + relative
+ * asset path, or null when the shape does not match (so the caller can fall
+ * through). `<rel>` is validated: a traversal attempt yields null.
+ */
+export function parseTenantAssetPath(
+  pathname: string,
+): { tenantId: string; rel: string } | null {
+  let p = pathname;
+  try {
+    p = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+  const m = p.match(/^\/tenants\/([^/]+)\/(.+)$/);
+  const tenantId = m?.[1];
+  const rel = m?.[2];
+  if (!tenantId || !rel || !isSafeRel(rel)) return null;
+  return { tenantId, rel };
+}
+
+// ---------------------------------------------------------------------------
+// Content-type + cache headers
+// ---------------------------------------------------------------------------
+
+const CONTENT_TYPES: Record<string, string> = {
+  css: "text/css; charset=utf-8",
+  js: "text/javascript; charset=utf-8",
+  mjs: "text/javascript; charset=utf-8",
+  json: "application/json; charset=utf-8",
+  html: "text/html; charset=utf-8",
+  txt: "text/plain; charset=utf-8",
+  xml: "application/xml; charset=utf-8",
+  svg: "image/svg+xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+  avif: "image/avif",
+  gif: "image/gif",
+  ico: "image/x-icon",
+  woff: "font/woff",
+  woff2: "font/woff2",
+  ttf: "font/ttf",
+  otf: "font/otf",
+  eot: "application/vnd.ms-fontobject",
+  pdf: "application/pdf",
+  mp4: "video/mp4",
+  webm: "video/webm",
+  mov: "video/quicktime",
+  wasm: "application/wasm",
+  map: "application/json; charset=utf-8",
+};
+
+/** Best-effort content-type from a relative path's extension. */
+export function assetContentType(rel: string): string {
+  const dot = rel.lastIndexOf(".");
+  const ext = dot >= 0 ? rel.slice(dot + 1).toLowerCase() : "";
+  return CONTENT_TYPES[ext] ?? "application/octet-stream";
+}
+
+/**
+ * Cache-control for a versioned asset. The URL path is stable but its BYTES flip
+ * with the pointer, so the resource at `/tenants/<id>/<rel>` is NOT immutable —
+ * we cache for a short window and revalidate. (The R2 KEY is immutable because
+ * versionId is content/snapshot-scoped, but the public URL is not versioned.)
+ */
+export const ASSET_CACHE_CONTROL =
+  "public, max-age=300, s-maxage=300, stale-while-revalidate=86400";
+
+// ---------------------------------------------------------------------------
+// Ingest — write a version's public assets to R2
+// ---------------------------------------------------------------------------
+
+/** One input file (seed's `buildSeedFiles` shape, or a reconcile publicAsset). */
+export interface AssetFile {
+  /** Source path (workspace or mapped artifact form — see `toPublicRel`). */
+  path: string;
+  /** How `content` is encoded. Bytes bypass this. Default "utf8". */
+  encoding?: "utf8" | "base64";
+  content: string | Uint8Array;
+}
+
+function decodeContent(f: AssetFile): Uint8Array {
+  if (f.content instanceof Uint8Array) return f.content;
+  if (f.encoding === "base64") {
+    const bin = atob(f.content);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+  }
+  return new TextEncoder().encode(f.content);
+}
+
+/** The public-asset subset of a file list, normalized to `{ rel, bytes }`. */
+export function selectPublicAssets(
+  tenantId: string,
+  files: AssetFile[],
+): Array<{ rel: string; bytes: Uint8Array }> {
+  const out: Array<{ rel: string; bytes: Uint8Array }> = [];
+  for (const f of files) {
+    const rel = toPublicRel(tenantId, f.path);
+    if (rel == null) continue;
+    out.push({ rel, bytes: decodeContent(f) });
+  }
+  return out;
+}
+
+/**
+ * Deterministic snapshot versionId derived purely from the asset set: sha256
+ * over the sorted `<rel>:sha256(bytes)` lines. Idempotent + self-contained — the
+ * default when the publish pipeline has not supplied its own snapshot id.
+ */
+export async function computeAssetsVersionId(
+  tenantId: string,
+  files: AssetFile[],
+): Promise<string> {
+  const assets = selectPublicAssets(tenantId, files);
+  const lines = await Promise.all(
+    assets.map(async (a) => `${a.rel}:${await sha256Hex(a.bytes)}`),
+  );
+  lines.sort();
+  return sha256Hex(lines.join("\n"));
+}
+
+export interface IngestResult {
+  versionId: string;
+  /** R2 keys written, in input order. */
+  keys: string[];
+  count: number;
+}
+
+/**
+ * Write a version's public assets to R2 under `tenants/<id>/<versionId>/<rel>`.
+ * Content-addressed by the (caller-supplied or computed) snapshot id → immutable
+ * + idempotent: re-ingesting the same version overwrites identical bytes (no-op).
+ * Non-public files in `files` are ignored, so the whole seed/reconcile file set
+ * can be passed. Pass `versionId` to bind assets to the publish snapshot id;
+ * omit it to derive one from the bytes.
+ */
+export async function ingestAssetVersion(
+  bucket: R2BucketLike,
+  tenantId: string,
+  files: AssetFile[],
+  versionId?: string,
+): Promise<IngestResult> {
+  const vid = versionId ?? (await computeAssetsVersionId(tenantId, files));
+  const assets = selectPublicAssets(tenantId, files);
+  const keys: string[] = [];
+  for (const a of assets) {
+    const key = tenantAssetKey(tenantId, vid, a.rel);
+    await bucket.put(key, a.bytes);
+    keys.push(key);
+  }
+  return { versionId: vid, keys, count: keys.length };
+}
+
+// ---------------------------------------------------------------------------
+// Pointer persistence (KV) — read/write the channel→version selection
+// ---------------------------------------------------------------------------
+
+export interface AssetsKv {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string): Promise<void>;
+}
+
+export async function readAssetsPointer(
+  kv: Pick<AssetsKv, "get">,
+  tenantId: string,
+): Promise<AssetsPointer> {
+  const raw = await kv.get(assetsPointerKey(tenantId));
+  if (!raw) return emptyAssetsPointer(tenantId);
+  try {
+    const p = JSON.parse(raw) as Partial<AssetsPointer>;
+    return {
+      tenantId,
+      rev: typeof p.rev === "number" ? p.rev : 0,
+      live: typeof p.live === "string" ? p.live : null,
+      test: typeof p.test === "string" ? p.test : null,
+    };
+  } catch {
+    // Fail safe: a malformed record reads as empty (never wedges writes).
+    return emptyAssetsPointer(tenantId);
+  }
+}
+
+/**
+ * Point a channel at a snapshot versionId (read-check-write on `rev`). KV has no
+ * hardware CAS; a single serialized writer per tenant (the publish/reconcile
+ * pipeline) makes the optimistic rev check sufficient — same trade-off as
+ * `KVVersionStore.setPointer`.
+ */
+export async function setAssetsChannel(
+  kv: AssetsKv,
+  tenantId: string,
+  channel: CustomizationEnv,
+  versionId: string,
+): Promise<AssetsPointer> {
+  const current = await readAssetsPointer(kv, tenantId);
+  const next: AssetsPointer = {
+    ...current,
+    rev: current.rev + 1,
+    [channel]: versionId,
+  };
+  await kv.put(assetsPointerKey(tenantId), JSON.stringify(next));
+  return next;
+}
+
+/** Promote the test snapshot to live (atomic pointer flip). */
+export async function promoteAssets(
+  kv: AssetsKv,
+  tenantId: string,
+): Promise<AssetsPointer> {
+  const current = await readAssetsPointer(kv, tenantId);
+  const next: AssetsPointer = {
+    ...current,
+    rev: current.rev + 1,
+    live: current.test,
+  };
+  await kv.put(assetsPointerKey(tenantId), JSON.stringify(next));
+  return next;
+}
+
+// ---------------------------------------------------------------------------
+// Serve — resolve version, stream from R2 with headers
+// ---------------------------------------------------------------------------
+
+export interface ServeTenantAssetDeps {
+  bucket: R2BucketLike;
+  /** KV read for the assets pointer. */
+  kvGet: (key: string) => Promise<string | null>;
+  /** Channel to serve; default "live". Pass `locals.customizationEnv`. */
+  channel?: CustomizationEnv;
+  /** Request `If-None-Match` header, for conditional GET (304). */
+  ifNoneMatch?: string | null;
+}
+
+/**
+ * Serve `/tenants/<id>/<rel>` from the version-scoped R2 store.
+ *
+ * Returns `null` — meaning "not handled here, fall through" — when the path is
+ * not a tenant-asset path OR the tenant has no published asset version for the
+ * channel (the back-compat gate: non-versioned tenants are served by the baked
+ * static tree, which the adapter matches BEFORE this SSR route). Returns a 404
+ * `Response` when a version IS selected but the object is missing. On a hit,
+ * streams the object with the resolved content-type, a revalidating cache
+ * header, and a versionId ETag (honoring `If-None-Match` with a 304).
+ */
+export async function serveTenantAsset(
+  deps: ServeTenantAssetDeps,
+  pathname: string,
+): Promise<Response | null> {
+  const parsed = parseTenantAssetPath(pathname);
+  if (!parsed) return null;
+  const { tenantId, rel } = parsed;
+
+  const pointer = await readAssetsPointer({ get: deps.kvGet }, tenantId);
+  const versionId = resolveAssetVersion(pointer, deps.channel ?? "live");
+  if (!versionId) return null; // non-versioned tenant → fall through
+
+  const etag = `"${versionId}"`;
+  const baseHeaders: Record<string, string> = {
+    "cache-control": ASSET_CACHE_CONTROL,
+    etag,
+    vary: "If-None-Match",
+  };
+
+  if (deps.ifNoneMatch && matchesEtag(deps.ifNoneMatch, etag)) {
+    return new Response(null, { status: 304, headers: baseHeaders });
+  }
+
+  const key = tenantAssetKey(tenantId, versionId, rel);
+  const object = await deps.bucket.get(key);
+  if (!object) {
+    return new Response("Not found", {
+      status: 404,
+      headers: { "cache-control": "no-store" },
+    });
+  }
+
+  const headers: Record<string, string> = {
+    ...baseHeaders,
+    "content-type": assetContentType(rel),
+  };
+  if (typeof object.size === "number") {
+    headers["content-length"] = String(object.size);
+  }
+  const body: BodyInit = object.body ?? (await object.arrayBuffer());
+  return new Response(body, { status: 200, headers });
+}
+
+/** Weak `If-None-Match` compare: `*`, exact, or member of a comma list. */
+function matchesEtag(ifNoneMatch: string, etag: string): boolean {
+  const norm = (s: string) => s.trim().replace(/^W\//, "");
+  const target = norm(etag);
+  return ifNoneMatch
+    .split(",")
+    .some((t) => t.trim() === "*" || norm(t) === target);
+}