@mantiq/health 0.1.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@mantiq/health",
+  "version": "0.1.0",
+  "description": "Application health checks — database, cache, queue, filesystem, mail, and custom checks",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abdullah Khan",
+  "homepage": "https://github.com/mantiqjs/mantiq/tree/main/packages/health",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mantiqjs/mantiq.git",
+    "directory": "packages/health"
+  },
+  "bugs": {
+    "url": "https://github.com/mantiqjs/mantiq/issues"
+  },
+  "keywords": [
+    "mantiq",
+    "mantiqjs",
+    "health",
+    "healthcheck",
+    "monitoring"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun --packages=external",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "@mantiq/core": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@mantiq/database": { "optional": true },
+    "@mantiq/cache": { "optional": true },
+    "@mantiq/queue": { "optional": true },
+    "@mantiq/filesystem": { "optional": true },
+    "@mantiq/mail": { "optional": true }
+  }
+}

package/src/HealthCheck.ts

@@ -0,0 +1,69 @@
+export type HealthStatus = 'ok' | 'degraded' | 'critical'
+
+export interface CheckResult {
+  name: string
+  status: HealthStatus
+  message?: string
+  duration: number  // ms
+  meta?: Record<string, any>
+}
+
+/**
+ * Base class for health checks. Extend this and implement `run()`.
+ *
+ * @example
+ * class CustomCheck extends HealthCheck {
+ *   name = 'custom'
+ *   async run(): Promise<void> {
+ *     // throw to fail, or call this.degrade() for warnings
+ *   }
+ * }
+ */
+export abstract class HealthCheck {
+  abstract readonly name: string
+
+  private _status: HealthStatus = 'ok'
+  private _message?: string
+  private _meta: Record<string, any> = {}
+
+  /** Override to perform the actual check. Throw to fail. */
+  abstract run(): Promise<void>
+
+  /** Mark this check as degraded (warning, not critical). */
+  protected degrade(message: string): void {
+    this._status = 'degraded'
+    this._message = message
+  }
+
+  /** Attach metadata to the result (shown only in debug mode). */
+  protected meta(key: string, value: any): void {
+    this._meta[key] = value
+  }
+
+  /** @internal Execute the check and return a result. */
+  async execute(): Promise<CheckResult> {
+    this._status = 'ok'
+    this._message = undefined
+    this._meta = {}
+
+    const start = performance.now()
+    try {
+      await this.run()
+      return {
+        name: this.name,
+        status: this._status,
+        message: this._message,
+        duration: Math.round((performance.now() - start) * 100) / 100,
+        meta: Object.keys(this._meta).length > 0 ? this._meta : undefined,
+      }
+    } catch (e: any) {
+      return {
+        name: this.name,
+        status: 'critical',
+        message: e.message ?? String(e),
+        duration: Math.round((performance.now() - start) * 100) / 100,
+        meta: Object.keys(this._meta).length > 0 ? this._meta : undefined,
+      }
+    }
+  }
+}

package/src/HealthHandler.ts

