@decocms/start 2.28.1 → 2.29.0

package/src/index.ts

@@ -3,4 +3,7 @@ export * from "./admin/index";
 export * from "./cms/index";
 export * from "./hooks/index";
 export * from "./middleware/index";
+// Observability surface — logger + instrumentWorker live behind their own
+// granular imports too (see `@decocms/start/sdk/logger`, `.../observability`).
+export { type Logger, type LogLevel, logger, setLogLevel } from "./sdk/logger";
 export * from "./types/index";

package/src/sdk/cachedLoader.ts

@@ -11,7 +11,8 @@
  * (e.g. "product") which derives timing from the unified profile system.
  */
 
-import { loaderCacheOptions, type CacheProfileName } from "./cacheHeaders";
+import { recordCacheMetric, withTracing } from "../middleware/observability";
+import { type CacheProfileName, loaderCacheOptions } from "./cacheHeaders";
 
 export type CachePolicy = "no-store" | "no-cache" | "stale-while-revalidate";
 
@@ -85,12 +86,7 @@ export function createCachedLoader<TProps, TResult>(
   optionsOrProfile: CachedLoaderOptions | CacheProfileName,
 ): (props: TProps) => Promise<TResult> {
   const resolved = resolveOptions(optionsOrProfile);
-  const {
-    policy,
-    maxAge = DEFAULT_MAX_AGE,
-    staleIfError = 0,
-    keyFn = JSON.stringify,
-  } = resolved;
+  const { policy, maxAge = DEFAULT_MAX_AGE, staleIfError = 0, keyFn = JSON.stringify } = resolved;
 
   const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
   const isDev = env?.DECO_CACHE_DISABLE === "true" || env?.NODE_ENV === "development";
@@ -101,10 +97,20 @@ export function createCachedLoader<TProps, TResult>(
     const cacheKey = `${name}::${keyFn(props)}`;
 
     const inflight = inflightRequests.get(cacheKey);
-    if (inflight) return inflight as Promise<TResult>;
+    if (inflight) {
+      // Treat in-flight dedup as a cache hit — avoided the origin call.
+      recordCacheMetric(true, name);
+      return inflight as Promise<TResult>;
+    }
 
     if (isDev) {
-      const promise = loaderFn(props).finally(() => inflightRequests.delete(cacheKey));
+      // Dev mode: no caching, but still useful to count attempts.
+      recordCacheMetric(false, name);
+      const promise = withTracing(
+        "deco.cachedLoader",
+        () => loaderFn(props).finally(() => inflightRequests.delete(cacheKey)),
+        { "deco.loader": name, "deco.cache.policy": "no-cache-dev" },
+      );
       inflightRequests.set(cacheKey, promise);
       return promise;
     }
@@ -114,13 +120,21 @@ export function createCachedLoader<TProps, TResult>(
     const isStale = entry ? now - entry.createdAt > maxAge : true;
 
     if (policy === "no-cache") {
-      if (entry && !isStale) return entry.value;
+      if (entry && !isStale) {
+        recordCacheMetric(true, name);
+        return entry.value;
+      }
     }
 
     if (policy === "stale-while-revalidate") {
-      if (entry && !isStale) return entry.value;
+      if (entry && !isStale) {
+        recordCacheMetric(true, name);
+        return entry.value;
+      }
 
       if (entry && isStale && !entry.refreshing) {
+        // Stale-while-revalidate hit: serve stale, refresh in background.
+        recordCacheMetric(true, name);
         entry.refreshing = true;
         loaderFn(props)
           .then((result) => {
@@ -141,10 +155,19 @@ export function createCachedLoader<TProps, TResult>(
         return entry.value;
       }
 
-      if (entry) return entry.value;
+      if (entry) {
+        recordCacheMetric(true, name);
+        return entry.value;
+      }
     }
 
-    const promise = loaderFn(props)
+    // Cache miss — emit metric, then run loader inside a span so individual
+    // slow loaders are visible in traces.
+    recordCacheMetric(false, name);
+    const promise = withTracing("deco.cachedLoader", () => loaderFn(props), {
+      "deco.loader": name,
+      "deco.cache.policy": policy,
+    })
       .then((result) => {
         cache.set(cacheKey, {
           value: result,

package/src/sdk/composite.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { MeterAdapter } from "../middleware/observability";
+import { createCompositeLogger, createCompositeMeter } from "./composite";
+import type { LoggerAdapter } from "./logger";
+
+describe("createCompositeLogger", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("fans calls out to every adapter", () => {
+    const aCalls: any[][] = [];
+    const bCalls: any[][] = [];
+    const a: LoggerAdapter = { log: (...args) => void aCalls.push(args) };
+    const b: LoggerAdapter = { log: (...args) => void bCalls.push(args) };
+    const composite = createCompositeLogger([a, b]);
+
+    composite.log("info", "hello", { foo: 1 });
+
+    expect(aCalls).toEqual([["info", "hello", { foo: 1 }]]);
+    expect(bCalls).toEqual([["info", "hello", { foo: 1 }]]);
+  });
+
+  it("filters falsy entries (null/undefined/false)", () => {
+    const calls: any[] = [];
+    const a: LoggerAdapter = { log: (...args) => void calls.push(args) };
+    const composite = createCompositeLogger([null, a, undefined, false]);
+    composite.log("info", "ok");
+    // adapter receives the call with no third arg (undefined is omitted)
+    expect(calls.length).toBe(1);
+    expect(calls[0][0]).toBe("info");
+    expect(calls[0][1]).toBe("ok");
+  });
+
+  it("isolates errors so one bad adapter does not block others", () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const okCalls: any[][] = [];
+    const broken: LoggerAdapter = {
+      log() {
+        throw new Error("boom");
+      },
+    };
+    const ok: LoggerAdapter = { log: (...args) => void okCalls.push(args) };
+    const composite = createCompositeLogger([broken, ok]);
+
+    expect(() => composite.log("error", "still goes through")).not.toThrow();
+    expect(okCalls.length).toBe(1);
+    expect(okCalls[0][0]).toBe("error");
+    expect(okCalls[0][1]).toBe("still goes through");
+    expect(errSpy).toHaveBeenCalled(); // composite reports the failure
+  });
+
+  it("returns the single adapter directly when only one is provided", () => {
+    const a: LoggerAdapter = { log: () => {} };
+    expect(createCompositeLogger([a])).toBe(a);
+  });
+});
+
+describe("createCompositeMeter", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  function recorder() {
+    const counter: any[] = [];
+    const gauge: any[] = [];
+    const histo: any[] = [];
+    const meter: MeterAdapter = {
+      counterInc: (n, v, l) => void counter.push([n, v, l]),
+      gaugeSet: (n, v, l) => void gauge.push([n, v, l]),
+      histogramRecord: (n, v, l) => void histo.push([n, v, l]),
+    };
+    return { meter, counter, gauge, histo };
+  }
+
+  it("fans counter/gauge/histogram across meters", () => {
+    const a = recorder();
+    const b = recorder();
+    const composite = createCompositeMeter([a.meter, b.meter]);
+
+    composite.counterInc("c", 1, { p: "/" });
+    composite.gaugeSet?.("g", 5);
+    composite.histogramRecord?.("h", 100, { route: "/p" });
+
+    expect(a.counter[0].slice(0, 2)).toEqual(["c", 1]);
+    expect(a.counter[0][2]).toEqual({ p: "/" });
+    expect(b.counter[0].slice(0, 2)).toEqual(["c", 1]);
+    expect(a.gauge[0].slice(0, 2)).toEqual(["g", 5]);
+    expect(b.gauge[0].slice(0, 2)).toEqual(["g", 5]);
+    expect(a.histo[0]).toEqual(["h", 100, { route: "/p" }]);
+    expect(b.histo[0]).toEqual(["h", 100, { route: "/p" }]);
+  });
+
+  it("isolates errors per meter and per call type", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const broken: MeterAdapter = {
+      counterInc: () => {
+        throw new Error("c");
+      },
+      gaugeSet: () => {
+        throw new Error("g");
+      },
+      histogramRecord: () => {
+        throw new Error("h");
+      },
+    };
+    const ok = recorder();
+    const composite = createCompositeMeter([broken, ok.meter]);
+
+    composite.counterInc("c", 1);
+    composite.gaugeSet?.("g", 5);
+    composite.histogramRecord?.("h", 100);
+
+    expect(ok.counter[0].slice(0, 2)).toEqual(["c", 1]);
+    expect(ok.gauge[0].slice(0, 2)).toEqual(["g", 5]);
+    expect(ok.histo[0].slice(0, 2)).toEqual(["h", 100]);
+  });
+
+  it("skips meters that don't implement optional ops", () => {
+    const onlyCounter: MeterAdapter = { counterInc: () => {} };
+    const composite = createCompositeMeter([onlyCounter]);
+    expect(() => composite.gaugeSet?.("g", 1)).not.toThrow();
+    expect(() => composite.histogramRecord?.("h", 1)).not.toThrow();
+  });
+});

package/src/sdk/composite.ts

@@ -0,0 +1,114 @@
+/**
+ * Composite adapters — fan out to multiple backends with try/catch isolation.
+ *
+ * Used by `instrumentWorker()` so the same logger/meter can dual-emit to
+ * (e.g.) console-JSON + OTLP, or AE + OTLP, without any one backend's
+ * failure taking down the others.
+ *
+ * The "always include console-JSON logger" guarantee in the observability
+ * plan relies on this: even if HyperDX is down, the local console adapter
+ * still records the line.
+ */
+
+import type { MeterAdapter } from "../middleware/observability";
+import type { LoggerAdapter, LogLevel } from "./logger";
+
+type Labels = Record<string, string | number | boolean>;
+
+// ---------------------------------------------------------------------------
+// Logger
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a single LoggerAdapter that fans every call out to all
+ * provided adapters. Falsy entries (e.g. `otelEnabled ? otelAdapter : null`)
+ * are filtered out so call sites can write:
+ *
+ * ```ts
+ * createCompositeLogger([defaultLoggerAdapter, otelEnabled ? otelLogger : null]);
+ * ```
+ *
+ * Each downstream `.log()` call is isolated in try/catch so a thrown
+ * error in one backend cannot suppress the others.
+ */
+export function createCompositeLogger(
+  adapters: Array<LoggerAdapter | null | undefined | false>,
+): LoggerAdapter {
+  const list = adapters.filter((a): a is LoggerAdapter => Boolean(a));
+
+  if (list.length === 1) return list[0];
+
+  return {
+    log(level: LogLevel, msg: string, attrs?: Record<string, unknown>) {
+      for (const adapter of list) {
+        try {
+          adapter.log(level, msg, attrs);
+        } catch (error) {
+          // Use console.error directly — calling logger here would recurse.
+          try {
+            console.error("[composite-logger] adapter failed", String(error));
+          } catch {
+            /* swallow */
+          }
+        }
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Meter
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a single MeterAdapter that fans counter/gauge/histogram writes
+ * out to all provided meters. Same semantics as `createCompositeLogger`:
+ * falsy entries are dropped, each downstream call is try/catch isolated.
+ */
+export function createCompositeMeter(
+  adapters: Array<MeterAdapter | null | undefined | false>,
+): MeterAdapter {
+  const list = adapters.filter((a): a is MeterAdapter => Boolean(a));
+
+  if (list.length === 1) return list[0];
+
+  return {
+    counterInc(name: string, value?: number, labels?: Labels) {
+      for (const m of list) {
+        try {
+          m.counterInc(name, value, labels);
+        } catch (error) {
+          warn("counterInc", name, error);
+        }
+      }
+    },
+    gaugeSet(name: string, value: number, labels?: Labels) {
+      for (const m of list) {
+        if (!m.gaugeSet) continue;
+        try {
+          m.gaugeSet(name, value, labels);
+        } catch (error) {
+          warn("gaugeSet", name, error);
+        }
+      }
+    },
+    histogramRecord(name: string, value: number, labels?: Labels) {
+      for (const m of list) {
+        if (!m.histogramRecord) continue;
+        try {
+          m.histogramRecord(name, value, labels);
+        } catch (error) {
+          warn("histogramRecord", name, error);
+        }
+      }
+    },
+  };
+}
+
+function warn(op: string, metric: string, error: unknown) {
+  try {
+    console.error(`[composite-meter] ${op}(${metric}) adapter failed`, String(error));
+  } catch {
+    /* swallow */
+  }
+}

package/src/sdk/instrumentedFetch.ts

@@ -16,6 +16,26 @@
  */
 
 import { getTracer } from "../middleware/observability";
+import { logger } from "./logger";
+
+/**
+ * Cloudflare / VTEX response headers that operators want to see as span
+ * attributes when debugging cache behavior. Mirrors `applyCustomAttributesOnSpan`
+ * in `deco-cx/deco/observability/otel/`.
+ */
+const CACHE_HEADERS_TO_SPAN: Array<{ header: string; attr: string }> = [
+  { header: "cf-cache-status", attr: "cf.cache.status" },
+  { header: "cf-ray", attr: "cf.ray" },
+  { header: "x-vtex-io-cluster-id", attr: "vtex.io.cluster.id" },
+  { header: "x-edge-cache-status", attr: "edge.cache.status" },
+];
+
+const TRUE_LITERAL = "true";
+
+function envFlag(name: string): boolean {
+  const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
+  return env?.[name] === TRUE_LITERAL;
+}
 
 export interface FetchInstrumentationOptions {
   /** Tag for log/trace grouping (e.g., "vtex", "shopify"). */
@@ -85,6 +105,32 @@ export function createInstrumentedFetch(
         );
       }
 
+      // Structured outgoing-fetch breadcrumb. Same field shape as the Fresh
+      // `@deco/deco/o11y` impl so log pipelines built off the old stack
+      // keep working unchanged. Off by default to avoid log explosion;
+      // enable with `OTEL_LOG_OUTGOING_FETCH=true`.
+      if (envFlag("OTEL_LOG_OUTGOING_FETCH")) {
+        let host = "";
+        let path = "";
+        try {
+          const u = new URL(url);
+          host = u.host;
+          path = u.pathname;
+        } catch {
+          /* unparseable URL — leave host/path blank */
+        }
+        logger.info("outgoing fetch", {
+          app: name,
+          host,
+          path,
+          method,
+          status: response.status,
+          ok: response.ok,
+          durationMs: Math.round(durationMs),
+          cached,
+        });
+      }
+
       onComplete?.({
         name,
         url,
@@ -108,6 +154,16 @@ export function createInstrumentedFetch(
 
         try {
           const response = await doFetch();
+          // Promote CF / VTEX cache headers as span attributes — the plan
+          // calls out these four. `@microlabs/otel-cf-workers` does not
+          // expose the response inside its own fetch span lifecycle, so
+          // capturing them here on our wrapper span is the practical
+          // place to do it.
+          for (const { header, attr } of CACHE_HEADERS_TO_SPAN) {
+            const value = response.headers.get(header);
+            if (value) span.setAttribute?.(attr, value);
+          }
+          span.setAttribute?.("http.status_code", response.status);
           span.end();
           return response;
         } catch (error) {

package/src/sdk/logger.test.ts

@@ -0,0 +1,135 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  configureLogger,
+  defaultLoggerAdapter,
+  getLoggerAdapter,
+  getLogLevel,
+  type LoggerAdapter,
+  logger,
+  setLogLevel,
+} from "./logger";
+
+describe("defaultLoggerAdapter", () => {
+  let logSpy: ReturnType<typeof vi.spyOn>;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+  let debugSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    debugSpy = vi.spyOn(console, "debug").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    configureLogger(defaultLoggerAdapter);
+    setLogLevel("debug"); // permissive default for the rest of the suite
+  });
+
+  it("emits one JSON line per call", () => {
+    defaultLoggerAdapter.log("info", "hello", { foo: 1 });
+    expect(logSpy).toHaveBeenCalledOnce();
+    const arg = logSpy.mock.calls[0]?.[0] as string;
+    const parsed = JSON.parse(arg);
+    expect(parsed).toMatchObject({ level: "info", msg: "hello", foo: 1 });
+    expect(typeof parsed.timestamp).toBe("string");
+  });
+
+  it("routes by level so CF Logs colorises correctly", () => {
+    defaultLoggerAdapter.log("error", "boom");
+    defaultLoggerAdapter.log("warn", "careful");
+    defaultLoggerAdapter.log("debug", "details");
+    expect(errorSpy).toHaveBeenCalledOnce();
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(debugSpy).toHaveBeenCalledOnce();
+  });
+
+  it("never throws on circular refs (last-resort fallback)", () => {
+    const circ: any = { name: "x" };
+    circ.self = circ;
+    expect(() => defaultLoggerAdapter.log("info", "circ", { circ })).not.toThrow();
+    expect(logSpy).toHaveBeenCalledOnce();
+  });
+
+  it("does not let attrs override level/msg/timestamp keys", () => {
+    defaultLoggerAdapter.log("info", "real-msg", {
+      level: "tampered",
+      msg: "tampered",
+      timestamp: "tampered",
+    });
+    const parsed = JSON.parse(logSpy.mock.calls[0]?.[0] as string);
+    expect(parsed.level).toBe("info");
+    expect(parsed.msg).toBe("real-msg");
+    expect(parsed.timestamp).not.toBe("tampered");
+  });
+});
+
+describe("level filtering", () => {
+  let logSpy: ReturnType<typeof vi.spyOn>;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+  let debugSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    debugSpy = vi.spyOn(console, "debug").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    configureLogger(defaultLoggerAdapter);
+    setLogLevel("info");
+  });
+
+  it("drops calls below the active min level", () => {
+    setLogLevel("warn");
+    expect(getLogLevel()).toBe("warn");
+    logger.debug("d");
+    logger.info("i");
+    logger.warn("w");
+    logger.error("e");
+    expect(debugSpy).not.toHaveBeenCalled();
+    expect(logSpy).not.toHaveBeenCalled(); // info routes to console.log
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(errorSpy).toHaveBeenCalledOnce();
+  });
+});
+
+describe("configureLogger", () => {
+  afterEach(() => {
+    configureLogger(defaultLoggerAdapter);
+    setLogLevel("info");
+  });
+
+  it("dispatches to the configured adapter", () => {
+    const calls: Array<[string, string, unknown]> = [];
+    const test: LoggerAdapter = {
+      log(level, msg, attrs) {
+        calls.push([level, msg, attrs]);
+      },
+    };
+    configureLogger(test);
+    expect(getLoggerAdapter()).toBe(test);
+
+    logger.info("hello", { x: 1 });
+    expect(calls).toEqual([["info", "hello", { x: 1 }]]);
+  });
+
+  it("falls back to default adapter if active adapter throws", () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const broken: LoggerAdapter = {
+      log() {
+        throw new Error("nope");
+      },
+    };
+    configureLogger(broken);
+    expect(() => logger.info("survives", { x: 1 })).not.toThrow();
+    // Default adapter was invoked as the fallback
+    expect(logSpy).toHaveBeenCalledOnce();
+    logSpy.mockRestore();
+  });
+});