apcore-js 0.4.0 → 0.5.0

package/tests/test-extensions.test.ts

@@ -0,0 +1,310 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ExtensionManager } from '../src/extensions.js';
+import type { ExtensionPoint } from '../src/extensions.js';
+import { Middleware } from '../src/middleware/index.js';
+import { ACL } from '../src/acl.js';
+import { Registry } from '../src/registry/registry.js';
+import { Executor } from '../src/executor.js';
+import { TracingMiddleware, InMemoryExporter } from '../src/observability/tracing.js';
+import type { Discoverer, ModuleValidator } from '../src/registry/registry.js';
+import type { SpanExporter, Span } from '../src/observability/tracing.js';
+
+// ---------------------------------------------------------------------------
+// Helpers: concrete implementations that satisfy the interfaces
+// ---------------------------------------------------------------------------
+
+class StubDiscoverer implements Discoverer {
+  discover(_roots: string[]) {
+    return [];
+  }
+}
+
+class StubValidator implements ModuleValidator {
+  validate(_module: unknown) {
+    return [];
+  }
+}
+
+class StubMiddleware extends Middleware {}
+
+class StubExporter implements SpanExporter {
+  export(_span: Span): void {
+    // no-op
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests: ExtensionManager basics
+// ---------------------------------------------------------------------------
+
+describe('ExtensionManager init', () => {
+  it('has five built-in extension points', () => {
+    const mgr = new ExtensionManager();
+    const points = mgr.listPoints();
+    expect(points).toHaveLength(5);
+  });
+
+  it('built-in point names match expected set', () => {
+    const mgr = new ExtensionManager();
+    const names = new Set(mgr.listPoints().map((p: ExtensionPoint) => p.name));
+    expect(names).toEqual(new Set(['discoverer', 'middleware', 'acl', 'span_exporter', 'module_validator']));
+  });
+
+  it('listPoints returns ExtensionPoint objects', () => {
+    const mgr = new ExtensionManager();
+    for (const p of mgr.listPoints()) {
+      expect(p).toHaveProperty('name');
+      expect(p).toHaveProperty('description');
+      expect(p).toHaveProperty('multiple');
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: register / get / getAll / unregister
+// ---------------------------------------------------------------------------
+
+describe('Discoverer extension', () => {
+  it('register and get', () => {
+    const mgr = new ExtensionManager();
+    const disc = new StubDiscoverer();
+    mgr.register('discoverer', disc);
+    expect(mgr.get('discoverer')).toBe(disc);
+  });
+
+  it('register replaces single', () => {
+    const mgr = new ExtensionManager();
+    const disc1 = new StubDiscoverer();
+    const disc2 = new StubDiscoverer();
+    mgr.register('discoverer', disc1);
+    mgr.register('discoverer', disc2);
+    expect(mgr.get('discoverer')).toBe(disc2);
+  });
+
+  it('unregister returns true', () => {
+    const mgr = new ExtensionManager();
+    const disc = new StubDiscoverer();
+    mgr.register('discoverer', disc);
+    expect(mgr.unregister('discoverer', disc)).toBe(true);
+    expect(mgr.get('discoverer')).toBeNull();
+  });
+
+  it('unregister returns false when missing', () => {
+    const mgr = new ExtensionManager();
+    const disc = new StubDiscoverer();
+    expect(mgr.unregister('discoverer', disc)).toBe(false);
+  });
+
+  it('get returns null when empty', () => {
+    const mgr = new ExtensionManager();
+    expect(mgr.get('discoverer')).toBeNull();
+  });
+});
+
+describe('Middleware extension', () => {
+  it('register and getAll', () => {
+    const mgr = new ExtensionManager();
+    const mw1 = new StubMiddleware();
+    const mw2 = new StubMiddleware();
+    mgr.register('middleware', mw1);
+    mgr.register('middleware', mw2);
+    expect(mgr.getAll('middleware')).toEqual([mw1, mw2]);
+  });
+
+  it('unregister specific', () => {
+    const mgr = new ExtensionManager();
+    const mw1 = new StubMiddleware();
+    const mw2 = new StubMiddleware();
+    mgr.register('middleware', mw1);
+    mgr.register('middleware', mw2);
+    mgr.unregister('middleware', mw1);
+    expect(mgr.getAll('middleware')).toEqual([mw2]);
+  });
+});
+
+describe('ACL extension', () => {
+  it('register and get', () => {
+    const mgr = new ExtensionManager();
+    const acl = new ACL([]);
+    mgr.register('acl', acl);
+    expect(mgr.get('acl')).toBe(acl);
+  });
+});
+
+describe('SpanExporter extension', () => {
+  it('register multiple', () => {
+    const mgr = new ExtensionManager();
+    const exp1 = new StubExporter();
+    const exp2 = new StubExporter();
+    mgr.register('span_exporter', exp1);
+    mgr.register('span_exporter', exp2);
+    expect(mgr.getAll('span_exporter')).toEqual([exp1, exp2]);
+  });
+});
+
+describe('ModuleValidator extension', () => {
+  it('register and get', () => {
+    const mgr = new ExtensionManager();
+    const val = new StubValidator();
+    mgr.register('module_validator', val);
+    expect(mgr.get('module_validator')).toBe(val);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: validation errors
+// ---------------------------------------------------------------------------
+
+describe('Validation', () => {
+  it('unknown point throws on register', () => {
+    const mgr = new ExtensionManager();
+    expect(() => mgr.register('nonexistent', {})).toThrow('Unknown extension point');
+  });
+
+  it('wrong type throws TypeError on register', () => {
+    const mgr = new ExtensionManager();
+    expect(() => mgr.register('middleware', 'not_a_middleware')).toThrow(TypeError);
+  });
+
+  it('get unknown point throws', () => {
+    const mgr = new ExtensionManager();
+    expect(() => mgr.get('nonexistent')).toThrow('Unknown extension point');
+  });
+
+  it('getAll unknown point throws', () => {
+    const mgr = new ExtensionManager();
+    expect(() => mgr.getAll('nonexistent')).toThrow('Unknown extension point');
+  });
+
+  it('unregister unknown point throws', () => {
+    const mgr = new ExtensionManager();
+    expect(() => mgr.unregister('nonexistent', {})).toThrow('Unknown extension point');
+  });
+
+  it('discoverer rejects wrong type', () => {
+    const mgr = new ExtensionManager();
+    expect(() => mgr.register('discoverer', new StubMiddleware())).toThrow(TypeError);
+  });
+
+  it('acl rejects wrong type', () => {
+    const mgr = new ExtensionManager();
+    expect(() => mgr.register('acl', new StubMiddleware())).toThrow(TypeError);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: apply()
+// ---------------------------------------------------------------------------
+
+describe('apply()', () => {
+  it('wires discoverer into registry', () => {
+    const mgr = new ExtensionManager();
+    const disc = new StubDiscoverer();
+    mgr.register('discoverer', disc);
+
+    const registry = { setDiscoverer: vi.fn(), setValidator: vi.fn() } as unknown as Registry;
+    const executor = { use: vi.fn(), setAcl: vi.fn(), middlewares: [] } as unknown as Executor;
+    mgr.apply(registry, executor);
+
+    expect(registry.setDiscoverer).toHaveBeenCalledWith(disc);
+  });
+
+  it('wires validator into registry', () => {
+    const mgr = new ExtensionManager();
+    const val = new StubValidator();
+    mgr.register('module_validator', val);
+
+    const registry = { setDiscoverer: vi.fn(), setValidator: vi.fn() } as unknown as Registry;
+    const executor = { use: vi.fn(), setAcl: vi.fn(), middlewares: [] } as unknown as Executor;
+    mgr.apply(registry, executor);
+
+    expect(registry.setValidator).toHaveBeenCalledWith(val);
+  });
+
+  it('wires ACL into executor', () => {
+    const mgr = new ExtensionManager();
+    const acl = new ACL([]);
+    mgr.register('acl', acl);
+
+    const registry = { setDiscoverer: vi.fn(), setValidator: vi.fn() } as unknown as Registry;
+    const executor = { use: vi.fn(), setAcl: vi.fn(), middlewares: [] } as unknown as Executor;
+    mgr.apply(registry, executor);
+
+    expect(executor.setAcl).toHaveBeenCalledWith(acl);
+  });
+
+  it('wires middleware into executor', () => {
+    const mgr = new ExtensionManager();
+    const mw = new StubMiddleware();
+    mgr.register('middleware', mw);
+
+    const registry = { setDiscoverer: vi.fn(), setValidator: vi.fn() } as unknown as Registry;
+    const executor = { use: vi.fn(), setAcl: vi.fn(), middlewares: [] } as unknown as Executor;
+    mgr.apply(registry, executor);
+
+    expect(executor.use).toHaveBeenCalledWith(mw);
+  });
+
+  it('wires single span exporter into TracingMiddleware', () => {
+    const mgr = new ExtensionManager();
+    const newExp = new StubExporter();
+    mgr.register('span_exporter', newExp);
+
+    const inMem = new InMemoryExporter();
+    const tracingMw = new TracingMiddleware(inMem);
+
+    const registry = { setDiscoverer: vi.fn(), setValidator: vi.fn() } as unknown as Registry;
+    const executor = { use: vi.fn(), setAcl: vi.fn(), middlewares: [tracingMw] } as unknown as Executor;
+    mgr.apply(registry, executor);
+
+    // setExporter is used instead of direct private access
+    expect((tracingMw as unknown as Record<string, unknown>)['_exporter']).toBe(newExp);
+  });
+
+  it('wires multiple span exporters via composite exporter', () => {
+    const mgr = new ExtensionManager();
+    const exp1 = new StubExporter();
+    const exp2 = new StubExporter();
+    mgr.register('span_exporter', exp1);
+    mgr.register('span_exporter', exp2);
+
+    const inMem = new InMemoryExporter();
+    const tracingMw = new TracingMiddleware(inMem);
+
+    const registry = { setDiscoverer: vi.fn(), setValidator: vi.fn() } as unknown as Registry;
+    const executor = { use: vi.fn(), setAcl: vi.fn(), middlewares: [tracingMw] } as unknown as Executor;
+    mgr.apply(registry, executor);
+
+    // A composite exporter should have been set that delegates to both
+    const composite = (tracingMw as unknown as Record<string, unknown>)['_exporter'] as Record<string, unknown>;
+    expect(composite['_exporters']).toEqual([exp1, exp2]);
+  });
+
+  it('apply with no extensions is safe', () => {
+    const mgr = new ExtensionManager();
+    const registry = { setDiscoverer: vi.fn(), setValidator: vi.fn() } as unknown as Registry;
+    const executor = { use: vi.fn(), setAcl: vi.fn(), middlewares: [] } as unknown as Executor;
+    mgr.apply(registry, executor);
+
+    expect(registry.setDiscoverer).not.toHaveBeenCalled();
+    expect(registry.setValidator).not.toHaveBeenCalled();
+    expect(executor.use).not.toHaveBeenCalled();
+  });
+
+  it('warns when span_exporter registered but no TracingMiddleware present', () => {
+    const mgr = new ExtensionManager();
+    const newExp = new StubExporter();
+    mgr.register('span_exporter', newExp);
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    const registry = { setDiscoverer: vi.fn(), setValidator: vi.fn() } as unknown as Registry;
+    const executor = { use: vi.fn(), setAcl: vi.fn(), middlewares: [] } as unknown as Executor;
+    mgr.apply(registry, executor);
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('span_exporter'),
+    );
+    warnSpy.mockRestore();
+  });
+});

package/tests/test-trace-context.test.ts

@@ -0,0 +1,251 @@
+import { describe, it, expect } from 'vitest';
+import { TraceContext } from '../src/trace-context.js';
+import type { TraceParent } from '../src/trace-context.js';
+import { Context } from '../src/context.js';
+import type { Span } from '../src/observability/tracing.js';
+
+const TRACEPARENT_RE = /^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/;
+
+describe('TraceContext.inject()', () => {
+  it('produces a valid traceparent format', () => {
+    const ctx = Context.create();
+    const headers = TraceContext.inject(ctx);
+    expect(headers).toHaveProperty('traceparent');
+    expect(headers.traceparent).toMatch(TRACEPARENT_RE);
+  });
+
+  it('uses context traceId (dashes stripped)', () => {
+    const ctx = Context.create();
+    const headers = TraceContext.inject(ctx);
+    const parts = headers.traceparent.split('-');
+    const expectedHex = ctx.traceId.replace(/-/g, '');
+    // parts[1] is the trace_id field (but split by '-' means we need to
+    // reconstruct from parts 1..4 since the 32-hex is split by the overall format)
+    // Actually the format is: 00-<32hex>-<16hex>-<2hex>
+    // Splitting by '-' gives: ["00", <32hex>, <16hex>, <2hex>]
+    expect(parts[1]).toBe(expectedHex);
+  });
+
+  it('starts with version 00', () => {
+    const ctx = Context.create();
+    const headers = TraceContext.inject(ctx);
+    expect(headers.traceparent.startsWith('00-')).toBe(true);
+  });
+
+  it('ends with trace flags 01', () => {
+    const ctx = Context.create();
+    const headers = TraceContext.inject(ctx);
+    expect(headers.traceparent.endsWith('-01')).toBe(true);
+  });
+
+  it('uses spanId from tracing stack when available', () => {
+    const ctx = Context.create();
+    const fakeSpan: Span = {
+      traceId: ctx.traceId,
+      name: 'test',
+      startTime: 0,
+      spanId: 'abcdef0123456789',
+      parentSpanId: null,
+      attributes: {},
+      endTime: null,
+      status: 'ok',
+      events: [],
+    };
+    ctx.data['_tracing_spans'] = [fakeSpan];
+
+    const headers = TraceContext.inject(ctx);
+    const parts = headers.traceparent.split('-');
+    expect(parts[2]).toBe('abcdef0123456789');
+  });
+
+  it('generates random parentId when no spans exist', () => {
+    const ctx = Context.create();
+    const headers = TraceContext.inject(ctx);
+    const parts = headers.traceparent.split('-');
+    const parentId = parts[2];
+    expect(parentId).toHaveLength(16);
+    expect(parentId).toMatch(/^[0-9a-f]{16}$/);
+  });
+});
+
+describe('TraceContext.extract()', () => {
+  it('parses a valid traceparent header', () => {
+    const headers = { traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' };
+    const result = TraceContext.extract(headers);
+    expect(result).not.toBeNull();
+    expect(result!.version).toBe('00');
+    expect(result!.traceId).toBe('4bf92f3577b34da6a3ce929d0e0e4736');
+    expect(result!.parentId).toBe('00f067aa0ba902b7');
+    expect(result!.traceFlags).toBe('01');
+  });
+
+  it('returns null for missing header', () => {
+    const result = TraceContext.extract({});
+    expect(result).toBeNull();
+  });
+
+  it('returns null for unrelated headers', () => {
+    const result = TraceContext.extract({ 'other-header': 'value' });
+    expect(result).toBeNull();
+  });
+
+  it('returns null for malformed traceparent', () => {
+    const result = TraceContext.extract({ traceparent: 'invalid-format' });
+    expect(result).toBeNull();
+  });
+
+  it('returns null for short trace_id', () => {
+    const result = TraceContext.extract({ traceparent: '00-abc-00f067aa0ba902b7-01' });
+    expect(result).toBeNull();
+  });
+
+  it('normalizes uppercase to lowercase', () => {
+    const headers = { traceparent: '00-4BF92F3577B34DA6A3CE929D0E0E4736-00F067AA0BA902B7-01' };
+    const result = TraceContext.extract(headers);
+    expect(result).not.toBeNull();
+    expect(result!.traceId).toBe('4bf92f3577b34da6a3ce929d0e0e4736');
+  });
+
+  it('parses unsampled trace flags', () => {
+    const headers = { traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00' };
+    const result = TraceContext.extract(headers);
+    expect(result).not.toBeNull();
+    expect(result!.traceFlags).toBe('00');
+  });
+
+  it('returns null for all-zero trace_id', () => {
+    const result = TraceContext.extract({ traceparent: '00-00000000000000000000000000000000-00f067aa0ba902b7-01' });
+    expect(result).toBeNull();
+  });
+
+  it('returns null for all-zero parent_id', () => {
+    const result = TraceContext.extract({ traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-0000000000000000-01' });
+    expect(result).toBeNull();
+  });
+
+  it('returns null for version ff', () => {
+    const result = TraceContext.extract({ traceparent: 'ff-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' });
+    expect(result).toBeNull();
+  });
+
+  it('returns a frozen object', () => {
+    const headers = { traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' };
+    const result = TraceContext.extract(headers);
+    expect(result).not.toBeNull();
+    expect(Object.isFrozen(result)).toBe(true);
+  });
+});
+
+describe('TraceContext.fromTraceparent()', () => {
+  it('parses a valid traceparent string', () => {
+    const tp = TraceContext.fromTraceparent('00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01');
+    expect(tp.version).toBe('00');
+    expect(tp.traceId).toBe('4bf92f3577b34da6a3ce929d0e0e4736');
+    expect(tp.parentId).toBe('00f067aa0ba902b7');
+    expect(tp.traceFlags).toBe('01');
+  });
+
+  it('throws on invalid traceparent', () => {
+    expect(() => TraceContext.fromTraceparent('not-a-valid-traceparent'))
+      .toThrow('Malformed traceparent');
+  });
+
+  it('throws on empty string', () => {
+    expect(() => TraceContext.fromTraceparent(''))
+      .toThrow('Malformed traceparent');
+  });
+
+  it('throws on missing parts', () => {
+    expect(() => TraceContext.fromTraceparent('00-4bf92f3577b34da6a3ce929d0e0e4736'))
+      .toThrow('Malformed traceparent');
+  });
+
+  it('throws on all-zero trace_id', () => {
+    expect(() => TraceContext.fromTraceparent('00-00000000000000000000000000000000-00f067aa0ba902b7-01'))
+      .toThrow('all-zero trace_id or parent_id');
+  });
+
+  it('throws on all-zero parent_id', () => {
+    expect(() => TraceContext.fromTraceparent('00-4bf92f3577b34da6a3ce929d0e0e4736-0000000000000000-01'))
+      .toThrow('all-zero trace_id or parent_id');
+  });
+
+  it('throws on version ff', () => {
+    expect(() => TraceContext.fromTraceparent('ff-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01'))
+      .toThrow('version ff is not allowed');
+  });
+
+  it('returns a frozen object', () => {
+    const tp = TraceContext.fromTraceparent('00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01');
+    expect(Object.isFrozen(tp)).toBe(true);
+  });
+});
+
+describe('Round-trip: inject -> extract', () => {
+  it('preserves trace_id through inject then extract', () => {
+    const ctx = Context.create();
+    const headers = TraceContext.inject(ctx);
+    const parsed = TraceContext.extract(headers);
+
+    expect(parsed).not.toBeNull();
+    const expectedHex = ctx.traceId.replace(/-/g, '');
+    expect(parsed!.traceId).toBe(expectedHex);
+  });
+
+  it('preserves parent_id through inject then extract', () => {
+    const ctx = Context.create();
+    const headers = TraceContext.inject(ctx);
+    const parsed = TraceContext.extract(headers);
+
+    expect(parsed).not.toBeNull();
+    const parts = headers.traceparent.split('-');
+    expect(parsed!.parentId).toBe(parts[2]);
+  });
+});
+
+describe('Context.create() with traceParent', () => {
+  it('uses traceParent traceId converted to UUID format', () => {
+    const tp: TraceParent = {
+      version: '00',
+      traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
+      parentId: '00f067aa0ba902b7',
+      traceFlags: '01',
+    };
+    const ctx = Context.create(null, null, undefined, tp);
+    expect(ctx.traceId).toBe('4bf92f35-77b3-4da6-a3ce-929d0e0e4736');
+  });
+
+  it('produces a valid UUID string from traceParent', () => {
+    const tp: TraceParent = {
+      version: '00',
+      traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
+      parentId: '00f067aa0ba902b7',
+      traceFlags: '01',
+    };
+    const ctx = Context.create(null, null, undefined, tp);
+    // Should match UUID format: 8-4-4-4-12
+    expect(ctx.traceId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  });
+
+  it('still works without traceParent', () => {
+    const ctx = Context.create();
+    expect(ctx.traceId).toBeDefined();
+    expect(ctx.traceId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  });
+
+  it('generates unique traceIds without traceParent', () => {
+    const ctx1 = Context.create();
+    const ctx2 = Context.create();
+    expect(ctx1.traceId).not.toBe(ctx2.traceId);
+  });
+
+  it('full round-trip: context -> inject -> extract -> create', () => {
+    const original = Context.create();
+    const headers = TraceContext.inject(original);
+    const parsed = TraceContext.extract(headers);
+    expect(parsed).not.toBeNull();
+
+    const restored = Context.create(null, null, undefined, parsed);
+    expect(restored.traceId).toBe(original.traceId);
+  });
+});