@tokenoftrust/storefront-runner 3.3.5 → 3.4.1

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

@@ -1,18 +1,20 @@
 /**
- * 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 document's server response time for the evidence panel, measured in the viewer's browser
+ * (a Worker fetching its own zone is answered by the origin, never by this Worker, so a
+ * server-side self-fetch cannot see the render). The panel script fetches the home document
+ * same-origin with the viewer's credentials and `__preview` grant, then reports the `total` the
+ * Worker stamps in `Server-Timing` (`lib/observability/shared/serverTiming.ts`) beside the time to
+ * first byte. 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.
+ * A gate page or any non-200 answer is not the render a reviewer gets, 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. */
+  /** Time to first byte. */
   ttfbMs: number;
   /** The isolate was serving its first request (`isolate;desc="cold"`). */
   cold: boolean;
@@ -23,6 +25,8 @@ export interface ServerResponseTimeUnmeasured {
   reason: string;
 }
 
+export type ServerResponseTimeResult = ServerResponseTime | ServerResponseTimeUnmeasured;
+
 /** 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 };
@@ -34,35 +38,54 @@ export function parseServerTiming(header: string | null | undefined): Pick<Serve
   };
 }
 
-/**
- * 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 };
+/** Turn the home document's response into a measurement, or the reason it is not one. */
+export function classifyHomeResponse(
+  res: { status: number; headers: { get(name: string): string | null } },
+  ttfbMs: number,
+): ServerResponseTimeResult {
+  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) };
 }
 
-/** Self-fetch and report the server response time, or why it could not be measured. */
-export async function measureServerResponseTime(
-  request: { url: URL; headers: Headers },
-  now: () => number = () => performance.now(),
-): Promise<ServerResponseTime | ServerResponseTimeUnmeasured> {
+/** The sentence the panel shows for a result. */
+export function describeServerResponseTime(result: ServerResponseTimeResult): string {
+  if (!result.measured) return `Not measured: ${result.reason}.`;
+  const server = result.serverTotalMs !== null ? `${result.serverTotalMs} ms server total (Server-Timing)` : "no Server-Timing header";
+  return `Home document: ${server} · ${result.ttfbMs} ms to first byte${result.cold ? " · cold isolate" : ""}. A hosted preview is a Worker render; a published static site is served from the CDN and is faster.`;
+}
+
+export interface BrowserDeps {
+  fetch: typeof fetch;
+  /** Resource-timing entries for a URL (`performance.getEntriesByName`). */
+  entries: (url: string) => PerformanceEntry[];
+  now: () => number;
+}
+
+/**
+ * Fetch the home document as the viewer and measure it. TTFB is the resource-timing
+ * `responseStart - requestStart` for that request, falling back to the wall time to headers.
+ */
+export async function measureHomeDocument(homeUrl: URL, deps: BrowserDeps): Promise<ServerResponseTimeResult> {
   try {
-    const started = now();
-    const res = await fetch(request.url, { headers: request.headers, redirect: "manual" });
-    const ttfbMs = now() - started;
-    await res.body?.cancel();
-    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) };
+    const started = deps.now();
+    const res = await deps.fetch(homeUrl.href, { credentials: "include", redirect: "manual", cache: "no-store" });
+    const wallMs = deps.now() - started;
+    await res.arrayBuffer();
+    const timing = deps.entries(homeUrl.href).at(-1) as PerformanceResourceTiming | undefined;
+    const ttfbMs = timing && timing.responseStart > 0 && timing.requestStart > 0 ? timing.responseStart - timing.requestStart : wallMs;
+    return classifyHomeResponse(res, ttfbMs);
   } catch {
     return { measured: false, reason: "the home document could not be fetched" };
   }
 }
