@decocms/blocks 7.29.0 → 7.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.29.0",
+  "version": "7.31.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/src/sdk/observability.ts

@@ -78,7 +78,13 @@ export {
   withTracing,
 } from "../middleware/observability";
 // Worker-entry wrapper + adapter wiring
-export { instrumentWorker, type OtelOptions } from "./otel";
+export {
+  bootObservability,
+  flushObservability,
+  instrumentWorker,
+  instrumentWorkflowRun,
+  type OtelOptions,
+} from "./otel";
 // Direct-POST OTLP trace exporter (Phase 3 / D-12). Exported for sites
 // that need to wire a custom traces endpoint outside `instrumentWorker`,
 // and for the audit tooling that asserts framework spans are flowing.

package/src/sdk/otel.test.ts

@@ -14,7 +14,12 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import * as composite from "./composite";
 import * as logger from "./logger";
 import * as observability from "./observability";
-import { _resetBootStateForTests, instrumentWorker } from "./otel";
+import {
+  _resetBootStateForTests,
+  flushObservability,
+  instrumentWorker,
+  instrumentWorkflowRun,
+} from "./otel";
 import * as adapters from "./otelAdapters";
 import { createClickhouseCollectorAdapter } from "./otelAdapters/clickhouseCollector";
 
@@ -524,3 +529,108 @@ describe("instrumentWorker — OTLP/HTTP error-log channel wiring", () => {
     expect(calls).toHaveLength(0);
   });
 });
+
+describe("instrumentWorkflowRun / flushObservability — Workflow entrypoints", () => {
+  beforeEach(() => {
+    _resetBootStateForTests();
+  });
+
+  afterEach(() => {
+    _resetBootStateForTests();
+  });
+
+  it("flushObservability resolves without throwing when no adapters are configured", async () => {
+    await expect(flushObservability()).resolves.toBeUndefined();
+  });
+
+  it("instrumentWorkflowRun returns fn's result and does not throw with no OTel env vars set", async () => {
+    const fn = vi.fn().mockResolvedValue("step-result");
+    const result = await instrumentWorkflowRun({}, undefined, fn);
+
+    expect(result).toBe("step-result");
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  function makeFetchSpy() {
+    const calls: Array<{ url: string; body: string }> = [];
+    const impl = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+      calls.push({ url: String(input), body: String(init?.body ?? "") });
+      return new Response("{}", { status: 200 });
+    });
+    return { impl: impl as unknown as typeof fetch, calls };
+  }
+
+  it("rethrows fn's rejection but still flushes buffered metrics", async () => {
+    const { impl, calls } = makeFetchSpy();
+    const fn = vi.fn(async () => {
+      observability.recordRequestMetric("WORKFLOW", "/batch-product", 500, 9);
+      throw new Error("workflow step failed");
+    });
+    const env = { DECO_OTEL_METRICS_ENDPOINT: "https://ingest.test/v1/metrics" };
+
+    await expect(
+      instrumentWorkflowRun(env, { otlpMetricsFetchImpl: impl }, fn),
+    ).rejects.toThrow("workflow step failed");
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe("https://ingest.test/v1/metrics");
+  });
+
+  it("still flushes when fn throws synchronously instead of returning a rejected promise", async () => {
+    const { impl, calls } = makeFetchSpy();
+    const fn = vi.fn(() => {
+      observability.recordRequestMetric("WORKFLOW", "/batch-product", 500, 9);
+      throw new Error("sync boom");
+    }) as unknown as () => Promise<string>;
+    const env = { DECO_OTEL_METRICS_ENDPOINT: "https://ingest.test/v1/metrics" };
+
+    await expect(
+      instrumentWorkflowRun(env, { otlpMetricsFetchImpl: impl }, fn),
+    ).rejects.toThrow("sync boom");
+
+    expect(calls).toHaveLength(1);
+  });
+
+  it("wires and flushes the OTLP metrics exporter, same as instrumentWorker's channel", async () => {
+    const { impl, calls } = makeFetchSpy();
+    const fn = vi.fn(async () => {
+      observability.recordRequestMetric("WORKFLOW", "/batch-product", 200, 12);
+      return "done";
+    });
+
+    const env = {
+      DECO_OTEL_METRICS_ENDPOINT: "https://ingest.test/v1/metrics",
+    } as unknown as Record<string, unknown>;
+
+    const result = await instrumentWorkflowRun(
+      env,
+      { serviceName: "workflow-smoke", otlpMetricsFetchImpl: impl },
+      fn,
+    );
+
+    expect(result).toBe("done");
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe("https://ingest.test/v1/metrics");
+  });
+
+  it("forces the flush past the per-isolate cooldown across consecutive replay legs", async () => {
+    // Regression test: instrumentWorkflowRun forces its exit-time flush past
+    // the ~5s default cooldown each OTLP adapter otherwise enforces, since a
+    // Workflow run() only gets one flush attempt per leg — no next request
+    // to retry on like a fetch handler has.
+    const { impl, calls } = makeFetchSpy();
+    const env = { DECO_OTEL_METRICS_ENDPOINT: "https://ingest.test/v1/metrics" };
+    const opts = { otlpMetricsFetchImpl: impl };
+
+    await instrumentWorkflowRun(env, opts, async () => {
+      observability.recordRequestMetric("WORKFLOW", "/leg-1", 200, 5);
+    });
+    // A second replay leg immediately after — well within the default
+    // cooldown window — must still flush, not get silently skipped.
+    await instrumentWorkflowRun(env, opts, async () => {
+      observability.recordRequestMetric("WORKFLOW", "/leg-2", 200, 5);
+    });
+
+    expect(calls).toHaveLength(2);
+  });
+});

