@multiplier-labs/stepflow 0.3.4 → 0.3.8

package/src/utils/logger.test.ts

@@ -1,121 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { ConsoleLogger, SilentLogger, createScopedLogger } from './logger';
-
-describe('ConsoleLogger', () => {
-  it('should log debug messages with prefix', () => {
-    const spy = vi.spyOn(console, 'debug').mockImplementation(() => {});
-    const logger = new ConsoleLogger('[test]', 'debug');
-
-    logger.debug('hello', { extra: true });
-
-    expect(spy).toHaveBeenCalledWith('[test] [DEBUG]', 'hello', { extra: true });
-    spy.mockRestore();
-  });
-
-  it('should log info messages with prefix', () => {
-    const spy = vi.spyOn(console, 'info').mockImplementation(() => {});
-    const logger = new ConsoleLogger('[test]');
-
-    logger.info('info msg');
-
-    expect(spy).toHaveBeenCalledWith('[test] [INFO]', 'info msg');
-    spy.mockRestore();
-  });
-
-  it('should log warn messages with prefix', () => {
-    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const logger = new ConsoleLogger('[test]');
-
-    logger.warn('warning');
-
-    expect(spy).toHaveBeenCalledWith('[test] [WARN]', 'warning');
-    spy.mockRestore();
-  });
-
-  it('should log error messages with prefix', () => {
-    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
-    const logger = new ConsoleLogger('[test]');
-
-    logger.error('error msg', new Error('boom'));
-
-    expect(spy).toHaveBeenCalledWith('[test] [ERROR]', 'error msg', expect.any(Error));
-    spy.mockRestore();
-  });
-
-  it('should use default prefix when none provided', () => {
-    const spy = vi.spyOn(console, 'info').mockImplementation(() => {});
-    const logger = new ConsoleLogger();
-
-    logger.info('test');
-
-    expect(spy).toHaveBeenCalledWith('[workflow] [INFO]', 'test');
-    spy.mockRestore();
-  });
-});
-
-describe('SilentLogger', () => {
-  it('should not throw on any log level', () => {
-    const logger = new SilentLogger();
-
-    expect(() => logger.debug('test')).not.toThrow();
-    expect(() => logger.info('test')).not.toThrow();
-    expect(() => logger.warn('test')).not.toThrow();
-    expect(() => logger.error('test')).not.toThrow();
-  });
-});
-
-describe('createScopedLogger', () => {
-  it('should prefix messages with run ID', () => {
-    const calls: string[] = [];
-    const baseLogger = {
-      debug: (msg: string) => calls.push(`debug:${msg}`),
-      info: (msg: string) => calls.push(`info:${msg}`),
-      warn: (msg: string) => calls.push(`warn:${msg}`),
-      error: (msg: string) => calls.push(`error:${msg}`),
-    };
-
-    const scoped = createScopedLogger(baseLogger, 'run-123');
-
-    scoped.debug('d');
-    scoped.info('i');
-    scoped.warn('w');
-    scoped.error('e');
-
-    expect(calls).toEqual([
-      'debug:[run:run-123] d',
-      'info:[run:run-123] i',
-      'warn:[run:run-123] w',
-      'error:[run:run-123] e',
-    ]);
-  });
-
-  it('should include step key when provided', () => {
-    const calls: string[] = [];
-    const baseLogger = {
-      debug: (msg: string) => calls.push(msg),
-      info: (msg: string) => calls.push(msg),
-      warn: (msg: string) => calls.push(msg),
-      error: (msg: string) => calls.push(msg),
-    };
-
-    const scoped = createScopedLogger(baseLogger, 'run-1', 'step-a');
-    scoped.info('hello');
-
-    expect(calls[0]).toBe('[run:run-1][step:step-a] hello');
-  });
-
-  it('should forward extra arguments', () => {
-    const captured: unknown[][] = [];
-    const baseLogger = {
-      debug: (...args: unknown[]) => captured.push(args),
-      info: (...args: unknown[]) => captured.push(args),
-      warn: (...args: unknown[]) => captured.push(args),
-      error: (...args: unknown[]) => captured.push(args),
-    };
-
-    const scoped = createScopedLogger(baseLogger, 'r1');
-    scoped.info('msg', { data: 1 }, 42);
-
-    expect(captured[0]).toEqual(['[run:r1] msg', { data: 1 }, 42]);
-  });
-});

