apcore-js 0.5.0 → 0.6.0

package/src/observability/context-logger.ts

@@ -1,203 +0,0 @@
-/**
- * Structured logging: ContextLogger and ObsLoggingMiddleware.
- */
-
-import type { Context } from '../context.js';
-import { Middleware } from '../middleware/base.js';
-
-const LEVELS: Record<string, number> = {
-  trace: 0,
-  debug: 10,
-  info: 20,
-  warn: 30,
-  error: 40,
-  fatal: 50,
-};
-
-const REDACTED = '***REDACTED***';
-
-interface WritableOutput {
-  write(s: string): void;
-}
-
-export class ContextLogger {
-  private _name: string;
-  private _format: string;
-  private _level: string;
-  private _levelValue: number;
-  private _redactSensitive: boolean;
-  private _output: WritableOutput;
-  private _traceId: string | null = null;
-  private _moduleId: string | null = null;
-  private _callerId: string | null = null;
-
-  constructor(options?: {
-    name?: string;
-    format?: string;
-    level?: string;
-    redactSensitive?: boolean;
-    output?: WritableOutput;
-  }) {
-    this._name = options?.name ?? 'apcore';
-    this._format = options?.format ?? 'json';
-    this._level = options?.level ?? 'info';
-    this._levelValue = LEVELS[this._level] ?? 20;
-    this._redactSensitive = options?.redactSensitive ?? true;
-    this._output = options?.output ?? { write: (s: string) => process.stderr.write(s) };
-  }
-
-  static fromContext(context: Context, name: string, options?: {
-    format?: string;
-    level?: string;
-    redactSensitive?: boolean;
-    output?: WritableOutput;
-  }): ContextLogger {
-    const logger = new ContextLogger({ name, ...options });
-    logger._traceId = context.traceId;
-    logger._moduleId = context.callChain.length > 0 ? context.callChain[context.callChain.length - 1] : null;
-    logger._callerId = context.callerId;
-    return logger;
-  }
-
-  private _emit(levelName: string, message: string, extra?: Record<string, unknown> | null): void {
-    const levelValue = LEVELS[levelName] ?? 20;
-    if (levelValue < this._levelValue) return;
-
-    let redactedExtra = extra ?? null;
-    if (extra != null && this._redactSensitive) {
-      redactedExtra = {};
-      for (const [k, v] of Object.entries(extra)) {
-        (redactedExtra as Record<string, unknown>)[k] = k.startsWith('_secret_') ? REDACTED : v;
-      }
-    }
-
-    const now = new Date();
-    const entry: Record<string, unknown> = {
-      timestamp: now.toISOString(),
-      level: levelName,
-      message,
-      trace_id: this._traceId,
-      module_id: this._moduleId,
-      caller_id: this._callerId,
-      logger: this._name,
-      extra: redactedExtra,
-    };
-
-    if (this._format === 'json') {
-      this._output.write(JSON.stringify(entry) + '\n');
-    } else {
-      const ts = now.toISOString().replace('T', ' ').replace(/\.\d+Z$/, '');
-      const lvl = levelName.toUpperCase();
-      const trace = this._traceId ?? 'none';
-      const mod = this._moduleId ?? 'none';
-      let extrasStr = '';
-      if (redactedExtra) {
-        extrasStr = ' ' + Object.entries(redactedExtra).map(([k, v]) => `${k}=${v}`).join(' ');
-      }
-      this._output.write(`${ts} [${lvl}] [trace=${trace}] [module=${mod}] ${message}${extrasStr}\n`);
-    }
-  }
-
-  trace(message: string, extra?: Record<string, unknown>): void {
-    this._emit('trace', message, extra);
-  }
-
-  debug(message: string, extra?: Record<string, unknown>): void {
-    this._emit('debug', message, extra);
-  }
-
-  info(message: string, extra?: Record<string, unknown>): void {
-    this._emit('info', message, extra);
-  }
-
-  warn(message: string, extra?: Record<string, unknown>): void {
-    this._emit('warn', message, extra);
-  }
-
-  error(message: string, extra?: Record<string, unknown>): void {
-    this._emit('error', message, extra);
-  }
-
-  fatal(message: string, extra?: Record<string, unknown>): void {
-    this._emit('fatal', message, extra);
-  }
-}
-
-export class ObsLoggingMiddleware extends Middleware {
-  private _logger: ContextLogger;
-  private _logInputs: boolean;
-  private _logOutputs: boolean;
-
-  constructor(options?: {
-    logger?: ContextLogger;
-    logInputs?: boolean;
-    logOutputs?: boolean;
-  }) {
-    super();
-    this._logger = options?.logger ?? new ContextLogger({ name: 'apcore.obs_logging' });
-    this._logInputs = options?.logInputs ?? true;
-    this._logOutputs = options?.logOutputs ?? true;
-  }
-
-  override before(
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    context: Context,
-  ): null {
-    const starts = (context.data['_obs_logging_starts'] as number[]) ?? [];
-    starts.push(performance.now());
-    context.data['_obs_logging_starts'] = starts;
-
-    const extra: Record<string, unknown> = {
-      module_id: moduleId,
-      caller_id: context.callerId,
-    };
-    if (this._logInputs) {
-      extra['inputs'] = context.redactedInputs ?? inputs;
-    }
-    this._logger.info('Module call started', extra);
-    return null;
-  }
-
-  override after(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    output: Record<string, unknown>,
-    context: Context,
-  ): null {
-    const starts = context.data['_obs_logging_starts'] as number[] | undefined;
-    if (!starts || starts.length === 0) return null;
-    const startTime = starts.pop()!;
-    const durationMs = performance.now() - startTime;
-
-    const extra: Record<string, unknown> = {
-      module_id: moduleId,
-      duration_ms: durationMs,
-    };
-    if (this._logOutputs) {
-      extra['output'] = output;
-    }
-    this._logger.info('Module call completed', extra);
-    return null;
-  }
-
-  override onError(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    error: Error,
-    context: Context,
-  ): null {
-    const starts = context.data['_obs_logging_starts'] as number[] | undefined;
-    if (!starts || starts.length === 0) return null;
-    const startTime = starts.pop()!;
-    const durationMs = performance.now() - startTime;
-
-    this._logger.error('Module call failed', {
-      module_id: moduleId,
-      duration_ms: durationMs,
-      error_type: error.constructor.name,
-      error_message: String(error),
-    });
-    return null;
-  }
-}

