@objectstack/core 0.9.1 → 1.0.0

package/dist/kernel.js

@@ -1,112 +1,469 @@
 import { createLogger } from './logger.js';
-import { ObjectKernelBase } from './kernel-base.js';
+import { ServiceRequirementDef } from '@objectstack/spec/system';
+import { PluginLoader, ServiceLifecycle } from './plugin-loader.js';
 /**
- * ObjectKernel - MiniKernel Architecture
+ * Enhanced ObjectKernel with Advanced Plugin Management
  *
- * A highly modular, plugin-based microkernel that:
- * - Manages plugin lifecycle (init, start, destroy)
- * - Provides dependency injection via service registry
- * - Implements event/hook system for inter-plugin communication
- * - Handles dependency resolution (topological sort)
- * - Provides configurable logging for server and browser
- *
- * Core philosophy:
- * - Business logic is completely separated into plugins
- * - Kernel only manages lifecycle, DI, and hooks
- * - Plugins are loaded as equal building blocks
+ * Extends the basic ObjectKernel with:
+ * - Async plugin loading with validation
+ * - Version compatibility checking
+ * - Plugin signature verification
+ * - Configuration validation (Zod)
+ * - Factory-based dependency injection
+ * - Service lifecycle management (singleton/transient/scoped)
+ * - Circular dependency detection
+ * - Lazy loading services
+ * - Graceful shutdown
+ * - Plugin startup timeout control
+ * - Startup failure rollback
+ * - Plugin health checks
  */
