reqon-dsl 0.2.0

package/src/auth/circuit-breaker.ts

@@ -0,0 +1,379 @@
+/**
+ * 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

@@ -0,0 +1,273 @@
+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',
+      },
+    });
+  });
+});