apcore-js 0.1.0

package/tests/integration/test-observability-integration.test.ts

@@ -0,0 +1,438 @@
+import { describe, it, expect } from 'vitest';
+import { Type } from '@sinclair/typebox';
+import { Executor } from '../../src/executor.js';
+import { FunctionModule } from '../../src/decorator.js';
+import { Registry } from '../../src/registry/registry.js';
+import { Context, createIdentity } from '../../src/context.js';
+import { InMemoryExporter, TracingMiddleware } from '../../src/observability/tracing.js';
+import { MetricsCollector, MetricsMiddleware } from '../../src/observability/metrics.js';
+import { ContextLogger, ObsLoggingMiddleware } from '../../src/observability/context-logger.js';
+
+describe('Observability Integration', () => {
+  it('full observability stack on success', async () => {
+    const registry = new Registry();
+    const testModule = new FunctionModule({
+      execute: (inputs) => ({ result: `Processed ${inputs['value']}` }),
+      moduleId: 'test.success',
+      inputSchema: Type.Object({ value: Type.String() }),
+      outputSchema: Type.Object({ result: Type.String() }),
+      description: 'Test module',
+    });
+    registry.register('test.success', testModule);
+
+    const metrics = new MetricsCollector();
+    const exporter = new InMemoryExporter();
+    const logLines: string[] = [];
+    const captureOutput = {
+      write(s: string): void {
+        logLines.push(s);
+      },
+    };
+    const logger = new ContextLogger({ name: 'test', output: captureOutput });
+
+    const executor = new Executor({
+      registry,
+      middlewares: [
+        new MetricsMiddleware(metrics),
+        new TracingMiddleware(exporter),
+        new ObsLoggingMiddleware({ logger }),
+      ],
+    });
+
+    const result = await executor.call('test.success', { value: 'hello' });
+    expect(result['result']).toBe('Processed hello');
+
+    // Verify span exported with status='ok'
+    const spans = exporter.getSpans();
+    expect(spans).toHaveLength(1);
+    expect(spans[0].status).toBe('ok');
+    expect(spans[0].name).toBe('apcore.module.execute');
+
+    // Verify success counter incremented
+    const snap = metrics.snapshot();
+    const counters = snap['counters'] as Record<string, number>;
+    expect(counters['apcore_module_calls_total|module_id=test.success,status=success']).toBe(1);
+
+    // Verify duration observed
+    const histograms = snap['histograms'] as Record<string, unknown>;
+    const counts = histograms['counts'] as Record<string, number>;
+    expect(counts['apcore_module_duration_seconds|module_id=test.success']).toBe(1);
+
+    // Verify logger captured "started" and "completed" messages
+    expect(logLines.length).toBeGreaterThanOrEqual(2);
+    const startedLog = logLines.find((line) => line.includes('Module call started'));
+    const completedLog = logLines.find((line) => line.includes('Module call completed'));
+    expect(startedLog).toBeDefined();
+    expect(completedLog).toBeDefined();
+  });
+
+  it('full observability stack on failure', async () => {
+    const registry = new Registry();
+    const testModule = new FunctionModule({
+      execute: (_inputs) => {
+        throw new Error('Test failure');
+      },
+      moduleId: 'test.failure',
+      inputSchema: Type.Object({ value: Type.String() }),
+      outputSchema: Type.Object({ result: Type.String() }),
+      description: 'Failing module',
+    });
+    registry.register('test.failure', testModule);
+
+    const metrics = new MetricsCollector();
+    const exporter = new InMemoryExporter();
+    const logLines: string[] = [];
+    const captureOutput = {
+      write(s: string): void {
+        logLines.push(s);
+      },
+    };
+    const logger = new ContextLogger({ name: 'test', output: captureOutput });
+
+    const executor = new Executor({
+      registry,
+      middlewares: [
+        new MetricsMiddleware(metrics),
+        new TracingMiddleware(exporter),
+        new ObsLoggingMiddleware({ logger }),
+      ],
+    });
+
+    await expect(executor.call('test.failure', { value: 'test' })).rejects.toThrow('Test failure');
+
+    // Verify span has status='error' and error_code attribute
+    const spans = exporter.getSpans();
+    expect(spans).toHaveLength(1);
+    expect(spans[0].status).toBe('error');
+    expect(spans[0].attributes['error_code']).toBe('Error');
+
+    // Verify error counter incremented
+    const snap = metrics.snapshot();
+    const counters = snap['counters'] as Record<string, number>;
+    expect(counters['apcore_module_calls_total|module_id=test.failure,status=error']).toBe(1);
+    expect(counters['apcore_module_errors_total|error_code=Error,module_id=test.failure']).toBe(1);
+
+    // Verify logger captured "started" and "failed" messages
+    expect(logLines.length).toBeGreaterThanOrEqual(2);
+    const startedLog = logLines.find((line) => line.includes('Module call started'));
+    const failedLog = logLines.find((line) => line.includes('Module call failed'));
+    expect(startedLog).toBeDefined();
+    expect(failedLog).toBeDefined();
+  });
+
+  it('tracing with nested calls', async () => {
+    const registry = new Registry();
+
+    const moduleB = new FunctionModule({
+      execute: (inputs) => ({ value: `B: ${inputs['data']}` }),
+      moduleId: 'mod.b',
+      inputSchema: Type.Object({ data: Type.String() }),
+      outputSchema: Type.Object({ value: Type.String() }),
+      description: 'Module B',
+    });
+
+    const moduleA = new FunctionModule({
+      execute: async (_inputs, context) => {
+        const executor = context.executor as Executor;
+        return executor.call('mod.b', { data: 'nested' }, context);
+      },
+      moduleId: 'mod.a',
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({ value: Type.String() }),
+      description: 'Module A',
+    });
+
+    registry.register('mod.a', moduleA);
+    registry.register('mod.b', moduleB);
+
+    const exporter = new InMemoryExporter();
+    const executor = new Executor({
+      registry,
+      middlewares: [new TracingMiddleware(exporter)],
+    });
+
+    const result = await executor.call('mod.a', {});
+    expect(result['value']).toBe('B: nested');
+
+    // Verify 2 spans exported
+    const spans = exporter.getSpans();
+    expect(spans).toHaveLength(2);
+
+    // Second span has parentSpanId matching first span's spanId
+    const spanA = spans.find((s) => s.attributes['moduleId'] === 'mod.a');
+    const spanB = spans.find((s) => s.attributes['moduleId'] === 'mod.b');
+    expect(spanA).toBeDefined();
+    expect(spanB).toBeDefined();
+    expect(spanB!.parentSpanId).toBe(spanA!.spanId);
+
+    // Both share same traceId
+    expect(spanA!.traceId).toBe(spanB!.traceId);
+  });
+
+  it('metrics accumulate across calls', async () => {
+    const registry = new Registry();
+
+    let callCount = 0;
+    const testModule = new FunctionModule({
+      execute: (_inputs) => {
+        callCount++;
+        if (callCount === 4) {
+          throw new Error('Fourth call fails');
+        }
+        return { result: 'ok' };
+      },
+      moduleId: 'test.accumulate',
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({ result: Type.String() }),
+      description: 'Test module',
+    });
+    registry.register('test.accumulate', testModule);
+
+    const metrics = new MetricsCollector();
+    const executor = new Executor({
+      registry,
+      middlewares: [new MetricsMiddleware(metrics)],
+    });
+
+    // Call 3 times successfully
+    await executor.call('test.accumulate', {});
+    await executor.call('test.accumulate', {});
+    await executor.call('test.accumulate', {});
+
+    // Call once with failure
+    await expect(executor.call('test.accumulate', {})).rejects.toThrow('Fourth call fails');
+
+    // Verify: success counter = 3, error counter = 1, duration histogram count = 4
+    const snap = metrics.snapshot();
+    const counters = snap['counters'] as Record<string, number>;
+    expect(counters['apcore_module_calls_total|module_id=test.accumulate,status=success']).toBe(3);
+    expect(counters['apcore_module_calls_total|module_id=test.accumulate,status=error']).toBe(1);
+
+    const histograms = snap['histograms'] as Record<string, unknown>;
+    const counts = histograms['counts'] as Record<string, number>;
+    expect(counts['apcore_module_duration_seconds|module_id=test.accumulate']).toBe(4);
+  });
+
+  it('TracingMiddleware with error_first sampling', async () => {
+    const registry = new Registry();
+
+    const successModule = new FunctionModule({
+      execute: (_inputs) => ({ result: 'ok' }),
+      moduleId: 'test.sampling.success',
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({ result: Type.String() }),
+      description: 'Success module',
+    });
+
+    const errorModule = new FunctionModule({
+      execute: (_inputs) => {
+        throw new Error('Sampling error');
+      },
+      moduleId: 'test.sampling.error',
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({ result: Type.String() }),
+      description: 'Error module',
+    });
+
+    registry.register('test.sampling.success', successModule);
+    registry.register('test.sampling.error', errorModule);
+
+    const exporter = new InMemoryExporter();
+    const executor = new Executor({
+      registry,
+      middlewares: [new TracingMiddleware(exporter, 0.0, 'error_first')],
+    });
+
+    // Success calls don't export spans
+    await executor.call('test.sampling.success', {});
+    await executor.call('test.sampling.success', {});
+    expect(exporter.getSpans()).toHaveLength(0);
+
+    // Error calls DO export spans
+    await expect(executor.call('test.sampling.error', {})).rejects.toThrow('Sampling error');
+    const spans = exporter.getSpans();
+    expect(spans).toHaveLength(1);
+    expect(spans[0].status).toBe('error');
+    expect(spans[0].attributes['moduleId']).toBe('test.sampling.error');
+  });
+
+  it('TracingMiddleware with off strategy', async () => {
+    const registry = new Registry();
+
+    const successModule = new FunctionModule({
+      execute: (_inputs) => ({ result: 'ok' }),
+      moduleId: 'test.off.success',
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({ result: Type.String() }),
+      description: 'Success module',
+    });
+
+    const errorModule = new FunctionModule({
+      execute: (_inputs) => {
+        throw new Error('Off error');
+      },
+      moduleId: 'test.off.error',
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({ result: Type.String() }),
+      description: 'Error module',
+    });
+
+    registry.register('test.off.success', successModule);
+    registry.register('test.off.error', errorModule);
+
+    const exporter = new InMemoryExporter();
+    const executor = new Executor({
+      registry,
+      middlewares: [new TracingMiddleware(exporter, 1.0, 'off')],
+    });
+
+    // No spans exported for success calls
+    await executor.call('test.off.success', {});
+    expect(exporter.getSpans()).toHaveLength(0);
+
+    // No spans exported for error calls
+    await expect(executor.call('test.off.error', {})).rejects.toThrow('Off error');
+    expect(exporter.getSpans()).toHaveLength(0);
+  });
+
+  it('ObsLoggingMiddleware captures inputs and outputs', async () => {
+    const registry = new Registry();
+    const testModule = new FunctionModule({
+      execute: (inputs) => ({ output_value: `processed_${inputs['input_value']}` }),
+      moduleId: 'test.logging',
+      inputSchema: Type.Object({ input_value: Type.String() }),
+      outputSchema: Type.Object({ output_value: Type.String() }),
+      description: 'Logging test',
+    });
+    registry.register('test.logging', testModule);
+
+    const logLines: string[] = [];
+    const captureOutput = {
+      write(s: string): void {
+        logLines.push(s);
+      },
+    };
+    const logger = new ContextLogger({ name: 'test', output: captureOutput });
+
+    const executor = new Executor({
+      registry,
+      middlewares: [new ObsLoggingMiddleware({ logger, logInputs: true, logOutputs: true })],
+    });
+
+    await executor.call('test.logging', { input_value: 'test_input' });
+
+    // Verify 'Module call started' includes module_id and inputs
+    const startedLog = logLines.find((line) => line.includes('Module call started'));
+    expect(startedLog).toBeDefined();
+    const startedData = JSON.parse(startedLog!);
+    expect(startedData.message).toBe('Module call started');
+    expect(startedData.extra.module_id).toBe('test.logging');
+    expect(startedData.extra.inputs).toEqual({ input_value: 'test_input' });
+
+    // Verify 'Module call completed' includes duration_ms and output
+    const completedLog = logLines.find((line) => line.includes('Module call completed'));
+    expect(completedLog).toBeDefined();
+    const completedData = JSON.parse(completedLog!);
+    expect(completedData.message).toBe('Module call completed');
+    expect(completedData.extra.module_id).toBe('test.logging');
+    expect(completedData.extra.output).toEqual({ output_value: 'processed_test_input' });
+    expect(typeof completedData.extra.duration_ms).toBe('number');
+    expect(completedData.extra.duration_ms).toBeGreaterThanOrEqual(0);
+  });
+
+  it('Context logger redacts _secret_ fields', async () => {
+    const registry = new Registry();
+    const testModule = new FunctionModule({
+      execute: (_inputs) => ({ result: 'done' }),
+      moduleId: 'test.redact',
+      inputSchema: Type.Object({
+        _secret_key: Type.String(),
+        normal_field: Type.String(),
+      }),
+      outputSchema: Type.Object({ result: Type.String() }),
+      description: 'Redaction test',
+    });
+    registry.register('test.redact', testModule);
+
+    const logLines: string[] = [];
+    const captureOutput = {
+      write(s: string): void {
+        logLines.push(s);
+      },
+    };
+    const logger = new ContextLogger({
+      name: 'test',
+      output: captureOutput,
+      redactSensitive: true,
+    });
+
+    const executor = new Executor({
+      registry,
+      middlewares: [new ObsLoggingMiddleware({ logger, logInputs: true })],
+    });
+
+    await executor.call('test.redact', {
+      _secret_key: 'super_secret_value',
+      normal_field: 'normal_value',
+    });
+
+    // Verify the logged extra has _secret_key redacted
+    const startedLog = logLines.find((line) => line.includes('Module call started'));
+    expect(startedLog).toBeDefined();
+    const logData = JSON.parse(startedLog!);
+    expect(logData.extra.inputs._secret_key).toBe('***REDACTED***');
+    expect(logData.extra.inputs.normal_field).toBe('normal_value');
+  });
+
+  it('Span attributes include moduleId, method, callerId', async () => {
+    const registry = new Registry();
+
+    const moduleB = new FunctionModule({
+      execute: (_inputs) => ({ result: 'B done' }),
+      moduleId: 'test.b',
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({ result: Type.String() }),
+      description: 'Module B',
+    });
+
+    const moduleA = new FunctionModule({
+      execute: async (_inputs, context) => {
+        const executor = context.executor as Executor;
+        return executor.call('test.b', {}, context);
+      },
+      moduleId: 'test.a',
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({ result: Type.String() }),
+      description: 'Module A',
+    });
+
+    registry.register('test.a', moduleA);
+    registry.register('test.b', moduleB);
+
+    const exporter = new InMemoryExporter();
+    const executor = new Executor({
+      registry,
+      middlewares: [new TracingMiddleware(exporter)],
+    });
+
+    await executor.call('test.a', {});
+
+    // Verify span attributes contain moduleId, method, callerId
+    const spans = exporter.getSpans();
+    expect(spans).toHaveLength(2);
+
+    // First span (test.a) has null callerId since it's top-level
+    const spanA = spans.find((s) => s.attributes['moduleId'] === 'test.a');
+    expect(spanA).toBeDefined();
+    expect(spanA!.attributes['moduleId']).toBe('test.a');
+    expect(spanA!.attributes['method']).toBe('execute');
+    expect(spanA!.attributes['callerId']).toBeNull();
+
+    // Second span (test.b) has callerId='test.a' since it's called by test.a
+    const spanB = spans.find((s) => s.attributes['moduleId'] === 'test.b');
+    expect(spanB).toBeDefined();
+    expect(spanB!.attributes['moduleId']).toBe('test.b');
+    expect(spanB!.attributes['method']).toBe('execute');
+    expect(spanB!.attributes['callerId']).toBe('test.a');
+  });
+});

