feat: add redacted best-effort telemetry contract

src/adapters/telemetry/best-effort-telemetry.js

@@ -0,0 +1,99 @@
+import { projectTelemetryEvent } from "../../contracts/telemetry.js";
+
+export const noOpTelemetry = Object.freeze({
+  emit: () => {},
+});
+
+/**
+ * @param {{
+ *   enabled: boolean,
+ *   endpoint?: string,
+ *   fetcher?: typeof fetch,
+ *   maxQueue?: number,
+ *   schedule?: (callback: () => void) => void
+ * }} options
+ */
+export function createTelemetryAdapter(options) {
+  if (!options.enabled || !options.endpoint) {
+    return Object.freeze({
+      ...noOpTelemetry,
+      flush: async () => {},
+      pendingCount: () => 0,
+      droppedCount: () => 0,
+    });
+  }
+
+  const endpoint = /** @type {string} */ (options.endpoint);
+  const fetcher = options.fetcher ?? fetch;
+  const maxQueue = options.maxQueue ?? 100;
+  const schedule = options.schedule ?? queueMicrotask;
+  const queue =
+    /** @type {Array<{eventName: string, attributes: Readonly<Record<string, unknown>>}>} */ (
+      []
+    );
+  let scheduled = false;
+  let flushing = false;
+  let dropped = 0;
+
+  /** @param {string} eventName @param {Record<string, unknown>} attributes */
+  function emit(eventName, attributes) {
+    const projected = projectTelemetryEvent(eventName, attributes);
+    if (!projected.success) {
+      dropped += 1;
+      return;
+    }
+
+    if (queue.length >= maxQueue) {
+      queue.shift();
+      dropped += 1;
+    }
+    queue.push(projected.event);
+
+    if (!scheduled) {
+      scheduled = true;
+      schedule(() => {
+        scheduled = false;
+        void flush();
+      });
+    }
+  }
+
+  async function flush() {
+    if (flushing || queue.length === 0) return;
+    flushing = true;
+    const batch = queue.splice(0, queue.length);
+    try {
+      const response = await fetcher(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ events: batch }),
+        keepalive: true,
+      });
+      if (!response.ok) dropped += batch.length;
+    } catch {
+      dropped += batch.length;
+    } finally {
+      flushing = false;
+    }
+  }
+
+  return Object.freeze({
+    emit,
+    flush,
+    pendingCount: () => queue.length,
+    droppedCount: () => dropped,
+  });
+}
+
+/**
+ * Propagates only a structurally valid W3C traceparent. Invalid/raw headers are
+ * discarded rather than logged or surfaced.
+ *
+ * @param {string | null | undefined} traceparent
+ */
+export function safeTraceparent(traceparent) {
+  return typeof traceparent === "string" &&
+    /^00-[0-9a-f]{32}-[0-9a-f]{16}-0[01]$/i.test(traceparent)
+    ? traceparent.toLowerCase()
+    : null;
+}

src/contracts/telemetry.js

@@ -0,0 +1,145 @@
+export const TELEMETRY_ATTRIBUTE_ALLOWLIST = Object.freeze([
+  "app_version",
+  "build_id",
+  "release_id",
+  "config_schema_version",
+  "api_contract_version",
+  "route_id",
+  "operation_id",
+  "error_kind",
+  "http_status_group",
+  "attempt_count_bucket",
+  "duration_bucket",
+  "component_boundary",
+  "active_release_id",
+  "mismatch_kind",
+  "reason",
+  "queue_size_bucket",
+]);
+
+export const TELEMETRY_FORBIDDEN_ATTRIBUTES = Object.freeze([
+  "access_token",
+  "refresh_token",
+  "authorization_header",
+  "cookie",
+  "email",
+  "user_name",
+  "raw_user_id",
+  "raw_url",
+  "query_string",
+  "request_body",
+  "response_body",
+  "storage_value",
+  "stack_in_user_message",
+]);
+
+/**
+ * @typedef {{
+ *   eventName: string,
+ *   trigger: string,
+ *   requiredAttributes: readonly string[],
+ *   optionalAttributes: readonly string[],
+ *   forbiddenAttributes: readonly string[],
+ *   sampling: string,
+ *   delivery: string
+ * }} TelemetryDefinition
+ */
+
+/**
+ * @param {string} eventName
+ * @param {string} trigger
+ * @param {string[]} requiredAttributes
+ * @param {string[]} [optionalAttributes]
+ * @param {string} [sampling]
+ * @returns {Readonly<TelemetryDefinition>}
+ */
+const event = (
+  eventName,
+  trigger,
+  requiredAttributes,
+  optionalAttributes = [],
+  sampling = "all",
+) =>
+  Object.freeze({
+    eventName,
+    trigger,
+    requiredAttributes: Object.freeze(requiredAttributes),
+    optionalAttributes: Object.freeze(optionalAttributes),
+    forbiddenAttributes: TELEMETRY_FORBIDDEN_ATTRIBUTES,
+    sampling,
+    delivery: "best-effort",
+  });
+
+export const TELEMETRY_REGISTRY = Object.freeze({
+  "app.boot.failed": event("app.boot.failed", "boot validation failure", [
+    "error_kind",
+    "build_id",
+    "config_schema_version",
+  ]),
+  "api.request.failed": event("api.request.failed", "terminal API failure", [
+    "error_kind",
+    "http_status_group",
+    "attempt_count_bucket",
+    "route_id",
+  ]),
+  "ui.render.failed": event("ui.render.failed", "React boundary catch", [
+    "route_id",
+    "build_id",
+    "component_boundary",
+  ]),
+  "release.mismatch.detected": event(
+    "release.mismatch.detected",
+    "release tuple mismatch",
+    ["build_id", "active_release_id", "mismatch_kind"],
+  ),
+  "telemetry.delivery.dropped": event(
+    "telemetry.delivery.dropped",
+    "queue or sink failure",
+    ["reason", "queue_size_bucket"],
+    [],
+    "internal-counter",
+  ),
+});
+
+/**
+ * @param {string} eventName
+ * @param {Record<string, unknown>} attributes
+ */
+export function projectTelemetryEvent(eventName, attributes) {
+  const registry =
+    /** @type {Record<string, (typeof TELEMETRY_REGISTRY)[keyof typeof TELEMETRY_REGISTRY]>} */ (
+      TELEMETRY_REGISTRY
+    );
+  const definition = registry[eventName];
+  if (!definition) {
+    return {
+      success: /** @type {false} */ (false),
+      reason: "unregistered-event",
+    };
+  }
+
+  const projected = Object.fromEntries(
+    Object.entries(attributes).filter(
+      ([key]) =>
+        TELEMETRY_ATTRIBUTE_ALLOWLIST.includes(key) &&
+        !TELEMETRY_FORBIDDEN_ATTRIBUTES.includes(key),
+    ),
+  );
+  const missing = definition.requiredAttributes.filter(
+    (key) => projected[key] === undefined,
+  );
+  if (missing.length > 0) {
+    return {
+      success: /** @type {false} */ (false),
+      reason: "missing-required-attributes",
+    };
+  }
+
+  return {
+    success: /** @type {true} */ (true),
+    event: Object.freeze({
+      eventName,
+      attributes: Object.freeze(projected),
+    }),
+  };
+}

