@vorionsys/platform-core 0.1.0

package/dist/common/database-resilience.js

@@ -0,0 +1,269 @@
+/**
+ * Database Circuit Breaker and Resilience
+ *
+ * Provides circuit breaker protection for database operations to prevent
+ * cascading failures when the database is unavailable or degraded.
+ *
+ * Features:
+ * - Circuit breaker with CLOSED -> OPEN -> HALF_OPEN states
+ * - Configurable failure threshold and reset timeout
+ * - Statement timeout enforcement via PostgreSQL
+ * - Metrics export for monitoring
+ * - Graceful degradation support
+ *
+ * @packageDocumentation
+ */
+import { getCircuitBreaker, CircuitBreakerOpenError, withCircuitBreaker, withCircuitBreakerResult, } from './circuit-breaker.js';
+import { getConfig } from './config.js';
+import { getPool, withStatementTimeout, DEFAULT_STATEMENT_TIMEOUT_MS } from './db.js';
+import { createLogger } from './logger.js';
+const logger = createLogger({ component: 'database-resilience' });
+// Re-export useful types from circuit-breaker
+export { CircuitBreakerOpenError };
+/**
+ * Database operation timeout in milliseconds
+ * Default: 30 seconds (configurable via config)
+ */
+export const DB_OPERATION_TIMEOUT_MS = 30000;
+/**
+ * Database circuit breaker service name
+ */
+export const DATABASE_SERVICE_NAME = 'database';
+/**
+ * Get the database circuit breaker instance
+ */
+export function getDatabaseCircuitBreaker() {
+    return getCircuitBreaker(DATABASE_SERVICE_NAME, (from, to, _breaker) => {
+        logger.info({ service: DATABASE_SERVICE_NAME, fromState: from, toState: to }, `Database circuit breaker state transition: ${from} -> ${to}`);
+    });
+}
+/**
+ * Check if the database circuit is currently open
+ */
+export async function isDatabaseCircuitOpen() {
+    const breaker = getDatabaseCircuitBreaker();
+    return await breaker.isOpen();
+}
+/**
+ * Get database circuit breaker status for monitoring
+ */
+export async function getDatabaseCircuitStatus() {
+    const breaker = getDatabaseCircuitBreaker();
+    return await breaker.getStatus();
+}
+/**
+ * Execute a database query with circuit breaker protection and timeout.
+ *
+ * This wrapper provides:
+ * 1. Circuit breaker protection - fast fail when DB is unhealthy
+ * 2. Statement timeout - prevents long-running queries
+ * 3. Metrics recording - tracks success/failure rates
+ *
+ * @param fn - The database operation to execute
+ * @param options - Optional configuration
+ * @returns The result of the database operation
+ * @throws CircuitBreakerOpenError when circuit is open
+ * @throws StatementTimeoutError when query exceeds timeout
+ *
+ * @example
+ * ```typescript
+ * const users = await withDatabaseCircuitBreaker(
+ *   async () => db.select().from(users).limit(100),
+ *   { operationName: 'listUsers' }
+ * );
+ * ```
+ */
+export async function withDatabaseCircuitBreaker(fn, options = {}) {
+    const config = getConfig();
+    const operationName = options.operationName ?? 'unknown';
+    const timeoutMs = options.timeoutMs ?? config.database.statementTimeoutMs ?? DEFAULT_STATEMENT_TIMEOUT_MS;
+    // Wrap with statement timeout first, then circuit breaker
+    return withCircuitBreaker(DATABASE_SERVICE_NAME, async () => {
+        return withStatementTimeout(fn, timeoutMs, operationName);
+    });
+}
+/**
+ * Execute a database operation with circuit breaker protection,
+ * returning a result object instead of throwing on circuit open.
+ *
+ * This variant is useful when you want to handle circuit open gracefully
+ * without try/catch, or when you want to use a fallback value.
+ *
+ * @param fn - The database operation to execute
+ * @param options - Optional configuration
+ * @returns Result object with success flag and result/error
+ *
+ * @example
+ * ```typescript
+ * const result = await withDatabaseCircuitBreakerResult(
+ *   async () => db.select().from(cache).where(eq(cache.key, key)),
+ *   { operationName: 'getCacheEntry' }
+ * );
+ *
+ * if (result.circuitOpen) {
+ *   // Use fallback - maybe return cached data or default
+ *   return getFromLocalCache(key) ?? defaultValue;
+ * }
+ *
+ * return result.success ? result.result : defaultValue;
+ * ```
+ */
+export async function withDatabaseCircuitBreakerResult(fn, options = {}) {
+    const config = getConfig();
+    const operationName = options.operationName ?? 'unknown';
+    const timeoutMs = options.timeoutMs ?? config.database.statementTimeoutMs ?? DEFAULT_STATEMENT_TIMEOUT_MS;
+    return withCircuitBreakerResult(DATABASE_SERVICE_NAME, async () => {
+        return withStatementTimeout(fn, timeoutMs, operationName);
+    });
+}
+/**
+ * Execute a raw SQL query with circuit breaker protection.
+ *
+ * For cases where you need to execute raw SQL without Drizzle ORM.
+ *
+ * @param sql - SQL query string
+ * @param params - Query parameters
+ * @param options - Optional configuration
+ * @returns Query result
+ */
+export async function executeWithCircuitBreaker(sql, params = [], options = {}) {
+    const pool = getPool();
+    if (!pool) {
+        throw new Error('Database pool not initialized');
+    }
+    const config = getConfig();
+    const timeoutMs = options.timeoutMs ?? config.database.statementTimeoutMs ?? DEFAULT_STATEMENT_TIMEOUT_MS;
+    return withCircuitBreaker(DATABASE_SERVICE_NAME, async () => {
+        // Set statement timeout for this query
+        const client = await pool.connect();
+        try {
+            await client.query(`SET statement_timeout = ${timeoutMs}`);
+            const result = await client.query(sql, params);
+            return result.rows;
+        }
+        finally {
+            client.release();
+        }
+    });
+}
+/**
+ * Force the database circuit breaker to open state.
+ * Useful for manual intervention during maintenance or incidents.
+ */
+export async function forceDatabaseCircuitOpen() {
+    const breaker = getDatabaseCircuitBreaker();
+    await breaker.forceOpen();
+    logger.warn({}, 'Database circuit breaker manually opened');
+}
+/**
+ * Force the database circuit breaker to closed state.
+ * Useful for manual recovery after maintenance.
+ */
+export async function forceDatabaseCircuitClose() {
+    const breaker = getDatabaseCircuitBreaker();
+    await breaker.forceClose();
+    logger.info({}, 'Database circuit breaker manually closed');
+}
+/**
+ * Reset the database circuit breaker.
+ * Clears all state and returns to CLOSED state.
+ */
+export async function resetDatabaseCircuit() {
+    const breaker = getDatabaseCircuitBreaker();
+    await breaker.reset();
+    logger.info({}, 'Database circuit breaker reset');
+}
+/**
+ * Database health check with circuit breaker status.
+ *
+ * Returns comprehensive health information including:
+ * - Database connectivity status
+ * - Circuit breaker state
+ * - Latency metrics
+ */
+export async function checkDatabaseHealthWithCircuit() {
+    const breaker = getDatabaseCircuitBreaker();
+    const status = await breaker.getStatus();
+    // If circuit is open, don't even try to check database
+    if (status.state === 'OPEN') {
+        return {
+            healthy: false,
+            error: 'Circuit breaker is OPEN - database marked as unavailable',
+            circuit: {
+                state: status.state,
+                failureCount: status.failureCount,
+                failureThreshold: status.failureThreshold,
+                timeUntilReset: status.timeUntilReset,
+            },
+        };
+    }
+    const pool = getPool();
+    if (!pool) {
+        return {
+            healthy: false,
+            error: 'Database pool not initialized',
+            circuit: {
+                state: status.state,
+                failureCount: status.failureCount,
+                failureThreshold: status.failureThreshold,
+                timeUntilReset: status.timeUntilReset,
+            },
+        };
+    }
+    const start = performance.now();
+    try {
+        // Use circuit breaker for the health check itself
+        const result = await withDatabaseCircuitBreakerResult(async () => {
+            const client = await pool.connect();
+            try {
+                await client.query('SELECT 1 as health_check');
+                return true;
+            }
+            finally {
+                client.release();
+            }
+        }, { operationName: 'healthCheck', timeoutMs: 5000 });
+        const latencyMs = Math.round(performance.now() - start);
+        const updatedStatus = await breaker.getStatus();
+        if (result.circuitOpen) {
+            return {
+                healthy: false,
+                latencyMs,
+                error: 'Circuit breaker is OPEN',
+                circuit: {
+                    state: updatedStatus.state,
+                    failureCount: updatedStatus.failureCount,
+                    failureThreshold: updatedStatus.failureThreshold,
+                    timeUntilReset: updatedStatus.timeUntilReset,
+                },
+            };
+        }
+        return {
+            healthy: result.success,
+            latencyMs,
+            error: result.error?.message,
+            circuit: {
+                state: updatedStatus.state,
+                failureCount: updatedStatus.failureCount,
+                failureThreshold: updatedStatus.failureThreshold,
+                timeUntilReset: updatedStatus.timeUntilReset,
+            },
+        };
+    }
+    catch (error) {
+        const latencyMs = Math.round(performance.now() - start);
+        const updatedStatus = await breaker.getStatus();
+        return {
+            healthy: false,
+            latencyMs,
+            error: error instanceof Error ? error.message : 'Unknown error',
+            circuit: {
+                state: updatedStatus.state,
+                failureCount: updatedStatus.failureCount,
+                failureThreshold: updatedStatus.failureThreshold,
+                timeUntilReset: updatedStatus.timeUntilReset,
+            },
+        };
+    }
+}
+//# sourceMappingURL=database-resilience.js.map

