@vorionsys/security 1.0.0

package/dist/common/database-resilience.d.ts

@@ -0,0 +1,156 @@
+/**
+ * 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 { CircuitState, CircuitBreakerOpenError } from './circuit-breaker.js';
+import type { CircuitBreaker } from './circuit-breaker.js';
+export { CircuitState, CircuitBreakerOpenError };
+/**
+ * Database operation timeout in milliseconds
+ * Default: 30 seconds (configurable via config)
+ */
+export declare const DB_OPERATION_TIMEOUT_MS = 30000;
+/**
+ * Database circuit breaker service name
+ */
+export declare const DATABASE_SERVICE_NAME = "database";
+/**
+ * Get the database circuit breaker instance
+ */
+export declare function getDatabaseCircuitBreaker(): CircuitBreaker;
+/**
+ * Check if the database circuit is currently open
+ */
+export declare function isDatabaseCircuitOpen(): Promise<boolean>;
+/**
+ * Get database circuit breaker status for monitoring
+ */
+export declare function getDatabaseCircuitStatus(): Promise<{
+    name: string;
+    state: CircuitState;
+    failureCount: number;
+    failureThreshold: number;
+    resetTimeoutMs: number;
+    timeUntilReset: number | null;
+}>;
+/**
+ * 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 declare function withDatabaseCircuitBreaker<T>(fn: () => Promise<T>, options?: {
+    operationName?: string;
+    timeoutMs?: number;
+}): Promise<T>;
+/**
+ * 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 declare function withDatabaseCircuitBreakerResult<T>(fn: () => Promise<T>, options?: {
+    operationName?: string;
+    timeoutMs?: number;
+}): Promise<{
+    success: boolean;
+    result?: T;
+    error?: Error;
+    circuitOpen: boolean;
+}>;
+/**
+ * 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 declare function executeWithCircuitBreaker<T = unknown>(sql: string, params?: unknown[], options?: {
+    operationName?: string;
+    timeoutMs?: number;
+}): Promise<T[]>;
+/**
+ * Force the database circuit breaker to open state.
+ * Useful for manual intervention during maintenance or incidents.
+ */
+export declare function forceDatabaseCircuitOpen(): Promise<void>;
+/**
+ * Force the database circuit breaker to closed state.
+ * Useful for manual recovery after maintenance.
+ */
+export declare function forceDatabaseCircuitClose(): Promise<void>;
+/**
+ * Reset the database circuit breaker.
+ * Clears all state and returns to CLOSED state.
+ */
+export declare function resetDatabaseCircuit(): Promise<void>;
+/**
+ * Database health check with circuit breaker status.
+ *
+ * Returns comprehensive health information including:
+ * - Database connectivity status
+ * - Circuit breaker state
+ * - Latency metrics
+ */
+export declare function checkDatabaseHealthWithCircuit(): Promise<{
+    healthy: boolean;
+    latencyMs?: number;
+    error?: string;
+    circuit: {
+        state: CircuitState;
+        failureCount: number;
+        failureThreshold: number;
+        timeUntilReset: number | null;
+    };
+}>;
+//# sourceMappingURL=database-resilience.d.ts.map

package/dist/common/database-resilience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-resilience.d.ts","sourceRoot":"","sources":["../../src/common/database-resilience.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,YAAY,EAEZ,uBAAuB,EAGxB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAK3D,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,QAAQ,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAEhD;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,cAAc,CAO1D;AAED;;GAEG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAG9D;AAED;;GAEG;AACH,wBAAsB,wBAAwB,IAAI,OAAO,CAAC;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,YAAY,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC,CAGD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,0BAA0B,CAAC,CAAC,EAChD,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE;IACP,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC,CAAC,CAAC,CASZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,gCAAgC,CAAC,CAAC,EACtD,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE;IACP,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC,CAQD;AAED;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAAC,CAAC,GAAG,OAAO,EACzD,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,OAAO,EAAO,EACtB,OAAO,GAAE;IACP,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC,CAAC,EAAE,CAAC,CAoBd;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,IAAI,CAAC,CAI9D;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CAI/D;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAI1D;AAED;;;;;;;GAOG;AACH,wBAAsB,8BAA8B,IAAI,OAAO,CAAC;IAC9D,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QACP,KAAK,EAAE,YAAY,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;QACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,CAAC;CACH,CAAC,CA4FD"}

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