package/src/utils/logger.ts

@@ -1,96 +0,0 @@
-/**
- * Logger utilities for the workflow engine.
- */
-
-import type { Logger, WorkflowError } from '../core/types';
-
-/** Log level for ConsoleLogger. Levels are ordered: debug < info < warn < error. */
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-
-const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
-  debug: 0,
-  info: 1,
-  warn: 2,
-  error: 3,
-};
-
-/**
- * Console-based logger implementation.
- * Uses console.log with prefixes for different levels.
- * Supports a configurable minimum log level (default: 'info').
- */
-export class ConsoleLogger implements Logger {
-  private prefix: string;
-  private minLevel: number;
-
-  constructor(prefix = '[workflow]', level: LogLevel = 'info') {
-    this.prefix = prefix;
-    this.minLevel = LOG_LEVEL_PRIORITY[level];
-  }
-
-  debug(message: string, ...args: unknown[]): void {
-    if (this.minLevel <= LOG_LEVEL_PRIORITY.debug) {
-      console.debug(`${this.prefix} [DEBUG]`, message, ...args);
-    }
-  }
-
-  info(message: string, ...args: unknown[]): void {
-    if (this.minLevel <= LOG_LEVEL_PRIORITY.info) {
-      console.info(`${this.prefix} [INFO]`, message, ...args);
-    }
-  }
-
-  warn(message: string, ...args: unknown[]): void {
-    if (this.minLevel <= LOG_LEVEL_PRIORITY.warn) {
-      console.warn(`${this.prefix} [WARN]`, message, ...args);
-    }
-  }
-
-  error(message: string, ...args: unknown[]): void {
-    if (this.minLevel <= LOG_LEVEL_PRIORITY.error) {
-      console.error(`${this.prefix} [ERROR]`, message, ...args);
-    }
-  }
-}
-
-/**
- * Silent logger that does nothing.
- * Useful for testing or when logs are not wanted.
- */
-export class SilentLogger implements Logger {
-  debug(): void {}
-  info(): void {}
-  warn(): void {}
-  error(): void {}
-}
-
-/**
- * Strip stack traces from a WorkflowError before persisting to storage.
- * Stack traces expose internal file paths and should be kept in logs only.
- */
-export function sanitizeErrorForStorage(error: WorkflowError): WorkflowError {
-  const { stack: _stack, ...rest } = error;
-  return rest;
-}
-
-/**
- * Create a scoped logger that includes run/step context.
- */
-export function createScopedLogger(
-  logger: Logger,
-  runId: string,
-  stepKey?: string
-): Logger {
-  const prefix = stepKey ? `[run:${runId}][step:${stepKey}]` : `[run:${runId}]`;
-
-  return {
-    debug: (message: string, ...args: unknown[]) =>
-      logger.debug(`${prefix} ${message}`, ...args),
-    info: (message: string, ...args: unknown[]) =>
-      logger.info(`${prefix} ${message}`, ...args),
-    warn: (message: string, ...args: unknown[]) =>
-      logger.warn(`${prefix} ${message}`, ...args),
-    error: (message: string, ...args: unknown[]) =>
-      logger.error(`${prefix} ${message}`, ...args),
-  };
-}

package/src/utils/pinned-fetch.test.ts