package/src/sdk/otel.ts

@@ -446,34 +446,98 @@ export function instrumentWorker(
         // ctx.waitUntil so no POST blocks the response. Each exporter
         // throttles itself per isolate — calling on every request is
         // cheap; the network only fires when the cooldown elapses or
-        // the buffer fills.
+        // the buffer fills. Skip the waitUntil call entirely when no
+        // adapter is configured (nothing to flush).
         const state = getBootState();
-        if (state.otlpMeter) {
+        if (state.otlpMeter || state.otlpLog || state.otlpTracer) {
           try {
-            ctx.waitUntil(state.otlpMeter.flush());
+            ctx.waitUntil(flushObservability());
           } catch {
             /* ctx.waitUntil throwing is benign — never block the response */
           }
         }
-        if (state.otlpLog) {
-          try {
-            ctx.waitUntil(state.otlpLog.flush());
-          } catch {
-            /* swallow */
-          }
-        }
-        if (state.otlpTracer) {
-          try {
-            ctx.waitUntil(state.otlpTracer.flush());
-          } catch {
-            /* swallow */
-          }
-        }
       }
     },
   };
 }
 
+/**
+ * Drains the OTLP metrics + error-log + traces buffers (whichever are
+ * configured for this isolate). Extracted out of `instrumentWorker`'s
+ * `finally` block so callers without a `{fetch}`/`ctx.waitUntil` lifecycle —
+ * e.g. Cloudflare Workflow `run()` handlers — can flush explicitly too. See
+ * `instrumentWorkflowRun` below.
+ *
+ * Each adapter's `flush()` is throttled by a per-isolate cooldown (default
+ * 5s) so a busy fetch handler doesn't fire a POST per request — pass
+ * `force: true` to bypass that cooldown for callers that only get one flush
+ * attempt with no next request to retry on (Workflow `run()` exit).
+ */
+export async function flushObservability(force = false): Promise<void> {
+  const state = getBootState();
+  await Promise.allSettled([
+    state.otlpMeter?.flush(force),
+    state.otlpLog?.flush(force),
+    state.otlpTracer?.flush(force),
+  ]);
+}
+
+/**
+ * Boots observability (same env-var-driven wiring `instrumentWorker` uses)
+ * and runs `fn`, flushing on the way out — the Workflow-entrypoint
+ * equivalent of `instrumentWorker`. Cloudflare Workflows have no `{fetch}` /
+ * `ctx.waitUntil` lifecycle, so this awaits the flush directly instead.
+ *
+ * Deliberately does NOT open a root span around `fn()`. Code in a
+ * `WorkflowEntrypoint.run(event, step)` outside `step.do`/`step.sleep`
+ * re-executes on every hibernate/wake replay — a span opened here would get
+ * a fresh random trace ID on every replay leg, producing disconnected
+ * traces instead of one coherent run. Create spans for individual
+ * `step.do(...)` callbacks with `withTracing` instead (each step only truly
+ * runs once, since `step.do` memoizes across replays), tagging them with
+ * `event.instanceId` so a backend can group replay legs under one logical
+ * run.
+ *
+ * The exit-time flush is `force`d (bypasses the per-isolate cooldown other
+ * `flush()` callers respect) — a Workflow `run()` invocation gets exactly
+ * one flush attempt on the way out, unlike a fetch handler where the next
+ * request's `ctx.waitUntil(flush())` can pick up whatever a cooldown-skipped
+ * flush left behind. Without forcing, a workflow with several replay legs in
+ * quick succession could have its final leg's flush silently skipped by the
+ * cooldown, losing that leg's buffered spans/metrics if the isolate is torn
+ * down before the next wake.
+ *
+ * @example
+ * ```ts
+ * async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
+ *   return instrumentWorkflowRun(this.env, undefined, async () => {
+ *     await step.do("fetch-product", () =>
+ *       withTracing("deco.workflow.step", () => fetchProduct(), {
+ *         "workflow.instance_id": event.instanceId,
+ *         "workflow.step": "fetch-product",
+ *       }),
+ *     );
+ *   });
+ * }
+ * ```
+ */
+export async function instrumentWorkflowRun<T>(
+  env: Record<string, unknown>,
+  options: OtelOptions | undefined,
+  fn: () => Promise<T>,
+): Promise<T> {
+  configureTracer(buildOtelApiTracer());
+  bootObservability(options ?? {}, env);
+  try {
+    // Awaiting inside this try (rather than `return fn().finally(...)`)
+    // ensures a synchronous throw from `fn` — not just a rejected promise —
+    // still reaches the `finally` below instead of skipping it.
+    return await fn();
+  } finally {
+    await flushObservability(true);
+  }
+}
+
 /**
  * Build the legacy `@opentelemetry/api` global-tracer bridge. Stays a
  * no-op when no global TracerProvider is registered — same outcome as
@@ -639,7 +703,18 @@ function patchConsole(state: BootState): void {
   console.debug = (...args: unknown[]) => forward("debug", args);
 }
 
-function bootObservability(opts: OtelOptions, env: Record<string, unknown>): void {
+/**
+ * Boots the observability stack for the current isolate: resolves the
+ * `DECO_OTEL` on/off/auto switch, builds the resource-attribute floor
+ * (service name/version/instance, deployment environment, cloud platform),
+ * and — gated per env var — wires the AE meter and OTLP metrics/logs/traces
+ * adapters. Idempotent per isolate (`BootState.booted` guards re-entry).
+ *
+ * Exported so callers with a lifecycle `instrumentWorker` doesn't fit
+ * (Cloudflare Workflows — see `instrumentWorkflowRun`) can boot the same
+ * stack directly.
+ */
+export function bootObservability(opts: OtelOptions, env: Record<string, unknown>): void {
   const state = getBootState();
   if (state.booted) return;
 

package/src/sdk/otelHttpLog.ts

@@ -107,8 +107,8 @@ export interface OtlpHttpLogOptions {
 
 export interface OtlpHttpLog {
   adapter: LoggerAdapter;
-  /** Force a flush, subject to the per-isolate cooldown. */
-  flush(): Promise<void>;
+  /** Flush, subject to the per-isolate cooldown unless `force` is true. */
+  flush(force?: boolean): Promise<void>;
   /** Pending log record count. For tests + audit. */
   pendingRecordCount(): number;
 }
@@ -324,12 +324,12 @@ export function createOtlpHttpLogAdapter(options: OtlpHttpLogOptions): OtlpHttpL
     }
   }
 
