@hkdigital/lib-core 0.4.18 → 0.4.20

package/dist/services/README.md

@@ -11,27 +11,39 @@ The services module provides two main components:
 
 All services follow a standardized state machine with proper error handling, logging, and health monitoring.
 
-## Service States
-
-Services transition through these states during their lifecycle:
-
-- `created` - Service instantiated but not initialized
-- `initializing` - Currently running initialization
-- `initialized` - Ready to start
-- `starting` - Currently starting up
-- `running` - Operational and healthy
-- `stopping` - Currently shutting down
-- `stopped` - Cleanly stopped
-- `destroying` - Being destroyed and cleaned up
-- `destroyed` - Completely destroyed
-- `error` - Failed and non-operational
-- `recovering` - Attempting recovery from error
+## Service states
+
+Services transition through these states during their lifecycle. Use these constants from `$lib/services/service-base/constants.js`:
+
+- `STATE_CREATED` - Service instantiated but not configured
+- `STATE_CONFIGURING` - Currently running configuration
+- `STATE_CONFIGURED` - Ready to start
+- `STATE_STARTING` - Currently starting up
+- `STATE_RUNNING` - Operational and healthy
+- `STATE_STOPPING` - Currently shutting down
+- `STATE_STOPPED` - Cleanly stopped
+- `STATE_DESTROYING` - Being destroyed and cleaned up
+- `STATE_DESTROYED` - Completely destroyed
+- `STATE_ERROR` - Failed and non-operational
+- `STATE_RECOVERING` - Attempting recovery from error
+
+```javascript
+import {
+  STATE_RUNNING,
+  STATE_ERROR
+} from '$lib/services/service-base/constants.js';
+
+if (service.state === STATE_RUNNING) {
+  // Service is operational
+}
+```
 
 ## ServiceBase
 
 Base class that all services should extend. Provides:
 
-- Standardized lifecycle methods (`initialize`, `start`, `stop`, `destroy`)
+- Standardized lifecycle methods (`configure`, `start`, `stop`, `destroy`)
+- Flexible configuration system with reconfiguration support
 - Health monitoring and recovery
 - Event emission for state changes
 - Integrated logging