tests/unit/telemetry.test.js

@@ -0,0 +1,105 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  createTelemetryAdapter,
+  safeTraceparent,
+} from "../../src/adapters/telemetry/best-effort-telemetry.js";
+import {
+  TELEMETRY_REGISTRY,
+  projectTelemetryEvent,
+} from "../../src/contracts/telemetry.js";
+
+const validAttributes = {
+  error_kind: "SERVER_FAILURE",
+  http_status_group: "5xx",
+  attempt_count_bucket: "3",
+  route_id: "SAMPLE_RESOURCE_LIST",
+};
+
+describe("telemetry registry and redaction", () => {
+  it("defines all event contract fields", () => {
+    for (const definition of Object.values(TELEMETRY_REGISTRY)) {
+      expect(definition).toEqual(
+        expect.objectContaining({
+          eventName: expect.any(String),
+          trigger: expect.any(String),
+          requiredAttributes: expect.any(Array),
+          optionalAttributes: expect.any(Array),
+          forbiddenAttributes: expect.any(Array),
+          sampling: expect.any(String),
+          delivery: "best-effort",
+        }),
+      );
+    }
+  });
+
+  it("uses a default-deny attribute projection", () => {
+    const projected = projectTelemetryEvent("api.request.failed", {
+      ...validAttributes,
+      raw_url: "https://api.test/path?token=secret",
+      unregistered: "private",
+    });
+
+    expect(projected.success).toBe(true);
+    expect(JSON.stringify(projected)).not.toMatch(/raw_url|token|secret|unregistered/);
+  });
+
+  it("validates traceparent without exposing invalid values", () => {
+    expect(
+      safeTraceparent(
+        "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+      ),
+    ).toBe("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01");
+    expect(safeTraceparent("Bearer secret")).toBeNull();
+  });
+});
+
+describe("best-effort telemetry adapter", () => {
+  it("bounds the queue using oldest-drop without blocking callers", () => {
+    const scheduled = [];
+    const adapter = createTelemetryAdapter({
+      enabled: true,
+      endpoint: "https://telemetry.test/events",
+      maxQueue: 2,
+      schedule: (callback) => scheduled.push(callback),
+      fetcher: vi.fn(),
+    });
+
+    adapter.emit("api.request.failed", validAttributes);
+    adapter.emit("api.request.failed", validAttributes);
+    adapter.emit("api.request.failed", validAttributes);
+
+    expect(adapter.pendingCount()).toBe(2);
+    expect(adapter.droppedCount()).toBe(1);
+    expect(scheduled).toHaveLength(1);
+  });
+
+  it("degrades on sink failure without throwing or recursive events", async () => {
+    const adapter = createTelemetryAdapter({
+      enabled: true,
+      endpoint: "https://telemetry.test/events",
+      schedule: () => {},
+      fetcher: async () => {
+        throw new Error("sink unavailable");
+      },
+    });
+    expect(() => adapter.emit("api.request.failed", validAttributes)).not.toThrow();
+    await expect(adapter.flush()).resolves.toBeUndefined();
+    expect(adapter.droppedCount()).toBe(1);
+    expect(adapter.pendingCount()).toBe(0);
+  });
+
+  it("performs no network or queue work when disabled", async () => {
+    const fetcher = vi.fn();
+    const adapter = createTelemetryAdapter({
+      enabled: false,
+      endpoint: "https://telemetry.test/events",
+      fetcher,
+    });
+    adapter.emit("api.request.failed", validAttributes);
+    await adapter.flush();
+
+    expect(fetcher).not.toHaveBeenCalled();
+    expect(adapter.pendingCount()).toBe(0);
+  });
+});