pi-harness-runtime 0.5.0 → 0.6.3-beta.13

package/packages/observability/src/alerts.ts

@@ -0,0 +1,355 @@
+/**
+ * Observability Package - Alert Engine
+ *
+ * Alert rule evaluation and alerting.
+ */
+
+import type { Alert, AlertAction, AlertCondition, AlertRule } from "./types.js";
+import { Logger } from "./logger.js";
+
+// ─── Alert Engine Class ─────────────────────────────────────────────────
+
+export class AlertEngine {
+	private readonly rules: Map<string, AlertRule> = new Map();
+	private readonly activeAlerts: Map<string, Alert> = new Map();
+	private readonly alertHistory: Alert[] = [];
+	private readonly logger: Logger;
+
+	constructor(logger?: Logger, _maxHistory = 1000) {
+		this.logger = logger ?? new Logger({ level: "warn" });
+	}
+
+	/**
+	 * Register an alert rule
+	 */
+	registerRule(rule: AlertRule): void {
+		this.rules.set(rule.name, { ...rule, enabled: rule.enabled ?? true });
+		this.logger.debug(`Alert rule registered: ${rule.name}`);
+	}
+
+	/**
+	 * Unregister an alert rule
+	 */
+	unregisterRule(name: string): void {
+		this.rules.delete(name);
+		this.logger.debug(`Alert rule unregistered: ${name}`);
+	}
+
+	/**
+	 * Get a rule by name
+	 */
+	getRule(name: string): AlertRule | undefined {
+		return this.rules.get(name);
+	}
+
+	/**
+	 * Enable or disable a rule
+	 */
+	setRuleEnabled(name: string, enabled: boolean): void {
+		const rule = this.rules.get(name);
+		if (rule) {
+			rule.enabled = enabled;
+		}
+	}
+
+	/**
+	 * Evaluate all rules
+	 */
+	async evaluate(metrics: Record<string, number>): Promise<Alert[]> {
+		const alerts: Alert[] = [];
+
+		for (const rule of this.rules.values()) {
+			if (!rule.enabled) continue;
+
+			const fired = this.evaluateCondition(rule.condition, metrics);
+
+			if (fired) {
+				// Check cooldown
+				const existingAlert = this.activeAlerts.get(rule.name);
+				if (existingAlert) {
+					const cooldownEnd =
+						new Date(existingAlert.triggeredAt).getTime() + rule.cooldown;
+					if (Date.now() < cooldownEnd) {
+						continue; // Still in cooldown
+					}
+				}
+
+				const alert = this.createAlert(rule);
+				alerts.push(alert);
+				this.activeAlerts.set(rule.name, alert);
+			} else {
+				// Resolve existing alert
+				const existingAlert = this.activeAlerts.get(rule.name);
+				if (existingAlert && existingAlert.fired) {
+					existingAlert.fired = false;
+					existingAlert.resolvedAt = new Date().toISOString();
+				}
+			}
+		}
+
+		// Trigger actions for new alerts
+		for (const alert of alerts) {
+			await this.triggerActions(alert);
+		}
+
+		return alerts;
+	}
+
+	/**
+	 * Evaluate a single condition
+	 */
+	private evaluateCondition(
+		condition: AlertCondition,
+		metrics: Record<string, number>,
+	): boolean {
+		switch (condition.type) {
+			case "threshold": {
+				const value = metrics[condition.metric] ?? 0;
+				switch (condition.operator) {
+					case ">":
+						return value > condition.value;
+					case "<":
+						return value < condition.value;
+					case ">=":
+						return value >= condition.value;
+					case "<=":
+						return value <= condition.value;
+					case "==":
+						return value === condition.value;
+					default:
+						return false;
+				}
+			}
+
+			case "rate": {
+				// Rate is typically calculated over a window
+				// For simplicity, we just check if the metric exists
+				const value = metrics[condition.metric] ?? 0;
+				return value > condition.threshold;
+			}
+
+			case "error_rate": {
+				// Error rate check - would need additional context
+				const value = metrics[`${condition.component}_errors_total`] ?? 0;
+				const total = metrics[`${condition.component}_total`] ?? 1;
+				const rate = total > 0 ? value / total : 0;
+				return rate > condition.threshold;
+			}
+
+			default:
+				return false;
+		}
+	}
+
+	/**
+	 * Create an alert from a rule
+	 */
+	private createAlert(rule: AlertRule): Alert {
+		return {
+			ruleName: rule.name,
+			severity: rule.severity,
+			message: this.formatAlertMessage(rule),
+			triggeredAt: new Date().toISOString(),
+			fired: true,
+		};
+	}
+
+	/**
+	 * Format alert message
+	 */
+	private formatAlertMessage(rule: AlertRule): string {
+		switch (rule.condition.type) {
+			case "threshold":
+				return `${rule.name}: ${rule.condition.metric} ${rule.condition.operator} ${rule.condition.value}`;
+			case "rate":
+				return `${rule.name}: ${rule.condition.metric} rate > ${rule.condition.threshold}`;
+			case "error_rate":
+				return `${rule.name}: ${rule.condition.component} error rate > ${rule.condition.threshold}`;
+			default:
+				return rule.name;
+		}
+	}
+
+	/**
+	 * Trigger alert actions
+	 */
+	private async triggerActions(alert: Alert): Promise<void> {
+		const rule = this.rules.get(alert.ruleName);
+		if (!rule) return;
+
+		for (const action of rule.actions) {
+			await this.executeAction(action, alert);
+		}
+	}
+
+	/**
+	 * Execute a single action
+	 */
+	private async executeAction(
+		action: AlertAction,
+		alert: Alert,
+	): Promise<void> {
+		switch (action.type) {
+			case "log":
+				this.logAlert(alert, action.level);
+				break;
+
+			case "notify":
+				await this.sendNotification(alert, action.channel, action.message);
+				break;
+
+			case "webhook":
+				await this.sendWebhook(alert, action);
+				break;
+
+			case "execute":
+				await this.executeCommand(alert, action.command);
+				break;
+		}
+	}
+
+	/**
+	 * Log an alert
+	 */
+	private logAlert(alert: Alert, level: string): void {
+		const message = `[ALERT] ${alert.severity.toUpperCase()}: ${alert.message}`;
+
+		switch (level) {
+			case "debug":
+				this.logger.debug(message);
+				break;
+			case "info":
+				this.logger.info(message);
+				break;
+			case "warn":
+				this.logger.warn(message);
+				break;
+			case "error":
+				this.logger.error(message);
+				break;
+			case "fatal":
+				this.logger.fatal(message);
+				break;
+			default:
+				this.logger.warn(message);
+		}
+	}
+
+	/**
+	 * Send a notification
+	 */
+	private async sendNotification(
+		alert: Alert,
+		channel: string,
+		message: string,
+	): Promise<void> {
+		// In a real implementation, this would send to Slack, PagerDuty, etc.
+		this.logger.info(
+			`Notification to ${channel}: ${message} - ${alert.message}`,
+		);
+	}
+
+	/**
+	 * Send a webhook
+	 */
+	private async sendWebhook(
+		alert: Alert,
+		action: { url: string; method?: string; headers?: Record<string, string> },
+	): Promise<void> {
+		try {
+			const response = (await fetch(action.url, {
+				method: action.method ?? "POST",
+				headers: {
+					"Content-Type": "application/json",
+					...action.headers,
+				},
+				body: JSON.stringify({
+					alert,
+					timestamp: new Date().toISOString(),
+				}),
+			})) as Response & { ok: boolean; status: number };
+
+			if (!response.ok) {
+				this.logger.error(`Webhook failed: ${response.status}`);
+			}
+		} catch (error) {
+			this.logger.error(
+				"Webhook error",
+				error instanceof Error ? error : new Error(String(error)),
+			);
+		}
+	}
+
+	/**
+	 * Execute a command
+	 */
+	private async executeCommand(alert: Alert, command: string): Promise<void> {
+		// In a real implementation, this would run a command
+		this.logger.info(
+			`Executing command: ${command} for alert ${alert.ruleName}`,
+		);
+	}
+
+	/**
+	 * Get active alerts
+	 */
+	getActiveAlerts(): Alert[] {
+		return Array.from(this.activeAlerts.values()).filter((a) => a.fired);
+	}
+
+	/**
+	 * Get alert history
+	 */
+	getAlertHistory(limit?: number): Alert[] {
+		const history = [...this.alertHistory].reverse();
+		if (limit) {
+			return history.slice(0, limit);
+		}
+		return history;
+	}
+
+	/**
+	 * Clear alert history
+	 */
+	clearHistory(): void {
+		this.alertHistory.length = 0;
+	}
+
+	/**
+	 * List all rules
+	 */
+	listRules(): AlertRule[] {
+		return Array.from(this.rules.values());
+	}
+
+	/**
+	 * Get rule count
+	 */
+	getRuleCount(): { total: number; enabled: number; disabled: number } {
+		let enabled = 0;
+		let disabled = 0;
+
+		for (const rule of this.rules.values()) {
+			if (rule.enabled) {
+				enabled++;
+			} else {
+				disabled++;
+			}
+		}
+
+		return {
+			total: this.rules.size,
+			enabled,
+			disabled,
+		};
+	}
+}
+
+// ─── Factory Function ────────────────────────────────────────────────────────
+
+/**
+ * Create an alert engine
+ */
+export function createAlertEngine(logger?: Logger): AlertEngine {
+	return new AlertEngine(logger);
+}

