@elevasis/core 0.1.0

package/src/platform/resilience/circuit-breaker.ts

@@ -0,0 +1,164 @@
+/**
+ * Generic circuit breaker state machine.
+ * Provides the core state management logic that can be reused across different services.
+ *
+ * State Transitions:
+ * - CLOSED -> OPEN: After failureThreshold consecutive failures
+ * - OPEN -> HALF_OPEN: After resetTimeoutMs has elapsed
+ * - HALF_OPEN -> CLOSED: After successThreshold consecutive successes
+ * - HALF_OPEN -> OPEN: On any failure
+ */
+
+import { ServiceUnavailableError } from './errors'
+import {
+  CIRCUIT_BREAKER_FAILURE_THRESHOLD,
+  CIRCUIT_BREAKER_COOLDOWN_MS,
+  CIRCUIT_BREAKER_SUCCESS_THRESHOLD,
+  CIRCUIT_BREAKER_HALF_OPEN_MAX_REQUESTS
+} from '../constants/resilience'
+
+export enum CircuitState {
+  CLOSED = 'closed',
+  OPEN = 'open',
+  HALF_OPEN = 'half_open'
+}
+
+export interface CircuitBreakerConfig {
+  /** Number of failures before opening circuit (default: 5) */
+  failureThreshold?: number
+  /** Time in ms before attempting recovery (default: 60000) */
+  resetTimeoutMs?: number
+  /** Successes needed to close circuit from half-open (default: 2) */
+  successThreshold?: number
+  /** Max concurrent requests in half-open state (default: 3) */
+  halfOpenMaxRequests?: number
+  /** Called when circuit state changes. Use for alerting on OPEN transitions. */
+  onStateChange?: (service: string, from: CircuitState, to: CircuitState, context: { failureCount: number }) => void
+}
+
+export interface CircuitBreaker {
+  /** Execute a function through the circuit breaker */
+  execute<T>(fn: () => Promise<T>): Promise<T>
+  /** Get current circuit state */
+  getState(): CircuitState
+  /** Get current failure count */
+  getFailureCount(): number
+  /** Reset circuit to closed state */
+  reset(): void
+}
+
+const DEFAULT_CONFIG: Required<Pick<CircuitBreakerConfig, 'failureThreshold' | 'resetTimeoutMs' | 'successThreshold' | 'halfOpenMaxRequests'>> = {
+  failureThreshold: CIRCUIT_BREAKER_FAILURE_THRESHOLD,
+  resetTimeoutMs: CIRCUIT_BREAKER_COOLDOWN_MS,
+  successThreshold: CIRCUIT_BREAKER_SUCCESS_THRESHOLD,
+  halfOpenMaxRequests: CIRCUIT_BREAKER_HALF_OPEN_MAX_REQUESTS
+}
+
+/**
+ * Creates a circuit breaker instance for a specific service.
+ *
+ * @param service - Service name for error context (e.g., 'llm:gpt-4', 'workos')
+ * @param config - Optional configuration overrides
+ * @returns CircuitBreaker instance
+ *
+ * @example
+ * ```typescript
+ * const breaker = createCircuitBreaker('workos')
+ *
+ * try {
+ *   const result = await breaker.execute(() => workos.userManagement.getUser(id))
+ * } catch (error) {
+ *   if (error instanceof ServiceUnavailableError) {
+ *     // Circuit is open, service unavailable
+ *   }
+ * }
+ * ```
+ */
+export function createCircuitBreaker(
+  service: string,
+  config?: CircuitBreakerConfig
+): CircuitBreaker {
+  const cfg = { ...DEFAULT_CONFIG, ...config }
+
+  let state = CircuitState.CLOSED
+  let failureCount = 0
+  let successCount = 0
+  let lastFailureTime = 0
+  let halfOpenRequests = 0
+
+  return {
+    async execute<T>(fn: () => Promise<T>): Promise<T> {
+      // Check if circuit should transition from OPEN to HALF_OPEN
+      if (state === CircuitState.OPEN) {
+        if (Date.now() - lastFailureTime >= cfg.resetTimeoutMs) {
+          const prev = state
+          state = CircuitState.HALF_OPEN
+          halfOpenRequests = 0
+          successCount = 0
+          cfg.onStateChange?.(service, prev, state, { failureCount })
+        } else {
+          throw new ServiceUnavailableError(service, 'circuit_open', {
+            failureCount,
+            resetIn: cfg.resetTimeoutMs - (Date.now() - lastFailureTime)
+          })
+        }
+      }
+
+      // In HALF_OPEN, limit concurrent requests to prevent thundering herd
+      if (state === CircuitState.HALF_OPEN) {
+        if (halfOpenRequests >= cfg.halfOpenMaxRequests) {
+          throw new ServiceUnavailableError(service, 'circuit_open', {
+            reason: 'half_open_limit_reached'
+          })
+        }
+        halfOpenRequests++
+      }
+
+      try {
+        const result = await fn()
+
+        // Success handling
+        if (state === CircuitState.HALF_OPEN) {
+          successCount++
+          if (successCount >= cfg.successThreshold) {
+            const prev = state
+            state = CircuitState.CLOSED
+            failureCount = 0
+            cfg.onStateChange?.(service, prev, state, { failureCount: 0 })
+          }
+        } else {
+          // Reset failure count on success in CLOSED state
+          failureCount = 0
+        }
+
+        return result
+      } catch (error) {
+        failureCount++
+        lastFailureTime = Date.now()
+
+        if (state === CircuitState.HALF_OPEN) {
+          // Any failure in HALF_OPEN immediately opens the circuit
+          const prev = state
+          state = CircuitState.OPEN
+          cfg.onStateChange?.(service, prev, state, { failureCount })
+        } else if (failureCount >= cfg.failureThreshold) {
+          // Threshold reached in CLOSED state
+          const prev = state
+          state = CircuitState.OPEN
+          cfg.onStateChange?.(service, prev, state, { failureCount })
+        }
+
+        throw error
+      }
+    },
+
+    getState: () => state,
+    getFailureCount: () => failureCount,
+    reset: () => {
+      state = CircuitState.CLOSED
+      failureCount = 0
+      successCount = 0
+      halfOpenRequests = 0
+    }
+  }
+}

