@ebowwa/pkg-ops 0.1.9

package/src/health-server.ts

@@ -0,0 +1,280 @@
+/**
+ * Health monitoring HTTP server.
+ *
+ * Provides an HTTP endpoint for health checks on port 8914 (configurable).
+ *
+ * @example
+ * ```typescript
+ * import { HealthServer, startHealthServer } from "@ebowwa/pkg-ops/health-server";
+ *
+ * // Start health server
+ * const server = await startHealthServer(8914);
+ *
+ * // Custom health checks
+ * server.addCheck("custom", async () => ({
+ *   healthy: true,
+ *   message: "Custom check passed",
+ * }));
+ *
+ * // Stop server
+ * await server.stop();
+ * ```
+ */
+
+import { createServer, type Server as HttpServer, type IncomingMessage, type ServerResponse } from "http";
+import { getServiceManager, type ServiceStatus } from "./service-manager.js";
+import { loadConfig, type PkgOpsConfig } from "./config.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface HealthCheckResult {
+  /** Whether the check passed */
+  healthy: boolean;
+  /** Human-readable message */
+  message: string;
+  /** Additional data */
+  data?: Record<string, unknown>;
+}
+
+export interface ServiceHealth {
+  /** Service name */
+  name: string;
+  /** Whether the service is healthy */
+  healthy: boolean;
+  /** Service status */
+  status: ServiceStatus;
+  /** Last check timestamp */
+  checkedAt: string;
+}
+
+export interface SystemHealth {
+  /** Overall health status */
+  healthy: boolean;
+  /** All services health */
+  services: ServiceHealth[];
+  /** System uptime in seconds */
+  uptime: number;
+  /** Timestamp of this check */
+  timestamp: string;
+}
+
+export type HealthCheckFn = () => Promise<HealthCheckResult> | HealthCheckResult;
+
+// ---------------------------------------------------------------------------
+// Health Server Class
+// ---------------------------------------------------------------------------
+
+/**
+ * HTTP server for health monitoring.
+ */
+export class HealthServer {
+  private server: HttpServer | null = null;
+  private checks = new Map<string, HealthCheckFn>();
+  private startTime = Date.now();
+  private port: number;
+
+  constructor(port: number = 8914) {
+    this.port = port;
+  }
+
+  /**
+   * Start the health server.
+   */
+  async start(): Promise<void> {
+    if (this.server) {
+      return;
+    }
+
+    return new Promise((resolve, reject) => {
+      this.server = createServer((req, res) => this.handleRequest(req, res));
+
+      this.server.on("error", reject);
+
+      this.server.listen(this.port, () => {
+        console.log(`Health server listening on port ${this.port}`);
+        this.server?.off("error", reject);
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Stop the health server.
+   */
+  async stop(): Promise<void> {
+    if (!this.server) {
+      return;
+    }
+
+    return new Promise((resolve) => {
+      this.server?.close(() => {
+        this.server = null;
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Add a custom health check.
+   */
+  addCheck(name: string, check: HealthCheckFn): void {
+    this.checks.set(name, check);
+  }
+
+  /**
+   * Remove a health check.
+   */
+  removeCheck(name: string): void {
+    this.checks.delete(name);
+  }
+
+  /**
+   * Check health of all services or a specific service.
+   * Public method for CLI usage.
+   */
+  async checkHealth(serviceName?: string): Promise<SystemHealth | ServiceHealth | null> {
+    if (serviceName) {
+      return this.getServiceHealth(serviceName);
+    }
+    return this.getSystemHealth();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private Methods
+  // ---------------------------------------------------------------------------
+
+  private async handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const url = req.url ?? "/";
+    const method = req.method ?? "GET";
+
+    try {
+      if (method === "GET" && url === "/health") {
+        const health = await this.getSystemHealth();
+        this.sendJson(res, 200, health);
+      } else if (method === "GET" && url.startsWith("/health/")) {
+        const serviceName = url.slice(8).replace(".service", "");
+        const health = await this.getServiceHealth(serviceName);
+        this.sendJson(res, health ? 200 : 404, health ?? { error: "Service not found" });
+      } else if (method === "GET" && url === "/ready") {
+        const health = await this.getSystemHealth();
+        this.sendJson(res, health.healthy ? 200 : 503, { ready: health.healthy });
+      } else if (method === "GET" && url === "/live") {
+        this.sendJson(res, 200, { alive: true });
+      } else {
+        this.sendJson(res, 404, { error: "Not found" });
+      }
+    } catch (error) {
+      console.error("Health check error:", error);
+      this.sendJson(res, 500, { error: "Internal server error" });
+    }
+  }
+
+  private async getSystemHealth(): Promise<SystemHealth> {
+    const config = loadConfig();
+    const serviceManager = getServiceManager();
+
+    const services: ServiceHealth[] = [];
+
+    for (const [packageName, pkgConfig] of Object.entries(config.packages)) {
+      if (!pkgConfig.service) continue;
+
+      const status = await serviceManager.status(pkgConfig.service);
+      const healthy = status.active && status.subState === "running";
+
+      services.push({
+        name: pkgConfig.service,
+        healthy,
+        status,
+        checkedAt: new Date().toISOString(),
+      });
+    }
+
+    // Run custom checks
+    const customResults: Record<string, HealthCheckResult> = {};
+    for (const [name, check] of this.checks) {
+      try {
+        customResults[name] = await check();
+      } catch (error) {
+        customResults[name] = {
+          healthy: false,
+          message: error instanceof Error ? error.message : "Unknown error",
+        };
+      }
+    }
+
+    const allHealthy = services.every((s) => s.healthy) &&
+      Object.values(customResults).every((r) => r.healthy);
+
+    return {
+      healthy: allHealthy,
+      services,
+      uptime: Math.floor((Date.now() - this.startTime) / 1000),
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  private async getServiceHealth(serviceName: string): Promise<ServiceHealth | null> {
+    const serviceManager = getServiceManager();
+
+    const exists = await serviceManager.exists(serviceName);
+    if (!exists) {
+      return null;
+    }
+
+    const status = await serviceManager.status(serviceName);
+    const healthy = status.active && status.subState === "running";
+
+    return {
+      name: serviceName,
+      healthy,
+      status,
+      checkedAt: new Date().toISOString(),
+    };
+  }
+
+  private sendJson(res: ServerResponse, statusCode: number, data: unknown): void {
+    res.statusCode = statusCode;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify(data, null, 2));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Singleton Instance
+// ---------------------------------------------------------------------------
+
+let healthServer: HealthServer | null = null;
+
+/**
+ * Start the health server with config port.
+ */
+export async function startHealthServer(port?: number): Promise<HealthServer> {
+  const config = loadConfig();
+  const actualPort = port ?? config.healthPort ?? 8914;
+
+  if (!healthServer) {
+    healthServer = new HealthServer(actualPort);
+  }
+
+  await healthServer.start();
+  return healthServer;
+}
+
+/**
+ * Stop the health server.
+ */
+export async function stopHealthServer(): Promise<void> {
+  if (healthServer) {
+    await healthServer.stop();
+    healthServer = null;
+  }
+}
+
+/**
+ * Get the health server instance.
+ */
+export function getHealthServer(): HealthServer | null {
+  return healthServer;
+}