@tokenoftrust/storefront-runner 2.5.5 → 3.0.0

package/apps/storefront/src/middleware/controlPlane.ts

@@ -11,7 +11,7 @@ import { readEnv, readD1, readKv } from "@/lib/publication/shared/env";
 import { fromD1, type D1Like } from "@/lib/catalog/d1/catalog";
 import { readCurrentTenantConsentConfig } from "@/lib/measurement/consent/consentConfigRead";
 import { loadActiveManagedInstallDeclarations } from "@/lib/integrations/integration/managedInstallDeclarations";
-import { buildTenantConsentBroker, verifyPreviewToken } from "@tot/public-runtime";
+import { buildTenantConsentBroker, verifyPreviewToken, storefrontModeRequiresSignIn } from "@tot/public-runtime";
 import { tenantIsDeclaredPublic } from "@/config/tenants";
 import type {
   ConsentSnapshot,
@@ -37,6 +37,7 @@ import { gatedApiResponse, gatedHoldingResponse } from "@/lib/access/auth/gatePa
 import { readSession, KvSessionStore, SESSION_COOKIE } from "@/lib/access/auth/session";
 import { runRenderChain } from "./renderChain.js";
 import { resolveCandidateContentPin } from "./candidatePin.js";
+import { timed } from "@/lib/observability/shared/serverTiming";
 import type { InternalContentGrant } from "@/lib/access/auth/internalContentAuthority";
 
 export interface ControlPlaneInput {
@@ -92,13 +93,13 @@ export async function serveControlPlane(input: ControlPlaneInput): Promise<Respo
     let viewerRecord = null;
     if (!isAuthPath(url.pathname)) {
       const sessionKv = await readKv("SESSION");
+      const sid = context.cookies.get(SESSION_COOKIE)?.value ?? null;
       if (sessionKv) {
-        const sid = context.cookies.get(SESSION_COOKIE)?.value ?? null;
-        viewerRecord = await readSession(
+        viewerRecord = await timed(locals.serverTiming, "session", () => readSession(
           new KvSessionStore(sessionKv),
           sid,
           Math.floor(Date.now() / 1000),
-        );
+        ));
       }
     }
     const nowSeconds = Math.floor(Date.now() / 1000);
@@ -193,9 +194,12 @@ export async function serveControlPlane(input: ControlPlaneInput): Promise<Respo
         return context.redirect(decision.location, 303);
       }
       // An API caller gets an honest 401, never a 200 page it would read as success.
-      if (isApiPath(url.pathname)) return gatedApiResponse(decision.location, request);
+      const gateReason = storefrontModeRequiresSignIn(tenant.storefront?.mode)
+        ? "storefront-unpaid"
+        : "shared-preview-host";
+      if (isApiPath(url.pathname)) return gatedApiResponse(decision.location, request, gateReason);
       // Withhold content but offer sign-in (carrying the intended destination).
-      return gatedHoldingResponse(decision.location);
+      return gatedHoldingResponse(decision.location, gateReason);
     }
     // Admitted to a store that is not public on this host: by session, preview
     // grant, or QA bypass. Visitor routes read this to stay side-effect-free for an
