@echovisionlab/geul-telemetry 0.1.0

package/src/redaction.ts

@@ -0,0 +1,35 @@
+import { stableErrorType } from "./error-metadata.ts";
+import { isForbiddenKey, normalizeKey } from "./log-attribute-policy.ts";
+
+// Stable public entrypoint retained for package consumers. Policy ownership and
+// error classification live in focused modules; only attribute normalization
+// is implemented here.
+export { stableErrorType } from "./error-metadata.ts";
+export { isForbiddenKey, normalizeKey } from "./log-attribute-policy.ts";
+
+export type NormalizedLogAttributes = Record<string, string | number | boolean>;
+
+// Conservative log boundary shared by TypeScript services. Sensitive keys,
+// raw errors, and untyped objects never reach stdout or OTLP exporters.
+export function normalizeLogAttributes(
+  attributes?: Readonly<Record<string, unknown>>,
+): NormalizedLogAttributes {
+  const normalized: NormalizedLogAttributes = {};
+  if (attributes === undefined) return normalized;
+  for (const [key, value] of Object.entries(attributes)) {
+    const normalizedKey = normalizeKey(key);
+    if (normalizedKey === "" || isForbiddenKey(normalizedKey)) continue;
+    if (normalizedKey === "error" || normalizedKey === "err") {
+      normalized.error_type = stableErrorType(value);
+      continue;
+    }
+    if (
+      typeof value === "string" ||
+      typeof value === "number" ||
+      typeof value === "boolean"
+    ) {
+      normalized[normalizedKey] = value;
+    }
+  }
+  return normalized;
+}

package/src/request-context.ts

@@ -0,0 +1,73 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { isIP } from "node:net";
+
+import type { Actor } from "./actor.ts";
+import {
+  createRequestId,
+  isRequestId,
+  MESSAGE_REQUEST_ID_HEADER,
+  REQUEST_ID_HEADER,
+} from "./request-id.ts";
+
+export { isRequestId, MESSAGE_REQUEST_ID_HEADER, REQUEST_ID_HEADER };
+
+export interface RequestContext {
+  readonly requestId: string;
+  readonly actor: Actor;
+  readonly requestedAt: Date;
+  readonly sourceIp?: string;
+}
+
+const requestScope = new AsyncLocalStorage<RequestContext>();
+export function isCanonicalSourceIp(value: string): boolean {
+  const version = isIP(value);
+  if (version === 4) {
+    return true;
+  }
+  if (version !== 6 || value !== value.toLowerCase()) {
+    return false;
+  }
+  const hostname = new URL(`http://[${value}]/`).hostname;
+  return hostname.slice(1, -1) === value;
+}
+
+export function createPublicRequestContext(sourceIp?: string): RequestContext {
+  if (sourceIp !== undefined && !isCanonicalSourceIp(sourceIp)) {
+    throw new TypeError("sourceIp must be a canonical IPv4 or IPv6 address");
+  }
+  const requestContext: RequestContext = {
+    requestId: createRequestId(),
+    actor: { kind: "anonymous" },
+    requestedAt: new Date(),
+    ...(sourceIp === undefined ? {} : { sourceIp }),
+  };
+  return Object.freeze(requestContext);
+}
+
+export function createPropagatedRequestContext(
+  requestId: string,
+  actor: Actor,
+): RequestContext {
+  if (!isRequestId(requestId)) {
+    throw new TypeError("requestId must be a canonical UUIDv4");
+  }
+  return Object.freeze({ requestId, actor, requestedAt: new Date() });
+}
+
+export function withActor(
+  requestContext: RequestContext,
+  actor: Actor,
+): RequestContext {
+  return Object.freeze({ ...requestContext, actor });
+}
+
+export function runWithRequestContext<T>(
+  requestContext: RequestContext,
+  callback: () => T,
+): T {
+  return requestScope.run(requestContext, callback);
+}
+
+export function activeRequestContext(): RequestContext | undefined {
+  return requestScope.getStore();
+}

package/src/request-id.ts