-  async function flush(): Promise<void> {
+  async function flush(force = false): Promise<void> {
     if (inflight) return inflight;
 
     const elapsed = now() - lastFlushAt;
     const overCap = buffer.length >= maxBuffer;
-    if (!overCap && elapsed < minFlushIntervalMs) return;
+    if (!force && !overCap && elapsed < minFlushIntervalMs) return;
 
     inflight = doFlush().finally(() => {
       lastFlushAt = now();

package/src/sdk/otelHttpMeter.ts

@@ -93,8 +93,8 @@ export interface OtlpHttpMeter extends MeterAdapter {
   gaugeSet(name: string, value: number, labels?: Labels): void;
   /** Always defined on this adapter — declared required to drop the `?.` at call sites. */
   histogramRecord(name: string, value: number, labels?: Labels): void;
-  /** Force a flush, subject to the per-isolate cooldown. */
-  flush(): Promise<void>;
+  /** Flush, subject to the per-isolate cooldown unless `force` is true. */
+  flush(force?: boolean): Promise<void>;
   /** Pending datapoint count across all metric kinds. For tests + audit. */
   pendingDatapointCount(): number;
 }
@@ -341,7 +341,7 @@ export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpH
     }
   }
 
-  async function flush(): Promise<void> {
+  async function flush(force = false): Promise<void> {
     // If a flush is in flight, reuse it — concurrent requests should not
     // pile up POSTs. The in-flight POST already snapshotted the buffer at
     // its enqueue time; new datapoints land in the buffer and will go out
@@ -350,8 +350,11 @@ export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpH
 
     const elapsed = now() - lastFlushAt;
     const overCap = pendingDatapointCount() >= maxBuffer;
-    if (!overCap && elapsed < minFlushIntervalMs) {
-      // Cooldown not elapsed and buffer is not at the cap — skip.
+    if (!force && !overCap && elapsed < minFlushIntervalMs) {
+      // Cooldown not elapsed and buffer is not at the cap — skip. `force`
+      // bypasses this for callers with no next-request opportunity to
+      // retry the flush (e.g. a Cloudflare Workflow's `run()` exit — see
+      // `instrumentWorkflowRun` in `otel.ts`).
       return;
     }
 

package/src/sdk/otelHttpTracer.ts

@@ -233,8 +233,8 @@ export interface OtlpHttpTracerOptions {
 }
 
 export interface OtlpHttpTracer extends TracerAdapter {
-  /** Drain the buffer (subject to cooldown). */
-  flush(): Promise<void>;
+  /** Drain the buffer, subject to cooldown unless `force` is true. */
+  flush(force?: boolean): Promise<void>;
   /** For tests + the audit channel. */
   pendingSpanCount(): number;
   /**
@@ -433,11 +433,11 @@ export function createOtlpHttpTracerAdapter(options: OtlpHttpTracerOptions): Otl
     }
   }
 
-  async function flush(): Promise<void> {
+  async function flush(force = false): Promise<void> {
     if (inflight) return inflight;
     const elapsed = now() - lastFlushAt;
     const overCap = spans.length >= maxBuffer;
-    if (!overCap && elapsed < minFlushIntervalMs) return;
+    if (!force && !overCap && elapsed < minFlushIntervalMs) return;
     inflight = doFlush().finally(() => {
       lastFlushAt = now();
       inflight = null;