@decocms/blocks 8.0.0 → 8.1.0-next.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/bin/deco.js +13 -0
  2. package/package.json +39 -3
  3. package/src/cms/applySectionConventions.ts +26 -2
  4. package/src/cms/blockSource.ts +37 -0
  5. package/src/cms/client.ts +5 -0
  6. package/src/cms/deferredTrigger.ts +58 -0
  7. package/src/cms/draftSource.ts +171 -57
  8. package/src/cms/index.ts +32 -3
  9. package/src/cms/loader.ts +318 -59
  10. package/src/cms/registry.ts +22 -0
  11. package/src/cms/renderJson.ts +179 -0
  12. package/src/cms/resolve.ts +396 -95
  13. package/src/cms/schema.ts +9 -5
  14. package/src/cms/sectionLoaders.ts +106 -56
  15. package/src/hooks/Image.tsx +70 -6
  16. package/src/hooks/LiveControls.tsx +30 -8
  17. package/src/hooks/Stats.tsx +134 -0
  18. package/src/hooks/index.ts +5 -0
  19. package/src/hooks/useLoadMore.ts +100 -0
  20. package/src/index.ts +37 -0
  21. package/src/middleware/observability.ts +173 -16
  22. package/src/preview/DraftPreviewBadge.tsx +306 -0
  23. package/src/preview/decoMark.ts +11 -0
  24. package/src/preview/index.ts +8 -0
  25. package/src/protocol/assets.ts +124 -0
  26. package/src/protocol/canonical.ts +7 -0
  27. package/src/protocol/ciphertext.ts +6 -0
  28. package/src/protocol/client.ts +170 -0
  29. package/src/protocol/conformance/cases/assets.ts +81 -0
  30. package/src/protocol/conformance/cases/guards.ts +314 -0
  31. package/src/protocol/conformance/cases/reads.ts +168 -0
  32. package/src/protocol/conformance/cases/types.ts +9 -0
  33. package/src/protocol/conformance/cases/wire.ts +138 -0
  34. package/src/protocol/conformance/cases/writes.ts +345 -0
  35. package/src/protocol/conformance/contentHashFixtures.ts +79 -0
  36. package/src/protocol/conformance/context.ts +222 -0
  37. package/src/protocol/conformance/index.ts +140 -0
  38. package/src/protocol/errors.ts +142 -0
  39. package/src/protocol/index.ts +39 -0
  40. package/src/protocol/keys.ts +279 -0
  41. package/src/protocol/params.ts +67 -0
  42. package/src/protocol/secrets.ts +231 -0
  43. package/src/protocol/server/assets.ts +119 -0
  44. package/src/protocol/server/auth.ts +49 -0
  45. package/src/protocol/server/bodyCache.ts +84 -0
  46. package/src/protocol/server/content.ts +175 -0
  47. package/src/protocol/server/core.ts +112 -0
  48. package/src/protocol/server/handler.ts +102 -0
  49. package/src/protocol/server/http.ts +139 -0
  50. package/src/protocol/server/index.ts +11 -0
  51. package/src/protocol/server/methods/apply.ts +341 -0
  52. package/src/protocol/server/methods/read.ts +156 -0
  53. package/src/protocol/server/rpc.ts +136 -0
  54. package/src/protocol/storage/fs/hash.ts +21 -0
  55. package/src/protocol/storage/fs/index.ts +338 -0
  56. package/src/protocol/storage/fs/lock.ts +68 -0
  57. package/src/protocol/storage/fs/transaction.ts +183 -0
  58. package/src/protocol/storage/fs/unsupported.ts +15 -0
  59. package/src/protocol/storage/memory.ts +238 -0
  60. package/src/protocol/storage.ts +182 -0
  61. package/src/protocol/types.ts +172 -0
  62. package/src/sdk/abTesting.ts +60 -3
  63. package/src/sdk/analytics.ts +72 -2
  64. package/src/sdk/cacheHeaders.ts +210 -10
  65. package/src/sdk/cacheStorage.ts +287 -0
  66. package/src/sdk/cachedLoader.ts +143 -90
  67. package/src/sdk/crypto.ts +16 -2
  68. package/src/sdk/deepOmit.ts +52 -0
  69. package/src/sdk/encoding.ts +2 -5
  70. package/src/sdk/experiments.ts +314 -0
  71. package/src/sdk/fetchCache.ts +269 -0
  72. package/src/sdk/fetchTimeout.ts +58 -0
  73. package/src/sdk/flags.ts +38 -8
  74. package/src/sdk/index.ts +7 -0
  75. package/src/sdk/instrumentedFetch.ts +25 -2
  76. package/src/sdk/nonce.ts +46 -0
  77. package/src/sdk/normalizeUrls.ts +2 -2
  78. package/src/sdk/observability.ts +8 -1
  79. package/src/sdk/otel.ts +131 -25
  80. package/src/sdk/otelHttpLog.ts +4 -4
  81. package/src/sdk/otelHttpMeter.ts +39 -13
  82. package/src/sdk/otelHttpTracer.ts +4 -4
  83. package/src/sdk/redirects.ts +113 -5
  84. package/src/sdk/responseCache.ts +82 -0
  85. package/src/sdk/urlUtils.ts +49 -0
  86. package/src/sdk/useSuggestions.ts +1 -1
  87. package/src/v8/analytics.ts +50 -0
  88. package/src/v8/background.ts +107 -0
  89. package/src/v8/builtins/data.ts +23 -0
  90. package/src/v8/builtins/index.ts +26 -0
  91. package/src/v8/builtins/lazy.ts +23 -0
  92. package/src/v8/builtins/legacy.ts +65 -0
  93. package/src/v8/builtins/matchers.ts +31 -0
  94. package/src/v8/builtins/multivariate.ts +25 -0
  95. package/src/v8/builtins/secret.ts +82 -0
  96. package/src/v8/canonical.ts +117 -0
  97. package/src/v8/ciphertext.ts +158 -0
  98. package/src/v8/cli/builtins.ts +20 -0
  99. package/src/v8/cli/check/index.ts +774 -0
  100. package/src/v8/cli/check/messages.ts +168 -0
  101. package/src/v8/cli/content.ts +287 -0
  102. package/src/v8/cli/index.ts +17 -0
  103. package/src/v8/cli/log.ts +18 -0
  104. package/src/v8/cli/main.ts +12 -0
  105. package/src/v8/cli/root.ts +66 -0
  106. package/src/v8/cli/run.ts +236 -0
  107. package/src/v8/cli/schema/builtinSchemas.ts +236 -0
  108. package/src/v8/cli/schema/generate.ts +507 -0
  109. package/src/v8/cli/schema/index.ts +63 -0
  110. package/src/v8/cli/schema/tsProgram.ts +497 -0
  111. package/src/v8/cli/schema/typeToSchema.ts +689 -0
  112. package/src/v8/cli/serve/server.ts +303 -0
  113. package/src/v8/cli/watch.ts +86 -0
  114. package/src/v8/client.ts +147 -0
  115. package/src/v8/cms.ts +237 -0
  116. package/src/v8/content.ts +195 -0
  117. package/src/v8/draft.ts +136 -0
  118. package/src/v8/errors.ts +59 -0
  119. package/src/v8/fetch.ts +152 -0
  120. package/src/v8/identity.ts +65 -0
  121. package/src/v8/index.ts +39 -0
  122. package/src/v8/json.ts +74 -0
  123. package/src/v8/matchRoute.ts +204 -0
  124. package/src/v8/remoteLoader.ts +282 -0
  125. package/src/v8/resolver.ts +278 -0
  126. package/src/v8/secrets.ts +17 -0
  127. package/src/v8/telemetry.ts +533 -0
  128. package/src/v8/types.ts +240 -0
  129. package/src/cms/blockSource.test.ts +0 -76
  130. package/src/cms/client.browserBundle.test.ts +0 -44
  131. package/src/cms/draftSource.test.ts +0 -343
  132. package/src/cms/layoutCacheRace.test.ts +0 -181
  133. package/src/cms/loadDecofileDirectory.test.ts +0 -109
  134. package/src/cms/loader.test.ts +0 -200
  135. package/src/cms/registry.test.ts +0 -110
  136. package/src/cms/resolve.test.ts +0 -980
  137. package/src/cms/schema.test.ts +0 -356
  138. package/src/cms/sectionLoaderContext.test.ts +0 -111
  139. package/src/cms/sectionLoaders.test.ts +0 -533
  140. package/src/cms/sectionMixins.test.ts +0 -167
  141. package/src/cms/stickyFlags.test.ts +0 -117
  142. package/src/flags/flags.test.ts +0 -148
  143. package/src/hooks/Image.test.ts +0 -100
  144. package/src/hooks/RenderSection.test.tsx +0 -81
  145. package/src/matchers/builtins.test.ts +0 -318
  146. package/src/matchers/override.test.ts +0 -205
  147. package/src/middleware/hydrationContext.test.ts +0 -61
  148. package/src/middleware/observability.test.ts +0 -242
  149. package/src/middleware/validateSection.test.ts +0 -147
  150. package/src/sdk/abTesting.test.ts +0 -326
  151. package/src/sdk/cacheHeaders.test.ts +0 -115
  152. package/src/sdk/cachedLoader.test.ts +0 -122
  153. package/src/sdk/cachedLoaderModule.test.ts +0 -209
  154. package/src/sdk/cn.test.ts +0 -34
  155. package/src/sdk/composite.test.ts +0 -121
  156. package/src/sdk/cookie.test.ts +0 -108
  157. package/src/sdk/encoding.test.ts +0 -71
  158. package/src/sdk/env.test.ts +0 -33
  159. package/src/sdk/flags.test.ts +0 -91
  160. package/src/sdk/http.test.ts +0 -71
  161. package/src/sdk/inflightTimeout.test.ts +0 -35
  162. package/src/sdk/instrumentedFetch.test.ts +0 -559
  163. package/src/sdk/invoke.test.ts +0 -115
  164. package/src/sdk/logger.test.ts +0 -432
  165. package/src/sdk/otel.test.ts +0 -526
  166. package/src/sdk/otelAdapters.test.ts +0 -89
  167. package/src/sdk/otelHttpLog.test.ts +0 -457
  168. package/src/sdk/otelHttpMeter.test.ts +0 -292
  169. package/src/sdk/otelHttpTracer.test.ts +0 -474
  170. package/src/sdk/requestContextStorage.browser.test.ts +0 -29
  171. package/src/sdk/urlRedaction.test.ts +0 -73
  172. package/src/sdk/useDevice.test.ts +0 -130
  173. package/src/sdk/useScript.test.ts +0 -128
  174. package/src/sdk/useSuggestions.test.ts +0 -230
  175. package/tsconfig.json +0 -7
