@vorionsys/security 1.0.0

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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"}

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

@@ -0,0 +1,307 @@
+/**
+ * Database Connection Pool Manager
+ *
+ * Provides advanced connection pooling capabilities for the Vorion security platform
+ * with health monitoring, automatic reconnection, and comprehensive metrics.
+ *
+ * Features:
+ * - Configurable pool size (min/max connections)
+ * - Connection lifecycle management with validation
+ * - Overflow queue with timeout for burst handling
+ * - Health checks with ping and query validation
+ * - Automatic reconnection on failure
+ * - Dead connection eviction
+ * - Slow query detection
+ * - Transaction support with auto-commit/rollback
+ * - Comprehensive Prometheus metrics
+ *
+ * @packageDocumentation
+ */
+import { Pool, PoolClient } from 'pg';
+import { VorionError, TimeoutError } from './errors.js';
+/**
+ * Configuration for the Vorion connection pool
+ */
+export interface ConnectionPoolConfig {
+    /** Database host */
+    host: string;
+    /** Database port */
+    port: number;
+    /** Database name */
+    database: string;
+    /** Database user */
+    user: string;
+    /** Database password */
+    password: string;
+    /** Minimum number of connections to maintain (default: 5) */
+    minConnections?: number;
+    /** Maximum number of connections allowed (default: 20) */
+    maxConnections?: number;
+    /** Time in ms before idle connections are closed (default: 30000) */
+    idleTimeoutMs?: number;
+    /** Time in ms to wait for a connection from the pool (default: 5000) */
+    connectionTimeoutMs?: number;
+    /** Maximum number of clients waiting for a connection (default: 100) */
+    maxWaitingClients?: number;
+    /** Whether to validate connections before returning them (default: true) */
+    validateOnBorrow?: boolean;
+    /** Interval in ms for eviction of dead connections (default: 60000) */
+    evictionRunIntervalMs?: number;
+    /** Statement timeout in ms for queries (default: 30000) */
+    statementTimeoutMs?: number;
+    /** Threshold in ms for slow query logging (default: 1000) */
+    slowQueryThresholdMs?: number;
+    /** SSL configuration for secure connections */
+    ssl?: boolean | {
+        rejectUnauthorized?: boolean;
+    };
+    /** Application name for PostgreSQL (useful for monitoring) */
+    applicationName?: string;
+}
+/**
+ * Pool statistics for monitoring
+ */
+export interface PoolStats {
+    /** Number of active (in-use) connections */
+    activeConnections: number;
+    /** Number of idle connections */
+    idleConnections: number;
+    /** Total connections in the pool */
+    totalConnections: number;
+    /** Number of clients waiting for a connection */
+    waitingClients: number;
+    /** Pool utilization percentage (0-100) */
+    utilizationPercent: number;
+    /** Maximum pool size */
+    maxConnections: number;
+    /** Minimum pool size */
+    minConnections: number;
+    /** Total connections created since pool start */
+    connectionsCreated: number;
+    /** Total connections destroyed since pool start */
+    connectionsDestroyed: number;
+    /** Total successful checkouts */
+    checkoutsTotal: number;
+    /** Total check-ins */
+    checkinsTotal: number;
+    /** Total validation failures */
+    validationFailures: number;
+    /** Total connection errors */
+    connectionErrors: number;
+    /** Pool health status */
+    healthy: boolean;
+    /** Last health check timestamp */
+    lastHealthCheck: string | null;
+    /** Eviction run count */
+    evictionRuns: number;
+    /** Connections evicted since start */
+    connectionsEvicted: number;
+}
+/**
+ * Error thrown when pool is exhausted and timeout occurs
+ */
+export declare class PoolExhaustedError extends VorionError {
+    readonly waitTimeMs: number;
+    readonly poolStats: Partial<PoolStats>;
+    code: string;
+    statusCode: number;
+    constructor(message: string, waitTimeMs: number, poolStats: Partial<PoolStats>);
+}
+/**
+ * Error thrown when connection validation fails
+ */
+export declare class ConnectionValidationError extends VorionError {
+    code: string;
+    statusCode: number;
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Error thrown when acquiring a connection times out
+ */
+export declare class ConnectionAcquireTimeoutError extends TimeoutError {
+    readonly waitTimeMs: number;
+    readonly poolStats: Partial<PoolStats>;
+    code: string;
+    constructor(message: string, waitTimeMs: number, poolStats: Partial<PoolStats>);
+}
+/**
+ * Advanced database connection pool manager with health monitoring,
+ * automatic reconnection, and comprehensive metrics.
+ *
+ * @example
+ * ```typescript
+ * const manager = ConnectionPoolManager.getInstance();
+ *
+ * // Initialize with configuration
+ * await manager.initialize({
+ *   host: 'localhost',
+ *   port: 5432,
+ *   database: 'vorion',
+ *   user: 'vorion',
+ *   password: 'secret',
+ *   minConnections: 5,
+ *   maxConnections: 20,
+ * });
+ *
+ * // Use withConnection for automatic resource management
+ * const users = await manager.withConnection(async (client) => {
+ *   const result = await client.query('SELECT * FROM users WHERE active = $1', [true]);
+ *   return result.rows;
+ * });
+ *
+ * // Use transaction for transactional operations
+ * await manager.transaction(async (client) => {
+ *   await client.query('UPDATE accounts SET balance = balance - $1 WHERE id = $2', [100, fromId]);
+ *   await client.query('UPDATE accounts SET balance = balance + $1 WHERE id = $2', [100, toId]);
+ * });
+ *
+ * // Get pool statistics
+ * const stats = manager.getStats();
+ * console.log(`Pool utilization: ${stats.utilizationPercent}%`);
+ *
+ * // Shutdown gracefully
+ * await manager.shutdown();
+ * ```
+ */
+export declare class ConnectionPoolManager {
+    private static instance;
+    private pool;
+    private config;
+    private connections;
+    private waitingQueue;
+    private evictionInterval;
+    private metricsInterval;
+    private isShuttingDown;
+    private isInitialized;
+    private stats;
+    private constructor();
+    /**
+     * Get the singleton instance of the connection pool manager
+     */
+    static getInstance(): ConnectionPoolManager;
+    /**
+     * Reset the singleton instance (primarily for testing)
+     */
+    static resetInstance(): void;
+    /**
+     * Initialize the connection pool with the given configuration
+     */
+    initialize(config?: Partial<ConnectionPoolConfig>): Promise<void>;
+    /**
+     * Warm up the pool by creating minimum number of connections
+     */
+    private warmUp;
+    /**
+     * Acquire a connection from the pool
+     */
+    acquire(): Promise<PoolClient>;
+    /**
+     * Acquire a connection with timeout handling
+     */
+    private acquireWithTimeout;
+    /**
+     * Release a connection back to the pool
+     */
+    release(client: PoolClient, destroy?: boolean): void;
+    /**
+     * Execute a callback with automatic connection management
+     */
+    withConnection<T>(callback: (client: PoolClient) => Promise<T>, operationName?: string): Promise<T>;
+    /**
+     * Execute a transaction with automatic commit/rollback
+     */
+    transaction<T>(callback: (client: PoolClient) => Promise<T>, operationName?: string): Promise<T>;
+    /**
+     * Validate a connection
+     */
+    private validateConnection;
+    /**
+     * Destroy a connection
+     */
+    private destroyConnection;
+    /**
+     * Start the eviction process for dead/idle connections
+     */
+    private startEvictionProcess;
+    /**
+     * Run eviction of dead/idle connections
+     */
+    private runEviction;
+    /**
+     * Start metrics collection interval
+     */
+    private startMetricsCollection;
+    /**
+     * Update Prometheus metrics
+     */
+    private updateMetrics;
+    /**
+     * Get pool statistics
+     */
+    getStats(): PoolStats;
+    /**
+     * Perform a health check on the pool
+     */
+    healthCheck(): Promise<{
+        healthy: boolean;
+        latencyMs: number;
+        stats: PoolStats;
+        error?: string;
+    }>;
+    /**
+     * Shutdown the pool gracefully
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
+    /**
+     * Check if the pool is initialized
+     */
+    isPoolInitialized(): boolean;
+    /**
+     * Get the underlying pg Pool (for advanced usage)
+     */
+    getUnderlyingPool(): Pool | null;
+}
+/**
+ * Get the global connection pool manager instance.
+ * The pool is automatically initialized on first access if configuration is available.
+ *
+ * @example
+ * ```typescript
+ * const pool = getPool();
+ *
+ * // Use the pool
+ * const result = await pool.withConnection(async (client) => {
+ *   return client.query('SELECT * FROM users');
+ * });
+ * ```
+ */
+export declare function getConnectionPool(): ConnectionPoolManager;
+/**
+ * Initialize the connection pool with custom configuration.
+ * Call this once at application startup.
+ *
+ * @example
+ * ```typescript
+ * await initializeConnectionPool({
+ *   minConnections: 10,
+ *   maxConnections: 50,
+ *   validateOnBorrow: true,
+ * });
+ * ```
+ */
+export declare function initializeConnectionPool(config?: Partial<ConnectionPoolConfig>): Promise<ConnectionPoolManager>;
+/**
+ * Shutdown the connection pool gracefully.
+ * Call this during application shutdown.
+ *
+ * @example
+ * ```typescript
+ * process.on('SIGTERM', async () => {
+ *   await shutdownConnectionPool();
+ *   process.exit(0);
+ * });
+ * ```
+ */
+export declare function shutdownConnectionPool(timeoutMs?: number): Promise<void>;
+export default ConnectionPoolManager;
+//# sourceMappingURL=db-pool.d.ts.map

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

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