package/src/platform/resilience/errors.ts

@@ -0,0 +1,68 @@
+/**
+ * Infrastructure error types for resilience utilities.
+ * These errors represent external service failures (not business logic errors).
+ * Map to HTTP 503 Service Unavailable.
+ */
+
+/**
+ * Thrown when an external service operation times out.
+ * Maps to HTTP 503 Service Unavailable.
+ */
+export class ServiceTimeoutError extends Error {
+  readonly service: string
+  readonly timeoutMs: number
+  readonly operation?: string
+  readonly context?: Record<string, unknown>
+
+  constructor(
+    service: string,
+    timeoutMs: number,
+    operation?: string,
+    context?: Record<string, unknown>
+  ) {
+    const op = operation ? `:${operation}` : ''
+    super(`${service}${op} timed out after ${timeoutMs}ms`)
+    this.name = 'ServiceTimeoutError'
+    this.service = service
+    this.timeoutMs = timeoutMs
+    this.operation = operation
+    this.context = context
+  }
+}
+
+/**
+ * Thrown when an external service is unavailable (circuit open, repeated failures).
+ * Maps to HTTP 503 Service Unavailable.
+ */
+export class ServiceUnavailableError extends Error {
+  readonly service: string
+  readonly reason: 'circuit_open' | 'timeout' | 'connection_failed'
+  readonly context?: Record<string, unknown>
+
+  constructor(
+    service: string,
+    reason: 'circuit_open' | 'timeout' | 'connection_failed',
+    context?: Record<string, unknown>
+  ) {
+    super(`${service} temporarily unavailable (${reason})`)
+    this.name = 'ServiceUnavailableError'
+    this.service = service
+    this.reason = reason
+    this.context = context
+  }
+}
+
+/**
+ * Type guard to check if an error is an infrastructure error (ServiceTimeoutError or ServiceUnavailableError).
+ * Infrastructure errors should map to HTTP 503, not 401 or 500.
+ */
+export function isInfrastructureError(
+  error: unknown
+): error is ServiceTimeoutError | ServiceUnavailableError {
+  if (error instanceof ServiceTimeoutError) return true
+  if (error instanceof ServiceUnavailableError) return true
+
+  // Also check for common network error codes
+  const code = (error as { code?: string })?.code
+  return code === 'ETIMEDOUT' || code === 'ECONNREFUSED' || code === 'ENOTFOUND'
+}

