@decocms/blocks 7.37.1 → 7.37.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.37.1",
+  "version": "7.37.3",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -55,6 +55,7 @@
     "./sdk/encoding": "./src/sdk/encoding.ts",
     "./sdk/env": "./src/sdk/env.ts",
     "./sdk/fetchCache": "./src/sdk/fetchCache.ts",
+    "./sdk/fetchTimeout": "./src/sdk/fetchTimeout.ts",
     "./sdk/flags": "./src/sdk/flags.ts",
     "./sdk/http": "./src/sdk/http.ts",
     "./sdk/instrumentedFetch": "./src/sdk/instrumentedFetch.ts",

package/src/middleware/observability.test.ts

@@ -7,6 +7,7 @@
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import {
   configureMeter,
+  normalizePath,
   type MeterAdapter,
   MetricNames,
   recordCacheMetric,
@@ -256,3 +257,37 @@ describe("recordCommerceMetric (D-11)", () => {
     ).not.toThrow();
   });
 });
+
+/**
+ * `http.route` is the highest-cardinality risk on the highest-volume metric.
+ * These cases are the real paths measured on production when the label reached
+ * 20,714 distinct values across 6 tenants.
+ */
+describe("normalizePath cardinality", () => {
+  it("collapses CMS content slugs", () => {
+    expect(normalizePath("/mochila-de-couro")).toBe("/:slug");
+    expect(normalizePath("/moveis/quarto-infantil")).toBe("/moveis/:slug");
+    expect(normalizePath("/granado/eau-de-toilette-spritz-100ml")).toBe("/granado/:slug");
+    expect(normalizePath("/moveis/quarto-adulto/cabeceiras-mesa-de-cabeceiras")).toBe(
+      "/moveis/:slug/:slug",
+    );
+  });
+
+  it("leaves bounded framework and API routes intact", () => {
+    expect(normalizePath("/")).toBe("/");
+    expect(normalizePath("/api/sessions")).toBe("/api/sessions");
+    expect(normalizePath("/deco/invoke/magento/loaders/features")).toBe(
+      "/deco/invoke/magento/loaders/features",
+    );
+  });
+
+  it("keeps dotfile segments readable", () => {
+    expect(normalizePath("/.well-known/passkey-endpoints")).toBe("/.well-known/:slug");
+  });
+
+  it("still collapses ids and product pages", () => {
+    expect(normalizePath("/produto/12345")).toBe("/produto/:id");
+    expect(normalizePath("/a/deadbeefcafe")).toBe("/a/:id");
+    expect(normalizePath("/some-product/p")).toBe("/:slug/p");
+  });
+});

package/src/middleware/observability.ts