@@ -43,8 +55,34 @@ Base class that all services should extend. Provides:
 import { ServiceBase } from '$lib/services/index.js';
 
 class DatabaseService extends ServiceBase {
-  async _init(config) {
-    this.connectionString = config.connectionString;
+  // eslint-disable-next-line no-unused-vars
+  async _configure(newConfig, oldConfig = null) {
+    if (!oldConfig) {
+      // Initial configuration
+
+      this.connectionString = newConfig.connectionString;
+      this.maxConnections = newConfig.maxConnections || 10;
+      return;
+    }
+
+    if (oldConfig.connectionString !== newConfig.connectionString) {
+      // Reconfiguration - handle changes intelligently
+
+      // Connection changed - need to reconnect
+      await this.connection?.close();
+
+      this.connectionString = newConfig.connectionString;
+      if (this.state === 'running') {
+        this.connection = await createConnection(this.connectionString);
+      }
+    }
+
+    if (oldConfig.maxConnections !== newConfig.maxConnections) {
+      // Pool size changed - update without reconnect
+      //
+      this.maxConnections = newConfig.maxConnections;
+      await this.connection?.setMaxConnections(this.maxConnections);
+    }
   }
 
   async _start() {
@@ -64,29 +102,49 @@ class DatabaseService extends ServiceBase {
 
 // Usage
 const db = new DatabaseService('database');
-await db.initialize({ connectionString: 'postgres://...' });
+await db.configure({
+  connectionString: 'postgres://localhost/myapp',
+  maxConnections: 20
+});
 await db.start();
 
 // Listen to events
 db.on('healthChanged', ({ healthy }) => {
   console.log(`Database is ${healthy ? 'healthy' : 'unhealthy'}`);
 });
+
+// Reconfigure at runtime
+await db.configure({
+  connectionString: 'postgres://localhost/myapp',
+  maxConnections: 50 // Hot-reloaded without restart
+});
 ```
 
 ### Protected Methods to Override
 
-- `_init(config)` - Initialize service with configuration
+- `_configure(newConfig, oldConfig = null)` - Configure service (handles both initial setup and reconfiguration)
 - `_start()` - Start the service
 - `_stop()` - Stop the service
 - `_destroy()` - Clean up resources (optional)
 - `_recover()` - Custom recovery logic (optional)
 - `_healthCheck()` - Return health status (optional)
 
-### Events
+### Service events
+
+ServiceBase emits these events (constants from `$lib/services/service-base/constants.js`):
 
-- `stateChanged` - Service state transitions
-- `healthChanged` - Health status changes
-- `error` - Service errors
+- `EVENT_STATE_CHANGED` - Service state transitions
+- `EVENT_TARGET_STATE_CHANGED` - Target state changes
+- `EVENT_HEALTH_CHANGED` - Health status changes
+- `EVENT_ERROR` - Service errors
+
+```javascript
+import { EVENT_STATE_CHANGED } from '$lib/services/service-base/constants.js';
+
+service.on(EVENT_STATE_CHANGED, ({ state, previousState }) => {
+  console.log(`Service transitioned from ${previousState} to ${state}`);
+});
+```
 
 ## ServiceManager
 
@@ -100,11 +158,13 @@ Manages multiple services with dependency resolution and coordinated lifecycle o
 - Health monitoring for all services
 - Centralized logging control
 - Service recovery management
+- Plugin system for extending configuration resolution
 
 ### Usage
 
 ```javascript
 import { ServiceManager } from '$hklib-core/services/index.js';
+
 import DatabaseService from './services/DatabaseService.js';
 import AuthService from './services/AuthService.js';
 
@@ -118,11 +178,16 @@ manager.register('database', DatabaseService, {
   connectionString: 'postgres://localhost/myapp'
 });
 
-manager.register('auth', AuthService, {
-  secret: process.env.JWT_SECRET
-}, {
-  dependencies: ['database'] // auth depends on database
-});
+manager.register(
+  'auth',
+  AuthService,
+  {
+    secret: process.env.JWT_SECRET
+  },
+  {
+    dependencies: ['database'] // auth depends on database
+  }
+);
 
 // Start all services in dependency order
 await manager.startAll();
@@ -137,19 +202,27 @@ await manager.stopAll();
 ### Service Registration
 
 ```javascript
-manager.register(name, ServiceClass, config, options);
+manager.register(name, ServiceClass, serviceConfigOrLabel, options);
 ```
 
 - `name` - Unique service identifier
 - `ServiceClass` - Class extending ServiceBase
-- `config` - Service-specific configuration
+- `serviceConfigOrLabel` - Service configuration object (`Object<string, *>`) or config label string
 - `options.dependencies` - Array of service names this service depends on
+- `options.startupPriority` - Higher priority services start first (default: 0)
 
 ### Health Monitoring
 
 ```javascript
+import {
+  SERVICE_HEALTH_CHANGED,
+  SERVICE_ERROR,
+  SERVICE_STATE_CHANGED,
+  SERVICE_LOG
+} from '$lib/services/service-manager/constants.js';
+
 // Listen for health changes
-manager.on('service:healthChanged', ({ service, healthy }) => {
+manager.on(SERVICE_HEALTH_CHANGED, ({ service, healthy }) => {
   if (!healthy) {
     console.error(`Service ${service} became unhealthy`);
   }
@@ -164,11 +237,20 @@ const systemHealth = await manager.checkHealth();
 
 ### Error Handling and Recovery
 
+### ServiceManager events
+
+ServiceManager emits these events (constants from `$lib/services/service-manager/constants.js`):
+
+- `SERVICE_STATE_CHANGED` - Service state changes
+- `SERVICE_HEALTH_CHANGED` - Service health changes
+- `SERVICE_ERROR` - Service errors
+- `SERVICE_LOG` - Service log messages
+
 ```javascript
 // Listen for service errors
-manager.on('service:error', async ({ service, error }) => {
+manager.on(SERVICE_ERROR, async ({ service, error }) => {
   console.log(`Service ${service} failed:`, error.message);
-  
+
   // Attempt automatic recovery
   await manager.recoverService(service);
 });
@@ -177,24 +259,149 @@ manager.on('service:error', async ({ service, error }) => {
 await manager.recoverService('database');
 ```
 
+## Plugins
+
+ServiceManager supports plugins e.g. to resolve service configurations dynamically.
+
+### ConfigPlugin
+
+The most common plugin for resolving service configuration from a pre-parsed configuration object. Perfect for environment variables, config files, or any structured configuration source.
+
+#### Basic Usage with Environment Variables
+
+```javascript
+import { ServiceManager } from '$lib/services/index.js';
+
+import ConfigPlugin from '$lib/services/manager-plugins/ConfigPlugin.js';
+
+import { getPrivateEnv } from '$lib/util/sveltekit/env-private.js';
+
+// Load and auto-group environment variables
+const envConfig = getPrivateEnv();
+//
+// Example:
+//
+// DATABASE_HOST=localhost
+// DATABASE_PORT=5432
+// DATABASE_NAME=myapp
+// REDIS_HOST=cache-server
+// REDIS_PORT=6379
+// JWT_SECRET=mysecret
+// =>
+// {
+//   database: { host: 'localhost', port: 5432, name: 'myapp' },
+//   redis: { host: 'cache-server', port: 6379 },
+//   jwtSecret: 'mysecret'
+// }
+//
+
+// Create plugin with grouped config
+const configPlugin = new ConfigPlugin(envConfig);
+
+// Attach to ServiceManager
+const manager = new ServiceManager();
+manager.attachPlugin(configPlugin);
+
+// Register services with config labels (not config objects)
+manager.register('database', DatabaseService, 'database'); // Uses envConfig.database
+manager.register('cache', RedisService, 'redis'); // Uses envConfig.redis
+
+await manager.startAll();
+```
+
+#### Configuration
+
+The plugin constructor accepts an object with configuration data, which can come from any source. E.g. the environment or a configuration file.
+
+```javascript
+// Combine multiple config sources
+const config = {
+  ...getPrivateEnv(), // Environment variables
+  ...(await loadConfigFile()), // Config file
+  database: {
+    // Override specific settings
+    ...envConfig.database,
+    connectionTimeout: 5000
+  }
+};
+
+const plugin = new ConfigPlugin(config);
+```
+
+### Methods
+
+```javascript
+// Replace all configurations and clean up unused ones
+await configPlugin.replaceAllConfigs(newConfig);
+
+// Replace configuration for a specific label
+await configPlugin.replaceConfig('database', newDatabaseConfig);
+
+// Clean up configurations not used by any service
+await configPlugin.cleanupConfigs();
+```
+
+### Live Configuration Updates
+
+The ConfigPlugin supports pushing configuration updates to running services:
+
+```javascript
+// Replace config for a specific label and notify all affected services
+const updatedServices = await configPlugin.replaceConfig('database', {
+  host: 'new-host.example.com',
+  port: 5433,
+  maxConnections: 50
+});
+
+// Returns array of service names that were updated: ['user-service', 'order-service']
+console.log(`Updated ${updatedServices.length} services`);
+```
+
+#### Service Requirements for Live Updates
+
+For services to support live configuration updates, they must:
+
+1. **Implement intelligent `_configure()` logic** that can handle both initial setup and reconfiguration
+2. **Check for meaningful changes** between old and new config
+3. **Apply changes without full restart** when possible
+
+```javascript
+class DatabaseService extends ServiceBase {
+  // eslint-disable-next-line no-unused-vars
+  async _configure(newConfig, oldConfig = null) {
+    if (!oldConfig) {
+      // Initial configuration
+      this.connectionString = newConfig.connectionString;
+      this.maxConnections = newConfig.maxConnections || 10;
+      return;
+    }
+
+    // Live reconfiguration - handle changes intelligently
+    if (oldConfig.connectionString !== newConfig.connectionString) {
+      // Connection changed - need to reconnect
+      await this.connection?.close();
+      this.connectionString = newConfig.connectionString;
+
+      if (this.state === 'running') {
+        this.connection = await createConnection(this.connectionString);
+      }
+    }
+
+    if (oldConfig.maxConnections !== newConfig.maxConnections) {
+      // Pool size changed - update without reconnect
+      this.maxConnections = newConfig.maxConnections;
+      await this.connection?.setMaxConnections(this.maxConnections);
+    }
+  }
+}
+```
+
 ## Best Practices
 
 1. **Always extend ServiceBase** for consistent lifecycle management
-2. **Keep initialization lightweight** - heavy work should be in `_start()`
+2. **Keep configuration lightweight** - heavy work should be in `_start()`
 3. **Implement proper cleanup** in `_stop()` to prevent resource leaks
 4. **Use health checks** for monitoring critical service functionality
 5. **Declare dependencies explicitly** when registering with ServiceManager
 6. **Handle errors gracefully** and implement recovery where appropriate
 7. **Use descriptive service names** for better logging and debugging
-
-## Testing
-
-Services include comprehensive test suites demonstrating:
-
-- Lifecycle state transitions
-- Error handling and recovery
-- Dependency resolution
-- Health monitoring
-- Event emission
-
-Run tests with your project's test command to ensure service reliability.

package/dist/services/manager-plugins/ConfigPlugin.d.ts

@@ -0,0 +1,68 @@
+/** @typedef {import('../service-manager/typedef.js').ServiceEntry} ServiceEntry */
+/**
+ * Plugin that resolves service configuration from a configuration object
+ */
+export default class ConfigPlugin {
+    /**
+     * Create a new object configuration plugin
+     *
+     * @param {Object<string, *>} allConfigs - Pre-parsed configuration object
+     */
+    constructor(allConfigs: {
+        [x: string]: any;
+    });
+    /** @type {string} */
+    name: string;
+    /** @type {import('../service-manager/ServiceManager.js').ServiceManager|null} */
+    manager: import("../service-manager/ServiceManager.js").ServiceManager | null;
+    /** @type {Object<string, *>} */
+    allConfigs: {
+        [x: string]: any;
+    };
+    /**
+     * Resolve service configuration from the configuration object
+     *
+     * @param {string} serviceName
+     * @param {ServiceEntry} serviceEntry - Service registration entry
+     * @param {*} currentConfig
+     *   Current config (could be object from previous plugins)
+     *
+     * @returns {Promise<Object|undefined>}
+     *   Resolved config object, or undefined to use currentConfig as-is
+     */
+    resolveServiceConfig(serviceName: string, serviceEntry: ServiceEntry, currentConfig: any): Promise<any | undefined>;
+    /**
+     * Replace the entire configuration object and clean up unused configs
+     *
+     * @param {Object<string, *>} newConfigObject - New configuration object
+     */
+    replaceAllConfigs(newConfigObject: {
+        [x: string]: any;
+    }): Promise<void>;
+    /**
+     * Replace a config for a specific label and push to affected services
+     *
+     * @param {string} configLabel - Config label to update
+     * @param {*} newConfig - New configuration value
+     *
+     * @returns {Promise<string[]>} Array of service names that were updated
+     */
+    replaceConfig(configLabel: string, newConfig: any): Promise<string[]>;
+    /**
+     * Remove all unused configurations (configs not referenced by any service)
+     */
+    cleanupConfigs(): Promise<void>;
+    /**
+     * Attach plugin to ServiceManager
+     *
+     * @param {import('../service-manager/ServiceManager.js').ServiceManager} manager
+     *   ServiceManager instance
+     */
+    attach(manager: import("../service-manager/ServiceManager.js").ServiceManager): void;
+    /**
+     * Detach plugin from ServiceManager
+     */
+    detach(): void;
+    #private;
+}
+export type ServiceEntry = import("../service-manager/typedef.js").ServiceEntry;