@decocms/start 4.5.0 → 5.0.0

package/src/sdk/workerEntry.ts

@@ -45,6 +45,17 @@ import { getAppMiddleware } from "./setupApps";
 import { cleanPathForCacheKey } from "./urlUtils";
 import { type Device, isMobileUA } from "./useDevice";
 
+/**
+ * Build-time identifier injected by `decoVitePlugin()` (see
+ * `src/vite/plugin.js`). Falls back to `undefined` if the consuming site
+ * isn't using the plugin or the symbol wasn't `define`d at bundle time.
+ *
+ * The runtime `env.BUILD_HASH` (when explicitly set, e.g. via
+ * `wrangler deploy --var BUILD_HASH:foo`) takes precedence — see
+ * `getBuildHash()` below.
+ */
+declare const __DECO_BUILD_HASH__: string | undefined;
+
 /**
  * Append Link preload headers for CSS and fonts so the browser starts
  * fetching them before parsing HTML. Only applied to HTML responses.
@@ -673,6 +684,23 @@ export function createDecoWorkerEntry(
     return parts.join("|");
   }
 
+  /**
+   * Resolve the per-deploy cache-key version with this priority:
+   *   1. `env[cacheVersionEnv]` — explicit override (e.g. `wrangler
+   *      deploy --var BUILD_HASH:foo`). Wins so callers can always
+   *      force a specific value.
+   *   2. `__DECO_BUILD_HASH__` — build-time constant injected by
+   *      `decoVitePlugin()` from WORKERS_CI_COMMIT_SHA / git rev-parse.
+   *      This is the production path on Cloudflare Workers Builds.
+   *   3. Empty string — versioning disabled (legacy pre-plugin sites).
+   */
+  function getBuildHash(env: Record<string, unknown>): string {
+    if (cacheVersionEnv === false) return "";
+    const fromEnv = (env[cacheVersionEnv] as string) || "";
+    if (fromEnv) return fromEnv;
+    return typeof __DECO_BUILD_HASH__ !== "undefined" ? __DECO_BUILD_HASH__ : "";
+  }
+
   function buildCacheKey(
     request: Request,
     env: Record<string, unknown>,
@@ -685,11 +713,9 @@ export function createDecoWorkerEntry(
       url.search = cleanUrl.search;
     }
 
-    if (cacheVersionEnv !== false) {
-      const version = (env[cacheVersionEnv] as string) || "";
-      if (version) {
-        url.searchParams.set("__v", version);
-      }
+    const version = getBuildHash(env);
+    if (version) {
+      url.searchParams.set("__v", version);
     }
 
     // Include CF geo data in cache key so location matcher results don't leak
@@ -791,10 +817,8 @@ export function createDecoWorkerEntry(
         for (const seg of segments) {
           for (const cc of geoKeys) {
             const url = new URL(p, baseUrl);
-            if (cacheVersionEnv !== false) {
-              const version = (env[cacheVersionEnv] as string) || "";
-              if (version) url.searchParams.set("__v", version);
-            }
+            const purgeVersion = getBuildHash(env);
+            if (purgeVersion) url.searchParams.set("__v", purgeVersion);
             url.searchParams.set("__seg", hashSegment(seg));
             if (cc) url.searchParams.set("__cf_geo", cc);
             const key = new Request(url.toString(), { method: "GET" });
@@ -816,10 +840,8 @@ export function createDecoWorkerEntry(
         for (const device of devices) {
           for (const cc of geoKeys) {
             const url = new URL(p, baseUrl);
-            if (cacheVersionEnv !== false) {
-              const version = (env[cacheVersionEnv] as string) || "";
-              if (version) url.searchParams.set("__v", version);
-            }
+            const purgeVersion = getBuildHash(env);
+            if (purgeVersion) url.searchParams.set("__v", purgeVersion);
             if (device) url.searchParams.set("__cf_device", device);
             if (cc) url.searchParams.set("__cf_geo", cc);
             const key = new Request(url.toString(), { method: "GET" });
@@ -1190,10 +1212,8 @@ export function createDecoWorkerEntry(
       // different regions or channels get separate cache entries.
       const cacheKeyUrl = new URL(request.url);
       cacheKeyUrl.searchParams.set("__body", bodyHash);
-      if (cacheVersionEnv !== false) {
-        const version = (env[cacheVersionEnv] as string) || "";
-        if (version) cacheKeyUrl.searchParams.set("__v", version);
-      }
+      const sfnVersion = getBuildHash(env);
+      if (sfnVersion) cacheKeyUrl.searchParams.set("__v", sfnVersion);
       if (sfnSegment) {
         cacheKeyUrl.searchParams.set("__seg", hashSegment(sfnSegment));
       } else if (deviceSpecificKeys) {
@@ -1409,10 +1429,8 @@ export function createDecoWorkerEntry(
       out.headers.set("X-Cache", xCache);
       out.headers.set("X-Cache-Profile", profile);
       if (segment) out.headers.set("X-Cache-Segment", hashSegment(segment));
-      if (cacheVersionEnv !== false) {
-        const v = (env[cacheVersionEnv] as string) || "";
-        if (v) out.headers.set("X-Cache-Version", v);
-      }
+      const headerVersion = getBuildHash(env);
+      if (headerVersion) out.headers.set("X-Cache-Version", headerVersion);
       if (extra) for (const [k, v] of Object.entries(extra)) out.headers.set(k, v);
       appendResourceHints(out);
       return out;

package/src/vite/plugin.js

@@ -31,8 +31,49 @@
  * export default defineConfig({ plugins: [decoVitePlugin(), ...] });
  * ```
  */
+import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 
+/**
+ * Resolve a per-build identifier for cache-key versioning.
+ *
+ * The returned string is injected into the worker bundle as the
+ * `__DECO_BUILD_HASH__` global via Vite `define`. `createDecoWorkerEntry`
+ * appends it (or `env.BUILD_HASH` if explicitly set) as `__v=<hash>` on
+ * every Cache API key, so each new deploy gets its own cache namespace
+ * — old edge-cached HTML referencing dead asset filenames stops being
+ * served the moment the new worker is live.
+ *
+ * Resolution order:
+ *   1. WORKERS_CI_COMMIT_SHA — Cloudflare Workers Builds default env var
+ *      (the production deploy path-of-record). Sliced to 12 chars.
+ *   2. `git rev-parse --short=12 HEAD` — local `wrangler deploy` from a
+ *      developer laptop. Try/catch so missing git or shallow clones don't
+ *      fail the build.
+ *   3. `Date.now().toString(36)` — last-resort fallback so the cache-bust
+ *      invariant never silently regresses to "always the same key".
+ *
+ * For dev (`command !== "build"`), the value is the literal `"dev"`.
+ *
+ * @returns {string}
+ */
+function resolveBuildHash() {
+  const ciSha = process.env.WORKERS_CI_COMMIT_SHA;
+  if (ciSha?.trim()) return ciSha.trim().slice(0, 12);
+
+  try {
+    const sha = execFileSync("git", ["rev-parse", "--short=12", "HEAD"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (sha) return sha;
+  } catch {
+    // git absent, not a repo, or shallow clone w/o history — fall through.
+  }
+
+  return Date.now().toString(36);
+}
+
 // Bare-specifier stubs resolved by ID before Vite touches them.
 /** @type {Record<string, string>} */
 const CLIENT_STUBS = {
@@ -227,6 +268,20 @@ export function decoVitePlugin() {
         };
       }
 
+      // Inject a per-build identifier as `__DECO_BUILD_HASH__` so
+      // createDecoWorkerEntry can fall back to it when env.BUILD_HASH is
+      // unset (the default on Cloudflare Workers Builds, where there's
+      // no GH-Actions step injecting --var BUILD_HASH).
+      //
+      // Dev gets the literal "dev" so SSR doesn't crash on an undefined
+      // identifier; prod gets WORKERS_CI_COMMIT_SHA → git rev-parse →
+      // time-based fallback (see resolveBuildHash above).
+      const buildHash = command === "build" ? resolveBuildHash() : "dev";
+      cfg.define = {
+        ...cfg.define,
+        __DECO_BUILD_HASH__: JSON.stringify(buildHash),
+      };
+
       // Only split chunks for production builds — dev uses unbundled ESM.
       if (command !== "build") return cfg;
       return {

package/src/vite/plugin.test.js

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { decoVitePlugin } from "./plugin.js";
 
 /**
@@ -52,3 +52,62 @@ describe("decoVitePlugin client stubs (regression guard)", () => {
     expect(id).toBeUndefined();
   });
 });
+
+describe("decoVitePlugin __DECO_BUILD_HASH__ injection", () => {
+  let originalEnv;
+
+  beforeEach(() => {
+    originalEnv = { ...process.env };
+    delete process.env.WORKERS_CI_COMMIT_SHA;
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    vi.restoreAllMocks();
+  });
+
+  function callConfig(command) {
+    const p = getPlugin();
+    return p.config({}, { command });
+  }
+
+  it("injects the literal 'dev' for non-build commands", () => {
+    const cfg = callConfig("serve");
+    expect(cfg.define.__DECO_BUILD_HASH__).toBe(JSON.stringify("dev"));
+  });
+
+  it("uses WORKERS_CI_COMMIT_SHA (sliced to 12 chars) when set on a build", () => {
+    process.env.WORKERS_CI_COMMIT_SHA = "abcdef1234567890fedcba";
+    const cfg = callConfig("build");
+    expect(cfg.define.__DECO_BUILD_HASH__).toBe(JSON.stringify("abcdef123456"));
+  });
+
+  it("falls back to git rev-parse when WORKERS_CI_COMMIT_SHA is unset", async () => {
+    // The plugin module imports execFileSync at top-level, so we can't easily
+    // mock it after the fact. Instead, exercise the real git binary against
+    // this repo (CI runs in the repo working tree). Assert the value is a
+    // 12-char lowercase hex SHA — that proves git was consulted, not that
+    // the time-based fallback was hit.
+    const cfg = callConfig("build");
+    const value = JSON.parse(cfg.define.__DECO_BUILD_HASH__);
+    // Either git produced a SHA (CI / dev machine inside a repo) or the
+    // time-based fallback ran. Both are acceptable; we just assert non-empty
+    // and length sanity.
+    expect(typeof value).toBe("string");
+    expect(value.length).toBeGreaterThan(0);
+    // Time-based fallback produces base36 characters; git short SHAs are
+    // 12 hex chars. Both fit in this superset regex.
+    expect(value).toMatch(/^[0-9a-z]+$/);
+  });
+
+  it("preserves allowedHosts behaviour (regression: define is additive, not replacing)", () => {
+    process.env.DECO_SITE_NAME = "test-site";
+    try {
+      const cfg = callConfig("serve");
+      expect(cfg.server?.allowedHosts).toContain(".deco.studio");
+      expect(cfg.define.__DECO_BUILD_HASH__).toBeDefined();
+    } finally {
+      delete process.env.DECO_SITE_NAME;
+    }
+  });
+});

package/vitest.config.ts

@@ -11,7 +11,7 @@ export default defineConfig({
       ["scripts/**", "node"],
     ],
     include: [
-      "src/**/*.test.{ts,tsx}",
+      "src/**/*.test.{ts,tsx,js}",
       "scripts/**/*.test.ts",
     ],
     globals: true,

package/src/sdk/sampler.test.ts

@@ -1,165 +0,0 @@
-import { ROOT_CONTEXT, SpanKind } from "@opentelemetry/api";
-import {
-  AlwaysOnSampler,
-  ParentBasedSampler,
-  SamplingDecision,
-} from "@opentelemetry/sdk-trace-base";
-import { describe, expect, it } from "vitest";
-import {
-  createUrlBasedHeadSampler,
-  DEFAULT_SAMPLE_RATIO,
-  decodeSamplingConfig,
-  URLBasedSampler,
-} from "./sampler";
-
-// Two trace IDs at opposite ends of the TraceIdRatioBased accumulator.
-// `accumulate(traceId)` xors the trace ID in 8-hex-char chunks; threshold at
-// ratio R is `floor(R * 0xffffffff)`. See
-// `@opentelemetry/sdk-trace-base/src/sampler/TraceIdRatioBasedSampler`.
-//
-//   LOW:  0x00000000 ^ 0x00000000 ^ 0xffffffff ^ 0xffffffff = 0
-//         → 0 < threshold for any ratio > 0 → SAMPLED at any ratio > 0
-//   HIGH: 0xffffffff ^ 0x00000000 ^ 0x00000000 ^ 0x00000000 = 0xffffffff
-//         → never below threshold for ratio < 1.0 → DROPPED at any ratio < 1
-const LOW_TRACE_ID = "0000000000000000ffffffffffffffff";
-const HIGH_TRACE_ID = "ffffffff000000000000000000000000";
-
-function decide(sampler: URLBasedSampler, path: string, traceId = LOW_TRACE_ID) {
-  return sampler.shouldSample(
-    ROOT_CONTEXT,
-    traceId,
-    "span-name",
-    SpanKind.SERVER,
-    { "url.path": path },
-    [],
-  );
-}
-
-describe("URLBasedSampler", () => {
-  it("exposes 0.1 as the framework-wide default sample ratio", () => {
-    expect(DEFAULT_SAMPLE_RATIO).toBe(0.1);
-  });
-
-  it("defaults to DEFAULT_SAMPLE_RATIO (0.1) when config omits `default`", () => {
-    const s = new URLBasedSampler();
-    // LOW_TRACE_ID accumulates to 0 — sampled at any ratio > 0, including 0.1.
-    expect(decide(s, "/anything").decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
-    // HIGH_TRACE_ID accumulates to ~uint32 max — dropped at 0.1, would be
-    // kept only at ratio ~= 1. This is the assertion that catches an
-    // accidental revert to the old `?? 1.0` fallback.
-    expect(decide(s, "/anything", HIGH_TRACE_ID).decision).toBe(SamplingDecision.NOT_RECORD);
-  });
-
-  it("explicit `default: 1` opts in to AlwaysOn (records every trace)", () => {
-    const s = new URLBasedSampler({ default: 1 });
-    expect(decide(s, "/anything", HIGH_TRACE_ID).decision).toBe(
-      SamplingDecision.RECORD_AND_SAMPLED,
-    );
-  });
-
-  it("falls back to provided 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, LOW_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, LOW_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 DEFAULT_SAMPLE_RATIO when config is null", () => {
-    const sampler = createUrlBasedHeadSampler(null);
-    // High-accumulating trace ID is dropped at 0.1 — proves the ParentBased
-    // wrapper inherits the URLBasedSampler default and isn't accidentally
-    // forcing AlwaysOn.
-    const result = sampler.shouldSample(
-      ROOT_CONTEXT,
-      HIGH_TRACE_ID,
-      "n",
-      SpanKind.SERVER,
-      { "url.path": "/" },
-      [],
-    );
-    expect(result.decision).toBe(SamplingDecision.NOT_RECORD);
-  });
-});
-
-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);
-  });
-});

package/src/sdk/sampler.ts

@@ -1,213 +0,0 @@
-/**
- * URL-based head sampler — port of `deco-cx/deco/observability/otel/samplers/urlBased.ts`.
- *
- * **No longer wired into `instrumentWorker` by default.** As of 4.4.0 the
- * recommended path for trace sampling is Cloudflare's wrangler-level
- * `observability.traces.head_sampling_rate`, which is one global rate per
- * Worker. This module stays as an opt-in escape hatch for sites that need
- * URL-pattern-aware sampling (e.g. always trace `/checkout`, sample
- * homepages at 1%) — those sites must wire OTel themselves outside the
- * default `instrumentWorker` flow.
- *
- * The sampler reads `OTEL_SAMPLING_CONFIG` (base64-encoded JSON) and
- * decides each trace's sample rate based on the matching pattern.
- *
- * Wrapped in `ParentBasedSampler` so a span inherits its parent's sampling
- * decision when one exists (i.e. distributed traces stay consistent end
- * to end).
- *
- * **Default ratio.** When no `default` is provided in the config (or the env
- * var is unset entirely), the sampler keeps **10%** of traces. Production
- * storefront traffic at full sampling will burn HyperDX ingest quotas
- * quickly — for an unconfigured site we'd rather drop 90% than overspend by
- * default. Sites that genuinely want every trace recorded must opt-in
- * explicitly with `OTEL_SAMPLING_CONFIG` setting `default: 1`.
- *
- * @example
- * ```jsonc
- * // base64-encode this and set as OTEL_SAMPLING_CONFIG:
- * {
- *   "default": 0.05,
- *   "rules": [
- *     { "pattern": "^/checkout",   "ratio": 1.0 },
- *     { "pattern": "^/api/health", "ratio": 0.0 },
- *     { "pattern": "/p$",          "ratio": 0.1 }
- *   ]
- * }
- * ```
- *
- * @deprecated Slated for removal in 5.0.0 unless a site declares an active
- *   need. Use Cloudflare's `head_sampling_rate` first.
- */
-
-import { type Attributes, type Context, type Link, type SpanKind, trace } from "@opentelemetry/api";
-import {
-  AlwaysOffSampler,
-  AlwaysOnSampler,
-  ParentBasedSampler,
-  type Sampler,
-  type SamplingResult,
-  TraceIdRatioBasedSampler,
-} from "@opentelemetry/sdk-trace-base";
-
-export interface SamplingRule {
-  /** ECMA RegExp pattern matched against the URL path. */
-  pattern: string;
-  /** Ratio in [0, 1]. */
-  ratio: number;
-}
-
-export interface SamplingConfig {
-  /**
-   * Default sample ratio applied when no rule matches. Defaults to **0.1**
-   * (10% sampled) when omitted. Set to `1` to record every trace
-   * (only do this when you need a full debug stream and accept the cost).
-   */
-  default?: number;
-  /** Ordered list of rules. First match wins. */
-  rules?: SamplingRule[];
-}
-
-/**
- * Default ratio applied by `URLBasedSampler` when neither the config nor a
- * matching rule specifies one. Centralised so tests + docs share a single
- * source of truth.
- */
-export const DEFAULT_SAMPLE_RATIO = 0.1;
-
-interface CompiledRule {
-  re: RegExp;
-  sampler: Sampler;
-}
-
-/**
- * URL-pattern-driven head sampler. Implements the OTel `Sampler` interface
- * directly so it can be plugged into `ParentBasedSampler`'s `root` slot.
- */
-export class URLBasedSampler implements Sampler {
-  private readonly defaultSampler: Sampler;
-  private readonly rules: CompiledRule[];
-
-  constructor(config: SamplingConfig = {}) {
-    this.defaultSampler = ratioToSampler(config.default ?? DEFAULT_SAMPLE_RATIO);
-    this.rules = (config.rules ?? []).map((rule) => ({
-      re: new RegExp(rule.pattern),
-      sampler: ratioToSampler(rule.ratio),
-    }));
-  }
-
-  shouldSample(
-    context: Context,
-    traceId: string,
-    spanName: string,
-    spanKind: SpanKind,
-    attributes: Attributes,
-    links: Link[],
-  ): SamplingResult {
-    const path = extractPath(attributes);
-    if (path) {
-      for (const rule of this.rules) {
-        if (rule.re.test(path)) {
-          return rule.sampler.shouldSample(context, traceId, spanName, spanKind, attributes, links);
-        }
-      }
-    }
-    return this.defaultSampler.shouldSample(
-      context,
-      traceId,
-      spanName,
-      spanKind,
-      attributes,
-      links,
-    );
-  }
-
-  toString(): string {
-    return `URLBasedSampler(${this.rules.length} rules)`;
-  }
-}
-
-function ratioToSampler(ratio: number): Sampler {
-  if (ratio >= 1) return new AlwaysOnSampler();
-  if (ratio <= 0) return new AlwaysOffSampler();
-  return new TraceIdRatioBasedSampler(ratio);
-}
-
-function extractPath(attrs: Attributes): string | null {
-  // Prefer the OTel-standard `url.path` (semconv >= 1.21), fall back to
-  // legacy `http.target` and `http.url`.
-  const direct = attrs["url.path"] ?? attrs["http.target"];
-  if (typeof direct === "string") return direct;
-
-  const httpUrl = attrs["http.url"];
-  if (typeof httpUrl === "string") {
-    try {
-      return new URL(httpUrl).pathname;
-    } catch {
-      return null;
-    }
-  }
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// Boot helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Decode a base64-encoded `OTEL_SAMPLING_CONFIG` value into a `SamplingConfig`.
- * Returns `null` (caller falls back to `DEFAULT_SAMPLE_RATIO`, currently 0.1) on:
- *  - missing / empty input
- *  - invalid base64
- *  - JSON parse failure
- *  - schema-mismatched payload
- *
- * Logs a warning to console when the env var is set but unparseable so the
- * mistake is visible in CF Logs without crashing the worker boot.
- */
-export function decodeSamplingConfig(raw: string | undefined): SamplingConfig | null {
-  if (!raw) return null;
-  try {
-    const json = atob(raw);
-    const parsed = JSON.parse(json) as unknown;
-    if (!parsed || typeof parsed !== "object") return null;
-    const obj = parsed as { default?: unknown; rules?: unknown };
-
-    const defaultRatio = typeof obj.default === "number" ? obj.default : undefined;
-    const rawRules = Array.isArray(obj.rules) ? obj.rules : [];
-    const rules: SamplingRule[] = [];
-    for (const r of rawRules) {
-      if (!r || typeof r !== "object") continue;
-      const rec = r as { pattern?: unknown; ratio?: unknown };
-      if (typeof rec.pattern !== "string" || typeof rec.ratio !== "number") continue;
-      try {
-        // Eagerly validate the regex so a bad pattern fails at boot, not
-        // on the first matching request.
-        new RegExp(rec.pattern);
-        rules.push({ pattern: rec.pattern, ratio: rec.ratio });
-      } catch {
-        console.warn(`[sampler] dropping invalid pattern: ${rec.pattern}`);
-      }
-    }
-
-    return { default: defaultRatio, rules };
-  } catch (err) {
-    console.warn(`[sampler] failed to decode OTEL_SAMPLING_CONFIG`, String(err));
-    return null;
-  }
-}
-
-/**
- * Build a `ParentBasedSampler` rooted at our URL-based sampler.
- * Wire as the `headSampler` for any custom OTel SDK setup (e.g. a site
- * that opts back into `@microlabs/otel-cf-workers` outside the default
- * `instrumentWorker` flow).
- */
-export function createUrlBasedHeadSampler(config: SamplingConfig | null): Sampler {
-  const root = new URLBasedSampler(config ?? {});
-  return new ParentBasedSampler({ root });
-}
-
-// Re-export OTel API helper so callers can read `traceId` / build tags off
-// the active span without importing @opentelemetry/api directly.
-export { trace as _otelTrace };