@adalo/metrics 0.0.0-staging.1

package/src/health/healthCheckClient.js

@@ -0,0 +1,347 @@
+const {
+  createDatabasePool,
+  runHealthCheck,
+  closePool,
+} = require('./databaseChecker')
+const {
+  getRedisClientType,
+  REDIS_V4,
+  IOREDIS,
+  REDIS_V3,
+} = require('../redisUtils')
+const { HealthCheckCache } = require('./healthCheckCache')
+
+/**
+ * @param {string} name
+ * @returns {number | undefined}
+ */
+function readNumberEnv(name) {
+  const raw = process.env[name]
+  if (raw == null || raw === '') return undefined
+  const num = Number(raw)
+  return Number.isFinite(num) ? num : undefined
+}
+
+/** @type {{ checkIntervalMs: number, staleThresholdMs: number, checkTimeoutMs: number, maxDbConnectLatencyMs: number }} */
+const DEFAULT_HEALTH_CONFIG = {
+  checkIntervalMs: 30_000,
+  staleThresholdMs: 180_000,
+  checkTimeoutMs: 15_000,
+  maxDbConnectLatencyMs:
+    readNumberEnv('HEALTH_DB_MAX_CONNECT_LATENCY_MS') ?? 1000,
+}
+
+const SENSITIVE_PATTERNS = [
+  {
+    pattern:
+      /(postgres(?:ql)?|mysql|mongodb|redis|amqp):\/\/([^:]+):([^@]+)@([^:/]+)(:\d+)?\/([^\s?]+)/gi,
+    replacement: '$1://***:***@***$5/***',
+  },
+  {
+    pattern: /(\w+):\/\/([^:]+):([^@]+)@([^\s/]+)/gi,
+    replacement: '$1://***:***@***',
+  },
+  {
+    pattern:
+      /(password|passwd|pwd|secret|token|api[_-]?key|auth[_-]?token)["\s]*[:=]["\s]*([^\s,}"]+)/gi,
+    replacement: '$1=***',
+  },
+  {
+    pattern:
+      /(database|table|schema|role|user|relation|column|index)\s*["']([^"']+)["']/gi,
+    replacement: '$1 "***"',
+  },
+  {
+    pattern: /\b(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})(:\d+)?\b/g,
+    replacement: '***$2',
+  },
+  {
+    pattern: /\b(host|hostname|server)["\s]*[:=]["\s]*([^\s,}"]+)/gi,
+    replacement: '$1=***',
+  },
+]
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function maskSensitiveData(text) {
+  if (!text || typeof text !== 'string') return text
+  let masked = text
+  for (const { pattern, replacement } of SENSITIVE_PATTERNS) {
+    masked = masked.replace(pattern, replacement)
+  }
+  return masked
+}
+
+/**
+ * @typedef {{ env: string, url?: string } | { env: string, client?: any }} HealthResource
+ */
+class HealthCheckClient {
+  /**
+   * @param {Object} options
+   * @param {HealthResource[]} options.resources - Must include Redis resource with client
+   * @param {Object} [options.config]
+   * @param {string} [options.appName] - For cache key: healthcheck:${appName}
+   * @param {string} [options.cacheKey] - Redis key (overrides appName)
+   */
+  constructor(options = {}) {
+    this.healthConfig = { ...DEFAULT_HEALTH_CONFIG, ...options.config }
+    this.appName =
+      options.appName || process.env.BUILD_APP_NAME || 'unknown-app'
+
+    this.prefixLogs = `[${this.appName}] [HealthCheck]`
+
+    this._refreshPromise = null
+    /** @type {Map<string, { pool: any, type: string }>} */
+    this._databasePools = new Map()
+
+    /** @type {HealthResource[]} */
+    this._resources = options.resources || []
+
+    const redisClient = this._getRedisClientForCache()
+    if (redisClient) {
+      this._redisClientType = getRedisClientType(redisClient)
+    }
+
+    this._cache = new HealthCheckCache({
+      redisClient: redisClient || null,
+      cacheKey: options.cacheKey,
+      appName: this.appName,
+      staleThresholdMs: this.healthConfig.staleThresholdMs,
+    })
+  }
+
+  _getEnv(resource) {
+    return resource.env ?? resource.name
+  }
+
+  _getRedisClientForCache() {
+    const redisResource = this._resources.find(r => 'client' in r && r.client)
+    return redisResource?.client || null
+  }
+
+  _getPool(env, url) {
+    if (!this._databasePools.has(env)) {
+      const { pool, type } = createDatabasePool(
+        env,
+        url,
+        this.healthConfig.checkTimeoutMs
+      )
+      this._databasePools.set(env, { pool, type })
+    }
+    return this._databasePools.get(env)
+  }
+
+  async _checkDatabase(resource) {
+    const env = this._getEnv(resource)
+    const url = 'url' in resource ? resource.url : process.env[env]
+    if (!url) {
+      return { status: 'error', error: `Env ${env} not set` }
+    }
+
+    try {
+      const { pool, type } = this._getPool(env, url)
+      const timings = await runHealthCheck(pool, type)
+
+      const maxConnect = this.healthConfig.maxDbConnectLatencyMs
+      if (
+        typeof maxConnect === 'number' &&
+        Number.isFinite(maxConnect) &&
+        timings?.connectMs != null &&
+        timings.connectMs > maxConnect
+      ) {
+        return {
+          status: 'error',
+          error: `DB connect latency ${timings.connectMs}ms exceeds ${maxConnect}ms`,
+          connectMs: timings.connectMs,
+        }
+      }
+
+      return { status: 'ok', connectMs: timings.connectMs }
+    } catch (err) {
+      const timings = err?.healthCheckTimings
+      return {
+        status: 'error',
+        error: maskSensitiveData(err.message),
+        ...(timings && typeof timings === 'object'
+          ? { connectMs: timings.connectMs }
+          : {}),
+      }
+    }
+  }
+
+  async _checkRedis(resource) {
+    const { client } = resource
+    if (!client) return { status: 'ok' }
+
+    try {
+      let pong
+      if (this._redisClientType === REDIS_V3) {
+        pong = await new Promise((resolve, reject) => {
+          client.ping((err, result) => {
+            if (err) reject(err)
+            else resolve(result)
+          })
+        })
+      } else if (
+        this._redisClientType === REDIS_V4 ||
+        this._redisClientType === IOREDIS
+      ) {
+        pong = await client.ping()
+      } else {
+        return { status: 'error', error: 'Unknown Redis client type' }
+      }
+
+      return pong === 'PONG'
+        ? { status: 'ok' }
+        : { status: 'error', error: `Unexpected: ${pong}` }
+    } catch (err) {
+      return { status: 'error', error: maskSensitiveData(err.message) }
+    }
+  }
+
+  async _performHealthCheckInternal() {
+    const resources = {}
+
+    for (const resource of this._resources) {
+      const env = this._getEnv(resource)
+
+      if ('client' in resource && resource.client) {
+        resources[env] = await this._checkRedis(resource)
+      } else {
+        resources[env] = await this._checkDatabase(resource)
+      }
+    }
+
+    const sortedResources = Object.keys(resources)
+      .sort()
+      .reduce((acc, key) => {
+        acc[key] = resources[key]
+        return acc
+      }, {})
+
+    const hasError = Object.values(resources).some(r => r.status === 'error')
+    const lastCheckAt = Date.now()
+
+    return {
+      status: hasError ? 'error' : 'ok',
+      lastCheckAt,
+      resources: sortedResources,
+      isStale: false,
+      config: this.healthConfig,
+    }
+  }
+
+  _formatResult(result, cached = false) {
+    const isStale =
+      !result.lastCheckAt ||
+      Date.now() - result.lastCheckAt > this.healthConfig.staleThresholdMs
+
+    return {
+      ...result,
+      isStale,
+      status: isStale ? 'stale' : result.status,
+      ...(isStale && {
+        error:
+          'Health check data is stale, health-check worker may not be running. Resource statuses are unknown.',
+      }),
+      ...(cached && { cached: true }),
+    }
+  }
+
+  async performHealthCheck() {
+    if (this._refreshPromise) {
+      return this._refreshPromise
+    }
+
+    this._refreshPromise = this._performHealthCheckInternal()
+      .then(result => {
+        this._refreshPromise = null
+        return this._formatResult(result)
+      })
+      .catch(err => {
+        this._refreshPromise = null
+        throw err
+      })
+
+    return this._refreshPromise
+  }
+
+  async getCachedResult() {
+    try {
+      const cached = await this._cache.get()
+      if (cached) return this._formatResult(cached)
+      return null
+    } catch (err) {
+      console.error(`${this.prefixLogs} Failed to read from cache:`, err)
+      return {
+        status: 'error',
+        lastCheckAt: null,
+        resources: {},
+        isStale: true,
+        error:
+          'Redis unavailable, unable to read health status of other resources',
+        config: this.healthConfig,
+      }
+    }
+  }
+
+  async refreshCache() {
+    const result = await this._performHealthCheckInternal()
+    await this._cache.set(result)
+    return result
+  }
+
+  clearCache() {
+    this._refreshPromise = null
+  }
+
+  healthHandler() {
+    return async (req, res) => {
+      try {
+        const result = await this.getCachedResult()
+
+        if (!result) {
+          res.status(503).json({
+            status: 'error',
+            lastCheckAt: null,
+            resources: {},
+            isStale: true,
+            error:
+              'No health check data yet, health-check worker may not be running',
+            config: this.healthConfig,
+          })
+          return
+        }
+
+        const statusCode = result.status === 'ok' ? 200 : 503
+        res.status(statusCode).json(result)
+      } catch (err) {
+        console.error(`${this.prefixLogs} Health check failed:`, err)
+        res.status(503).json({
+          status: 'error',
+          lastCheckAt: null,
+          resources: {},
+          isStale: true,
+          error:
+            'Redis unavailable, unable to read health status of other resources',
+          config: this.healthConfig,
+        })
+      }
+    }
+  }
+
+  async cleanup() {
+    for (const [, { pool }] of this._databasePools) {
+      try {
+        await closePool(pool)
+      } catch (err) {
+        console.error(`${this.prefixLogs} Error closing database pool:`, err)
+      }
+    }
+    this._databasePools.clear()
+  }
+}
+
+module.exports = { HealthCheckClient, DEFAULT_HEALTH_CONFIG }

package/src/health/healthCheckUtils.js

@@ -0,0 +1,125 @@
+const { HealthCheckClient } = require('./healthCheckClient')
+
+/**
+ * @param {Object<string, string>} urls
+ * @returns {{ env: string, url: string }[]}
+ */
+function additionalDatabaseUrlsToResources(urls) {
+  if (!urls || typeof urls !== 'object') return []
+  return Object.entries(urls)
+    .filter(([, url]) => url)
+    .map(([env, url]) => ({ env, url }))
+}
+
+/**
+ * @param {Object} options
+ * @param {{ env: string } | { env: string, url?: string } | { env: string, client?: any }}[] options.resources
+ * @param {string} [options.appName] - For cache key: healthcheck:${appName}
+ * @param {string} [options.cacheKey] - Redis key (overrides appName)
+ * @param {Object} [options.config]
+ * @param {string} [options.databaseUrl]
+ * @param {string} [options.databaseName]
+ * @param {Object<string, string>} [options.additionalDatabaseUrls]
+ * @returns {HealthCheckClient}
+ */
+function createHealthCheckWorkerClient(options) {
+  const {
+    resources,
+    appName,
+    cacheKey,
+    config,
+    databaseUrl,
+    databaseName,
+    additionalDatabaseUrls,
+  } = options
+
+  let resourcesArray = Array.isArray(resources) ? resources : []
+
+  if (resourcesArray.length === 0) {
+    resourcesArray = []
+
+    if (databaseUrl) {
+      const url = databaseUrl || process.env.DATABASE_URL
+      if (url) {
+        const env = databaseName || 'DATABASE_URL'
+        resourcesArray.push({ env, url })
+      }
+    }
+
+    const clusterResources = additionalDatabaseUrlsToResources(
+      additionalDatabaseUrls || {}
+    )
+    resourcesArray.push(...clusterResources)
+  }
+
+  const redisResource = resourcesArray.find(r => 'client' in r && r.client)
+  if (!redisResource) {
+    throw new Error(
+      'resources must include Redis resource with client (e.g. { env: "REDIS_URL", client })'
+    )
+  }
+
+  return new HealthCheckClient({
+    resources: resourcesArray,
+    appName: appName || process.env.BUILD_APP_NAME || 'unknown-app',
+    cacheKey,
+    config,
+  })
+}
+
+/**
+ * @param {Object} options
+ * @param {any} options.redisClient
+ * @param {string} [options.appName] - For cache key: healthcheck:${appName}
+ * @param {string} [options.cacheKey] - Redis key (e.g. 'health:database:status')
+ * @param {Object} [options.config]
+ * @returns {HealthCheckClient}
+ */
+function createHealthCheckEndpointClient(options) {
+  const { redisClient, appName, cacheKey, config } = options
+
+  if (!redisClient) {
+    throw new Error(
+      'redisClient is required for createHealthCheckEndpointClient'
+    )
+  }
+
+  return new HealthCheckClient({
+    resources: [{ env: 'REDIS_URL', client: redisClient }],
+    appName: appName || process.env.BUILD_APP_NAME || 'unknown-app',
+    cacheKey,
+    config,
+  })
+}
+
+/**
+ * @param {Object} options
+ * @param {any} options.redisClient
+ * @param {string} [options.cacheKey] - Redis key (e.g. 'health:database:status')
+ * @param {string} [options.appName] - For cache key: healthcheck:${appName}
+ * @param {Object} [options.config]
+ * @returns {(req: any, res: any) => Promise<void>}
+ */
+function getHealthCheckStatus(options) {
+  const { redisClient, cacheKey, appName, config } = options
+
+  if (!redisClient) {
+    throw new Error('redisClient is required for getHealthCheckStatus')
+  }
+
+  const client = createHealthCheckEndpointClient({
+    redisClient,
+    cacheKey,
+    appName,
+    config,
+  })
+
+  return client.healthHandler()
+}
+
+module.exports = {
+  createHealthCheckWorkerClient,
+  createHealthCheckEndpointClient,
+  getHealthCheckStatus,
+  additionalDatabaseUrlsToResources,
+}

package/src/health/healthCheckWorker.js

@@ -0,0 +1,71 @@
+/**
+ * @param {Object} options
+ * @param {{ name: string } | { name: string, url?: string } | { name: string, client: any }}[] options.resources - Must include Redis resource with client
+ * @param {string} [options.appName]
+ * @param {number} [options.refreshIntervalMs]
+ * @param {string} [options.databaseUrl]
+ * @param {string} [options.databaseName]
+ * @param {Object<string, string>} [options.additionalDatabaseUrls]
+ */
+const { createHealthCheckWorkerClient } = require('./healthCheckUtils')
+const { DEFAULT_HEALTH_CONFIG } = require('./healthCheckClient')
+
+export function createHealthCheckWorker(options) {
+  const {
+    refreshIntervalMs = DEFAULT_HEALTH_CONFIG.checkIntervalMs,
+    ...workerClientOptions
+  } = options
+
+  const appName =
+    workerClientOptions.appName || process.env.BUILD_APP_NAME || 'unknown-app'
+  const dynoId = process.env.HOSTNAME || 'unknown-dyno'
+  const processType =
+    process.env.BUILD_DYNO_PROCESS_TYPE || 'health-check-worker'
+  const logValues = process.env.HEALTH_LOG_VALUES === 'true'
+  const prefixLogs = `[${processType}] [${appName}] [${dynoId}] [HealthCheck]`
+
+  const healthCheckClient = createHealthCheckWorkerClient(workerClientOptions)
+
+  return async function runHealthCheckWorker() {
+    console.log(`${prefixLogs} Starting health check worker...`)
+    console.log(`${prefixLogs} Refresh interval: ${refreshIntervalMs}ms`)
+
+    try {
+      await healthCheckClient.refreshCache()
+      if (logValues) {
+        console.log(`${prefixLogs} Initial health check completed`)
+      }
+    } catch (err) {
+      console.error(`${prefixLogs} Initial health check failed:`, err)
+    }
+
+    const interval = setInterval(async () => {
+      try {
+        const result = await healthCheckClient.refreshCache()
+        if (logValues) {
+          console.log(
+            `${prefixLogs} Health check refreshed at ${result.lastCheckAt}, status: ${result.status}`
+          )
+        }
+      } catch (err) {
+        console.error(`${prefixLogs} Health check refresh failed:`, err)
+      }
+    }, refreshIntervalMs)
+
+    process.on('SIGTERM', () => {
+      console.log(`${prefixLogs} Received SIGTERM, shutting down...`)
+      clearInterval(interval)
+      healthCheckClient.cleanup().finally(() => {
+        process.exit(0)
+      })
+    })
+
+    process.on('SIGINT', () => {
+      console.log(`${prefixLogs} Received SIGINT, shutting down...`)
+      clearInterval(interval)
+      healthCheckClient.cleanup().finally(() => {
+        process.exit(0)
+      })
+    })
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+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'