package/tests/observability/test-context-logger.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect } from 'vitest';
+import { Context, createIdentity } from '../../src/context.js';
+import { ContextLogger, ObsLoggingMiddleware } from '../../src/observability/context-logger.js';
+
+function createBufferOutput() {
+  const lines: string[] = [];
+  return {
+    output: { write: (s: string) => lines.push(s) },
+    lines,
+  };
+}
+
+describe('ContextLogger', () => {
+  it('creates with defaults', () => {
+    const logger = new ContextLogger();
+    // Should not throw
+    expect(logger).toBeDefined();
+  });
+
+  it('logs JSON format by default', () => {
+    const { output, lines } = createBufferOutput();
+    const logger = new ContextLogger({ output });
+    logger.info('test message');
+    expect(lines).toHaveLength(1);
+    const parsed = JSON.parse(lines[0]);
+    expect(parsed.level).toBe('info');
+    expect(parsed.message).toBe('test message');
+  });
+
+  it('logs text format', () => {
+    const { output, lines } = createBufferOutput();
+    const logger = new ContextLogger({ format: 'text', output });
+    logger.info('test message');
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toContain('[INFO]');
+    expect(lines[0]).toContain('test message');
+  });
+
+  it('respects log level filtering', () => {
+    const { output, lines } = createBufferOutput();
+    const logger = new ContextLogger({ level: 'warn', output });
+    logger.debug('should not appear');
+    logger.info('should not appear');
+    logger.warn('should appear');
+    logger.error('should appear');
+    expect(lines).toHaveLength(2);
+  });
+
+  it('redacts _secret_ prefix keys', () => {
+    const { output, lines } = createBufferOutput();
+    const logger = new ContextLogger({ output });
+    logger.info('test', { _secret_token: 'abc123', name: 'Bob' });
+    const parsed = JSON.parse(lines[0]);
+    expect(parsed.extra._secret_token).toBe('***REDACTED***');
+    expect(parsed.extra.name).toBe('Bob');
+  });
+
+  it('does not redact when disabled', () => {
+    const { output, lines } = createBufferOutput();
+    const logger = new ContextLogger({ output, redactSensitive: false });
+    logger.info('test', { _secret_token: 'abc123' });
+    const parsed = JSON.parse(lines[0]);
+    expect(parsed.extra._secret_token).toBe('abc123');
+  });
+
+  it('fromContext sets trace/module/caller', () => {
+    const { output, lines } = createBufferOutput();
+    const ctx = Context.create(undefined, createIdentity('user1'));
+    const childCtx = ctx.child('mod.test');
+    const logger = ContextLogger.fromContext(childCtx, 'test-logger', { output });
+    logger.info('context log');
+    const parsed = JSON.parse(lines[0]);
+    expect(parsed.trace_id).toBe(ctx.traceId);
+    expect(parsed.module_id).toBe('mod.test');
+    expect(parsed.logger).toBe('test-logger');
+  });
+
+  it('all log levels work', () => {
+    const { output, lines } = createBufferOutput();
+    const logger = new ContextLogger({ level: 'trace', output });
+    logger.trace('t');
+    logger.debug('d');
+    logger.info('i');
+    logger.warn('w');
+    logger.error('e');
+    logger.fatal('f');
+    expect(lines).toHaveLength(6);
+  });
+});
+
+describe('ObsLoggingMiddleware', () => {
+  it('logs before and after', () => {
+    const { output, lines } = createBufferOutput();
+    const logger = new ContextLogger({ output });
+    const mw = new ObsLoggingMiddleware({ logger });
+    const ctx = Context.create();
+
+    mw.before('mod.a', { name: 'Alice' }, ctx);
+    mw.after('mod.a', { name: 'Alice' }, { result: 'ok' }, ctx);
+
+    expect(lines).toHaveLength(2);
+    const before = JSON.parse(lines[0]);
+    const after = JSON.parse(lines[1]);
+    expect(before.message).toBe('Module call started');
+    expect(after.message).toBe('Module call completed');
+    expect(after.extra.duration_ms).toBeDefined();
+  });
+
+  it('logs onError', () => {
+    const { output, lines } = createBufferOutput();
+    const logger = new ContextLogger({ output });
+    const mw = new ObsLoggingMiddleware({ logger });
+    const ctx = Context.create();
+
+    mw.before('mod.a', {}, ctx);
+    mw.onError('mod.a', {}, new Error('boom'), ctx);
+
+    expect(lines).toHaveLength(2);
+    const errorLog = JSON.parse(lines[1]);
+    expect(errorLog.message).toBe('Module call failed');
+    expect(errorLog.extra.error_type).toBe('Error');
+  });
+});