+
+/** Measure the home document and write the sentence into `target`. */
+export async function mountServerResponseTime(target: Element, pageUrl: string, deps: BrowserDeps): Promise<void> {
+  const page = new URL(pageUrl);
+  const homeUrl = new URL(target.getAttribute("data-home-path") ?? "/", page.origin);
+  const grant = page.searchParams.get("__preview");
+  if (grant) homeUrl.searchParams.set("__preview", grant);
+  target.textContent = describeServerResponseTime(await measureHomeDocument(homeUrl, deps));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "3.3.5",
+  "version": "3.4.1",
   "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/src/asset-registry.ts

@@ -34,10 +34,17 @@ export interface AssetProvenance {
   at: string;
 }
 
+/**
+ * How a derived pool object was made from its `parent` entry. A rendition's identity is its parent's
+ * address plus this recipe; the bytes it produces get their own address, so a changed recipe or
+ * encoder mints new renditions and never rewrites a URL already served.
+ */
+export interface VariantRecipe { kind: "variant"; parent: string; width: number; format: string; quality: number; encoder: string }
+
 export type AssetRecipe =
   | { kind: "original" }
   | { kind: "sanitized"; sanitizer: string; source: string }
-  | { kind: "variant"; parent: string; width: number; format: string; encoder: string };
+  | VariantRecipe;
 
 export type RetentionClass = "release" | "durable" | "external-use" | "removal-requested";
 export interface RetentionTransition {
@@ -55,6 +62,9 @@ export interface AssetRecord {
   address: string;
   mediaType?: string;
   size?: number;
+  /** Intrinsic pixel dimensions of an image, as decoded (orientation applied). */
+  width?: number;
+  height?: number;
   provenance?: AssetProvenance;
   /** Tenants authorized to reference this address: each one proved it holds the bytes. */
   tenants?: string[];
@@ -79,6 +89,8 @@ export interface AssetWrite {
   entry: string;
   mediaType?: string;
   size?: number;
+  width?: number;
+  height?: number;
   provenance?: AssetProvenance;
   tenant?: string;
   owner?: string;
@@ -103,6 +115,11 @@ const MAX_TENANTS = 256;
 const MAX_RENDITIONS = 64;
 const MAX_TRANSITIONS = 32;
 const MAX_LOCATOR = 2048;
+const MAX_DIMENSION = 65535;
+
+function validDimension(value: unknown): value is number {
+  return Number.isSafeInteger(value) && (value as number) > 0 && (value as number) <= MAX_DIMENSION;
+}
 
 /**
  * The retention transitions an owner or a designation may make. A record with no retention facet is
@@ -176,8 +193,10 @@ function normalizeRecipe(raw: unknown): AssetRecipe | null {
   if (raw.kind === "variant" && typeof raw.parent === "string" && entryAddress(raw.parent) !== null &&
       Number.isSafeInteger(raw.width) && (raw.width as number) > 0 && (raw.width as number) <= 16384 &&
       typeof raw.format === "string" && TOKEN_RE.test(raw.format) &&
+      Number.isSafeInteger(raw.quality) && (raw.quality as number) >= 1 && (raw.quality as number) <= 100 &&
       typeof raw.encoder === "string" && TOKEN_RE.test(raw.encoder)) {
-    return { kind: "variant", parent: raw.parent, width: raw.width as number, format: raw.format, encoder: raw.encoder };
+    return { kind: "variant", parent: raw.parent, width: raw.width as number, format: raw.format,
+      quality: raw.quality as number, encoder: raw.encoder };
   }
   return null;
 }
@@ -227,6 +246,11 @@ export function normalizeAssetRecord(entry: string, raw: unknown): AssetRecord |
   const record: AssetRecord = { address };
   if (typeof raw.mediaType === "string" && MEDIA_TYPE_RE.test(raw.mediaType)) record.mediaType = raw.mediaType;
   if (Number.isSafeInteger(raw.size) && (raw.size as number) > 0) record.size = raw.size as number;
+  // Dimensions are one fact: both or neither.
+  if (validDimension(raw.width) && validDimension(raw.height)) {
+    record.width = raw.width;
+    record.height = raw.height;
+  }
   const provenance = normalizeProvenance(raw.provenance);
   if (provenance) record.provenance = provenance;
   if (Array.isArray(raw.tenants)) {
@@ -294,6 +318,10 @@ export function applyAssetWrite(existing: AssetRecord | undefined, write: AssetW
   const record: AssetRecord = existing ? structuredCloneRecord(existing) : { address };
   if (record.mediaType === undefined && write.mediaType !== undefined && MEDIA_TYPE_RE.test(write.mediaType)) record.mediaType = write.mediaType;
   if (record.size === undefined && Number.isSafeInteger(write.size) && (write.size as number) > 0) record.size = write.size as number;
+  if (record.width === undefined && validDimension(write.width) && validDimension(write.height)) {
+    record.width = write.width;
+    record.height = write.height;
+  }
   if (record.provenance === undefined && write.provenance) {
     const provenance = normalizeProvenance(write.provenance);
     if (provenance) record.provenance = provenance;
@@ -386,6 +414,34 @@ export function authorizeAssetReference(
   };
 }
 
+export interface RegisteredRendition { entry: string; size: number }
+
+/**
+ * The registered rendition of `recipe.parent` made by exactly `recipe`, or null. It counts only when
+ * the parent lists it among its renditions, its record's recipe has the same width, format, quality
+ * and encoder, it is registered to `tenantId`, and the store holds a byte verification of it (so it
+ * is in the pool). A recipe or encoder that differs in any field finds nothing: it mints its own
+ * renditions. The record's own `parent` is not compared: two sources with the same pixels share
+ * rendition bytes, the record keeps its first writer's parent, and each parent's link is the proof
+ * that a build made it from that parent.
+ */
+export function registeredRendition(
+  registry: AssetRegistry | null | undefined, tenantId: string, recipe: VariantRecipe,
+): RegisteredRendition | null {
+  const wanted = normalizeRecipe(recipe);
+  if (!registry || !wanted || wanted.kind !== "variant") return null;
+  for (const entry of registry.assets[wanted.parent]?.renditions ?? []) {
+    const record = registry.assets[entry];
+    const made = record?.recipe;
+    if (!record?.verified || !record.tenants?.includes(tenantId) || made?.kind !== "variant") continue;
+    if (made.width === wanted.width && made.format === wanted.format &&
+        made.quality === wanted.quality && made.encoder === wanted.encoder) {
+      return { entry, size: record.verified.size };
+    }
+  }
+  return null;
+}
+
 /**
  * The tenants a record lists other than `tenantId`, without naming them: true when the address is
  * registered and this tenant is not among its tenants. Capture uses it to refuse a reference to