@objectstack/core 4.0.3 → 4.0.5

package/src/hot-reload.ts

@@ -1,382 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { createHash } from 'node:crypto';
-
-import type { 
-  HotReloadConfig, 
-  PluginStateSnapshot 
-} from '@objectstack/spec/kernel';
-import type { ObjectLogger } from './logger.js';
-import type { Plugin } from './types.js';
-
-// Polyfill for UUID generation to support both Node.js and Browser
-const generateUUID = () => {
-  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
-    return crypto.randomUUID();
-  }
-  // Basic UUID v4 fallback
-  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
-    const r = Math.random() * 16 | 0;
-    const v = c === 'x' ? r : (r & 0x3 | 0x8);
-    return v.toString(16);
-  });
-};
-
-/**
- * Plugin State Manager
- * 
- * Handles state persistence and restoration during hot reloads
- */
-class PluginStateManager {
-  private logger: ObjectLogger;
-  private stateSnapshots = new Map<string, PluginStateSnapshot>();
-  private memoryStore = new Map<string, any>();
-
-  constructor(logger: ObjectLogger) {
-    this.logger = logger.child({ component: 'StateManager' });
-  }
-
-  /**
-   * Save plugin state before reload
-   */
-  async saveState(
-    pluginId: string,
-    version: string,
-    state: Record<string, any>,
-    config: HotReloadConfig
-  ): Promise<string> {
-    const snapshot: PluginStateSnapshot = {
-      pluginId,
-      version,
-      timestamp: new Date().toISOString(),
-      state,
-      metadata: {
-        checksum: this.calculateChecksum(state),
-        compressed: false,
-      },
-    };
-
-    const snapshotId = generateUUID();
-
-    switch (config.stateStrategy) {
-      case 'memory':
-        this.memoryStore.set(snapshotId, snapshot);
-        this.logger.debug('State saved to memory', { pluginId, snapshotId });
-        break;
-
-      case 'disk':
-        // For disk storage, we would write to file system
-        // For now, store in memory as fallback
-        this.memoryStore.set(snapshotId, snapshot);
-        this.logger.debug('State saved to disk (memory fallback)', { pluginId, snapshotId });
-        break;
-
-      case 'distributed':
-        // For distributed storage, would use Redis/etcd
-        // For now, store in memory as fallback
-        this.memoryStore.set(snapshotId, snapshot);
-        this.logger.debug('State saved to distributed store (memory fallback)', { 
-          pluginId, 
-          snapshotId 
-        });
-        break;
-
-      case 'none':
-        this.logger.debug('State persistence disabled', { pluginId });
-        break;
-    }
-
-    this.stateSnapshots.set(pluginId, snapshot);
-    return snapshotId;
-  }
-
-  /**
-   * Restore plugin state after reload
-   */
-  async restoreState(
-    pluginId: string,
-    snapshotId?: string
-  ): Promise<Record<string, any> | undefined> {
-    // Try to get from snapshot ID first, otherwise use latest for plugin
-    let snapshot: PluginStateSnapshot | undefined;
-
-    if (snapshotId) {
-      snapshot = this.memoryStore.get(snapshotId);
-    } else {
-      snapshot = this.stateSnapshots.get(pluginId);
-    }
-
-    if (!snapshot) {
-      this.logger.warn('No state snapshot found', { pluginId, snapshotId });
-      return undefined;
-    }
-
-    // Verify checksum if available
-    if (snapshot.metadata?.checksum) {
-      const currentChecksum = this.calculateChecksum(snapshot.state);
-      if (currentChecksum !== snapshot.metadata.checksum) {
-        this.logger.error('State checksum mismatch - data may be corrupted', { 
-          pluginId,
-          expected: snapshot.metadata.checksum,
-          actual: currentChecksum
-        });
-        return undefined;
-      }
-    }
-
-    this.logger.debug('State restored', { pluginId, version: snapshot.version });
-    return snapshot.state;
-  }
-
-  /**
-   * Clear state for a plugin
-   */
-  clearState(pluginId: string): void {
-    this.stateSnapshots.delete(pluginId);
-    // Note: We don't clear memory store as it might have multiple snapshots
-    this.logger.debug('State cleared', { pluginId });
-  }
-
-  /**
-   * Calculate checksum for state verification using SHA-256.
-   */
-  private calculateChecksum(state: Record<string, any>): string {
-    const stateStr = JSON.stringify(state);
-    return createHash('sha256').update(stateStr).digest('hex');
-  }
-
-  /**
-   * Shutdown state manager
-   */
-  shutdown(): void {
-    this.stateSnapshots.clear();
-    this.memoryStore.clear();
-    this.logger.info('State manager shutdown complete');
-  }
-}
-
-/**
- * Hot Reload Manager
- * 
- * Manages hot reloading of plugins with state preservation
- */
-export class HotReloadManager {
-  private logger: ObjectLogger;
-  private stateManager: PluginStateManager;
-  private reloadConfigs = new Map<string, HotReloadConfig>();
-  private watchHandles = new Map<string, any>();
-  private reloadTimers = new Map<string, NodeJS.Timeout>();
-
-  constructor(logger: ObjectLogger) {
-    this.logger = logger.child({ component: 'HotReload' });
-    this.stateManager = new PluginStateManager(logger);
-  }
-
-  /**
-   * Register a plugin for hot reload
-   */
-  registerPlugin(pluginName: string, config: HotReloadConfig): void {
-    if (!config.enabled) {
-      this.logger.debug('Hot reload disabled for plugin', { plugin: pluginName });
-      return;
-    }
-
-    this.reloadConfigs.set(pluginName, config);
-    this.logger.info('Plugin registered for hot reload', { 
-      plugin: pluginName,
-      watchPatterns: config.watchPatterns,
-      stateStrategy: config.stateStrategy
-    });
-  }
-
-  /**
-   * Start watching for changes (requires file system integration)
-   */
-  startWatching(pluginName: string): void {
-    const config = this.reloadConfigs.get(pluginName);
-    if (!config || !config.enabled) {
-      return;
-    }
-
-    // Note: Actual file watching would require chokidar or similar
-    // This is a placeholder for the integration point
-    this.logger.info('File watching started', { 
-      plugin: pluginName,
-      patterns: config.watchPatterns 
-    });
-  }
-
-  /**
-   * Stop watching for changes
-   */
-  stopWatching(pluginName: string): void {
-    const handle = this.watchHandles.get(pluginName);
-    if (handle) {
-      // Stop watching (would call chokidar close())
-      this.watchHandles.delete(pluginName);
-      this.logger.info('File watching stopped', { plugin: pluginName });
-    }
-
-    // Clear any pending reload timers
-    const timer = this.reloadTimers.get(pluginName);
-    if (timer) {
-      clearTimeout(timer);
-      this.reloadTimers.delete(pluginName);
-    }
-  }
-
-  /**
-   * Trigger hot reload for a plugin
-   */
-  async reloadPlugin(
-    pluginName: string,
-    plugin: Plugin,
-    version: string,
-    getPluginState: () => Record<string, any>,
-    restorePluginState: (state: Record<string, any>) => void
-  ): Promise<boolean> {
-    const config = this.reloadConfigs.get(pluginName);
-    if (!config) {
-      this.logger.warn('Cannot reload - plugin not registered', { plugin: pluginName });
-      return false;
-    }
-
-    this.logger.info('Starting hot reload', { plugin: pluginName });
-
-    try {
-      // Call before reload hooks
-      if (config.beforeReload) {
-        this.logger.debug('Executing before reload hooks', { 
-          plugin: pluginName,
-          hooks: config.beforeReload 
-        });
-        // Hook execution would be done through kernel's hook system
-      }
-
-      // Save state if configured
-      let snapshotId: string | undefined;
-      if (config.preserveState && config.stateStrategy !== 'none') {
-        const state = getPluginState();
-        snapshotId = await this.stateManager.saveState(
-          pluginName,
-          version,
-          state,
-          config
-        );
-        this.logger.debug('Plugin state saved', { plugin: pluginName, snapshotId });
-      }
-
-      // Gracefully shutdown the plugin
-      if (plugin.destroy) {
-        this.logger.debug('Destroying plugin', { plugin: pluginName });
-        
-        const shutdownPromise = plugin.destroy();
-        const timeoutPromise = new Promise((_, reject) => {
-          setTimeout(() => reject(new Error('Shutdown timeout')), config.shutdownTimeout);
-        });
-
-        await Promise.race([shutdownPromise, timeoutPromise]);
-        this.logger.debug('Plugin destroyed successfully', { plugin: pluginName });
-      }
-
-      // At this point, the kernel would reload the plugin module
-      // This would be handled by the plugin loader
-      this.logger.debug('Plugin module would be reloaded here', { plugin: pluginName });
-
-      // Restore state if we saved it
-      if (snapshotId && config.preserveState) {
-        const restoredState = await this.stateManager.restoreState(pluginName, snapshotId);
-        if (restoredState) {
-          restorePluginState(restoredState);
-          this.logger.debug('Plugin state restored', { plugin: pluginName });
-        }
-      }
-
-      // Call after reload hooks
-      if (config.afterReload) {
-        this.logger.debug('Executing after reload hooks', { 
-          plugin: pluginName,
-          hooks: config.afterReload 
-        });
-        // Hook execution would be done through kernel's hook system
-      }
-
-      this.logger.info('Hot reload completed successfully', { plugin: pluginName });
-      return true;
-    } catch (error) {
-      this.logger.error('Hot reload failed', { 
-        plugin: pluginName, 
-        error 
-      });
-      return false;
-    }
-  }
-
-  /**
-   * Schedule a reload with debouncing
-   */
-  scheduleReload(
-    pluginName: string,
-    reloadFn: () => Promise<void>
-  ): void {
-    const config = this.reloadConfigs.get(pluginName);
-    if (!config) {
-      return;
-    }
-
-    // Clear existing timer
-    const existingTimer = this.reloadTimers.get(pluginName);
-    if (existingTimer) {
-      clearTimeout(existingTimer);
-    }
-
-    // Schedule new reload with debounce
-    const timer = setTimeout(() => {
-      this.logger.debug('Debounce period elapsed, executing reload', { 
-        plugin: pluginName 
-      });
-      reloadFn().catch(error => {
-        this.logger.error('Scheduled reload failed', { 
-          plugin: pluginName, 
-          error 
-        });
-      });
-      this.reloadTimers.delete(pluginName);
-    }, config.debounceDelay);
-
-    this.reloadTimers.set(pluginName, timer);
-    this.logger.debug('Reload scheduled with debounce', { 
-      plugin: pluginName,
-      delay: config.debounceDelay 
-    });
-  }
-
-  /**
-   * Get state manager for direct access
-   */
-  getStateManager(): PluginStateManager {
-    return this.stateManager;
-  }
-
-  /**
-   * Shutdown hot reload manager
-   */
-  shutdown(): void {
-    // Stop all watching
-    for (const pluginName of this.watchHandles.keys()) {
-      this.stopWatching(pluginName);
-    }
-
-    // Clear all timers
-    for (const timer of this.reloadTimers.values()) {
-      clearTimeout(timer);
-    }
-
-    this.reloadConfigs.clear();
-    this.watchHandles.clear();
-    this.reloadTimers.clear();
-    this.stateManager.shutdown();
-    
-    this.logger.info('Hot reload manager shutdown complete');
-  }
-}

