@objectstack/core 0.9.1 → 1.0.0

package/dist/health-monitor.js

@@ -0,0 +1,269 @@
+/**
+ * Plugin Health Monitor
+ *
+ * Monitors plugin health status and performs automatic recovery actions.
+ * Implements the advanced lifecycle health monitoring protocol.
+ */
+export class PluginHealthMonitor {
+    constructor(logger) {
+        this.healthChecks = new Map();
+        this.healthStatus = new Map();
+        this.healthReports = new Map();
+        this.checkIntervals = new Map();
+        this.failureCounters = new Map();
+        this.successCounters = new Map();
+        this.restartAttempts = new Map();
+        this.logger = logger.child({ component: 'HealthMonitor' });
+    }
+    /**
+     * Register a plugin for health monitoring
+     */
+    registerPlugin(pluginName, config) {
+        this.healthChecks.set(pluginName, config);
+        this.healthStatus.set(pluginName, 'unknown');
+        this.failureCounters.set(pluginName, 0);
+        this.successCounters.set(pluginName, 0);
+        this.restartAttempts.set(pluginName, 0);
+        this.logger.info('Plugin registered for health monitoring', {
+            plugin: pluginName,
+            interval: config.interval
+        });
+    }
+    /**
+     * Start monitoring a plugin
+     */
+    startMonitoring(pluginName, plugin) {
+        const config = this.healthChecks.get(pluginName);
+        if (!config) {
+            this.logger.warn('Cannot start monitoring - plugin not registered', { plugin: pluginName });
+            return;
+        }
+        // Clear any existing interval
+        this.stopMonitoring(pluginName);
+        // Set up periodic health checks
+        const interval = setInterval(() => {
+            this.performHealthCheck(pluginName, plugin, config).catch(error => {
+                this.logger.error('Health check failed with error', {
+                    plugin: pluginName,
+                    error
+                });
+            });
+        }, config.interval);
+        this.checkIntervals.set(pluginName, interval);
+        this.logger.info('Health monitoring started', { plugin: pluginName });
+        // Perform initial health check
+        this.performHealthCheck(pluginName, plugin, config).catch(error => {
+            this.logger.error('Initial health check failed', {
+                plugin: pluginName,
+                error
+            });
+        });
+    }
+    /**
+     * Stop monitoring a plugin
+     */
+    stopMonitoring(pluginName) {
+        const interval = this.checkIntervals.get(pluginName);
+        if (interval) {
+            clearInterval(interval);
+            this.checkIntervals.delete(pluginName);
+            this.logger.info('Health monitoring stopped', { plugin: pluginName });
+        }
+    }
+    /**
+     * Perform a health check on a plugin
+     */
+    async performHealthCheck(pluginName, plugin, config) {
+        const startTime = Date.now();
+        let status = 'healthy';
+        let message;
+        const checks = [];
+        try {
+            // Check if plugin has a custom health check method
+            if (config.checkMethod && typeof plugin[config.checkMethod] === 'function') {
+                const checkResult = await Promise.race([
+                    plugin[config.checkMethod](),
+                    this.timeout(config.timeout, `Health check timeout after ${config.timeout}ms`)
+                ]);
+                if (checkResult === false || (checkResult && checkResult.status === 'unhealthy')) {
+                    status = 'unhealthy';
+                    message = checkResult?.message || 'Custom health check failed';
+                    checks.push({ name: config.checkMethod, status: 'failed', message });
+                }
+                else {
+                    checks.push({ name: config.checkMethod, status: 'passed' });
+                }
+            }
+            else {
+                // Default health check - just verify plugin is loaded
+                checks.push({ name: 'plugin-loaded', status: 'passed' });
+            }
+            // Update counters based on result
+            if (status === 'healthy') {
+                this.successCounters.set(pluginName, (this.successCounters.get(pluginName) || 0) + 1);
+                this.failureCounters.set(pluginName, 0);
+                // Recover from unhealthy state if we have enough successes
+                const currentStatus = this.healthStatus.get(pluginName);
+                if (currentStatus === 'unhealthy' || currentStatus === 'degraded') {
+                    const successCount = this.successCounters.get(pluginName) || 0;
+                    if (successCount >= config.successThreshold) {
+                        this.healthStatus.set(pluginName, 'healthy');
+                        this.logger.info('Plugin recovered to healthy state', { plugin: pluginName });
+                    }
+                    else {
+                        this.healthStatus.set(pluginName, 'recovering');
+                    }
+                }
+                else {
+                    this.healthStatus.set(pluginName, 'healthy');
+                }
+            }
+            else {
+                this.failureCounters.set(pluginName, (this.failureCounters.get(pluginName) || 0) + 1);
+                this.successCounters.set(pluginName, 0);
+                const failureCount = this.failureCounters.get(pluginName) || 0;
+                if (failureCount >= config.failureThreshold) {
+                    this.healthStatus.set(pluginName, 'unhealthy');
+                    this.logger.warn('Plugin marked as unhealthy', {
+                        plugin: pluginName,
+                        failures: failureCount
+                    });
+                    // Attempt auto-restart if configured
+                    if (config.autoRestart) {
+                        await this.attemptRestart(pluginName, plugin, config);
+                    }
+                }
+                else {
+                    this.healthStatus.set(pluginName, 'degraded');
+                }
+            }
+        }
+        catch (error) {
+            status = 'failed';
+            message = error instanceof Error ? error.message : 'Unknown error';
+            this.failureCounters.set(pluginName, (this.failureCounters.get(pluginName) || 0) + 1);
+            this.healthStatus.set(pluginName, 'failed');
+            checks.push({
+                name: 'health-check',
+                status: 'failed',
+                message: message
+            });
+            this.logger.error('Health check exception', {
+                plugin: pluginName,
+                error
+            });
+        }
+        // Create health report
+        const report = {
+            status: this.healthStatus.get(pluginName) || 'unknown',
+            timestamp: new Date().toISOString(),
+            message,
+            metrics: {
+                uptime: Date.now() - startTime,
+            },
+            checks: checks.length > 0 ? checks : undefined,
+        };
+        this.healthReports.set(pluginName, report);
+    }
+    /**
+     * Attempt to restart a plugin
+     */
+    async attemptRestart(pluginName, plugin, config) {
+        const attempts = this.restartAttempts.get(pluginName) || 0;
+        if (attempts >= config.maxRestartAttempts) {
+            this.logger.error('Max restart attempts reached, giving up', {
+                plugin: pluginName,
+                attempts
+            });
+            this.healthStatus.set(pluginName, 'failed');
+            return;
+        }
+        this.restartAttempts.set(pluginName, attempts + 1);
+        // Calculate backoff delay
+        const delay = this.calculateBackoff(attempts, config.restartBackoff);
+        this.logger.info('Scheduling plugin restart', {
+            plugin: pluginName,
+            attempt: attempts + 1,
+            delay
+        });
+        await new Promise(resolve => setTimeout(resolve, delay));
+        try {
+            // Call destroy and init to restart
+            if (plugin.destroy) {
+                await plugin.destroy();
+            }
+            // Note: Full restart would require kernel context
+            // This is a simplified version - actual implementation would need kernel integration
+            this.logger.info('Plugin restarted', { plugin: pluginName });
+            // Reset counters on successful restart
+            this.failureCounters.set(pluginName, 0);
+            this.successCounters.set(pluginName, 0);
+            this.healthStatus.set(pluginName, 'recovering');
+        }
+        catch (error) {
+            this.logger.error('Plugin restart failed', {
+                plugin: pluginName,
+                error
+            });
+            this.healthStatus.set(pluginName, 'failed');
+        }
+    }
+    /**
+     * Calculate backoff delay for restarts
+     */
+    calculateBackoff(attempt, strategy) {
+        const baseDelay = 1000; // 1 second base
+        switch (strategy) {
+            case 'fixed':
+                return baseDelay;
+            case 'linear':
+                return baseDelay * (attempt + 1);
+            case 'exponential':
+                return baseDelay * Math.pow(2, attempt);
+            default:
+                return baseDelay;
+        }
+    }
+    /**
+     * Get current health status of a plugin
+     */
+    getHealthStatus(pluginName) {
+        return this.healthStatus.get(pluginName);
+    }
+    /**
+     * Get latest health report for a plugin
+     */
+    getHealthReport(pluginName) {
+        return this.healthReports.get(pluginName);
+    }
+    /**
+     * Get all health statuses
+     */
+    getAllHealthStatuses() {
+        return new Map(this.healthStatus);
+    }
+    /**
+     * Shutdown health monitor
+     */
+    shutdown() {
+        // Stop all monitoring intervals
+        for (const pluginName of this.checkIntervals.keys()) {
+            this.stopMonitoring(pluginName);
+        }
+        this.healthChecks.clear();
+        this.healthStatus.clear();
+        this.healthReports.clear();
+        this.failureCounters.clear();
+        this.successCounters.clear();
+        this.restartAttempts.clear();
+        this.logger.info('Health monitor shutdown complete');
+    }
+    /**
+     * Timeout helper
+     */
+    timeout(ms, message) {
+        return new Promise((_, reject) => {
+            setTimeout(() => reject(new Error(message)), ms);
+        });
+    }
+}