package/dist/common/database-resilience.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-resilience.js","sourceRoot":"","sources":["../../src/common/database-resilience.ts"],"names":[],"mappings":"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"}

package/dist/common/db-metrics.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Database Metrics Wrapper
+ *
+ * Provides instrumentation for database operations, capturing query timing,
+ * success/failure counts, and connection pool metrics.
+ */
+import type { Pool, PoolClient, QueryResult, QueryResultRow } from 'pg';
+import { type DbOperationType } from '../intent/metrics.js';
+/**
+ * Wraps a pg Pool to instrument queries with metrics
+ */
+export declare class InstrumentedPool {
+    private pool;
+    private metricsInterval;
+    constructor(pool: Pool);
+    /**
+     * Start periodic collection of pool metrics
+     */
+    startMetricsCollection(intervalMs?: number): void;
+    /**
+     * Stop periodic metrics collection
+     */
+    stopMetricsCollection(): void;
+    /**
+     * Collect current pool metrics
+     */
+    collectPoolMetrics(): void;
+    /**
+     * Execute a query with metrics instrumentation
+     */
+    query<R extends QueryResultRow = QueryResultRow>(text: string, values?: unknown[]): Promise<QueryResult<R>>;
+    /**
+     * Get an instrumented client from the pool
+     */
+    connect(): Promise<InstrumentedPoolClient>;
+    /**
+     * Get the underlying pool (for advanced usage)
+     */
+    getPool(): Pool;
+    /**
+     * End the pool connection
+     */
+    end(): Promise<void>;
+}
+/**
+ * Wraps a pg PoolClient to instrument queries with metrics
+ */
+export declare class InstrumentedPoolClient {
+    private client;
+    constructor(client: PoolClient);
+    /**
+     * Execute a query with metrics instrumentation
+     */
+    query<R extends QueryResultRow = QueryResultRow>(text: string, values?: unknown[]): Promise<QueryResult<R>>;
+    /**
+     * Release the client back to the pool
+     */
+    release(err?: Error | boolean): void;
+    /**
+     * Get the underlying client (for advanced usage)
+     */
+    getClient(): PoolClient;
+}
+/**
+ * Wrap a database query function with metrics instrumentation.
+ * Useful for instrumenting existing code without changing structure.
+ */
+export declare function withDbMetrics<T>(operation: DbOperationType, queryFn: () => Promise<T>): Promise<T>;
+/**
+ * Timer helper for measuring query duration.
+ * Useful for instrumenting Drizzle ORM queries.
+ */
+export declare class DbQueryTimer {
+    private startTime;
+    private operation;
+    constructor(operation: DbOperationType);
+    /**
+     * Record success and return the duration in seconds
+     */
+    success(): number;
+    /**
+     * Record failure
+     */
+    failure(error: unknown): void;
+}
+/**
+ * Create a timer for measuring query duration
+ */
+export declare function startDbQueryTimer(operation: DbOperationType): DbQueryTimer;
+//# sourceMappingURL=db-metrics.d.ts.map

