@tokenoftrust/storefront-runner 2.0.18 → 2.0.20

package/packages/public-runtime/src/publication-routing.ts

@@ -0,0 +1,246 @@
+/**
+ * One publication request plan: normalized mount resolution, canonical route,
+ * content lookup path, and independently selected immutable version.
+ *
+ * The route-tier resolver owns normalization and longest-prefix matching. This
+ * module consumes that answer without decoding or canonicalizing the request a
+ * second time, so request routing, preview, static materialization, and canonical
+ * URL generation cannot disagree about which publication space owns a path.
+ */
+import type { ContractViolation } from "./integration/result.js";
+import {
+  resolvePublicationChannelVersionV1,
+  validatePublicationVersionStateV1,
+  type PublicationChannelPointerV1,
+  type PublicationChannelV1,
+  type PublicationVersionStateV1,
+  type PublicationVersionV1,
+} from "./publication-version.js";
+import {
+  resolveRouteTierV1,
+  type ResolvedRouteTierV1,
+  type RouteTierIndexV1,
+} from "./route-tier.js";
+import type { PublicationSpaceManifestV1 } from "./publication-space.js";
+
+export const PUBLICATION_ROUTE_PLAN_VERSION = 1 as const;
+
+export type PublicationRouteFailureCodeV1 =
+  | "publication_route_unresolved"
+  | "publication_route_authority_mismatch"
+  | "publication_state_malformed"
+  | "publication_channel_unselected"
+  | "publication_version_provenance_mismatch"
+  | "publication_renderer_contract_mismatch";
+
+export interface PublicationRouteRenderPlanV1 {
+  version: typeof PUBLICATION_ROUTE_PLAN_VERSION;
+  action: "render";
+  route: ResolvedRouteTierV1;
+  manifest: PublicationSpaceManifestV1;
+  /** Normalized route as requested, with the matched mount still attached. */
+  requestPath: string;
+  /** Route relative to the selected publication source. Always absolute. */
+  contentPath: string;
+  /** Canonical tenant-relative route used by links and Astro dispatch. */
+  canonicalPath: string;
+  assetNamespace: string;
+}
+
+export interface PublicationRouteRedirectPlanV1 {
+  version: typeof PUBLICATION_ROUTE_PLAN_VERSION;
+  action: "redirect-308";
+  route: ResolvedRouteTierV1;
+  manifest: PublicationSpaceManifestV1;
+  requestPath: string;
+  /** Canonical tenant-relative redirect target, including the unmatched suffix. */
+  locationPath: string;
+}
+
+export interface PublicationRouteFailedPlanV1 {
+  version: typeof PUBLICATION_ROUTE_PLAN_VERSION;
+  action: "fail-closed";
+  route: ResolvedRouteTierV1;
+  code: "publication_route_unresolved";
+  violations: readonly ContractViolation[];
+}
+
+export type PublicationRoutePlanV1 =
+  | PublicationRouteRenderPlanV1
+  | PublicationRouteRedirectPlanV1
+  | PublicationRouteFailedPlanV1;
+
+export interface SelectedPublicationRouteV1 extends PublicationRouteRenderPlanV1 {
+  channel: PublicationChannelV1;
+  pointer: PublicationChannelPointerV1;
+  publicationVersion: PublicationVersionV1;
+}
+
+export type PublicationRouteSelectionV1 =
+  | { ok: true; value: SelectedPublicationRouteV1 }
+  | { ok: false; code: PublicationRouteFailureCodeV1; plan: PublicationRoutePlanV1 };
+
+function suffixAfterMount(path: string, mount: string): string {
+  if (mount === "/") return path === "/" ? "" : path;
+  return path === mount ? "" : path.slice(mount.length);
+}
+
+function appendSuffix(mount: string, suffix: string): string {
+  if (!suffix) return mount;
+  if (mount === "/") return suffix;
+  return `${mount}${suffix}`;
+}
+
+/** Resolve one request through the already-compiled tenant mount authority. */
+export function resolvePublicationRoutePlanV1(
+  index: RouteTierIndexV1,
+  requestPath: string,
+): PublicationRoutePlanV1 {
+  const route = resolveRouteTierV1(index, requestPath);
+  const mount = route.mount;
+  const spaceId = route.space?.spaceId;
+  const manifest = spaceId ? index.spaces.get(spaceId) : undefined;
+  if (route.origin !== "publication-space" || !mount || !manifest) {
+    return {
+      version: PUBLICATION_ROUTE_PLAN_VERSION,
+      action: "fail-closed",
+      route,
+      code: "publication_route_unresolved",
+      violations: route.violations,
+    };
+  }
+
+  const suffix = suffixAfterMount(route.path, mount.mount);
+  if (mount.behavior === "redirect-308") {
+    if (!mount.redirectTo) {
+      return {
+        version: PUBLICATION_ROUTE_PLAN_VERSION,
+        action: "fail-closed",
+        route,
+        code: "publication_route_unresolved",
+        violations: [{
+          path: "mount.redirectTo",
+          code: "publication_redirect_target_required",
+          message: "A redirect publication mount must have a canonical target.",
+        }],
+      };
+    }
+    return {
+      version: PUBLICATION_ROUTE_PLAN_VERSION,
+      action: "redirect-308",
+      route,
+      manifest,
+      requestPath: route.path,
+      locationPath: appendSuffix(mount.redirectTo, suffix),
+    };
+  }
+
+  return {
+    version: PUBLICATION_ROUTE_PLAN_VERSION,
+    action: "render",
+    route,
+    manifest,
+    requestPath: route.path,
+    contentPath: suffix || "/",
+    canonicalPath: appendSuffix(mount.canonicalMount, suffix),
+    assetNamespace: manifest.assets.namespace,
+  };
+}
+
+/**
+ * Prove a carried plan still describes the current registry and request. This
+ * check must run before pointer or artifact I/O whenever a plan crosses a seam.
+ */
+export function publicationRoutePlanIsCurrentV1(
+  index: RouteTierIndexV1,
+  requestPath: string,
+  plan: PublicationRoutePlanV1,
+): boolean {
+  return JSON.stringify(resolvePublicationRoutePlanV1(index, requestPath)) === JSON.stringify(plan);
+}
+
+/**
+ * Bind a render plan to exactly one channel pointer and immutable version.
+ * Any malformed/missing/mismatched state fails closed; there is no root or
+ * tenant-wide fallback after a publication space has been selected.
+ */
+export function selectPublicationRouteVersionV1(
+  index: RouteTierIndexV1,
+  requestPath: string,
+  plan: PublicationRoutePlanV1,
+  stateRaw: PublicationVersionStateV1,
+  channel: PublicationChannelV1,
+): PublicationRouteSelectionV1 {
+  if (!publicationRoutePlanIsCurrentV1(index, requestPath, plan)) {
+    return { ok: false, code: "publication_route_authority_mismatch", plan };
+  }
+  if (plan.action !== "render") {
+    return { ok: false, code: "publication_route_unresolved", plan };
+  }
+  const checked = validatePublicationVersionStateV1(stateRaw);
+  if (!checked.ok) return { ok: false, code: "publication_state_malformed", plan };
+  const selected = resolvePublicationChannelVersionV1(
+    checked.value,
+    plan.manifest.tenant,
+    plan.manifest.id,
+    channel,
+  );
+  if (!selected) return { ok: false, code: "publication_channel_unselected", plan };
+  const { pointer, version } = selected;
+  if (
+    version.source.forge !== plan.manifest.source.forge ||
+    version.source.repo !== plan.manifest.source.repo ||
+    version.source.commitSha !== pointer.sourceSha
+  ) {
+    return { ok: false, code: "publication_version_provenance_mismatch", plan };
+  }
+  if (
+    version.renderer.contractVersion !== plan.manifest.renderer.contractVersion ||
+    version.renderer.themeContractVersion !== plan.manifest.renderer.themeContractVersion
+  ) {
+    return { ok: false, code: "publication_renderer_contract_mismatch", plan };
+  }
+  return {
+    ok: true,
+    value: {
+      ...plan,
+      channel,
+      pointer,
+      publicationVersion: version,
+    },
+  };
+}
+
+/** Build an absolute canonical URL without carrying query or fragment input. */
+export function publicationCanonicalUrlV1(
+  canonicalOrigin: string,
+  plan: Pick<PublicationRouteRenderPlanV1, "canonicalPath">,
+): string {
+  const origin = new URL(canonicalOrigin);
+  return new URL(plan.canonicalPath, `${origin.protocol}//${origin.host}`).toString();
+}
+
+/**
+ * Canonicalize a tenant-relative link through the same mount authority as a
+ * request. Queries/fragments are opaque suffixes; only the path is resolved.
+ * External, protocol-relative, reserved, and malformed routes fail closed.
+ */
+export function canonicalizePublicationLinkV1(
+  index: RouteTierIndexV1,
+  href: string,
+): string | null {
+  if (!href.startsWith("/") || href.startsWith("//")) return null;
+  const query = href.indexOf("?");
+  const fragment = href.indexOf("#");
+  const delimiter = query === -1
+    ? fragment
+    : fragment === -1
+      ? query
+      : Math.min(query, fragment);
+  const path = delimiter === -1 ? href : href.slice(0, delimiter);
+  const suffix = delimiter === -1 ? "" : href.slice(delimiter);
+  const plan = resolvePublicationRoutePlanV1(index, path);
+  if (plan.action === "fail-closed") return null;
+  const canonicalPath = plan.action === "render" ? plan.canonicalPath : plan.locationPath;
+  return `${canonicalPath}${suffix}`;
+}

package/packages/public-runtime/src/publication-version.ts

@@ -390,6 +390,21 @@ export function serializePublicationTransitionRequestV1(value: PublicationTransi
   return serializeValidated(value, validatePublicationTransitionRequestV1, "PublicationTransitionRequestV1");
 }
 
+export function parsePublicationVersionStateV1Json(json: string): ContractResult<PublicationVersionStateV1> {
+  return parseJson(json, (raw) => validatePublicationVersionStateV1(raw as PublicationVersionStateV1));
+}
+export function serializePublicationVersionStateV1(value: PublicationVersionStateV1): string {
+  return serializeValidated(
+    value,
+    (raw) => validatePublicationVersionStateV1(raw as PublicationVersionStateV1),
+    "PublicationVersionStateV1",
+  );
+}
+/** Public read projection for one tenant's exact publication pointer state. */
+export function publicationVersionStateKey(tenant: string): string {
+  return `cust:publication-state:${tenant}`;
+}
+
 export function publicationVersionKey(tenant: string, spaceId: string, versionId: string): string {
   return `cust:publication-version:${tenant}:${spaceId}:${versionId}`;
 }