@@ -611,10 +611,33 @@ export function recordLoaderError(name: string) {
  */
 export function normalizePath(path: string): string {
   // Collapse dynamic segments to reduce cardinality
-  return path
+  const collapsed = path
     .replace(/\/[0-9a-f]{8,}/gi, "/:id")
     .replace(/\/\d+/g, "/:id")
     .replace(/\/[^/]+\/p$/, "/:slug/p");
+
+  // Content slugs are the case none of the rules above catch: they carry no
+  // digits, no hex id and no `/p` suffix, so a CMS page passes through as its
+  // own literal path and becomes its own series.
+  //
+  //   /mochila-de-couro
+  //   /moveis/quarto-infantil
+  //   /granado/eau-de-toilette-spritz-100ml
+  //
+  // Measured on the production ClickHouse, `http.route` reached 20,714
+  // distinct values across only 6 tenants — on `http.server.request.duration`,
+  // the highest-volume metric in the pipeline (19M rows / 3h).
+  //
+  // A hyphen is the discriminator. CMS slugs are hyphenated by construction,
+  // while framework and API segments are single words (`api`, `sessions`,
+  // `deco`, `invoke`, `loaders`, `render`). Dotfile segments such as
+  // `.well-known` are excluded so they keep their meaning.
+  return collapsed
+    .split("/")
+    .map((segment) =>
+      segment.includes("-") && !segment.startsWith(".") ? ":slug" : segment,
+    )
+    .join("/");
 }
 
 // ---------------------------------------------------------------------------

package/src/sdk/fetchTimeout.ts

@@ -0,0 +1,58 @@
+/**
+ * Default network-level timeout for outbound `fetch()` calls.
+ *
+ * Background: nothing in `@decocms/blocks` previously bounded how long an
+ * outbound fetch could hang. `withInflightTimeout` (see `./inflightTimeout.ts`)
+ * only frees the module-level dedup Map slot when a wrapped Promise never
+ * settles — it abandons the underlying fetch rather than aborting it, so the
+ * TCP connection (and the isolate memory pinned to it) stays alive until the
+ * runtime kills the request. This module fixes the root cause: actually abort
+ * the request via `AbortSignal.timeout`, composed with any caller-supplied
+ * signal so callers that already do their own cancellation aren't overridden.
+ */
+
+/** Default per-request timeout for outbound fetch calls. */
+export const DEFAULT_FETCH_TIMEOUT_MS = 10_000;
+
+/**
+ * Named alias for `typeof fetch`. Prefer this over repeating `typeof fetch`
+ * in signatures — packages that ban the bare `fetch` global (see this
+ * monorepo's `biome.json` `noRestrictedGlobals` override) flag `typeof fetch`
+ * too, since it's the same identifier reference; `FetchFn` sidesteps that.
+ */
+export type FetchFn = typeof fetch;
+
+/**
+ * Combine a caller-supplied `AbortSignal` (if any) with a timeout signal, so
+ * neither cancellation source is lost. Pass `timeoutMs <= 0` or
+ * non-finite to opt out of the timeout entirely (e.g. long-lived streaming
+ * requests) while still honoring the caller's own signal.
+ */
+export function withTimeoutSignal(
+  signal: AbortSignal | undefined | null,
+  timeoutMs: number,
+): AbortSignal | undefined {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return signal ?? undefined;
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  return signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+}
+
+/**
+ * Wrap a `fetch` implementation so every call is aborted after `timeoutMs`
+ * unless it settles first. Use directly at ad-hoc fetch call sites that
+ * don't go through `createInstrumentedFetch` (e.g. one-off API clients).
+ *
+ * When `baseFetch` is omitted, `globalThis.fetch` is resolved on every call
+ * (not captured once at wrap time) so tests that swap `globalThis.fetch`
+ * with a mock after this module loads still get intercepted.
+ */
+export function withFetchTimeout(
+  baseFetch?: typeof fetch,
+  timeoutMs: number = DEFAULT_FETCH_TIMEOUT_MS,
+): typeof fetch {
+  return (input, init) =>
+    (baseFetch ?? globalThis.fetch)(input, {
+      ...init,
+      signal: withTimeoutSignal(init?.signal, timeoutMs),
+    });
+}

package/src/sdk/index.ts

@@ -20,6 +20,12 @@ export { decodeCookie, deleteCookie, getCookie, getServerSideCookie, setCookie }
 export { buildCSPHeaderValue, type CSPOptions, setCSPHeaders } from "./csp";
 export { djb2, djb2Hex } from "./djb2";
 export { isDevMode } from "./env";
+export {
+  DEFAULT_FETCH_TIMEOUT_MS,
+  type FetchFn,
+  withFetchTimeout,
+  withTimeoutSignal,
+} from "./fetchTimeout";
 export {
   createInstrumentedFetch,
   type FetchInstrumentationOptions,

package/src/sdk/instrumentedFetch.ts

@@ -15,6 +15,7 @@
  * ```
  */
 
+import { DEFAULT_FETCH_TIMEOUT_MS, withTimeoutSignal } from "./fetchTimeout";
 import { logger } from "./logger";
 import { getTracer, injectTraceContext } from "./observability";
 import { redactUrl } from "./urlRedaction";
@@ -87,6 +88,15 @@ export interface FetchInstrumentationOptions {
    *   `init.operation` ?? `defaultOperation` ?? `resolveOperation(url, method)` ?? `"fetch"`
    */
   resolveOperation?: (url: string, method: string) => string | undefined;
+  /**
+   * Abort a request after this many ms unless it settles first, via
+   * `AbortSignal.timeout` composed with any signal the caller already
+   * passed in `init.signal`. Default: {@link DEFAULT_FETCH_TIMEOUT_MS}
+   * (10s). Pass `0` or `Infinity` to disable for this integration (e.g. a
+   * client that intentionally makes long-lived/streaming requests).
+   * Override per-call via `init.timeoutMs`.
+   */
+  timeoutMs?: number;
 }
 
 export interface FetchMetrics {
@@ -115,6 +125,12 @@ export type InstrumentedFetchInit = RequestInit & {
    * surfaces to the network as a request property.
    */
   operation?: string;
+  /**
+   * Per-call timeout override (ms). See
+   * {@link FetchInstrumentationOptions.timeoutMs}. Stripped from the init
+   * before reaching `baseFetch`.
+   */
+  timeoutMs?: number;
 };
 
 /**
@@ -149,6 +165,7 @@ export function createInstrumentedFetch(
     injectTraceparent = true,
     defaultOperation,
     resolveOperation,
+    timeoutMs = DEFAULT_FETCH_TIMEOUT_MS,
   } = options;
 
   return async (input: RequestInfo | URL, init?: InstrumentedFetchInit): Promise<Response> => {
@@ -177,9 +194,10 @@ export function createInstrumentedFetch(
     // off init so it never reaches `baseFetch` as an unknown RequestInit
     // property (some runtimes warn / future runtimes might reject).
     const explicitOp = init?.operation;
+    const effectiveTimeoutMs = init?.timeoutMs ?? timeoutMs;
     let initForFetch: RequestInit | undefined = init;
-    if (init && "operation" in init) {
-      const { operation: _drop, ...rest } = init;
+    if (init && ("operation" in init || "timeoutMs" in init)) {
+      const { operation: _drop, timeoutMs: _drop2, ...rest } = init;
       initForFetch = rest;
     }
     const operation =
@@ -218,6 +236,11 @@ export function createInstrumentedFetch(
       finalInit = { ...(initForFetch ?? {}), headers };
     }
 
+    finalInit = {
+      ...(finalInit ?? {}),
+      signal: withTimeoutSignal(finalInit?.signal, effectiveTimeoutMs),
+    };
+
     const doFetch = async (): Promise<Response> => {
       if (logging) {
         console.log(`[${name}] ${method} ${truncateUrl(safeUrl)}`);