autotel-pact 0.2.0

package/src/auto-wrap.ts

@@ -0,0 +1,283 @@
+/**
+ * Auto-wrap entry for vitest / jest setup files.
+ *
+ * Importing this module monkey-patches `@pact-foundation/pact`'s
+ * `MessageConsumerPact.prototype.verify` and `PactV3.prototype.executeTest`
+ * so every contract test in the project records a ledger entry without
+ * users having to wrap each call by hand.
+ *
+ * Usage (vitest):
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { defineConfig } from 'vitest/config';
+ * export default defineConfig({
+ *   test: { setupFiles: ['autotel-pact/auto-wrap'] },
+ * });
+ * ```
+ *
+ * Usage (jest):
+ *
+ * ```js
+ * // jest.config.js
+ * module.exports = { setupFilesAfterEach: ['autotel-pact/auto-wrap'] };
+ * ```
+ *
+ * Configuration is via environment variables — there's no API surface,
+ * because setup files don't get parameters:
+ *
+ * - `AUTOTEL_PACT_RUN_ID` — tag every ledger entry with this run id
+ * - `AUTOTEL_PACT_LEDGER_DIR` — override the default `.autotel-pact/` dir
+ *
+ * Idempotent: importing twice is a no-op.
+ *
+ * Safe when Pact-JS isn't installed: logs a single warning and exits
+ * cleanly. The same setup file can stay in place for a repo whose
+ * non-contract test packages don't have Pact as a dependency.
+ */
+
+import { span as autotelSpan, getActiveSpan } from 'autotel';
+import { createRequire } from 'node:module';
+import { buildPactAttributes, outcomeAttribute } from './attrs.js';
+import { appendLedgerEntry } from './ledger.js';
+import { LEDGER_ENTRY_SPEC, type InteractionLedgerEntry, type PactInteractionMeta } from './types.js';
+import type { HttpInteraction } from './wrapper-http.js';
+import type { ReifiedMessage } from './wrapper.js';
+
+const INSTALLED = Symbol.for('autotel-pact:auto-wrap-installed');
+
+interface PactJsModule {
+  MessageConsumerPact?: { prototype: Record<string | symbol, unknown> };
+  PactV3?: { prototype: Record<string | symbol, unknown> };
+}
+
+/**
+ * Install the auto-wrap. Called at module load when this file is imported.
+ * Exposed for tests + explicit-invocation users.
+ *
+ * @param pactModule Override Pact-JS resolution. When omitted, requires
+ *   `@pact-foundation/pact` from disk. Tests can pass synthetic classes.
+ *
+ * Returns `true` if Pact-JS was found and patched, `false` otherwise.
+ */
+export function installAutoWrap(pactModule?: PactJsModule): boolean {
+  const pactJs = pactModule ?? loadPactJs();
+  if (!pactJs) return false;
+
+  patchMessagePact(pactJs);
+  patchHttpPact(pactJs);
+  return true;
+}
+
+function loadPactJs(): PactJsModule | undefined {
+  try {
+    // Use createRequire so we work from both ESM and CJS without
+    // pulling Pact-JS into the dynamic import graph.
+    const require = createRequire(import.meta.url);
+    return require('@pact-foundation/pact') as PactJsModule;
+  } catch {
+    process.stderr.write(
+      'autotel-pact/auto-wrap: @pact-foundation/pact not installed — skipping.\n',
+    );
+    return undefined;
+  }
+}
+
+function patchMessagePact(mod: PactJsModule): void {
+  const ctor = mod.MessageConsumerPact;
+  if (!ctor) return;
+  const proto = ctor.prototype;
+  if (proto[INSTALLED]) return;
+
+  const originalVerify = proto.verify as (
+    handler: (m: ReifiedMessage) => Promise<unknown>,
+  ) => Promise<unknown>;
+
+  proto.verify = async function patchedVerify(
+    this: { config: { consumer: string; provider: string } },
+    handler: (m: ReifiedMessage) => Promise<unknown>,
+  ): Promise<unknown> {
+    const start = process.hrtime.bigint();
+    let captured: ReifiedMessage | undefined;
+    const consumer = this.config?.consumer ?? '<unknown>';
+    const provider = this.config?.provider ?? '<unknown>';
+
+    return autotelSpan('pact.interaction', async (span) => {
+      span.setAttributes({
+        'pact.consumer': consumer,
+        'pact.provider': provider,
+        'pact.kind': 'message',
+      });
+
+      try {
+        const result = await originalVerify.call(this, async (reified) => {
+          captured = reified;
+          const meta: PactInteractionMeta = {
+            consumer,
+            provider,
+            description: reified.description ?? '<unknown>',
+            states: (reified.providerStates ?? []).map((s) => s.name),
+            kind: 'message',
+          };
+          span.setAttributes(buildPactAttributes(meta));
+          return handler(reified);
+        });
+        span.setAttributes(outcomeAttribute('passed'));
+        writeAutoLedgerEntry({
+          consumer,
+          provider,
+          interaction: captured?.description ?? '<unknown>',
+          states: (captured?.providerStates ?? []).map((s) => s.name),
+          kind: 'message',
+          outcome: 'passed',
+          start,
+        });
+        return result;
+      } catch (error) {
+        span.setAttributes(outcomeAttribute('failed'));
+        writeAutoLedgerEntry({
+          consumer,
+          provider,
+          interaction: captured?.description ?? '<unknown>',
+          states: (captured?.providerStates ?? []).map((s) => s.name),
+          kind: 'message',
+          outcome: 'failed',
+          start,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+      }
+    });
+  };
+
+  proto[INSTALLED] = true;
+}
+
+function patchHttpPact(mod: PactJsModule): void {
+  const ctor = mod.PactV3;
+  if (!ctor) return;
+  const proto = ctor.prototype;
+  if (proto[INSTALLED]) return;
+
+  // Track interactions added to each PactV3 instance. Cleared after
+  // executeTest emits ledger entries for them, so the same instance can
+  // be reused across multiple test cases.
+  const tracked = new WeakMap<object, HttpInteraction[]>();
+
+  const originalAdd = proto.addInteraction as (i: HttpInteraction) => unknown;
+  proto.addInteraction = function patchedAddInteraction(this: object, interaction: HttpInteraction) {
+    const list = tracked.get(this) ?? [];
+    list.push(interaction);
+    tracked.set(this, list);
+    return originalAdd.call(this, interaction);
+  };
+
+  const originalExecute = proto.executeTest as <T>(
+    fn: (server: { url: string; port: number }) => Promise<T>,
+  ) => Promise<T | undefined>;
+
+  proto.executeTest = async function patchedExecuteTest<T>(
+    this: { opts?: { consumer?: string; provider?: string } },
+    fn: (server: { url: string; port: number }) => Promise<T>,
+  ): Promise<T | undefined> {
+    const start = process.hrtime.bigint();
+    const consumer = this.opts?.consumer ?? '<unknown>';
+    const provider = this.opts?.provider ?? '<unknown>';
+    const interactions = tracked.get(this) ?? [];
+    tracked.set(this, []);
+
+    return autotelSpan('pact.interaction', async (span) => {
+      span.setAttributes({
+        'pact.consumer': consumer,
+        'pact.provider': provider,
+        'pact.kind': 'http',
+      });
+      // If multiple interactions were added before executeTest, the span
+      // attributes describe the first; ledger entries are still written
+      // for each. Most real tests use one interaction per executeTest.
+      const first = interactions[0];
+      if (first) {
+        span.setAttributes(
+          buildPactAttributes({
+            consumer,
+            provider,
+            description: first.uponReceiving,
+            states: (first.states ?? []).map((s) => s.description),
+            kind: 'http',
+          }),
+        );
+      }
+
+      try {
+        const result = (await originalExecute.call(this, fn)) as T | undefined;
+        span.setAttributes(outcomeAttribute('passed'));
+        for (const i of interactions) {
+          writeAutoLedgerEntry({
+            consumer,
+            provider,
+            interaction: i.uponReceiving,
+            states: (i.states ?? []).map((s) => s.description),
+            kind: 'http',
+            outcome: 'passed',
+            start,
+          });
+        }
+        return result;
+      } catch (error_) {
+        span.setAttributes(outcomeAttribute('failed'));
+        const error = error_ instanceof Error ? error_.message : String(error_);
+        for (const i of interactions) {
+          writeAutoLedgerEntry({
+            consumer,
+            provider,
+            interaction: i.uponReceiving,
+            states: (i.states ?? []).map((s) => s.description),
+            kind: 'http',
+            outcome: 'failed',
+            start,
+            error,
+          });
+        }
+        throw error_;
+      }
+    });
+  };
+
+  proto[INSTALLED] = true;
+}
+
+function writeAutoLedgerEntry(args: {
+  consumer: string;
+  provider: string;
+  interaction: string;
+  states: string[];
+  kind: 'message' | 'http';
+  outcome: 'passed' | 'failed';
+  start: bigint;
+  error?: string;
+}): void {
+  const ctx = getActiveSpan()?.spanContext();
+  const entry: InteractionLedgerEntry = {
+    type: 'interaction',
+    spec: LEDGER_ENTRY_SPEC,
+    consumer: args.consumer,
+    provider: args.provider,
+    interaction: args.interaction,
+    states: args.states,
+    kind: args.kind,
+    source: 'test',
+    role: 'consumer',
+    outcome: args.outcome,
+    duration_ms: Number(process.hrtime.bigint() - args.start) / 1e6,
+    observed_at: new Date().toISOString(),
+    trace_id: ctx?.traceId,
+    span_id: ctx?.spanId,
+    run_id: process.env.AUTOTEL_PACT_RUN_ID,
+    git_sha: process.env.GIT_SHA ?? process.env.GITHUB_SHA,
+    error: args.error,
+  };
+  appendLedgerEntry(entry);
+}
+
+// Install on import — this file is meant to be loaded once as a setup file.
+installAutoWrap();

package/src/broker.test.ts

@@ -0,0 +1,175 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  brokerConfigFromEnv,
+  fetchBrokerVerifications,
+  parseBrokerVerificationResult,
+} from './broker.js';
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+});
+
+describe('parseBrokerVerificationResult', () => {
+  it('parses success and verifiedAt', () => {
+    const r = parseBrokerVerificationResult('A', 'B', {
+      success: true,
+      verifiedAt: '2026-01-01T00:00:00Z',
+    });
+    expect(r).toEqual({
+      consumer: 'A',
+      provider: 'B',
+      success: true,
+      verifiedAt: '2026-01-01T00:00:00Z',
+    });
+  });
+
+  it('falls back to verified_at (snake_case) and createdAt', () => {
+    expect(
+      parseBrokerVerificationResult('A', 'B', { success: true, verified_at: '2026-01-02T00:00:00Z' }),
+    ).toMatchObject({ verifiedAt: '2026-01-02T00:00:00Z' });
+    expect(
+      parseBrokerVerificationResult('A', 'B', { success: true, createdAt: '2026-01-03T00:00:00Z' }),
+    ).toMatchObject({ verifiedAt: '2026-01-03T00:00:00Z' });
+  });
+
+  it('infers success from result: "success" when success field missing', () => {
+    expect(
+      parseBrokerVerificationResult('A', 'B', { result: 'success' }),
+    ).toMatchObject({ success: true });
+  });
+
+  it('returns null for non-object input', () => {
+    expect(parseBrokerVerificationResult('A', 'B', null)).toBeNull();
+    expect(parseBrokerVerificationResult('A', 'B', 'string')).toBeNull();
+  });
+});
+
+describe('fetchBrokerVerifications', () => {
+  it('fetches latest verification per pair with bearer auth', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ success: true, verifiedAt: '2026-06-01T00:00:00Z' }),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const results = await fetchBrokerVerifications(
+      { baseUrl: 'https://broker.example', token: 'tok' },
+      [{ consumer: 'A', provider: 'B' }],
+    );
+
+    expect(results[0]).toMatchObject({ consumer: 'A', provider: 'B', success: true });
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://broker.example/pacts/provider/B/consumer/A/latest/verification-results',
+      expect.objectContaining({
+        headers: expect.objectContaining({ Authorization: 'Bearer tok' }),
+      }),
+    );
+  });
+
+  it('uses basic auth when username + password supplied', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ success: true }),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    await fetchBrokerVerifications(
+      { baseUrl: 'https://b.example', username: 'u', password: 'p' },
+      [{ consumer: 'A', provider: 'B' }],
+    );
+
+    const expectedAuth = `Basic ${Buffer.from('u:p').toString('base64')}`;
+    expect(fetchMock).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        headers: expect.objectContaining({ Authorization: expectedAuth }),
+      }),
+    );
+  });
+
+  it('records error and success:false on non-2xx response', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 404,
+      statusText: 'Not Found',
+      json: async () => ({}),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const [result] = await fetchBrokerVerifications(
+      { baseUrl: 'https://b.example' },
+      [{ consumer: 'A', provider: 'B' }],
+    );
+    expect(result).toMatchObject({
+      consumer: 'A',
+      provider: 'B',
+      success: false,
+      error: 'HTTP 404 Not Found',
+    });
+  });
+
+  it('records error and success:false on network failure', async () => {
+    const fetchMock = vi.fn().mockRejectedValue(new Error('ENOTFOUND broker.example'));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const [result] = await fetchBrokerVerifications(
+      { baseUrl: 'https://b.example' },
+      [{ consumer: 'A', provider: 'B' }],
+    );
+    expect(result).toMatchObject({
+      consumer: 'A',
+      provider: 'B',
+      success: false,
+      error: 'ENOTFOUND broker.example',
+    });
+  });
+
+  it('handles multiple pairs and trims trailing slash on base url', async () => {
+    const calls: string[] = [];
+    const fetchMock = vi.fn().mockImplementation((url: string) => {
+      calls.push(url);
+      return Promise.resolve({
+        ok: true,
+        json: async () => ({ success: true }),
+      });
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const results = await fetchBrokerVerifications(
+      { baseUrl: 'https://b.example/' },
+      [
+        { consumer: 'A', provider: 'B' },
+        { consumer: 'C', provider: 'D' },
+      ],
+    );
+
+    expect(results).toHaveLength(2);
+    expect(calls[0]).toBe(
+      'https://b.example/pacts/provider/B/consumer/A/latest/verification-results',
+    );
+    expect(calls[1]).toBe(
+      'https://b.example/pacts/provider/D/consumer/C/latest/verification-results',
+    );
+  });
+});
+
+describe('brokerConfigFromEnv', () => {
+  it('returns undefined when PACT_BROKER_BASE_URL is unset', () => {
+    vi.stubEnv('PACT_BROKER_BASE_URL', '');
+    expect(brokerConfigFromEnv()).toBeUndefined();
+  });
+
+  it('reads baseUrl, token, and basic auth from env', () => {
+    vi.stubEnv('PACT_BROKER_BASE_URL', 'https://b.example');
+    vi.stubEnv('PACT_BROKER_TOKEN', 'tok');
+    vi.stubEnv('PACT_BROKER_USERNAME', 'u');
+    vi.stubEnv('PACT_BROKER_PASSWORD', 'p');
+    expect(brokerConfigFromEnv()).toEqual({
+      baseUrl: 'https://b.example',
+      token: 'tok',
+      username: 'u',
+      password: 'p',
+    });
+  });
+});

