@tokenoftrust/storefront-runner 3.3.3 → 3.3.5

package/apps/storefront/src/lib/observability/diag/serverResponseTime.ts

@@ -2,9 +2,14 @@
  * The document's server response time for the evidence panel: the `total` the Worker stamps in
  * `Server-Timing` (`lib/observability/shared/serverTiming.ts`) next to the time this self-fetch
  * waited for the response headers (TTFB as seen from the Worker). Advisory — never gates promotion.
+ *
+ * The self-fetch carries the viewer's preview grant so it measures the render a reviewer gets. A
+ * gate page or any non-200 answer is not that render, so it is reported as not measured rather
+ * than as a number.
  */
 
 export interface ServerResponseTime {
+  measured: true;
   /** `total;dur` from the document's `Server-Timing`, or null when the header is absent. */
   serverTotalMs: number | null;
   /** Wall time until the response headers arrived. */
@@ -13,6 +18,11 @@ export interface ServerResponseTime {
   cold: boolean;
 }
 
+export interface ServerResponseTimeUnmeasured {
+  measured: false;
+  reason: string;
+}
+
 /** Pull `total;dur` and the cold marker out of a `Server-Timing` header value. */
 export function parseServerTiming(header: string | null | undefined): Pick<ServerResponseTime, "serverTotalMs" | "cold"> {
   if (!header) return { serverTotalMs: null, cold: false };
@@ -24,18 +34,35 @@ export function parseServerTiming(header: string | null | undefined): Pick<Serve
   };
 }
 