@@ -251,10 +255,8 @@ export async function serveControlPlane(input: ControlPlaneInput): Promise<Respo
   let managedIntegrationDeclarations: IntegrationDeclarationInput[] = [];
   if (appsD1) {
     try {
-      managedIntegrationDeclarations = await loadActiveManagedInstallDeclarations(
-        fromD1(appsD1),
-        tenant.tenant_id,
-      );
+      managedIntegrationDeclarations = await timed(locals.serverTiming, "installs", () =>
+        loadActiveManagedInstallDeclarations(fromD1(appsD1), tenant.tenant_id));
     } catch {
       managedIntegrationDeclarations = [];
     }
@@ -278,7 +280,8 @@ export async function serveControlPlane(input: ControlPlaneInput): Promise<Respo
     publicationBucket: input.publicationBucket,
     verifiedCandidatePin: candidatePin ?? undefined,
     managedIntegrationDeclarations,
-    readTenantConsentSnapshot: () => readSavedConsentSnapshot(tenant.tenant_id),
+    readTenantConsentSnapshot: () =>
+      timed(locals.serverTiming, "consent", () => readSavedConsentSnapshot(tenant.tenant_id)),
     // The D1 catalog serving projection, for a tenant that declares
     // `catalog.serving: "d1"` (ADR 0033). Deferred to the chain's own catalog build
     // so a request the static bundle or the edge cache answers never pays for it.

package/apps/storefront/src/middleware/index.ts

@@ -25,7 +25,7 @@ import { getTenantResolver } from "@/config/resolver";
 import { readEnv, readKv, readR2 } from "@/lib/publication/shared/runtimeEnv";
 import { resolveCdnForwardRouting, resolveTenantRouting } from "@/lib/access/shared/tenantRouting";
 import { crossSiteFormRefusal, verifyCdnForward } from "@/lib/publication/shared/cdnForward";
-import { compileRouteTierIndexV1, resolvePublicationRoutePlanV1, type RouteTierIndexV1 , storefrontModeRequiresSignIn } from "@tot/public-runtime";
+import { SAMPLE_CART_HANDOFF_URL, compileRouteTierIndexV1, resolvePublicationRoutePlanV1, type RouteTierIndexV1 , storefrontModeRequiresSignIn } from "@tot/public-runtime";
 import type { PublicationArtifactBucketV1, TenantConfig } from "@tot/public-runtime";
 import { DEV_DRAFT_COOKIE } from "@/lib/developer-experience/dev/devDraft";
 import { applySecurityHeaders } from "@/lib/access/shared/securityHeaders";
@@ -36,6 +36,7 @@ import { parseGateMode } from "@/lib/access/auth/loginGate";
 import { evaluateDemoGate, hostInGateList } from "@/lib/access/shared/demoGate";
 import { isMaintenanceOn, maintenanceResponse } from "@/lib/access/shared/maintenance";
 import { HEALTH_PATH, healthResponse } from "@/lib/observability/shared/health";
+import { ServerTiming, withServerTiming } from "@/lib/observability/shared/serverTiming";
 import { observeDeployVersion } from "@/lib/activity/deployVersion";
 import { primeActivityKillSwitch } from "@/lib/activity/killSwitch";
 import {
@@ -73,20 +74,27 @@ function routeTierIndexFor(tenant: TenantConfig): RouteTierIndexV1 {
  * appended after the branch has read or written any edge cache.
  */
 export const onRequest = defineMiddleware(async (context, next) => {
+  // An in-process rewrite re-enters this middleware with the same locals; the outer pass owns
+  // the recorder and the header.
+  const outer = !context.locals.serverTiming;
+  const timing = context.locals.serverTiming ?? new ServerTiming();
+  context.locals.serverTiming = timing;
   const seen: { cdnForwarded: boolean; assetBasePath?: string } = { cdnForwarded: false };
-  const response = await serveRequest(context, next, seen);
+  const response = await serveRequest(context, next, seen, timing);
   const { scopePreviewPinnedImageUrls } = await import("@/lib/assets/preview-pinned-image-urls");
   const scoped = await scopePreviewPinnedImageUrls(response, context.locals.apiBasePath ?? seen.assetBasePath ?? "");
-  return withVisitorRegionCookie(
+  const finished = withVisitorRegionCookie(
     scoped,
     visitorRegionFor(context.request, { cdnForwarded: seen.cdnForwarded, dev: import.meta.env.DEV }),
   );
+  return outer ? withServerTiming(finished, timing) : finished;
 });
 
 async function serveRequest(
   context: APIContext,
   next: MiddlewareNext,
   seen: { cdnForwarded: boolean; assetBasePath?: string },
+  timing: ServerTiming,
 ): Promise<Response> {
   const { request, locals } = context;
   const url = new URL(request.url);
@@ -137,6 +145,16 @@ async function serveRequest(
   const crossSite = crossSiteFormRefusal(request, origin);
   if (crossSite) return crossSite;
 
+  // The canonical TEST sample GET signs server catalog facts without shopper state.
+  const sampleHandoff = new URL(SAMPLE_CART_HANDOFF_URL);
+  if (request.method === "GET" && !cdn && url.origin === sampleHandoff.origin &&
+      host === sampleHandoff.host && url.pathname === sampleHandoff.pathname) {
+    const { GET } = await import("@/pages/api/commerce/checkout-handoff");
+    const response = await GET(context);
+    applySecurityHeaders(response.headers);
+    return response;
+  }
+
   // Demo access gate for named hosts (DEMO_GATE_HOSTS). Two modes, switched by
   // DEMO_GATE_MODE:
   //   "password" (default) — interim Basic-Auth gate, enforced HERE (host-level,
@@ -158,10 +176,12 @@ async function serveRequest(
   // Host first; if the host owns no tenant, a leading /<domain>/ path segment
   // selects one (DNS-free tenant selection on localhost/preview). The resolver
   // is KV-backed in prod (many-tenant) and static in plain dev.
-  const resolver = await getTenantResolver();
-  const { tenant, basePath, renderPath } = cdn
-    ? await resolveCdnForwardRouting(cdn, url.pathname, resolver)
-    : await resolveTenantRouting(host, url.pathname, resolver);
+  const { tenant, basePath, renderPath } = await timing.time("tenant", async () => {
+    const resolver = await getTenantResolver();
+    return cdn
+      ? await resolveCdnForwardRouting(cdn, url.pathname, resolver)
+      : await resolveTenantRouting(host, url.pathname, resolver);
+  });
   if (!tenant) {
     return new Response("Unknown host", { status: 404 });
   }
@@ -214,13 +234,14 @@ async function serveRequest(
   let internalContentGrant: InternalContentGrant | undefined;
   if (publication.action !== "fail-closed" && route.requiresAuthorization) {
     const sessionKv = await readKv("SESSION");
-    const decision = await authorizeInternalContentRequest({
+    const coreUrl = await readEnv("TOT_CORE_URL");
+    const decision = await timing.time("internal-auth", () => authorizeInternalContentRequest({
       route,
       sessionStore: sessionKv ? new KvSessionStore(sessionKv) : undefined,
       sessionId: context.cookies.get(SESSION_COOKIE)?.value ?? null,
-      coreUrl: await readEnv("TOT_CORE_URL"),
+      coreUrl,
       mintAssertion: mintOpaqueBrokerAssertion,
-    });
+    }));
     if (decision.allowed) internalContentGrant = decision;
     if (!internalContentGrant) {
       const response = new Response("Not Found", { status: 404 });
@@ -288,7 +309,7 @@ async function serveRequest(
       (capturedRevisionId || renderPath.startsWith("/_a/"))
         ? ((await readR2("PRODUCT_IMAGES")) ?? (await readR2("TENANT_ASSETS")) ?? null)
         : null;
-    const bundled = await tryServeStaticBundle({
+    const bundled = await timing.time("bundle", () => tryServeStaticBundle({
       request,
       url,
       tenant,
@@ -309,7 +330,7 @@ async function serveRequest(
             },
           }
         : {}),
-    });
+    }));
     if (bundled) return bundled;
     const rootLocation = platformStaticRootLocationV1({
       origin,

package/apps/storefront/src/middleware/renderChain.ts

@@ -104,9 +104,10 @@ import {
   resolveIntegrationRenderState,
 } from "@/lib/integrations/integration/renderIntegrationState";
 import { recordActivity } from "@/lib/activity/recordActivity";
+import { timed } from "@/lib/observability/shared/serverTiming";
 import { middlewareRewriteTargetV1 } from "./routeBranch.js";
 import { declaredTenantOrigins } from "@/lib/access/shared/tenantOrigins";
-import { withDeclaredTenantConfig } from "@/config/declaredTenantConfig";
+import { DeclaredTenantConfigUnreadError, withDeclaredTenantConfig } from "@/config/declaredTenantConfig";
 import {
   applyInternalContentResponsePolicy,
   internalContentGrantMatchesPlan,
@@ -226,14 +227,15 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     });
   }
 
-  const publicationSource = await resolvePublicationRuntimeSourceV1({
+  const timing = locals.serverTiming;
+  const publicationSource = await timed(timing, "source", () => resolvePublicationRuntimeSourceV1({
     index: input.routeTierIndex,
     requestPath: input.publicationRequestPath,
     plan: input.publicationRoute,
     channel: channelFromEnv(customization.env),
     store: kv ? { get: (key) => kv.get(key) } : undefined,
     bucket: input.publicationBucket,
-  });
+  }));
   if (publicationSource.status === "unavailable") {
     const response = new Response("Not Found", {
       status: 404,
@@ -264,12 +266,26 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // features). Everything below — static bundle, notices, gates, features,
   // capabilities — reads this, never the bare record. A candidate-pinned render
   // takes the candidate version's declaration, so a reviewer sees the notices the
-  // change under review declares.
-  const tenant = await withDeclaredTenantConfig(
-    tenantRecord,
-    kv ? (key: string) => kv.get(key) : async () => null,
-    { env: customization.env, ...(candidatePin ? { pinnedVersionId: candidatePin.versionId } : {}) },
-  );
+  // change under review declares. A declaration that cannot be read refuses the
+  // render: the store's compliance is unknown, and its gates and notices with it.
+  let tenant: TenantConfig;
+  try {
+    tenant = await timed(timing, "config", () => withDeclaredTenantConfig(
+      tenantRecord,
+      kv ? (key: string) => kv.get(key) : async () => null,
+      { env: customization.env, ...(candidatePin ? { pinnedVersionId: candidatePin.versionId } : {}) },
+    ));
+  } catch (err) {
+    if (!(err instanceof DeclaredTenantConfigUnreadError)) throw err;
+    console.error(err.message);
+    const response = new Response("Service Unavailable", {
+      status: 503,
+      headers: { "Cache-Control": "private, no-store", "Retry-After": "30" },
+    });
+    applySecurityHeaders(response.headers);
+    if (isInternalPublication) applyInternalContentResponsePolicy(response.headers);
+    return response;
+  }
   // Request-scoped read memo: every content read resolves the same pointer and
   // version manifest, and a catalog render reads one artifact per catalog file.
   const kvReads = new Map<string, Promise<string | null>>();
@@ -351,12 +367,18 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     secret: previewSecret,
     nowSeconds,
   });
-  const capturedRevisionId = candidatePin?.versionId ?? cookieRevision;
+  // The shared preview sets no version cookie, yet its documents name `/_a/` captures of the
+  // version the preview channel serves (capture overlay); those resolve against that version.
+  const sharedPreviewRevision = !candidatePin && !cookieRevision && customization.env === "test" &&
+    renderPath.startsWith("/_a/")
+    ? (await resolveServableChannelVersion(kvGet, tenant.tenant_id, "preview")).versionId
+    : null;
+  const capturedRevisionId = candidatePin?.versionId ?? cookieRevision ?? sharedPreviewRevision;
   const originalsBucket =
     (capturedRevisionId || renderPath.startsWith("/_a/"))
       ? ((await readR2("PRODUCT_IMAGES")) ?? (await readR2("TENANT_ASSETS")) ?? null)
       : null;
-  const bundled = publicationSource.status === "legacy-root" ? await tryServeStaticBundle({
+  const bundled = publicationSource.status === "legacy-root" ? await timed(timing, "bundle", () => tryServeStaticBundle({
     request,
     url,
     tenant,
@@ -376,7 +398,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
           },
         }
       : {}),
-  }) : null;
+  })) : null;
   if (bundled) return bundled;
 
   // ---- Tenant-local integration materialization (ext-kernel-09) --------------
@@ -496,10 +518,10 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     !candidatePin &&
     !draftCookie &&
     !isInternalPublication &&
-    isCacheablePath(url.pathname, url.searchParams);
+    isCacheablePath(url.pathname);
   let pageKey: Request | null = null;
   if (pageCacheEligible && cache && kv) {
-    const version = await readCacheVersion(kv, tenant.tenant_id);
+    const version = await timed(timing, "page-cache", () => readCacheVersion(kv, tenant.tenant_id));
     // Fold the resolved integration plan revision into the key so a warm entry is
     // version-scoped: a rollback/uninstall resolves a new revision → old entry
     // unreachable → clean re-render without the removed origins (never a TTL wait).
@@ -514,7 +536,9 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
       locals.integrationCsp?.planRevision,
       publicationSource.status === "selected" ? publicationSource.cacheScope : undefined,
     );
-    const hit = await getCachedPage(cache, pageKey);
+    const key = pageKey;
+    const hit = await timed(timing, "page-cache", () => getCachedPage(cache, key));
+    timing?.note("cache", hit ? "hit" : "miss");
     // The cached artifact is nonce-free (carries the placeholder). Stamp a fresh
     // per-response nonce into its body + CSP header so a warm hit is served with a
     // brand-new nonce, never the one an earlier response rendered with.
@@ -544,7 +568,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // below still run).
   if (kv && !candidatePin) {
     const channel = channelFromEnv(customization.env);
-    await resolveServableChannelVersion(kvGet, tenant.tenant_id, channel, ({ versionId }) => {
+    await timed(timing, "channel", () => resolveServableChannelVersion(kvGet, tenant.tenant_id, channel, ({ versionId }) => {
       recordActivity({
         action: "preview.build.requested",
         actor: { kind: "system", id: "storefront" },
@@ -553,7 +577,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
         scope: { tenantId: tenant.tenant_id },
         payload: { args: { changeId: versionId } },
       });
-    }).catch(() => {
+    })).catch(() => {
       /* fail-open: self-heal detection never breaks the request */
     });
   }
@@ -570,7 +594,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     draftClaims && draftClaims.tenantId === tenant.tenant_id ? draftClaims : null;
 
   let theme = mergeTheme(referenceTheme, tenant.theme_tokens);
-  const publishedTheme = await readRuntimeArtifact(themeArtifactPath(tenant.tenant_id));
+  const publishedTheme = await timed(timing, "artifacts", () => readRuntimeArtifact(themeArtifactPath(tenant.tenant_id)));
   if (publishedTheme) {
     try {
       theme = mergeTheme(theme, JSON.parse(publishedTheme) as DeepPartial<ThemeTokens>);
@@ -596,7 +620,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // commit (localhost=working tree, preview=PR head, live=promoted). So a
   // capability change is PR-gated and separable per environment.
   let publishedCaps: Partial<CapabilityConfig> | null = null;
-  const publishedCapsRaw = await readRuntimeArtifact(capabilitiesArtifactPath(tenant.tenant_id));
+  const publishedCapsRaw = await timed(timing, "artifacts", () => readRuntimeArtifact(capabilitiesArtifactPath(tenant.tenant_id)));
   if (publishedCapsRaw) {
     try {
       publishedCaps = JSON.parse(publishedCapsRaw) as Partial<CapabilityConfig>;
@@ -612,7 +636,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // tenant enables a catalogued embed by committing embeds.json — no platform
   // change — but can never introduce a non-catalog origin.
   let publishedEmbeds: string[] | null = null;
-  const publishedEmbedsRaw = await readRuntimeArtifact(embedsArtifactPath(tenant.tenant_id));
+  const publishedEmbedsRaw = await timed(timing, "artifacts", () => readRuntimeArtifact(embedsArtifactPath(tenant.tenant_id)));
   if (publishedEmbedsRaw) {
     try {
       const parsed = JSON.parse(publishedEmbedsRaw);
@@ -648,7 +672,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // loader + signed add-to-cart, and the CSP additions below.
   const commerce =
     locals.features.catalog && capabilities.cartCheckout.enabled
-      ? await resolveTenantCommerce(tenant)
+      ? await timed(timing, "commerce", () => resolveTenantCommerce(tenant))
       : null;
   locals.commerce = commerce ?? undefined;
   // Developer-draft content overlay — serves the AI-edited artifacts to the draft
@@ -666,7 +690,8 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // are read through the SAME content source just resolved, so they follow the
   // request's selected version exactly as pages and the blog do. Only the control
   // plane supplies the D1 projection; the public branch never reads D1.
-  locals.tot = await createToTClient(tenant, await input.readCatalogD1?.(), locals.content);
+  locals.tot = await timed(timing, "catalog", async () =>
+    createToTClient(tenant, await input.readCatalogD1?.(), locals.content));
   locals.themeStyle = themeToCssVars(theme);
   locals.canonicalBase = canonicalBase;
   locals.customizationEnv = customization.env;
@@ -733,9 +758,9 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     // request. Rewriting there discards the route it already chose.
     routePattern: context.routePattern,
   });
-  let response = rewriteTarget !== undefined
-    ? await next(rewriteTarget)
-    : await next();
+  let response = await timed(timing, "render", () => rewriteTarget !== undefined
+    ? next(rewriteTarget)
+    : next());
 
   // A nested pass of this middleware (an in-process `rewrite()`) already decorated
   // and nonce-stamped the response. Serve it verbatim: decorating again would inject
@@ -869,7 +894,8 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     );
     // Store the nonce-free artifact (the placeholder is still in the body + CSP
     // header) BEFORE stamping — so the cache never holds a live/reusable nonce.
-    await putCachedPage(cache, pageKey, response);
+    const key = pageKey;
+    await timed(timing, "page-cache", () => putCachedPage(cache, key, response));
   }
   // MATERIALIZE-ONLY capture (ADR 0013): expose the tenant's resolved route-document
   // Cache-Control so the publish/materialize plane can bake it into the bundle

package/apps/storefront/src/pages/[...slug].astro

@@ -40,6 +40,9 @@ if (
 // dir, so the pages live under `/style-guide/…` and we rewrite the underscored URL
 // onto them, under the same tenant prefix. These are noindex + sitemap-excluded and
 // never reskin the live site.
+// Its query, like the `__preview` flag below, only matters to a Worker render: the
+// static copy of a page is the published, non-preview render.
+export const STATIC_QUERY = "render-only";
 const styleGuideTarget = styleGuideAliasRewrite(basePath, slug, Astro.url.search);
 if (styleGuideTarget !== undefined) {
   return Astro.rewrite(styleGuideTarget);