package/dist/health-monitor.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=health-monitor.test.d.ts.map

package/dist/health-monitor.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-monitor.test.d.ts","sourceRoot":"","sources":["../src/health-monitor.test.ts"],"names":[],"mappings":""}

package/dist/health-monitor.test.js

@@ -0,0 +1,68 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PluginHealthMonitor } from './health-monitor.js';
+import { createLogger } from './logger.js';
+describe('PluginHealthMonitor', () => {
+    let monitor;
+    let logger;
+    beforeEach(() => {
+        logger = createLogger({ level: 'silent' });
+        monitor = new PluginHealthMonitor(logger);
+    });
+    it('should register plugin for health monitoring', () => {
+        const config = {
+            interval: 5000,
+            timeout: 1000,
+            failureThreshold: 3,
+            successThreshold: 1,
+            autoRestart: false,
+            maxRestartAttempts: 3,
+            restartBackoff: 'exponential',
+        };
+        monitor.registerPlugin('test-plugin', config);
+        expect(monitor.getHealthStatus('test-plugin')).toBe('unknown');
+    });
+    it('should report healthy status initially', () => {
+        const config = {
+            interval: 5000,
+            timeout: 1000,
+            failureThreshold: 3,
+            successThreshold: 1,
+            autoRestart: false,
+            maxRestartAttempts: 3,
+            restartBackoff: 'fixed',
+        };
+        monitor.registerPlugin('test-plugin', config);
+        expect(monitor.getHealthStatus('test-plugin')).toBe('unknown');
+    });
+    it('should get all health statuses', () => {
+        const config = {
+            interval: 5000,
+            timeout: 1000,
+            failureThreshold: 3,
+            successThreshold: 1,
+            autoRestart: false,
+            maxRestartAttempts: 3,
+            restartBackoff: 'linear',
+        };
+        monitor.registerPlugin('plugin1', config);
+        monitor.registerPlugin('plugin2', config);
+        const statuses = monitor.getAllHealthStatuses();
+        expect(statuses.size).toBe(2);
+        expect(statuses.has('plugin1')).toBe(true);
+        expect(statuses.has('plugin2')).toBe(true);
+    });
+    it('should shutdown cleanly', () => {
+        const config = {
+            interval: 5000,
+            timeout: 1000,
+            failureThreshold: 3,
+            successThreshold: 1,
+            autoRestart: false,
+            maxRestartAttempts: 3,
+            restartBackoff: 'exponential',
+        };
+        monitor.registerPlugin('test-plugin', config);
+        monitor.shutdown();
+        expect(monitor.getAllHealthStatuses().size).toBe(0);
+    });
+});