-export class ObjectKernel extends ObjectKernelBase {
-    constructor(config) {
-        const logger = createLogger(config?.logger);
-        super(logger);
-        // Initialize context after logger is created
-        this.context = this.createContext();
+export class ObjectKernel {
+    constructor(config = {}) {
+        this.plugins = new Map();
+        this.services = new Map();
+        this.hooks = new Map();
+        this.state = 'idle';
+        this.startedPlugins = new Set();
+        this.pluginStartTimes = new Map();
+        this.shutdownHandlers = [];
+        this.config = {
+            defaultStartupTimeout: 30000, // 30 seconds
+            gracefulShutdown: true,
+            shutdownTimeout: 60000, // 60 seconds
+            rollbackOnFailure: true,
+            ...config,
+        };
+        this.logger = createLogger(config.logger);
+        this.pluginLoader = new PluginLoader(this.logger);
+        // Initialize context
+        this.context = {
+            registerService: (name, service) => {
+                this.registerService(name, service);
+            },
+            getService: (name) => {
+                // 1. Try direct service map first (synchronous cache)
+                const service = this.services.get(name);
+                if (service) {
+                    return service;
+                }
+                // 2. Try to get from plugin loader cache (Sync access to factories)
+                const loaderService = this.pluginLoader.getServiceInstance(name);
+                if (loaderService) {
+                    // Cache it locally for faster next access
+                    this.services.set(name, loaderService);
+                    return loaderService;
+                }
+                // 3. Try to get from plugin loader (support async factories)
+                try {
+                    const service = this.pluginLoader.getService(name);
+                    if (service instanceof Promise) {
+                        // If we found it in the loader but not in the sync map, it's likely a factory-based service or still loading
+                        throw new Error(`Service '${name}' is async - use await`);
+                    }
+                    return service;
+                }
+                catch (error) {
+                    if (error.message?.includes('is async')) {
+                        throw error;
+                    }
+                    // Re-throw critical factory errors instead of masking them as "not found"
+                    // If the error came from the factory execution (e.g. database connection failed), we must see it.
+                    // "Service '${name}' not found" comes from PluginLoader.getService fallback.
+                    const isNotFoundError = error.message === `Service '${name}' not found`;
+                    if (!isNotFoundError) {
+                        throw error;
+                    }
+                    throw new Error(`[Kernel] Service '${name}' not found`);
+                }
+            },
+            hook: (name, handler) => {
+                if (!this.hooks.has(name)) {
+                    this.hooks.set(name, []);
+                }
+                this.hooks.get(name).push(handler);
+            },
+            trigger: async (name, ...args) => {
+                const handlers = this.hooks.get(name) || [];
+                for (const handler of handlers) {
+                    await handler(...args);
+                }
+            },
+            getServices: () => {
+                return new Map(this.services);
+            },
+            logger: this.logger,
+            getKernel: () => this, // Type compatibility
+        };
+        this.pluginLoader.setContext(this.context);
+        // Register shutdown handler
+        if (this.config.gracefulShutdown) {
+            this.registerShutdownSignals();
+        }
+    }
+    /**
+     * Register a plugin with enhanced validation
+     */
+    async use(plugin) {
+        if (this.state !== 'idle') {
+            throw new Error('[Kernel] Cannot register plugins after bootstrap has started');
+        }
+        // Load plugin through enhanced loader
+        const result = await this.pluginLoader.loadPlugin(plugin);
+        if (!result.success || !result.plugin) {
+            throw new Error(`Failed to load plugin: ${plugin.name} - ${result.error?.message}`);
+        }
+        const pluginMeta = result.plugin;
+        this.plugins.set(pluginMeta.name, pluginMeta);
+        this.logger.info(`Plugin registered: ${pluginMeta.name}@${pluginMeta.version}`, {
+            plugin: pluginMeta.name,
+            version: pluginMeta.version,
+        });
+        return this;
     }
     /**
-     * Register a plugin
-     * @param plugin - Plugin instance
+     * Register a service instance directly
      */
-    use(plugin) {
-        this.validateIdle();
-        const pluginName = plugin.name;
-        if (this.plugins.has(pluginName)) {
-            throw new Error(`[Kernel] Plugin '${pluginName}' already registered`);
+    registerService(name, service) {
+        if (this.services.has(name)) {
+            throw new Error(`[Kernel] Service '${name}' already registered`);
         }
-        this.plugins.set(pluginName, plugin);
+        this.services.set(name, service);
+        this.pluginLoader.registerService(name, service);
+        this.logger.info(`Service '${name}' registered`, { service: name });
         return this;
     }
     /**
-     * Bootstrap the kernel
-     * 1. Resolve dependencies (topological sort)
-     * 2. Init phase - plugins register services
-     * 3. Start phase - plugins execute business logic
-     * 4. Trigger 'kernel:ready' hook
+     * Register a service factory with lifecycle management
+     */
+    registerServiceFactory(name, factory, lifecycle = ServiceLifecycle.SINGLETON, dependencies) {
+        this.pluginLoader.registerServiceFactory({
+            name,
+            factory,
+            lifecycle,
+            dependencies,
+        });
+        return this;
+    }
+    /**
+     * Validate Critical System Requirements
+     */
+    validateSystemRequirements() {
+        if (this.config.skipSystemValidation) {
+            this.logger.debug('System requirement validation skipped');
+            return;
+        }
+        this.logger.debug('Validating system service requirements...');
+        const missingServices = [];
+        const missingCoreServices = [];
+        // Iterate through all defined requirements
+        for (const [serviceName, criticality] of Object.entries(ServiceRequirementDef)) {
+            const hasService = this.services.has(serviceName) || this.pluginLoader.hasService(serviceName);
+            if (!hasService) {
+                if (criticality === 'required') {
+                    this.logger.error(`CRITICAL: Required service missing: ${serviceName}`);
+                    missingServices.push(serviceName);
+                }
+                else if (criticality === 'core') {
+                    this.logger.warn(`CORE: Core service missing, functionality may be degraded: ${serviceName}`);
+                    missingCoreServices.push(serviceName);
+                }
+                else {
+                    this.logger.info(`Info: Optional service not present: ${serviceName}`);
+                }
+            }
+        }
+        if (missingServices.length > 0) {
+            const errorMsg = `System failed to start. Missing critical services: ${missingServices.join(', ')}`;
+            this.logger.error(errorMsg);
+            throw new Error(errorMsg);
+        }
+        if (missingCoreServices.length > 0) {
+            this.logger.warn(`System started with degraded capabilities. Missing core services: ${missingCoreServices.join(', ')}`);
+        }
+        this.logger.info('System requirement check passed');
+    }
+    /**
+     * Bootstrap the kernel with enhanced features
      */
     async bootstrap() {
-        this.validateState('idle');
+        if (this.state !== 'idle') {
+            throw new Error('[Kernel] Kernel already bootstrapped');
+        }
         this.state = 'initializing';
         this.logger.info('Bootstrap started');
-        // Resolve dependencies
-        const orderedPlugins = this.resolveDependencies();
-        // Phase 1: Init - Plugins register services
-        this.logger.info('Phase 1: Init plugins');
-        for (const plugin of orderedPlugins) {
-            await this.runPluginInit(plugin);
+        try {
+            // Check for circular dependencies
+            const cycles = this.pluginLoader.detectCircularDependencies();
+            if (cycles.length > 0) {
+                this.logger.warn('Circular service dependencies detected:', { cycles });
+            }
+            // Resolve plugin dependencies
+            const orderedPlugins = this.resolveDependencies();
+            // Phase 1: Init - Plugins register services
+            this.logger.info('Phase 1: Init plugins');
+            for (const plugin of orderedPlugins) {
+                await this.initPluginWithTimeout(plugin);
+            }
+            // Phase 2: Start - Plugins execute business logic
+            this.logger.info('Phase 2: Start plugins');
+            this.state = 'running';
+            for (const plugin of orderedPlugins) {
+                const result = await this.startPluginWithTimeout(plugin);
+                if (!result.success) {
+                    this.logger.error(`Plugin startup failed: ${plugin.name}`, result.error);
+                    if (this.config.rollbackOnFailure) {
+                        this.logger.warn('Rolling back started plugins...');
+                        await this.rollbackStartedPlugins();
+                        throw new Error(`Plugin ${plugin.name} failed to start - rollback complete`);
+                    }
+                }
+            }
+            // Phase 3: Trigger kernel:ready hook
+            this.validateSystemRequirements(); // Final check before ready
+            this.logger.debug('Triggering kernel:ready hook');
+            await this.context.trigger('kernel:ready');
+            this.logger.info('✅ Bootstrap complete');
         }
-        // Phase 2: Start - Plugins execute business logic
-        this.logger.info('Phase 2: Start plugins');
-        this.state = 'running';
-        for (const plugin of orderedPlugins) {
-            await this.runPluginStart(plugin);
+        catch (error) {
+            this.state = 'stopped';
+            throw error;
         }
-        // Trigger ready hook
-        await this.triggerHook('kernel:ready');
-        this.logger.info('✅ Bootstrap complete', {
-            pluginCount: this.plugins.size
-        });
     }
     /**
-     * Shutdown the kernel
-     * Calls destroy on all plugins in reverse order
+     * Graceful shutdown with timeout
      */
     async shutdown() {
-        await this.destroy();
-    }
-    /**
-     * Graceful shutdown - destroy all plugins in reverse order
-     */
-    async destroy() {
-        if (this.state === 'stopped') {
-            this.logger.warn('Kernel already stopped');
+        if (this.state === 'stopped' || this.state === 'stopping') {
+            this.logger.warn('Kernel already stopped or stopping');
             return;
         }
+        if (this.state !== 'running') {
+            throw new Error('[Kernel] Kernel not running');
+        }
         this.state = 'stopping';
-        this.logger.info('Shutdown started');
-        // Trigger shutdown hook
-        await this.triggerHook('kernel:shutdown');
-        // Destroy plugins in reverse order
-        const orderedPlugins = this.resolveDependencies();
-        for (const plugin of orderedPlugins.reverse()) {
-            await this.runPluginDestroy(plugin);
-        }
-        this.state = 'stopped';
-        this.logger.info('✅ Shutdown complete');
-        // Cleanup logger resources
-        if (this.logger && typeof this.logger.destroy === 'function') {
+        this.logger.info('Graceful shutdown started');
+        try {
+            // Create shutdown promise with timeout
+            const shutdownPromise = this.performShutdown();
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => {
+                    reject(new Error('Shutdown timeout exceeded'));
+                }, this.config.shutdownTimeout);
+            });
+            // Race between shutdown and timeout
+            await Promise.race([shutdownPromise, timeoutPromise]);
+            this.state = 'stopped';
+            this.logger.info('✅ Graceful shutdown complete');
+        }
+        catch (error) {
+            this.logger.error('Shutdown error - forcing stop', error);
+            this.state = 'stopped';
+            throw error;
+        }
+        finally {
+            // Cleanup logger resources
             await this.logger.destroy();
         }
     }
     /**
-     * Get a service from the registry
-     * Convenience method for external access
+     * Check health of a specific plugin
+     */
+    async checkPluginHealth(pluginName) {
+        return await this.pluginLoader.checkPluginHealth(pluginName);
+    }
+    /**
+     * Check health of all plugins
+     */
+    async checkAllPluginsHealth() {
+        const results = new Map();
+        for (const pluginName of this.plugins.keys()) {
+            const health = await this.checkPluginHealth(pluginName);
+            results.set(pluginName, health);
+        }
+        return results;
+    }
+    /**
+     * Get plugin startup metrics
+     */
+    getPluginMetrics() {
+        return new Map(this.pluginStartTimes);
+    }
+    /**
+     * Get a service (sync helper)
      */
     getService(name) {
         return this.context.getService(name);
     }
+    /**
+     * Get a service asynchronously (supports factories)
+     */
+    async getServiceAsync(name, scopeId) {
+        return await this.pluginLoader.getService(name, scopeId);
+    }
     /**
      * Check if kernel is running
      */
     isRunning() {
         return this.state === 'running';
     }
+    /**
+     * Get kernel state
+     */
+    getState() {
+        return this.state;
+    }
+    // Private methods
+    async initPluginWithTimeout(plugin) {
+        const timeout = plugin.startupTimeout || this.config.defaultStartupTimeout;
+        this.logger.debug(`Init: ${plugin.name}`, { plugin: plugin.name });
+        const initPromise = plugin.init(this.context);
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new Error(`Plugin ${plugin.name} init timeout after ${timeout}ms`));
+            }, timeout);
+        });
+        await Promise.race([initPromise, timeoutPromise]);
+    }
+    async startPluginWithTimeout(plugin) {
+        if (!plugin.start) {
+            return { success: true, pluginName: plugin.name };
+        }
+        const timeout = plugin.startupTimeout || this.config.defaultStartupTimeout;
+        const startTime = Date.now();
+        this.logger.debug(`Start: ${plugin.name}`, { plugin: plugin.name });
+        try {
+            const startPromise = plugin.start(this.context);
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => {
+                    reject(new Error(`Plugin ${plugin.name} start timeout after ${timeout}ms`));
+                }, timeout);
+            });
+            await Promise.race([startPromise, timeoutPromise]);
+            const duration = Date.now() - startTime;
+            this.startedPlugins.add(plugin.name);
+            this.pluginStartTimes.set(plugin.name, duration);
+            this.logger.debug(`Plugin started: ${plugin.name} (${duration}ms)`);
+            return {
+                success: true,
+                pluginName: plugin.name,
+                startTime: duration,
+            };
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const isTimeout = error.message.includes('timeout');
+            return {
+                success: false,
+                pluginName: plugin.name,
+                error: error,
+                startTime: duration,
+                timedOut: isTimeout,
+            };
+        }
+    }
+    async rollbackStartedPlugins() {
+        const pluginsToRollback = Array.from(this.startedPlugins).reverse();
+        for (const pluginName of pluginsToRollback) {
+            const plugin = this.plugins.get(pluginName);
+            if (plugin?.destroy) {
+                try {
+                    this.logger.debug(`Rollback: ${pluginName}`);
+                    await plugin.destroy();
+                }
+                catch (error) {
+                    this.logger.error(`Rollback failed for ${pluginName}`, error);
+                }
+            }
+        }
+        this.startedPlugins.clear();
+    }
+    async performShutdown() {
+        // Trigger shutdown hook
+        await this.context.trigger('kernel:shutdown');
+        // Destroy plugins in reverse order
+        const orderedPlugins = Array.from(this.plugins.values()).reverse();
+        for (const plugin of orderedPlugins) {
+            if (plugin.destroy) {
+                this.logger.debug(`Destroy: ${plugin.name}`, { plugin: plugin.name });
+                try {
+                    await plugin.destroy();
+                }
+                catch (error) {
+                    this.logger.error(`Error destroying plugin ${plugin.name}`, error);
+                }
+            }
+        }
+        // Execute custom shutdown handlers
+        for (const handler of this.shutdownHandlers) {
+            try {
+                await handler();
+            }
+            catch (error) {
+                this.logger.error('Shutdown handler error', error);
+            }
+        }
+    }
+    resolveDependencies() {
+        const resolved = [];
+        const visited = new Set();
+        const visiting = new Set();
+        const visit = (pluginName) => {
+            if (visited.has(pluginName))
+                return;
+            if (visiting.has(pluginName)) {
+                throw new Error(`[Kernel] Circular dependency detected: ${pluginName}`);
+            }
+            const plugin = this.plugins.get(pluginName);
+            if (!plugin) {
+                throw new Error(`[Kernel] Plugin '${pluginName}' not found`);
+            }
+            visiting.add(pluginName);
+            // Visit dependencies first
+            const deps = plugin.dependencies || [];
+            for (const dep of deps) {
+                if (!this.plugins.has(dep)) {
+                    throw new Error(`[Kernel] Dependency '${dep}' not found for plugin '${pluginName}'`);
+                }
+                visit(dep);
+            }
+            visiting.delete(pluginName);
+            visited.add(pluginName);
+            resolved.push(plugin);
+        };
+        // Visit all plugins
+        for (const pluginName of this.plugins.keys()) {
+            visit(pluginName);
+        }
+        return resolved;
+    }
+    registerShutdownSignals() {
+        const signals = ['SIGINT', 'SIGTERM', 'SIGQUIT'];
+        let shutdownInProgress = false;
+        const handleShutdown = async (signal) => {
+            if (shutdownInProgress) {
+                this.logger.warn(`Shutdown already in progress, ignoring ${signal}`);
+                return;
+            }
+            shutdownInProgress = true;
+            this.logger.info(`Received ${signal} - initiating graceful shutdown`);
+            try {
+                await this.shutdown();
+                process.exit(0);
+            }
+            catch (error) {
+                this.logger.error('Shutdown failed', error);
+                process.exit(1);
+            }
+        };
+        for (const signal of signals) {
+            process.on(signal, () => handleShutdown(signal));
+        }
+    }
+    /**
+     * Register a custom shutdown handler
+     */
+    onShutdown(handler) {
+        this.shutdownHandlers.push(handler);
+    }
 }