package/src/broker.ts

@@ -0,0 +1,118 @@
+import type { BrokerVerification } from './types.js';
+
+export interface BrokerConfig {
+  baseUrl: string;
+  token?: string;
+  username?: string;
+  password?: string;
+}
+
+export interface ConsumerProviderPair {
+  consumer: string;
+  provider: string;
+}
+
+function authHeaders(config: BrokerConfig): Record<string, string> {
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+  };
+  if (config.token) {
+    headers.Authorization = `Bearer ${config.token}`;
+  } else if (config.username && config.password) {
+    const encoded = Buffer.from(`${config.username}:${config.password}`).toString('base64');
+    headers.Authorization = `Basic ${encoded}`;
+  }
+  return headers;
+}
+
+function trimBaseUrl(url: string): string {
+  return url.replace(/\/$/, '');
+}
+
+/**
+ * Parse Pact Broker latest verification result payload.
+ */
+export function parseBrokerVerificationResult(
+  consumer: string,
+  provider: string,
+  json: unknown,
+): BrokerVerification | null {
+  if (!json || typeof json !== 'object') return null;
+  const body = json as Record<string, unknown>;
+  const success =
+    body.success === true ||
+    (body.success === undefined && body.result === 'success');
+  const verifiedAt =
+    typeof body.verifiedAt === 'string'
+      ? body.verifiedAt
+      : typeof body.verified_at === 'string'
+        ? body.verified_at
+        : typeof body.createdAt === 'string'
+          ? body.createdAt
+          : undefined;
+
+  return {
+    consumer,
+    provider,
+    success: !!success,
+    verifiedAt,
+  };
+}
+
+/**
+ * Fetch latest verification results for each consumer–provider pair.
+ */
+export async function fetchBrokerVerifications(
+  config: BrokerConfig,
+  pairs: ConsumerProviderPair[],
+): Promise<BrokerVerification[]> {
+  const base = trimBaseUrl(config.baseUrl);
+  const headers = authHeaders(config);
+  const results: BrokerVerification[] = [];
+
+  for (const { consumer, provider } of pairs) {
+    const url = `${base}/pacts/provider/${encodeURIComponent(provider)}/consumer/${encodeURIComponent(consumer)}/latest/verification-results`;
+    try {
+      const res = await fetch(url, { headers });
+      if (!res.ok) {
+        results.push({
+          consumer,
+          provider,
+          success: false,
+          error: `HTTP ${res.status} ${res.statusText}`.trim(),
+        });
+        continue;
+      }
+      const json: unknown = await res.json();
+      const parsed = parseBrokerVerificationResult(consumer, provider, json);
+      results.push(
+        parsed ?? {
+          consumer,
+          provider,
+          success: false,
+          error: 'Unparseable broker response',
+        },
+      );
+    } catch (error) {
+      results.push({
+        consumer,
+        provider,
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return results;
+}
+
+export function brokerConfigFromEnv(): BrokerConfig | undefined {
+  const baseUrl = process.env.PACT_BROKER_BASE_URL;
+  if (!baseUrl) return undefined;
+  return {
+    baseUrl,
+    token: process.env.PACT_BROKER_TOKEN,
+    username: process.env.PACT_BROKER_USERNAME,
+    password: process.env.PACT_BROKER_PASSWORD,
+  };
+}