@decocms/blocks 7.0.0

package/src/sdk/logger.ts

@@ -0,0 +1,304 @@
+/**
+ * Pluggable structured logger for @decocms/start.
+ *
+ * Mirrors the public shape of `@deco/deco/o11y` logger so site code that
+ * does `logger.info("...", { key: "value" })` keeps working unchanged
+ * after the Fresh → TanStack migration.
+ *
+ * Backed by a `LoggerAdapter`. The default adapter writes one JSON line
+ * to `console.log` per call — that line is what Cloudflare Logs / Logpush
+ * captures, so logging works out of the box on Workers without any
+ * additional configuration.
+ *
+ * To dual-emit to OTLP (HyperDX, etc.), wrap the default with
+ * `createCompositeLogger([defaultLoggerAdapter, otelLoggerAdapter])`
+ * inside `instrumentWorker()`.
+ *
+ * @example
+ * ```ts
+ * import { logger } from "@decocms/start/sdk/logger";
+ *
+ * logger.info("checkout started", { orderFormId, items: cart.items.length });
+ * logger.warn("retrying vtex call", { attempt, host });
+ * logger.error("payment failed", { reason, code, traceId });
+ * ```
+ */
+
+import { getActiveSpan } from "./observability";
+import { RequestContext } from "./requestContext";
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+const LEVEL_RANK: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+export interface LoggerAdapter {
+  log(level: LogLevel, msg: string, attrs?: Record<string, unknown>): void;
+}
+
+// ---------------------------------------------------------------------------
+// Default adapter — structured JSON to console.log
+// ---------------------------------------------------------------------------
+
+/**
+ * Cloudflare-Logs-friendly default. One JSON object per call, on stdout.
+ * Always safe to use — never throws, never depends on env, never makes
+ * a network call.
+ */
+export const defaultLoggerAdapter: LoggerAdapter = {
+  log(level, msg, attrs) {
+    const payload: Record<string, unknown> = {
+      level,
+      msg,
+      timestamp: new Date().toISOString(),
+    };
+    if (attrs) {
+      // Spread last so explicit attrs win over our defaults except
+      // for `level` / `msg` / `timestamp` which we always want canonical.
+      for (const [k, v] of Object.entries(attrs)) {
+        if (k !== "level" && k !== "msg" && k !== "timestamp") {
+          payload[k] = v;
+        }
+      }
+    }
+    // Route by level so Cloudflare's log dashboard colorises correctly.
+    const fn =
+      level === "error"
+        ? console.error
+        : level === "warn"
+          ? console.warn
+          : level === "debug"
+            ? console.debug
+            : console.log;
+    try {
+      fn(JSON.stringify(payload));
+    } catch {
+      // Last-resort: fall back to plain string. Never crash the request
+      // because of a circular-ref or non-serialisable attribute.
+      fn(`${level} ${msg}`);
+    }
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Configurable global state
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Shared module state — pinned to globalThis via Symbol.for so multiple
+// inlined copies of this module (one per bundled entry file in dist/) all
+// converge on the SAME state. See the matching comment in
+// `observability.ts` for the rationale — `configureLogger()` from one
+// entry file's copy of this module would otherwise write to an
+// `activeAdapter` that `logger.error()` in another entry's copy never
+// reads, and direct-POST error-log capture silently no-ops.
+// ---------------------------------------------------------------------------
+
+interface LoggerState {
+  activeAdapter: LoggerAdapter;
+  minLevel: LogLevel;
+  attributeFloor: Record<string, unknown>;
+}
+
+const STATE_KEY = Symbol.for("@decocms/start/logger/state.v1");
+
+function getState(): LoggerState {
+  const g = globalThis as Record<symbol, unknown>;
+  if (!g[STATE_KEY]) {
+    g[STATE_KEY] = {
+      activeAdapter: defaultLoggerAdapter,
+      minLevel: "info" as LogLevel,
+      attributeFloor: {},
+    } satisfies LoggerState;
+  }
+  return g[STATE_KEY] as LoggerState;
+}
+
+/**
+ * Replace the active logger adapter.
+ * Call once at worker boot from `instrumentWorker()`.
+ */
+export function configureLogger(adapter: LoggerAdapter): void {
+  getState().activeAdapter = adapter;
+}
+
+/**
+ * Replace the per-record attribute floor — keys here will be added to
+ * every log line UNLESS the caller passes the same key in their `attrs`
+ * (caller wins). Set once at worker boot from `instrumentWorker()`.
+ *
+ * Used to stamp `deco.runtime.version`, `deco.apps.version`,
+ * `deployment.environment` on every log so HyperDX panels filtering on
+ * these dimensions keep working under Cloudflare-managed log export
+ * (which otherwise strips our resource attributes — only the JSON record
+ * body survives).
+ */
+export function setLoggerAttributeFloor(attrs: Record<string, unknown>): void {
+  getState().attributeFloor = { ...attrs };
+}
+
+/**
+ * Test-only: read the current attribute floor. Do not call from app code.
+ */
+export function _getLoggerAttributeFloorForTests(): Record<string, unknown> {
+  return { ...getState().attributeFloor };
+}
+
+/**
+ * Get the current active logger adapter (for tests / advanced wiring).
+ */
+export function getLoggerAdapter(): LoggerAdapter {
+  return getState().activeAdapter;
+}
+
+/**
+ * Set the minimum log level. Calls below this level are dropped before
+ * reaching any adapter — useful to silence `debug` in production.
+ *
+ * Defaults to `info`. Override per environment via `setLogLevel("debug")`
+ * or by reading an env var at boot.
+ */
+export function setLogLevel(level: LogLevel): void {
+  getState().minLevel = level;
+}
+
+export function getLogLevel(): LogLevel {
+  return getState().minLevel;
+}
+
+function shouldLog(level: LogLevel): boolean {
+  return LEVEL_RANK[level] >= LEVEL_RANK[getState().minLevel];
+}
+
+// ---------------------------------------------------------------------------
+// Public logger surface
+// ---------------------------------------------------------------------------
+
+/**
+ * Strict structured logger. Mirrors `@deco/deco/o11y`:
+ *  - first arg is a human-readable message string
+ *  - optional second arg is a flat attributes object
+ *
+ * Adapters decide the destination (stdout JSON, OTLP, both, …). The
+ * contract is intentionally narrow so structured output stays predictable
+ * across all sinks.
+ *
+ * @example
+ * ```ts
+ * logger.info("checkout started", { orderFormId, items });
+ * logger.warn("retrying vtex call", { attempt, host });
+ *
+ * // For Errors, serialize explicitly into the attrs payload:
+ * try { ... } catch (err) {
+ *   const e = serializeError(err);
+ *   logger.error(e.message, { error: e, stage: "checkout" });
+ * }
+ * ```
+ */
+export interface Logger {
+  debug(msg: string, attrs?: Record<string, unknown>): void;
+  info(msg: string, attrs?: Record<string, unknown>): void;
+  warn(msg: string, attrs?: Record<string, unknown>): void;
+  error(msg: string, attrs?: Record<string, unknown>): void;
+}
+
+/**
+ * Normalised, JSON-safe error shape suitable for inclusion in logger
+ * attributes. `serializeError` always returns this shape regardless of
+ * what was thrown.
+ */
+export interface SerializedError {
+  name: string;
+  message: string;
+  stack?: string;
+}
+
+/**
+ * Convert any thrown value into a flat, structured object that survives
+ * `JSON.stringify` and round-trips cleanly to OTel / Cloudflare Logs.
+ * Strict logger sites should call this from their catch blocks rather
+ * than passing the Error directly.
+ *
+ * @example
+ * ```ts
+ * try { ... } catch (err) {
+ *   const e = serializeError(err);
+ *   logger.error(e.message, { error: e });
+ * }
+ * ```
+ */
+export function serializeError(err: unknown): SerializedError {
+  if (err instanceof Error) {
+    return { name: err.name, message: err.message, stack: err.stack };
+  }
+  if (err && typeof err === "object") {
+    let body: string;
+    try {
+      body = JSON.stringify(err);
+    } catch {
+      body = String(err);
+    }
+    return { name: "NonError", message: body };
+  }
+  return { name: "NonError", message: String(err) };
+}
+
+function emit(level: LogLevel, msg: string, attrs?: Record<string, unknown>): void {
+  if (!shouldLog(level)) return;
+  // Pull trace context from the active span so every log line correlates
+  // to its trace in ClickStack/HyperDX. No active span → no-op; caller
+  // attrs always win so explicit `trace_id` overrides keep working.
+  const ctx = getActiveSpan()?.spanContext?.();
+  // Pull request.id from the AsyncLocalStorage-backed RequestContext so
+  // every log line in the request also carries the join key used by
+  // direct-POST metrics + tail-worker rows. Single read, no allocation
+  // when outside a request scope.
+  const requestId = RequestContext.requestId;
+  const requestAttrs: Record<string, unknown> | undefined =
+    ctx || requestId
+      ? {
+          ...(ctx ? { trace_id: ctx.traceId, span_id: ctx.spanId } : {}),
+          ...(requestId ? { "request.id": requestId } : {}),
+        }
+      : undefined;
+  // Merge order: floor → trace / request context → caller attrs. Caller
+  // wins; the request-scoped context only overrides floor keys (which
+  // never set `trace_id` / `request.id` anyway).
+  const s = getState();
+  const hasFloor = Object.keys(s.attributeFloor).length > 0;
+  let merged: Record<string, unknown> | undefined;
+  if (!hasFloor && !requestAttrs && !attrs) {
+    merged = undefined;
+  } else {
+    merged = {
+      ...(hasFloor ? s.attributeFloor : {}),
+      ...(requestAttrs ?? {}),
+      ...(attrs ?? {}),
+    };
+  }
+  try {
+    s.activeAdapter.log(level, msg, merged);
+  } catch {
+    // Adapter blew up. Fall back to default so we don't lose the line.
+    if (s.activeAdapter !== defaultLoggerAdapter) {
+      try {
+        defaultLoggerAdapter.log(level, msg, merged);
+      } catch {
+        /* swallow */
+      }
+    }
+  }
+}
+
+export const logger: Logger = {
+  debug: (msg, attrs) => emit("debug", msg, attrs),
+  info: (msg, attrs) => emit("info", msg, attrs),
+  warn: (msg, attrs) => emit("warn", msg, attrs),
+  error: (msg, attrs) => emit("error", msg, attrs),
+};
+
+export default logger;

package/src/sdk/mergeCacheControl.ts

@@ -0,0 +1,150 @@
+/**
+ * Cache-Control merge utility.
+ *
+ * When a page makes multiple backend calls with different cache lifetimes,
+ * the final page response must use the most restrictive (shortest) cache
+ * values. This utility merges multiple Cache-Control headers following
+ * the "most restrictive wins" strategy.
+ *
+ * @example
+ * ```ts
+ * import { mergeCacheControl } from "@decocms/start/sdk/mergeCacheControl";
+ *
+ * // Product loader returns 60s, mega menu returns 3600s
+ * const merged = mergeCacheControl([
+ *   "public, s-maxage=60, stale-while-revalidate=300",
+ *   "public, s-maxage=3600, stale-while-revalidate=86400",
+ * ]);
+ * // => "public, s-maxage=60, stale-while-revalidate=300"
+ * ```
+ */
+
+interface ParsedCacheControl {
+  isPublic: boolean;
+  isPrivate: boolean;
+  noCache: boolean;
+  noStore: boolean;
+  maxAge?: number;
+  sMaxAge?: number;
+  staleWhileRevalidate?: number;
+  staleIfError?: number;
+  mustRevalidate: boolean;
+}
+
+function safeParseInt(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const n = parseInt(value, 10);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function parse(header: string): ParsedCacheControl {
+  const directives = header.split(",").map((d) => d.trim().toLowerCase());
+
+  const result: ParsedCacheControl = {
+    isPublic: false,
+    isPrivate: false,
+    noCache: false,
+    noStore: false,
+    mustRevalidate: false,
+  };
+
+  for (const directive of directives) {
+    if (directive === "public") result.isPublic = true;
+    else if (directive === "private") result.isPrivate = true;
+    else if (directive === "no-cache") result.noCache = true;
+    else if (directive === "no-store") result.noStore = true;
+    else if (directive === "must-revalidate") result.mustRevalidate = true;
+    else if (directive.startsWith("max-age=")) {
+      result.maxAge = safeParseInt(directive.split("=")[1]);
+    } else if (directive.startsWith("s-maxage=")) {
+      result.sMaxAge = safeParseInt(directive.split("=")[1]);
+    } else if (directive.startsWith("stale-while-revalidate=")) {
+      result.staleWhileRevalidate = safeParseInt(directive.split("=")[1]);
+    } else if (directive.startsWith("stale-if-error=")) {
+      result.staleIfError = safeParseInt(directive.split("=")[1]);
+    }
+  }
+
+  return result;
+}
+
+function minDefined(...values: (number | undefined)[]): number | undefined {
+  const defined = values.filter((v): v is number => v != null);
+  return defined.length > 0 ? Math.min(...defined) : undefined;
+}
+
+/**
+ * Merge multiple Cache-Control headers using "most restrictive wins".
+ *
+ * - If any header is `private`, the result is `private`
+ * - If any header has `no-store`, the result has `no-store`
+ * - Numeric values (max-age, s-maxage, swr) use the minimum
+ */
+export function mergeCacheControl(headers: string[]): string {
+  if (headers.length === 0) return "public, s-maxage=0";
+  if (headers.length === 1) return headers[0];
+
+  const parsed = headers.map(parse);
+
+  const anyPrivate = parsed.some((p) => p.isPrivate);
+  const anyNoStore = parsed.some((p) => p.noStore);
+  const anyNoCache = parsed.some((p) => p.noCache);
+  const anyMustRevalidate = parsed.some((p) => p.mustRevalidate);
+
+  if (anyNoStore) {
+    return "private, no-cache, no-store, must-revalidate";
+  }
+
+  if (anyPrivate) {
+    const maxAge = minDefined(...parsed.map((p) => p.maxAge));
+    const parts = ["private"];
+    if (anyNoCache) parts.push("no-cache");
+    if (maxAge != null) parts.push(`max-age=${maxAge}`);
+    if (anyMustRevalidate) parts.push("must-revalidate");
+    return parts.join(", ");
+  }
+
+  const maxAge = minDefined(...parsed.map((p) => p.maxAge));
+  const sMaxAge = minDefined(...parsed.map((p) => p.sMaxAge));
+  const swr = minDefined(...parsed.map((p) => p.staleWhileRevalidate));
+  const sie = minDefined(...parsed.map((p) => p.staleIfError));
+
+  const parts: string[] = ["public"];
+  if (maxAge != null) parts.push(`max-age=${maxAge}`);
+  if (sMaxAge != null) parts.push(`s-maxage=${sMaxAge}`);
+  if (swr != null) parts.push(`stale-while-revalidate=${swr}`);
+  if (sie != null) parts.push(`stale-if-error=${sie}`);
+  if (anyMustRevalidate) parts.push("must-revalidate");
+
+  return parts.join(", ");
+}
+
+/**
+ * Accumulator for collecting cache control headers across loaders.
+ *
+ * Use in middleware to collect headers from each loader call and
+ * compute the final merged header at the end.
+ *
+ * @example
+ * ```ts
+ * const collector = createCacheControlCollector();
+ * collector.add("public, s-maxage=60");
+ * collector.add("public, s-maxage=3600");
+ * response.headers.set("Cache-Control", collector.result());
+ * // => "public, s-maxage=60"
+ * ```
+ */
+export function createCacheControlCollector() {
+  const headers: string[] = [];
+  return {
+    add(header: string) {
+      headers.push(header);
+    },
+    result(): string {
+      return mergeCacheControl(headers);
+    },
+    get count() {
+      return headers.length;
+    },
+  };
+}

package/src/sdk/normalizeUrls.ts

@@ -0,0 +1,91 @@
+/**
+ * URL normalization for CMS-resolved props.
+ *
+ * Strips registered production origins from absolute URLs, converting them to
+ * relative paths. This allows staging/preview deployments to work without
+ * every CMS-authored link sending users to the production domain.
+ *
+ * Only affects strings that START with a registered origin + "/" — image CDN
+ * URLs, API endpoints on different domains, and non-URL strings are untouched.
+ *
+ * @example
+ * ```ts
+ * // In site's setup.ts:
+ * import { registerProductionOrigins } from "@decocms/start/sdk/normalizeUrls";
+ * registerProductionOrigins([
+ *   "https://www.casaevideo.com.br",
+ *   "https://casaevideo.com.br",
+ * ]);
+ * ```
+ */
+
+let origins: string[] = [];
+
+/**
+ * Register production origins that should be stripped from CMS-resolved URLs.
+ * Call once in your site's setup.ts before any page loads.
+ */
+export function registerProductionOrigins(productionOrigins: string[]) {
+  origins = productionOrigins.map((o) => o.replace(/\/+$/, ""));
+}
+
+export function getProductionOrigins(): readonly string[] {
+  return origins;
+}
+
+function normalizeString(str: string): string {
+  for (const origin of origins) {
+    if (str.startsWith(origin + "/")) {
+      return str.slice(origin.length);
+    }
+    if (str === origin) {
+      return "/";
+    }
+  }
+  return str;
+}
+
+/**
+ * Deep-walk an object tree and rewrite any string value that starts with a
+ * registered production origin to a relative path. Returns the same reference
+ * if nothing was changed (structural sharing).
+ */
+export function normalizeUrlsInObject<T>(obj: T): T {
+  if (!origins.length) return obj;
+  return deepNormalize(obj) as T;
+}
+
+function deepNormalize(val: unknown): unknown {
+  if (val == null) return val;
+
+  if (typeof val === "string") {
+    return normalizeString(val);
+  }
+
+  if (Array.isArray(val)) {
+    let changed = false;
+    const result = val.map((item) => {
+      const normalized = deepNormalize(item);
+      if (normalized !== item) changed = true;
+      return normalized;
+    });
+    return changed ? result : val;
+  }
+
+  if (typeof val === "object") {
+    // Skip React elements, Dates, RegExps, and other non-plain objects
+    const proto = Object.getPrototypeOf(val);
+    if (proto !== Object.prototype && proto !== null) return val;
+
+    let changed = false;
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(val as Record<string, unknown>)) {
+      const normalized = deepNormalize(value);
+      result[key] = normalized;
+      if (normalized !== value) changed = true;
+    }
+    return changed ? result : val;
+  }
+
+  return val;
+}

package/src/sdk/observability.ts

@@ -0,0 +1,109 @@
+/**
+ * One-stop import for everything observability-related in `@decocms/start`.
+ *
+ * Consumers (sites, apps) should prefer importing from here so future
+ * re-organisations don't ripple through every site:
+ *
+ * ```ts
+ * import {
+ *   instrumentWorker,
+ *   logger,
+ *   setLogLevel,
+ *   withTracing,
+ *   recordRequestMetric,
+ *   recordCacheMetric,
+ *   MetricNames,
+ * } from "@decocms/start/sdk/observability";
+ * ```
+ *
+ * The granular modules (`@decocms/start/sdk/logger`, `.../otelAdapters`)
+ * remain importable for advanced use cases (custom adapters, tests, etc.)
+ * but the common path stays here.
+ *
+ * **5.0.0 surface change.** The OTLP exporters (`createOtelLoggerAdapter`,
+ * `createOtelMeterAdapter`), the flush registry (`flushOtelProviders`,
+ * `registerOtelFlushHandler`), and the URL-based sampler
+ * (`URLBasedSampler`, `decodeSamplingConfig`, `createUrlBasedHeadSampler`,
+ * `SamplingConfig`, `SamplingRule`) were removed. They will be reintroduced
+ * via `./otelAdapters/clickhouseCollector.ts` when the platform-side OTel
+ * collector ships. The `instrumentWorker` / `withTracing` / `logger` /
+ * `recordRequestMetric` / `recordCacheMetric` surface is unchanged — only
+ * the transport layer was stripped.
+ */
+
+// Composite helpers (for advanced multi-backend wiring — e.g. AE + future
+// ClickHouse-collector meter, or default-console + future-collector logger)
+export { createCompositeLogger, createCompositeMeter } from "./composite";
+// Logger surface
+export {
+  configureLogger,
+  defaultLoggerAdapter,
+  getLoggerAdapter,
+  getLogLevel,
+  type Logger,
+  type LoggerAdapter,
+  type LogLevel,
+  logger,
+  type SerializedError,
+  serializeError,
+  setLoggerAttributeFloor,
+  setLogLevel,
+} from "./logger";
+// Tracer / meter / request log primitives (re-exported from the middleware)
+export {
+  type CacheDecision,
+  type CacheLayer,
+  type CommerceMetricLabels,
+  configureMeter,
+  configureTracer,
+  getActiveSpan,
+  getMeter,
+  getTracer,
+  injectTraceContext,
+  logRequest,
+  type MeterAdapter,
+  MetricNames,
+  recordCacheMetric,
+  recordCommerceMetric,
+  recordLoaderError,
+  recordLoaderMetric,
+  recordRequestMetric,
+  type RequestMetricLabels,
+  type RequestStore,
+  type Span,
+  setObservabilitySpanStore,
+  setSpanAttribute,
+  statusClassFor,
+  type TracerAdapter,
+  withTracing,
+} from "../middleware/observability";
+// Worker-entry wrapper + adapter wiring
+export { instrumentWorker, type OtelOptions } from "./otel";
+// Direct-POST OTLP trace exporter (Phase 3 / D-12). Exported for sites
+// that need to wire a custom traces endpoint outside `instrumentWorker`,
+// and for the audit tooling that asserts framework spans are flowing.
+export {
+  createOtlpHttpTracerAdapter,
+  newSpanId,
+  newTraceId,
+  type OtlpHttpTracer,
+  type OtlpHttpTracerOptions,
+  parseTraceparent,
+  shouldSampleTrace,
+  type TraceContext,
+} from "./otelHttpTracer";
+// AE meter adapter + runtime env helpers (for tests / custom wiring)
+export {
+  type AnalyticsEngineDataset,
+  type AnalyticsEngineMeterAdapterOptions,
+  createAnalyticsEngineMeterAdapter,
+  getRuntimeEnv,
+  setRuntimeEnv,
+} from "./otelAdapters";
+// ClickHouse collector adapter — stub today, real exporter when the
+// collector lands. Re-exported from here so site code can import the
+// future-target symbol via the canonical observability barrel.
+export {
+  type ClickhouseCollectorOptions,
+  createClickhouseCollectorAdapter,
+} from "./otelAdapters/clickhouseCollector";