package/src/platform/resilience/http-error-mapper.ts

@@ -0,0 +1,129 @@
+/**
+ * HTTP Error Mapper
+ *
+ * Shared utility for mapping HTTP status codes to ToolingError types.
+ * Used by all integration adapters for consistent error handling.
+ *
+ * Standard mapping:
+ * - 401/403 -> credentials_invalid (authentication failed)
+ * - 400/404/409 -> validation_error (non-retryable client errors)
+ * - 429 -> rate_limit_exceeded (retryable)
+ * - 500+ -> server_unavailable (retryable)
+ * - Other 4xx -> validation_error (non-retryable)
+ * - Other -> api_error (retryable)
+ */
+
+import { ToolingError, type ToolingErrorType } from '../../execution/engine/tools/types'
+
+/**
+ * Context for HTTP error creation
+ */
+export interface HttpErrorContext {
+  integration: string
+  method: string
+  statusCode?: number
+  organizationId?: string
+  [key: string]: unknown
+}
+
+/**
+ * Custom error parser function type
+ * Allows adapters to extract error messages from API-specific response formats
+ */
+export type ErrorParser = (responseBody: string) => string | undefined
+
+/**
+ * Map HTTP status code to ToolingError type
+ *
+ * Standard mapping used by all integration adapters:
+ * - 401/403 -> credentials_invalid (authentication failed)
+ * - 400/404/409 -> validation_error (non-retryable client errors)
+ * - 429 -> rate_limit_exceeded (retryable)
+ * - 500+ -> server_unavailable (retryable)
+ * - Other 4xx -> validation_error (non-retryable)
+ * - Other -> api_error (retryable)
+ *
+ * @param status - HTTP status code
+ * @returns ToolingErrorType for the status code
+ */
+export function mapHttpStatusToErrorType(status: number): ToolingErrorType {
+  if (status === 401 || status === 403) return 'credentials_invalid'
+  if (status === 404 || status === 400 || status === 409) return 'validation_error'
+  if (status === 429) return 'rate_limit_exceeded'
+  if (status >= 500) return 'server_unavailable'
+  if (status >= 400) return 'validation_error'
+  return 'api_error'
+}
+
+/**
+ * Create ToolingError from HTTP response
+ *
+ * Reads response body, parses error message, and creates appropriate ToolingError.
+ * Supports custom error parser for API-specific response formats.
+ *
+ * @param response - Fetch Response object
+ * @param context - Error context (integration name, method, etc.)
+ * @param parseError - Optional custom parser for API-specific error formats
+ * @returns ToolingError with appropriate type and message
+ *
+ * @example
+ * // Basic usage
+ * if (!response.ok) {
+ *   throw await createHttpError(response, {
+ *     integration: 'attio',
+ *     method: 'listRecords',
+ *     listId
+ *   })
+ * }
+ *
+ * @example
+ * // With custom error parser
+ * if (!response.ok) {
+ *   throw await createHttpError(
+ *     response,
+ *     { integration: 'attio', method: 'createRecord' },
+ *     (body) => {
+ *       const json = JSON.parse(body)
+ *       return json.message
+ *     }
+ *   )
+ * }
+ */
+export async function createHttpError(
+  response: Response,
+  context: HttpErrorContext,
+  parseError?: ErrorParser
+): Promise<ToolingError> {
+  const errorText = await response.text()
+  let message = `${context.integration} API error: ${response.status} ${response.statusText}`
+
+  // Try custom parser first, then generic JSON parsing
+  if (parseError) {
+    try {
+      const parsed = parseError(errorText)
+      if (parsed) message = parsed
+    } catch {
+      // Custom parser failed, fall through to generic parsing
+    }
+  }
+
+  // Generic JSON parsing if no custom parser or custom parser didn't return a message
+  if (!parseError || message.includes('API error:')) {
+    try {
+      const json = JSON.parse(errorText)
+      const parsedMessage = json.message || json.error?.message
+      if (parsedMessage) message = parsedMessage
+    } catch {
+      // Response is not JSON, use raw text if available
+      if (errorText && errorText.length < 500) {
+        message = errorText
+      }
+    }
+  }
+
+  return new ToolingError(
+    mapHttpStatusToErrorType(response.status),
+    message,
+    { ...context, statusCode: response.status }
+  )
+}

package/src/platform/resilience/index.ts

