@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,533 @@
1
+ /**
2
+ * Telemetry: OpenTelemetry over OTLP/HTTP (JSON, gzipped), with no SDK. See
3
+ * /next/telemetry and /next/telemetry-internals.
4
+ *
5
+ * - **Where** comes from code: `createCMS({ telemetry })`, or the standard
6
+ * `OTEL_EXPORTER_OTLP_ENDPOINT`/`OTEL_EXPORTER_OTLP_HEADERS` when it's left
7
+ * out. `false` sends nothing.
8
+ * - **How much** comes from content: the `Telemetry` saved block of the
9
+ * release being served, capped by `telemetry.limits`.
10
+ * - Metrics are aggregated in memory (delta histograms); error logs and traces
11
+ * are sampled. Batches leave in the background (after the response on
12
+ * Workers, on an unref'd timer elsewhere); a send that fails is retried
13
+ * once on 429/502/503/504 and otherwise dropped.
14
+ * - Everything is scrubbed before encoding: no query strings, tokens,
15
+ * cookies or authorization values, and no value a secret block decrypted.
16
+ */
17
+ import { hasBackgroundHook, later, runInBackground } from "./background";
18
+ import { isResolutionError } from "./errors";
19
+ import { readEnv } from "./identity";
20
+ import { isPlainObject } from "./json";
21
+ import type { CMSError, Snapshot, TelemetryConfig } from "./types";
22
+
23
+ /** The hosted Deco CMS collector, for `telemetry: { site, token }`. */
24
+ const HOSTED_TELEMETRY_ENDPOINT = "https://otel.decocms.com";
25
+
26
+ const SINK = Symbol.for("decocms.blocks.telemetry");
27
+ const FLUSH_MS = 10_000;
28
+ const MAX_LOGS = 200;
29
+ const MAX_SPANS = 1_000;
30
+ const MAX_SECRETS = 1_000;
31
+ const RETRY_STATUSES = new Set([429, 502, 503, 504]);
32
+ /** OpenTelemetry's recommended `http.*.request.duration` buckets, in seconds. */
33
+ const BOUNDS = [0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10];
34
+ const DEFAULTS = { enabled: true, metrics: true, errorSampleRate: 0.05, traceSampleRate: 0 };
35
+ const DEFAULT_LIMITS = { errorSampleRate: 0.1, traceSampleRate: 0 };
36
+
37
+ type Attributes = Record<string, string | number | boolean | undefined>;
38
+
39
+ interface Destination {
40
+ endpoint: string;
41
+ headers: Record<string, string>;
42
+ site?: string;
43
+ limits: { errorSampleRate: number; traceSampleRate: number };
44
+ }
45
+
46
+ interface SpanInput {
47
+ name: string;
48
+ kind: "internal" | "server" | "client";
49
+ traceId: string;
50
+ parentSpanId?: string;
51
+ /** Epoch milliseconds. */
52
+ start: number;
53
+ end: number;
54
+ attributes: Attributes;
55
+ error?: boolean;
56
+ }
57
+
58
+ /** What a client reports: block runs (spans when sampled, failures as error logs) and errors. */
59
+ export interface ClientTelemetry {
60
+ block(type: string, start: number, end: number, error?: unknown): void;
61
+ error(error: CMSError): void;
62
+ }
63
+
64
+ interface Histogram {
65
+ name: string;
66
+ attributes: Attributes;
67
+ count: number;
68
+ sum: number;
69
+ min: number;
70
+ max: number;
71
+ buckets: number[];
72
+ }
73
+
74
+ interface LogRecord {
75
+ time: number;
76
+ message: string;
77
+ attributes: Attributes;
78
+ }
79
+
80
+ /**
81
+ * Where telemetry goes, or `null` for nowhere. `{ site, token }` or
82
+ * `{ endpoint }` with an empty value (an unset environment variable) is off.
83
+ */
84
+ export function resolveDestination(
85
+ config: false | TelemetryConfig | undefined,
86
+ site?: string,
87
+ ): Destination | null {
88
+ if (config === false) return null;
89
+ if (config === undefined || config === null) {
90
+ const endpoint = readEnv("OTEL_EXPORTER_OTLP_ENDPOINT");
91
+ if (!endpoint) return null;
92
+ const headers = parseKeyValues(readEnv("OTEL_EXPORTER_OTLP_HEADERS"));
93
+ return { endpoint, headers, site, limits: DEFAULT_LIMITS };
94
+ }
95
+ const limits = {
96
+ errorSampleRate: rate(config.limits?.errorSampleRate, DEFAULT_LIMITS.errorSampleRate),
97
+ traceSampleRate: rate(config.limits?.traceSampleRate, DEFAULT_LIMITS.traceSampleRate),
98
+ };
99
+ if ("endpoint" in config) {
100
+ if (typeof config.endpoint !== "string" || !config.endpoint) return null;
101
+ return { endpoint: config.endpoint, headers: { ...config.headers }, site, limits };
102
+ }
103
+ if (!config.site || !config.token) return null;
104
+ return {
105
+ endpoint: HOSTED_TELEMETRY_ENDPOINT,
106
+ headers: { authorization: `Bearer ${config.token}` },
107
+ site: config.site,
108
+ limits,
109
+ };
110
+ }
111
+
112
+ export class TelemetryPipeline {
113
+ readonly #destination: Destination;
114
+ #settings = { ...DEFAULTS };
115
+ #settingsRevision: string | undefined;
116
+ #release: string | undefined;
117
+ #histograms = new Map<string, Histogram>();
118
+ #logs: LogRecord[] = [];
119
+ #spans: (SpanInput & { spanId: string })[] = [];
120
+ #windowStart = Date.now();
121
+ #scheduled = false;
122
+ /** Values secret blocks decrypted, replaced with `[redacted]` wherever they'd be sent. */
123
+ readonly #secrets = new Set<string>();
124
+
125
+ constructor(destination: Destination) {
126
+ this.#destination = destination;
127
+ this.#apply(undefined);
128
+ }
129
+
130
+ /** Never send `value`: it's replaced with `[redacted]` in every log, span and label. */
131
+ redact(value: string): void {
132
+ if (value.length > 0 && this.#secrets.size < MAX_SECRETS) this.#secrets.add(value);
133
+ }
134
+
135
+ /** The release being served: its revision labels batches and its `Telemetry` block sets the rates. */
136
+ useRelease(snapshot: Snapshot): void {
137
+ this.#release = snapshot.revision;
138
+ if (this.#settingsRevision === snapshot.revision) return;
139
+ this.#settingsRevision = snapshot.revision;
140
+ const entry = snapshot.blocks.Telemetry;
141
+ this.#apply(isPlainObject(entry) && entry.__resolveType === "telemetry" ? entry : undefined);
142
+ }
143
+
144
+ histogram(name: string, attributes: Attributes, seconds: number): void {
145
+ if (!this.#settings.enabled || !this.#settings.metrics) return;
146
+ const key = `${name}\u0000${JSON.stringify(attributes)}`;
147
+ let histogram = this.#histograms.get(key);
148
+ if (histogram === undefined) {
149
+ histogram = {
150
+ name,
151
+ attributes,
152
+ count: 0,
153
+ sum: 0,
154
+ min: Number.POSITIVE_INFINITY,
155
+ max: Number.NEGATIVE_INFINITY,
156
+ buckets: new Array(BOUNDS.length + 1).fill(0),
157
+ };
158
+ this.#histograms.set(key, histogram);
159
+ }
160
+ histogram.count++;
161
+ histogram.sum += seconds;
162
+ histogram.min = Math.min(histogram.min, seconds);
163
+ histogram.max = Math.max(histogram.max, seconds);
164
+ const bucket = BOUNDS.findIndex((bound) => seconds <= bound);
165
+ histogram.buckets[bucket === -1 ? BOUNDS.length : bucket]++;
166
+ this.#schedule();
167
+ }
168
+
169
+ /** An error log, kept at the error sample rate. */
170
+ error(message: string, attributes: Attributes): void {
171
+ if (!this.#settings.enabled || Math.random() >= this.#settings.errorSampleRate) return;
172
+ if (this.#logs.length >= MAX_LOGS) return;
173
+ this.#logs.push({ time: Date.now(), message, attributes });
174
+ this.#schedule();
175
+ }
176
+
177
+ /** Whether to trace one request (or one upstream call), at the trace sample rate. */
178
+ sampleTrace(): boolean {
179
+ return this.#settings.enabled && Math.random() < this.#settings.traceSampleRate;
180
+ }
181
+
182
+ span(span: SpanInput): void {
183
+ if (!this.#settings.enabled || this.#spans.length >= MAX_SPANS) return;
184
+ this.#spans.push({ ...span, spanId: randomHex(8) });
185
+ this.#schedule();
186
+ }
187
+
188
+ /**
189
+ * The hooks one client reports through. The trace decision is made once per
190
+ * client, on its first block, after its release is loaded, so the first
191
+ * client of a release already uses that release's `Telemetry` block.
192
+ */
193
+ forClient(): ClientTelemetry {
194
+ let decided = false;
195
+ let traceId: string | undefined;
196
+ return {
197
+ block: (type, start, end, error) => {
198
+ if (!decided) {
199
+ decided = true;
200
+ traceId = this.sampleTrace() ? newTraceId() : undefined;
201
+ }
202
+ if (traceId !== undefined) {
203
+ this.span({
204
+ name: type,
205
+ kind: "internal",
206
+ traceId,
207
+ start,
208
+ end,
209
+ attributes: { "deco.block.type": type },
210
+ error: error !== undefined,
211
+ });
212
+ }
213
+ // A ResolutionError was already reported where it started.
214
+ if (error !== undefined && !isResolutionError(error)) {
215
+ this.error(`block "${type}" failed: ${describe(error)}`, {
216
+ "error.code": "BLOCK_FAILED",
217
+ "deco.block.type": type,
218
+ });
219
+ }
220
+ },
221
+ error: (error) => {
222
+ // Block failures arrive through block(); a missing name is ordinary.
223
+ if (error.code === "NOT_FOUND" || error.code === "BLOCK_FAILED") return;
224
+ // A loader's message can quote a draft pointer (and its token): never send it.
225
+ const message = error.code === "LOADER_FAILED" ? "content loader failed" : error.message;
226
+ this.error(message, { "error.code": error.code, "deco.path": error.path.join(".") });
227
+ },
228
+ };
229
+ }
230
+
231
+ /** Sends what's been collected since the last batch. Never throws. */
232
+ async flush(): Promise<void> {
233
+ const now = Date.now();
234
+ const start = this.#windowStart;
235
+ this.#windowStart = now;
236
+ const histograms = [...this.#histograms.values()];
237
+ const logs = this.#logs;
238
+ const spans = this.#spans;
239
+ this.#histograms = new Map();
240
+ this.#logs = [];
241
+ this.#spans = [];
242
+ const scrub = (text: string) => this.#scrub(text);
243
+ const encode = (attributes: Attributes) => encodeAttributes(attributes, scrub);
244
+ const resource = { attributes: encode(this.#resource()) };
245
+ const scope = { name: "@decocms/blocks" };
246
+ const sends: Promise<void>[] = [];
247
+ if (histograms.length > 0) {
248
+ const byName = new Map<string, Histogram[]>();
249
+ for (const h of histograms) byName.set(h.name, [...(byName.get(h.name) ?? []), h]);
250
+ sends.push(
251
+ this.#send("/v1/metrics", {
252
+ resourceMetrics: [
253
+ {
254
+ resource,
255
+ scopeMetrics: [
256
+ {
257
+ scope,
258
+ metrics: [...byName].map(([name, points]) => ({
259
+ name,
260
+ unit: "s",
261
+ histogram: {
262
+ aggregationTemporality: 1, // DELTA
263
+ dataPoints: points.map((h) => ({
264
+ attributes: encode(h.attributes),
265
+ startTimeUnixNano: nanos(start),
266
+ timeUnixNano: nanos(now),
267
+ count: String(h.count),
268
+ sum: h.sum,
269
+ min: h.min,
270
+ max: h.max,
271
+ bucketCounts: h.buckets.map(String),
272
+ explicitBounds: BOUNDS,
273
+ })),
274
+ },
275
+ })),
276
+ },
277
+ ],
278
+ },
279
+ ],
280
+ }),
281
+ );
282
+ }
283
+ if (logs.length > 0) {
284
+ sends.push(
285
+ this.#send("/v1/logs", {
286
+ resourceLogs: [
287
+ {
288
+ resource,
289
+ scopeLogs: [
290
+ {
291
+ scope,
292
+ logRecords: logs.map((log) => ({
293
+ timeUnixNano: nanos(log.time),
294
+ severityNumber: 17,
295
+ severityText: "ERROR",
296
+ body: { stringValue: scrub(log.message) },
297
+ attributes: encode(log.attributes),
298
+ })),
299
+ },
300
+ ],
301
+ },
302
+ ],
303
+ }),
304
+ );
305
+ }
306
+ if (spans.length > 0) {
307
+ const kinds = { internal: 1, server: 2, client: 3 };
308
+ sends.push(
309
+ this.#send("/v1/traces", {
310
+ resourceSpans: [
311
+ {
312
+ resource,
313
+ scopeSpans: [
314
+ {
315
+ scope,
316
+ spans: spans.map((span) => ({
317
+ traceId: span.traceId,
318
+ spanId: span.spanId,
319
+ ...(span.parentSpanId ? { parentSpanId: span.parentSpanId } : {}),
320
+ name: span.name,
321
+ kind: kinds[span.kind],
322
+ startTimeUnixNano: nanos(span.start),
323
+ endTimeUnixNano: nanos(span.end),
324
+ attributes: encode(span.attributes),
325
+ status: { code: span.error ? 2 : 0 },
326
+ })),
327
+ },
328
+ ],
329
+ },
330
+ ],
331
+ }),
332
+ );
333
+ }
334
+ await Promise.all(sends);
335
+ }
336
+
337
+ #scrub(text: string): string {
338
+ let out = text;
339
+ for (const secret of this.#secrets) out = out.split(secret).join("[redacted]");
340
+ return scrubText(out);
341
+ }
342
+
343
+ #apply(block: Record<string, unknown> | undefined): void {
344
+ const { limits } = this.#destination;
345
+ this.#settings = {
346
+ enabled: typeof block?.enabled === "boolean" ? block.enabled : DEFAULTS.enabled,
347
+ metrics: typeof block?.metrics === "boolean" ? block.metrics : DEFAULTS.metrics,
348
+ errorSampleRate: Math.min(
349
+ rate(block?.errorSampleRate, DEFAULTS.errorSampleRate),
350
+ limits.errorSampleRate,
351
+ ),
352
+ traceSampleRate: Math.min(
353
+ rate(block?.traceSampleRate, DEFAULTS.traceSampleRate),
354
+ limits.traceSampleRate,
355
+ ),
356
+ };
357
+ }
358
+
359
+ #schedule(): void {
360
+ if (this.#scheduled) return;
361
+ this.#scheduled = true;
362
+ if (!hasBackgroundHook()) {
363
+ later(FLUSH_MS, () => {
364
+ this.#scheduled = false;
365
+ void this.flush();
366
+ });
367
+ return;
368
+ }
369
+ // With a binding's hook (Workers: after the response, in ctx.waitUntil),
370
+ // a batch goes out once it's FLUSH_MS old; a younger one stays pending
371
+ // and a later request's measurement schedules it again.
372
+ runInBackground(() => {
373
+ this.#scheduled = false;
374
+ if (Date.now() - this.#windowStart < FLUSH_MS) return;
375
+ return this.flush();
376
+ });
377
+ }
378
+
379
+ #resource(): Attributes {
380
+ const site = this.#destination.site;
381
+ return {
382
+ "service.name": readEnv("OTEL_SERVICE_NAME") || site || "decocms-site",
383
+ "service.version": firstEnv(COMMIT_VARIABLES) ?? "unknown",
384
+ "deployment.environment.name":
385
+ readEnv("VERCEL_ENV") ||
386
+ (readEnv("NODE_ENV") === "development" ? "development" : "production"),
387
+ ...(site ? { "deco.site": site } : {}),
388
+ ...(this.#release ? { "deco.release": this.#release } : {}),
389
+ // The standard OTel override wins: service.version=<commit>,
390
+ // deployment.environment.name=preview, service.name=…
391
+ ...parseKeyValues(readEnv("OTEL_RESOURCE_ATTRIBUTES")),
392
+ };
393
+ }
394
+
395
+ async #send(path: string, payload: unknown): Promise<void> {
396
+ const url = this.#destination.endpoint.replace(/\/+$/, "") + path;
397
+ const { body, gzipped } = await gzip(JSON.stringify(payload));
398
+ const headers: Record<string, string> = {
399
+ ...this.#destination.headers,
400
+ "content-type": "application/json",
401
+ };
402
+ if (gzipped) headers["content-encoding"] = "gzip";
403
+ for (let attempt = 0; ; attempt++) {
404
+ let response: Response;
405
+ try {
406
+ response = await fetch(url, { method: "POST", headers, body });
407
+ } catch {
408
+ return; // a collector that's down loses this batch
409
+ }
410
+ void response.body?.cancel().catch(() => {});
411
+ if (response.ok || !RETRY_STATUSES.has(response.status) || attempt >= 1) return;
412
+ await new Promise((resolve) => later(1_000, () => resolve(undefined)));
413
+ }
414
+ }
415
+ }
416
+
417
+ // ---------------------------------------------------------------------------
418
+ // The process's active pipeline, which the instrumented fetch reports to
419
+ // ---------------------------------------------------------------------------
420
+
421
+ /** The pipeline the instrumented fetch reports to: the latest CMS created with telemetry. */
422
+ export function currentTelemetry(): TelemetryPipeline | undefined {
423
+ return (globalThis as Record<symbol, TelemetryPipeline | undefined>)[SINK];
424
+ }
425
+
426
+ export function setCurrentTelemetry(pipeline: TelemetryPipeline | undefined): void {
427
+ (globalThis as Record<symbol, TelemetryPipeline | undefined>)[SINK] = pipeline;
428
+ }
429
+
430
+ // ---------------------------------------------------------------------------
431
+ // Helpers
432
+ // ---------------------------------------------------------------------------
433
+
434
+ /** Where hosts put the deployed commit, tried in order (`service.version`). */
435
+ const COMMIT_VARIABLES = [
436
+ "DECO_COMMIT_SHA",
437
+ "WORKERS_CI_COMMIT_SHA",
438
+ "CF_PAGES_COMMIT_SHA",
439
+ "VERCEL_GIT_COMMIT_SHA",
440
+ "GITHUB_SHA",
441
+ "RENDER_GIT_COMMIT",
442
+ "SOURCE_VERSION",
443
+ "COMMIT_SHA",
444
+ ];
445
+
446
+ function firstEnv(names: readonly string[]): string | undefined {
447
+ for (const name of names) {
448
+ const value = readEnv(name);
449
+ if (value) return value;
450
+ }
451
+ return undefined;
452
+ }
453
+
454
+ const QUERY = /(https?:\/\/[^\s?#"'<>]+)\?[^\s#"'<>]*/gi;
455
+ const CREDENTIAL = /\b(Bearer|Basic)\s+[\w~+/.=-]+/gi;
456
+ const SENSITIVE =
457
+ /\b(authorization|cookie|set-cookie|x-api-key|api[-_]?key|app[-_]?key|app[-_]?token|token|secret|password)(["']?\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;&]+)/gi;
458
+
459
+ /** Removes query strings, credentials and cookie/token values from text before it's sent. */
460
+ function scrubText(text: string): string {
461
+ return text
462
+ .replace(QUERY, "$1?[redacted]")
463
+ .replace(CREDENTIAL, "$1 [redacted]")
464
+ .replace(SENSITIVE, "$1$2[redacted]")
465
+ .slice(0, 1_000);
466
+ }
467
+
468
+ export function newTraceId(): string {
469
+ return randomHex(16);
470
+ }
471
+
472
+ export function describe(error: unknown): string {
473
+ if (error instanceof Error) return `${error.name}: ${error.message}`;
474
+ try {
475
+ return String(error);
476
+ } catch {
477
+ return "unknown error";
478
+ }
479
+ }
480
+
481
+ function randomHex(bytes: number): string {
482
+ const values = crypto.getRandomValues(new Uint8Array(bytes));
483
+ return Array.from(values, (b) => b.toString(16).padStart(2, "0")).join("");
484
+ }
485
+
486
+ function rate(value: unknown, fallback: number): number {
487
+ return typeof value === "number" && Number.isFinite(value)
488
+ ? Math.min(1, Math.max(0, value))
489
+ : fallback;
490
+ }
491
+
492
+ /** `k1=v1,k2=v2` with URL-encoded values, the format of the OTEL_* environment variables. */
493
+ function parseKeyValues(raw: string | undefined): Record<string, string> {
494
+ const out: Record<string, string> = {};
495
+ for (const pair of raw?.split(",") ?? []) {
496
+ const at = pair.indexOf("=");
497
+ if (at <= 0) continue;
498
+ try {
499
+ out[decodeURIComponent(pair.slice(0, at).trim())] = decodeURIComponent(
500
+ pair.slice(at + 1).trim(),
501
+ );
502
+ } catch {
503
+ // A malformed pair is skipped.
504
+ }
505
+ }
506
+ return out;
507
+ }
508
+
509
+ function encodeAttributes(attributes: Attributes, scrub: (text: string) => string) {
510
+ return Object.entries(attributes)
511
+ .filter(([, value]) => value !== undefined)
512
+ .map(([key, value]) => ({
513
+ key,
514
+ value:
515
+ typeof value === "string"
516
+ ? { stringValue: scrub(value) }
517
+ : typeof value === "boolean"
518
+ ? { boolValue: value }
519
+ : Number.isInteger(value)
520
+ ? { intValue: String(value) }
521
+ : { doubleValue: value },
522
+ }));
523
+ }
524
+
525
+ function nanos(ms: number): string {
526
+ return `${Math.round(ms)}000000`;
527
+ }
528
+
529
+ async function gzip(text: string): Promise<{ body: BodyInit; gzipped: boolean }> {
530
+ if (typeof CompressionStream !== "function") return { body: text, gzipped: false };
531
+ const stream = new Blob([text]).stream().pipeThrough(new CompressionStream("gzip"));
532
+ return { body: new Uint8Array(await new Response(stream).arrayBuffer()), gzipped: true };
533
+ }