tech-log-frontend/src/contracts/telemetry.ts

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",
] as const);

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",
] as const);

type TelemetryDefinitionFor<Name extends string> = Readonly<{
  eventName: Name;
  trigger: string;
  requiredAttributes: readonly string[];
  optionalAttributes: readonly string[];
  forbiddenAttributes: readonly string[];
  sampling: string;
  delivery: "best-effort";
}>;

const event = <Name extends string>(
  eventName: Name,
  trigger: string,
  requiredAttributes: readonly string[],
  optionalAttributes: readonly string[] = [],
  sampling = "all",
): TelemetryDefinitionFor<Name> =>
  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",
  ),
});

export type TelemetryEventName = keyof typeof TELEMETRY_REGISTRY;
export type TelemetryDefinition = TelemetryDefinitionFor<TelemetryEventName>;
export type TelemetryEvent = Readonly<{
  eventName: TelemetryEventName;
  timestamp: string;
  attributes: Readonly<Record<string, unknown>>;
}>;

export type TelemetryProjectionResult =
  | Readonly<{ success: true; event: TelemetryEvent }>
  | Readonly<{ success: false; reason: string }>;

const SAFE_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,63}$/;
const ATTRIBUTE_VALUE_POLICIES: 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),
    });

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

function isTelemetryEventName(value: string): value is TelemetryEventName {
  return Object.hasOwn(TELEMETRY_REGISTRY, value);
}

function includesAttribute(list: readonly string[], key: string): boolean {
  return list.includes(key);
}

function projectTelemetryEventUnsafe(
  eventName: string,
  attributes: Readonly<Record<string, unknown>>,
  now: () => number = Date.now,
): TelemetryProjectionResult {
  if (!isTelemetryEventName(eventName)) {
    return {
      success: false,
      reason: "unregistered-event",
    };
  }
  const definition = TELEMETRY_REGISTRY[eventName];

  const attributeKeys = Object.keys(attributes);
  if (
    attributeKeys.length >
    TELEMETRY_ATTRIBUTE_ALLOWLIST.length +
      TELEMETRY_FORBIDDEN_ATTRIBUTES.length
  ) {
    return {
      success: false,
      reason: "invalid-attribute-value",
    };
  }
  const unknown = attributeKeys.filter(
    (key) =>
      !includesAttribute(TELEMETRY_ATTRIBUTE_ALLOWLIST, key) &&
      !includesAttribute(TELEMETRY_FORBIDDEN_ATTRIBUTES, key),
  );
  if (unknown.length > 0) {
    return {
      success: false,
      reason: "unknown-attributes",
    };
  }
  const projected = Object.fromEntries(
    Object.entries(attributes).filter(
      ([key, value]) =>
        includesAttribute(TELEMETRY_ATTRIBUTE_ALLOWLIST, key) &&
        !includesAttribute(TELEMETRY_FORBIDDEN_ATTRIBUTES, key) &&
        validAttributeValue(key, value),
    ),
  );
  const invalid = Object.entries(attributes).filter(
    ([key, value]) =>
      includesAttribute(TELEMETRY_ATTRIBUTE_ALLOWLIST, key) &&
      !validAttributeValue(key, value),
  );
  if (invalid.length > 0) {
    return {
      success: false,
      reason: "invalid-attribute-value",
    };
  }
  const missing = definition.requiredAttributes.filter(
    (key) => projected[key] === undefined,
  );
  if (missing.length > 0) {
    return {
      success: false,
      reason: "missing-required-attributes",
    };
  }

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

export function projectTelemetryEvent(
  eventName: string,
  attributes: Readonly<Record<string, unknown>>,
  now: () => number = Date.now,
): TelemetryProjectionResult {
  try {
    return projectTelemetryEventUnsafe(eventName, attributes, now);
  } catch {
    return {
      success: false,
      reason: "serialization-failure",
    };
  }
}