@@ -0,0 +1,93 @@
+/**
+ * Resilience utilities for protecting against external service failures.
+ *
+ * This module provides:
+ * - Timeout wrappers for external service calls
+ * - Circuit breaker pattern for preventing cascading failures
+ * - Infrastructure error types for proper error classification
+ * - Rate limiting (token bucket algorithm)
+ * - Retry with exponential backoff
+ * - HTTP error mapping
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   withTimeout,
+ *   SERVICE_TIMEOUTS,
+ *   createCircuitBreaker,
+ *   ServiceTimeoutError,
+ *   ServiceUnavailableError,
+ *   isInfrastructureError,
+ *   withRetry,
+ *   DEFAULT_RETRY_POLICY,
+ *   createRateLimiter,
+ *   createHttpError
+ * } from '@repo/core/resilience'
+ *
+ * // Wrap external calls with timeout
+ * const result = await withTimeout(
+ *   externalService.call(),
+ *   SERVICE_TIMEOUTS.WORKOS_JWT,
+ *   'ServiceName',
+ *   'operation'
+ * )
+ *
+ * // Use circuit breaker for services with repeated failures
+ * const breaker = createCircuitBreaker('my-service')
+ * const data = await breaker.execute(() => myService.fetch())
+ *
+ * // Use retry with exponential backoff
+ * const response = await withRetry(
+ *   () => fetch('/api/data'),
+ *   DEFAULT_RETRY_POLICY
+ * )
+ * ```
+ */
+
+// Error types
+export {
+  ServiceTimeoutError,
+  ServiceUnavailableError,
+  isInfrastructureError
+} from './errors'
+
+// Timeout utility
+export { withTimeout, SERVICE_TIMEOUTS } from './timeout'
+
+// Circuit breaker
+export {
+  createCircuitBreaker,
+  CircuitState,
+  type CircuitBreaker,
+  type CircuitBreakerConfig
+} from './circuit-breaker'
+
+// Rate limiting
+export {
+  InMemoryRateLimiter,
+  createRateLimiter
+} from './rate-limiter'
+
+// Retry logic
+export {
+  withRetry,
+  calculateRetryDelay,
+  sleep
+} from './retry'
+
+// Rate limiter types
+export {
+  type RateLimiter,
+  type RetryPolicy
+} from './rate-limiter-types'
+
+// Retry policy constant (canonical source: constants/resilience)
+export { DEFAULT_RETRY_POLICY } from '../constants/resilience'
+
+// HTTP error mapping
+export {
+  createHttpError,
+  mapHttpStatusToErrorType,
+  type HttpErrorContext,
+  type ErrorParser
+} from './http-error-mapper'

package/src/platform/resilience/rate-limiter-types.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared utility types for integration tools
+ *
+ * These types define the interfaces for rate limiting and retry logic
+ * that are used by integration tools.
+ */
+
+/**
+ * Rate limiter interface
+ * Implements token bucket algorithm for rate limiting
+ */
+export interface RateLimiter {
+  /**
+   * Check if request is allowed
+   * @param key - Rate limit key (e.g., '${organizationId}:${integration}')
+   * @returns true if allowed, false if rate limited
+   */
+  allow(key: string): Promise<boolean>
+
+  /**
+   * Get remaining tokens for key
+   * @param key - Rate limit key
+   * @returns Number of tokens remaining
+   */
+  remaining(key: string): Promise<number>
+
+  /**
+   * Reset rate limit for key
+   * @param key - Rate limit key
+   */
+  reset(key: string): Promise<void>
+}
+
+/**
+ * Retry policy configuration
+ */
+export interface RetryPolicy {
+  /** Maximum number of retry attempts */
+  maxRetries: number
+  /** Initial delay in ms (exponential backoff) */
+  initialDelayMs: number
+  /** Maximum delay in ms (cap for exponential backoff) */
+  maxDelayMs: number
+  /** Jitter factor (0-1, adds randomness to prevent thundering herd) */
+  jitterFactor: number
+}

package/src/platform/resilience/rate-limiter.ts

