@decocms/blocks 7.0.0

package/src/sdk/http.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import { HttpError, STATUS_CODE, UserAgent } from "./http";
+
+describe("STATUS_CODE", () => {
+  it("exposes common codes with the IANA-canonical names", () => {
+    expect(STATUS_CODE.OK).toBe(200);
+    expect(STATUS_CODE.MovedPermanently).toBe(301);
+    expect(STATUS_CODE.NotFound).toBe(404);
+    expect(STATUS_CODE.TooManyRequests).toBe(429);
+    expect(STATUS_CODE.InternalServerError).toBe(500);
+  });
+
+  it("is readonly at the type level", () => {
+    // @ts-expect-error — assigning into the const map should not type-check.
+    STATUS_CODE.OK = 999;
+    // Even though the assignment is allowed at runtime (frozen-by-convention),
+    // we just want the type to flag it. The value is whatever JS allows.
+    expect(typeof STATUS_CODE.OK).toBe("number");
+  });
+});
+
+describe("UserAgent", () => {
+  it("accepts a string and exposes it via toString", () => {
+    const ua = new UserAgent("Mozilla/5.0 (test)");
+    expect(ua.toString()).toBe("Mozilla/5.0 (test)");
+  });
+
+  it("treats null as an empty UA string", () => {
+    const ua = new UserAgent(null);
+    expect(ua.toString()).toBe("");
+  });
+
+  it("exposes empty browser/os/cpu/device/engine accessors", () => {
+    const ua = new UserAgent("anything");
+    expect(ua.browser).toEqual({});
+    expect(ua.os).toEqual({});
+    expect(ua.cpu).toEqual({});
+    expect(ua.device).toEqual({});
+    expect(ua.engine).toEqual({});
+  });
+});
+
+describe("HttpError", () => {
+  it("captures status and message", () => {
+    const err = new HttpError(404, "Missing");
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("HttpError");
+    expect(err.status).toBe(404);
+    expect(err.message).toBe("Missing");
+  });
+
+  it("defaults the message from the status when not provided", () => {
+    const err = new HttpError(503);
+    expect(err.message).toBe("HTTP 503");
+  });
+
+  it("preserves an optional body payload for downstream handling", () => {
+    const body = { code: "rate_limited" };
+    const err = new HttpError(429, "Too Many Requests", body);
+    expect(err.body).toEqual(body);
+  });
+
+  it("supports `instanceof` discrimination", () => {
+    const err = new HttpError(304);
+    function isNotModified(e: unknown): e is HttpError {
+      return e instanceof HttpError && e.status === 304;
+    }
+    expect(isNotModified(err)).toBe(true);
+    expect(isNotModified(new Error("nope"))).toBe(false);
+  });
+});

package/src/sdk/http.ts