@@ -0,0 +1,13 @@
+export const REQUEST_ID_HEADER = "X-Request-ID";
+export const MESSAGE_REQUEST_ID_HEADER = "x-request-id";
+
+const canonicalUUIDv4 =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+export function isRequestId(value: string): boolean {
+  return canonicalUUIDv4.test(value);
+}
+
+export function createRequestId(): string {
+  return globalThis.crypto.randomUUID();
+}

package/src/request-result.ts

@@ -0,0 +1,73 @@
+import type { RequestOutcome } from "./records.ts";
+
+export const REQUEST_REASONS = [
+  "authentication_required",
+  "permission_denied",
+  "rate_limited",
+  "client_error",
+  "server_error",
+] as const;
+
+export type RequestReason = (typeof REQUEST_REASONS)[number];
+
+export interface RequestResult {
+  readonly status_code: number;
+  readonly duration_ms: number;
+  readonly outcome: RequestOutcome;
+  readonly error_code?: string;
+  readonly reason?: RequestReason;
+}
+
+export function classifyHTTPResult(
+  statusCode: number,
+  durationMs: number,
+): RequestResult {
+  if (
+    !Number.isInteger(statusCode) ||
+    statusCode < 100 ||
+    statusCode > 599 ||
+    !Number.isInteger(durationMs) ||
+    durationMs < 0
+  ) {
+    throw new TypeError(
+      "HTTP result requires a valid status_code and non-negative duration_ms",
+    );
+  }
+  if (statusCode < 400) {
+    return {
+      status_code: statusCode,
+      duration_ms: durationMs,
+      outcome: "succeeded",
+    };
+  }
+  if (statusCode === 401) {
+    return {
+      status_code: statusCode,
+      duration_ms: durationMs,
+      outcome: "blocked",
+      reason: "authentication_required",
+    };
+  }
+  if (statusCode === 403) {
+    return {
+      status_code: statusCode,
+      duration_ms: durationMs,
+      outcome: "blocked",
+      reason: "permission_denied",
+    };
+  }
+  if (statusCode === 429) {
+    return {
+      status_code: statusCode,
+      duration_ms: durationMs,
+      outcome: "blocked",
+      reason: "rate_limited",
+    };
+  }
+  return {
+    status_code: statusCode,
+    duration_ms: durationMs,
+    outcome: "failed",
+    reason: statusCode < 500 ? "client_error" : "server_error",
+  };
+}

package/src/request.ts

@@ -0,0 +1,60 @@
+import type { RecordActor } from "./actor.ts";
+import {
+  validateRequestRecord,
+  type Correlation,
+  type RequestRecord,
+} from "./records.ts";
+import type { RequestResult } from "./request-result.ts";
+
+export {
+  classifyHTTPResult,
+  REQUEST_REASONS,
+  type RequestReason,
+  type RequestResult,
+} from "./request-result.ts";
+
+export type RequestMetadata = Correlation &
+  RecordActor & {
+    readonly occurred_at: string;
+  };
+
+export function buildHTTPRequestRecord(
+  metadata: RequestMetadata,
+  httpMethod: string,
+  httpRoute: string,
+  result: RequestResult,
+): RequestRecord {
+  return buildRequestRecord(metadata, result, {
+    http_method: httpMethod,
+    http_route: httpRoute,
+  });
+}
+
+export function buildRPCRequestRecord(
+  metadata: RequestMetadata,
+  httpMethod: string,
+  rpcService: string,
+  rpcMethod: string,
+  result: RequestResult,
+): RequestRecord {
+  return buildRequestRecord(metadata, result, {
+    http_method: httpMethod,
+    rpc_service: rpcService,
+    rpc_method: rpcMethod,
+  });
+}
+
+function buildRequestRecord(
+  metadata: RequestMetadata,
+  result: RequestResult,
+  boundary: Partial<RequestRecord>,
+): RequestRecord {
+  const record = {
+    ...metadata,
+    ...boundary,
+    ...result,
+    event: "request.completed",
+  } as RequestRecord;
+  validateRequestRecord(record);
+  return record;
+}