package/tests/observability/test-metrics.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+import { MetricsCollector, MetricsMiddleware } from '../../src/observability/metrics.js';
+import { Context } from '../../src/context.js';
+
+describe('MetricsCollector', () => {
+  it('increments counters', () => {
+    const collector = new MetricsCollector();
+    collector.increment('test_counter', { method: 'GET' });
+    collector.increment('test_counter', { method: 'GET' });
+    const snap = collector.snapshot();
+    expect((snap['counters'] as Record<string, number>)['test_counter|method=GET']).toBe(2);
+  });
+
+  it('observes histogram values', () => {
+    const collector = new MetricsCollector();
+    collector.observe('test_hist', { module: 'a' }, 0.05);
+    collector.observe('test_hist', { module: 'a' }, 0.5);
+    const snap = collector.snapshot();
+    const hists = snap['histograms'] as Record<string, Record<string, number>>;
+    expect(hists['sums']['test_hist|module=a']).toBeCloseTo(0.55);
+    expect(hists['counts']['test_hist|module=a']).toBe(2);
+  });
+
+  it('convenience methods work', () => {
+    const collector = new MetricsCollector();
+    collector.incrementCalls('mod.a', 'success');
+    collector.incrementErrors('mod.a', 'TIMEOUT');
+    collector.observeDuration('mod.a', 0.1);
+
+    const snap = collector.snapshot();
+    const counters = snap['counters'] as Record<string, number>;
+    expect(counters['apcore_module_calls_total|module_id=mod.a,status=success']).toBe(1);
+    expect(counters['apcore_module_errors_total|error_code=TIMEOUT,module_id=mod.a']).toBe(1);
+  });
+
+  it('reset clears all data', () => {
+    const collector = new MetricsCollector();
+    collector.incrementCalls('mod.a', 'success');
+    collector.observeDuration('mod.a', 0.1);
+    collector.reset();
+    const snap = collector.snapshot();
+    expect(Object.keys(snap['counters'] as Record<string, unknown>)).toHaveLength(0);
+  });
+
+  it('exportPrometheus produces valid format', () => {
+    const collector = new MetricsCollector();
+    collector.incrementCalls('mod.a', 'success');
+    collector.observeDuration('mod.a', 0.05);
+    const output = collector.exportPrometheus();
+    expect(output).toContain('# HELP');
+    expect(output).toContain('# TYPE');
+    expect(output).toContain('apcore_module_calls_total');
+    expect(output).toContain('apcore_module_duration_seconds');
+  });
+
+  it('empty collector returns empty prometheus string', () => {
+    const collector = new MetricsCollector();
+    expect(collector.exportPrometheus()).toBe('');
+  });
+});
+
+describe('MetricsMiddleware', () => {
+  it('records call metrics on success', () => {
+    const collector = new MetricsCollector();
+    const mw = new MetricsMiddleware(collector);
+    const ctx = Context.create();
+
+    mw.before('mod.a', {}, ctx);
+    mw.after('mod.a', {}, { result: 'ok' }, ctx);
+
+    const snap = collector.snapshot();
+    const counters = snap['counters'] as Record<string, number>;
+    expect(counters['apcore_module_calls_total|module_id=mod.a,status=success']).toBe(1);
+  });
+
+  it('records error metrics on failure', () => {
+    const collector = new MetricsCollector();
+    const mw = new MetricsMiddleware(collector);
+    const ctx = Context.create();
+
+    mw.before('mod.a', {}, ctx);
+    mw.onError('mod.a', {}, new Error('boom'), ctx);
+
+    const snap = collector.snapshot();
+    const counters = snap['counters'] as Record<string, number>;
+    expect(counters['apcore_module_calls_total|module_id=mod.a,status=error']).toBe(1);
+    expect(counters['apcore_module_errors_total|error_code=Error,module_id=mod.a']).toBe(1);
+  });
+});