package/dist/common/db-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-metrics.d.ts","sourceRoot":"","sources":["../../src/common/db-metrics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,IAAI,CAAC;AACxE,OAAO,EAWL,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAE9B;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,IAAI,CAAO;IACnB,OAAO,CAAC,eAAe,CAA+B;gBAE1C,IAAI,EAAE,IAAI;IAItB;;OAEG;IACH,sBAAsB,CAAC,UAAU,GAAE,MAAa,GAAG,IAAI;IAgBvD;;OAEG;IACH,qBAAqB,IAAI,IAAI;IAO7B;;OAEG;IACH,kBAAkB,IAAI,IAAI;IAY1B;;OAEG;IACG,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EACnD,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAgB1B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAKhD;;OAEG;IACH,OAAO,IAAI,IAAI;IAIf;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAI3B;AAED;;GAEG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAAa;gBAEf,MAAM,EAAE,UAAU;IAI9B;;OAEG;IACG,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EACnD,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAgB1B;;OAEG;IACH,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,IAAI;IAIpC;;OAEG;IACH,SAAS,IAAI,UAAU;CAGxB;AAqCD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,CAAC,CAcZ;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAkB;gBAEvB,SAAS,EAAE,eAAe;IAKtC;;OAEG;IACH,OAAO,IAAI,MAAM;IAMjB;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;CAI9B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,eAAe,GAAG,YAAY,CAE1E"}

