@decocms/blocks 7.0.0

package/src/middleware/hydrationContext.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { buildHydrationContext } from "./hydrationContext";
+
+function makeRequest(headers: Record<string, string> = {}): Request {
+  return new Request("https://store.com/", { headers });
+}
+
+describe("buildHydrationContext", () => {
+  it("extracts locale and timezone from cookies", () => {
+    const req = makeRequest({ cookie: "locale=pt-BR; tz=America/Sao_Paulo" });
+    const ctx = buildHydrationContext(req);
+    expect(ctx.locale).toBe("pt-BR");
+    expect(ctx.timeZone).toBe("America/Sao_Paulo");
+  });
+
+  it("falls back to Accept-Language when no locale cookie", () => {
+    const req = makeRequest({ "accept-language": "pt-BR,pt;q=0.9,en;q=0.8" });
+    const ctx = buildHydrationContext(req);
+    expect(ctx.locale).toBe("pt-BR");
+  });
+
+  it("defaults to en-US and UTC when no headers or cookies", () => {
+    const req = makeRequest();
+    const ctx = buildHydrationContext(req);
+    expect(ctx.locale).toBe("en-US");
+    expect(ctx.timeZone).toBe("UTC");
+  });
+
+  it("extracts country from cf-ipcountry header", () => {
+    const req = makeRequest({ "cf-ipcountry": "BR" });
+    const ctx = buildHydrationContext(req);
+    expect(ctx.country).toBe("BR");
+  });
+
+  it("extracts country from cookie when no cf header", () => {
+    const req = makeRequest({ cookie: "country=US" });
+    const ctx = buildHydrationContext(req);
+    expect(ctx.country).toBe("US");
+  });
+
+  it("country is undefined when not available", () => {
+    const req = makeRequest();
+    const ctx = buildHydrationContext(req);
+    expect(ctx.country).toBeUndefined();
+  });
+
+  it("cf-ipcountry takes precedence over cookie", () => {
+    const req = makeRequest({
+      "cf-ipcountry": "BR",
+      cookie: "country=US",
+    });
+    const ctx = buildHydrationContext(req);
+    expect(ctx.country).toBe("BR");
+  });
+
+  it("handles cookies with = in values", () => {
+    const req = makeRequest({ cookie: "locale=en-US; token=abc=def=ghi" });
+    const ctx = buildHydrationContext(req);
+    expect(ctx.locale).toBe("en-US");
+  });
+});

package/src/middleware/hydrationContext.ts

@@ -0,0 +1,79 @@
+/**
+ * Hydration context utilities for consistent SSR/client rendering.
+ *
+ * Provides patterns for extracting locale, timezone, and other
+ * request-specific data that must be consistent between server
+ * and client to avoid hydration mismatches.
+ *
+ * @example
+ * ```tsx
+ * // In your storefront's middleware.ts:
+ * import { createMiddleware } from "@tanstack/react-start";
+ * import { buildHydrationContext } from "@decocms/start/middleware/hydrationContext";
+ *
+ * export const hydrationMiddleware = createMiddleware().server(async ({ request, next }) => {
+ *   const hydrationCtx = buildHydrationContext(request);
+ *   return next({ context: { hydration: hydrationCtx } });
+ * });
+ * ```
+ *
+ * Then in components:
+ * ```tsx
+ * // Use the cookie-based values for deterministic SSR rendering
+ * const locale = hydrationCtx.locale; // same on server and client
+ * ```
+ */
+
+export interface HydrationContext {
+  /** Locale from cookie or Accept-Language header. */
+  locale: string;
+  /** Timezone from cookie. Falls back to "UTC" for deterministic SSR. */
+  timeZone: string;
+  /** Country code from Cloudflare headers or cookie. */
+  country?: string;
+}
+
+/**
+ * Build hydration context from a request.
+ *
+ * Values are extracted from cookies first (set by the client on first visit),
+ * then from headers. Cookie-based values are deterministic because the same
+ * cookie is sent on both SSR and client-side navigations.
+ *
+ * Recommended: set these cookies on first client render:
+ * ```tsx
+ * useEffect(() => {
+ *   const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+ *   document.cookie = `tz=${tz}; path=/; max-age=31536000; SameSite=Lax`;
+ *   document.cookie = `locale=${navigator.language}; path=/; max-age=31536000; SameSite=Lax`;
+ * }, []);
+ * ```
+ */
+export function buildHydrationContext(request: Request): HydrationContext {
+  const cookies = parseCookies(request.headers.get("cookie") ?? "");
+
+  // Locale: cookie → Accept-Language → fallback
+  const locale =
+    cookies.locale ||
+    request.headers.get("accept-language")?.split(",")[0]?.split(";")[0]?.trim() ||
+    "en-US";
+
+  // Timezone: cookie → UTC fallback (never guess — causes hydration mismatch)
+  const timeZone = cookies.tz || "UTC";
+
+  // Country: Cloudflare header → cookie
+  const country =
+    request.headers.get("cf-ipcountry") || cookies.country || undefined;
+
+  return { locale, timeZone, country };
+}
+
+function parseCookies(cookieHeader: string): Record<string, string> {
+  const cookies: Record<string, string> = {};
+  for (const part of cookieHeader.split(";")) {
+    const [key, ...rest] = part.split("=");
+    const k = key?.trim();
+    if (k) cookies[k] = rest.join("=").trim();
+  }
+  return cookies;
+}

