deepline 0.1.222 → 0.1.224

package/dist/bundling-sources/shared_libs/observability/node-tracing.ts

@@ -0,0 +1,125 @@
+import { mkdir, appendFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import type { NodeSDK } from '@opentelemetry/sdk-node';
+import type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
+import type { ExportResult } from '@opentelemetry/core';
+
+const EXPORT_RESULT_SUCCESS = 0;
+const EXPORT_RESULT_FAILED = 1;
+
+declare global {
+  var __deeplineTracingInitPromise: Promise<boolean> | undefined;
+  var __deeplineTracingSdk: NodeSDK | undefined;
+  var __deeplineTracingShutdownPromise: Promise<void> | undefined;
+}
+
+class JsonlFileSpanExporter implements SpanExporter {
+  constructor(private readonly filePath: string) {}
+
+  async export(
+    spans: ReadableSpan[],
+    resultCallback: (result: ExportResult) => void,
+  ): Promise<void> {
+    try {
+      await mkdir(dirname(this.filePath), { recursive: true });
+      const lines = spans
+        .map((span) =>
+          JSON.stringify({
+            traceId: span.spanContext().traceId,
+            spanId: span.spanContext().spanId,
+            parentSpanId: span.parentSpanContext?.spanId ?? null,
+            name: span.name,
+            kind: span.kind,
+            startTime: span.startTime,
+            endTime: span.endTime,
+            attributes: span.attributes,
+            status: span.status,
+            resource: span.resource.attributes,
+          }),
+        )
+        .join('\n');
+      if (lines.length > 0) {
+        await appendFile(this.filePath, `${lines}\n`, 'utf-8');
+      }
+      resultCallback({ code: EXPORT_RESULT_SUCCESS });
+    } catch (error) {
+      resultCallback({
+        code: EXPORT_RESULT_FAILED,
+        error: error instanceof Error ? error : new Error(String(error)),
+      });
+    }
+  }
+
+  async shutdown(): Promise<void> {}
+  async forceFlush(): Promise<void> {}
+}
+
+async function resolveTraceExporters(): Promise<SpanExporter[]> {
+  const exporters: SpanExporter[] = [];
+  const otlpEndpoint =
+    process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT?.trim() ||
+    process.env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim() ||
+    '';
+  if (otlpEndpoint) {
+    const { OTLPTraceExporter } =
+      await import('@opentelemetry/exporter-trace-otlp-http');
+    exporters.push(new OTLPTraceExporter());
+  }
+
+  const traceFilePath = process.env.DEEPLINE_TRACE_FILE?.trim() || '';
+  if (traceFilePath) {
+    exporters.push(new JsonlFileSpanExporter(traceFilePath));
+  }
+
+  return exporters;
+}
+
+async function startNodeTracing(serviceName: string): Promise<boolean> {
+  const exporters = await resolveTraceExporters();
+  if (exporters.length === 0) {
+    return false;
+  }
+
+  if (!process.env.OTEL_SERVICE_NAME) {
+    process.env.OTEL_SERVICE_NAME = serviceName;
+  }
+
+  const [{ NodeSDK }, { BatchSpanProcessor }] = await Promise.all([
+    import('@opentelemetry/sdk-node'),
+    import('@opentelemetry/sdk-trace-base'),
+  ]);
+
+  const sdk = new NodeSDK({
+    instrumentations: [],
+    spanProcessors: exporters.map(
+      (exporter) => new BatchSpanProcessor(exporter),
+    ),
+  });
+  await sdk.start();
+  globalThis.__deeplineTracingSdk = sdk;
+  return true;
+}
+
+export async function ensureNodeTracing(serviceName: string): Promise<boolean> {
+  globalThis.__deeplineTracingInitPromise ??= startNodeTracing(serviceName);
+  return await globalThis.__deeplineTracingInitPromise;
+}
+
+export async function shutdownNodeTracing(): Promise<void> {
+  const initialized = await (globalThis.__deeplineTracingInitPromise ??
+    Promise.resolve(false));
+  if (!initialized) {
+    return;
+  }
+
+  const sdk = globalThis.__deeplineTracingSdk;
+  if (!sdk) {
+    return;
+  }
+
+  globalThis.__deeplineTracingShutdownPromise ??= sdk.shutdown().finally(() => {
+    globalThis.__deeplineTracingSdk = undefined;
+    globalThis.__deeplineTracingInitPromise = undefined;
+  });
+  await globalThis.__deeplineTracingShutdownPromise;
+}

package/dist/bundling-sources/shared_libs/observability/redaction.ts

@@ -0,0 +1,94 @@
+const SENSITIVE_FIELD_NAME =
+  'authorization|cookie|password|secret|client[_-]?secret|access[_-]?token|refresh[_-]?token|(?:x[_-]?)?api[_-]?key|private[_-]?key|token|credentials';
+const INLINE_SECRET_FIELD_NAME =
+  'cookie|password|secret|client[_-]?secret|access[_-]?token|refresh[_-]?token|(?:x[_-]?)?api[_-]?key|token|credentials';
+const SENSITIVE_FIELD_PATTERN = new RegExp(
+  `(^|[._-])(${SENSITIVE_FIELD_NAME})$`,
+  'i',
+);
+const BEARER_CREDENTIAL_PATTERN = /\bBearer\s+[A-Za-z0-9._~+/=-]+/gi;
+const BASIC_CREDENTIAL_PATTERN =
+  /\bBasic\s+[A-Za-z0-9+/]{4,}={0,2}(?=\s|$|[,;])/gi;
+const PRIVATE_KEY_PATTERN =
+  /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/gi;
+const AUTHORIZATION_CREDENTIAL_PATTERN =
+  /\b(authorization)(\s*[:=]\s*)(Bearer|Basic)\s+\S+/gi;
+const JWT_PATTERN =
+  /\b[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{1,}\.[A-Za-z0-9_-]{8,}\b/g;
+const JSON_SECRET_PATTERN = new RegExp(
+  `(["'])(${SENSITIVE_FIELD_NAME})\\1(\\s*:\\s*)(["'])(.*?)\\4`,
+  'gi',
+);
+const INLINE_SECRET_PATTERN = new RegExp(
+  `\\b(${INLINE_SECRET_FIELD_NAME})(\\s*[:=]\\s*)([^\\s,;]+)`,
+  'gi',
+);
+
+/** Whether a structured telemetry field name must never retain its value. */
+export function isSensitiveTelemetryFieldName(value: string): boolean {
+  return SENSITIVE_FIELD_PATTERN.test(value);
+}
+
+function redactStructuredValue(
+  key: string,
+  value: unknown,
+  seen = new WeakSet<object>(),
+): unknown {
+  if (isSensitiveTelemetryFieldName(key)) return '[REDACTED]';
+  if (typeof value === 'string') return redactPlainTelemetryText(value);
+  if (!value || typeof value !== 'object') return value;
+  if (seen.has(value)) return '[circular]';
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const redacted = value.map((item) =>
+      redactStructuredValue('item', item, seen),
+    );
+    seen.delete(value);
+    return redacted;
+  }
+  const redacted = Object.fromEntries(
+    Object.entries(value).map(([childKey, childValue]) => [
+      childKey,
+      redactStructuredValue(childKey, childValue, seen),
+    ]),
+  );
+  seen.delete(value);
+  return redacted;
+}
+
+function redactPlainTelemetryText(value: string): string {
+  return value
+    .replace(PRIVATE_KEY_PATTERN, '[REDACTED]')
+    .replace(AUTHORIZATION_CREDENTIAL_PATTERN, '$1$2$3 [REDACTED]')
+    .replace(BEARER_CREDENTIAL_PATTERN, 'Bearer [REDACTED]')
+    .replace(BASIC_CREDENTIAL_PATTERN, 'Basic [REDACTED]')
+    .replace(JWT_PATTERN, '[REDACTED_JWT]')
+    .replace(
+      JSON_SECRET_PATTERN,
+      (_match, keyQuote, key, separator, valueQuote) =>
+        `${keyQuote}${key}${keyQuote}${separator}${valueQuote}[REDACTED]${valueQuote}`,
+    )
+    .replace(INLINE_SECRET_PATTERN, '$1$2[REDACTED]');
+}
+
+/**
+ * Redact credentials from arbitrary diagnostic text. Kept dependency-free so
+ * the play-worker bundle can share exactly the same base redaction rules as
+ * server telemetry without importing the full telemetry emitter.
+ */
+export function redactTelemetryText(value: string): string {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith('{') && trimmed.endsWith('}')) ||
+    (trimmed.startsWith('[') && trimmed.endsWith(']'))
+  ) {
+    try {
+      return JSON.stringify(
+        redactStructuredValue('serializedJson', JSON.parse(trimmed)),
+      );
+    } catch {
+      // Non-JSON diagnostic strings still use pattern-based redaction below.
+    }
+  }
+  return redactPlainTelemetryText(value);
+}

