reqon-dsl 0.2.0 → 0.3.0

package/src/auth/circuit-breaker.ts

@@ -1,379 +0,0 @@
-/**
- * Circuit Breaker implementation for HTTP requests.
- *
- * Prevents repeated failures from cascading by automatically detecting
- * failure patterns and "opening" the circuit to fail fast.
- *
- * States:
- * - CLOSED: Normal operation, requests pass through
- * - OPEN: Circuit tripped, requests fail immediately
- * - HALF_OPEN: Testing if service recovered, limited requests allowed
- */
-
-export type CircuitState = 'closed' | 'open' | 'half_open';
-
-export interface CircuitBreakerConfig {
-  /** Number of failures before opening circuit (default: 5) */
-  failureThreshold?: number;
-  /** Time in ms before attempting recovery (default: 30000 = 30s) */
-  resetTimeout?: number;
-  /** Number of successful requests in half-open to close circuit (default: 2) */
-  successThreshold?: number;
-  /** Time window in ms for counting failures (default: 60000 = 60s) */
-  failureWindow?: number;
-  /** HTTP status codes to count as failures (default: 500-599) */
-  failureStatusCodes?: number[];
-  /** Whether to count network errors as failures (default: true) */
-  countNetworkErrors?: boolean;
-}
-
-export interface CircuitBreakerStatus {
-  state: CircuitState;
-  failures: number;
-  successes: number;
-  lastFailureTime?: Date;
-  nextAttemptTime?: Date;
-  isOpen: boolean;
-}
-
-export interface CircuitBreakerEvent {
-  source: string;
-  endpoint?: string;
-  state: CircuitState;
-  previousState: CircuitState;
-  failures: number;
-  reason?: string;
-}
-
-export interface CircuitBreakerCallbacks {
-  /** Called when circuit opens (too many failures) */
-  onOpen?: (event: CircuitBreakerEvent) => void;
-  /** Called when circuit closes (recovery successful) */
-  onClose?: (event: CircuitBreakerEvent) => void;
-  /** Called when circuit enters half-open state */
-  onHalfOpen?: (event: CircuitBreakerEvent) => void;
-  /** Called when a request is rejected due to open circuit */
-  onRejected?: (event: { source: string; endpoint?: string; nextAttemptIn: number }) => void;
-}
-
-interface CircuitEntry {
-  state: CircuitState;
-  failures: number;
-  successes: number;
-  failureTimestamps: number[];
-  lastFailureTime?: number;
-  openedAt?: number;
-  config: Required<CircuitBreakerConfig>;
-}
-
-const DEFAULT_CONFIG: Required<CircuitBreakerConfig> = {
-  failureThreshold: 5,
-  resetTimeout: 30000,
-  successThreshold: 2,
-  failureWindow: 60000,
-  failureStatusCodes: [500, 501, 502, 503, 504],
-  countNetworkErrors: true,
-};
-
-/**
- * Error thrown when circuit breaker is open
- */
-export class CircuitBreakerError extends Error {
-  constructor(
-    public readonly source: string,
-    public readonly endpoint: string | undefined,
-    public readonly nextAttemptIn: number
-  ) {
-    super(
-      `Circuit breaker open for ${source}${endpoint ? `:${endpoint}` : ''}. ` +
-        `Next attempt in ${Math.ceil(nextAttemptIn / 1000)}s`
-    );
-    this.name = 'CircuitBreakerError';
-  }
-}
-
-/**
- * Circuit breaker for managing failure detection and recovery
- */
-export class CircuitBreaker {
-  private circuits: Map<string, CircuitEntry> = new Map();
-  private callbacks: CircuitBreakerCallbacks = {};
-  private defaultConfig: Required<CircuitBreakerConfig>;
-
-  constructor(defaultConfig?: CircuitBreakerConfig) {
-    this.defaultConfig = { ...DEFAULT_CONFIG, ...defaultConfig };
-  }
-
-  /**
-   * Configure circuit breaker for a specific source
-   */
-  configure(source: string, config: CircuitBreakerConfig): void {
-    const key = this.getKey(source);
-    const existing = this.circuits.get(key);
-
-    if (existing) {
-      existing.config = { ...this.defaultConfig, ...config };
-    } else {
-      this.circuits.set(key, this.createEntry({ ...this.defaultConfig, ...config }));
-    }
-  }
-
-  /**
-   * Set event callbacks
-   */
-  setCallbacks(callbacks: CircuitBreakerCallbacks): void {
-    this.callbacks = callbacks;
-  }
-
-  /**
-   * Check if a request can proceed (throws if circuit is open)
-   */
-  canProceed(source: string, endpoint?: string): boolean {
-    const entry = this.getOrCreateEntry(source, endpoint);
-    const now = Date.now();
-
-    if (entry.state === 'closed') {
-      return true;
-    }
-
-    if (entry.state === 'open') {
-      const timeSinceOpen = now - (entry.openedAt ?? now);
-
-      if (timeSinceOpen >= entry.config.resetTimeout) {
-        // Transition to half-open
-        this.transitionTo(entry, 'half_open', source, endpoint);
-        return true;
-      }
-
-      return false;
-    }
-
-    // Half-open: allow the request through for testing
-    return true;
-  }
-
-  /**
-   * Ensure request can proceed, throwing CircuitBreakerError if not
-   */
-  ensureCanProceed(source: string, endpoint?: string): void {
-    if (!this.canProceed(source, endpoint)) {
-      const entry = this.getOrCreateEntry(source, endpoint);
-      const now = Date.now();
-      const nextAttemptIn = entry.config.resetTimeout - (now - (entry.openedAt ?? now));
-
-      this.callbacks.onRejected?.({
-        source,
-        endpoint,
-        nextAttemptIn,
-      });
-
-      throw new CircuitBreakerError(source, endpoint, nextAttemptIn);
-    }
-  }
-
-  /**
-   * Record a successful request
-   */
-  recordSuccess(source: string, endpoint?: string): void {
-    const entry = this.getOrCreateEntry(source, endpoint);
-
-    if (entry.state === 'half_open') {
-      entry.successes++;
-
-      if (entry.successes >= entry.config.successThreshold) {
-        // Recovery successful, close the circuit
-        this.transitionTo(entry, 'closed', source, endpoint);
-      }
-    } else if (entry.state === 'closed') {
-      // Clear old failures from window
-      this.pruneOldFailures(entry);
-    }
-  }
-
-  /**
-   * Record a failed request
-   */
-  recordFailure(source: string, endpoint?: string, statusCode?: number, isNetworkError = false): void {
-    const entry = this.getOrCreateEntry(source, endpoint);
-    const config = entry.config;
-
-    // Check if this failure type should be counted
-    const isFailureStatus = statusCode !== undefined && config.failureStatusCodes.includes(statusCode);
-    const shouldCount = isFailureStatus || (isNetworkError && config.countNetworkErrors);
-
-    if (!shouldCount) {
-      return;
-    }
-
-    const now = Date.now();
-
-    if (entry.state === 'half_open') {
-      // Any failure in half-open immediately re-opens circuit
-      this.transitionTo(entry, 'open', source, endpoint, 'Failure during recovery attempt');
-      return;
-    }
-
-    if (entry.state === 'closed') {
-      // Prune old failures and add new one
-      this.pruneOldFailures(entry);
-      entry.failureTimestamps.push(now);
-      entry.failures = entry.failureTimestamps.length;
-      entry.lastFailureTime = now;
-
-      // Check if we should open the circuit
-      if (entry.failures >= config.failureThreshold) {
-        this.transitionTo(
-          entry,
-          'open',
-          source,
-          endpoint,
-          `${entry.failures} failures in ${config.failureWindow}ms window`
-        );
-      }
-    }
-  }
-
-  /**
-   * Get current status for a source/endpoint
-   */
-  getStatus(source: string, endpoint?: string): CircuitBreakerStatus {
-    const entry = this.getOrCreateEntry(source, endpoint);
-    const now = Date.now();
-
-    let nextAttemptTime: Date | undefined;
-    if (entry.state === 'open' && entry.openedAt) {
-      const nextAttemptMs = entry.openedAt + entry.config.resetTimeout;
-      nextAttemptTime = new Date(nextAttemptMs);
-    }
-
-    return {
-      state: entry.state,
-      failures: entry.failures,
-      successes: entry.successes,
-      lastFailureTime: entry.lastFailureTime ? new Date(entry.lastFailureTime) : undefined,
-      nextAttemptTime,
-      isOpen: entry.state === 'open',
-    };
-  }
-
-  /**
-   * Force reset a circuit to closed state
-   */
-  reset(source: string, endpoint?: string): void {
-    const key = this.getKey(source, endpoint);
-    const entry = this.circuits.get(key);
-
-    if (entry) {
-      const previousState = entry.state;
-      entry.state = 'closed';
-      entry.failures = 0;
-      entry.successes = 0;
-      entry.failureTimestamps = [];
-      entry.lastFailureTime = undefined;
-      entry.openedAt = undefined;
-
-      if (previousState !== 'closed') {
-        this.callbacks.onClose?.({
-          source,
-          endpoint,
-          state: 'closed',
-          previousState,
-          failures: 0,
-          reason: 'Manual reset',
-        });
-      }
-    }
-  }
-
-  /**
-   * Get all circuit statuses
-   */
-  getAllStatuses(): Map<string, CircuitBreakerStatus> {
-    const result = new Map<string, CircuitBreakerStatus>();
-
-    for (const [key, entry] of this.circuits) {
-      const [source, endpoint] = key.split(':');
-      result.set(key, this.getStatus(source, endpoint === '' ? undefined : endpoint));
-    }
-
-    return result;
-  }
-
-  private getKey(source: string, endpoint?: string): string {
-    return endpoint ? `${source}:${endpoint}` : source;
-  }
-
-  private createEntry(config: Required<CircuitBreakerConfig>): CircuitEntry {
-    return {
-      state: 'closed',
-      failures: 0,
-      successes: 0,
-      failureTimestamps: [],
-      config,
-    };
-  }
-
-  private getOrCreateEntry(source: string, endpoint?: string): CircuitEntry {
-    const key = this.getKey(source, endpoint);
-    let entry = this.circuits.get(key);
-
-    if (!entry) {
-      // Check for source-level config
-      const sourceEntry = this.circuits.get(source);
-      const config = sourceEntry?.config ?? this.defaultConfig;
-      entry = this.createEntry(config);
-      this.circuits.set(key, entry);
-    }
-
-    return entry;
-  }
-
-  private pruneOldFailures(entry: CircuitEntry): void {
-    const now = Date.now();
-    const windowStart = now - entry.config.failureWindow;
-    entry.failureTimestamps = entry.failureTimestamps.filter((ts) => ts >= windowStart);
-    entry.failures = entry.failureTimestamps.length;
-  }
-
-  private transitionTo(
-    entry: CircuitEntry,
-    newState: CircuitState,
-    source: string,
-    endpoint?: string,
-    reason?: string
-  ): void {
-    const previousState = entry.state;
-    entry.state = newState;
-
-    const event: CircuitBreakerEvent = {
-      source,
-      endpoint,
-      state: newState,
-      previousState,
-      failures: entry.failures,
-      reason,
-    };
-
-    switch (newState) {
-      case 'open':
-        entry.openedAt = Date.now();
-        entry.successes = 0;
-        this.callbacks.onOpen?.(event);
-        break;
-
-      case 'half_open':
-        entry.successes = 0;
-        this.callbacks.onHalfOpen?.(event);
-        break;
-
-      case 'closed':
-        entry.failures = 0;
-        entry.successes = 0;
-        entry.failureTimestamps = [];
-        entry.lastFailureTime = undefined;
-        entry.openedAt = undefined;
-        this.callbacks.onClose?.(event);
-        break;
-    }
-  }
-}

