clean-architecture-frontend-template/src/contracts/telemetry.js

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",
  ], ["operation_id", "duration_bucket"]),
  "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",
  ),
});

const SAFE_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,63}$/;
const ATTRIBUTE_VALUE_POLICIES =
  /** @type {Readonly<Record<string, (value: string) => boolean>>} */ (
    Object.freeze({
      route_id: (value) => /^[A-Z][A-Z0-9_]{0,63}$/.test(value),
      operation_id: (value) => /^[A-Z][A-Z0-9_]{0,63}$/.test(value),
      error_kind: (value) => /^[A-Z][A-Z0-9_]{0,63}$/.test(value),
      http_status_group: (value) => /^(?:[1-5]xx|none)$/.test(value),
      attempt_count_bucket: (value) => /^(?:1|2|3|3-4|5\+)$/.test(value),
      duration_bucket: (value) =>
        /^(?:lt100ms|100-499ms|500-1999ms|gte2000ms|unknown)$/.test(
          value,
        ),
      component_boundary: (value) =>
        /^(?:route|feature|boot)$/.test(value),
      mismatch_kind: (value) => /^[A-Z][A-Z0-9_]{0,63}$/.test(value),
      reason: (value) =>
        /^(?:queue-full|sink-failure|invalid-event|invalid-context|serialization-failure)$/.test(
          value,
        ),
      queue_size_bucket: (value) =>
        /^(?:0|1-10|11-50|51\+)$/.test(value),
    })
  );

/** @param {string} key @param {unknown} value */
function validAttributeValue(key, value) {
  if (typeof value !== "string") return false;
  const policy = ATTRIBUTE_VALUE_POLICIES[key];
  return policy ? policy(value) : SAFE_IDENTIFIER.test(value);
}

/**
 * @param {string} eventName
 * @param {Record<string, unknown>} attributes
 * @param {() => number} [now]
 */
function projectTelemetryEventUnsafe(eventName, attributes, now = Date.now) {
  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 attributeKeys = Object.keys(attributes);
  if (
    attributeKeys.length >
    TELEMETRY_ATTRIBUTE_ALLOWLIST.length +
      TELEMETRY_FORBIDDEN_ATTRIBUTES.length
  ) {
    return {
      success: /** @type {false} */ (false),
      reason: "invalid-attribute-value",
    };
  }
  const unknown = attributeKeys.filter(
    (key) =>
      !TELEMETRY_ATTRIBUTE_ALLOWLIST.includes(key) &&
      !TELEMETRY_FORBIDDEN_ATTRIBUTES.includes(key),
  );
  if (unknown.length > 0) {
    return {
      success: /** @type {false} */ (false),
      reason: "unknown-attributes",
    };
  }
  const projected = Object.fromEntries(
    Object.entries(attributes).filter(
      ([key, value]) =>
        TELEMETRY_ATTRIBUTE_ALLOWLIST.includes(key) &&
        !TELEMETRY_FORBIDDEN_ATTRIBUTES.includes(key) &&
        validAttributeValue(key, value),
    ),
  );
  const invalid = Object.entries(attributes).filter(
    ([key, value]) =>
      TELEMETRY_ATTRIBUTE_ALLOWLIST.includes(key) &&
      !validAttributeValue(key, value),
  );
  if (invalid.length > 0) {
    return {
      success: /** @type {false} */ (false),
      reason: "invalid-attribute-value",
    };
  }
  const missing = definition.requiredAttributes.filter(
    (key) => projected[key] === undefined,
  );
  if (missing.length > 0) {
    return {
      success: /** @type {false} */ (false),
      reason: "missing-required-attributes",
    };
  }

  let timestamp;
  try {
    timestamp = new Date(now()).toISOString();
  } catch {
    timestamp = new Date(0).toISOString();
  }
  return {
    success: /** @type {true} */ (true),
    event: Object.freeze({
      eventName,
      timestamp,
      attributes: Object.freeze(projected),
    }),
  };
}

/**
 * @param {string} eventName
 * @param {Record<string, unknown>} attributes
 * @param {() => number} [now]
 */
export function projectTelemetryEvent(eventName, attributes, now = Date.now) {
  try {
    return projectTelemetryEventUnsafe(eventName, attributes, now);
  } catch {
    return {
      success: /** @type {false} */ (false),
      reason: "serialization-failure",
    };
  }
}