@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.
- package/bin/deco.js +13 -0
- package/package.json +39 -3
- package/src/cms/applySectionConventions.ts +26 -2
- package/src/cms/blockSource.ts +37 -0
- package/src/cms/client.ts +5 -0
- package/src/cms/deferredTrigger.ts +58 -0
- package/src/cms/draftSource.ts +171 -57
- package/src/cms/index.ts +32 -3
- package/src/cms/loader.ts +318 -59
- package/src/cms/registry.ts +22 -0
- package/src/cms/renderJson.ts +179 -0
- package/src/cms/resolve.ts +396 -95
- package/src/cms/schema.ts +9 -5
- package/src/cms/sectionLoaders.ts +106 -56
- package/src/hooks/Image.tsx +70 -6
- package/src/hooks/LiveControls.tsx +30 -8
- package/src/hooks/Stats.tsx +134 -0
- package/src/hooks/index.ts +5 -0
- package/src/hooks/useLoadMore.ts +100 -0
- package/src/index.ts +37 -0
- package/src/middleware/observability.ts +173 -16
- package/src/preview/DraftPreviewBadge.tsx +306 -0
- package/src/preview/decoMark.ts +11 -0
- package/src/preview/index.ts +8 -0
- package/src/protocol/assets.ts +124 -0
- package/src/protocol/canonical.ts +7 -0
- package/src/protocol/ciphertext.ts +6 -0
- package/src/protocol/client.ts +170 -0
- package/src/protocol/conformance/cases/assets.ts +81 -0
- package/src/protocol/conformance/cases/guards.ts +314 -0
- package/src/protocol/conformance/cases/reads.ts +168 -0
- package/src/protocol/conformance/cases/types.ts +9 -0
- package/src/protocol/conformance/cases/wire.ts +138 -0
- package/src/protocol/conformance/cases/writes.ts +345 -0
- package/src/protocol/conformance/contentHashFixtures.ts +79 -0
- package/src/protocol/conformance/context.ts +222 -0
- package/src/protocol/conformance/index.ts +140 -0
- package/src/protocol/errors.ts +142 -0
- package/src/protocol/index.ts +39 -0
- package/src/protocol/keys.ts +279 -0
- package/src/protocol/params.ts +67 -0
- package/src/protocol/secrets.ts +231 -0
- package/src/protocol/server/assets.ts +119 -0
- package/src/protocol/server/auth.ts +49 -0
- package/src/protocol/server/bodyCache.ts +84 -0
- package/src/protocol/server/content.ts +175 -0
- package/src/protocol/server/core.ts +112 -0
- package/src/protocol/server/handler.ts +102 -0
- package/src/protocol/server/http.ts +139 -0
- package/src/protocol/server/index.ts +11 -0
- package/src/protocol/server/methods/apply.ts +341 -0
- package/src/protocol/server/methods/read.ts +156 -0
- package/src/protocol/server/rpc.ts +136 -0
- package/src/protocol/storage/fs/hash.ts +21 -0
- package/src/protocol/storage/fs/index.ts +338 -0
- package/src/protocol/storage/fs/lock.ts +68 -0
- package/src/protocol/storage/fs/transaction.ts +183 -0
- package/src/protocol/storage/fs/unsupported.ts +15 -0
- package/src/protocol/storage/memory.ts +238 -0
- package/src/protocol/storage.ts +182 -0
- package/src/protocol/types.ts +172 -0
- package/src/sdk/abTesting.ts +60 -3
- package/src/sdk/analytics.ts +72 -2
- package/src/sdk/cacheHeaders.ts +210 -10
- package/src/sdk/cacheStorage.ts +287 -0
- package/src/sdk/cachedLoader.ts +143 -90
- package/src/sdk/crypto.ts +16 -2
- package/src/sdk/deepOmit.ts +52 -0
- package/src/sdk/encoding.ts +2 -5
- package/src/sdk/experiments.ts +314 -0
- package/src/sdk/fetchCache.ts +269 -0
- package/src/sdk/fetchTimeout.ts +58 -0
- package/src/sdk/flags.ts +38 -8
- package/src/sdk/index.ts +7 -0
- package/src/sdk/instrumentedFetch.ts +25 -2
- package/src/sdk/nonce.ts +46 -0
- package/src/sdk/normalizeUrls.ts +2 -2
- package/src/sdk/observability.ts +8 -1
- package/src/sdk/otel.ts +131 -25
- package/src/sdk/otelHttpLog.ts +4 -4
- package/src/sdk/otelHttpMeter.ts +39 -13
- package/src/sdk/otelHttpTracer.ts +4 -4
- package/src/sdk/redirects.ts +113 -5
- package/src/sdk/responseCache.ts +82 -0
- package/src/sdk/urlUtils.ts +49 -0
- package/src/sdk/useSuggestions.ts +1 -1
- package/src/v8/analytics.ts +50 -0
- package/src/v8/background.ts +107 -0
- package/src/v8/builtins/data.ts +23 -0
- package/src/v8/builtins/index.ts +26 -0
- package/src/v8/builtins/lazy.ts +23 -0
- package/src/v8/builtins/legacy.ts +65 -0
- package/src/v8/builtins/matchers.ts +31 -0
- package/src/v8/builtins/multivariate.ts +25 -0
- package/src/v8/builtins/secret.ts +82 -0
- package/src/v8/canonical.ts +117 -0
- package/src/v8/ciphertext.ts +158 -0
- package/src/v8/cli/builtins.ts +20 -0
- package/src/v8/cli/check/index.ts +774 -0
- package/src/v8/cli/check/messages.ts +168 -0
- package/src/v8/cli/content.ts +287 -0
- package/src/v8/cli/index.ts +17 -0
- package/src/v8/cli/log.ts +18 -0
- package/src/v8/cli/main.ts +12 -0
- package/src/v8/cli/root.ts +66 -0
- package/src/v8/cli/run.ts +236 -0
- package/src/v8/cli/schema/builtinSchemas.ts +236 -0
- package/src/v8/cli/schema/generate.ts +507 -0
- package/src/v8/cli/schema/index.ts +63 -0
- package/src/v8/cli/schema/tsProgram.ts +497 -0
- package/src/v8/cli/schema/typeToSchema.ts +689 -0
- package/src/v8/cli/serve/server.ts +303 -0
- package/src/v8/cli/watch.ts +86 -0
- package/src/v8/client.ts +147 -0
- package/src/v8/cms.ts +237 -0
- package/src/v8/content.ts +195 -0
- package/src/v8/draft.ts +136 -0
- package/src/v8/errors.ts +59 -0
- package/src/v8/fetch.ts +152 -0
- package/src/v8/identity.ts +65 -0
- package/src/v8/index.ts +39 -0
- package/src/v8/json.ts +74 -0
- package/src/v8/matchRoute.ts +204 -0
- package/src/v8/remoteLoader.ts +282 -0
- package/src/v8/resolver.ts +278 -0
- package/src/v8/secrets.ts +17 -0
- package/src/v8/telemetry.ts +533 -0
- package/src/v8/types.ts +240 -0
- package/src/cms/blockSource.test.ts +0 -76
- package/src/cms/client.browserBundle.test.ts +0 -44
- package/src/cms/draftSource.test.ts +0 -343
- package/src/cms/layoutCacheRace.test.ts +0 -181
- package/src/cms/loadDecofileDirectory.test.ts +0 -109
- package/src/cms/loader.test.ts +0 -200
- package/src/cms/registry.test.ts +0 -110
- package/src/cms/resolve.test.ts +0 -980
- package/src/cms/schema.test.ts +0 -356
- package/src/cms/sectionLoaderContext.test.ts +0 -111
- package/src/cms/sectionLoaders.test.ts +0 -533
- package/src/cms/sectionMixins.test.ts +0 -167
- package/src/cms/stickyFlags.test.ts +0 -117
- package/src/flags/flags.test.ts +0 -148
- package/src/hooks/Image.test.ts +0 -100
- package/src/hooks/RenderSection.test.tsx +0 -81
- package/src/matchers/builtins.test.ts +0 -318
- package/src/matchers/override.test.ts +0 -205
- package/src/middleware/hydrationContext.test.ts +0 -61
- package/src/middleware/observability.test.ts +0 -242
- package/src/middleware/validateSection.test.ts +0 -147
- package/src/sdk/abTesting.test.ts +0 -326
- package/src/sdk/cacheHeaders.test.ts +0 -115
- package/src/sdk/cachedLoader.test.ts +0 -122
- package/src/sdk/cachedLoaderModule.test.ts +0 -209
- package/src/sdk/cn.test.ts +0 -34
- package/src/sdk/composite.test.ts +0 -121
- package/src/sdk/cookie.test.ts +0 -108
- package/src/sdk/encoding.test.ts +0 -71
- package/src/sdk/env.test.ts +0 -33
- package/src/sdk/flags.test.ts +0 -91
- package/src/sdk/http.test.ts +0 -71
- package/src/sdk/inflightTimeout.test.ts +0 -35
- package/src/sdk/instrumentedFetch.test.ts +0 -559
- package/src/sdk/invoke.test.ts +0 -115
- package/src/sdk/logger.test.ts +0 -432
- package/src/sdk/otel.test.ts +0 -526
- package/src/sdk/otelAdapters.test.ts +0 -89
- package/src/sdk/otelHttpLog.test.ts +0 -457
- package/src/sdk/otelHttpMeter.test.ts +0 -292
- package/src/sdk/otelHttpTracer.test.ts +0 -474
- package/src/sdk/requestContextStorage.browser.test.ts +0 -29
- package/src/sdk/urlRedaction.test.ts +0 -73
- package/src/sdk/useDevice.test.ts +0 -130
- package/src/sdk/useScript.test.ts +0 -128
- package/src/sdk/useSuggestions.test.ts +0 -230
- 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) =>
|
|
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<
|
|
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
|
|
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 /
|
|
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
|
-
* - `
|
|
461
|
-
* (intelligent-search,
|
|
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" | "
|
|
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 /
|
|
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
|
|
499
|
-
//
|
|
500
|
-
//
|
|
501
|
-
//
|
|
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
|
-
|
|
620
|
+
status: decision ?? (hit ? "HIT" : "MISS"),
|
|
504
621
|
};
|
|
505
|
-
if (profile) labels["
|
|
506
|
-
if (layer) labels["
|
|
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
|
-
|
|
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
|
// ---------------------------------------------------------------------------
|