@@ -0,0 +1,100 @@
1
+ "use client";
2
+
3
+ import { useState, useEffect, useCallback, useRef } from "react";
4
+
5
+ /**
6
+ * Extract the next-page URL from a loader result.
7
+ * Handles both conventions used by commerce loaders:
8
+ * - pageInfo.nextPage (VTEX, Blog, most standard loaders)
9
+ * - nextPage (flat, some legacy loaders)
10
+ */
11
+ export function getNextPageUrl(data: unknown): string | undefined {
12
+ if (!data || typeof data !== "object") return undefined;
13
+ const d = data as Record<string, unknown>;
14
+ if (d.pageInfo && typeof d.pageInfo === "object") {
15
+ const pi = d.pageInfo as Record<string, unknown>;
16
+ if (typeof pi.nextPage === "string" && pi.nextPage) return pi.nextPage;
17
+ }
18
+ if (typeof d.nextPage === "string" && d.nextPage) return d.nextPage;
19
+ return undefined;
20
+ }
21
+
22
+ /**
23
+ * Accumulates pages of loader data for "Ver mais" / load-more pagination.
24
+ *
25
+ * Fresh's `usePartialSection({ mode: "append" })` appended HTML without a
26
+ * page reload. This hook is the TanStack equivalent: it calls the loader
27
+ * via POST /deco/invoke — passing the nextPage URL as `__pageUrl` so the
28
+ * loader reconstructs query, sort, and filter state from it — then pushes
29
+ * the result into local state.
30
+ *
31
+ * Usage in a migrated section:
32
+ * ```tsx
33
+ * "use client"
34
+ * const { pages, loadMore, loading, hasMore, error } = useLoadMore(
35
+ * props.page ?? { products: [], pageInfo: {} },
36
+ * "apps/vtex.ts/loaders/intelligentSearch/productListingPage.ts",
37
+ * pageUrl // resetKey: pass the current page URL so accumulated pages reset on filter/sort change
38
+ * )
39
+ * const allProducts = pages.flatMap(p => p.products ?? [])
40
+ * ```
41
+ *
42
+ * The component must be `"use client"` because this hook uses useState.
43
+ *
44
+ * @param resetKey - When this value changes, accumulated pages reset to [initial].
45
+ * Pass the current page URL (or any value that changes on filter/sort navigation)
46
+ * to clear the accumulated product list when the user changes filters.
47
+ * Without resetKey, add `key={pageUrl}` to the section element instead.
48
+ */
49
+ export function useLoadMore<T>(initial: T, loaderKey: string, resetKey?: unknown) {
50
+ const [pages, setPages] = useState<T[]>([initial]);
51
+ const [loading, setLoading] = useState(false);
52
+ const [error, setError] = useState<Error | null>(null);
53
+ // useRef guard prevents two rapid clicks both passing the !loading check
54
+ // before the async state update propagates (React state is not synchronous).
55
+ const inflight = useRef(false);
56
+ // Skip the reset effect on first mount — pages are already seeded from useState.
57
+ const isFirstRender = useRef(true);
58
+
59
+ useEffect(() => {
60
+ if (isFirstRender.current) {
61
+ isFirstRender.current = false;
62
+ return;
63
+ }
64
+ setPages([initial]);
65
+ setError(null);
66
+ // eslint-disable-next-line react-hooks/exhaustive-deps
67
+ }, [resetKey]);
68
+
69
+ const lastPage = pages[pages.length - 1];
70
+ const nextPageRel = getNextPageUrl(lastPage);
71
+ const hasMore = Boolean(nextPageRel);
72
+
73
+ const loadMore = useCallback(async () => {
74
+ if (!nextPageRel || inflight.current) return;
75
+ inflight.current = true;
76
+ setLoading(true);
77
+ setError(null);
78
+ try {
79
+ const abs = new URL(nextPageRel, location.href);
80
+ const res = await fetch("/deco/invoke", {
81
+ method: "POST",
82
+ headers: { "content-type": "application/json" },
83
+ body: JSON.stringify({
84
+ key: loaderKey,
85
+ props: { __pageUrl: abs.href, __pagePath: abs.pathname },
86
+ }),
87
+ });
88
+ if (!res.ok) throw new Error(`invoke ${res.status} for ${loaderKey}`);
89
+ const next = (await res.json()) as T;
90
+ setPages((prev) => [...prev, next]);
91
+ } catch (e) {
92
+ setError(e instanceof Error ? e : new Error(String(e)));
93
+ } finally {
94
+ inflight.current = false;
95
+ setLoading(false);
96
+ }
97
+ }, [nextPageRel, loaderKey]);
98
+
99
+ return { pages, loadMore, loading, hasMore, error };
100
+ }
package/src/index.ts CHANGED
@@ -6,3 +6,40 @@ export * from "./middleware/index";
6
6
  // granular imports too (see `@decocms/blocks/sdk/logger`, `.../observability`).