package/src/index.ts

@@ -1,50 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * @objectstack/core
- * 
- * Core runtime for ObjectStack microkernel architecture.
- * Provides plugin system, dependency injection, and lifecycle management.
- */
-
-export * from './kernel-base.js';
-export * from './kernel.js';
-export * from './lite-kernel.js';
-export * from './types.js';
-export * from './logger.js';
-export * from './plugin-loader.js';
-export * from './api-registry.js';
-export * from './api-registry-plugin.js';
-export * as QA from './qa/index.js';
-
-// Export security utilities
-export * from './security/index.js';
-
-// Export environment utilities
-export * from './utils/env.js';
-
-// Export in-memory fallbacks for core-criticality services
-export * from './fallbacks/index.js';
-
-// Export Phase 2 components - Advanced lifecycle management
-export * from './health-monitor.js';
-export * from './hot-reload.js';
-export * from './dependency-resolver.js';
-
-// Export Phase 3 components - Package lifecycle management
-export * from './namespace-resolver.js';
-export * from './package-manager.js';
-
-// Re-export contracts from @objectstack/spec for backward compatibility
-export type { 
-    Logger,
-    IHttpServer,
-    IHttpRequest,
-    IHttpResponse,
-    RouteHandler,
-    Middleware,
-    IDataEngine,
-    IDataDriver,
-    /** @deprecated Use `IDataDriver` instead */
-    DriverInterface
-} from '@objectstack/spec/contracts';

