@decocms/start 2.28.2 → 2.29.0

package/src/sdk/otelAdapters.test.ts

@@ -0,0 +1,135 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createAnalyticsEngineMeterAdapter,
+  createOtelLoggerAdapter,
+  createOtelMeterAdapter,
+  setRuntimeEnv,
+} from "./otelAdapters";
+import { RequestContext } from "./requestContext";
+
+describe("createOtelLoggerAdapter / createOtelMeterAdapter", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("returns null when no endpoint is provided (no-op safe)", () => {
+    expect(createOtelLoggerAdapter(null)).toBeNull();
+    expect(createOtelLoggerAdapter({ endpoint: "" })).toBeNull();
+    expect(createOtelMeterAdapter(null)).toBeNull();
+  });
+
+  it("constructs without throwing when an endpoint is provided", () => {
+    // We don't want this test to actually open a network connection.
+    // The exporters lazy-initialize their HTTP client and only POST on
+    // batch flush, so simply constructing must not throw.
+    const log = createOtelLoggerAdapter({
+      endpoint: "https://otel.example.invalid",
+      headers: { authorization: "test" },
+      name: "test-svc",
+    });
+    expect(log).not.toBeNull();
+    expect(typeof log!.log).toBe("function");
+
+    const meter = createOtelMeterAdapter({
+      endpoint: "https://otel.example.invalid",
+      headers: { authorization: "test" },
+      exportIntervalMillis: 60_000,
+      name: "test-svc",
+    });
+    expect(meter).not.toBeNull();
+    expect(typeof meter!.counterInc).toBe("function");
+    expect(typeof meter!.histogramRecord).toBe("function");
+  });
+
+  it("logs without throwing for a variety of attribute shapes", () => {
+    const log = createOtelLoggerAdapter({ endpoint: "https://otel.example.invalid" });
+    expect(log).not.toBeNull();
+    expect(() =>
+      log!.log("info", "ok", {
+        s: "x",
+        n: 1,
+        b: true,
+        arr: [1, "two", true],
+        nested: { a: 1, b: { c: "d" } },
+        nullV: null,
+        undef: undefined,
+        fn: () => {},
+        sym: Symbol("s") as unknown as string,
+      }),
+    ).not.toThrow();
+  });
+});
+
+describe("createAnalyticsEngineMeterAdapter", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("no-ops when binding is missing (does not throw)", () => {
+    const meter = createAnalyticsEngineMeterAdapter({ bindingName: "MISSING" });
+    expect(() => meter.counterInc("foo", 1)).not.toThrow();
+    expect(() => meter.gaugeSet?.("bar", 5)).not.toThrow();
+    expect(() => meter.histogramRecord?.("baz", 100)).not.toThrow();
+  });
+
+  it("writes one data point per call to the resolved binding", () => {
+    const writeDataPoint = vi.fn();
+    const binding = { writeDataPoint };
+
+    const meter = createAnalyticsEngineMeterAdapter({ binding });
+
+    meter.counterInc("http_requests_total", 1, { method: "GET", path: "/", status: 200 });
+    meter.histogramRecord?.("http_request_duration_ms", 150, {
+      method: "GET",
+      path: "/",
+      status: 200,
+    });
+    meter.gaugeSet?.("custom_gauge", 7, { region: "gru" });
+
+    expect(writeDataPoint).toHaveBeenCalledTimes(3);
+
+    // For HTTP request metrics, indexes[0] must be the path.
+    expect(writeDataPoint.mock.calls[0]?.[0].indexes).toEqual(["/"]);
+    expect(writeDataPoint.mock.calls[0]?.[0].doubles).toEqual([1]);
+    expect(writeDataPoint.mock.calls[0]?.[0].blobs?.[0]).toBe("http_requests_total");
+
+    expect(writeDataPoint.mock.calls[1]?.[0].indexes).toEqual(["/"]);
+    expect(writeDataPoint.mock.calls[1]?.[0].doubles).toEqual([150]);
+
+    // Non-HTTP metrics fall back to the metric name as the index.
+    expect(writeDataPoint.mock.calls[2]?.[0].indexes).toEqual(["custom_gauge"]);
+    expect(writeDataPoint.mock.calls[2]?.[0].doubles).toEqual([7]);
+  });
+
+  it("resolves binding via RequestContext when not provided directly", () => {
+    const writeDataPoint = vi.fn();
+    const env = { DECO_METRICS: { writeDataPoint } };
+
+    RequestContext.run(new Request("https://x.example/"), () => {
+      setRuntimeEnv(env);
+      const meter = createAnalyticsEngineMeterAdapter();
+      // Use a known HTTP metric name so path is promoted to index[0].
+      meter.counterInc("http_requests_total", 1, { path: "/x" });
+      expect(writeDataPoint).toHaveBeenCalledOnce();
+      expect(writeDataPoint.mock.calls[0]?.[0].indexes).toEqual(["/x"]);
+    });
+  });
+
+  it("never throws when binding throws", () => {
+    const binding = {
+      writeDataPoint: () => {
+        throw new Error("AE down");
+      },
+    };
+    const meter = createAnalyticsEngineMeterAdapter({ binding });
+    expect(() => meter.counterInc("x", 1)).not.toThrow();
+  });
+
+  it("orders blob columns deterministically by sorted label keys", () => {
+    const writeDataPoint = vi.fn();
+    const binding = { writeDataPoint };
+    const meter = createAnalyticsEngineMeterAdapter({ binding });
+
+    meter.counterInc("metric", 1, { z: "last", a: "first", m: "mid" });
+
+    const blobs = writeDataPoint.mock.calls[0]?.[0].blobs as string[];
+    // blobs[0] is metric name; remaining must follow sorted label-key order: a, m, z
+    expect(blobs).toEqual(["metric", "first", "mid", "last"]);
+  });
+});