package/src/middleware/index.ts

@@ -0,0 +1,88 @@
+/**
+ * Deco middleware utilities for TanStack Start.
+ *
+ * These are NOT TanStack `createMiddleware()` instances because
+ * `@decocms/start` doesn't depend on `@tanstack/react-start`.
+ * Instead, they export composable handler functions that storefronts
+ * wire into their own `createMiddleware()` chain.
+ *
+ * @example
+ * ```ts
+ * // In your storefront's middleware.ts
+ * import { createMiddleware } from "@tanstack/react-start";
+ * import { buildDecoState, handleLiveness, applyServerTiming, applyCorsHeaders } from "@decocms/start/middleware";
+ *
+ * export const decoMiddleware = createMiddleware().server(async ({ request, next }) => {
+ *   const liveness = handleLiveness(request);
+ *   if (liveness) return { result: undefined, response: liveness };
+ *
+ *   const state = buildDecoState(request, "my-site");
+ *   const endTotal = state.timings.start("total");
+ *
+ *   const result = await next();
+ *
+ *   endTotal();
+ *   applyServerTiming(result.response, state);
+ *   if (state.isAdmin) applyCorsHeaders(result.response, request);
+ *
+ *   return result;
+ * });
+ * ```
+ */
+
+export {
+  type CacheDecision,
+  configureMeter,
+  configureTracer,
+  getActiveSpan,
+  getMeter,
+  getTracer,
+  injectTraceContext,
+  logRequest,
+  type MeterAdapter,
+  MetricNames,
+  recordCacheMetric,
+  recordRequestMetric,
+  type Span,
+  setSpanAttribute,
+  type TracerAdapter,
+  withTracing,
+} from "../sdk/observability";
+export { buildDecoState, type DecoState } from "./decoState";
+export {
+  getHealthMetrics,
+  type HealthMetrics,
+  handleHealthCheck,
+  trackRequest,
+} from "./healthMetrics";
+export { buildHydrationContext, type HydrationContext } from "./hydrationContext";
+export { handleLiveness } from "./liveness";
+export {
+  createSectionValidator,
+  type DeferredSectionInput,
+  validateDeferredSectionInput,
+} from "./validateSection";
+
+/**
+ * Appends Server-Timing header to a response from the accumulated timings.
+ */
+export function applyServerTiming(response: Response, state: { timings: { toHeader(): string } }) {
+  const header = state.timings.toHeader();
+  if (header) {
+    response.headers.append("Server-Timing", header);
+  }
+}
+
+/**
+ * Applies CORS headers for deco admin origins to a response.
+ */
+export function applyCorsHeaders(response: Response, request: Request) {
+  const origin = request.headers.get("origin") || "*";
+  response.headers.set("Access-Control-Allow-Origin", origin);
+  response.headers.set("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+  response.headers.set(
+    "Access-Control-Allow-Headers",
+    "Content-Type, Authorization, If-None-Match",
+  );
+  response.headers.set("Access-Control-Allow-Credentials", "true");
+}

package/src/middleware/liveness.ts

@@ -0,0 +1,21 @@
+/**
+ * Liveness and readiness probe handlers.
+ *
+ * - `/_liveness` — simple 200 OK for load balancers (K8s, Cloudflare)
+ * - `/deco/_health` — detailed JSON health metrics (delegated to healthMetrics)
+ */
+
+import { handleHealthCheck } from "./healthMetrics";
+
+export function handleLiveness(request: Request): Response | null {
+  const url = new URL(request.url);
+
+  if (url.pathname === "/_liveness" || url.pathname === "/deco/_liveness") {
+    return new Response("OK", {
+      status: 200,
+      headers: { "Content-Type": "text/plain", "Cache-Control": "no-store" },
+    });
+  }
+
+  return handleHealthCheck(request);
+}