@@ -0,0 +1,124 @@
+/**
+ * HTTP constants and small typed helpers — replaces the parts of Deno's
+ * `@std/http` (other than cookies, which live in `./cookie.ts`) that deco
+ * storefronts touch.
+ *
+ * Currently exposes:
+ *   - `STATUS_CODE` — full IANA status-code map (parity with @std/http).
+ *   - `UserAgent`   — minimal class with the same shape; does not parse
+ *                     the UA string (sites only used `.toString()` and
+ *                     basic browser/os accessors in dev). Replace with a
+ *                     real parser like `ua-parser-js` if you actually
+ *                     depend on the parsed fields.
+ */
+
+export const STATUS_CODE = {
+  Continue: 100,
+  SwitchingProtocols: 101,
+  Processing: 102,
+  EarlyHints: 103,
+  OK: 200,
+  Created: 201,
+  Accepted: 202,
+  NonAuthoritativeInfo: 203,
+  NoContent: 204,
+  ResetContent: 205,
+  PartialContent: 206,
+  MultiStatus: 207,
+  AlreadyReported: 208,
+  IMUsed: 226,
+  MultipleChoices: 300,
+  MovedPermanently: 301,
+  Found: 302,
+  SeeOther: 303,
+  NotModified: 304,
+  UseProxy: 305,
+  TemporaryRedirect: 307,
+  PermanentRedirect: 308,
+  BadRequest: 400,
+  Unauthorized: 401,
+  PaymentRequired: 402,
+  Forbidden: 403,
+  NotFound: 404,
+  MethodNotAllowed: 405,
+  NotAcceptable: 406,
+  ProxyAuthRequired: 407,
+  RequestTimeout: 408,
+  Conflict: 409,
+  Gone: 410,
+  LengthRequired: 411,
+  PreconditionFailed: 412,
+  ContentTooLarge: 413,
+  URITooLong: 414,
+  UnsupportedMediaType: 415,
+  RangeNotSatisfiable: 416,
+  ExpectationFailed: 417,
+  Teapot: 418,
+  MisdirectedRequest: 421,
+  UnprocessableEntity: 422,
+  Locked: 423,
+  FailedDependency: 424,
+  TooEarly: 425,
+  UpgradeRequired: 426,
+  PreconditionRequired: 428,
+  TooManyRequests: 429,
+  RequestHeaderFieldsTooLarge: 431,
+  UnavailableForLegalReasons: 451,
+  InternalServerError: 500,
+  NotImplemented: 501,
+  BadGateway: 502,
+  ServiceUnavailable: 503,
+  GatewayTimeout: 504,
+  HTTPVersionNotSupported: 505,
+  VariantAlsoNegotiates: 506,
+  InsufficientStorage: 507,
+  LoopDetected: 508,
+  NotExtended: 510,
+  NetworkAuthenticationRequired: 511,
+} as const;
+
+export type StatusCode = typeof STATUS_CODE[keyof typeof STATUS_CODE];
+
+/**
+ * Minimal stand-in for Deno's `@std/http`'s `UserAgent`. Captures the raw
+ * UA string and exposes the same field shape; does NOT parse. Replace with
+ * a real parser when you start depending on parsed fields.
+ */
+export class UserAgent {
+  ua: string;
+  browser: { name?: string; version?: string };
+  os: { name?: string; version?: string };
+  device: { vendor?: string; model?: string; type?: string };
+  cpu: { architecture?: string };
+  engine: { name?: string; version?: string };
+
+  constructor(ua: string | null) {
+    this.ua = ua ?? "";
+    this.browser = {};
+    this.os = {};
+    this.device = {};
+    this.cpu = {};
+    this.engine = {};
+  }
+
+  toString(): string {
+    return this.ua;
+  }
+}
+
+/**
+ * Lightweight HTTP error class. Drop-in for the `HttpError` shape that
+ * `deco-cx/apps` exposes — sites use it as `error instanceof HttpError &&
+ * error.status === 304` and similar.
+ */
+export class HttpError extends Error {
+  status: number;
+  body?: unknown;
+
+  constructor(status: number, message?: string, body?: unknown) {
+    super(message ?? `HTTP ${status}`);
+    this.name = "HttpError";
+    this.status = status;
+    this.body = body;
+  }
+}

package/src/sdk/index.ts

@@ -0,0 +1,90 @@
+export { ANALYTICS_SCRIPT, type DataEventParams, gtmScript, useSendEvent } from "./analytics";
+export {
+  type CacheProfileConfig,
+  type CacheProfileName,
+  type CacheProfileOverrides,
+  type CacheTimingWindow,
+  cacheHeaders,
+  detectCacheProfile,
+  type EdgeCacheConfig,
+  edgeCacheConfig,
+  getCacheProfile,
+  type LoaderCacheOptions,
+  loaderCacheOptions,
+  registerCachePattern,
+  routeCacheDefaults,
+  setCacheProfile,
+} from "./cacheHeaders";
+export { clx } from "./clx";
+export { decodeCookie, deleteCookie, getCookie, getServerSideCookie, setCookie } from "./cookie";
+export { buildCSPHeaderValue, type CSPOptions, setCSPHeaders } from "./csp";
+export { djb2, djb2Hex } from "./djb2";
+export { isDevMode } from "./env";
+export {
+  createInstrumentedFetch,
+  type FetchInstrumentationOptions,
+  type FetchMetrics,
+  instrumentFetch,
+} from "./instrumentedFetch";
+export {
+  batchInvoke,
+  createAppInvoke,
+  createInvokeProxy,
+  type InvokeProxy,
+  invoke,
+  invokeQueryOptions,
+  type NestedFromFlat,
+} from "./invoke";
+export { createCacheControlCollector, mergeCacheControl } from "./mergeCacheControl";
+export {
+  getProductionOrigins,
+  normalizeUrlsInObject,
+  registerProductionOrigins,
+} from "./normalizeUrls";
+export {
+  addRedirects,
+  loadRedirects,
+  matchRedirect,
+  parseRedirectsCsv,
+  type Redirect,
+  type RedirectMap,
+  registerRedirectResolveType,
+} from "./redirects";
+export { createServerTimings, type ServerTimings } from "./serverTimings";
+export { type ReactiveSignal, signal } from "./signal";
+export { redactUrl, type RedactUrlOptions } from "./urlRedaction";
+export {
+  canonicalUrl,
+  cleanPathForCacheKey,
+  hasTrackingParams,
+  registerTrackingParam,
+  registerTrackingParams,
+  stripTrackingParams,
+} from "./urlUtils";
+export {
+  checkDesktop,
+  checkMobile,
+  checkTablet,
+  type Device,
+  DeviceContext,
+  DeviceProvider,
+  detectDevice,
+  isMobileUA,
+  MOBILE_RE,
+  TABLET_RE,
+  useDevice,
+} from "./useDevice";
+export { useId } from "./useId";
+export {
+  inlineScript,
+  usePartialSection,
+  useScript,
+  useScriptAsDataURI,
+  useSection,
+} from "./useScript";
+export {
+  isWrappedError,
+  unwrapError,
+  type WrappedError,
+  wrapCaughtErrors,
+} from "./wrapCaughtErrors";