package/dist/hot-reload.d.ts

@@ -0,0 +1,79 @@
+import type { HotReloadConfig } from '@objectstack/spec/kernel';
+import type { ObjectLogger } from './logger.js';
+import type { Plugin } from './types.js';
+/**
+ * Plugin State Manager
+ *
+ * Handles state persistence and restoration during hot reloads
+ */
+declare class PluginStateManager {
+    private logger;
+    private stateSnapshots;
+    private memoryStore;
+    constructor(logger: ObjectLogger);
+    /**
+     * Save plugin state before reload
+     */
+    saveState(pluginId: string, version: string, state: Record<string, any>, config: HotReloadConfig): Promise<string>;
+    /**
+     * Restore plugin state after reload
+     */
+    restoreState(pluginId: string, snapshotId?: string): Promise<Record<string, any> | undefined>;
+    /**
+     * Clear state for a plugin
+     */
+    clearState(pluginId: string): void;
+    /**
+     * Calculate simple checksum for state verification
+     * WARNING: This is a simple hash for demo purposes.
+     * In production, use a cryptographic hash like SHA-256.
+     */
+    private calculateChecksum;
+    /**
+     * Shutdown state manager
+     */
+    shutdown(): void;
+}
+/**
+ * Hot Reload Manager
+ *
+ * Manages hot reloading of plugins with state preservation
+ */
+export declare class HotReloadManager {
+    private logger;
+    private stateManager;
+    private reloadConfigs;
+    private watchHandles;
+    private reloadTimers;
+    constructor(logger: ObjectLogger);
+    /**
+     * Register a plugin for hot reload
+     */
+    registerPlugin(pluginName: string, config: HotReloadConfig): void;
+    /**
+     * Start watching for changes (requires file system integration)
+     */
+    startWatching(pluginName: string): void;
+    /**
+     * Stop watching for changes
+     */
+    stopWatching(pluginName: string): void;
+    /**
+     * Trigger hot reload for a plugin
+     */
+    reloadPlugin(pluginName: string, plugin: Plugin, version: string, getPluginState: () => Record<string, any>, restorePluginState: (state: Record<string, any>) => void): Promise<boolean>;
+    /**
+     * Schedule a reload with debouncing
+     */
+    scheduleReload(pluginName: string, reloadFn: () => Promise<void>): void;
+    /**
+     * Get state manager for direct access
+     */
+    getStateManager(): PluginStateManager;
+    /**
+     * Shutdown hot reload manager
+     */
+    shutdown(): void;
+}
+export {};
+//# sourceMappingURL=hot-reload.d.ts.map

package/dist/hot-reload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hot-reload.d.ts","sourceRoot":"","sources":["../src/hot-reload.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAezC;;;;GAIG;AACH,cAAM,kBAAkB;IACtB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,cAAc,CAA0C;IAChE,OAAO,CAAC,WAAW,CAA0B;gBAEjC,MAAM,EAAE,YAAY;IAIhC;;OAEG;IACG,SAAS,CACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,MAAM,CAAC;IA8ClB;;OAEG;IACG,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;IAgC3C;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAMlC;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAazB;;OAEG;IACH,QAAQ,IAAI,IAAI;CAKjB;AAED;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,aAAa,CAAsC;IAC3D,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,YAAY,CAAqC;gBAE7C,MAAM,EAAE,YAAY;IAKhC;;OAEG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAcjE;;OAEG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAcvC;;OAEG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAgBtC;;OAEG;IACG,YAAY,CAChB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzC,kBAAkB,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,GACvD,OAAO,CAAC,OAAO,CAAC;IA8EnB;;OAEG;IACH,cAAc,CACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAC5B,IAAI;IAiCP;;OAEG;IACH,eAAe,IAAI,kBAAkB;IAIrC;;OAEG;IACH,QAAQ,IAAI,IAAI;CAkBjB"}