package/packages/observability/src/health.ts

@@ -0,0 +1,325 @@
+/**
+ * Observability Package - Health Monitor
+ *
+ * Health check registration and monitoring.
+ */
+
+import type {
+	HealthCheck,
+	HealthCheckRegistration,
+	HealthReport,
+	HealthResult,
+} from "./types.js";
+
+// ─── Default Configuration ─────────────────────────────────────────────────
+
+const DEFAULT_SERVICE_NAME = "harness-runtime";
+const DEFAULT_VERSION = "1.0.0";
+
+// ─── Health Monitor Class ─────────────────────────────────────────────────
+
+export class HealthMonitor {
+	private readonly checks: Map<string, HealthCheckRegistration> = new Map();
+	private readonly version: string;
+	private readonly startTime: number;
+
+	constructor(_serviceName = DEFAULT_SERVICE_NAME, version = DEFAULT_VERSION) {
+		this.version = version;
+		this.startTime = Date.now();
+	}
+
+	/**
+	 * Register a health check
+	 */
+	registerHealthCheck(name: string, check: HealthCheck, critical = true): void {
+		this.checks.set(name, {
+			name,
+			check,
+			critical,
+		});
+	}
+
+	/**
+	 * Unregister a health check
+	 */
+	unregisterHealthCheck(name: string): void {
+		this.checks.delete(name);
+	}
+
+	/**
+	 * Check a single health check
+	 */
+	async checkHealth(name: string): Promise<HealthResult> {
+		const registration = this.checks.get(name);
+		if (!registration) {
+			return {
+				status: "unhealthy",
+				message: `Health check '${name}' not found`,
+				timestamp: new Date().toISOString(),
+			};
+		}
+
+		try {
+			const timeoutPromise = new Promise<HealthResult>((_, reject) =>
+				setTimeout(() => reject(new Error("Health check timeout")), 5000),
+			);
+
+			const result = await Promise.race([registration.check(), timeoutPromise]);
+
+			return result;
+		} catch (error) {
+			return {
+				status: "unhealthy",
+				message: `Health check failed: ${error instanceof Error ? error.message : String(error)}`,
+				timestamp: new Date().toISOString(),
+			};
+		}
+	}
+
+	/**
+	 * Check all health checks
+	 */
+	async checkHealthAll(): Promise<HealthReport> {
+		const checks: Record<string, HealthResult> = {};
+		let overallStatus: "healthy" | "degraded" | "unhealthy" = "healthy";
+
+		// Run all checks in parallel
+		const results = await Promise.allSettled(
+			Array.from(this.checks.entries()).map(async ([_name, registration]) => {
+				try {
+					const timeoutPromise = new Promise<HealthResult>((_, reject) =>
+						setTimeout(() => reject(new Error("Health check timeout")), 5000),
+					);
+
+					return await Promise.race([registration.check(), timeoutPromise]);
+				} catch (error) {
+					return {
+						status: "unhealthy" as const,
+						message: `Health check failed: ${error instanceof Error ? error.message : String(error)}`,
+						timestamp: new Date().toISOString(),
+					};
+				}
+			}),
+		);
+
+		// Process results
+		for (let i = 0; i < Array.from(this.checks.entries()).length; i++) {
+			const [name] = Array.from(this.checks.entries())[i];
+			const result = results[i];
+
+			if (result.status === "fulfilled") {
+				checks[name] = result.value;
+
+				// Update overall status
+				if (result.value.status === "unhealthy") {
+					overallStatus = "unhealthy";
+				} else if (
+					result.value.status === "degraded" &&
+					overallStatus !== "unhealthy"
+				) {
+					overallStatus = "degraded";
+				}
+			} else {
+				checks[name] = {
+					status: "unhealthy",
+					message: `Health check threw: ${result.reason}`,
+					timestamp: new Date().toISOString(),
+				};
+				overallStatus = "unhealthy";
+			}
+		}
+
+		return {
+			overall: overallStatus,
+			version: this.version,
+			uptime: Date.now() - this.startTime,
+			checks,
+			timestamp: new Date().toISOString(),
+		};
+	}
+
+	/**
+	 * Check liveness probe (simple check that service is running)
+	 */
+	async checkLiveness(): Promise<HealthResult> {
+		return {
+			status: "healthy",
+			message: "Service is running",
+			timestamp: new Date().toISOString(),
+		};
+	}
+
+	/**
+	 * Check readiness probe (full health check)
+	 */
+	async checkReadiness(): Promise<HealthResult> {
+		const report = await this.checkHealthAll();
+
+		if (report.overall === "healthy") {
+			return {
+				status: "healthy",
+				message: "Service is ready",
+				timestamp: new Date().toISOString(),
+			};
+		}
+
+		if (report.overall === "degraded") {
+			return {
+				status: "degraded",
+				message: "Service is degraded",
+				details: {
+					failedChecks: Object.keys(report.checks).filter(
+						(name) => report.checks[name].status !== "healthy",
+					),
+				},
+				timestamp: new Date().toISOString(),
+			};
+		}
+
+		return {
+			status: "unhealthy",
+			message: "Service is not ready",
+			details: {
+				failedChecks: Object.keys(report.checks).filter(
+					(name) => report.checks[name].status !== "healthy",
+				),
+			},
+			timestamp: new Date().toISOString(),
+		};
+	}
+
+	/**
+	 * Get list of registered health checks
+	 */
+	listHealthChecks(): string[] {
+		return Array.from(this.checks.keys());
+	}
+
+	/**
+	 * Get health check info
+	 */
+	getHealthCheck(name: string): HealthCheckRegistration | undefined {
+		return this.checks.get(name);
+	}
+}
+
+// ─── Built-in Health Checks ────────────────────────────────────────────────
+
+/**
+ * Create a basic connectivity health check
+ */
+export function createConnectivityHealthCheck(
+	_name: string,
+	endpoint: string,
+	timeout = 5000,
+): HealthCheck {
+	return async () => {
+		try {
+			const controller = new AbortController();
+			const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+			const response = (await fetch(endpoint, {
+				method: "GET",
+				signal: controller.signal,
+			})) as Response & { ok: boolean; status: number };
+
+			clearTimeout(timeoutId);
+
+			if (!response.ok) {
+				return {
+					status: "degraded",
+					message: `Endpoint returned ${response.status}`,
+					timestamp: new Date().toISOString(),
+				};
+			}
+
+			return {
+				status: "healthy",
+				message: "Connectivity OK",
+				timestamp: new Date().toISOString(),
+			};
+		} catch (error) {
+			return {
+				status: "unhealthy",
+				message: `Connectivity check failed: ${error instanceof Error ? error.message : String(error)}`,
+				timestamp: new Date().toISOString(),
+			};
+		}
+	};
+}
+
+/**
+ * Create a memory usage health check
+ */
+export function createMemoryHealthCheck(
+	_name: string,
+	thresholdPercent = 90,
+): HealthCheck {
+	return async () => {
+		const usage = process.memoryUsage();
+		const heapUsedPercent = (usage.heapUsed / usage.heapTotal) * 100;
+
+		if (heapUsedPercent > thresholdPercent) {
+			return {
+				status: "unhealthy",
+				message: `Memory usage high: ${heapUsedPercent.toFixed(1)}%`,
+				details: {
+					heapUsed: `${(usage.heapUsed / 1024 / 1024).toFixed(2)} MB`,
+					heapTotal: `${(usage.heapTotal / 1024 / 1024).toFixed(2)} MB`,
+					heapUsedPercent,
+				},
+				timestamp: new Date().toISOString(),
+			};
+		}
+
+		if (heapUsedPercent > thresholdPercent * 0.8) {
+			return {
+				status: "degraded",
+				message: `Memory usage elevated: ${heapUsedPercent.toFixed(1)}%`,
+				details: {
+					heapUsedPercent,
+				},
+				timestamp: new Date().toISOString(),
+			};
+		}
+
+		return {
+			status: "healthy",
+			message: `Memory usage OK: ${heapUsedPercent.toFixed(1)}%`,
+			details: {
+				heapUsedPercent,
+			},
+			timestamp: new Date().toISOString(),
+		};
+	};
+}
+
+/**
+ * Create a disk space health check
+ */
+export function createDiskSpaceHealthCheck(
+	_name: string,
+	_minFreeMB = 100,
+): HealthCheck {
+	return async () => {
+		// In Node.js, we'd need to use a native module for disk space
+		// For now, return healthy
+		return {
+			status: "healthy",
+			message: "Disk space check not implemented in this environment",
+			timestamp: new Date().toISOString(),
+		};
+	};
+}
+
+// ─── Factory Function ────────────────────────────────────────────────────────
+
+/**
+ * Create a health monitor with the given service name
+ */
+export function createHealthMonitor(
+	serviceName?: string,
+	version?: string,
+): HealthMonitor {
+	return new HealthMonitor(serviceName, version);
+}