7
7
  export { type Logger, type LogLevel, logger, setLogLevel } from "./sdk/logger";
8
8
  export * from "./types/index";
9
+
10
+ // Next major (v8) core SDK. Explicit re-exports shadow the star exports above,
11
+ // so where v7 and v8 share a name (`DraftPointer`, `parseDraftPointer`) the
12
+ // root serves the v8 one; v7's stays reachable at `@decocms/blocks/cms`.
13
+ export {
14
+ type Analytics,
15
+ type Block,
16
+ type BlockFunction,
17
+ type Blocks,
18
+ type Client,
19
+ type CMS,
20
+ type CMSError,
21
+ createCMS,
22
+ DRAFT_COOKIE,
23
+ type DraftPointer,
24
+ draftCookie,
25
+ draftPointer,
26
+ formatDraftPointer,
27
+ type Lazy,
28
+ type ListOptions,
29
+ type Loader,
30
+ type Match,
31
+ matchRoute,
32
+ type Page,
33
+ parseDraftPointer,
34
+ type Redirect,
35
+ type Result,
36
+ type Route,
37
+ remoteLoader,
38
+ resetForTests,
39
+ type Secret,
40
+ type Seo,
41
+ type Snapshot,
42
+ type Telemetry,
43
+ type TelemetryConfig,
44
+ type Variant,
45
+ } from "./v8/index";
@@ -27,7 +27,23 @@
27
27
  *