-/** Self-fetch `url` and report its server response time; null when the fetch fails. */
+/**
+ * The URL and headers that make a self-fetch of `path` the viewer's own render: the request's
+ * `__preview` grant (query) and cookies are forwarded.
+ */
+export function viewerRenderRequest(requestUrl: string, path: string, cookie: string | null): { url: URL; headers: Headers } {
+  const source = new URL(requestUrl);
+  const url = new URL(path, source.origin);
+  const grant = source.searchParams.get("__preview");
+  if (grant) url.searchParams.set("__preview", grant);
+  const headers = new Headers();
+  if (cookie) headers.set("cookie", cookie);
+  return { url, headers };
+}
+
+/** Self-fetch and report the server response time, or why it could not be measured. */
 export async function measureServerResponseTime(
-  url: URL,
+  request: { url: URL; headers: Headers },
   now: () => number = () => performance.now(),
-): Promise<ServerResponseTime | null> {
+): Promise<ServerResponseTime | ServerResponseTimeUnmeasured> {
   try {
     const started = now();
-    const res = await fetch(url, { redirect: "manual" });
+    const res = await fetch(request.url, { headers: request.headers, redirect: "manual" });
     const ttfbMs = now() - started;
     await res.body?.cancel();
-    return { ...parseServerTiming(res.headers.get("server-timing")), ttfbMs: Math.round(ttfbMs) };
+    const gate = res.headers.get("x-tot-gate");
+    if (gate) return { measured: false, reason: `the fetch was answered by the access gate (${gate}), not the store render` };
+    if (res.status !== 200) return { measured: false, reason: `the home document answered ${res.status}, not a render` };
+    return { measured: true, ...parseServerTiming(res.headers.get("server-timing")), ttfbMs: Math.round(ttfbMs) };
   } catch {
-    return null;
+    return { measured: false, reason: "the home document could not be fetched" };
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "3.3.3",
+  "version": "3.3.5",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/scripts/generate-managed-analytics-api-v1-schemas.mjs

@@ -1,13 +1,92 @@
+// Renders packages/public-runtime/schemas/managed-analytics/v1/*.schema.json from
+// MANAGED_ANALYTICS_API_V1_JSON_SCHEMAS. The output is a declared derived mirror
+// (.tot/derived-mirror-steps.json), re-derived on the umbrella tip.
+//
+//   (no flag)  write every schema file
+//   --check    refuse a stale, missing or orphaned file. Inside a fold gate (TOT_FOLD_GATE=1) a
+//              stale or missing file passes with a STALE line, since the tip re-derives it; an
+//              orphan still refuses, because no derivation deletes a file.
+import { readdirSync, readFileSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
-import { MANAGED_ANALYTICS_API_V1_JSON_SCHEMAS } from "../src/integration/managed-analytics-api-v1.schemas.ts";
+import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const here = dirname(fileURLToPath(import.meta.url));
-const output = resolve(here, "../schemas/managed-analytics/v1");
-await mkdir(output, { recursive: true });
+const repoRoot = resolve(here, "../../..");
+export const OUTPUT_DIR = relative(repoRoot, resolve(here, "../schemas/managed-analytics/v1"));
 
-for (const schema of Object.values(MANAGED_ANALYTICS_API_V1_JSON_SCHEMAS)) {
-  const name = new URL(schema.$id).pathname.split("/").at(-1);
-  await writeFile(resolve(output, name), `${JSON.stringify(schema, null, 2)}\n`, "utf8");
+/**
+ * Every schema file, as repo-relative path -> text.
+ * @returns {Promise<Map<string, string>>}
+ */
+export async function renderManagedAnalyticsSchemas() {
+  const { MANAGED_ANALYTICS_API_V1_JSON_SCHEMAS } = await import("../src/integration/managed-analytics-api-v1.schemas.ts");
+  const files = new Map();
+  for (const schema of Object.values(MANAGED_ANALYTICS_API_V1_JSON_SCHEMAS)) {
+    const name = new URL(schema.$id).pathname.split("/").at(-1);
+    files.set(`${OUTPUT_DIR}/${name}`, `${JSON.stringify(schema, null, 2)}\n`);
+  }
+  return files;
+}
+
+/**
+ * The committed files under `root` against a fresh render: `stale` differ or are missing, `orphans`
+ * sit in the output directory with no schema rendering them.
+ * @param {string} [root]
+ */
+export async function findSchemaDrift(root = repoRoot) {
+  const files = await renderManagedAnalyticsSchemas();
+  /** @param {string} path */
+  const committed = (path) => {
+    try {
+      return readFileSync(resolve(root, path), "utf8");
+    } catch {
+      return null;
+    }
+  };
+  let present = [];
+  try {
+    present = readdirSync(resolve(root, OUTPUT_DIR));
+  } catch {
+    present = [];
+  }
+  return {
+    files,
+    stale: [...files].filter(([path, text]) => committed(path) !== text).map(([path]) => path),
+    orphans: present.map((name) => `${OUTPUT_DIR}/${name}`).filter((path) => !files.has(path)),
+  };
+}
+
+/**
+ * The `--check` verdict. A fold gate tolerates stale files, which the tip re-derives; an orphan is
+ * always red, since no derivation deletes a file.
+ * @param {{ count: number, stale: string[], orphans: string[], foldGate: boolean }} drift
+ * @returns {{ ok: boolean, lines: string[] }}
+ */
+export function schemaCheckVerdict({ count, stale, orphans, foldGate }) {
+  const lines = [
+    ...orphans.map((path) => `managed-analytics-schemas-orphan: ${path} is not rendered by any schema; delete it`),
+    ...stale.map((path) => `${foldGate ? "STALE" : "managed-analytics-schemas-stale"}: ${path}`),
+  ];
+  const ok = orphans.length === 0 && (stale.length === 0 || foldGate);
+  if (!ok && stale.length > 0) lines.push(`re-derive: node ${relative(repoRoot, fileURLToPath(import.meta.url))}`);
+  if (ok) lines.push(`${count} managed analytics v1 schemas are ${stale.length > 0 ? "stale; the tip re-derives them" : "current"}`);
+  return { ok, lines };
+}
+
+async function check() {
+  const { files, stale, orphans } = await findSchemaDrift();
+  const verdict = schemaCheckVerdict({ count: files.size, stale, orphans, foldGate: process.env.TOT_FOLD_GATE === "1" });
+  for (const line of verdict.lines) (verdict.ok ? console.log : console.error)(line);
+  if (!verdict.ok) process.exitCode = 1;
+}
+
+async function write() {
+  const files = await renderManagedAnalyticsSchemas();
+  await mkdir(resolve(repoRoot, OUTPUT_DIR), { recursive: true });
+  for (const [path, text] of files) await writeFile(resolve(repoRoot, path), text, "utf8");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  await (process.argv.includes("--check") ? check() : write());
 }