package/src/system.ts

@@ -0,0 +1,355 @@
+import {
+  SYSTEM_EVENT_OUTCOMES,
+  validateSystemRecord,
+  type AuditAction,
+  type AuditAppendFailureReason,
+  type Correlation,
+  type SecurityAction,
+  type SystemEvent,
+  type SystemRecord,
+  type TranslationEntityType,
+  type TranslationFailureReason,
+  type TranslationJobTerminalOutcome,
+} from "./records.ts";
+import type { JobFailureReason, JobKind } from "./job.ts";
+
+export type SystemMetadata = Correlation & {
+  readonly occurred_at: string;
+};
+
+export interface SystemFailure {
+  readonly error_code?: string;
+  readonly reason?: string;
+}
+
+export type QueueFailureReason =
+  | "enqueue_failed"
+  | "handler_failed"
+  | "completion_failed"
+  | "shutdown"
+  | "visibility_update_failed"
+  | "archive_failed";
+
+export interface QueuePublishContext {
+  readonly queue: string;
+  readonly message_id: string;
+  readonly command_id: string;
+  readonly duration_ms: number;
+}
+
+export interface QueueDeliveryContext {
+  readonly queue: string;
+  readonly message_id: string;
+  readonly command_id: string;
+  readonly retry_count: number;
+  readonly duration_ms: number;
+}
+
+export interface QueueHandoffContext {
+  readonly queue: string;
+  readonly message_id: string;
+  readonly command_id: string;
+  readonly retry_count: number;
+}
+
+export interface JobContext {
+  readonly job_kind: JobKind;
+  readonly job_id: string;
+}
+
+export interface JobFailure {
+  readonly reason: JobFailureReason;
+}
+
+/** Bounded public context for an authoritative Translation terminal transition. */
+export interface TranslationJobTerminalContext {
+  readonly job_id: string;
+  readonly entity_type: TranslationEntityType;
+  readonly target_locale: string;
+  readonly duration_ms: number;
+}
+
+export type CollaborationCheckpointFailureReason =
+  | "shared_document_unavailable"
+  | "source_document_unavailable"
+  | "locale_ownership_changed"
+  | "shared_structure_changed"
+  | "shared_materialization_changed"
+  | "document_revision_changed"
+  | "target_revision_changed"
+  | "persist_failed";
+
+export type CollaborationCheckpointEntityType =
+  | "post"
+  | "page"
+  | "work"
+  | "release"
+  | "label"
+  | "artist"
+  | "campaign"
+  | "program_event"
+  | "map_theme"
+  | "terms_history"
+  | "privacy_history"
+  | "form"
+  | "email_layout";
+
+export interface CollaborationCheckpointContext {
+  readonly entity_type: CollaborationCheckpointEntityType;
+  readonly entity_id: string;
+  readonly retry_count: number;
+}
+
+export type ClientRenderComponent = "general" | "admin" | "global";
+
+export type SystemLogLevel = "info" | "warn" | "error";
+
+export function systemLogLevel(record: SystemRecord): SystemLogLevel {
+  validateSystemRecord(record);
+  if (record.outcome === "failed") return "error";
+  if (record.outcome === "degraded" || record.outcome === "requeued") {
+    return "warn";
+  }
+  return "info";
+}
+
+export const buildServiceReadyRecord = (
+  metadata: SystemMetadata,
+  component: string,
+) => buildSystemRecord(metadata, "service.ready", { component });
+export const buildServiceDegradedRecord = (
+  metadata: SystemMetadata,
+  component: string,
+  failure: SystemFailure,
+) => buildSystemRecord(metadata, "service.degraded", { component, ...failure });
+export const buildServiceStoppingRecord = (
+  metadata: SystemMetadata,
+  component: string,
+) => buildSystemRecord(metadata, "service.stopping", { component });
+export const buildServiceFailedRecord = (
+  metadata: SystemMetadata,
+  component: string,
+  failure: SystemFailure,
+) => buildSystemRecord(metadata, "service.failed", { component, ...failure });
+export const buildDependencyDegradedRecord = (
+  metadata: SystemMetadata,
+  dependency: string,
+  operation: string,
+  failure: SystemFailure,
+) =>
+  buildSystemRecord(metadata, "dependency.degraded", {
+    dependency,
+    operation,
+    ...failure,
+  });
+export const buildDependencyRecoveredRecord = (
+  metadata: SystemMetadata,
+  dependency: string,
+  operation: string,
+) =>
+  buildSystemRecord(metadata, "dependency.recovered", {
+    dependency,
+    operation,
+  });
+export const buildQueuePublishSucceededRecord = (
+  metadata: SystemMetadata,
+  queue: QueuePublishContext,
+) =>
+  buildSystemRecord(metadata, "queue.publish.succeeded", {
+    domain: "queue",
+    ...queue,
+  });
+export const buildQueuePublishFailedRecord = (
+  metadata: SystemMetadata,
+  queue: QueuePublishContext,
+  reason: QueueFailureReason,
+) =>
+  buildSystemRecord(metadata, "queue.publish.failed", {
+    domain: "queue",
+    ...queue,
+    reason,
+  });
+export const buildQueueDeliverySucceededRecord = (
+  metadata: SystemMetadata,
+  queue: QueueDeliveryContext,
+) =>
+  buildSystemRecord(metadata, "queue.delivery.succeeded", {
+    domain: "queue",
+    ...queue,
+  });
+export const buildQueueDeliveryFailedRecord = (
+  metadata: SystemMetadata,
+  queue: QueueDeliveryContext,
+  reason: QueueFailureReason,
+) =>
+  buildSystemRecord(metadata, "queue.delivery.failed", {
+    domain: "queue",
+    ...queue,
+    reason,
+  });
+export const buildQueueDeliveryRequeuedRecord = (
+  metadata: SystemMetadata,
+  queue: QueueDeliveryContext,
+  reason: QueueFailureReason,
+) =>
+  buildSystemRecord(metadata, "queue.delivery.requeued", {
+    domain: "queue",
+    ...queue,
+    reason,
+  });
+export const buildQueueRetryAcceptedRecord = (
+  metadata: SystemMetadata,
+  queue: QueueHandoffContext,
+) =>
+  buildSystemRecord(metadata, "queue.retry.accepted", {
+    domain: "queue",
+    ...queue,
+  });
+export const buildQueueRetryFailedRecord = (
+  metadata: SystemMetadata,
+  queue: QueueHandoffContext,
+  reason: QueueFailureReason,
+) =>
+  buildSystemRecord(metadata, "queue.retry.failed", {
+    domain: "queue",
+    ...queue,
+    reason,
+  });
+export const buildQueueDLQAcceptedRecord = (
+  metadata: SystemMetadata,
+  queue: QueueHandoffContext,
+) =>
+  buildSystemRecord(metadata, "queue.dlq.accepted", {
+    domain: "queue",
+    ...queue,
+  });
+export const buildQueueDLQFailedRecord = (
+  metadata: SystemMetadata,
+  queue: QueueHandoffContext,
+  reason: QueueFailureReason,
+) =>
+  buildSystemRecord(metadata, "queue.dlq.failed", {
+    domain: "queue",
+    ...queue,
+    reason,
+  });
+export const buildJobStartedRecord = (
+  metadata: SystemMetadata,
+  job: JobContext,
+) => buildSystemRecord(metadata, "job.started", job);
+export const buildJobSucceededRecord = (
+  metadata: SystemMetadata,
+  job: JobContext,
+  durationMs: number,
+) =>
+  buildSystemRecord(metadata, "job.succeeded", {
+    ...job,
+    duration_ms: durationMs,
+  });
+export const buildJobFailedRecord = (
+  metadata: SystemMetadata,
+  job: JobContext,
+  durationMs: number,
+  failure: JobFailure,
+) =>
+  buildSystemRecord(metadata, "job.failed", {
+    ...job,
+    duration_ms: durationMs,
+    ...failure,
+  });
+export const buildTranslationJobTerminalRecord = (
+  metadata: SystemMetadata,
+  job: TranslationJobTerminalContext,
+  outcome: TranslationJobTerminalOutcome,
+  errorClassification?: TranslationFailureReason,
+) => {
+  if (outcome === "failed") {
+    if (errorClassification === undefined) {
+      throw new TypeError(
+        "failed translation.job.terminal requires an error classification",
+      );
+    }
+  } else if (errorClassification !== undefined) {
+    throw new TypeError(
+      `${outcome} translation terminal events cannot contain an error classification`,
+    );
+  }
+  return buildSystemRecord(metadata, "translation.job.terminal", {
+    domain: "translation",
+    ...job,
+    outcome,
+    ...(errorClassification === undefined
+      ? {}
+      : { error_classification: errorClassification }),
+  });
+};
+export const buildCollaborationCheckpointFailedRecord = (
+  metadata: SystemMetadata,
+  checkpoint: CollaborationCheckpointContext,
+  reason: CollaborationCheckpointFailureReason,
+) =>
+  buildSystemRecord(metadata, "collaboration.checkpoint.failed", {
+    domain: "collaboration",
+    ...checkpoint,
+    reason,
+  });
+export const buildClientRenderFailedRecord = (
+  metadata: SystemMetadata,
+  component: ClientRenderComponent,
+) =>
+  buildSystemRecord(metadata, "client.render.failed", {
+    domain: "client",
+    component,
+    reason: "react_error_boundary",
+  });
+export const buildDomainAuditAppendFailedRecord = (
+  metadata: SystemMetadata,
+  action: AuditAction,
+  reason: AuditAppendFailureReason,
+) =>
+  buildSystemRecord(metadata, "audit.append.failed", {
+    domain: "audit",
+    record_class: "domain_audit",
+    action,
+    reason,
+  });
+export const buildSecurityAccessAppendFailedRecord = (
+  metadata: SystemMetadata,
+  action: SecurityAction,
+  reason: AuditAppendFailureReason,
+) =>
+  buildSystemRecord(metadata, "audit.append.failed", {
+    domain: "audit",
+    record_class: "security_access",
+    action,
+    reason,
+  });
+export const buildTelemetryPipelineDegradedRecord = (
+  metadata: SystemMetadata,
+  component: string,
+  failure: SystemFailure,
+) =>
+  buildSystemRecord(metadata, "telemetry.pipeline.degraded", {
+    component,
+    ...failure,
+  });
+export const buildTelemetryPipelineRecoveredRecord = (
+  metadata: SystemMetadata,
+  component: string,
+) => buildSystemRecord(metadata, "telemetry.pipeline.recovered", { component });
+
+function buildSystemRecord(
+  metadata: SystemMetadata,
+  event: SystemEvent,
+  attributes: Partial<SystemRecord>,
+): SystemRecord {
+  const outcome = attributes.outcome ?? SYSTEM_EVENT_OUTCOMES[event]!;
+  const record = {
+    ...metadata,
+    ...attributes,
+    event,
+    outcome,
+  } as SystemRecord;
+  validateSystemRecord(record);
+  return record;
+}

package/src/trace.ts

@@ -0,0 +1,13 @@
+import { context, isSpanContextValid, trace } from "@opentelemetry/api";
+
+import type { Correlation } from "./records.ts";
+
+export type TraceCorrelation = Pick<Correlation, "trace_id" | "span_id">;
+
+// Browser-safe correlation primitive. Request IDs remain server RequestContext
+// state; browser-imported code can read only the active OpenTelemetry span.
+export function traceCorrelationFromActiveContext(): TraceCorrelation {
+  const spanContext = trace.getSpanContext(context.active());
+  if (spanContext === undefined || !isSpanContextValid(spanContext)) return {};
+  return { trace_id: spanContext.traceId, span_id: spanContext.spanId };
+}