family-ai-agent 1.0.6 → 1.0.8

package/src/database/health/circuit-breaker.ts

@@ -0,0 +1,214 @@
+/**
+ * Circuit Breaker
+ *
+ * Prevents cascade failures by temporarily blocking calls to failing services.
+ * Implements the circuit breaker pattern for database resilience.
+ */
+
+import type { CircuitBreakerState, CircuitBreakerOptions } from '../types.js';
+import { createLogger } from '../../utils/logger.js';
+
+const logger = createLogger('CircuitBreaker');
+
+/**
+ * Error thrown when circuit is open
+ */
+export class CircuitOpenError extends Error {
+  constructor(message: string = 'Circuit breaker is open') {
+    super(message);
+    this.name = 'CircuitOpenError';
+  }
+}
+
+/**
+ * Default circuit breaker options
+ */
+const DEFAULT_OPTIONS: CircuitBreakerOptions = {
+  failureThreshold: 5,
+  resetTimeoutMs: 60000,
+  halfOpenMaxAttempts: 3,
+};
+
+/**
+ * Circuit breaker for database operations
+ */
+export class CircuitBreaker {
+  private state: CircuitBreakerState = 'closed';
+  private failureCount: number = 0;
+  private successCount: number = 0;
+  private lastFailureTime: number = 0;
+  private options: CircuitBreakerOptions;
+  private stateChangeListeners: Array<(state: CircuitBreakerState) => void> = [];
+
+  constructor(options: Partial<CircuitBreakerOptions> = {}) {
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+  }
+
+  /**
+   * Execute a function with circuit breaker protection
+   */
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    // Check if circuit should transition from open to half-open
+    if (this.state === 'open') {
+      const timeSinceLastFailure = Date.now() - this.lastFailureTime;
+      if (timeSinceLastFailure >= this.options.resetTimeoutMs) {
+        this.transitionTo('half-open');
+      } else {
+        throw new CircuitOpenError(
+          `Circuit breaker is open. Retry in ${Math.ceil(
+            (this.options.resetTimeoutMs - timeSinceLastFailure) / 1000
+          )} seconds.`
+        );
+      }
+    }
+
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      throw error;
+    }
+  }
+
+  /**
+   * Handle successful execution
+   */
+  private onSuccess(): void {
+    this.failureCount = 0;
+
+    if (this.state === 'half-open') {
+      this.successCount++;
+      if (this.successCount >= this.options.halfOpenMaxAttempts) {
+        this.transitionTo('closed');
+      }
+    }
+  }
+
+  /**
+   * Handle failed execution
+   */
+  private onFailure(): void {
+    this.failureCount++;
+    this.lastFailureTime = Date.now();
+    this.successCount = 0;
+
+    if (this.state === 'half-open') {
+      // Immediately open on failure in half-open state
+      this.transitionTo('open');
+    } else if (this.failureCount >= this.options.failureThreshold) {
+      this.transitionTo('open');
+    }
+  }
+
+  /**
+   * Transition to a new state
+   */
+  private transitionTo(newState: CircuitBreakerState): void {
+    if (this.state === newState) return;
+
+    const oldState = this.state;
+    this.state = newState;
+
+    if (newState === 'closed') {
+      this.failureCount = 0;
+      this.successCount = 0;
+    } else if (newState === 'half-open') {
+      this.successCount = 0;
+    }
+
+    logger.info('Circuit breaker state changed', {
+      from: oldState,
+      to: newState,
+    });
+
+    // Notify listeners
+    for (const listener of this.stateChangeListeners) {
+      try {
+        listener(newState);
+      } catch (error) {
+        logger.error('State change listener error', { error });
+      }
+    }
+  }
+
+  /**
+   * Register a state change listener
+   */
+  onStateChange(listener: (state: CircuitBreakerState) => void): () => void {
+    this.stateChangeListeners.push(listener);
+    return () => {
+      const index = this.stateChangeListeners.indexOf(listener);
+      if (index >= 0) {
+        this.stateChangeListeners.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Get current state
+   */
+  getState(): CircuitBreakerState {
+    return this.state;
+  }
+
+  /**
+   * Check if circuit is open
+   */
+  isOpen(): boolean {
+    return this.state === 'open';
+  }
+
+  /**
+   * Check if circuit is half-open
+   */
+  isHalfOpen(): boolean {
+    return this.state === 'half-open';
+  }
+
+  /**
+   * Check if circuit is closed
+   */
+  isClosed(): boolean {
+    return this.state === 'closed';
+  }
+
+  /**
+   * Force circuit to open state
+   */
+  trip(): void {
+    this.lastFailureTime = Date.now();
+    this.transitionTo('open');
+  }
+
+  /**
+   * Force circuit to closed state
+   */
+  reset(): void {
+    this.transitionTo('closed');
+  }
+
+  /**
+   * Get circuit breaker statistics
+   */
+  getStats(): {
+    state: CircuitBreakerState;
+    failureCount: number;
+    successCount: number;
+    lastFailureTime: number | null;
+    timeSinceLastFailure: number | null;
+  } {
+    return {
+      state: this.state,
+      failureCount: this.failureCount,
+      successCount: this.successCount,
+      lastFailureTime: this.lastFailureTime || null,
+      timeSinceLastFailure: this.lastFailureTime
+        ? Date.now() - this.lastFailureTime
+        : null,
+    };
+  }
+}
+
+export default CircuitBreaker;

package/src/database/health/health-monitor.ts

@@ -0,0 +1,224 @@
+/**
+ * Health Monitor
+ *
+ * Monitors database connection health and provides status information.
+ * Integrates with circuit breaker for resilience.
+ */
+
+import type { DatabaseAdapter, DatabaseHealth, HealthMonitorOptions } from '../types.js';
+import { CircuitBreaker } from './circuit-breaker.js';
+import { createLogger } from '../../utils/logger.js';
+
+const logger = createLogger('HealthMonitor');
+
+/**
+ * Default health monitor options
+ */
+const DEFAULT_OPTIONS: HealthMonitorOptions = {
+  checkIntervalMs: 30000,
+  errorThreshold: 3,
+};
+
+/**
+ * Database health monitor
+ */
+export class HealthMonitor {
+  private adapter: DatabaseAdapter;
+  private circuitBreaker: CircuitBreaker;
+  private options: HealthMonitorOptions;
+
+  private checkInterval: NodeJS.Timeout | null = null;
+  private lastStatus: DatabaseHealth | null = null;
+  private consecutiveErrors: number = 0;
+  private isRunning: boolean = false;
+
+  constructor(
+    adapter: DatabaseAdapter,
+    circuitBreaker: CircuitBreaker,
+    options: Partial<HealthMonitorOptions> = {}
+  ) {
+    this.adapter = adapter;
+    this.circuitBreaker = circuitBreaker;
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+  }
+
+  /**
+   * Start health monitoring
+   */
+  start(): void {
+    if (this.isRunning) return;
+
+    this.isRunning = true;
+    this.check(); // Initial check
+
+    this.checkInterval = setInterval(
+      () => this.check(),
+      this.options.checkIntervalMs
+    );
+
+    logger.info('Health monitor started', {
+      intervalMs: this.options.checkIntervalMs,
+    });
+  }
+
+  /**
+   * Stop health monitoring
+   */
+  stop(): void {
+    if (!this.isRunning) return;
+
+    if (this.checkInterval) {
+      clearInterval(this.checkInterval);
+      this.checkInterval = null;
+    }
+
+    this.isRunning = false;
+    logger.info('Health monitor stopped');
+  }
+
+  /**
+   * Perform a health check
+   */
+  async check(): Promise<DatabaseHealth> {
+    const startTime = Date.now();
+    const errors: string[] = [];
+    let isHealthy = false;
+
+    try {
+      isHealthy = await this.circuitBreaker.execute(async () => {
+        return this.adapter.healthCheck();
+      });
+
+      if (isHealthy) {
+        this.consecutiveErrors = 0;
+      } else {
+        this.consecutiveErrors++;
+        errors.push('Health check returned false');
+      }
+    } catch (error) {
+      this.consecutiveErrors++;
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      errors.push(message);
+      logger.warn('Health check failed', { error: message });
+    }
+
+    const latencyMs = Date.now() - startTime;
+    const status = this.determineStatus(errors.length > 0, latencyMs);
+
+    this.lastStatus = {
+      status,
+      type: this.adapter.type,
+      latencyMs,
+      poolStats: this.adapter.getPoolStats?.(),
+      circuitState: this.circuitBreaker.getState(),
+      lastCheck: new Date(),
+      errors,
+    };
+
+    // Log status changes
+    if (status !== 'healthy') {
+      logger.warn('Database health degraded', {
+        status,
+        errors,
+        consecutiveErrors: this.consecutiveErrors,
+      });
+    }
+
+    return this.lastStatus;
+  }
+
+  /**
+   * Determine overall health status
+   */
+  private determineStatus(
+    hasErrors: boolean,
+    latencyMs: number
+  ): 'healthy' | 'degraded' | 'unhealthy' {
+    // Unhealthy if circuit is open or too many consecutive errors
+    if (
+      this.circuitBreaker.isOpen() ||
+      this.consecutiveErrors >= this.options.errorThreshold
+    ) {
+      return 'unhealthy';
+    }
+
+    // Degraded if circuit is half-open, has errors, or high latency
+    if (
+      this.circuitBreaker.isHalfOpen() ||
+      hasErrors ||
+      latencyMs > 1000
+    ) {
+      return 'degraded';
+    }
+
+    return 'healthy';
+  }
+
+  /**
+   * Get current health status
+   */
+  getStatus(): DatabaseHealth | null {
+    return this.lastStatus;
+  }
+
+  /**
+   * Check if database is healthy
+   */
+  isHealthy(): boolean {
+    return this.lastStatus?.status === 'healthy';
+  }
+
+  /**
+   * Check if database is degraded
+   */
+  isDegraded(): boolean {
+    return this.lastStatus?.status === 'degraded';
+  }
+
+  /**
+   * Check if database is unhealthy
+   */
+  isUnhealthy(): boolean {
+    return this.lastStatus?.status === 'unhealthy';
+  }
+
+  /**
+   * Wait for database to become healthy
+   */
+  async waitForHealthy(timeoutMs: number = 30000): Promise<boolean> {
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < timeoutMs) {
+      const status = await this.check();
+      if (status.status === 'healthy') {
+        return true;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+
+    return false;
+  }
+
+  /**
+   * Get health summary for API responses
+   */
+  getSummary(): {
+    healthy: boolean;
+    status: string;
+    database: string;
+    latencyMs: number;
+    circuitBreaker: string;
+  } {
+    const status = this.lastStatus;
+
+    return {
+      healthy: status?.status === 'healthy',
+      status: status?.status ?? 'unknown',
+      database: this.adapter.type,
+      latencyMs: status?.latencyMs ?? -1,
+      circuitBreaker: this.circuitBreaker.getState(),
+    };
+  }
+}
+
+export default HealthMonitor;

package/src/database/health/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Health Monitoring Exports
+ *
+ * Central export for health monitoring and circuit breaker functionality.
+ */
+
+export { CircuitBreaker, CircuitOpenError } from './circuit-breaker.js';
+export { HealthMonitor } from './health-monitor.js';
+
+import { CircuitBreaker } from './circuit-breaker.js';
+import { HealthMonitor } from './health-monitor.js';
+import type { DatabaseAdapter, CircuitBreakerOptions, HealthMonitorOptions } from '../types.js';
+
+/**
+ * Create a health monitoring system for an adapter
+ */
+export function createHealthSystem(
+  adapter: DatabaseAdapter,
+  options: {
+    circuitBreaker?: Partial<CircuitBreakerOptions>;
+    healthMonitor?: Partial<HealthMonitorOptions>;
+  } = {}
+): {
+  circuitBreaker: CircuitBreaker;
+  healthMonitor: HealthMonitor;
+} {
+  const circuitBreaker = new CircuitBreaker(options.circuitBreaker);
+  const healthMonitor = new HealthMonitor(
+    adapter,
+    circuitBreaker,
+    options.healthMonitor
+  );
+
+  return { circuitBreaker, healthMonitor };
+}
+
+export default {
+  CircuitBreaker,
+  HealthMonitor,
+  createHealthSystem,
+};

package/src/database/index.ts

@@ -0,0 +1,157 @@
+/**
+ * Database Layer
+ *
+ * Main entry point for the database abstraction layer.
+ * Provides unified access to PostgreSQL and SQLite with auto-detection.
+ */
+
+// Core types
+export * from './types.js';
+
+// Configuration
+export { getDatabaseConfig, loadDatabaseConfig, buildPostgresUrl, getDefaultSqlitePath } from './db-config.js';
+
+// Adapters
+export {
+  getAdapter,
+  closeAdapter,
+  resetAdapter,
+  detectDatabase,
+  isAdapterInitialized,
+  getAdapterType,
+  PostgresAdapter,
+  SQLiteAdapter,
+  BaseAdapter,
+} from './adapters/index.js';
+
+// Drizzle ORM (exclude duplicate types already exported from types.js)
+export {
+  // Drizzle factories
+  createPgDrizzle,
+  createSqliteDrizzle,
+  isPgDrizzle,
+  isSqliteDrizzle,
+  // Types
+  type DrizzlePgInstance,
+  type DrizzleSqliteInstance,
+  type DrizzleInstance,
+  // Conversations
+  conversationsPg,
+  messagesPg,
+  conversationsSqlite,
+  messagesSqlite,
+  type ConversationPg,
+  type NewConversationPg,
+  type MessagePg,
+  type NewMessagePg,
+  type ConversationSqlite,
+  type NewConversationSqlite,
+  type MessageSqlite,
+  type NewMessageSqlite,
+  type Conversation,
+  type NewConversation,
+  type Message,
+  type NewMessage,
+  // Long-term memories (excluding MemoryType - already in types.js)
+  longTermMemoriesPg,
+  longTermMemoriesSqlite,
+  type LongTermMemoryPg,
+  type NewLongTermMemoryPg,
+  type LongTermMemorySqlite,
+  type NewLongTermMemorySqlite,
+  type LongTermMemory,
+  type NewLongTermMemory,
+  type ParsedMemory,
+  // Documents
+  documentsPg,
+  documentChunksPg,
+  documentsSqlite,
+  documentChunksSqlite,
+  type DocumentPg,
+  type NewDocumentPg,
+  type DocumentChunkPg,
+  type NewDocumentChunkPg,
+  type DocumentSqlite,
+  type NewDocumentSqlite,
+  type DocumentChunkSqlite,
+  type NewDocumentChunkSqlite,
+  type Document,
+  type NewDocument,
+  type DocumentChunk,
+  type NewDocumentChunk,
+  type ParsedDocumentChunk,
+  // Checkpoints
+  checkpointsPg,
+  checkpointWritesPg,
+  checkpointsSqlite,
+  checkpointWritesSqlite,
+  type CheckpointPg,
+  type NewCheckpointPg,
+  type CheckpointWritePg,
+  type NewCheckpointWritePg,
+  type CheckpointSqlite,
+  type NewCheckpointSqlite,
+  type CheckpointWriteSqlite,
+  type NewCheckpointWriteSqlite,
+  type Checkpoint,
+  type NewCheckpoint,
+  type CheckpointWrite,
+  type NewCheckpointWrite,
+  // Audit logs (excluding AuditActionType - already in types.js)
+  auditLogsPg,
+  auditLogsSqlite,
+  type AuditLogPg,
+  type NewAuditLogPg,
+  type AuditLogSqlite,
+  type NewAuditLogSqlite,
+  type AuditLog,
+  type NewAuditLog,
+  type AuditStatus,
+  // Tasks (excluding TaskStatus - already in types.js)
+  tasksPg,
+  tasksSqlite,
+  type TaskPg,
+  type NewTaskPg,
+  type TaskSqlite,
+  type NewTaskSqlite,
+  type Task,
+  type NewTask,
+  TaskPriority,
+  type TaskPriorityLevel,
+  // Schema helpers
+  pgSchema,
+  sqliteSchema,
+} from './drizzle/index.js';
+
+// Vector search
+export {
+  HNSWIndex,
+  EmbeddingCache,
+  PgVectorSearchEngine,
+  SqliteVectorSearchEngine,
+  createVectorSearchEngine,
+  cosineSimilarity,
+  euclideanDistance,
+  parseEmbedding,
+  serializeEmbedding,
+} from './vector/index.js';
+
+// Migrations
+export { Migrator, createMigrator, runMigrations, getCurrentVersion, allMigrations } from './migrations/index.js';
+
+// Health monitoring
+export { CircuitBreaker, CircuitOpenError, HealthMonitor, createHealthSystem } from './health/index.js';
+
+// Caching
+export { QueryCache, getQueryCache, resetQueryCache, cacheKeys, invalidationPatterns } from './cache/index.js';
+
+// Re-export client functions for backward compatibility
+export {
+  initDatabase,
+  closePool,
+  query,
+  transaction,
+  getClient,
+  healthCheck,
+  getPool,
+} from './client.js';

package/src/database/migrations/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Migration System Exports
+ *
+ * Central export for the database migration system.
+ */
+
+export { Migrator } from './migrator.js';
+export { migration001Initial } from './versions/001_initial.js';
+
+import { Migrator } from './migrator.js';
+import { migration001Initial } from './versions/001_initial.js';
+import type { DatabaseAdapter, Migration } from '../types.js';
+
+/**
+ * All registered migrations in order
+ */
+export const allMigrations: Migration[] = [
+  migration001Initial,
+];
+
+/**
+ * Create and configure a migrator with all registered migrations
+ */
+export function createMigrator(adapter: DatabaseAdapter): Migrator {
+  const migrator = new Migrator(adapter);
+  migrator.registerAll(allMigrations);
+  return migrator;
+}
+
+/**
+ * Run all pending migrations
+ */
+export async function runMigrations(adapter: DatabaseAdapter) {
+  const migrator = createMigrator(adapter);
+  return migrator.migrate();
+}
+
+/**
+ * Get current schema version
+ */
+export async function getCurrentVersion(adapter: DatabaseAdapter): Promise<number> {
+  const migrator = createMigrator(adapter);
+  return migrator.getCurrentVersion();
+}
+
+export default {
+  Migrator,
+  allMigrations,
+  createMigrator,
+  runMigrations,
+  getCurrentVersion,
+};