package/src/observability/metrics.ts

@@ -1,214 +0,0 @@
-/**
- * In-memory metrics collection with Prometheus export.
- */
-
-import type { Context } from '../context.js';
-import { ModuleError } from '../errors.js';
-import { Middleware } from '../middleware/base.js';
-
-const DESCRIPTIONS: Record<string, string> = {
-  apcore_module_calls_total: 'Total module calls',
-  apcore_module_errors_total: 'Total module errors',
-  apcore_module_duration_seconds: 'Module execution duration',
-};
-
-function labelsKey(labels: Record<string, string>): string {
-  return Object.entries(labels).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}=${v}`).join(',');
-}
-
-export class MetricsCollector {
-  static readonly DEFAULT_BUCKETS: number[] = [
-    0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0, 60.0,
-  ];
-
-  private _buckets: number[];
-  private _counters: Map<string, number> = new Map();
-  private _histogramSums: Map<string, number> = new Map();
-  private _histogramCounts: Map<string, number> = new Map();
-  private _histogramBuckets: Map<string, number> = new Map();
-
-  constructor(buckets?: number[]) {
-    this._buckets = buckets ? [...buckets].sort((a, b) => a - b) : [...MetricsCollector.DEFAULT_BUCKETS];
-  }
-
-  increment(name: string, labels: Record<string, string>, amount: number = 1): void {
-    const key = `${name}|${labelsKey(labels)}`;
-    this._counters.set(key, (this._counters.get(key) ?? 0) + amount);
-  }
-
-  observe(name: string, labels: Record<string, string>, value: number): void {
-    const lk = labelsKey(labels);
-    const key = `${name}|${lk}`;
-
-    this._histogramSums.set(key, (this._histogramSums.get(key) ?? 0) + value);
-    this._histogramCounts.set(key, (this._histogramCounts.get(key) ?? 0) + 1);
-
-    for (const b of this._buckets) {
-      if (value <= b) {
-        const bkey = `${name}|${lk}|${b}`;
-        this._histogramBuckets.set(bkey, (this._histogramBuckets.get(bkey) ?? 0) + 1);
-      }
-    }
-    // +Inf bucket
-    const infKey = `${name}|${lk}|Inf`;
-    this._histogramBuckets.set(infKey, (this._histogramBuckets.get(infKey) ?? 0) + 1);
-  }
-
-  snapshot(): Record<string, unknown> {
-    return {
-      counters: Object.fromEntries(this._counters),
-      histograms: {
-        sums: Object.fromEntries(this._histogramSums),
-        counts: Object.fromEntries(this._histogramCounts),
-        buckets: Object.fromEntries(this._histogramBuckets),
-      },
-    };
-  }
-
-  reset(): void {
-    this._counters.clear();
-    this._histogramSums.clear();
-    this._histogramCounts.clear();
-    this._histogramBuckets.clear();
-  }
-
-  exportPrometheus(): string {
-    const lines: string[] = [];
-    const counterNames = new Set<string>();
-    const histNames = new Set<string>();
-
-    // Counters
-    for (const [compositeKey, value] of [...this._counters.entries()].sort()) {
-      const [name, lk] = compositeKey.split('|', 2);
-      if (!counterNames.has(name)) {
-        const desc = DESCRIPTIONS[name] ?? name;
-        lines.push(`# HELP ${name} ${desc}`);
-        lines.push(`# TYPE ${name} counter`);
-        counterNames.add(name);
-      }
-      const labelsStr = formatLabels(parseLabels(lk));
-      lines.push(`${name}${labelsStr} ${value}`);
-    }
-
-    // Histograms
-    const histKeys = [...this._histogramSums.keys()].sort();
-    for (const compositeKey of histKeys) {
-      const [name, lk] = compositeKey.split('|', 2);
-      if (!histNames.has(name)) {
-        const desc = DESCRIPTIONS[name] ?? name;
-        lines.push(`# HELP ${name} ${desc}`);
-        lines.push(`# TYPE ${name} histogram`);
-        histNames.add(name);
-      }
-
-      const labelsDict = parseLabels(lk);
-      const labelsStr = formatLabels(labelsDict);
-
-      for (const b of this._buckets) {
-        const bkey = `${name}|${lk}|${b}`;
-        const count = this._histogramBuckets.get(bkey) ?? 0;
-        const leStr = String(b);
-        const leLabels = { ...labelsDict, le: leStr };
-        lines.push(`${name}_bucket${formatLabels(leLabels)} ${count}`);
-      }
-
-      const infKey = `${name}|${lk}|Inf`;
-      const infCount = this._histogramBuckets.get(infKey) ?? 0;
-      const infLabels = { ...labelsDict, le: '+Inf' };
-      lines.push(`${name}_bucket${formatLabels(infLabels)} ${infCount}`);
-
-      const sumVal = this._histogramSums.get(compositeKey) ?? 0;
-      const countVal = this._histogramCounts.get(compositeKey) ?? 0;
-      lines.push(`${name}_sum${labelsStr} ${sumVal}`);
-      lines.push(`${name}_count${labelsStr} ${countVal}`);
-    }
-
-    return lines.length > 0 ? lines.join('\n') + '\n' : '';
-  }
-
-  incrementCalls(moduleId: string, status: string): void {
-    this.increment('apcore_module_calls_total', { module_id: moduleId, status });
-  }
-
-  incrementErrors(moduleId: string, errorCode: string): void {
-    this.increment('apcore_module_errors_total', { module_id: moduleId, error_code: errorCode });
-  }
-
-  observeDuration(moduleId: string, durationSeconds: number): void {
-    this.observe('apcore_module_duration_seconds', { module_id: moduleId }, durationSeconds);
-  }
-}
-
-function parseLabels(lk: string): Record<string, string> {
-  if (!lk) return {};
-  const result: Record<string, string> = {};
-  for (const pair of lk.split(',')) {
-    const [k, v] = pair.split('=', 2);
-    if (k) result[k] = v ?? '';
-  }
-  return result;
-}
-
-function formatLabels(labels: Record<string, string>): string {
-  const entries = Object.entries(labels);
-  if (entries.length === 0) return '';
-  const sorted = entries.sort(([a], [b]) => {
-    if (a === 'le') return 1;
-    if (b === 'le') return -1;
-    return a.localeCompare(b);
-  });
-  const pairs = sorted.map(([k, v]) => `${k}="${v}"`).join(',');
-  return `{${pairs}}`;
-}
-
-export class MetricsMiddleware extends Middleware {
-  private _collector: MetricsCollector;
-
-  constructor(collector: MetricsCollector) {
-    super();
-    this._collector = collector;
-  }
-
-  override before(
-    _moduleId: string,
-    _inputs: Record<string, unknown>,
-    context: Context,
-  ): null {
-    const starts = (context.data['_metrics_starts'] as number[]) ?? [];
-    starts.push(performance.now());
-    context.data['_metrics_starts'] = starts;
-    return null;
-  }
-
-  override after(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    _output: Record<string, unknown>,
-    context: Context,
-  ): null {
-    const starts = context.data['_metrics_starts'] as number[] | undefined;
-    if (!starts || starts.length === 0) return null;
-    const startTime = starts.pop()!;
-    const durationS = (performance.now() - startTime) / 1000;
-    this._collector.incrementCalls(moduleId, 'success');
-    this._collector.observeDuration(moduleId, durationS);
-    return null;
-  }
-
-  override onError(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    error: Error,
-    context: Context,
-  ): null {
-    const starts = context.data['_metrics_starts'] as number[] | undefined;
-    if (!starts || starts.length === 0) return null;
-    const startTime = starts.pop()!;
-    const durationS = (performance.now() - startTime) / 1000;
-    const errorCode = error instanceof ModuleError ? error.code : error.constructor.name;
-    this._collector.incrementCalls(moduleId, 'error');
-    this._collector.incrementErrors(moduleId, errorCode);
-    this._collector.observeDuration(moduleId, durationS);
-    return null;
-  }
-}

