@decocms/blocks 7.0.0

package/src/matchers/override.test.ts

@@ -0,0 +1,205 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { setBlocks } from "../cms/loader";
+import type { MatcherContext } from "../cms/resolve";
+import { evaluateMatcher, registerMatcher } from "../cms/resolve";
+import { DECO_MATCHERS_OVERRIDE_PARAM, getMatchersOverride } from "./override";
+
+const TEST_MATCHER_KEY = "test/matchers/flag.ts";
+// Block names with spaces are only addressable via query string — the header
+// format splits pairs on spaces (same limitation as the Deno runtime).
+const SAVED_BLOCK = "Segmento Mobile";
+const SAVED_BLOCK_NO_SPACE = "PromoAtiva";
+
+const matcherFn = vi.fn(
+  (rule: Record<string, unknown>) => (rule.result as boolean | undefined) ?? false,
+);
+
+function ctxWithHeader(value: string): MatcherContext {
+  return {
+    url: "https://example.com/",
+    request: new Request("https://example.com/", {
+      headers: { [DECO_MATCHERS_OVERRIDE_PARAM]: value },
+    }),
+  };
+}
+
+function ctxWithQS(search: string): MatcherContext {
+  const url = `https://example.com/?${search}`;
+  return { url, request: new Request(url) };
+}
+
+beforeEach(() => {
+  matcherFn.mockClear();
+  registerMatcher(TEST_MATCHER_KEY, matcherFn);
+  setBlocks({
+    [SAVED_BLOCK]: { __resolveType: TEST_MATCHER_KEY, result: true },
+    [SAVED_BLOCK_NO_SPACE]: { __resolveType: TEST_MATCHER_KEY, result: true },
+  });
+});
+
+describe("getMatchersOverride", () => {
+  it("parses space-separated pairs from the header", () => {
+    const overrides = getMatchersOverride(ctxWithHeader("a=1 b=0"));
+    expect(overrides).toEqual({ a: true, b: false });
+  });
+
+  it("parses repeated query string params, including names with spaces", () => {
+    const overrides = getMatchersOverride(
+      ctxWithQS(
+        `${DECO_MATCHERS_OVERRIDE_PARAM}=Segmento%20Mobile%3D1&${DECO_MATCHERS_OVERRIDE_PARAM}=b%3D0`,
+      ),
+    );
+    expect(overrides).toEqual({ "Segmento Mobile": true, b: false });
+  });
+
+  it("prefers the header over the query string", () => {
+    const url = `https://example.com/?${DECO_MATCHERS_OVERRIDE_PARAM}=a%3D0`;
+    const ctx: MatcherContext = {
+      url,
+      request: new Request(url, {
+        headers: { [DECO_MATCHERS_OVERRIDE_PARAM]: "a=1" },
+      }),
+    };
+    expect(getMatchersOverride(ctx)).toEqual({ a: true });
+  });
+
+  it("falls back to the headers record when no Request is present", () => {
+    const overrides = getMatchersOverride({
+      headers: { [DECO_MATCHERS_OVERRIDE_PARAM]: "a=1" },
+    });
+    expect(overrides).toEqual({ a: true });
+  });
+
+  it("returns an empty object when no override is present", () => {
+    expect(getMatchersOverride({ url: "https://example.com/" })).toEqual({});
+    expect(getMatchersOverride({})).toEqual({});
+  });
+});
+
+describe("evaluateMatcher with overrides", () => {
+  it("forces a saved matcher block to false via header without running it", () => {
+    const result = evaluateMatcher(
+      { __resolveType: SAVED_BLOCK_NO_SPACE },
+      ctxWithHeader(`${SAVED_BLOCK_NO_SPACE}=0`),
+    );
+    expect(result).toBe(false);
+    expect(matcherFn).not.toHaveBeenCalled();
+  });
+
+  it("forces a spaced-name block to false via query string", () => {
+    const result = evaluateMatcher(
+      { __resolveType: SAVED_BLOCK },
+      ctxWithQS(`${DECO_MATCHERS_OVERRIDE_PARAM}=${encodeURIComponent(`${SAVED_BLOCK}=0`)}`),
+    );
+    expect(result).toBe(false);
+    expect(matcherFn).not.toHaveBeenCalled();
+  });
+
+  it("forces a saved matcher block to true without running it", () => {
+    setBlocks({
+      [SAVED_BLOCK]: { __resolveType: TEST_MATCHER_KEY, result: false },
+    });
+    const result = evaluateMatcher(
+      { __resolveType: SAVED_BLOCK },
+      ctxWithQS(`${DECO_MATCHERS_OVERRIDE_PARAM}=${encodeURIComponent(`${SAVED_BLOCK}=1`)}`),
+    );
+    expect(result).toBe(true);
+    expect(matcherFn).not.toHaveBeenCalled();
+  });
+
+  it("runs the matcher normally when no override targets it", () => {
+    const result = evaluateMatcher(
+      { __resolveType: SAVED_BLOCK },
+      ctxWithHeader("Outro Segmento=0"),
+    );
+    expect(result).toBe(true);
+    expect(matcherFn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not affect inline matchers keyed by raw type", () => {
+    const result = evaluateMatcher(
+      { __resolveType: TEST_MATCHER_KEY, result: true },
+      ctxWithHeader(`${TEST_MATCHER_KEY}=0`),
+    );
+    expect(result).toBe(true);
+    expect(matcherFn).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("evaluateMatcher with inline rule path overrides", () => {
+  const PAGE_ID = "pages-home-c4bcbfb771e9";
+
+  function setPageBlocks() {
+    const page = {
+      __resolveType: "website/pages/Page.tsx",
+      sections: [
+        { __resolveType: "site/sections/Header.tsx" },
+        {
+          __resolveType: "website/flags/multivariate/section.ts",
+          variants: [
+            {
+              rule: { __resolveType: TEST_MATCHER_KEY, result: true },
+              value: { __resolveType: "site/sections/A.tsx" },
+            },
+            {
+              rule: { __resolveType: TEST_MATCHER_KEY, result: false },
+              value: { __resolveType: "site/sections/B.tsx" },
+            },
+          ],
+        },
+      ],
+    };
+    setBlocks({ [PAGE_ID]: page });
+    return page;
+  }
+
+  it("forces an inline rule by <blockId>@<prop.path> without running it", () => {
+    const page = setPageBlocks();
+    const rule = page.sections[1].variants![0].rule as Record<string, unknown>;
+    const result = evaluateMatcher(
+      rule,
+      ctxWithQS(
+        `${DECO_MATCHERS_OVERRIDE_PARAM}=${encodeURIComponent(
+          `${PAGE_ID}@sections.1.variants.0.rule=0`,
+        )}`,
+      ),
+    );
+    expect(result).toBe(false);
+    expect(matcherFn).not.toHaveBeenCalled();
+  });
+
+  it("forces an inline rule to true via header path key", () => {
+    const page = setPageBlocks();
+    const rule = page.sections[1].variants![1].rule as Record<string, unknown>;
+    const result = evaluateMatcher(rule, ctxWithHeader(`${PAGE_ID}@sections.1.variants.1.rule=1`));
+    expect(result).toBe(true);
+    expect(matcherFn).not.toHaveBeenCalled();
+  });
+
+  it("evaluates normally when the path key targets a different position", () => {
+    const page = setPageBlocks();
+    const rule = page.sections[1].variants![0].rule as Record<string, unknown>;
+    const result = evaluateMatcher(rule, ctxWithHeader(`${PAGE_ID}@sections.1.variants.1.rule=0`));
+    expect(result).toBe(true);
+    expect(matcherFn).toHaveBeenCalledTimes(1);
+  });
+
+  it("rebuilds the index when blocks are swapped", () => {
+    const first = setPageBlocks();
+    const overrideCtx = () => ctxWithHeader(`${PAGE_ID}@sections.1.variants.0.rule=0`);
+    expect(
+      evaluateMatcher(
+        first.sections[1].variants![0].rule as Record<string, unknown>,
+        overrideCtx(),
+      ),
+    ).toBe(false);
+
+    const second = setPageBlocks();
+    expect(
+      evaluateMatcher(
+        second.sections[1].variants![0].rule as Record<string, unknown>,
+        overrideCtx(),
+      ),
+    ).toBe(false);
+  });
+});

package/src/matchers/override.ts

@@ -0,0 +1,136 @@
+/**
+ * Per-request matcher override — port of the Deno runtime's
+ * `x-deco-matchers-override` flag (deco/blocks/matcher.ts).
+ *
+ * Forces matcher results without running them, keyed by the Deno-style
+ * uniqueId derived from the matcher's position in the decofile:
+ *
+ * - Saved matcher block referenced by name → the block name
+ *   (`Segmento Mobile=1`), mirroring Deno's resolve chain stopping at the
+ *   first resolvable.
+ * - Inline matcher → `<blockId>@<prop.path.to.rule>`
+ *   (`pages-home-c4bcbfb771e9@sections.2.variants.0.rule=0`).
+ *
+ * Carried by:
+ * - Header: `x-deco-matchers-override: SegmentA=1 SegmentB=0`
+ *   (space-separated pairs; `=1` forces true, anything else forces false)
+ * - Query string: `?x-deco-matchers-override=Segment%20A%3D1` (repeatable)
+ *
+ * Header takes precedence over query string when both are present.
+ */
+
+import type { MatcherContext } from "../cms/resolve";
+
+export const DECO_MATCHERS_OVERRIDE_PARAM = "x-deco-matchers-override";
+
+/** Splits on the FIRST "=" so block names containing "=" still work. */
+function addPair(values: Record<string, boolean>, pair: string): void {
+  const idx = pair.indexOf("=");
+  if (idx <= 0) return;
+  values[pair.slice(0, idx)] = pair.slice(idx + 1) === "1";
+}
+
+function parseFromHeaders(ctx: MatcherContext): Record<string, boolean> | undefined {
+  const val =
+    ctx.request?.headers.get(DECO_MATCHERS_OVERRIDE_PARAM) ??
+    ctx.headers?.[DECO_MATCHERS_OVERRIDE_PARAM];
+  if (!val) return undefined;
+  const values: Record<string, boolean> = {};
+  for (const pair of val.split(" ")) addPair(values, pair);
+  return values;
+}
+
+function parseFromQS(ctx: MatcherContext): Record<string, boolean> | undefined {
+  if (!ctx.url) return undefined;
+  let url: URL;
+  try {
+    url = new URL(ctx.url);
+  } catch {
+    return undefined;
+  }
+  if (!url.searchParams.has(DECO_MATCHERS_OVERRIDE_PARAM)) return undefined;
+  const values: Record<string, boolean> = {};
+  for (const pair of url.searchParams.getAll(DECO_MATCHERS_OVERRIDE_PARAM)) {
+    addPair(values, pair);
+  }
+  return values;
+}
+
+const EMPTY: Record<string, boolean> = {};
+
+// Memoized per Request so a page with many matchers parses once.
+const overridesByRequest = new WeakMap<Request, Record<string, boolean>>();
+
+/**
+ * Parse the matcher overrides for this request (header first, then query
+ * string). Returns an empty object when no override is present.
+ */
+export function getMatchersOverride(ctx: MatcherContext): Record<string, boolean> {
+  const request = ctx.request;
+  if (request) {
+    const cached = overridesByRequest.get(request);
+    if (cached) return cached;
+  }
+  const values = parseFromHeaders(ctx) ?? parseFromQS(ctx) ?? EMPTY;
+  if (request) overridesByRequest.set(request, values);
+  return values;
+}
+
+export function hasMatchersOverride(ctx: MatcherContext): boolean {
+  const overrides = getMatchersOverride(ctx);
+  for (const _ in overrides) return true;
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Rule uniqueId index — Deno resolveChain semantics
+// ---------------------------------------------------------------------------
+
+type RuleIdIndex = WeakMap<object, string>;
+
+// Keyed by the blocks map identity, so the index is rebuilt on decofile
+// hot-reload / KV swap (setBlocks replaces the map) and admin preview
+// (withBlocksOverride returns a fresh merged map).
+const indexByBlocks = new WeakMap<Record<string, unknown>, RuleIdIndex>();
+
+function walkBlock(node: unknown, blockId: string, path: string, index: RuleIdIndex): void {
+  if (!node || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      walkBlock(node[i], blockId, path ? `${path}.${i}` : `${i}`, index);
+    }
+    return;
+  }
+  const obj = node as Record<string, unknown>;
+  if (path && typeof obj.__resolveType === "string") {
+    index.set(obj, `${blockId}@${path}`);
+  }
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === "__resolveType") continue;
+    walkBlock(value, blockId, path ? `${path}.${key}` : key, index);
+  }
+}
+
+/**
+ * Resolve the Deno-style uniqueId (`<blockId>@<prop.path>`) for an inline
+ * rule object by its identity in the blocks map. Returns undefined for
+ * objects created during resolution (spreads/merges) — those are addressed
+ * by their saved-block name instead.
+ *
+ * The index is built lazily (only when a request carries an override) and
+ * cached per blocks map, so override-free traffic pays nothing.
+ */
+export function getRuleOverrideId(
+  blocks: Record<string, unknown>,
+  rule: object,
+): string | undefined {
+  let index = indexByBlocks.get(blocks);
+  if (!index) {
+    index = new WeakMap();
+    for (const [blockId, block] of Object.entries(blocks)) {
+      walkBlock(block, blockId, "", index);
+    }
+    indexByBlocks.set(blocks, index);
+  }
+  return index.get(rule);
+}

package/src/matchers/posthog.ts

@@ -0,0 +1,154 @@
+/**
+ * PostHog feature flag matcher bridge.
+ *
+ * Bridges deco's CMS matcher interface (`evaluateMatcher`) to PostHog's
+ * feature flag system for experiment-grade A/B testing with sticky sessions.
+ *
+ * This module is designed to be used with `registerMatcher()` from the CMS.
+ * PostHog itself is NOT a dependency of `@decocms/start` — the storefront
+ * provides the PostHog client via `configurePostHogMatcher()`.
+ *
+ * @example
+ * ```ts
+ * // In your storefront setup.ts
+ * import { registerMatcher } from "@decocms/start/cms";
+ * import { createPostHogMatcher, configurePostHogMatcher } from "@decocms/start/matchers/posthog";
+ * import posthog from "posthog-js";
+ *
+ * configurePostHogMatcher({
+ *   isFeatureEnabled: (key) => posthog.isFeatureEnabled(key) ?? false,
+ *   getFeatureFlagVariant: (key) => posthog.getFeatureFlag(key),
+ * });
+ *
+ * registerMatcher("posthog/matchers/featureFlag.ts", createPostHogMatcher());
+ * ```
+ */
+
+import type { MatcherContext } from "../cms/resolve";
+
+export interface PostHogAdapter {
+  /**
+   * Evaluate a boolean feature flag.
+   * Should return `true` if the flag is enabled for the current user.
+   */
+  isFeatureEnabled: (flagKey: string) => boolean;
+  /**
+   * Get the variant key for a multivariate feature flag.
+   * Returns the variant string or `undefined`/`false` if not matched.
+   */
+  getFeatureFlagVariant?: (flagKey: string) => string | boolean | undefined;
+}
+
+let adapter: PostHogAdapter | null = null;
+
+/**
+ * Provide the PostHog client adapter. Must be called before
+ * any PostHog matchers are evaluated.
+ */
+export function configurePostHogMatcher(ph: PostHogAdapter) {
+  adapter = ph;
+}
+
+/**
+ * Creates a matcher function compatible with `registerMatcher()`.
+ *
+ * CMS rule shape (in the decofile JSON):
+ * ```json
+ * {
+ *   "__resolveType": "posthog/matchers/featureFlag.ts",
+ *   "flagKey": "my-experiment",
+ *   "variant": "treatment"
+ * }
+ * ```
+ *
+ * - If only `flagKey` is provided, matches when the flag is enabled (boolean).
+ * - If `variant` is also provided, matches when the flag's variant equals it.
+ */
+export function createPostHogMatcher() {
+  return (rule: Record<string, unknown>, _ctx: MatcherContext): boolean => {
+    if (!adapter) {
+      console.warn(
+        "[PostHog Matcher] No adapter configured. Call configurePostHogMatcher() first.",
+      );
+      return false;
+    }
+
+    const flagKey = rule.flagKey as string | undefined;
+    if (!flagKey) {
+      console.warn("[PostHog Matcher] Missing `flagKey` in matcher rule.");
+      return false;
+    }
+
+    const expectedVariant = rule.variant as string | undefined;
+
+    if (expectedVariant && adapter.getFeatureFlagVariant) {
+      const actual = adapter.getFeatureFlagVariant(flagKey);
+      return actual === expectedVariant;
+    }
+
+    return adapter.isFeatureEnabled(flagKey);
+  };
+}
+
+/**
+ * Server-side PostHog evaluation for SSR.
+ *
+ * Uses the PostHog Node SDK to evaluate flags server-side,
+ * ensuring the first render has the correct variant without a flash.
+ *
+ * @example
+ * ```ts
+ * import { PostHog } from "posthog-node";
+ * import { configurePostHogMatcher, createServerPostHogAdapter } from "@decocms/start/matchers/posthog";
+ *
+ * const phServer = new PostHog(process.env.POSTHOG_API_KEY);
+ *
+ * // In your middleware, per-request:
+ * const adapter = createServerPostHogAdapter(phServer, distinctId);
+ * configurePostHogMatcher(adapter);
+ * ```
+ */
+export function createServerPostHogAdapter(
+  client: {
+    isFeatureEnabled: (key: string, distinctId: string) => Promise<boolean> | boolean;
+    getFeatureFlag: (
+      key: string,
+      distinctId: string,
+    ) => Promise<string | boolean | undefined> | string | boolean | undefined;
+  },
+  distinctId: string,
+): PostHogAdapter {
+  const flagCache = new Map<string, boolean>();
+  const variantCache = new Map<string, string | boolean | undefined>();
+
+  return {
+    isFeatureEnabled(key: string): boolean {
+      if (flagCache.has(key)) return flagCache.get(key)!;
+
+      // Synchronous path — pre-warm the cache in middleware before resolution
+      const result = client.isFeatureEnabled(key, distinctId);
+      if (result instanceof Promise) {
+        console.warn(
+          "[PostHog] Async flag evaluation used synchronously. Pre-warm flags in middleware.",
+        );
+        return false;
+      }
+      flagCache.set(key, result);
+      return result;
+    },
+
+    getFeatureFlagVariant(key: string): string | boolean | undefined {
+      if (variantCache.has(key)) return variantCache.get(key);
+
+      const result = client.getFeatureFlag(key, distinctId);
+      if (result instanceof Promise) {
+        console.warn(
+          "[PostHog] Async variant evaluation used synchronously. Pre-warm flags in middleware.",
+        );
+        return undefined;
+      }
+      variantCache.set(key, result);
+      return result;
+    },
+  };
+}

package/src/middleware/decoState.ts

@@ -0,0 +1,55 @@
+/**
+ * Per-request Deco state that the middleware pipeline builds up
+ * and passes through the request lifecycle.
+ */
+import { createServerTimings, type ServerTimings } from "../sdk/serverTimings";
+import type { Flag } from "../types/index";
+
+export interface DecoState {
+  /** Site name / identifier. */
+  site: string;
+  /** Per-request Server-Timing tracker. */
+  timings: ServerTimings;
+  /** Active feature flags for this request. */
+  flags: Flag[];
+  /** Whether the request is from a deco admin origin. */
+  isAdmin: boolean;
+  /** Whether debug mode is enabled (via `?__d=true` or admin). */
+  debug: boolean;
+  /** Start time of the request (ms). */
+  startedAt: number;
+}
+
+export function buildDecoState(request: Request, site?: string): DecoState {
+  const url = new URL(request.url);
+  const origin = request.headers.get("origin") || request.headers.get("referer") || "";
+
+  const ADMIN_ORIGINS = [
+    "https://admin.deco.cx",
+    "https://v0-admin.deco.cx",
+    "https://play.deco.cx",
+    "https://admin-cx.deco.page",
+    "https://deco.chat",
+    "https://admin.decocms.com",
+    "https://decocms.com",
+  ];
+
+  const isAdmin =
+    origin.includes("localhost") ||
+    origin.includes("127.0.0.1") ||
+    ADMIN_ORIGINS.some((d) => origin.startsWith(d));
+
+  const debug = url.searchParams.has("__d") || isAdmin;
+
+  return {
+    site:
+      site ||
+      (typeof globalThis.process !== "undefined" ? globalThis.process.env?.DECO_SITE : undefined) ||
+      "storefront",
+    timings: createServerTimings(),
+    flags: [],
+    isAdmin,
+    debug,
+    startedAt: performance.now(),
+  };
+}

package/src/middleware/healthMetrics.ts

@@ -0,0 +1,133 @@
+/**
+ * Health metrics collection for request tracking and diagnostics.
+ *
+ * Provides atomic counters for requests (total, inflight, errors)
+ * and a health endpoint with cache stats and uptime.
+ *
+ * @example
+ * ```ts
+ * import { trackRequest, getHealthMetrics, handleHealthCheck } from "@decocms/start/middleware/healthMetrics";
+ *
+ * // In middleware:
+ * trackRequest.start();
+ * const response = await next();
+ * trackRequest.end(response.status);
+ * ```
+ */
+
+import { getLoaderCacheStats } from "../sdk/cachedLoader";
+
+// ---------------------------------------------------------------------------
+// Counters
+// ---------------------------------------------------------------------------
+
+let totalRequests = 0;
+let inflightRequests = 0;
+let totalErrors = 0;
+const startedAt = Date.now();
+
+const statusCounts: Record<string, number> = {};
+
+export const trackRequest = {
+  start() {
+    totalRequests++;
+    inflightRequests++;
+  },
+
+  end(status: number) {
+    inflightRequests--;
+    const bucket = `${Math.floor(status / 100)}xx`;
+    statusCounts[bucket] = (statusCounts[bucket] || 0) + 1;
+    if (status >= 500) totalErrors++;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Metrics access
+// ---------------------------------------------------------------------------
+
+export interface HealthMetrics {
+  uptime: number;
+  uptimeHuman: string;
+  requests: {
+    total: number;
+    inflight: number;
+    errors: number;
+    statusCodes: Record<string, number>;
+  };
+  cache: {
+    entries: number;
+    inflight: number;
+    estimatedBytes: number;
+    maxBytes: number;
+  };
+  memory?: {
+    rss: number;
+    heapUsed: number;
+    heapTotal: number;
+  };
+}
+
+function formatUptime(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = seconds % 60;
+  return `${h}h ${m}m ${s}s`;
+}
+
+export function getHealthMetrics(): HealthMetrics {
+  const uptime = Date.now() - startedAt;
+  const cacheStats = getLoaderCacheStats();
+
+  const metrics: HealthMetrics = {
+    uptime,
+    uptimeHuman: formatUptime(uptime),
+    requests: {
+      total: totalRequests,
+      inflight: inflightRequests,
+      errors: totalErrors,
+      statusCodes: { ...statusCounts },
+    },
+    cache: cacheStats,
+  };
+
+  // Memory info is only available in Node.js / Deno environments
+  if (typeof globalThis.process !== "undefined" && globalThis.process.memoryUsage) {
+    try {
+      const mem = globalThis.process.memoryUsage();
+      metrics.memory = {
+        rss: mem.rss,
+        heapUsed: mem.heapUsed,
+        heapTotal: mem.heapTotal,
+      };
+    } catch {
+      // not available in this runtime
+    }
+  }
+
+  return metrics;
+}
+
+// ---------------------------------------------------------------------------
+// Health check handler
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle `/deco/_health` requests with detailed metrics.
+ * Returns null for non-matching requests.
+ */
+export function handleHealthCheck(request: Request): Response | null {
+  const url = new URL(request.url);
+  if (url.pathname !== "/deco/_health") return null;
+
+  const metrics = getHealthMetrics();
+
+  return new Response(JSON.stringify(metrics, null, 2), {
+    status: 200,
+    headers: {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store",
+    },
+  });
+}