package/src/sdk/inflightTimeout.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it, vi } from "vitest";
+import { DEFAULT_INFLIGHT_TIMEOUT_MS, withInflightTimeout } from "./inflightTimeout";
+
+describe("withInflightTimeout", () => {
+  it("returns the underlying value when work settles in time", async () => {
+    const result = await withInflightTimeout(Promise.resolve(42), "ok-case");
+    expect(result).toBe(42);
+  });
+
+  it("propagates rejection when underlying work rejects in time", async () => {
+    await expect(
+      withInflightTimeout(Promise.reject(new Error("boom")), "reject-case"),
+    ).rejects.toThrow("boom");
+  });
+
+  it("rejects with a timeout error when underlying work never settles", async () => {
+    vi.useFakeTimers();
+    try {
+      const hung = new Promise<number>(() => {});
+      const raced = withInflightTimeout(hung, "hung-case", 1_000);
+      // Swallow the eventual rejection so the runner doesn't see it as unhandled
+      raced.catch(() => {});
+
+      await vi.advanceTimersByTimeAsync(1_500);
+      await expect(raced).rejects.toThrow(/timed out/);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("exports a sane default timeout", () => {
+    expect(DEFAULT_INFLIGHT_TIMEOUT_MS).toBeGreaterThanOrEqual(1_000);
+    expect(DEFAULT_INFLIGHT_TIMEOUT_MS).toBeLessThanOrEqual(60_000);
+  });
+});

package/src/sdk/inflightTimeout.ts

@@ -0,0 +1,53 @@
+/**
+ * Inflight-Promise timeout guard for module-level dedup caches.
+ *
+ * Background: across `@decocms/start` (and `@decocms/apps`) we keep
+ * `Map<string, Promise<...>>` caches at module scope to dedup concurrent
+ * resolutions of the same loader / section / layout block. Entries are
+ * evicted via `.finally()` on the stored Promise.
+ *
+ * The problem: if the wrapped work never settles — e.g. an upstream `fetch()`
+ * hangs because a CDN holds the TCP connection open — the `.finally()` never
+ * runs and the Map entry leaks forever. With
+ * `no_handle_cross_request_promise_resolution: true` on the consumer Worker,
+ * the zombie Promise survives across requests. Every subsequent caller for
+ * the same key `await`s it, pinning request context into memory until
+ * `exceededMemory` terminates the isolate.
+ *
+ * Production observation on a TanStack Start storefront (24h window): 514
+ * hard `exceededMemory` crashes, with CPU time ~0 and wall time in the tens
+ * of minutes — workers sleeping on the dead Promise, not computing.
+ *
+ * Fix: race the stored Promise against a timeout so its terminal state is
+ * guaranteed, which means `.finally()` always runs and the Map slot is
+ * freed. The underlying hung work is abandoned (the CF runtime will GC it
+ * once the request ends).
+ */
+
+/** Default per-entry timeout for inflight dedup caches. */
+export const DEFAULT_INFLIGHT_TIMEOUT_MS = 10_000;
+
+/**
+ * Race `work` against a timeout. If `work` doesn't settle within `ms`, the
+ * returned Promise rejects with a descriptive error so callers' `.finally()`
+ * cleanup always runs.
+ */
+export function withInflightTimeout<T>(
+  work: Promise<T>,
+  label: string,
+  ms: number = DEFAULT_INFLIGHT_TIMEOUT_MS,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      reject(
+        new Error(
+          `[deco-start] inflight cache entry "${label}" timed out after ${ms}ms`,
+        ),
+      );
+    }, ms);
+  });
+  return Promise.race([work, timeout]).finally(() => {
+    if (timer !== undefined) clearTimeout(timer);
+  });
+}