@decocms/blocks 7.62.5 → 7.63.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.62.5",
+  "version": "7.63.1",
   "type": "module",
   "engines": {
     "node": ">=24"

package/src/middleware/observability.ts

@@ -282,6 +282,9 @@ export const MetricNames = {
   // Labels on this counter use short keys (status/profile/layer/provider) —
   // the metric name already provides the deco.cache.* namespace.
   CACHE_REQUESTS: "deco.cache.requests",
+  // Size in bytes of the values moving through a cache, dimensioned by `op`.
+  // Bucketed in decades of bytes — see CACHE_SIZE_BUCKET_BOUNDARIES_BYTES.
+  CACHE_SIZE: "deco.cache.size",
   RESOLVE_DURATION: "deco.cms.resolve.duration",
   LOADER_DURATION: "deco.loader.duration",
   LOADER_ERRORS: "deco.loader.errors",
@@ -323,6 +326,29 @@ export const DURATION_BUCKET_BOUNDARIES_SECONDS: readonly number[] = [
   10,
 ];
 
+/**
+ * Bucket boundaries, in BYTES, for {@link MetricNames.CACHE_SIZE}.
+ *
+ * Decades, matching the `http.server.response.body.size` histogram already
+ * flowing through the same ingestor — a size distribution is read in orders of
+ * magnitude, not in linear steps, and reusing the house convention means the
+ * two byte histograms are directly comparable.
+ *
+ * The range is bounded on both ends by the loader cache itself: entries are
+ * floored at `MIN_ENTRY_BYTES` (512 B) and the store is capped at 32 MB, which
+ * is why the last bound is the cap rather than another decade — the top bucket
+ * then reads as "single entry at/near the whole cache budget", which is the
+ * thing worth alerting on.
+ */
+export const CACHE_SIZE_BUCKET_BOUNDARIES_BYTES: readonly number[] = [
+  1_000,
+  10_000,
+  100_000,
+  1_000_000,
+  10_000_000,
+  33_554_432,
+];
+
 /**
  * Per-metric metadata emitted in the OTLP payload's `description` and
  * `unit` fields. Durations are normalized to **seconds at the source** (OTel
@@ -339,7 +365,11 @@ export const DURATION_BUCKET_BOUNDARIES_SECONDS: readonly number[] = [
  */
 export const METRIC_METADATA: Record<
   string,
-  { description: string; unit: string; boundaries?: readonly number[] }
+  {
+    description: string;
+    unit: string;
+    boundaries?: readonly number[];
+  }
 > = {
   [MetricNames.HTTP_SERVER_REQUEST_DURATION]: {
     description: "Duration of HTTP server requests handled at the Worker entry point.",
@@ -355,6 +385,11 @@ export const METRIC_METADATA: Record<
     description: "Cache lookups, dimensioned by status (hit/stale/miss/bypass).",
     unit: "{request}",
   },
+  [MetricNames.CACHE_SIZE]: {
+    description: "Size in bytes of values written to / read from a cache, dimensioned by op.",
+    unit: "By",
+    boundaries: CACHE_SIZE_BUCKET_BOUNDARIES_BYTES,
+  },
   [MetricNames.RESOLVE_DURATION]: {
     description: "Duration of `deco.cms.resolvePage` — CMS route to block tree resolution.",
     unit: "s",
@@ -590,6 +625,22 @@ export function recordCacheMetric(
   m.counterInc(MetricNames.CACHE_REQUESTS, 1, labels);
 }
 
+/**
+ * Record the size of a value moving through a cache, in BYTES — not seconds,
+ * so unlike the duration helpers this one does not divide.
+ *
+ * `profile` deliberately reuses the label key {@link recordCacheMetric} already
+ * uses for the `cachedLoader` layer (there it carries the loader name), so
+ * `deco.cache.size` joins `deco.cache.requests{layer="cachedLoader"}` on
+ * `profile` with no renaming in the query.
+ *
+ * Only `op: "set"` is emitted today; the label exists so a future read-side
+ * measurement lands on the same series without a breaking dashboard change.
+ */
+export function recordCacheSizeMetric(bytes: number, profile: string, op: "set" | "get" = "set") {
+  getState().meter?.histogramRecord?.(MetricNames.CACHE_SIZE, bytes, { op, profile });
+}
+
 /**
  * Labels for the outbound commerce sample recorded on
  * `http.client.request.duration`. Owned by the framework so apps-start (and

package/src/sdk/cachedLoader.ts

@@ -13,6 +13,7 @@
 
 import {
   recordCacheMetric,
+  recordCacheSizeMetric,
   recordLoaderError,
   recordLoaderMetric,
   withTracing,
@@ -171,7 +172,13 @@ function estimateBytes(value: unknown): number {
   }
 }
 
-function setCacheEntry<T>(key: string, entry: CacheEntry<T>) {
+/**
+ * The single write path into the cache — both the cold-miss and the SWR
+ * background-refresh callers route through here, which is why the size metric
+ * is emitted at this chokepoint rather than at each call site.
+ */
+function setCacheEntry<T>(key: string, entry: CacheEntry<T>, name: string) {
+  recordCacheSizeMetric(entry.estimatedBytes, name);
   const prev = cache.get(key);
   if (prev) cacheBytes -= prev.estimatedBytes;
   cacheBytes += entry.estimatedBytes;
@@ -317,12 +324,16 @@ export function createCachedLoader<TProps, TResult>(
             // Skip the write if a purge cleared the cache mid-refresh — otherwise
             // we'd re-insert pre-purge data the purge was meant to drop.
             if (gen !== cacheGeneration) return;
-            setCacheEntry(cacheKey, {
-              value: result,
-              createdAt: Date.now(),
-              refreshing: false,
-              estimatedBytes: estimateBytes(result),
-            });
+            setCacheEntry(
+              cacheKey,
+              {
+                value: result,
+                createdAt: Date.now(),
+                refreshing: false,
+                estimatedBytes: estimateBytes(result),
+              },
+              name,
+            );
             evictIfNeeded();
           })
           .catch(() => {
@@ -362,12 +373,16 @@ export function createCachedLoader<TProps, TResult>(
         // Skip caching if a purge landed while this loader was in flight — still
         // return the fresh value to the caller, just don't persist a raced entry.
         if (gen === cacheGeneration) {
-          setCacheEntry(cacheKey, {
-            value: result,
-            createdAt: Date.now(),
-            refreshing: false,
-            estimatedBytes: estimateBytes(result),
-          });
+          setCacheEntry(
+            cacheKey,
+            {
+              value: result,
+              createdAt: Date.now(),
+              refreshing: false,
+              estimatedBytes: estimateBytes(result),
+            },
+            name,
+          );
           evictIfNeeded();
         }
         return result;

package/src/sdk/cachedLoaderSizeMetric.test.ts

@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { configureMeter, MetricNames } from "../middleware/observability";
+import { clearLoaderCache, createCachedLoader } from "./cachedLoader";
+
+type Sample = { name: string; value: number; labels?: Record<string, unknown> };
+
+function fakeMeter(samples: Sample[]) {
+  return {
+    counterInc: () => {},
+    gaugeSet: () => {},
+    histogramRecord: (name: string, value: number, labels?: Record<string, unknown>) => {
+      samples.push({ name, value, labels });
+    },
+  };
+}
+
+const sizeSamples = (samples: Sample[]) => samples.filter((s) => s.name === MetricNames.CACHE_SIZE);
+
+describe("deco.cache.size — emitted on every loader cache write", () => {
+  let samples: Sample[];
+
+  beforeEach(() => {
+    clearLoaderCache();
+    samples = [];
+    configureMeter(fakeMeter(samples));
+  });
+
+  afterEach(() => {
+    clearLoaderCache();
+    configureMeter({ counterInc: () => {} }); // drop the recorder
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("records one sample on the cold-miss write, labelled op=set + the loader name", async () => {
+    const cached = createCachedLoader("t/size-miss", async (p: { id: number }) => ({ v: p.id }), {
+      policy: "stale-while-revalidate",
+      maxAge: 60_000,
+    });
+
+    await cached({ id: 1 });
+
+    const sizes = sizeSamples(samples);
+    expect(sizes).toHaveLength(1);
+    expect(sizes[0].labels).toEqual({ op: "set", profile: "t/size-miss" });
+    // Bytes, not seconds — and floored at MIN_ENTRY_BYTES for a tiny payload.
+    expect(sizes[0].value).toBe(512);
+  });
+
+  it("does not re-record on a HIT — only writes are measured", async () => {
+    const cached = createCachedLoader("t/size-hit", async (p: { id: number }) => ({ v: p.id }), {
+      policy: "stale-while-revalidate",
+      maxAge: 60_000,
+    });
+
+    await cached({ id: 1 }); // MISS -> write
+    await cached({ id: 1 }); // HIT  -> no write
+
+    expect(sizeSamples(samples)).toHaveLength(1);
+  });
+
+  it("records the SWR background-refresh write too, not just the cold miss", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-05-18T16:00:00.000Z"));
+
+    const cached = createCachedLoader("t/size-swr", async (p: { id: number }) => ({ v: p.id }), {
+      policy: "stale-while-revalidate",
+      maxAge: 1_000,
+    });
+
+    await cached({ id: 1 }); // MISS -> write #1
+    vi.setSystemTime(new Date("2026-05-18T16:00:05.000Z")); // now stale
+    await cached({ id: 1 }); // STALE-HIT -> background refresh
+    await vi.runAllTimersAsync(); // let the refresh settle
+
+    const sizes = sizeSamples(samples);
+    expect(sizes).toHaveLength(2); // write #2 came from the refresh
+    expect(sizes.every((s) => s.labels?.op === "set")).toBe(true);
+    expect(sizes.every((s) => s.labels?.profile === "t/size-swr")).toBe(true);
+  });
+
+  it("scales with the payload so a fat loader is distinguishable from a thin one", async () => {
+    const big = { blob: "x".repeat(50_000) };
+    const cached = createCachedLoader("t/size-big", async () => big, {
+      policy: "stale-while-revalidate",
+      maxAge: 60_000,
+    });
+
+    await cached({});
+
+    expect(sizeSamples(samples)[0].value).toBeGreaterThan(50_000);
+  });
+});

package/src/sdk/observability.ts

@@ -64,6 +64,7 @@ export {
   type MeterAdapter,
   MetricNames,
   recordCacheMetric,
+  recordCacheSizeMetric,
   recordCommerceMetric,
   recordLoaderError,
   recordLoaderMetric,

package/src/sdk/otelHttpMeter.test.ts

@@ -63,6 +63,10 @@ function buildAdapter(
     nowMs?: () => number;
     onError?: (kind: "flush" | "overflow" | "kind-mismatch", err: unknown) => void;
     histogramBounds?: number[];
+    metricMetadata?: Record<
+      string,
+      { description?: string; unit?: string; boundaries?: readonly number[] }
+    >;
   } = {},
 ) {
   return createOtlpHttpMeterAdapter({
@@ -78,6 +82,7 @@ function buildAdapter(
     nowMs: overrides.nowMs,
     onError: overrides.onError,
     histogramBounds: overrides.histogramBounds,
+    metricMetadata: overrides.metricMetadata,
   });
 }
 
@@ -290,3 +295,101 @@ describe("createOtlpHttpMeterAdapter — buffer + flush", () => {
     expect(slow).toHaveBeenCalledTimes(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Per-metric bucket boundaries
+// ---------------------------------------------------------------------------
+
+interface HistoMetric {
+  name: string;
+  unit?: string;
+  histogram?: {
+    dataPoints: Array<{
+      attributes: Array<{ key: string; value: Record<string, unknown> }>;
+      count: string;
+      sum: number;
+      bucketCounts: string[];
+      explicitBounds: number[];
+    }>;
+  };
+}
+
+function histoMetrics(calls: Array<{ init?: RequestInit }>): HistoMetric[] {
+  const payload = JSON.parse(calls[0].init!.body as string) as {
+    resourceMetrics: Array<{ scopeMetrics: Array<{ metrics: HistoMetric[] }> }>;
+  };
+  return payload.resourceMetrics[0].scopeMetrics[0].metrics;
+}
+
+// Decades of bytes, mirroring CACHE_SIZE_BUCKET_BOUNDARIES_BYTES.
+const BYTE_BOUNDS = [1_000, 10_000, 100_000, 1_000_000, 10_000_000, 33_554_432];
+
+describe("createOtlpHttpMeterAdapter — per-metric bucket boundaries", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-05-18T16:00:00.000Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("buckets a metric against its own boundaries, not the adapter default", async () => {
+    const { impl, calls } = captureFetch();
+    const meter = buildAdapter({
+      fetchImpl: impl,
+      // The ms-tuned adapter default: every byte value would saturate its
+      // overflow bucket, which is the regression this test pins.
+      histogramBounds: [5, 10, 25, 50, 75, 100, 250, 500, 1000],
+      metricMetadata: { "deco.cache.size": { unit: "By", boundaries: BYTE_BOUNDS } },
+    });
+
+    const labels = { op: "set", profile: "productList" };
+    meter.histogramRecord("deco.cache.size", 512, labels); // bucket 0  (<= 1k)
+    meter.histogramRecord("deco.cache.size", 50_000, labels); // bucket 2  (<= 100k)
+    meter.histogramRecord("deco.cache.size", 50_000_000, labels); // overflow (> 32M)
+
+    await meter.flush();
+
+    const dp = histoMetrics(calls)[0].histogram!.dataPoints[0];
+    expect(dp.explicitBounds).toEqual(BYTE_BOUNDS);
+    expect(dp.bucketCounts).toEqual(["1", "0", "1", "0", "0", "0", "1"]);
+    expect(dp.count).toBe("3");
+  });
+
+  it("emits the bounds the counts were filed against, per metric, in one flush", async () => {
+    const { impl, calls } = captureFetch();
+    const meter = buildAdapter({
+      fetchImpl: impl,
+      histogramBounds: [5, 10, 25],
+      metricMetadata: { "deco.cache.size": { unit: "By", boundaries: BYTE_BOUNDS } },
+    });
+
+    // Two histograms with different units in the SAME adapter — the bug was
+    // that both serialized with one shared array.
+    meter.histogramRecord("deco.cache.size", 512, { op: "set" });
+    meter.histogramRecord("deco.loader.duration", 7, { name: "x" });
+
+    await meter.flush();
+
+    const byName = Object.fromEntries(histoMetrics(calls).map((m) => [m.name, m]));
+    expect(byName["deco.cache.size"].histogram!.dataPoints[0].explicitBounds).toEqual(BYTE_BOUNDS);
+    expect(byName["deco.loader.duration"].histogram!.dataPoints[0].explicitBounds).toEqual([
+      5, 10, 25,
+    ]);
+  });
+
+  it("falls back to the adapter default when a metric declares no boundaries", async () => {
+    const { impl, calls } = captureFetch();
+    const meter = buildAdapter({ fetchImpl: impl, histogramBounds: [10, 100] });
+
+    meter.histogramRecord("deco.loader.duration", 50, { name: "x" });
+
+    await meter.flush();
+
+    const dp = histoMetrics(calls)[0].histogram!.dataPoints[0];
+    expect(dp.explicitBounds).toEqual([10, 100]);
+    expect(dp.bucketCounts).toEqual(["0", "1", "0"]);
+  });
+});

package/src/sdk/otelHttpMeter.ts

@@ -84,8 +84,20 @@ export interface OtlpHttpMeterOptions {
    * The framework owns the lookup; callers MUST NOT pass metadata at
    * record time. See `MetricNames` / `METRIC_METADATA` in
    * `middleware/observability.ts`.
+   *
+   * `boundaries`, when present, is ALSO used to bucket that metric, overriding
+   * the adapter-wide `histogramBounds`. Without this a byte-sized histogram and
+   * a seconds-valued one would share the single ms-tuned default and both read
+   * back as a single saturated bucket.
    */
-  metricMetadata?: Record<string, { description?: string; unit?: string }>;
+  metricMetadata?: Record<string, MetricMetadata>;
+}
+
+export interface MetricMetadata {
+  description?: string;
+  unit?: string;
+  /** Explicit bucket bounds for THIS metric, in the metric's own unit. */
+  boundaries?: readonly number[];
 }
 
 export interface OtlpHttpMeter extends MeterAdapter {
@@ -130,6 +142,13 @@ interface MetricEntry {
   counter?: Map<string, CounterPoint>;
   gauge?: Map<string, GaugePoint>;
   histogram?: Map<string, HistogramPoint>;
+  /**
+   * Bounds this metric is bucketed with — resolved once from the metric's own
+   * `boundaries` metadata, falling back to the adapter-wide default. Held on
+   * the entry so `serializeOtlp` emits the bounds the counts were actually
+   * filed against; emitting a different array silently mislabels every bucket.
+   */
+  bounds?: readonly number[];
 }
 
 // ---------------------------------------------------------------------------
@@ -273,6 +292,8 @@ export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpH
     }
     const entry = existing ?? materializeEntry(name, "histogram");
     if (!entry.histogram) return;
+    const bounds = entry.bounds ?? metricMetadata[name]?.boundaries ?? histogramBounds;
+    entry.bounds = bounds;
     let point = entry.histogram.get(key);
     if (!point) {
       point = {
@@ -280,7 +301,7 @@ export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpH
         sum: 0,
         min: Number.POSITIVE_INFINITY,
         max: Number.NEGATIVE_INFINITY,
-        bucketCounts: new Array(histogramBounds.length + 1).fill(0),
+        bucketCounts: new Array(bounds.length + 1).fill(0),
         attrs: labels ? { ...labels } : {},
         startTimeUnixNano: msToNs(isolateStartMs),
       };
@@ -290,10 +311,10 @@ export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpH
     point.sum += value;
     if (value < point.min) point.min = value;
     if (value > point.max) point.max = value;
-    // Locate bucket. histogramBounds is small (<=20); linear scan is fine.
-    let bucketIdx = histogramBounds.length;
-    for (let i = 0; i < histogramBounds.length; i++) {
-      if (value <= histogramBounds[i]) {
+    // Locate bucket. bounds is small (<=20); linear scan is fine.
+    let bucketIdx = bounds.length;
+    for (let i = 0; i < bounds.length; i++) {
+      if (value <= bounds[i]) {
         bucketIdx = i;
         break;
       }
@@ -410,7 +431,7 @@ interface SerializeOpts {
   scopeVersion: string;
   histogramBounds: number[];
   flushAtNs: string;
-  metricMetadata: Record<string, { description?: string; unit?: string }>;
+  metricMetadata: Record<string, MetricMetadata>;
 }
 
 function serializeOtlp(
@@ -470,7 +491,9 @@ function serializeOtlp(
           min: point.min === Number.POSITIVE_INFINITY ? 0 : point.min,
           max: point.max === Number.NEGATIVE_INFINITY ? 0 : point.max,
           bucketCounts: point.bucketCounts.map((c) => String(c)),
-          explicitBounds: opts.histogramBounds,
+          // Must be the array the counts were bucketed against, not the
+          // adapter-wide default — see MetricEntry.bounds.
+          explicitBounds: entry.bounds ?? opts.histogramBounds,
         });
       }
       otlpMetrics.push({