package/src/middleware/observability.test.ts

@@ -0,0 +1,238 @@
+/**
+ * Phase 2 (D-11) coverage for the metric surface — canonical label set,
+ * cache_layer, commerce_request_duration_ms. The Phase 1 logger/trace
+ * tests live under `src/sdk/logger.test.ts` and `src/sdk/otel.test.ts`;
+ * this file focuses on the middleware-level helpers.
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  configureMeter,
+  type MeterAdapter,
+  MetricNames,
+  recordCacheMetric,
+  recordCommerceMetric,
+  recordRequestMetric,
+  statusClassFor,
+} from "./observability";
+
+interface Counter {
+  name: string;
+  value: number;
+  labels?: Record<string, unknown>;
+}
+interface Histogram {
+  name: string;
+  value: number;
+  labels?: Record<string, unknown>;
+}
+
+function captureMeter(): {
+  adapter: MeterAdapter;
+  counters: Counter[];
+  histograms: Histogram[];
+} {
+  const counters: Counter[] = [];
+  const histograms: Histogram[] = [];
+  const adapter: MeterAdapter = {
+    counterInc(name, value, labels) {
+      counters.push({ name, value: value ?? 1, labels });
+    },
+    histogramRecord(name, value, labels) {
+      histograms.push({ name, value, labels });
+    },
+  };
+  return { adapter, counters, histograms };
+}
+
+describe("statusClassFor", () => {
+  it("maps 2xx / 3xx / 4xx / 5xx to canonical class labels", () => {
+    expect(statusClassFor(200)).toBe("2xx");
+    expect(statusClassFor(204)).toBe("2xx");
+    expect(statusClassFor(301)).toBe("3xx");
+    expect(statusClassFor(404)).toBe("4xx");
+    expect(statusClassFor(500)).toBe("5xx");
+    expect(statusClassFor(503)).toBe("5xx");
+  });
+
+  it("returns 'unknown' for out-of-range / NaN / non-numeric inputs", () => {
+    expect(statusClassFor(-1)).toBe("unknown");
+    expect(statusClassFor(99)).toBe("unknown");
+    expect(statusClassFor(600)).toBe("unknown");
+    expect(statusClassFor(Number.NaN)).toBe("unknown");
+    expect(statusClassFor(Infinity)).toBe("unknown");
+  });
+});
+
+describe("recordRequestMetric — canonical labels (D-11)", () => {
+  afterEach(() => {
+    // Reset meter so other tests start clean.
+    configureMeter({ counterInc: () => {} });
+  });
+
+  it("stamps method + route_pattern + status + status_class by default", () => {
+    const { adapter, counters, histograms } = captureMeter();
+    configureMeter(adapter);
+
+    recordRequestMetric("GET", "/products/abc123/p", 200, 42);
+
+    // Canonical OTel HTTP server metric is histogram-only; the count
+    // dimension is derived from the histogram's bucket counts at query
+    // time, so we no longer emit a parallel `_total` counter.
+    expect(counters).toHaveLength(0);
+    expect(histograms).toHaveLength(1);
+    expect(histograms[0]?.name).toBe(MetricNames.HTTP_SERVER_REQUEST_DURATION);
+    expect(histograms[0]?.value).toBe(42);
+    expect(histograms[0]?.labels).toMatchObject({
+      method: "GET",
+      // Default normalization: dynamic segments collapsed.
+      route_pattern: "/products/:slug/p",
+      status: 200,
+      status_class: "2xx",
+    });
+  });
+
+  it("prefers caller-supplied route_pattern over normalized path", () => {
+    const { adapter, histograms } = captureMeter();
+    configureMeter(adapter);
+
+    recordRequestMetric("GET", "/anything/random/123", 200, 5, {
+      route_pattern: "/_products/$slug/p",
+    });
+
+    expect(histograms[0]?.labels?.route_pattern).toBe("/_products/$slug/p");
+  });
+
+  it("tags 5xx requests with status_class=5xx for downstream error filtering", () => {
+    const { adapter, histograms } = captureMeter();
+    configureMeter(adapter);
+
+    recordRequestMetric("POST", "/checkout", 503, 120);
+
+    expect(histograms[0]?.labels?.status_class).toBe("5xx");
+    expect(histograms[0]?.labels?.status).toBe(503);
+  });
+
+  it("propagates optional labels (outcome, cache_decision, cache_layer, region, extra)", () => {
+    const { adapter, histograms } = captureMeter();
+    configureMeter(adapter);
+
+    recordRequestMetric("GET", "/", 200, 10, {
+      outcome: "ok",
+      cache_decision: "STALE-HIT",
+      cache_layer: "edge",
+      region: "GRU",
+      extra: { ab_variant: "B" },
+    });
+
+    expect(histograms[0]?.labels).toMatchObject({
+      outcome: "ok",
+      cache_decision: "STALE-HIT",
+      cache_layer: "edge",
+      region: "GRU",
+      ab_variant: "B",
+    });
+  });
+
+  it("is a no-op when no meter is configured", () => {
+    // We can't easily prove a no-op other than verifying no throw —
+    // safer than calling configureMeter(null), which would mask real
+    // bugs. The previous test's `afterEach` reset already gives us a
+    // bare meter; this test confirms the call is benign.
+    expect(() => recordRequestMetric("GET", "/", 200, 1)).not.toThrow();
+  });
+});
+
+describe("recordCacheMetric — cache_layer label", () => {
+  beforeEach(() => {
+    configureMeter({ counterInc: () => {} });
+  });
+
+  it("stamps profile + decision + layer when all are provided", () => {
+    const { adapter, counters } = captureMeter();
+    configureMeter(adapter);
+
+    recordCacheMetric(true, "product", "HIT", "edge");
+
+    expect(counters).toHaveLength(1);
+    expect(counters[0]?.name).toBe(MetricNames.CACHE_HIT);
+    expect(counters[0]?.labels).toMatchObject({
+      profile: "product",
+      cache_decision: "HIT",
+      cache_layer: "edge",
+    });
+  });
+
+  it("emits cache_miss_total when hit=false", () => {
+    const { adapter, counters } = captureMeter();
+    configureMeter(adapter);
+
+    recordCacheMetric(false, "search", "MISS", "edge");
+
+    expect(counters[0]?.name).toBe(MetricNames.CACHE_MISS);
+  });
+
+  it("supports the legacy 3-arg signature for backward compat", () => {
+    const { adapter, counters } = captureMeter();
+    configureMeter(adapter);
+
+    recordCacheMetric(true, "static");
+
+    expect(counters[0]?.labels).toEqual({ profile: "static" });
+  });
+
+  it("distinguishes cachedLoader vs edge vs vtex-swr layers", () => {
+    const { adapter, counters } = captureMeter();
+    configureMeter(adapter);
+
+    recordCacheMetric(true, "loader-x", "HIT", "cachedLoader");
+    recordCacheMetric(true, "vtex-product", "HIT", "vtex-swr");
+
+    expect(counters[0]?.labels?.cache_layer).toBe("cachedLoader");
+    expect(counters[1]?.labels?.cache_layer).toBe("vtex-swr");
+  });
+});
+
+describe("recordCommerceMetric (D-11)", () => {
+  beforeEach(() => {
+    configureMeter({ counterInc: () => {} });
+  });
+
+  it("emits http.client.request.duration with provider + operation labels", () => {
+    const { adapter, histograms } = captureMeter();
+    configureMeter(adapter);
+
+    recordCommerceMetric(123, {
+      provider: "vtex",
+      operation: "intelligent-search.product_search",
+      status_class: "2xx",
+    });
+
+    expect(histograms).toHaveLength(1);
+    expect(histograms[0]?.name).toBe(MetricNames.HTTP_CLIENT_REQUEST_DURATION);
+    expect(histograms[0]?.value).toBe(123);
+    expect(histograms[0]?.labels).toMatchObject({
+      provider: "vtex",
+      operation: "intelligent-search.product_search",
+      status_class: "2xx",
+    });
+  });
+
+  it("includes the cached boolean when provided", () => {
+    const { adapter, histograms } = captureMeter();
+    configureMeter(adapter);
+
+    recordCommerceMetric(5, {
+      provider: "shopify",
+      operation: "graphql.cart_query",
+      cached: true,
+    });
+
+    expect(histograms[0]?.labels?.cached).toBe(true);
+  });
+
+  it("is a no-op when no meter is configured", () => {
+    expect(() =>
+      recordCommerceMetric(1, { provider: "vtex", operation: "test" }),
+    ).not.toThrow();
+  });
+});