package/src/auth/credentials.test.ts

@@ -1,273 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import {
-  resolveEnvString,
-  hasEnvReference,
-  resolveCredentials,
-  credentialsFromEnv,
-} from './credentials.js';
-
-describe('resolveEnvString', () => {
-  const originalEnv = process.env;
-
-  beforeEach(() => {
-    process.env = { ...originalEnv };
-  });
-
-  afterEach(() => {
-    process.env = originalEnv;
-  });
-
-  it('should resolve $VAR_NAME pattern', () => {
-    process.env.MY_TOKEN = 'secret123';
-    expect(resolveEnvString('Bearer $MY_TOKEN')).toBe('Bearer secret123');
-  });
-
-  it('should resolve ${VAR_NAME} pattern', () => {
-    process.env.API_KEY = 'key456';
-    expect(resolveEnvString('${API_KEY}')).toBe('key456');
-  });
-
-  it('should resolve ${VAR_NAME:-default} pattern with value present', () => {
-    process.env.DB_HOST = 'production.db';
-    expect(resolveEnvString('${DB_HOST:-localhost}')).toBe('production.db');
-  });
-
-  it('should use default when env var is missing', () => {
-    delete process.env.MISSING_VAR;
-    expect(resolveEnvString('${MISSING_VAR:-fallback}')).toBe('fallback');
-  });
-
-  it('should return empty string for missing var without default', () => {
-    delete process.env.MISSING_VAR;
-    expect(resolveEnvString('prefix-${MISSING_VAR}-suffix')).toBe('prefix--suffix');
-  });
-
-  it('should resolve multiple variables in one string', () => {
-    process.env.HOST = 'api.example.com';
-    process.env.PORT = '8080';
-    expect(resolveEnvString('https://${HOST}:${PORT}/path')).toBe(
-      'https://api.example.com:8080/path'
-    );
-  });
-
-  it('should handle mixed patterns', () => {
-    process.env.USER = 'admin';
-    process.env.PASS = 'secret';
-    expect(resolveEnvString('$USER:${PASS}')).toBe('admin:secret');
-  });
-
-  it('should not modify strings without env references', () => {
-    expect(resolveEnvString('plain text')).toBe('plain text');
-  });
-
-  it('should handle empty default value', () => {
-    delete process.env.EMPTY_DEFAULT;
-    expect(resolveEnvString('${EMPTY_DEFAULT:-}')).toBe('');
-  });
-});
-
-describe('hasEnvReference', () => {
-  it('should detect $VAR pattern', () => {
-    expect(hasEnvReference('token: $API_KEY')).toBe(true);
-  });
-
-  it('should detect ${VAR} pattern', () => {
-    expect(hasEnvReference('${SECRET}')).toBe(true);
-  });
-
-  it('should detect ${VAR:-default} pattern', () => {
-    expect(hasEnvReference('${VAR:-default}')).toBe(true);
-  });
-
-  it('should return false for plain strings', () => {
-    expect(hasEnvReference('no variables here')).toBe(false);
-  });
-
-  it('should return false for partial patterns', () => {
-    expect(hasEnvReference('$ not a var')).toBe(false);
-  });
-});
-
-describe('resolveCredentials', () => {
-  const originalEnv = process.env;
-
-  beforeEach(() => {
-    process.env = { ...originalEnv };
-  });
-
-  afterEach(() => {
-    process.env = originalEnv;
-  });
-
-  it('should resolve env vars in nested objects', () => {
-    process.env.GITHUB_TOKEN = 'ghp_xxx';
-    process.env.XERO_CLIENT_ID = 'client123';
-    process.env.XERO_CLIENT_SECRET = 'secret456';
-
-    const config = {
-      GitHub: {
-        type: 'bearer',
-        token: '$GITHUB_TOKEN',
-      },
-      Xero: {
-        type: 'oauth2',
-        clientId: '${XERO_CLIENT_ID}',
-        clientSecret: '${XERO_CLIENT_SECRET}',
-        tokenEndpoint: 'https://identity.xero.com/connect/token',
-      },
-    };
-
-    const resolved = resolveCredentials(config);
-
-    expect(resolved).toEqual({
-      GitHub: {
-        type: 'bearer',
-        token: 'ghp_xxx',
-      },
-      Xero: {
-        type: 'oauth2',
-        clientId: 'client123',
-        clientSecret: 'secret456',
-        tokenEndpoint: 'https://identity.xero.com/connect/token',
-      },
-    });
-  });
-
-  it('should resolve env vars in arrays', () => {
-    process.env.ITEM1 = 'first';
-    process.env.ITEM2 = 'second';
-
-    const config = ['$ITEM1', '${ITEM2}', 'static'];
-    const resolved = resolveCredentials(config);
-
-    expect(resolved).toEqual(['first', 'second', 'static']);
-  });
-
-  it('should handle null and undefined', () => {
-    expect(resolveCredentials(null)).toBe(null);
-    expect(resolveCredentials(undefined)).toBe(undefined);
-  });
-
-  it('should preserve non-string values', () => {
-    const config = {
-      timeout: 5000,
-      enabled: true,
-      items: [1, 2, 3],
-    };
-
-    expect(resolveCredentials(config)).toEqual(config);
-  });
-});
-
-describe('credentialsFromEnv', () => {
-  const originalEnv = process.env;
-
-  beforeEach(() => {
-    process.env = { ...originalEnv };
-  });
-
-  afterEach(() => {
-    process.env = originalEnv;
-  });
-
-  it('should build credentials from REQON_* env vars', () => {
-    process.env.REQON_GITHUB_TOKEN = 'ghp_xxx';
-    process.env.REQON_GITHUB_TYPE = 'bearer';
-
-    const creds = credentialsFromEnv(['GitHub']);
-
-    expect(creds).toEqual({
-      GitHub: {
-        type: 'bearer',
-        token: 'ghp_xxx',
-      },
-    });
-  });
-
-  it('should default to bearer when token is present without type', () => {
-    process.env.REQON_STRIPE_TOKEN = 'sk_live_xxx';
-
-    const creds = credentialsFromEnv(['Stripe']);
-
-    expect(creds).toEqual({
-      Stripe: {
-        type: 'bearer',
-        token: 'sk_live_xxx',
-      },
-    });
-  });
-
-  it('should handle oauth2 credentials', () => {
-    process.env.REQON_XERO_TYPE = 'oauth2';
-    process.env.REQON_XERO_ACCESS_TOKEN = 'access123';
-    process.env.REQON_XERO_REFRESH_TOKEN = 'refresh456';
-    process.env.REQON_XERO_CLIENT_ID = 'client789';
-    process.env.REQON_XERO_TOKEN_ENDPOINT = 'https://identity.xero.com/connect/token';
-
-    const creds = credentialsFromEnv(['Xero']);
-
-    expect(creds).toEqual({
-      Xero: {
-        type: 'oauth2',
-        accessToken: 'access123',
-        refreshToken: 'refresh456',
-        clientId: 'client789',
-        tokenEndpoint: 'https://identity.xero.com/connect/token',
-      },
-    });
-  });
-
-  it('should handle api_key credentials', () => {
-    process.env.REQON_SENDGRID_TYPE = 'api_key';
-    process.env.REQON_SENDGRID_API_KEY = 'SG.xxx';
-    process.env.REQON_SENDGRID_HEADER_NAME = 'Authorization';
-
-    const creds = credentialsFromEnv(['SendGrid']);
-
-    expect(creds).toEqual({
-      SendGrid: {
-        type: 'api_key',
-        apiKey: 'SG.xxx',
-        headerName: 'Authorization',
-      },
-    });
-  });
-
-  it('should skip sources with no credentials', () => {
-    const creds = credentialsFromEnv(['Unknown', 'Missing']);
-
-    expect(creds).toEqual({});
-  });
-
-  it('should handle multiple sources', () => {
-    process.env.REQON_GITHUB_TOKEN = 'ghp_xxx';
-    process.env.REQON_STRIPE_TOKEN = 'sk_xxx';
-
-    const creds = credentialsFromEnv(['GitHub', 'Stripe', 'NoCredentials']);
-
-    expect(creds).toEqual({
-      GitHub: {
-        type: 'bearer',
-        token: 'ghp_xxx',
-      },
-      Stripe: {
-        type: 'bearer',
-        token: 'sk_xxx',
-      },
-    });
-  });
-
-  it('should be case-insensitive for source names', () => {
-    process.env.REQON_MYAPI_TOKEN = 'token123';
-
-    // Uppercase source name
-    const creds = credentialsFromEnv(['MyApi']);
-
-    expect(creds).toEqual({
-      MyApi: {
-        type: 'bearer',
-        token: 'token123',
-      },
-    });
-  });
-});