package/src/kernel-base.ts

@@ -1,273 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { Plugin, PluginContext } from './types.js';
-import type { Logger } from '@objectstack/spec/contracts';
-import type { IServiceRegistry } from '@objectstack/spec/contracts';
-
-/**
- * Kernel state machine
- */
-export type KernelState = 'idle' | 'initializing' | 'running' | 'stopping' | 'stopped';
-
-/**
- * ObjectKernelBase - Abstract Base Class for Microkernel
- * 
- * Provides common functionality for ObjectKernel and LiteKernel:
- * - Plugin management (Map storage)
- * - Dependency resolution (topological sort)
- * - Hook/Event system
- * - Context creation
- * - State validation
- * 
- * This eliminates code duplication between the implementations.
- */
-export abstract class ObjectKernelBase {
-    protected plugins: Map<string, Plugin> = new Map();
-    protected services: IServiceRegistry | Map<string, any> = new Map();
-    protected hooks: Map<string, Array<(...args: any[]) => void | Promise<void>>> = new Map();
-    protected state: KernelState = 'idle';
-    protected logger: Logger;
-    protected context!: PluginContext;
-
-    constructor(logger: Logger) {
-        this.logger = logger;
-    }
-
-    /**
-     * Validate kernel state
-     * @param requiredState - Required state for the operation
-     * @throws Error if current state doesn't match
-     */
-    protected validateState(requiredState: KernelState): void {
-        if (this.state !== requiredState) {
-            throw new Error(
-                `[Kernel] Invalid state: expected '${requiredState}', got '${this.state}'`
-            );
-        }
-    }
-
-    /**
-     * Validate kernel is in idle state (for plugin registration)
-     */
-    protected validateIdle(): void {
-        if (this.state !== 'idle') {
-            throw new Error('[Kernel] Cannot register plugins after bootstrap has started');
-        }
-    }
-
-    /**
-     * Create the plugin context
-     * Subclasses can override to customize context creation
-     */
-    protected createContext(): PluginContext {
-        return {
-            registerService: (name, service) => {
-                if (this.services instanceof Map) {
-                    if (this.services.has(name)) {
-                        throw new Error(`[Kernel] Service '${name}' already registered`);
-                    }
-                    this.services.set(name, service);
-                } else {
-                    // IServiceRegistry implementation
-                    this.services.register(name, service);
-                }
-                this.logger.info(`Service '${name}' registered`, { service: name });
-            },
-            getService: <T>(name: string): T => {
-                if (this.services instanceof Map) {
-                    const service = this.services.get(name);
-                    if (!service) {
-                        throw new Error(`[Kernel] Service '${name}' not found`);
-                    }
-                    return service as T;
-                } else {
-                    // IServiceRegistry implementation
-                    return this.services.get<T>(name);
-                }
-            },
-            replaceService: <T>(name: string, implementation: T): void => {
-                if (this.services instanceof Map) {
-                    if (!this.services.has(name)) {
-                        throw new Error(`[Kernel] Service '${name}' not found. Use registerService() to add new services.`);
-                    }
-                    this.services.set(name, implementation);
-                } else {
-                    // IServiceRegistry implementation
-                    if (!this.services.has(name)) {
-                        throw new Error(`[Kernel] Service '${name}' not found. Use registerService() to add new services.`);
-                    }
-                    this.services.register(name, implementation);
-                }
-                this.logger.info(`Service '${name}' replaced`, { service: name });
-            },
-            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: () => {
-                if (this.services instanceof Map) {
-                    return new Map(this.services);
-                } else {
-                    // For IServiceRegistry, we need to return the underlying Map
-                    // This is a compatibility method
-                    return new Map();
-                }
-            },
-            logger: this.logger,
-            getKernel: () => this as any,
-        };
-    }
-
-    /**
-     * Resolve plugin dependencies using topological sort
-     * @returns Ordered list of plugins (dependencies first)
-     */
-    protected resolveDependencies(): Plugin[] {
-        const resolved: Plugin[] = [];
-        const visited = new Set<string>();
-        const visiting = new Set<string>();
-
-        const visit = (pluginName: string) => {
-            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;
-    }
-
-    /**
-     * Run plugin init phase
-     * @param plugin - Plugin to initialize
-     */
-    protected async runPluginInit(plugin: Plugin): Promise<void> {
-        const pluginName = plugin.name;
-        this.logger.info(`Initializing plugin: ${pluginName}`);
-        
-        try {
-            await plugin.init(this.context);
-            this.logger.info(`Plugin initialized: ${pluginName}`);
-        } catch (error) {
-            this.logger.error(`Plugin init failed: ${pluginName}`, error as Error);
-            throw error;
-        }
-    }
-
-    /**
-     * Run plugin start phase
-     * @param plugin - Plugin to start
-     */
-    protected async runPluginStart(plugin: Plugin): Promise<void> {
-        if (!plugin.start) return;
-        
-        const pluginName = plugin.name;
-        this.logger.info(`Starting plugin: ${pluginName}`);
-        
-        try {
-            await plugin.start(this.context);
-            this.logger.info(`Plugin started: ${pluginName}`);
-        } catch (error) {
-            this.logger.error(`Plugin start failed: ${pluginName}`, error as Error);
-            throw error;
-        }
-    }
-
-    /**
-     * Run plugin destroy phase
-     * @param plugin - Plugin to destroy
-     */
-    protected async runPluginDestroy(plugin: Plugin): Promise<void> {
-        if (!plugin.destroy) return;
-        
-        const pluginName = plugin.name;
-        this.logger.info(`Destroying plugin: ${pluginName}`);
-        
-        try {
-            await plugin.destroy();
-            this.logger.info(`Plugin destroyed: ${pluginName}`);
-        } catch (error) {
-            this.logger.error(`Plugin destroy failed: ${pluginName}`, error as Error);
-            throw error;
-        }
-    }
-
-    /**
-     * Trigger a hook with all registered handlers
-     * @param name - Hook name
-     * @param args - Arguments to pass to handlers
-     */
-    protected async triggerHook(name: string, ...args: any[]): Promise<void> {
-        const handlers = this.hooks.get(name) || [];
-        this.logger.debug(`Triggering hook: ${name}`, { 
-            hook: name, 
-            handlerCount: handlers.length 
-        });
-        
-        for (const handler of handlers) {
-            try {
-                await handler(...args);
-            } catch (error) {
-                this.logger.error(`Hook handler failed: ${name}`, error as Error);
-                // Continue with other handlers even if one fails
-            }
-        }
-    }
-
-    /**
-     * Get current kernel state
-     */
-    getState(): KernelState {
-        return this.state;
-    }
-
-    /**
-     * Get all registered plugins
-     */
-    getPlugins(): Map<string, Plugin> {
-        return new Map(this.plugins);
-    }
-
-    /**
-     * Abstract methods to be implemented by subclasses
-     */
-    abstract use(plugin: Plugin): this | Promise<this>;
-    abstract bootstrap(): Promise<void>;
-    abstract destroy(): Promise<void>;
-}