28
28
  * configureMeter({
29
29
  * counterInc: (name, value, labels) => metrics.getMeter("deco").createCounter(name).add(value, labels),
30
- * histogramRecord: (name, value, labels) => metrics.getMeter("deco").createHistogram(name).record(value, labels),
30
+ * histogramRecord: (name, value, labels) => {
31
+ * // METRIC_METADATA carries the unit AND the bucket boundaries. Forwarding
32
+ * // `boundaries` to `advice` is required, not optional: durations are
33
+ * // recorded in seconds and the SDK's default buckets are milliseconds, so
34
+ * // an adapter that omits it files everything into the first bucket and
35
+ * // every quantile reads back as ~0.
36
+ * const meta = METRIC_METADATA[name];
37
+ * metrics.getMeter("deco")
38
+ * .createHistogram(name, {
39
+ * unit: meta?.unit,
40
+ * description: meta?.description,
41
+ * advice: meta?.boundaries
42
+ * ? { explicitBucketBoundaries: [...meta.boundaries] }
43
+ * : undefined,
44
+ * })
45
+ * .record(value, labels);
46
+ * },
31
47
  * });
32
48
  * ```
33
49
  */
@@ -263,41 +279,126 @@ export const MetricNames = {
263
279
  // Single cache counter dimensioned by `deco.cache.status` — follows the OTel
264
280
  // semconv pattern (cf. nfs.server.repcache.requests + .status). deco-cx/deco
265
281
  // uses the same name so both frameworks aggregate together.
282
+ // Labels on this counter use short keys (status/profile/layer/provider) —
283
+ // the metric name already provides the deco.cache.* namespace.
266
284
  CACHE_REQUESTS: "deco.cache.requests",
285
+ // Size in bytes of the values moving through a cache, dimensioned by `op`.
286
+ // Bucketed in decades of bytes — see CACHE_SIZE_BUCKET_BOUNDARIES_BYTES.
287
+ CACHE_SIZE: "deco.cache.size",
267
288
  RESOLVE_DURATION: "deco.cms.resolve.duration",
268
289
  LOADER_DURATION: "deco.loader.duration",
269
290
  LOADER_ERRORS: "deco.loader.errors",
270
291
  } as const;
271
292
 
293
+ /**
294
+ * Explicit bucket boundaries, in SECONDS, for every duration histogram declared
295
+ * in {@link METRIC_METADATA}.
296
+ *
297
+ * These exist because the unit and the buckets are configured in two different
298
+ * places and had drifted apart. The record helpers divide by 1000, so values
299
+ * arrive in seconds — correct per SemConv. But the OTel SDK's *default*
300
+ * boundaries are `[0, 5, 10, 25, 50, 75, 100, 250, 500, 1000]`, which are
301
+ * milliseconds. An adapter that calls `createHistogram(name)` without an
302
+ * `advice` therefore files every sub-5-second observation into the first bucket.
303
+ *
304
+ * Measured on the production ClickHouse before this change: 99.8%–99.95% of all
305
+ * observations on `http.server.request.duration` (78.7M/hour),
306
+ * `http.client.request.duration`, `deco.loader.duration` and
307
+ * `deco.cms.resolve.duration` sat in bucket 1, so every quantile read back as
308
+ * ~0 and the latency dashboards had to fall back to tail-sampled traces.
309
+ *
310
+ * Values are the SemConv-recommended defaults for HTTP duration histograms.
311
+ */
312
+ export const DURATION_BUCKET_BOUNDARIES_SECONDS: readonly number[] = [
313
+ 0.005,
314
+ 0.01,
315
+ 0.025,
316
+ 0.05,
317
+ 0.075,
318
+ 0.1,
319
+ 0.25,
320
+ 0.5,
321
+ 0.75,
322
+ 1,
323
+ 2.5,
324
+ 5,
325
+ 7.5,
326
+ 10,
327
+ ];
328
+
329
+ /**
330
+ * Bucket boundaries, in BYTES, for {@link MetricNames.CACHE_SIZE}.
331
+ *
332
+ * Decades, matching the `http.server.response.body.size` histogram already
333
+ * flowing through the same ingestor — a size distribution is read in orders of
334
+ * magnitude, not in linear steps, and reusing the house convention means the
335
+ * two byte histograms are directly comparable.
336
+ *
337
+ * The range is bounded on both ends by the loader cache itself: entries are
338
+ * floored at `MIN_ENTRY_BYTES` (512 B) and the store is capped at 32 MB, which
339
+ * is why the last bound is the cap rather than another decade — the top bucket
340
+ * then reads as "single entry at/near the whole cache budget", which is the
341
+ * thing worth alerting on.
342
+ */
343
+ export const CACHE_SIZE_BUCKET_BOUNDARIES_BYTES: readonly number[] = [
344
+ 1_000,
345
+ 10_000,
346
+ 100_000,
347
+ 1_000_000,
348
+ 10_000_000,
349
+ 33_554_432,
350
+ ];
351
+
272
352
  /**
273
353
  * Per-metric metadata emitted in the OTLP payload's `description` and
274
354
  * `unit` fields. Durations are normalized to **seconds at the source** (OTel
275
355
  * semconv), matching the deco-cx/deco framework — NOT converted downstream in
276
356
  * the collector. Callers still pass milliseconds; the record helpers divide.
277
357
  *
358
+ * `boundaries`, when present, MUST be forwarded to the histogram's `advice` at
359
+ * creation time — the unit alone does not tell the SDK how to bucket, and its
360
+ * defaults assume milliseconds. See
361
+ * {@link DURATION_BUCKET_BOUNDARIES_SECONDS}.
362
+ *
278
363
  * Keep keys aligned with `MetricNames` values so a missing entry is a
279
364
  * type error at compile time when a new metric ships without metadata.
280
365
  */
281
- export const METRIC_METADATA: Record<string, { description: string; unit: string }> = {
366
+ export const METRIC_METADATA: Record<
367
+ string,
368
+ {
369
+ description: string;
370
+ unit: string;
371
+ boundaries?: readonly number[];
372
+ }
373
+ > = {
282
374
  [MetricNames.HTTP_SERVER_REQUEST_DURATION]: {
283
375
  description: "Duration of HTTP server requests handled at the Worker entry point.",
284
376
  unit: "s",
377
+ boundaries: DURATION_BUCKET_BOUNDARIES_SECONDS,
285
378
  },
286
379
  [MetricNames.HTTP_CLIENT_REQUEST_DURATION]: {
287
380
  description: "Duration of outbound HTTP client requests (commerce, generic fetch).",
288
381
  unit: "s",
382
+ boundaries: DURATION_BUCKET_BOUNDARIES_SECONDS,
289
383
  },
290
384
  [MetricNames.CACHE_REQUESTS]: {
291
- description: "Cache lookups, dimensioned by deco.cache.status (hit/stale/miss/bypass).",
385
+ description: "Cache lookups, dimensioned by status (hit/stale/miss/bypass).",
292
386
  unit: "{request}",
293
387
  },
388
+ [MetricNames.CACHE_SIZE]: {
389
+ description: "Size in bytes of values written to / read from a cache, dimensioned by op.",
390
+ unit: "By",
391
+ boundaries: CACHE_SIZE_BUCKET_BOUNDARIES_BYTES,
392
+ },
294
393
  [MetricNames.RESOLVE_DURATION]: {
295
394
  description: "Duration of `deco.cms.resolvePage` — CMS route to block tree resolution.",
296
395
  unit: "s",
396
+ boundaries: DURATION_BUCKET_BOUNDARIES_SECONDS,
297
397
  },
298
398
  [MetricNames.LOADER_DURATION]: {
299
399
  description: "Per-loader execution duration, emitted by cachedLoader.",
300
400
  unit: "s",
401
+ boundaries: DURATION_BUCKET_BOUNDARIES_SECONDS,
301
402
  },
302
403
  [MetricNames.LOADER_ERRORS]: {
303
404
  description: "Per-loader error count.",
@@ -398,7 +499,7 @@ export function recordRequestMetric(
398
499
  // - `status_class`: 5-element enum (2xx / 3xx / 4xx / 5xx / unknown).
399
500
  // - `outcome`: CF outcome enum (~7 values).
400
501
  // - `cache_decision`: 5-element enum.
401
- // - `cache_layer`: 3-element enum (edge / cachedLoader / vtex-swr).
502
+ // - `cache_layer`: 3-element enum (edge / cachedLoader / swr).
402
503
  // - `region`: ~250 CF colo codes worldwide.
403
504
  // Total combinations are bounded — safe for unbounded series on
404
505
  // ClickHouse but operators should still avoid grouping by `region`
@@ -457,10 +558,15 @@ export type CacheDecision = "HIT" | "STALE-HIT" | "STALE-ERROR" | "MISS" | "BYPA
457
558
  * - `edge` — Cloudflare Cache API (HTML pages, server-fn responses)
458
559
  * - `cachedLoader` — In-memory per-isolate via `sdk/cachedLoader.ts`
459
560
  * (loader-level SWR, dedup, in-flight)
460
- * - `vtex-swr` — Apps-side in-memory cache shared by VTEX clients
461
- * (intelligent-search, cross-selling, etc.)
561
+ * - `swr` — Apps-side in-memory SWR fetch cache shared by commerce
562
+ * clients (VTEX intelligent-search, Magento GraphQL,
563
+ * Shopify, etc.) via `sdk/fetchCache.ts`. Provider-agnostic;
564
+ * the specific backend rides on `deco.cache.provider`
565
+ * (e.g. `vtex` / `magento` / `shopify`), a separate label
566
+ * from `deco.cache.profile` (page-type, set by `edge`).
567
+ * Renamed from the old `vtex-swr` once the util was shared.
462
568
  */
463
- export type CacheLayer = "edge" | "cachedLoader" | "vtex-swr";
569
+ export type CacheLayer = "edge" | "cachedLoader" | "swr";
464
570
 
465
571
  /**
466
572
  * Record a cache hit/miss metric. Also stamps the decision on the active
@@ -471,18 +577,28 @@ export type CacheLayer = "edge" | "cachedLoader" | "vtex-swr";
471
577
  * Backward-compatible signature:
472
578
  * recordCacheMetric(hit, profile?, decision?)
473
579
  * recordCacheMetric(hit, profile?, decision?, layer?)
580
+ * recordCacheMetric(hit, profile?, decision?, layer?, provider?)
474
581
  *
475
582
  * `decision` is optional — when omitted, the metric still records HIT
476
583
  * vs MISS but dashboards can't distinguish SWR/SIE paths. Pass it
477
584
  * whenever known. `layer` defaults to `edge` when called from
478
- * workerEntry; cachedLoader / vtex-swr call sites should pass their
585
+ * workerEntry; cachedLoader / swr call sites should pass their
479
586
  * value explicitly.
587
+ *
588
+ * `profile` and `provider` are DISTINCT dimensions and must not be
589
+ * conflated: `profile` is the page/route type (`product` / `listing` /
590
+ * `search`, set by the `edge` layer) or loader name (`cachedLoader`);
591
+ * `provider` is the commerce backend (`vtex` / `magento` / `shopify`, set
592
+ * by the `swr` layer). Keeping them on separate labels means a
593
+ * `sum by (profile)` panel never blends page-types with backend
594
+ * names. The `swr` layer passes `provider` and leaves `profile` unset.
480
595
  */
481
596
  export function recordCacheMetric(
482
597
  hit: boolean,
483
598
  profile?: string,
484
599
  decision?: CacheDecision,
485
600
  layer?: CacheLayer,
601
+ provider?: string,
486
602
  ) {
487
603
  // Stamp on the active span FIRST so the attribute survives even if the
488
604
  // meter is a no-op (e.g. on tests, or in dev without DECO_METRICS).
@@ -491,22 +607,40 @@ export function recordCacheMetric(
491
607
  if (decision) active.setAttribute?.("deco.cache.status", decision);
492
608
  if (profile) active.setAttribute?.("deco.cache.profile", profile);
493
609
  if (layer) active.setAttribute?.("deco.cache.layer", layer);
610
+ if (provider) active.setAttribute?.("deco.cache.provider", provider);
494
611
  }
495
612
 
496
613
  const m = getState().meter;
497
614
  if (!m) return;
498
- // Single counter dimensioned by deco.cache.status — unified with deco-cx/deco
499
- // (follows the semconv nfs.server.repcache.requests + .status pattern). status
500
- // is the decision when known (HIT/STALE-HIT/STALE-ERROR/MISS/BYPASS), else the
501
- // hit boolean. Same key on span + metric.
615
+ // Single counter dimensioned by status — the metric name deco.cache.requests
616
+ // already scopes the label, so the deco.cache. prefix is redundant on labels.
617
+ // Span attribute keeps the full deco.cache.status key (spans mix attrs from
618
+ // many sources, so the namespace is needed there).
502
619
  const labels: Labels = {
503
- "deco.cache.status": decision ?? (hit ? "HIT" : "MISS"),
620
+ status: decision ?? (hit ? "HIT" : "MISS"),
504
621
  };
505
- if (profile) labels["deco.cache.profile"] = profile;
506
- if (layer) labels["deco.cache.layer"] = layer;
622
+ if (profile) labels["profile"] = profile;
623
+ if (layer) labels["layer"] = layer;
624
+ if (provider) labels["provider"] = provider;
507
625
  m.counterInc(MetricNames.CACHE_REQUESTS, 1, labels);
508
626
  }
509
627
 
628
+ /**
629
+ * Record the size of a value moving through a cache, in BYTES — not seconds,
630
+ * so unlike the duration helpers this one does not divide.
631
+ *
632
+ * `profile` deliberately reuses the label key {@link recordCacheMetric} already
633
+ * uses for the `cachedLoader` layer (there it carries the loader name), so
634
+ * `deco.cache.size` joins `deco.cache.requests{layer="cachedLoader"}` on
635
+ * `profile` with no renaming in the query.
636
+ *
637
+ * Only `op: "set"` is emitted today; the label exists so a future read-side
638
+ * measurement lands on the same series without a breaking dashboard change.
639
+ */
640
+ export function recordCacheSizeMetric(bytes: number, profile: string, op: "set" | "get" = "set") {
641
+ getState().meter?.histogramRecord?.(MetricNames.CACHE_SIZE, bytes, { op, profile });
642
+ }
643
+
510
644
  /**
511
645
  * Labels for the outbound commerce sample recorded on
512
646
  * `http.client.request.duration`. Owned by the framework so apps-start (and
@@ -592,10 +726,33 @@ export function recordLoaderError(name: string) {
592
726
  */
593
727
  export function normalizePath(path: string): string {
594
728
  // Collapse dynamic segments to reduce cardinality
595
- return path
729
+ const collapsed = path
596
730
  .replace(/\/[0-9a-f]{8,}/gi, "/:id")
597
731
  .replace(/\/\d+/g, "/:id")
598
732
  .replace(/\/[^/]+\/p$/, "/:slug/p");
733
+
734
+ // Content slugs are the case none of the rules above catch: they carry no
735
+ // digits, no hex id and no `/p` suffix, so a CMS page passes through as its
736
+ // own literal path and becomes its own series.
737
+ //
738
+ // /mochila-de-couro
739
+ // /moveis/quarto-infantil
740
+ // /acme/eau-de-toilette-spritz-100ml
741
+ //
742
+ // Measured on the production ClickHouse, `http.route` reached 20,714
743
+ // distinct values across only 6 tenants — on `http.server.request.duration`,
744
+ // the highest-volume metric in the pipeline (19M rows / 3h).
745
+ //
746
+ // A hyphen is the discriminator. CMS slugs are hyphenated by construction,
747
+ // while framework and API segments are single words (`api`, `sessions`,
748
+ // `deco`, `invoke`, `loaders`, `render`). Dotfile segments such as
749
+ // `.well-known` are excluded so they keep their meaning.
750
+ return collapsed
751
+ .split("/")
752
+ .map((segment) =>
753
+ segment.includes("-") && !segment.startsWith(".") ? ":slug" : segment,
754
+ )
755
+ .join("/");
599
756
  }
600
757
 
601
758
  // ---------------------------------------------------------------------------