@@ -0,0 +1,56 @@
+import type { HealthManager, HealthReport } from './HealthManager.ts'
+
+/**
+ * HTTP request handler for /health endpoint.
+ *
+ * - Debug mode: full report with all check details, durations, and metadata
+ * - Production: minimal response — just status and timestamp
+ *
+ * Returns 200 for ok/degraded, 503 for critical.
+ */
+export function healthHandler(manager: HealthManager, debug = false) {
+  return async (_request: Request): Promise<Response> => {
+    const report = await manager.check()
+    const status = report.status === 'critical' ? 503 : 200
+
+    if (debug) {
+      return new Response(JSON.stringify(report, null, 2), {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }
+
+    // Production: strip meta and detailed messages
+    const minimal: Record<string, any> = {
+      status: report.status,
+      timestamp: report.timestamp,
+    }
+
+    // Only include check names + status (no messages, no meta)
+    if (report.status !== 'ok') {
+      minimal.checks = report.checks
+        .filter((c) => c.status !== 'ok')
+        .map((c) => ({ name: c.name, status: c.status }))
+    }
+
+    return new Response(JSON.stringify(minimal), {
+      status,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+}
+
+/**
+ * Returns the health status as a compact string for Heartbeat headers.
+ * Format: "ok" | "degraded:database,memory" | "critical:database"
+ */
+export async function healthHeaderValue(manager: HealthManager): Promise<string> {
+  const report = manager.lastReport ?? await manager.check()
+  if (report.status === 'ok') return 'ok'
+
+  const failing = report.checks
+    .filter((c) => c.status !== 'ok')
+    .map((c) => c.name)
+
+  return `${report.status}:${failing.join(',')}`
+}

package/src/HealthManager.ts

@@ -0,0 +1,62 @@
+import type { HealthCheck, CheckResult, HealthStatus } from './HealthCheck.ts'
+
+export interface HealthReport {
+  status: HealthStatus
+  timestamp: string
+  duration: number  // total ms
+  checks: CheckResult[]
+}
+
+export class HealthManager {
+  private checks: HealthCheck[] = []
+  private _lastReport: HealthReport | null = null
+
+  /** Register a health check. */
+  register(check: HealthCheck): this {
+    this.checks.push(check)
+    return this
+  }
+
+  /** Register multiple checks at once. */
+  registerMany(checks: HealthCheck[]): this {
+    for (const check of checks) this.register(check)
+    return this
+  }
+
+  /** Run all checks and return a full report. */
+  async check(): Promise<HealthReport> {
+    const start = performance.now()
+    const results = await Promise.all(this.checks.map((c) => c.execute()))
+
+    let overall: HealthStatus = 'ok'
+    for (const r of results) {
+      if (r.status === 'critical') { overall = 'critical'; break }
+      if (r.status === 'degraded') overall = 'degraded'
+    }
+
+    this._lastReport = {
+      status: overall,
+      timestamp: new Date().toISOString(),
+      duration: Math.round((performance.now() - start) * 100) / 100,
+      checks: results,
+    }
+
+    return this._lastReport
+  }
+
+  /** Returns the last cached report (without re-running checks). */
+  get lastReport(): HealthReport | null {
+    return this._lastReport
+  }
+
+  /** Quick status check — returns 'ok', 'degraded', or 'critical'. */
+  async status(): Promise<HealthStatus> {
+    const report = await this.check()
+    return report.status
+  }
+
+  /** Returns registered check names. */
+  getCheckNames(): string[] {
+    return this.checks.map((c) => c.name)
+  }
+}

package/src/checks/AppCheck.ts

@@ -0,0 +1,36 @@
+import { HealthCheck } from '../HealthCheck.ts'
+
+/**
+ * Verifies core application components are booted and functional.
+ * Checks: config loaded, encryption key set, app instance exists.
+ */
+export class AppCheck extends HealthCheck {
+  readonly name = 'app'
+
+  constructor(private app: any) {
+    super()
+  }
+
+  override async run(): Promise<void> {
+    if (!this.app) throw new Error('Application instance is null')
+
+    // Check container is functional
+    try {
+      const name = this.app.config?.('app.name') ?? this.app.make?.('config')?.get?.('app.name')
+      this.meta('name', name ?? 'unknown')
+    } catch {
+      this.degrade('Config not accessible')
+    }
+
+    // Check environment
+    this.meta('env', process.env['APP_ENV'] ?? process.env['NODE_ENV'] ?? 'unknown')
+    this.meta('debug', process.env['APP_DEBUG'] === 'true')
+
+    // Check APP_KEY is set (critical for encryption/sessions)
+    const appKey = process.env['APP_KEY']
+    if (!appKey || appKey.length < 10) {
+      throw new Error('APP_KEY is missing or too short — run `bun mantiq key:generate`')
+    }
+    this.meta('key', 'set')
+  }
+}

package/src/checks/AuthCheck.ts

@@ -0,0 +1,29 @@
+import { HealthCheck } from '../HealthCheck.ts'
+
+/**
+ * Verifies the auth system is configured — guards and providers exist.
+ */
+export class AuthCheck extends HealthCheck {
+  readonly name = 'auth'
+
+  constructor(private auth: any) {
+    super()
+  }
+
+  override async run(): Promise<void> {
+    if (!this.auth) throw new Error('Auth instance is null')
+
+    const defaultGuard = this.auth.getDefaultGuard?.() ?? this.auth.defaultGuard ?? 'unknown'
+    this.meta('guard', typeof defaultGuard === 'string' ? defaultGuard : 'unknown')
+
+    try {
+      const guard = this.auth.guard?.() ?? this.auth.guard?.(defaultGuard)
+      if (!guard) {
+        throw new Error(`Default guard "${defaultGuard}" could not be resolved`)
+      }
+      this.meta('provider', guard.getProvider?.()?.constructor?.name ?? 'unknown')
+    } catch (e: any) {
+      throw new Error(`Auth not configured: ${e.message}`)
+    }
+  }
+}

package/src/checks/CacheCheck.ts

@@ -0,0 +1,32 @@
+import { HealthCheck } from '../HealthCheck.ts'
+
+/**
+ * Verifies the cache driver can read and write.
+ * Writes a test key, reads it back, then deletes it.
+ */
+export class CacheCheck extends HealthCheck {
+  readonly name = 'cache'
+
+  constructor(private cache: any) {
+    super()
+  }
+
+  override async run(): Promise<void> {
+    if (!this.cache) throw new Error('Cache instance is null')
+
+    const driver = this.cache.getDefaultDriver?.() ?? this.cache.driver?.() ?? 'unknown'
+    this.meta('driver', typeof driver === 'string' ? driver : 'unknown')
+
+    const key = `__health_check_${Date.now()}`
+    const value = 'ok'
+
+    await this.cache.put(key, value, 10) // 10 seconds TTL
+    const read = await this.cache.get(key)
+
+    if (read !== value) {
+      throw new Error(`Cache write/read mismatch: wrote "${value}", got "${read}"`)
+    }
+
+    await this.cache.forget(key)
+  }
+}

package/src/checks/DatabaseCheck.ts

@@ -0,0 +1,39 @@
+import { HealthCheck } from '../HealthCheck.ts'
+
+/**
+ * Verifies the database connection is alive by running a simple query.
+ *
+ * @example
+ * health.register(new DatabaseCheck(db().connection()))
+ */
+export class DatabaseCheck extends HealthCheck {
+  readonly name = 'database'
+
+  constructor(private connection: any) {
+    super()
+  }
+
+  override async run(): Promise<void> {
+    const driver = this.connection.getDriverName?.() ?? 'unknown'
+    this.meta('driver', driver)
+
+    const start = performance.now()
+
+    if (driver === 'mongodb') {
+      // MongoDB: ping the server
+      const db = typeof this.connection.native === 'function'
+        ? await this.connection.native()
+        : null
+      if (db) {
+        await db.command({ ping: 1 })
+      } else {
+        throw new Error('Cannot access native MongoDB connection')
+      }
+    } else {
+      // SQL: run a trivial query
+      await this.connection.select('SELECT 1')
+    }
+
+    this.meta('latency', `${Math.round(performance.now() - start)}ms`)
+  }
+}

package/src/checks/EnvironmentCheck.ts

@@ -0,0 +1,36 @@
+import { HealthCheck } from '../HealthCheck.ts'
+
+/**
+ * Verifies required environment variables are set.
+ *
+ * @example
+ * health.register(new EnvironmentCheck(['APP_KEY', 'DB_DATABASE']))
+ */
+export class EnvironmentCheck extends HealthCheck {
+  readonly name = 'environment'
+
+  constructor(private requiredVars: string[] = ['APP_KEY']) {
+    super()
+  }
+
+  override async run(): Promise<void> {
+    const missing: string[] = []
+    const present: string[] = []
+
+    for (const key of this.requiredVars) {
+      if (process.env[key]) {
+        present.push(key)
+      } else {
+        missing.push(key)
+      }
+    }
+
+    this.meta('checked', this.requiredVars.length)
+    this.meta('present', present.length)
+
+    if (missing.length > 0) {
+      this.meta('missing', missing)
+      throw new Error(`Missing environment variables: ${missing.join(', ')}`)
+    }
+  }
+}

package/src/checks/MailCheck.ts

@@ -0,0 +1,30 @@
+import { HealthCheck } from '../HealthCheck.ts'
+
+/**
+ * Verifies the mail driver is configured and accessible.
+ * Does NOT send an actual email — just checks the driver can be resolved.
+ */
+export class MailCheck extends HealthCheck {
+  readonly name = 'mail'
+
+  constructor(private mail: any) {
+    super()
+  }
+
+  override async run(): Promise<void> {
+    if (!this.mail) throw new Error('Mail instance is null')
+
+    const driver = this.mail.getDefaultDriver?.() ?? 'unknown'
+    this.meta('driver', typeof driver === 'string' ? driver : 'unknown')
+
+    // Try to resolve the transport — this validates config without sending
+    try {
+      const transport = this.mail.driver?.() ?? this.mail.transport?.()
+      if (!transport) {
+        this.degrade('Mail transport could not be resolved — check config')
+      }
+    } catch (e: any) {
+      throw new Error(`Mail driver not configured: ${e.message}`)
+    }
+  }
+}

package/src/checks/MemoryCheck.ts

@@ -0,0 +1,40 @@
+import { HealthCheck } from '../HealthCheck.ts'
+
+/**
+ * Checks memory usage against a threshold.
+ * Degrades if usage exceeds the warning threshold, fails if critical.
+ *
+ * @example
+ * health.register(new MemoryCheck({ warnAt: 256, criticalAt: 512 })) // MB
+ */
+export class MemoryCheck extends HealthCheck {
+  readonly name = 'memory'
+
+  private warnMB: number
+  private criticalMB: number
+
+  constructor(opts: { warnAt?: number; criticalAt?: number } = {}) {
+    super()
+    this.warnMB = opts.warnAt ?? 256
+    this.criticalMB = opts.criticalAt ?? 512
+  }
+
+  override async run(): Promise<void> {
+    const usage = process.memoryUsage()
+    const heapMB = Math.round(usage.heapUsed / 1024 / 1024 * 10) / 10
+    const rssMB = Math.round(usage.rss / 1024 / 1024 * 10) / 10
+
+    this.meta('heap', `${heapMB}MB`)
+    this.meta('rss', `${rssMB}MB`)
+    this.meta('threshold_warn', `${this.warnMB}MB`)
+    this.meta('threshold_critical', `${this.criticalMB}MB`)
+
+    if (heapMB >= this.criticalMB) {
+      throw new Error(`Heap usage ${heapMB}MB exceeds critical threshold ${this.criticalMB}MB`)
+    }
+
+    if (heapMB >= this.warnMB) {
+      this.degrade(`Heap usage ${heapMB}MB exceeds warning threshold ${this.warnMB}MB`)
+    }
+  }
+}

package/src/checks/QueueCheck.ts

@@ -0,0 +1,26 @@
+import { HealthCheck } from '../HealthCheck.ts'
+
+/**
+ * Verifies the queue driver is accessible and can report its size.
+ */
+export class QueueCheck extends HealthCheck {
+  readonly name = 'queue'
+
+  constructor(private queue: any) {
+    super()
+  }
+
+  override async run(): Promise<void> {
+    if (!this.queue) throw new Error('Queue instance is null')
+
+    const driver = this.queue.getDefaultDriver?.() ?? 'unknown'
+    this.meta('driver', typeof driver === 'string' ? driver : 'unknown')
+
+    try {
+      const size = await this.queue.size?.('default')
+      this.meta('pending', size ?? 0)
+    } catch (e: any) {
+      throw new Error(`Queue driver not accessible: ${e.message}`)
+    }
+  }
+}

package/src/checks/RouterCheck.ts

@@ -0,0 +1,41 @@
+import { HealthCheck } from '../HealthCheck.ts'
+
+/**
+ * Verifies the router has routes registered and key endpoints exist.
+ */
+export class RouterCheck extends HealthCheck {
+  readonly name = 'router'
+
+  constructor(
+    private router: any,
+    private expectedRoutes: string[] = [],
+  ) {
+    super()
+  }
+
+  override async run(): Promise<void> {
+    if (!this.router) throw new Error('Router instance is null')
+
+    const routes = this.router.getRoutes?.() ?? this.router.routes ?? []
+    const routeCount = Array.isArray(routes) ? routes.length : Object.keys(routes).length
+    this.meta('routes', routeCount)
+
+    if (routeCount === 0) {
+      throw new Error('No routes registered')
+    }
+
+    // Verify expected routes exist
+    if (this.expectedRoutes.length > 0) {
+      const registeredPaths = Array.isArray(routes)
+        ? routes.map((r: any) => r.path ?? r.uri ?? '')
+        : Object.keys(routes)
+
+      const missing = this.expectedRoutes.filter((p) => !registeredPaths.some((rp: string) => rp === p || rp.includes(p)))
+
+      if (missing.length > 0) {
+        this.meta('missing', missing)
+        this.degrade(`Missing expected routes: ${missing.join(', ')}`)
+      }
+    }
+  }
+}

package/src/checks/SchedulerCheck.ts

@@ -0,0 +1,24 @@
+import { HealthCheck } from '../HealthCheck.ts'
+
+/**
+ * Verifies scheduled tasks are registered and the scheduler is running.
+ */
+export class SchedulerCheck extends HealthCheck {
+  readonly name = 'scheduler'
+
+  constructor(private scheduler: any) {
+    super()
+  }
+
+  override async run(): Promise<void> {
+    if (!this.scheduler) throw new Error('Scheduler instance is null')
+
+    const tasks = this.scheduler.events?.() ?? this.scheduler.tasks ?? []
+    const count = Array.isArray(tasks) ? tasks.length : 0
+    this.meta('tasks', count)
+
+    if (count === 0) {
+      this.degrade('No scheduled tasks registered')
+    }
+  }
+}

package/src/checks/StorageCheck.ts

@@ -0,0 +1,39 @@
+import { HealthCheck } from '../HealthCheck.ts'
+import { existsSync, mkdirSync, writeFileSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Verifies the storage directory is writable.
+ *
+ * @example
+ * health.register(new StorageCheck('./storage'))
+ */
+export class StorageCheck extends HealthCheck {
+  readonly name = 'storage'
+
+  constructor(private storagePath: string = './storage') {
+    super()
+  }
+
+  override async run(): Promise<void> {
+    this.meta('path', this.storagePath)
+
+    if (!existsSync(this.storagePath)) {
+      try {
+        mkdirSync(this.storagePath, { recursive: true })
+      } catch {
+        throw new Error(`Storage directory does not exist and cannot be created: ${this.storagePath}`)
+      }
+    }
+
+    // Write and delete a temp file to verify write access
+    const testFile = join(this.storagePath, `.health-check-${Date.now()}`)
+    try {
+      writeFileSync(testFile, 'ok')
+      unlinkSync(testFile)
+      this.meta('writable', true)
+    } catch (e: any) {
+      throw new Error(`Storage directory is not writable: ${e.message}`)
+    }
+  }
+}

package/src/checks/UptimeCheck.ts

@@ -0,0 +1,24 @@
+import { HealthCheck } from '../HealthCheck.ts'
+
+/**
+ * Reports process uptime. Always passes.
+ */
+export class UptimeCheck extends HealthCheck {
+  readonly name = 'uptime'
+
+  override async run(): Promise<void> {
+    const seconds = Math.floor(process.uptime())
+    const hours = Math.floor(seconds / 3600)
+    const minutes = Math.floor((seconds % 3600) / 60)
+    const secs = seconds % 60
+
+    const parts: string[] = []
+    if (hours > 0) parts.push(`${hours}h`)
+    if (minutes > 0) parts.push(`${minutes}m`)
+    parts.push(`${secs}s`)
+
+    this.meta('seconds', seconds)
+    this.meta('formatted', parts.join(' '))
+    this.meta('pid', process.pid)
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+// ── Core ─────────────────────────────────────────────────────────────────────
+export { HealthCheck } from './HealthCheck.ts'
+export type { CheckResult, HealthStatus } from './HealthCheck.ts'
+export { HealthManager } from './HealthManager.ts'
+export type { HealthReport } from './HealthManager.ts'
+
+// ── Handler ──────────────────────────────────────────────────────────────────
+export { healthHandler, healthHeaderValue } from './HealthHandler.ts'
+
+// ── Infrastructure Checks ────────────────────────────────────────────────────
+export { DatabaseCheck } from './checks/DatabaseCheck.ts'
+export { StorageCheck } from './checks/StorageCheck.ts'
+export { EnvironmentCheck } from './checks/EnvironmentCheck.ts'
+export { MemoryCheck } from './checks/MemoryCheck.ts'
+export { UptimeCheck } from './checks/UptimeCheck.ts'
+
+// ── Application Checks ──────────────────────────────────────────────────────
+export { AppCheck } from './checks/AppCheck.ts'
+export { CacheCheck } from './checks/CacheCheck.ts'
+export { QueueCheck } from './checks/QueueCheck.ts'
+export { RouterCheck } from './checks/RouterCheck.ts'
+export { MailCheck } from './checks/MailCheck.ts'
+export { AuthCheck } from './checks/AuthCheck.ts'
+export { SchedulerCheck } from './checks/SchedulerCheck.ts'