package/dist/common/db-metrics.js

@@ -0,0 +1,219 @@
+/**
+ * Database Metrics Wrapper
+ *
+ * Provides instrumentation for database operations, capturing query timing,
+ * success/failure counts, and connection pool metrics.
+ */
+import { detectOperationType, recordDbQuery, recordDbQueryError, updateDbPoolMetrics, } from '../intent/metrics.js';
+/**
+ * Wraps a pg Pool to instrument queries with metrics
+ */
+export class InstrumentedPool {
+    pool;
+    metricsInterval = null;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /**
+     * Start periodic collection of pool metrics
+     */
+    startMetricsCollection(intervalMs = 5000) {
+        if (this.metricsInterval) {
+            return;
+        }
+        this.metricsInterval = setInterval(() => {
+            this.collectPoolMetrics();
+        }, intervalMs);
+        // Don't keep the process alive just for metrics collection
+        this.metricsInterval.unref();
+        // Collect immediately
+        this.collectPoolMetrics();
+    }
+    /**
+     * Stop periodic metrics collection
+     */
+    stopMetricsCollection() {
+        if (this.metricsInterval) {
+            clearInterval(this.metricsInterval);
+            this.metricsInterval = null;
+        }
+    }
+    /**
+     * Collect current pool metrics
+     */
+    collectPoolMetrics() {
+        // pg Pool exposes these properties
+        const totalCount = this.pool.totalCount;
+        const idleCount = this.pool.idleCount;
+        const waitingCount = this.pool.waitingCount;
+        // Active = total - idle
+        const activeCount = totalCount - idleCount;
+        updateDbPoolMetrics(activeCount, idleCount, waitingCount);
+    }
+    /**
+     * Execute a query with metrics instrumentation
+     */
+    async query(text, values) {
+        const operation = detectOperationType(text);
+        const startTime = performance.now();
+        try {
+            const result = await this.pool.query(text, values);
+            const durationSeconds = (performance.now() - startTime) / 1000;
+            recordDbQuery(operation, durationSeconds);
+            return result;
+        }
+        catch (error) {
+            const errorType = getErrorType(error);
+            recordDbQueryError(operation, errorType);
+            throw error;
+        }
+    }
+    /**
+     * Get an instrumented client from the pool
+     */
+    async connect() {
+        const client = await this.pool.connect();
+        return new InstrumentedPoolClient(client);
+    }
+    /**
+     * Get the underlying pool (for advanced usage)
+     */
+    getPool() {
+        return this.pool;
+    }
+    /**
+     * End the pool connection
+     */
+    async end() {
+        this.stopMetricsCollection();
+        await this.pool.end();
+    }
+}
+/**
+ * Wraps a pg PoolClient to instrument queries with metrics
+ */
+export class InstrumentedPoolClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Execute a query with metrics instrumentation
+     */
+    async query(text, values) {
+        const operation = detectOperationType(text);
+        const startTime = performance.now();
+        try {
+            const result = await this.client.query(text, values);
+            const durationSeconds = (performance.now() - startTime) / 1000;
+            recordDbQuery(operation, durationSeconds);
+            return result;
+        }
+        catch (error) {
+            const errorType = getErrorType(error);
+            recordDbQueryError(operation, errorType);
+            throw error;
+        }
+    }
+    /**
+     * Release the client back to the pool
+     */
+    release(err) {
+        this.client.release(err);
+    }
+    /**
+     * Get the underlying client (for advanced usage)
+     */
+    getClient() {
+        return this.client;
+    }
+}
+/**
+ * Extract error type from an error for metrics labeling
+ */
+function getErrorType(error) {
+    if (error instanceof Error) {
+        // PostgreSQL error codes
+        const pgError = error;
+        if (pgError.code) {
+            // Map common Postgres error codes to readable types
+            switch (pgError.code) {
+                case '23505': return 'unique_violation';
+                case '23503': return 'foreign_key_violation';
+                case '23502': return 'not_null_violation';
+                case '23514': return 'check_violation';
+                case '42P01': return 'undefined_table';
+                case '42703': return 'undefined_column';
+                case '57014': return 'query_canceled';
+                case '40001': return 'serialization_failure';
+                case '40P01': return 'deadlock_detected';
+                case '08006': return 'connection_failure';
+                case '08001': return 'connection_refused';
+                case '08004': return 'connection_rejected';
+                case '57P01': return 'admin_shutdown';
+                default: return `pg_${pgError.code}`;
+            }
+        }
+        // Connection/network errors
+        if (error.message.includes('timeout'))
+            return 'timeout';
+        if (error.message.includes('ECONNREFUSED'))
+            return 'connection_refused';
+        if (error.message.includes('ENOTFOUND'))
+            return 'host_not_found';
+        return 'unknown';
+    }
+    return 'unknown';
+}
+/**
+ * Wrap a database query function with metrics instrumentation.
+ * Useful for instrumenting existing code without changing structure.
+ */
+export function withDbMetrics(operation, queryFn) {
+    const startTime = performance.now();
+    return queryFn()
+        .then((result) => {
+        const durationSeconds = (performance.now() - startTime) / 1000;
+        recordDbQuery(operation, durationSeconds);
+        return result;
+    })
+        .catch((error) => {
+        const errorType = getErrorType(error);
+        recordDbQueryError(operation, errorType);
+        throw error;
+    });
+}
+/**
+ * Timer helper for measuring query duration.
+ * Useful for instrumenting Drizzle ORM queries.
+ */
+export class DbQueryTimer {
+    startTime;
+    operation;
+    constructor(operation) {
+        this.operation = operation;
+        this.startTime = performance.now();
+    }
+    /**
+     * Record success and return the duration in seconds
+     */
+    success() {
+        const durationSeconds = (performance.now() - this.startTime) / 1000;
+        recordDbQuery(this.operation, durationSeconds);
+        return durationSeconds;
+    }
+    /**
+     * Record failure
+     */
+    failure(error) {
+        const errorType = getErrorType(error);
+        recordDbQueryError(this.operation, errorType);
+    }
+}
+/**
+ * Create a timer for measuring query duration
+ */
+export function startDbQueryTimer(operation) {
+    return new DbQueryTimer(operation);
+}
+//# sourceMappingURL=db-metrics.js.map

package/dist/common/db-metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-metrics.js","sourceRoot":"","sources":["../../src/common/db-metrics.ts"],"names":[],"mappings":"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"}