package/dist/bundling-sources/shared_libs/observability/telemetry.ts

@@ -0,0 +1,414 @@
+import {
+  isSensitiveTelemetryFieldName,
+  redactTelemetryText,
+} from './redaction';
+
+export { isSensitiveTelemetryFieldName } from './redaction';
+
+export const TELEMETRY_SCHEMA_VERSION = 1 as const;
+
+export type TelemetryScalar = string | number | boolean | null | undefined;
+export type TelemetryValue =
+  | Exclude<TelemetryScalar, undefined>
+  | readonly TelemetryValue[]
+  | { readonly [key: string]: TelemetryValue };
+export type TelemetryFields = Readonly<Record<string, unknown>>;
+
+export type TelemetryContext = {
+  environment?: string | null;
+  release?: string | null;
+  orgId?: string | null;
+  orgName?: string | null;
+  userId?: string | null;
+  apiKeyId?: string | null;
+  authType?: string | null;
+  requestId?: string | null;
+  runId?: string | null;
+  workflowId?: string | null;
+  workflowName?: string | null;
+  workflowOrigin?: string | null;
+  playName?: string | null;
+  machineId?: string | null;
+};
+
+export type TelemetryLevel = 'debug' | 'info' | 'warn' | 'error';
+export type TelemetryMetricKind = 'counter' | 'gauge' | 'distribution';
+export type TelemetrySpanOutcome = 'ok' | 'error';
+
+type TelemetryEventBase = {
+  telemetrySchemaVersion: typeof TELEMETRY_SCHEMA_VERSION;
+  timestamp: string;
+  service: string;
+  component: string | null;
+  event: string;
+  tag: string;
+} & Omit<TelemetryContext, never> &
+  Record<string, TelemetryValue | undefined>;
+
+export type TelemetryLogEvent = TelemetryEventBase & {
+  telemetryKind: 'log';
+  telemetryLevel: TelemetryLevel;
+  errorType?: string;
+  errorMessage?: string;
+};
+
+export type TelemetryMetricEvent = TelemetryEventBase & {
+  telemetryKind: 'metric';
+  telemetryMetricKind: TelemetryMetricKind;
+  telemetryMetricValue: number;
+  telemetryMetricUnit: string | null;
+};
+
+export type TelemetrySpanEvent = TelemetryEventBase & {
+  telemetryKind: 'span';
+  telemetryLevel: 'info' | 'error';
+  spanDurationMs: number;
+  spanOutcome: TelemetrySpanOutcome;
+  errorType?: string;
+  errorMessage?: string;
+};
+
+export type TelemetryEvent =
+  | TelemetryLogEvent
+  | TelemetryMetricEvent
+  | TelemetrySpanEvent;
+
+export type TelemetryAdapter = {
+  emit(event: TelemetryEvent): void | Promise<void>;
+};
+
+export type TelemetryEventOptions = { tag?: string };
+
+export type Telemetry = {
+  child(input: { component?: string; context?: TelemetryContext }): Telemetry;
+  debug(
+    event: string,
+    fields?: TelemetryFields,
+    options?: TelemetryEventOptions,
+  ): Promise<void>;
+  info(
+    event: string,
+    fields?: TelemetryFields,
+    options?: TelemetryEventOptions,
+  ): Promise<void>;
+  warn(
+    event: string,
+    fields?: TelemetryFields,
+    options?: TelemetryEventOptions,
+  ): Promise<void>;
+  error(
+    event: string,
+    error?: unknown,
+    fields?: TelemetryFields,
+    options?: TelemetryEventOptions,
+  ): Promise<void>;
+  counter(
+    metric: string,
+    value?: number,
+    fields?: TelemetryFields,
+  ): Promise<void>;
+  gauge(metric: string, value: number, fields?: TelemetryFields): Promise<void>;
+  distribution(
+    metric: string,
+    value: number,
+    options?: { unit?: string; fields?: TelemetryFields },
+  ): Promise<void>;
+  time<T>(
+    span: string,
+    fields: TelemetryFields | undefined,
+    fn: () => Promise<T> | T,
+  ): Promise<T>;
+};
+
+type CreateTelemetryInput = {
+  service: string;
+  component?: string;
+  context?: TelemetryContext;
+  adapter?: TelemetryAdapter;
+  now?: () => Date;
+};
+
+const MAX_FIELD_STRING_LENGTH = 8_000;
+const MAX_FIELD_DEPTH = 8;
+const MAX_ARRAY_ITEMS = 100;
+const MAX_OBJECT_KEYS = 100;
+
+const RESERVED_FIELDS = new Set([
+  'telemetrySchemaVersion',
+  'timestamp',
+  'service',
+  'component',
+  'event',
+  'tag',
+  'telemetryKind',
+  'telemetryLevel',
+  'telemetryMetricKind',
+  'telemetryMetricValue',
+  'telemetryMetricUnit',
+  'spanDurationMs',
+  'spanOutcome',
+  'environment',
+  'release',
+  'orgId',
+  'orgName',
+  'userId',
+  'apiKeyId',
+  'authType',
+  'requestId',
+  'runId',
+  'workflowId',
+  'workflowName',
+  'workflowOrigin',
+  'playName',
+  'machineId',
+]);
+
+function normalizeName(value: string, label: string): string {
+  const normalized = value.trim();
+  if (!normalized) throw new Error(`${label} must not be empty.`);
+  return normalized;
+}
+
+export function redactTelemetryString(value: string): string {
+  return redactTelemetryText(value);
+}
+
+function normalizeFieldValue(
+  key: string,
+  value: unknown,
+  depth = 0,
+  seen = new WeakSet<object>(),
+): TelemetryValue | undefined {
+  if (isSensitiveTelemetryFieldName(key)) return '[REDACTED]';
+  if (value === null) return null;
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : undefined;
+  }
+  if (typeof value === 'string') {
+    const redacted = redactTelemetryString(value);
+    if (redacted.length <= MAX_FIELD_STRING_LENGTH) return redacted;
+    return `${redacted.slice(0, MAX_FIELD_STRING_LENGTH)}…`;
+  }
+  if (typeof value === 'bigint') return String(value);
+  if (value instanceof Date) return value.toISOString();
+  if (value instanceof Error) {
+    return {
+      name: value.name || 'Error',
+      message: normalizeFieldValue(
+        'message',
+        value.message,
+        depth + 1,
+        seen,
+      ) as string,
+    };
+  }
+  if (typeof value !== 'object' || value === undefined) return undefined;
+  if (depth >= MAX_FIELD_DEPTH) return '[max-depth]';
+  if (seen.has(value)) return '[circular]';
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const normalized = value
+      .slice(0, MAX_ARRAY_ITEMS)
+      .map(
+        (item) => normalizeFieldValue('item', item, depth + 1, seen) ?? null,
+      );
+    if (value.length > MAX_ARRAY_ITEMS) normalized.push('[truncated]');
+    seen.delete(value);
+    return normalized;
+  }
+  const normalized: Record<string, TelemetryValue> = {};
+  const entries = Object.entries(value).slice(0, MAX_OBJECT_KEYS);
+  for (const [childKey, childValue] of entries) {
+    const item = normalizeFieldValue(childKey, childValue, depth + 1, seen);
+    if (item !== undefined) normalized[childKey] = item;
+  }
+  if (Object.keys(value).length > MAX_OBJECT_KEYS) {
+    normalized.__truncated__ = true;
+  }
+  seen.delete(value);
+  return normalized;
+}
+
+function normalizeFields(fields: TelemetryFields | undefined) {
+  const normalized: Record<string, TelemetryValue> = {};
+  for (const [key, value] of Object.entries(fields ?? {})) {
+    if (RESERVED_FIELDS.has(key) || value === undefined) continue;
+    const normalizedValue = normalizeFieldValue(key, value);
+    if (normalizedValue !== undefined) normalized[key] = normalizedValue;
+  }
+  return normalized;
+}
+
+function normalizeContext(context: TelemetryContext | undefined) {
+  return Object.fromEntries(
+    Object.entries(context ?? {}).filter(([, value]) => value !== undefined),
+  ) as TelemetryContext;
+}
+
+function errorFields(
+  error: unknown,
+): Partial<Pick<TelemetrySpanEvent, 'errorType' | 'errorMessage'>> {
+  if (error === undefined || error === null) return {};
+  if (error instanceof Error) {
+    return {
+      errorType: error.name || 'Error',
+      errorMessage: redactTelemetryString(error.message),
+    };
+  }
+  return {
+    errorType: 'Error',
+    errorMessage: redactTelemetryString(String(error)),
+  };
+}
+
+export function createConsoleTelemetryAdapter(input?: {
+  console?: Pick<Console, 'debug' | 'info' | 'warn' | 'error'>;
+}): TelemetryAdapter {
+  const target = input?.console ?? console;
+  return {
+    emit(event) {
+      const line = JSON.stringify(event);
+      if (event.telemetryKind === 'log') target[event.telemetryLevel](line);
+      else if (event.telemetryKind === 'span' && event.spanOutcome === 'error')
+        target.error(line);
+      else target.info(line);
+    },
+  };
+}
+
+export function composeTelemetryAdapters(
+  ...adapters: readonly TelemetryAdapter[]
+): TelemetryAdapter {
+  return {
+    async emit(event) {
+      await Promise.allSettled(
+        adapters.map((adapter) =>
+          Promise.resolve().then(() => adapter.emit(event)),
+        ),
+      );
+    },
+  };
+}
+
+export function createTelemetry(input: CreateTelemetryInput): Telemetry {
+  const service = normalizeName(input.service, 'Telemetry service');
+  const component = input.component?.trim() || null;
+  const context = normalizeContext(input.context);
+  const adapter = input.adapter ?? createConsoleTelemetryAdapter();
+  const now = input.now ?? (() => new Date());
+
+  function base(
+    event: string,
+    options?: TelemetryEventOptions,
+  ): TelemetryEventBase {
+    const eventName = normalizeName(event, 'Telemetry event');
+    return {
+      telemetrySchemaVersion: TELEMETRY_SCHEMA_VERSION,
+      timestamp: now().toISOString(),
+      service,
+      component,
+      event: eventName,
+      tag: options?.tag?.trim() || `[${eventName}]`,
+      ...context,
+    };
+  }
+
+  async function publish(event: TelemetryEvent): Promise<void> {
+    try {
+      await adapter.emit(event);
+    } catch {
+      // Product execution must not depend on operational telemetry delivery.
+    }
+  }
+
+  async function log(
+    level: TelemetryLevel,
+    event: string,
+    fields?: TelemetryFields,
+    options?: TelemetryEventOptions,
+  ) {
+    await publish({
+      ...base(event, options),
+      ...normalizeFields(fields),
+      telemetryKind: 'log',
+      telemetryLevel: level,
+    });
+  }
+
+  async function metric(
+    metricKind: TelemetryMetricKind,
+    name: string,
+    value: number,
+    unit: string | undefined,
+    fields: TelemetryFields | undefined,
+  ) {
+    if (!Number.isFinite(value)) {
+      throw new Error(`Telemetry metric ${name} must have a finite value.`);
+    }
+    await publish({
+      ...base(name),
+      ...normalizeFields(fields),
+      telemetryKind: 'metric',
+      telemetryMetricKind: metricKind,
+      telemetryMetricValue: value,
+      telemetryMetricUnit: unit?.trim() || null,
+    });
+  }
+
+  return {
+    child(childInput) {
+      return createTelemetry({
+        service,
+        component: childInput.component ?? component ?? undefined,
+        context: { ...context, ...normalizeContext(childInput.context) },
+        adapter,
+        now,
+      });
+    },
+    debug: (event, fields, options) => log('debug', event, fields, options),
+    info: (event, fields, options) => log('info', event, fields, options),
+    warn: (event, fields, options) => log('warn', event, fields, options),
+    async error(event, error, fields, options) {
+      await publish({
+        ...base(event, options),
+        ...normalizeFields(fields),
+        telemetryKind: 'log',
+        telemetryLevel: 'error',
+        ...errorFields(error),
+      });
+    },
+    counter: (name, value = 1, fields) =>
+      metric('counter', name, value, undefined, fields),
+    gauge: (name, value, fields) =>
+      metric('gauge', name, value, undefined, fields),
+    distribution: (name, value, options) =>
+      metric('distribution', name, value, options?.unit, options?.fields),
+    async time(span, fields, fn) {
+      const startedAt = performance.now();
+      try {
+        const result = await fn();
+        await publish({
+          ...base(span),
+          ...normalizeFields(fields),
+          telemetryKind: 'span',
+          telemetryLevel: 'info',
+          spanDurationMs: performance.now() - startedAt,
+          spanOutcome: 'ok',
+        });
+        return result;
+      } catch (error) {
+        await publish({
+          ...base(span),
+          ...normalizeFields(fields),
+          telemetryKind: 'span',
+          telemetryLevel: 'error',
+          spanDurationMs: performance.now() - startedAt,
+          spanOutcome: 'error',
+          ...errorFields(error),
+        });
+        throw error;
+      }
+    },
+  };
+}