@adalo/metrics 0.1.122 → 0.1.124

package/src/{healthCheckClient.js → health/healthCheckClient.js}

@@ -4,7 +4,8 @@ const {
   REDIS_V4,
   IOREDIS,
   REDIS_V3,
-} = require('./redisUtils')
+} = require('../redisUtils')
+const { HealthCheckCache } = require('./healthCheckCache')
 
 const HEALTH_CHECK_CACHE_TTL_MS = 60 * 1000
 
@@ -68,7 +69,8 @@ function maskSensitiveData(text) {
 /**
  * @typedef {Object} ComponentHealth
  * @property {HealthStatus} status - Component health status
- * @property {string} [message] - Optional status message
+ * @property {string} [error] - Error message if status is unhealthy
+ * @property {string} [message] - Optional status message (deprecated, use error)
  * @property {number} [latencyMs] - Connection latency in milliseconds
  */
 
@@ -82,8 +84,8 @@ function maskSensitiveData(text) {
  * @typedef {Object} HealthCheckResult
  * @property {HealthStatus} status - Overall health status
  * @property {string} timestamp - ISO timestamp of the check
- * @property {boolean} cached - Whether this result is from cache
- * @property {Object<string, ComponentHealth | DatabaseClusterHealth>} components - Individual component health
+ * @property {Object<string, ComponentHealth | DatabaseClusterHealth>} checks - Individual service health checks
+ * @property {string[]} [errors] - Top-level error messages (not related to specific services)
  */
 
 /**
@@ -116,12 +118,14 @@ class HealthCheckClient {
    * @param {string} [options.databaseUrl] - Main PostgreSQL connection URL
    * @param {string} [options.databaseName='main'] - Name for the main database
    * @param {Object<string, string>} [options.additionalDatabaseUrls] - Additional DB clusters (name -> URL)
-   * @param {any} [options.redisClient] - Redis client instance (ioredis or node-redis)
+   * @param {any} [options.redisClient] - Redis client instance (ioredis or node-redis) - used for cache
+   * @param {boolean} [options.includeRedisCheck=false] - Include Redis health check in results (for backend)
    * @param {number} [options.cacheTtlMs=60000] - Cache TTL in milliseconds (default: 60s)
    * @param {string} [options.appName] - Application name for logging
    */
   constructor(options = {}) {
     this.redisClient = options.redisClient || null
+    this.includeRedisCheck = options.includeRedisCheck || false
     this.cacheTtlMs = options.cacheTtlMs ?? HEALTH_CHECK_CACHE_TTL_MS
     this.appName =
       options.appName || process.env.BUILD_APP_NAME || 'unknown-app'
@@ -131,17 +135,29 @@ class HealthCheckClient {
     /** @type {CachedHealthResult | null} */
     this._cachedResult = null
 
+    /** @type {Promise<HealthCheckResult> | null} */
+    this._refreshPromise = null
+
     /** @type {Map<string, Pool>} */
     this._databasePools = new Map()
 
+    /** @type {DatabaseConfig | null} */
+    this._mainDatabaseConfig = null
+
     /** @type {DatabaseConfig[]} */
-    this._databaseConfigs = []
+    this._clusterConfigs = []
 
     this._initDatabases(options)
 
     if (this.redisClient) {
       this._redisClientType = getRedisClientType(this.redisClient)
     }
+
+    this._cache = new HealthCheckCache({
+      redisClient: this.redisClient,
+      appName: this.appName,
+      cacheTtlMs: this.cacheTtlMs,
+    })
   }
 
   /**
@@ -151,16 +167,16 @@ class HealthCheckClient {
    */
   _initDatabases(options) {
     const mainUrl = options.databaseUrl || process.env.DATABASE_URL || ''
-    const mainName = options.databaseName || 'main'
+    const mainName = options.databaseName || `${this.appName}_db`
 
     if (mainUrl) {
-      this._databaseConfigs.push({ name: mainName, url: mainUrl })
+      this._mainDatabaseConfig = { name: mainName, url: mainUrl }
     }
 
     const additionalUrls = options.additionalDatabaseUrls || {}
     for (const [name, url] of Object.entries(additionalUrls)) {
       if (url) {
-        this._databaseConfigs.push({ name, url })
+        this._clusterConfigs.push({ name, url })
       }
     }
   }
@@ -215,43 +231,71 @@ class HealthCheckClient {
     } catch (err) {
       return {
         status: 'unhealthy',
-        message: maskSensitiveData(err.message),
+        error: maskSensitiveData(err.message),
         latencyMs: Date.now() - start,
       }
     }
   }
 
   /**
-   * Tests all PostgreSQL database clusters in parallel.
-   * @returns {Promise<DatabaseClusterHealth | null>}
+   * Tests all PostgreSQL databases (main + clusters) in parallel.
+   * @returns {Promise<Object | null>} Database health with optional clusters
    * @private
    */
   async _checkAllDatabases() {
-    if (this._databaseConfigs.length === 0) {
+    if (!this._mainDatabaseConfig && this._clusterConfigs.length === 0) {
       return null
     }
 
-    const results = await Promise.all(
-      this._databaseConfigs.map(async config => ({
-        name: config.name,
-        health: await this._checkSingleDatabase(config),
-      }))
-    )
+    // Check main database
+    let mainHealth = null
+    if (this._mainDatabaseConfig) {
+      mainHealth = await this._checkSingleDatabase(this._mainDatabaseConfig)
+    }
+
+    // Check clusters in parallel
+    let clusters = null
+    if (this._clusterConfigs.length > 0) {
+      const clusterResults = await Promise.all(
+        this._clusterConfigs.map(async config => ({
+          name: config.name,
+          health: await this._checkSingleDatabase(config),
+        }))
+      )
+
+      clusters = {}
+      for (const { name, health } of clusterResults) {
+        clusters[name] = health
+      }
+    }
 
-    const clusters = {}
-    for (const { name, health } of results) {
-      clusters[name] = health
+    // Calculate overall status
+    const allStatuses = []
+    if (mainHealth) allStatuses.push(mainHealth.status)
+    if (clusters) {
+      allStatuses.push(...Object.values(clusters).map(c => c.status))
     }
 
-    const statuses = Object.values(clusters).map(c => c.status)
     let overallStatus = 'healthy'
-    if (statuses.some(s => s === 'unhealthy')) {
+    if (allStatuses.some(s => s === 'unhealthy')) {
       overallStatus = 'unhealthy'
-    } else if (statuses.some(s => s === 'degraded')) {
+    } else if (allStatuses.some(s => s === 'degraded')) {
       overallStatus = 'degraded'
     }
 
-    return { status: overallStatus, clusters }
+    // Build result
+    const result = { status: overallStatus }
+    if (mainHealth) {
+      result.latencyMs = mainHealth.latencyMs
+      if (mainHealth.error) result.error = mainHealth.error
+      // Keep message for backward compatibility
+      if (mainHealth.message) result.message = mainHealth.message
+    }
+    if (clusters) {
+      result.clusters = clusters
+    }
+
+    return result
   }
 
   /**
@@ -309,24 +353,71 @@ class HealthCheckClient {
   /**
    * Performs a full health check on all configured components.
    * Results are cached for the configured TTL to prevent excessive load.
+   * Uses a mutex pattern to prevent concurrent health checks when cache expires.
+   * If cache is expired but a refresh is in progress, returns stale cache (if available).
    *
    * @returns {Promise<HealthCheckResult>}
    */
   async performHealthCheck() {
+    // If cache is valid, return immediately
     if (this._isCacheValid()) {
       return { ...this._cachedResult.result, cached: true }
     }
 
-    const [dbHealth, redisHealth] = await Promise.all([
-      this._checkAllDatabases(),
-      this._checkRedis(),
-    ])
+    // If a refresh is already in progress, return stale cache (if available) or wait for refresh
+    if (this._refreshPromise) {
+      // Return stale cache immediately if available, otherwise wait for refresh
+      if (this._cachedResult) {
+        return { ...this._cachedResult.result, cached: true }
+      }
+      // Wait for the in-progress refresh
+      return this._refreshPromise
+    }
+
+    // Start a new refresh
+    this._refreshPromise = this._performHealthCheckInternal()
+      .then(result => {
+        this._refreshPromise = null
+        return result
+      })
+      .catch(err => {
+        this._refreshPromise = null
+        throw err
+      })
+
+    // Return stale cache if available while refresh is happening, otherwise wait
+    if (this._cachedResult) {
+      // Return stale cache immediately, refresh will happen in background
+      return { ...this._cachedResult.result, cached: true }
+    }
 
-    const components = {}
-    if (dbHealth) components.database = dbHealth
-    if (this.redisClient) components.redis = redisHealth
+    // No stale cache available, wait for refresh
+    return this._refreshPromise
+  }
 
-    const statuses = Object.values(components).map(c => c.status)
+  /**
+   * Internal method that actually performs the health check.
+   * This is separated to allow the mutex pattern in performHealthCheck.
+   * Only checks database - Redis is used only for cache, not health check.
+   *
+   * @returns {Promise<HealthCheckResult>}
+   * @private
+   */
+  async _performHealthCheckInternal() {
+    // Check database
+    const dbHealth = await this._checkAllDatabases()
+
+    // Optionally check Redis (for backend)
+    let redisHealth = null
+    if (this.includeRedisCheck && this.redisClient) {
+      redisHealth = await this._checkRedis()
+    }
+
+    const checks = {}
+    if (dbHealth) checks.database = dbHealth
+    if (redisHealth) checks.redis = redisHealth
+
+    const statuses = Object.values(checks).map(c => c.status)
     let overallStatus = 'healthy'
 
     if (statuses.some(s => s === 'unhealthy')) {
@@ -339,8 +430,7 @@ class HealthCheckClient {
     const result = {
       status: overallStatus,
       timestamp: new Date().toISOString(),
-      cached: false,
-      components,
+      checks,
     }
 
     this._cachedResult = {
@@ -351,11 +441,59 @@ class HealthCheckClient {
     return result
   }
 
+  /**
+   * Gets cached result from shared cache (Redis if available, otherwise in-memory).
+   * Returns null if no cache is available. This is used by endpoints to read-only access.
+   * If Redis fails, returns error result with proper format.
+   *
+   * @returns {Promise<HealthCheckResult | null>} Cached result, error result if Redis fails, or null if not available
+   */
+  async getCachedResult() {
+    try {
+      const cached = await this._cache.get()
+      if (cached) {
+        return cached
+      }
+      // No cache available - worker may not have run yet
+      return null
+    } catch (err) {
+      // Redis read failed - return error result with proper format
+      console.error(`${this.prefixLogs} Failed to read from cache:`, err)
+      const errorMessage = maskSensitiveData(err.message || 'Cache read failed')
+      return {
+        status: 'unhealthy',
+        timestamp: new Date().toISOString(),
+        checks: {
+          redis: {
+            status: 'unhealthy',
+            error: errorMessage,
+          },
+        },
+        errors: [errorMessage],
+      }
+    }
+  }
+
+  /**
+   * Forces a refresh of the health check cache.
+   * This is used by background workers to periodically update the cache.
+   * Updates shared cache (Redis if available, otherwise in-memory).
+   *
+   * @returns {Promise<HealthCheckResult>}
+   */
+  async refreshCache() {
+    const result = await this._performHealthCheckInternal()
+    await this._cache.set(result)
+
+    return result
+  }
+
   /**
    * Clears the cached health check result, forcing the next check to be fresh.
    */
   clearCache() {
     this._cachedResult = null
+    this._refreshPromise = null
   }
 
   /**
@@ -368,20 +506,29 @@ class HealthCheckClient {
   _getErrorMessages(result) {
     const errors = []
 
-    if (result.components.database) {
-      const db = result.components.database
+    if (result.checks.database) {
+      const db = result.checks.database
+
+      // Check main database status
+      if (db.status === 'unhealthy' && (db.message || db.error)) {
+        const dbName = this._mainDatabaseConfig?.name || 'main'
+        const errorMsg = db.error || db.message
+        errors.push(`DB ${dbName}: ${maskSensitiveData(errorMsg)}`)
+      }
+
+      // Check clusters
       if (db.clusters) {
         for (const [name, health] of Object.entries(db.clusters)) {
           if (health.status === 'unhealthy') {
-            const message = health.message || 'connection failed'
+            const message = health.error || health.message || 'connection failed'
             errors.push(`DB ${name}: ${maskSensitiveData(message)}`)
           }
         }
       }
     }
 
-    if (result.components.redis && result.components.redis.status === 'unhealthy') {
-      const message = result.components.redis.message || 'connection failed'
+    if (result.checks.redis && result.checks.redis.status === 'unhealthy') {
+      const message = result.checks.redis.error || result.checks.redis.message || 'connection failed'
       errors.push(`Redis: ${maskSensitiveData(message)}`)
     }
 
@@ -394,17 +541,41 @@ class HealthCheckClient {
    * Response includes errors array when status is not healthy.
    * All sensitive data (passwords, connection strings, etc.) is masked.
    *
+   * This handler only reads from cache and never triggers database queries.
+   * Use a background worker to periodically refresh the cache.
+   *
    * @returns {(req: any, res: any) => Promise<void>} Express request handler
    */
   healthHandler() {
     return async (req, res) => {
       try {
-        const result = await this.performHealthCheck()
+        // Only read from cache, never trigger DB queries
+        const result = await this.getCachedResult()
+
+        if (!result) {
+          // No cache available - return unhealthy status with proper format
+          const errorMsg = 'Health check cache not available. Worker may not be running.'
+          res.status(503).json({
+            status: 'unhealthy',
+            timestamp: new Date().toISOString(),
+            checks: {
+              redis: {
+                status: 'unhealthy',
+                error: errorMsg,
+              },
+            },
+            errors: [errorMsg],
+          })
+          return
+        }
+
         const statusCode = result.status === 'unhealthy' ? 503 : 200
-        
-        // Build response with errors if not healthy
+
+        // Build response - errors are already in result if present
         const response = { ...result }
-        if (result.status !== 'healthy') {
+        
+        // Add top-level errors array if not healthy and errors not already present
+        if (result.status !== 'healthy' && !result.errors) {
           const errors = this._getErrorMessages(result)
           if (errors.length > 0) {
             response.errors = errors
@@ -414,11 +585,17 @@ class HealthCheckClient {
         res.status(statusCode).json(response)
       } catch (err) {
         console.error(`${this.prefixLogs} Health check failed:`, err)
+        const errorMsg = maskSensitiveData(err.message)
         res.status(503).json({
           status: 'unhealthy',
           timestamp: new Date().toISOString(),
-          cached: false,
-          errors: [maskSensitiveData(err.message)],
+          checks: {
+            redis: {
+              status: 'unhealthy',
+              error: errorMsg,
+            },
+          },
+          errors: [errorMsg],
         })
       }
     }
@@ -428,9 +605,9 @@ class HealthCheckClient {
    * Register health check endpoint on an Express app.
    *
    * @param {import('express').Application} app - Express application
-   * @param {string} [path='/health'] - Path for the health endpoint
+   * @param {string} [path='/health-status'] - Path for the health endpoint
    */
-  registerHealthEndpoint(app, path = '/health') {
+  registerHealthEndpoint(app, path = '/health-status') {
     app.get(path, this.healthHandler())
     console.info(`${this.prefixLogs} Registered health endpoint at ${path}`)
   }

package/src/health/healthCheckUtils.js

@@ -0,0 +1,143 @@
+const redis = require('redis')
+const { getRedisClientType, REDIS_V3, REDIS_V4 } = require('../redisUtils')
+
+/**
+ * Creates a Redis client for health check cache with a specific client name.
+ * This allows the cache to be shared across worker and web processes.
+ *
+ * @param {Object} options
+ * @param {string} [options.redisUrl] - Redis URL (defaults to process.env.REDIS_URL)
+ * @param {string} [options.appName] - Application name for client name
+ * @param {string} [options.clientName='healthcheck'] - Client name suffix
+ * @returns {any | null} Redis client instance or null if REDIS_URL not available
+ */
+function createHealthCheckRedisClient(options = {}) {
+  const redisUrl = options.redisUrl || process.env.REDIS_URL
+  const appName = options.appName || process.env.METRICS_APP_NAME || process.env.BUILD_APP_NAME || 'unknown-app'
+  const clientName = options.clientName || 'healthcheck'
+
+  if (!redisUrl) {
+    console.warn(`[HealthCheck] REDIS_URL not configured for ${appName}, cache will be in-memory only (not shared across processes)`)
+    return null
+  }
+
+  try {
+    const client = redis.createClient({
+      url: redisUrl,
+      retry_strategy: retryOptions => {
+        if (retryOptions.attempt > 3) {
+          console.warn(`[HealthCheck] Redis client connection failed after max retries for ${appName}`)
+          return undefined
+        }
+        return 2000
+      },
+    })
+
+    // Set client name for identification
+    if (process.env.NODE_ENV !== 'test') {
+      client.on('connect', () => {
+        const fullClientName = `${appName}:${clientName}`
+        client.send_command(
+          'CLIENT',
+          ['SETNAME', fullClientName],
+          err => {
+            if (err) {
+              console.error(`[HealthCheck] Failed to set client name for ${fullClientName}:`, err)
+            } else {
+              console.log(`[HealthCheck] Connected to Redis for pid:${process.pid} (${fullClientName})`)
+            }
+          }
+        )
+      })
+    }
+
+    client.on('error', err => {
+      console.warn(`[HealthCheck] Redis client error for ${appName}:`, err.message)
+    })
+
+    return client
+  } catch (err) {
+    console.warn(`[HealthCheck] Failed to create Redis client for ${appName}:`, err.message)
+    return null
+  }
+}
+
+/**
+ * Creates a health check client for worker process.
+ * Worker needs database config to perform health checks and store results in Redis.
+ *
+ * @param {Object} options
+ * @param {string} options.databaseUrl - Main database URL
+ * @param {string} options.databaseName - Database name
+ * @param {string} [options.appName] - Application name (defaults to BUILD_APP_NAME)
+ * @param {Object<string, string>} [options.additionalDatabaseUrls] - Additional database clusters (for database service)
+ * @param {string} [options.redisUrl] - Redis URL (defaults to process.env.REDIS_URL)
+ * @param {number} [options.cacheTtlMs=60000] - Cache TTL in milliseconds
+ * @returns {HealthCheckClient} Configured health check client instance for worker
+ */
+function createHealthCheckWorkerClient(options) {
+  const { HealthCheckClient } = require('./healthCheckClient')
+  const {
+    databaseUrl,
+    databaseName,
+    appName,
+    additionalDatabaseUrls,
+    redisUrl,
+    includeRedisCheck = false,
+    cacheTtlMs = 60000,
+  } = options
+
+  const redisClient = createHealthCheckRedisClient({
+    redisUrl,
+    appName,
+    clientName: 'healthcheck-worker',
+  })
+
+  const clientOptions = {
+    databaseUrl,
+    databaseName,
+    appName: appName || process.env.BUILD_APP_NAME || 'unknown-app',
+    redisClient,
+    includeRedisCheck,
+    cacheTtlMs,
+  }
+
+  if (additionalDatabaseUrls) {
+    clientOptions.additionalDatabaseUrls = additionalDatabaseUrls
+  }
+
+  return new HealthCheckClient(clientOptions)
+}
+
+/**
+ * Creates a health check client for endpoint handlers.
+ * Endpoints only read from cache, so they only need Redis client (no database config).
+ *
+ * @param {Object} options
+ * @param {any} options.redisClient - Existing Redis client instance (from system) - REQUIRED
+ * @param {boolean} [options.includeRedisCheck=false] - Include Redis health check in response (for backend)
+ * @param {number} [options.cacheTtlMs=60000] - Cache TTL in milliseconds
+ * @returns {HealthCheckClient} Configured health check client instance for endpoints
+ */
+function createHealthCheckEndpointClient(options) {
+  const { HealthCheckClient } = require('./healthCheckClient')
+  const { redisClient, includeRedisCheck = false, cacheTtlMs = 60000 } = options
+
+  if (!redisClient) {
+    throw new Error('redisClient is required for createHealthCheckEndpointClient')
+  }
+
+  return new HealthCheckClient({
+    appName: process.env.BUILD_APP_NAME || 'unknown-app',
+    redisClient,
+    cacheTtlMs,
+    includeRedisCheck,
+  })
+}
+
+module.exports = {
+  createHealthCheckRedisClient,
+  createHealthCheckWorkerClient,
+  createHealthCheckEndpointClient,
+}
+

package/src/health/healthCheckWorker.js

@@ -0,0 +1,61 @@
+/**
+ * Shared health check worker utility.
+ * This runs as a separate process and periodically refreshes the health check cache,
+ * preventing HTTP requests from triggering database queries.
+ * Creates its own Redis connection and health check client internally.
+ *
+ * @param {Object} options
+ * @param {string} options.databaseUrl - Main database URL
+ * @param {string} options.databaseName - Database name
+ * @param {string} [options.appName] - Application name (defaults to BUILD_APP_NAME)
+ * @param {Object<string, string>} [options.additionalDatabaseUrls] - Additional database clusters (for database service)
+ * @param {string} [options.redisUrl] - Redis URL (defaults to process.env.REDIS_URL)
+ * @param {number} [options.refreshIntervalMs=60000] - Refresh interval in milliseconds (default: 1 minute)
+ * @param {number} [options.cacheTtlMs=60000] - Cache TTL in milliseconds
+ */
+const { createHealthCheckWorkerClient } = require('./healthCheckUtils')
+
+export function createHealthCheckWorker(options) {
+  const { refreshIntervalMs = 60000, ...workerClientOptions } = options
+
+  const healthCheckClient = createHealthCheckWorkerClient(workerClientOptions)
+
+  return async function runHealthCheckWorker() {
+    console.log('[HealthCheckWorker] Starting health check worker...')
+    console.log(`[HealthCheckWorker] Refresh interval: ${refreshIntervalMs}ms`)
+
+    try {
+      await healthCheckClient.refreshCache()
+      console.log('[HealthCheckWorker] Initial health check completed')
+    } catch (err) {
+      console.error('[HealthCheckWorker] Initial health check failed:', err)
+    }
+
+    const interval = setInterval(async () => {
+      try {
+        const result = await healthCheckClient.refreshCache()
+        console.log(
+          `[HealthCheckWorker] Health check refreshed at ${result.timestamp}, status: ${result.status}`
+        )
+      } catch (err) {
+        console.error('[HealthCheckWorker] Health check refresh failed:', err)
+      }
+    }, refreshIntervalMs)
+
+    process.on('SIGTERM', () => {
+      console.log('[HealthCheckWorker] Received SIGTERM, shutting down...')
+      clearInterval(interval)
+      healthCheckClient.cleanup().finally(() => {
+        process.exit(0)
+      })
+    })
+
+    process.on('SIGINT', () => {
+      console.log('[HealthCheckWorker] Received SIGINT, shutting down...')
+      clearInterval(interval)
+      healthCheckClient.cleanup().finally(() => {
+        process.exit(0)
+      })
+    })
+  }
+}

package/src/index.ts

@@ -1,7 +1,9 @@
-export * from './baseMetricsClient'
-export * from './metricsClient'
-export * from './metricsRedisClient'
-export * from './metricsQueueRedisClient'
-export * from './metricsDatabaseClient'
-export * from './healthCheckClient'
+export * from './metrics/baseMetricsClient'
+export * from './metrics/metricsClient'
+export * from './metrics/metricsRedisClient'
+export * from './metrics/metricsQueueRedisClient'
+export * from './metrics/metricsDatabaseClient'
+export * from './health/healthCheckClient'
+export * from './health/healthCheckUtils'
+export * from './health/healthCheckWorker'
 export * from './redisUtils'

package/src/{metricsQueueRedisClient.js → metrics/metricsQueueRedisClient.js}

@@ -1,6 +1,6 @@
 const Queue = require('bee-queue')
-const { RedisMetricsClient } = require('.')
-const { IOREDIS } = require('./redisUtils')
+const { RedisMetricsClient } = require('./metricsRedisClient')
+const { IOREDIS } = require('../redisUtils')
 
 /**
  * QueueRedisMetricsClient extends RedisMetricsClient to collect

package/src/{metricsRedisClient.js → metrics/metricsRedisClient.js}

@@ -4,7 +4,7 @@ const {
   REDIS_V4,
   IOREDIS,
   REDIS_V3,
-} = require('./redisUtils')
+} = require('../redisUtils')
 
 const redisConnectionStableFields = ['name', 'flags', 'cmd']
 const redisConnectionFields = ['name', 'flags', 'tot-mem', 'cmd']