package/src/sdk/otelAdapters.ts

@@ -0,0 +1,401 @@
+/**
+ * OpenTelemetry adapter implementations for `@decocms/start`.
+ *
+ * These adapters plug into the framework's existing pluggable interfaces:
+ *  - `LoggerAdapter`  (from `./logger`)        ← OTLP logs
+ *  - `MeterAdapter`   (from `../middleware/observability`) ← OTLP metrics
+ *  - `MeterAdapter`                              ← Cloudflare Workers Analytics Engine
+ *
+ * Mirrors the metrics views and TTLs from `deco-cx/deco`'s
+ * `observability/otel/metrics.ts` so dashboards built against the Fresh
+ * stack keep working after the migration.
+ *
+ * All three adapters are no-op safe: missing env vars / missing AE binding
+ * means the adapter does nothing rather than throwing. The fan-out wrapper
+ * in `./composite` provides additional try/catch isolation.
+ */
+
+import {
+  type Counter,
+  type Histogram,
+  metrics as metricsApi,
+  type ObservableGauge,
+} from "@opentelemetry/api";
+import { type AnyValue, logs as logsApi, SeverityNumber } from "@opentelemetry/api-logs";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import type { Resource } from "@opentelemetry/resources";
+import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
+import {
+  type AggregationOption,
+  AggregationType,
+  InstrumentType,
+  MeterProvider,
+  PeriodicExportingMetricReader,
+  type ViewOptions,
+} from "@opentelemetry/sdk-metrics";
+import type { MeterAdapter } from "../middleware/observability";
+import { MetricNames } from "../middleware/observability";
+import type { LoggerAdapter, LogLevel } from "./logger";
+import { RequestContext } from "./requestContext";
+
+// ---------------------------------------------------------------------------
+// Env / binding access
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-request access to the Cloudflare Worker `env` bag. Stashed by
+ * `instrumentWorker()` at the top of every request via
+ * `RequestContext.setBag("__deco_env", env)`.
+ *
+ * Adapters use this to look up the AE binding (or any future binding-driven
+ * destination) without forcing site code to thread `env` through every
+ * call site.
+ */
+const ENV_BAG_KEY = "__deco_env";
+
+export function setRuntimeEnv(env: Record<string, unknown>): void {
+  RequestContext.setBag(ENV_BAG_KEY, env);
+}
+
+export function getRuntimeEnv(): Record<string, unknown> | undefined {
+  return RequestContext.getBag<Record<string, unknown>>(ENV_BAG_KEY);
+}
+
+// ---------------------------------------------------------------------------
+// OtelLoggerAdapter
+// ---------------------------------------------------------------------------
+
+const SEVERITY: Record<LogLevel, { number: SeverityNumber; text: string }> = {
+  debug: { number: SeverityNumber.DEBUG, text: "DEBUG" },
+  info: { number: SeverityNumber.INFO, text: "INFO" },
+  warn: { number: SeverityNumber.WARN, text: "WARN" },
+  error: { number: SeverityNumber.ERROR, text: "ERROR" },
+};
+
+export interface OtelLoggerAdapterOptions {
+  endpoint: string;
+  headers?: Record<string, string>;
+  resource?: Resource;
+  /** OTel logger name. Defaults to "@decocms/start". */
+  name?: string;
+}
+
+/**
+ * Streams `logger.*` calls to an OTLP/HTTP logs endpoint (e.g. HyperDX).
+ *
+ * Returns `null` when no endpoint is configured — `instrumentWorker()`
+ * uses that signal to skip registering this adapter.
+ */
+export function createOtelLoggerAdapter(
+  options: OtelLoggerAdapterOptions | null,
+): LoggerAdapter | null {
+  if (!options || !options.endpoint) return null;
+
+  const exporter = new OTLPLogExporter({
+    url: joinPath(options.endpoint, "/v1/logs"),
+    headers: options.headers,
+  });
+
+  const provider = new LoggerProvider({
+    resource: options.resource,
+  });
+  provider.addLogRecordProcessor(new BatchLogRecordProcessor(exporter));
+
+  // Register globally so `@opentelemetry/api-logs` consumers (if any)
+  // also pick it up. Idempotent — safe across multiple worker reloads.
+  try {
+    logsApi.setGlobalLoggerProvider(provider);
+  } catch {
+    /* already set */
+  }
+
+  const otelLogger = provider.getLogger(options.name ?? "@decocms/start");
+
+  return {
+    log(level, msg, attrs) {
+      const sev = SEVERITY[level];
+      otelLogger.emit({
+        severityNumber: sev.number,
+        severityText: sev.text,
+        body: msg,
+        attributes: attrs ? sanitizeAttributes(attrs) : undefined,
+      });
+    },
+  };
+}
+
+/**
+ * Coerce an arbitrary `Record<string, unknown>` into the strict `AnyValueMap`
+ * the OTel logs API expects. Drops anything that can't be safely
+ * represented (functions, symbols, circular structures via stringify guard).
+ */
+function sanitizeAttributes(attrs: Record<string, unknown>): Record<string, AnyValue> {
+  const out: Record<string, AnyValue> = {};
+  for (const [k, v] of Object.entries(attrs)) {
+    out[k] = toAnyValue(v);
+  }
+  return out;
+}
+
+function toAnyValue(v: unknown): AnyValue {
+  if (v === null || v === undefined) return undefined;
+  if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
+  if (v instanceof Uint8Array) return v;
+  if (Array.isArray(v)) return v.map(toAnyValue);
+  if (typeof v === "object") {
+    const out: Record<string, AnyValue> = {};
+    for (const [k, vv] of Object.entries(v as Record<string, unknown>)) {
+      out[k] = toAnyValue(vv);
+    }
+    return out;
+  }
+  // Functions, symbols, bigint — stringify so the operator still sees something.
+  try {
+    return String(v);
+  } catch {
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// OtelMeterAdapter
+// ---------------------------------------------------------------------------
+
+/**
+ * Histogram bucket boundaries for millisecond timings.
+ * Mirrors `deco-cx/deco/observability/otel/metrics.ts` so HyperDX
+ * panels built off the Fresh stack keep working unchanged.
+ */
+const MS_BOUNDARIES = [10, 100, 500, 1000, 5000, 10000, 15000];
+/** Histogram bucket boundaries for second timings. */
+const SECONDS_BOUNDARIES = [1, 5, 10, 50];
+
+export interface OtelMeterAdapterOptions {
+  endpoint: string;
+  headers?: Record<string, string>;
+  resource?: Resource;
+  /** Push interval in ms. Defaults to env.OTEL_EXPORT_INTERVAL or 60_000. */
+  exportIntervalMillis?: number;
+  /** OTel meter name. Defaults to "@decocms/start". */
+  name?: string;
+}
+
+/**
+ * Streams metric writes to an OTLP/HTTP metrics endpoint with a
+ * `PeriodicExportingMetricReader`.
+ *
+ * Two histogram views are pre-registered:
+ *  - any metric ending with `_ms` → millisecond bucket boundaries
+ *  - any metric ending with `_s`  → second bucket boundaries
+ *
+ * Returns `null` when no endpoint is configured.
+ */
+export function createOtelMeterAdapter(
+  options: OtelMeterAdapterOptions | null,
+): MeterAdapter | null {
+  if (!options || !options.endpoint) return null;
+
+  const exporter = new OTLPMetricExporter({
+    url: joinPath(options.endpoint, "/v1/metrics"),
+    headers: options.headers,
+  });
+
+  const reader = new PeriodicExportingMetricReader({
+    exporter,
+    exportIntervalMillis: options.exportIntervalMillis ?? 60_000,
+  });
+
+  const histogramAggregation = (boundaries: number[]): AggregationOption => ({
+    type: AggregationType.EXPLICIT_BUCKET_HISTOGRAM,
+    options: { boundaries, recordMinMax: true },
+  });
+
+  const views: ViewOptions[] = [
+    {
+      instrumentName: "*_ms",
+      instrumentType: InstrumentType.HISTOGRAM,
+      aggregation: histogramAggregation(MS_BOUNDARIES),
+    },
+    {
+      instrumentName: "*_s",
+      instrumentType: InstrumentType.HISTOGRAM,
+      aggregation: histogramAggregation(SECONDS_BOUNDARIES),
+    },
+  ];
+
+  const provider = new MeterProvider({
+    resource: options.resource,
+    readers: [reader],
+    views,
+  });
+
+  try {
+    metricsApi.setGlobalMeterProvider(provider);
+  } catch {
+    /* already set */
+  }
+
+  const meter = provider.getMeter(options.name ?? "@decocms/start");
+
+  // Lazy-create instruments by name so we don't pay the create cost on
+  // every recordRequestMetric / recordCacheMetric invocation.
+  const counters = new Map<string, Counter>();
+  const histograms = new Map<string, Histogram>();
+  const gauges = new Map<string, ObservableGauge>();
+  const gaugeValues = new Map<string, { value: number; labels?: Record<string, unknown> }>();
+
+  function getCounter(name: string): Counter {
+    let c = counters.get(name);
+    if (!c) {
+      c = meter.createCounter(name);
+      counters.set(name, c);
+    }
+    return c;
+  }
+  function getHistogram(name: string): Histogram {
+    let h = histograms.get(name);
+    if (!h) {
+      h = meter.createHistogram(name);
+      histograms.set(name, h);
+    }
+    return h;
+  }
+  function ensureGauge(name: string): void {
+    if (gauges.has(name)) return;
+    const g = meter.createObservableGauge(name);
+    g.addCallback((result) => {
+      const last = gaugeValues.get(name);
+      if (last)
+        result.observe(last.value, last.labels as Record<string, string | number | boolean>);
+    });
+    gauges.set(name, g);
+  }
+
+  return {
+    counterInc(name, value, labels) {
+      getCounter(name).add(value ?? 1, labels);
+    },
+    histogramRecord(name, value, labels) {
+      getHistogram(name).record(value, labels);
+    },
+    gaugeSet(name, value, labels) {
+      ensureGauge(name);
+      gaugeValues.set(name, { value, labels });
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// AnalyticsEngineMeterAdapter
+// ---------------------------------------------------------------------------
+
+/**
+ * Workers Analytics Engine binding shape. Defined here so we don't need
+ * `@cloudflare/workers-types` as a dep.
+ */
+interface AnalyticsEngineDataset {
+  writeDataPoint(point: { indexes?: string[]; blobs?: string[]; doubles?: number[] }): void;
+}
+
+export interface AnalyticsEngineMeterAdapterOptions {
+  /** Env var name holding the AE binding. Defaults to "DECO_METRICS". */
+  bindingName?: string;
+  /** Pre-resolved binding (mainly for tests). Bypasses RequestContext lookup. */
+  binding?: AnalyticsEngineDataset;
+}
+
+/**
+ * Writes one Analytics Engine data point per metric call.
+ *
+ * Schema (must stay stable — dashboards and SQL queries depend on it):
+ *  - `indexes[0]`: a low-cardinality dimension. For request metrics that's
+ *    the normalized URL path; for cache/resolve metrics that's the metric
+ *    name itself.
+ *  - `blobs[0]`: metric name (so a single dataset can hold many metrics).
+ *  - `blobs[1..]`: stringified label values, in stable label-name order.
+ *  - `doubles[0]`: the metric value (count, ms, gauge value).
+ *
+ * AE truncates / charges per data point, so this adapter is intentionally
+ * coarse: one point per `counterInc` / `histogramRecord` / `gaugeSet`.
+ */
+export function createAnalyticsEngineMeterAdapter(
+  options: AnalyticsEngineMeterAdapterOptions = {},
+): MeterAdapter {
+  const bindingName = options.bindingName ?? "DECO_METRICS";
+
+  function resolveBinding(): AnalyticsEngineDataset | null {
+    if (options.binding) return options.binding;
+    const env = getRuntimeEnv();
+    const b = env?.[bindingName] as AnalyticsEngineDataset | undefined;
+    return b ?? null;
+  }
+
+  function write(name: string, value: number, labels?: Record<string, unknown>): void {
+    const binding = resolveBinding();
+    if (!binding) return; // No-op when binding is missing — never throw.
+
+    const indexValue = pickIndex(name, labels);
+    const blobs: string[] = [name];
+    if (labels) {
+      // Stable order — sort keys so the same blob index always means the
+      // same label across requests. AE has no schema; we enforce one here.
+      const keys = Object.keys(labels).sort();
+      for (const k of keys) {
+        const v = labels[k];
+        if (v !== undefined && v !== null) blobs.push(String(v));
+      }
+    }
+
+    try {
+      binding.writeDataPoint({
+        indexes: indexValue ? [indexValue] : undefined,
+        blobs,
+        doubles: [value],
+      });
+    } catch {
+      /* AE write failed — never fail the request */
+    }
+  }
+
+  return {
+    counterInc(name, value, labels) {
+      write(name, value ?? 1, labels);
+    },
+    histogramRecord(name, value, labels) {
+      write(name, value, labels);
+    },
+    gaugeSet(name, value, labels) {
+      write(name, value, labels);
+    },
+  };
+}
+
+function pickIndex(metricName: string, labels?: Record<string, unknown>): string | undefined {
+  if (!labels) return metricName;
+  // For HTTP request metrics the natural index is the path (matches the
+  // plan: `indexes[0]=path`). For other metrics, fall back to the metric
+  // name so the dataset is always queryable by index.
+  if (
+    metricName === MetricNames.HTTP_REQUESTS_TOTAL ||
+    metricName === MetricNames.HTTP_REQUEST_DURATION_MS ||
+    metricName === MetricNames.HTTP_REQUEST_ERRORS
+  ) {
+    const p = labels.path;
+    if (typeof p === "string" && p.length > 0) return p;
+  }
+  return metricName;
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+function joinPath(base: string, path: string): string {
+  if (!base) return path;
+  if (base.endsWith("/")) base = base.slice(0, -1);
+  if (!path.startsWith("/")) path = "/" + path;
+  // Already includes the path? Don't double-append.
+  if (base.toLowerCase().endsWith(path.toLowerCase())) return base;
+  return base + path;
+}

package/src/sdk/sampler.test.ts

@@ -0,0 +1,127 @@
+import { ROOT_CONTEXT, SpanKind } from "@opentelemetry/api";
+import {
+  AlwaysOnSampler,
+  ParentBasedSampler,
+  SamplingDecision,
+} from "@opentelemetry/sdk-trace-base";
+import { describe, expect, it } from "vitest";
+import { createUrlBasedHeadSampler, decodeSamplingConfig, URLBasedSampler } from "./sampler";
+
+const TRACE_ID = "0000000000000000ffffffffffffffff";
+
+function decide(sampler: URLBasedSampler, path: string) {
+  return sampler.shouldSample(
+    ROOT_CONTEXT,
+    TRACE_ID,
+    "span-name",
+    SpanKind.SERVER,
+    { "url.path": path },
+    [],
+  );
+}
+
+describe("URLBasedSampler", () => {
+  it("falls back to default ratio when no rule matches", () => {
+    const s = new URLBasedSampler({ default: 1.0 });
+    expect(decide(s, "/anything").decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+  });
+
+  it("first matching rule wins", () => {
+    const s = new URLBasedSampler({
+      default: 1.0,
+      rules: [
+        { pattern: "^/api/health", ratio: 0.0 },
+        { pattern: "^/api/", ratio: 1.0 },
+      ],
+    });
+    expect(decide(s, "/api/health").decision).toBe(SamplingDecision.NOT_RECORD);
+    expect(decide(s, "/api/orders").decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+  });
+
+  it("falls back to default when no path attribute is present", () => {
+    const s = new URLBasedSampler({ default: 1.0 });
+    const result = s.shouldSample(ROOT_CONTEXT, TRACE_ID, "noop", SpanKind.INTERNAL, {}, []);
+    expect(result.decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+  });
+
+  it("supports url.path, http.target, and http.url", () => {
+    const s = new URLBasedSampler({
+      default: 0.0,
+      rules: [{ pattern: "^/wanted", ratio: 1.0 }],
+    });
+    const ok = (attrs: Record<string, string>) =>
+      s.shouldSample(ROOT_CONTEXT, TRACE_ID, "n", SpanKind.SERVER, attrs, []);
+
+    expect(ok({ "url.path": "/wanted/x" }).decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+    expect(ok({ "http.target": "/wanted/y" }).decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+    expect(ok({ "http.url": "https://h.example/wanted/z?q=1" }).decision).toBe(
+      SamplingDecision.RECORD_AND_SAMPLED,
+    );
+  });
+});
+
+describe("decodeSamplingConfig", () => {
+  it("returns null on missing input", () => {
+    expect(decodeSamplingConfig(undefined)).toBeNull();
+    expect(decodeSamplingConfig("")).toBeNull();
+  });
+
+  it("decodes valid base64 JSON", () => {
+    const cfg = { default: 0.5, rules: [{ pattern: "^/x", ratio: 1.0 }] };
+    const enc = btoa(JSON.stringify(cfg));
+    const decoded = decodeSamplingConfig(enc);
+    expect(decoded).toEqual(cfg);
+  });
+
+  it("drops invalid rules but keeps the rest", () => {
+    const enc = btoa(
+      JSON.stringify({
+        default: 0.1,
+        rules: [
+          { pattern: "^/ok", ratio: 1.0 },
+          { pattern: "^[", ratio: 1.0 }, // invalid regex
+          { pattern: "^/yes", ratio: 0.5 },
+          { pattern: 7, ratio: 0.5 }, // wrong type
+        ],
+      }),
+    );
+    const decoded = decodeSamplingConfig(enc);
+    expect(decoded?.rules).toEqual([
+      { pattern: "^/ok", ratio: 1.0 },
+      { pattern: "^/yes", ratio: 0.5 },
+    ]);
+  });
+
+  it("returns null for non-JSON input", () => {
+    expect(decodeSamplingConfig("not-base64-not-json!!")).toBeNull();
+  });
+});
+
+describe("createUrlBasedHeadSampler", () => {
+  it("wraps the URL-based sampler in ParentBasedSampler", () => {
+    const sampler = createUrlBasedHeadSampler(null);
+    expect(sampler).toBeInstanceOf(ParentBasedSampler);
+  });
+
+  it("applies the default-ratio = 1.0 when config is null", () => {
+    // Smoke test only — sampler internals are validated above.
+    const sampler = createUrlBasedHeadSampler(null);
+    const result = sampler.shouldSample(
+      ROOT_CONTEXT,
+      TRACE_ID,
+      "n",
+      SpanKind.SERVER,
+      { "url.path": "/" },
+      [],
+    );
+    expect(result.decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+  });
+});
+
+describe("regression: AlwaysOnSampler still works", () => {
+  it("guards against accidental import-rename breakage", () => {
+    // If sdk-trace-base ever renames AlwaysOnSampler we want a loud failure.
+    const s = new AlwaysOnSampler();
+    expect(s.shouldSample().decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+  });
+});