@adalo/metrics 0.1.123 → 0.1.124

package/src/health/healthCheckCache.js

@@ -0,0 +1,237 @@
+const {
+  getRedisClientType,
+  REDIS_V4,
+  IOREDIS,
+  REDIS_V3,
+} = require('../redisUtils')
+
+/**
+ * HealthCheckCache provides a shared cache layer for health check results.
+ * It uses Redis if available for cross-process sharing, with graceful fallback
+ * to in-memory cache if Redis is not configured or unavailable.
+ */
+class HealthCheckCache {
+  /**
+   * @param {Object} options
+   * @param {any} [options.redisClient] - Redis client instance (optional)
+   * @param {string} [options.appName] - Application name for cache key
+   * @param {number} [options.cacheTtlMs=60000] - Cache TTL in milliseconds
+   */
+  constructor(options = {}) {
+    this.redisClient = options.redisClient || null
+    this.appName = options.appName || process.env.BUILD_APP_NAME || 'unknown-app'
+    this.cacheTtlMs = options.cacheTtlMs ?? 60 * 1000
+    this.cacheKey = `healthcheck:${this.appName}`
+    
+    /** In-memory fallback cache */
+    this._memoryCache = null
+    this._memoryCacheTimestamp = null
+
+    if (this.redisClient) {
+      this._redisClientType = getRedisClientType(this.redisClient)
+      this._redisAvailable = true
+    } else {
+      this._redisAvailable = false
+      console.warn(
+        `[HealthCheckCache] Redis not configured for ${this.appName}, using in-memory cache only (not shared across processes)`
+      )
+    }
+  }
+
+  /**
+   * Checks if Redis is available and working.
+   * @returns {Promise<boolean>}
+   * @private
+   */
+  async _checkRedisAvailable() {
+    if (!this.redisClient || !this._redisAvailable) {
+      return false
+    }
+
+    try {
+      let pong
+      if (this._redisClientType === REDIS_V3) {
+        pong = await new Promise((resolve, reject) => {
+          this.redisClient.ping((err, result) => {
+            if (err) reject(err)
+            else resolve(result)
+          })
+        })
+      } else if (
+        this._redisClientType === REDIS_V4 ||
+        this._redisClientType === IOREDIS
+      ) {
+        pong = await this.redisClient.ping()
+      } else {
+        return false
+      }
+      return pong === 'PONG'
+    } catch (err) {
+      // Redis not available
+      if (this._redisAvailable) {
+        console.warn(
+          `[HealthCheckCache] Redis became unavailable: ${err.message}`
+        )
+        this._redisAvailable = false
+      }
+      return false
+    }
+  }
+
+  /**
+   * Gets cached health check result from Redis (if available) or in-memory cache.
+   * Throws error if Redis is configured but read fails (so caller can return proper error format).
+   * @returns {Promise<Object | null>} Cached result or null
+   * @throws {Error} If Redis is configured but read fails
+   */
+  async get() {
+    // If Redis is configured, we MUST read from it (don't fall back to memory)
+    if (this.redisClient) {
+      try {
+        let cachedStr
+        if (this._redisClientType === REDIS_V3) {
+          cachedStr = await new Promise((resolve, reject) => {
+            this.redisClient.get(this.cacheKey, (err, result) => {
+              if (err) reject(err)
+              else resolve(result)
+            })
+          })
+        } else if (
+          this._redisClientType === REDIS_V4 ||
+          this._redisClientType === IOREDIS
+        ) {
+          cachedStr = await this.redisClient.get(this.cacheKey)
+        }
+
+        if (cachedStr) {
+          try {
+            const cached = JSON.parse(cachedStr)
+            if (cached.result && cached.timestamp) {
+              const age = Date.now() - cached.timestamp
+              if (age < this.cacheTtlMs) {
+                // Also update in-memory cache as backup
+                this._memoryCache = cached.result
+                this._memoryCacheTimestamp = cached.timestamp
+                return cached.result
+              }
+            }
+          } catch (parseErr) {
+            console.warn(
+              `[HealthCheckCache] Failed to parse Redis cache:`,
+              parseErr.message
+            )
+          }
+        }
+        // No cache in Redis - return null (worker may not have run yet)
+        return null
+      } catch (redisErr) {
+        // Redis read failed - throw error so caller can return proper error format
+        this._redisAvailable = false
+        throw new Error(`Redis cache read failed: ${redisErr.message}`)
+      }
+    }
+
+    // No Redis configured - fall back to in-memory cache
+    if (this._memoryCache && this._memoryCacheTimestamp) {
+      const age = Date.now() - this._memoryCacheTimestamp
+      if (age < this.cacheTtlMs) {
+        return this._memoryCache
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Sets cached health check result in Redis (if available) and in-memory.
+   * @param {Object} result - Health check result to cache
+   * @returns {Promise<void>}
+   */
+  async set(result) {
+    const cacheData = {
+      result,
+      timestamp: Date.now(),
+    }
+
+    // Update in-memory cache
+    this._memoryCache = result
+    this._memoryCacheTimestamp = cacheData.timestamp
+
+    // Try to update Redis if available
+    if (await this._checkRedisAvailable()) {
+      try {
+        const cacheStr = JSON.stringify(cacheData)
+        const ttlSeconds = Math.ceil(this.cacheTtlMs / 1000) + 10
+
+        if (this._redisClientType === REDIS_V3) {
+          await new Promise((resolve, reject) => {
+            this.redisClient.setex(
+              this.cacheKey,
+              ttlSeconds,
+              cacheStr,
+              (err) => {
+                if (err) reject(err)
+                else resolve()
+              }
+            )
+          })
+        } else if (
+          this._redisClientType === REDIS_V4 ||
+          this._redisClientType === IOREDIS
+        ) {
+          await this.redisClient.setex(this.cacheKey, ttlSeconds, cacheStr)
+        }
+      } catch (redisErr) {
+        // Redis write failed, but in-memory cache is updated
+        console.warn(
+          `[HealthCheckCache] Redis write failed (in-memory cache updated):`,
+          redisErr.message
+        )
+        this._redisAvailable = false
+      }
+    }
+  }
+
+  /**
+   * Clears the cache (both Redis and in-memory).
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    this._memoryCache = null
+    this._memoryCacheTimestamp = null
+
+    if (await this._checkRedisAvailable()) {
+      try {
+        if (this._redisClientType === REDIS_V3) {
+          await new Promise((resolve, reject) => {
+            this.redisClient.del(this.cacheKey, (err) => {
+              if (err) reject(err)
+              else resolve()
+            })
+          })
+        } else if (
+          this._redisClientType === REDIS_V4 ||
+          this._redisClientType === IOREDIS
+        ) {
+          await this.redisClient.del(this.cacheKey)
+        }
+      } catch (redisErr) {
+        console.warn(
+          `[HealthCheckCache] Redis clear failed:`,
+          redisErr.message
+        )
+      }
+    }
+  }
+
+  /**
+   * Checks if Redis is configured and available.
+   * @returns {boolean}
+   */
+  isRedisAvailable() {
+    return this._redisAvailable && this.redisClient !== null
+  }
+}
+
+module.exports = { HealthCheckCache }
+

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,6 +135,9 @@ class HealthCheckClient {
     /** @type {CachedHealthResult | null} */
     this._cachedResult = null
 
+    /** @type {Promise<HealthCheckResult> | null} */
+    this._refreshPromise = null
+
     /** @type {Map<string, Pool>} */
     this._databasePools = new Map()
 
@@ -145,6 +152,12 @@ class HealthCheckClient {
     if (this.redisClient) {
       this._redisClientType = getRedisClientType(this.redisClient)
     }
+
+    this._cache = new HealthCheckCache({
+      redisClient: this.redisClient,
+      appName: this.appName,
+      cacheTtlMs: this.cacheTtlMs,
+    })
   }
 
   /**
@@ -218,7 +231,7 @@ class HealthCheckClient {
     } catch (err) {
       return {
         status: 'unhealthy',
-        message: maskSensitiveData(err.message),
+        error: maskSensitiveData(err.message),
         latencyMs: Date.now() - start,
       }
     }
@@ -274,6 +287,8 @@ class HealthCheckClient {
     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) {
@@ -338,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')) {
@@ -368,8 +430,7 @@ class HealthCheckClient {
     const result = {
       status: overallStatus,
       timestamp: new Date().toISOString(),
-      cached: false,
-      components,
+      checks,
     }
 
     this._cachedResult = {
@@ -380,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
   }
 
   /**
@@ -397,28 +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) {
+      if (db.status === 'unhealthy' && (db.message || db.error)) {
         const dbName = this._mainDatabaseConfig?.name || 'main'
-        errors.push(`DB ${dbName}: ${maskSensitiveData(db.message)}`)
+        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)}`)
     }
 
@@ -431,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
@@ -451,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],
         })
       }
     }