package/src/observability/tracing.ts

@@ -1,252 +0,0 @@
-/**
- * Tracing system: Span, SpanExporter implementations, and TracingMiddleware.
- */
-
-import { randomBytes } from 'node:crypto';
-import type { Context } from '../context.js';
-import { Middleware } from '../middleware/base.js';
-
-export interface Span {
-  traceId: string;
-  name: string;
-  startTime: number;
-  spanId: string;
-  parentSpanId: string | null;
-  attributes: Record<string, unknown>;
-  endTime: number | null;
-  status: string;
-  events: Array<Record<string, unknown>>;
-}
-
-export function createSpan(options: {
-  traceId: string;
-  name: string;
-  startTime: number;
-  spanId?: string;
-  parentSpanId?: string | null;
-  attributes?: Record<string, unknown>;
-}): Span {
-  return {
-    traceId: options.traceId,
-    name: options.name,
-    startTime: options.startTime,
-    spanId: options.spanId ?? randomBytes(8).toString('hex'),
-    parentSpanId: options.parentSpanId ?? null,
-    attributes: options.attributes ?? {},
-    endTime: null,
-    status: 'ok',
-    events: [],
-  };
-}
-
-export interface SpanExporter {
-  export(span: Span): void;
-}
-
-export class StdoutExporter implements SpanExporter {
-  export(span: Span): void {
-    process.stdout.write(JSON.stringify(span) + '\n');
-  }
-}
-
-export class InMemoryExporter implements SpanExporter {
-  private _spans: Span[] = [];
-  private _maxSpans: number;
-
-  constructor(maxSpans: number = 10_000) {
-    this._maxSpans = maxSpans;
-  }
-
-  export(span: Span): void {
-    if (this._spans.length >= this._maxSpans) {
-      // Drop oldest half to amortize the cost instead of O(n) shift per insert
-      this._spans = this._spans.slice(Math.floor(this._maxSpans / 2));
-    }
-    this._spans.push(span);
-  }
-
-  getSpans(): Span[] {
-    return [...this._spans];
-  }
-
-  clear(): void {
-    this._spans = [];
-  }
-}
-
-export class OTLPExporter implements SpanExporter {
-  private _endpoint: string;
-  private _serviceName: string;
-  private _headers: Record<string, string>;
-
-  constructor(options?: {
-    endpoint?: string;
-    serviceName?: string;
-    headers?: Record<string, string>;
-  }) {
-    this._endpoint = options?.endpoint ?? 'http://localhost:4318/v1/traces';
-    this._serviceName = options?.serviceName ?? 'apcore';
-    this._headers = options?.headers ?? {};
-  }
-
-  export(span: Span): void {
-    const payload = {
-      resourceSpans: [{
-        resource: {
-          attributes: [
-            { key: 'service.name', value: { stringValue: this._serviceName } },
-          ],
-        },
-        scopeSpans: [{
-          scope: { name: 'apcore' },
-          spans: [{
-            traceId: span.traceId,
-            spanId: span.spanId,
-            parentSpanId: span.parentSpanId ?? undefined,
-            name: span.name,
-            startTimeUnixNano: String(Math.round(span.startTime * 1_000_000_000)),
-            endTimeUnixNano: span.endTime ? String(Math.round(span.endTime * 1_000_000_000)) : undefined,
-            status: { code: span.status === 'ok' ? 1 : 2 },
-            attributes: Object.entries(span.attributes).map(([key, value]) => ({
-              key,
-              value: { stringValue: String(value) },
-            })),
-          }],
-        }],
-      }],
-    };
-
-    // Fire-and-forget POST
-    fetch(this._endpoint, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        ...this._headers,
-      },
-      body: JSON.stringify(payload),
-    }).catch(() => {
-      // Silently ignore network errors
-    });
-  }
-}
-
-const VALID_STRATEGIES = new Set(['full', 'proportional', 'error_first', 'off']);
-
-export class TracingMiddleware extends Middleware {
-  private _exporter: SpanExporter;
-  private _samplingRate: number;
-  private _samplingStrategy: string;
-
-  constructor(
-    exporter: SpanExporter,
-    samplingRate: number = 1.0,
-    samplingStrategy: string = 'full',
-  ) {
-    super();
-    if (samplingRate < 0.0 || samplingRate > 1.0) {
-      throw new Error(`sampling_rate must be between 0.0 and 1.0, got ${samplingRate}`);
-    }
-    if (!VALID_STRATEGIES.has(samplingStrategy)) {
-      throw new Error(`sampling_strategy must be one of ${[...VALID_STRATEGIES].join(', ')}, got '${samplingStrategy}'`);
-    }
-    this._exporter = exporter;
-    this._samplingRate = samplingRate;
-    this._samplingStrategy = samplingStrategy;
-  }
-
-  /** Replace the span exporter used by this middleware. */
-  setExporter(exporter: SpanExporter): void {
-    if (!exporter || typeof exporter.export !== 'function') {
-      throw new Error('exporter must implement SpanExporter interface');
-    }
-    this._exporter = exporter;
-  }
-
-  private _shouldSample(context: Context): boolean {
-    const existing = context.data['_tracing_sampled'];
-    if (typeof existing === 'boolean') return existing;
-
-    let decision: boolean;
-    if (this._samplingStrategy === 'full') {
-      decision = true;
-    } else if (this._samplingStrategy === 'off') {
-      decision = false;
-    } else {
-      decision = Math.random() < this._samplingRate;
-    }
-
-    context.data['_tracing_sampled'] = decision;
-    return decision;
-  }
-
-  override before(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    context: Context,
-  ): null {
-    this._shouldSample(context);
-
-    const spansStack = (context.data['_tracing_spans'] as Span[]) ?? [];
-    context.data['_tracing_spans'] = spansStack;
-    const parentSpanId = spansStack.length > 0 ? spansStack[spansStack.length - 1].spanId : null;
-
-    const span = createSpan({
-      traceId: context.traceId,
-      name: 'apcore.module.execute',
-      startTime: Date.now() / 1000,
-      parentSpanId,
-      attributes: {
-        moduleId,
-        method: 'execute',
-        callerId: context.callerId,
-      },
-    });
-    spansStack.push(span);
-    return null;
-  }
-
-  override after(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    _output: Record<string, unknown>,
-    context: Context,
-  ): null {
-    const spansStack = (context.data['_tracing_spans'] as Span[]) ?? [];
-    if (spansStack.length === 0) return null;
-
-    const span = spansStack.pop()!;
-    span.endTime = Date.now() / 1000;
-    span.status = 'ok';
-    span.attributes['duration_ms'] = (span.endTime - span.startTime) * 1000;
-    span.attributes['success'] = true;
-
-    if (context.data['_tracing_sampled']) {
-      this._exporter.export(span);
-    }
-    return null;
-  }
-
-  override onError(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    error: Error,
-    context: Context,
-  ): null {
-    const spansStack = (context.data['_tracing_spans'] as Span[]) ?? [];
-    if (spansStack.length === 0) return null;
-
-    const span = spansStack.pop()!;
-    span.endTime = Date.now() / 1000;
-    span.status = 'error';
-    span.attributes['duration_ms'] = (span.endTime - span.startTime) * 1000;
-    span.attributes['success'] = false;
-    span.attributes['error_code'] = (error as unknown as Record<string, unknown>)['code'] ?? error.constructor.name;
-
-    const shouldExport =
-      this._samplingStrategy === 'error_first' || context.data['_tracing_sampled'];
-    if (shouldExport) {
-      this._exporter.export(span);
-    }
-    return null;
-  }
-}