@@ -0,0 +1,140 @@
+import type { RateLimiter } from './rate-limiter-types'
+import { DEFAULT_RATE_LIMIT_CAPACITY, DEFAULT_RATE_LIMIT_WINDOW_MS, STALE_BUCKET_MULTIPLIER } from '../constants/resilience'
+
+/**
+ * Token bucket state
+ */
+interface TokenBucket {
+  tokens: number
+  lastRefill: number
+}
+
+/**
+ * In-memory token bucket rate limiter
+ *
+ * Implements token bucket algorithm for rate limiting integration API calls.
+ * Default: 60 requests per minute per organization per integration.
+ *
+ * Pattern: Stateful class (justified - manages rate limit state)
+ *
+ * @example
+ * const limiter = new InMemoryRateLimiter(60, 60000) // 60 req/min
+ * const allowed = await limiter.allow('org123:gmail')
+ * if (!allowed) {
+ *   throw new ToolingError('rate_limit_exceeded', 'Rate limit exceeded')
+ * }
+ */
+export class InMemoryRateLimiter implements RateLimiter {
+  private buckets = new Map<string, TokenBucket>()
+  private lastEviction = Date.now()
+
+  /**
+   * @param capacity - Maximum tokens (requests) allowed
+   * @param refillIntervalMs - Refill interval in milliseconds
+   */
+  constructor(
+    private readonly capacity: number = DEFAULT_RATE_LIMIT_CAPACITY,
+    private readonly refillIntervalMs: number = DEFAULT_RATE_LIMIT_WINDOW_MS
+  ) {}
+
+  /**
+   * Check if request is allowed and consume token if available
+   */
+  async allow(key: string): Promise<boolean> {
+    const bucket = this.getOrCreateBucket(key)
+    this.refillBucket(bucket)
+
+    if (bucket.tokens > 0) {
+      bucket.tokens -= 1
+      return true
+    }
+
+    return false
+  }
+
+  /**
+   * Get remaining tokens for key
+   */
+  async remaining(key: string): Promise<number> {
+    const bucket = this.getOrCreateBucket(key)
+    this.refillBucket(bucket)
+    return Math.floor(bucket.tokens)
+  }
+
+  /**
+   * Reset rate limit for key (removes bucket)
+   */
+  async reset(key: string): Promise<void> {
+    this.buckets.delete(key)
+  }
+
+  /**
+   * Get or create token bucket for key
+   * Lazily evicts stale buckets to prevent memory leaks
+   */
+  private getOrCreateBucket(key: string): TokenBucket {
+    this.evictStaleBuckets()
+
+    let bucket = this.buckets.get(key)
+    if (!bucket) {
+      bucket = {
+        tokens: this.capacity,
+        lastRefill: Date.now()
+      }
+      this.buckets.set(key, bucket)
+    }
+    return bucket
+  }
+
+  /**
+   * Evict buckets that haven't been accessed in 5x the refill interval
+   * Runs at most once per refill interval to avoid overhead
+   */
+  private evictStaleBuckets(): void {
+    const now = Date.now()
+    if (now - this.lastEviction < this.refillIntervalMs) return
+    this.lastEviction = now
+
+    const staleThreshold = this.refillIntervalMs * STALE_BUCKET_MULTIPLIER
+    for (const [key, bucket] of this.buckets) {
+      if (now - bucket.lastRefill > staleThreshold) {
+        this.buckets.delete(key)
+      }
+    }
+  }
+
+  /**
+   * Refill bucket based on time elapsed
+   * Uses linear refill: tokens added = (elapsed / interval) * capacity
+   */
+  private refillBucket(bucket: TokenBucket): void {
+    const now = Date.now()
+    const elapsed = now - bucket.lastRefill
+
+    if (elapsed >= this.refillIntervalMs) {
+      // Full refill if interval passed
+      bucket.tokens = this.capacity
+      bucket.lastRefill = now
+    } else {
+      // Partial refill based on elapsed time
+      const tokensToAdd = (elapsed / this.refillIntervalMs) * this.capacity
+      bucket.tokens = Math.min(this.capacity, bucket.tokens + tokensToAdd)
+      bucket.lastRefill = now
+    }
+  }
+
+  /**
+   * Clear all buckets (for testing)
+   */
+  clearAll(): void {
+    this.buckets.clear()
+  }
+}
+
+/**
+ * Create default rate limiter instance
+ * 60 requests per minute per organization per integration
+ */
+export function createRateLimiter(): RateLimiter {
+  return new InMemoryRateLimiter(DEFAULT_RATE_LIMIT_CAPACITY, DEFAULT_RATE_LIMIT_WINDOW_MS)
+}