@@ -1,84 +0,0 @@
-/**
- * pinnedFetch is the linchpin of the M1 (DNS rebinding TOCTOU) fix: by
- * passing a `lookup` function that returns a caller-supplied IP, the TCP
- * connection cannot be re-resolved to a different address. We test it
- * against a real loopback HTTP server because ESM forbids spying on the
- * `http` module's exports and we want to exercise the real request path
- * end-to-end.
- */
-
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import * as http from 'node:http';
-import { pinnedFetch } from './pinned-fetch';
-
-describe('pinnedFetch', () => {
-  let server: http.Server;
-  let port: number;
-  let lastRequest: { hostHeader?: string; method?: string; path?: string; body: string } = {
-    body: '',
-  };
-
-  beforeAll(async () => {
-    server = http.createServer((req, res) => {
-      const chunks: Buffer[] = [];
-      req.on('data', (c: Buffer) => chunks.push(c));
-      req.on('end', () => {
-        lastRequest = {
-          hostHeader: req.headers.host,
-          method: req.method,
-          path: req.url,
-          body: Buffer.concat(chunks).toString('utf8'),
-        };
-        res.writeHead(204, 'No Content');
-        res.end();
-      });
-    });
-    await new Promise<void>((resolve) => {
-      server.listen(0, '127.0.0.1', () => resolve());
-    });
-    port = (server.address() as { port: number }).port;
-  });
-
-  afterAll(async () => {
-    await new Promise<void>((resolve) => server.close(() => resolve()));
-  });
-
-  it('connects to the pinned IP even when the URL hostname is unrelated', async () => {
-    // The URL hostname is one that would never resolve to 127.0.0.1 via DNS.
-    // pinnedFetch must ignore the URL's would-be DNS answer and connect to
-    // the pinned address. If pinning is broken, the connection will fail
-    // or hit a different host.
-    const response = await pinnedFetch(
-      `http://rebind.invalid:${port}/hook`,
-      { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{"ok":1}' },
-      '127.0.0.1',
-      4,
-    );
-
-    expect(response.ok).toBe(true);
-    expect(response.status).toBe(204);
-    expect(lastRequest.method).toBe('POST');
-    expect(lastRequest.path).toBe('/hook');
-    expect(lastRequest.body).toBe('{"ok":1}');
-  });
-
-  it('preserves the original hostname in the Host header (vhost / TLS SNI)', async () => {
-    await pinnedFetch(
-      `http://example.test:${port}/`,
-      { method: 'GET' },
-      '127.0.0.1',
-      4,
-    );
-
-    // The Host header must reflect the URL hostname, not the pinned IP, so
-    // that virtual-host routing and TLS certificate validation work.
-    expect(lastRequest.hostHeader).toContain('example.test');
-  });
-
-  it('rejects when the connection cannot be established', async () => {
-    // Pin to a non-listening port on loopback.
-    await expect(
-      pinnedFetch(`http://example.test:1/`, { method: 'GET' }, '127.0.0.1', 4),
-    ).rejects.toThrow();
-  });
-});

package/src/utils/pinned-fetch.ts

@@ -1,118 +0,0 @@
-/**
- * DNS-pinned fetch helper.
- *
- * Performs an HTTP(S) request that connects to a caller-supplied IP address
- * instead of re-resolving the URL hostname. Used by the webhook transport to
- * close the SSRF DNS-rebinding TOCTOU window: the hostname is resolved
- * exactly once (by the caller), the resolved IP is validated, and the
- * resolved IP is then pinned for the connection so the request cannot be
- * rerouted by a hostile DNS server.
- *
- * The original hostname is preserved for TLS SNI / certificate verification
- * and for the HTTP `Host` header.
- *
- * Audit: 2026-04-27 finding M1 — DNS TOCTOU between SSRF validation and
- * connect.
- */
-
-import * as http from 'node:http';
-import * as https from 'node:https';
-import type { LookupAddress, LookupOptions } from 'node:dns';
-
-/** Minimal fetch-compatible Response surface used by the webhook transport. */
-export interface PinnedFetchResponse {
-  ok: boolean;
-  status: number;
-  statusText: string;
-}
-
-/** Subset of `RequestInit` accepted by `pinnedFetch`. */
-export interface PinnedFetchInit {
-  method?: string;
-  headers?: Record<string, string>;
-  body?: string;
-  signal?: AbortSignal;
-}
-
-/**
- * Make an HTTP(S) request that connects to `address` instead of resolving
- * `url`'s hostname. Returns a minimal `Response`-shaped object compatible
- * with the webhook transport's status / ok checks.
- *
- * @throws Error on transport failure or abort
- */
-export function pinnedFetch(
-  url: string,
-  init: PinnedFetchInit,
-  address: string,
-  family: 4 | 6 = 4,
-): Promise<PinnedFetchResponse> {
-  const parsed = new URL(url);
-  const isHttps = parsed.protocol === 'https:';
-  const lib = isHttps ? https : http;
-  const port = parsed.port ? Number(parsed.port) : isHttps ? 443 : 80;
-
-  // `lookup` is called by the agent's socket-create path. By returning the
-  // pre-validated address here we guarantee the TCP connection target is the
-  // IP whose safety the caller already verified. Node may invoke this with
-  // `{ all: true }` (expects an array result) or single-address mode
-  // (expects positional address/family) — handle both for cross-version safety.
-  const lookup = (
-    _hostname: string,
-    options: LookupOptions,
-    cb: (err: NodeJS.ErrnoException | null, addr: string | LookupAddress[], fam?: number) => void,
-  ): void => {
-    if (options && options.all === true) {
-      cb(null, [{ address, family }]);
-    } else {
-      cb(null, address, family);
-    }
-  };
-
-  return new Promise<PinnedFetchResponse>((resolve, reject) => {
-    const req = lib.request(
-      {
-        hostname: parsed.hostname,
-        port,
-        path: `${parsed.pathname || '/'}${parsed.search}`,
-        method: init.method ?? 'GET',
-        headers: init.headers,
-        lookup,
-        servername: parsed.hostname,
-      },
-      (res) => {
-        // Drain the body — we only inspect status, but leaving the socket
-        // half-read would leak it.
-        res.resume();
-        res.on('end', () => {
-          const status = res.statusCode ?? 0;
-          resolve({
-            ok: status >= 200 && status < 300,
-            status,
-            statusText: res.statusMessage ?? '',
-          });
-        });
-        res.on('error', reject);
-      },
-    );
-
-    req.on('error', reject);
-
-    if (init.signal) {
-      if (init.signal.aborted) {
-        req.destroy(new Error('Request aborted'));
-      } else {
-        init.signal.addEventListener(
-          'abort',
-          () => req.destroy(new Error('Request aborted')),
-          { once: true },
-        );
-      }
-    }
-
-    if (init.body !== undefined) {
-      req.write(init.body);
-    }
-    req.end();
-  });
-}

package/src/utils/postgres-deps.ts

@@ -1,79 +0,0 @@
-/**
- * Shared lazy-loader for PostgreSQL dependencies (kysely + pg).
- *
- * Both `PostgresStorageAdapter` and `PostgresSchedulePersistence` need the same
- * set of optional peer dependencies. This module loads them once and caches the
- * result so the logic isn't duplicated across files.
- */
-
-/**
- * Dynamic imports prevent static type resolution for these modules;
- * `any` is intentional here — callers cast to the appropriate Kysely/pg types.
- */
-export interface PostgresDeps {
-  Kysely: any;
-  PostgresDialect: any;
-  sql: any;
-  pgModule: any;
-}
-
-let cached: PostgresDeps | undefined;
-let loadingPromise: Promise<PostgresDeps> | undefined;
-
-/**
- * Lazily load and cache the PostgreSQL peer dependencies (kysely + pg).
- * @returns The cached `{Kysely, PostgresDialect, sql, pgModule}` object.
- * @throws {Error} If the `kysely` optional peer dependency is not installed.
- * @throws {Error} If the `pg` optional peer dependency is not installed.
- */
-export async function loadPostgresDeps(): Promise<PostgresDeps> {
-  if (cached) return cached;
-  if (loadingPromise) return loadingPromise;
-
-  loadingPromise = (async () => {
-    let Kysely: any;
-    let PostgresDialect: any;
-    let sql: any;
-    let pgModule: any;
-
-    try {
-      const kyselyMod = await import('kysely');
-      Kysely = kyselyMod.Kysely;
-      PostgresDialect = kyselyMod.PostgresDialect;
-      sql = kyselyMod.sql;
-    } catch {
-      throw new Error(
-        'PostgreSQL support requires the "kysely" package. Install it with: npm install kysely'
-      );
-    }
-    try {
-      const pg = await import('pg');
-      pgModule = pg.default ?? pg;
-    } catch {
-      throw new Error(
-        'PostgreSQL support requires the "pg" package. Install it with: npm install pg'
-      );
-    }
-
-    cached = { Kysely, PostgresDialect, sql, pgModule };
-    return cached;
-  })();
-
-  return loadingPromise;
-}
-
-/**
- * Synchronously access the cached PostgreSQL deps. Throws if
- * `loadPostgresDeps()` has not yet completed. Used by code paths that run
- * after `PostgresStorageAdapter.initialize()` and need direct access to
- * `sql` / `Kysely` without re-awaiting.
- */
-export function requirePostgresDeps(): PostgresDeps {
-  if (!cached) {
-    throw new Error(
-      'PostgreSQL dependencies have not been loaded yet. ' +
-      'Call loadPostgresDeps() (or PostgresStorageAdapter.initialize()) first.'
-    );
-  }
-  return cached;
-}

package/src/utils/retry.test.ts

@@ -1,177 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { sleep, withRetry, calculateRetryDelay, DEFAULT_RETRY_OPTIONS } from './retry';
-import { WorkflowCanceledError } from './errors';
-
-describe('sleep', () => {
-  it('should resolve after the given time', async () => {
-    const start = Date.now();
-    await sleep(50);
-    const elapsed = Date.now() - start;
-    expect(elapsed).toBeGreaterThanOrEqual(40);
-  });
-
-  it('should reject immediately if signal is already aborted', async () => {
-    const controller = new AbortController();
-    controller.abort();
-
-    await expect(sleep(1000, controller.signal)).rejects.toThrow(WorkflowCanceledError);
-  });
-
-  it('should reject when signal is aborted during sleep', async () => {
-    const controller = new AbortController();
-
-    const promise = sleep(5000, controller.signal);
-    setTimeout(() => controller.abort(), 20);
-
-    await expect(promise).rejects.toThrow(WorkflowCanceledError);
-  });
-});
-
-describe('calculateRetryDelay', () => {
-  it('should return base delay for first attempt', () => {
-    expect(calculateRetryDelay(1, 1000, 2)).toBe(1000);
-  });
-
-  it('should apply backoff multiplier', () => {
-    expect(calculateRetryDelay(2, 1000, 2)).toBe(2000);
-    expect(calculateRetryDelay(3, 1000, 2)).toBe(4000);
-  });
-
-  it('should work with non-integer backoff', () => {
-    expect(calculateRetryDelay(2, 100, 1.5)).toBe(150);
-  });
-});
-
-describe('DEFAULT_RETRY_OPTIONS', () => {
-  it('should have expected defaults', () => {
-    expect(DEFAULT_RETRY_OPTIONS.maxRetries).toBe(3);
-    expect(DEFAULT_RETRY_OPTIONS.delay).toBe(1000);
-    expect(DEFAULT_RETRY_OPTIONS.backoff).toBe(2);
-  });
-});
-
-describe('withRetry', () => {
-  it('should return result on first success', async () => {
-    const fn = vi.fn().mockResolvedValue('ok');
-    const result = await withRetry(fn, { maxRetries: 3, delay: 10, backoff: 1 });
-
-    expect(result).toBe('ok');
-    expect(fn).toHaveBeenCalledTimes(1);
-  });
-
-  it('should retry on failure and succeed', async () => {
-    let attempt = 0;
-    const fn = vi.fn(async () => {
-      attempt++;
-      if (attempt < 3) throw new Error(`fail ${attempt}`);
-      return 'success';
-    });
-
-    const result = await withRetry(fn, { maxRetries: 3, delay: 10, backoff: 1 });
-
-    expect(result).toBe('success');
-    expect(fn).toHaveBeenCalledTimes(3);
-  });
-
-  it('should throw after exhausting retries', async () => {
-    const fn = vi.fn().mockRejectedValue(new Error('always fails'));
-
-    await expect(
-      withRetry(fn, { maxRetries: 2, delay: 10, backoff: 1 })
-    ).rejects.toThrow('always fails');
-
-    // 1 initial + 2 retries = 3 calls
-    expect(fn).toHaveBeenCalledTimes(3);
-  });
-
-  it('should call onRetry callback', async () => {
-    let attempt = 0;
-    const onRetryCalls: Array<{ attempt: number; delay: number }> = [];
-
-    const fn = vi.fn(async () => {
-      attempt++;
-      if (attempt < 3) throw new Error('fail');
-      return 'ok';
-    });
-
-    await withRetry(fn, {
-      maxRetries: 3,
-      delay: 100,
-      backoff: 2,
-      onRetry: (a, _err, d) => onRetryCalls.push({ attempt: a, delay: d }),
-    });
-
-    expect(onRetryCalls).toHaveLength(2);
-    expect(onRetryCalls[0]).toEqual({ attempt: 1, delay: 100 });
-    expect(onRetryCalls[1]).toEqual({ attempt: 2, delay: 200 });
-  });
-
-  it('should respect abort signal before first attempt', async () => {
-    const controller = new AbortController();
-    controller.abort();
-
-    const fn = vi.fn().mockResolvedValue('ok');
-
-    await expect(
-      withRetry(fn, { maxRetries: 3, delay: 10, backoff: 1, signal: controller.signal })
-    ).rejects.toThrow('canceled');
-
-    expect(fn).not.toHaveBeenCalled();
-  });
-
-  it('should respect abort signal during retry wait', async () => {
-    const controller = new AbortController();
-
-    const fn = vi.fn().mockRejectedValue(new Error('fail'));
-
-    const promise = withRetry(fn, {
-      maxRetries: 5,
-      delay: 5000,
-      backoff: 1,
-      signal: controller.signal,
-    });
-
-    // Abort during the retry delay
-    setTimeout(() => controller.abort(), 50);
-
-    await expect(promise).rejects.toThrow(WorkflowCanceledError);
-  });
-
-  it('should apply backoff between retries', async () => {
-    const timestamps: number[] = [];
-    let attempt = 0;
-
-    const fn = vi.fn(async () => {
-      timestamps.push(Date.now());
-      attempt++;
-      if (attempt <= 2) throw new Error('fail');
-      return 'ok';
-    });
-
-    await withRetry(fn, { maxRetries: 3, delay: 50, backoff: 2 });
-
-    // Check that delay increases between retries
-    const gap1 = timestamps[1] - timestamps[0];
-    const gap2 = timestamps[2] - timestamps[1];
-
-    expect(gap1).toBeGreaterThanOrEqual(40); // ~50ms first delay
-    expect(gap2).toBeGreaterThanOrEqual(80); // ~100ms second delay (50*2)
-  });
-
-  it('should convert non-Error throws to Error', async () => {
-    const fn = vi.fn(async () => {
-      throw 'string error';
-    });
-
-    await expect(
-      withRetry(fn, { maxRetries: 0, delay: 10, backoff: 1 })
-    ).rejects.toThrow('string error');
-  });
-
-  it('should use default options when none provided', async () => {
-    const fn = vi.fn().mockResolvedValue('ok');
-    const result = await withRetry(fn);
-
-    expect(result).toBe('ok');
-  });
-});