@hkdigital/lib-core 0.4.18 → 0.4.20

package/dist/services/manager-plugins/ConfigPlugin.js

@@ -0,0 +1,329 @@
+/**
+ * @fileoverview Object-based configuration plugin for ServiceManager
+ *
+ * Resolves service configuration from a pre-provided configuration object
+ * using config labels that map to object properties or prefixed keys.
+ *
+ * @example
+ * // Basic usage with config object
+ * import ConfigPlugin from './ConfigPlugin.js';
+ *
+ * const allConfigs = {
+ *   'database': { host: 'localhost', port: 5432 },
+ *   'auth': { secret: 'my-secret', algorithm: 'HS256' }
+ * };
+ *
+ * const objectPlugin = new ConfigPlugin(allConfigs);
+ * manager.attachPlugin(objectPlugin);
+ *
+ * @example
+ * // With environment variables using utility
+ * import { allEnv } from '../../util/sveltekit/env.js';
+ * import ConfigPlugin from './ConfigPlugin.js';
+ *
+ * const envConfig = await allEnv();
+ * const envPlugin = new ConfigPlugin(envConfig, {
+ *   prefixMap: {
+ *     'database': 'DATABASE',
+ *     'auth': 'JWT'
+ *   }
+ * });
+ *
+ * @example
+ * // Mixed configuration sources
+ * const mixedConfig = {
+ *   ...await allEnv(),
+ *   'custom-service': { specialOption: true },
+ *   'override-service': { host: 'custom-host' }
+ * };
+ * const mixedPlugin = new ConfigPlugin(mixedConfig);
+ */
+
+import { SERVICE_STATE_CHANGED } from '../service-manager/constants.js';
+
+/** @typedef {import('../service-manager/typedef.js').ServiceEntry} ServiceEntry */
+
+/**
+ * Plugin that resolves service configuration from a configuration object
+ */
+export default class ConfigPlugin {
+  /** @type {Map<string, *>} */
+  #pendingConfigUpdates;
+
+  /**
+   * Create a new object configuration plugin
+   *
+   * @param {Object<string, *>} allConfigs - Pre-parsed configuration object
+   */
+  constructor(allConfigs) {
+    /** @type {string} */
+    this.name = 'object-config';
+
+    /** @type {import('../service-manager/ServiceManager.js').ServiceManager|null} */
+    this.manager = null;
+
+    /** @type {Object<string, *>} */
+    this.allConfigs = allConfigs || {};
+
+    this.#pendingConfigUpdates = new Map();
+  }
+
+  /**
+   * 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
+   */
+  // eslint-disable-next-line no-unused-vars
+  async resolveServiceConfig(serviceName, serviceEntry, currentConfig) {
+    const configLabel = serviceEntry.serviceConfigOrLabel;
+
+    if (typeof configLabel !== 'string') {
+      // Expected config label
+      return undefined;
+    }
+
+    // Simple object lookup
+    const config = this.allConfigs[configLabel];
+
+    if (config !== undefined) {
+      this.manager?.logger?.debug(
+        `Resolved object config for '${serviceName}' (label: ${configLabel})`,
+        {
+          configKeys:
+            typeof config === 'object' ? Object.keys(config) : 'primitive'
+        }
+      );
+    }
+
+    return config;
+  }
+
+  /**
+   * Replace the entire configuration object and clean up unused configs
+   *
+   * @param {Object<string, *>} newConfigObject - New configuration object
+   */
+  async replaceAllConfigs(newConfigObject) {
+    await this.cleanupConfigs();
+
+    // Apply new configs to all services that have config labels
+    const updatedServices = [];
+    for (const [configLabel, newConfig] of Object.entries(
+      newConfigObject || {}
+    )) {
+      const services = await this.replaceConfig(configLabel, newConfig);
+      updatedServices.push(...services);
+    }
+
+    this.manager?.logger?.debug(
+      `Replaced all configurations, updated ${updatedServices.length} services`
+    );
+  }
+
+  /**
+   * 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
+   */
+  async replaceConfig(configLabel, newConfig) {
+    // Update the config object
+    this.allConfigs[configLabel] = newConfig;
+
+    // Store as pending update
+    this.#pendingConfigUpdates.set(configLabel, newConfig);
+
+    const updatedServices = [];
+
+    // Find all services using this config label using helper function
+    const servicesByLabel = this.#servicesByConfigLabel();
+    const serviceNames = servicesByLabel.get(configLabel) || [];
+
+    for (const serviceName of serviceNames) {
+      const serviceEntry = this.manager.services.get(serviceName);
+      if (serviceEntry && serviceEntry.instance) {
+        try {
+          // Try to apply config - ServiceBase.configure() will handle state validation
+          await this.#applyConfigToService(
+            serviceName,
+            serviceEntry,
+            newConfig
+          );
+          updatedServices.push(serviceName);
+
+          // Remove from pending since it was applied
+          this.#pendingConfigUpdates.delete(configLabel);
+        } catch (error) {
+          // If configure() fails due to invalid state, it will be retried later
+          this.manager.logger.debug(
+            `Could not update config for service '${serviceName}' (${error.message}), will retry when service state allows`
+          );
+        }
+      }
+    }
+
+    this.manager.logger.debug(
+      `Config label '${configLabel}' updated, applied to ${updatedServices.length} services immediately`
+    );
+
+    return updatedServices;
+  }
+
+  /**
+   * Get services organized by their config labels
+   *
+   * @returns {Map<string, string[]>}
+   *   Map where keys are config labels and values are arrays of service names
+   */
+  #servicesByConfigLabel() {
+    const servicesByLabel = new Map();
+
+    for (const [serviceName, serviceEntry] of this.manager.services) {
+      const configLabel = serviceEntry.serviceConfigOrLabel;
+
+      if (typeof configLabel === 'string') {
+        if (!servicesByLabel.has(configLabel)) {
+          servicesByLabel.set(configLabel, []);
+        }
+
+        servicesByLabel.get(configLabel).push(serviceName);
+      }
+    }
+
+    return servicesByLabel;
+  }
+
+  /**
+   * Remove all unused configurations (configs not referenced by any service)
+   */
+  async cleanupConfigs() {
+    const usedConfigLabels = new Set();
+
+    // Collect all config labels used by registered services
+    for (const [, serviceEntry] of this.manager.services) {
+      const configLabel = serviceEntry.serviceConfigOrLabel;
+
+      if (typeof configLabel === 'string') {
+        usedConfigLabels.add(configLabel);
+      }
+    }
+
+    // Remove configs that aren't used by any service
+    const configKeys = Object.keys(this.allConfigs);
+    let removedCount = 0;
+
+    for (const key of configKeys) {
+      if (!usedConfigLabels.has(key)) {
+        delete this.allConfigs[key];
+        removedCount++;
+      }
+    }
+
+    this.manager?.logger?.debug(
+      `Cleaned up ${removedCount} unused configurations`
+    );
+  }
+
+  /**
+   * Apply configuration to a specific service
+   *
+   * @param {string} serviceName - Name of the service
+   * @param {import('../service-manager/typedef.js').ServiceEntry} serviceEntry
+   *   Service entry from manager
+   * @param {*} newConfig - New configuration to apply
+   */
+  async #applyConfigToService(serviceName, serviceEntry, newConfig) {
+    await serviceEntry.instance.configure(newConfig);
+
+    this.manager.logger.info(`Updated config for service '${serviceName}'`);
+  }
+
+  /**
+   * Process pending config updates for services that can now be configured
+   *
+   * @param {string} serviceName - Name of the service that changed state
+   * @param {import('../service-base/ServiceBase.js').default} serviceInstance
+   *   Service instance
+   */
+  async #processPendingUpdates(serviceName, serviceInstance) {
+    const serviceEntry = this.manager.services.get(serviceName);
+
+    const configLabel = serviceEntry?.serviceConfigOrLabel;
+
+    if (typeof configLabel !== 'string') {
+      return;
+    }
+
+    if (this.#pendingConfigUpdates.has(configLabel)) {
+      const pendingConfig = this.#pendingConfigUpdates.get(configLabel);
+
+      try {
+        await this.#applyConfigToService(
+          serviceName,
+          serviceEntry,
+          pendingConfig
+        );
+        this.#pendingConfigUpdates.delete(configLabel);
+
+        this.manager.logger.info(
+          `Applied pending config update for service '${serviceName}' (label: ${configLabel})`
+        );
+      } catch (error) {
+        this.manager.logger.debug(
+          `Could not apply pending config for service '${serviceName}': ${error.message}`
+        );
+      }
+    }
+  }
+
+  /**
+   * Attach plugin to ServiceManager
+   *
+   * @param {import('../service-manager/ServiceManager.js').ServiceManager} manager
+   *   ServiceManager instance
+   */
+  attach(manager) {
+    if (this.manager) {
+      throw new Error(
+        `Plugin '${this.name}' is already attached to a ServiceManager`
+      );
+    }
+
+    this.manager = manager;
+
+    const configKeys = Object.keys(this.allConfigs).length;
+
+    this.manager.logger.info(
+      `ConfigPlugin attached with ${configKeys} config keys`
+    );
+
+    // Listen for service state changes to process pending updates
+    this.manager.on(
+      SERVICE_STATE_CHANGED,
+      async ({ service, state, instance }) => {
+        await this.#processPendingUpdates(service, instance);
+      }
+    );
+  }
+
+  /**
+   * Detach plugin from ServiceManager
+   */
+  detach() {
+    if (this.manager) {
+      // Clear pending updates
+      this.#pendingConfigUpdates.clear();
+
+      this.manager.logger.info('ConfigPlugin detached');
+      this.manager = null;
+    }
+  }
+}

package/dist/services/service-base/ServiceBase.d.ts

@@ -1,8 +1,7 @@
 /**
- * @typedef {import('./typedef.js').ServiceOptions} ServiceOptions
- * @typedef {import('./typedef.js').StopOptions} StopOptions
- * @typedef {import('./typedef.js').HealthStatus} HealthStatus
+ * @typedef {import('./typedef.js').ServiceState} ServiceState
  * @typedef {import('./typedef.js').StateChangeEvent} StateChangeEvent
+ * @typedef {import('./typedef.js').TargetStateChangeEvent} TargetStateChangeEvent
  * @typedef {import('./typedef.js').HealthChangeEvent} HealthChangeEvent
  * @typedef {import('./typedef.js').ServiceErrorEvent} ServiceErrorEvent
  */
@@ -15,13 +14,15 @@ export class ServiceBase extends EventEmitter {
      * Create a new service instance
      *
      * @param {string} name - Service name
-     * @param {ServiceOptions} [options={}] - Service options
+     * @param {import('./typedef.js').ServiceOptions} [options={}] - Service options
      */
-    constructor(name: string, options?: ServiceOptions);
+    constructor(name: string, options?: import("./typedef.js").ServiceOptions);
     /** @type {string} */
     name: string;
-    /** @type {string} */
-    state: string;
+    /** @type {ServiceState} */
+    state: ServiceState;
+    /** @type {ServiceState} */
+    targetState: ServiceState;
     /** @type {boolean} */
     healthy: boolean;
     /** @type {Error|null} */
@@ -31,13 +32,13 @@ export class ServiceBase extends EventEmitter {
     /** @private @type {number} */
     private _shutdownTimeout;
     /**
-     * Initialize the service with configuration
+     * Configure the service with configuration
      *
      * @param {*} [config={}] - Service-specific configuration
      *
-     * @returns {Promise<boolean>} True if initialization succeeded
+     * @returns {Promise<boolean>} True if configuration succeeded
      */
-    initialize(config?: any): Promise<boolean>;
+    configure(config?: any): Promise<boolean>;
     /**
      * Start the service
      *
@@ -47,11 +48,11 @@ export class ServiceBase extends EventEmitter {
     /**
      * Stop the service with optional timeout
      *
-     * @param {StopOptions} [options={}] - Stop options
+     * @param {import('./typedef.js').StopOptions} [options={}] - Stop options
      *
      * @returns {Promise<boolean>} True if the service stopped successfully
      */
-    stop(options?: StopOptions): Promise<boolean>;
+    stop(options?: import("./typedef.js").StopOptions): Promise<boolean>;
     /**
      * Recover the service from error state
      *
@@ -67,9 +68,10 @@ export class ServiceBase extends EventEmitter {
     /**
      * Get the current health status of the service
      *
-     * @returns {Promise<HealthStatus>} Health status object
+     * @returns {Promise<import('./typedef.js').HealthStatus>}
+     *   Health status object
      */
-    getHealth(): Promise<HealthStatus>;
+    getHealth(): Promise<import("./typedef.js").HealthStatus>;
     /**
      * Set the service log level
      *
@@ -79,14 +81,38 @@ export class ServiceBase extends EventEmitter {
      */
     setLogLevel(level: string): boolean;
     /**
-     * Initialize the service (override in subclass)
+     * Configure the service (handles both initial config and reconfiguration)
      *
      * @protected
-     * @param {*} config - Service configuration
+     * @param {any} newConfig - Configuration to apply
+     * @param {any} [oldConfig=null] - Previous config (null = initial setup)
      *
      * @returns {Promise<void>}
-     */
-    protected _init(config: any): Promise<void>;
+     *
+     * @remarks
+     * This method is called both for initial setup and reconfiguration.
+     * When oldConfig is provided, you should:
+     * 1. Compare oldConfig vs newConfig to determine changes
+     * 2. Clean up resources that need replacing
+     * 3. Apply only the changes that are necessary
+     * 4. Preserve resources that don't need changing
+     *
+     * @example
+     * async _configure(newConfig, oldConfig = null) {
+     *   if (!oldConfig) {
+     *     // Initial setup
+     *     this.connection = new Connection(newConfig.url);
+     *     return;
+     *   }
+     *
+     *   // Reconfiguration
+     *   if (oldConfig.url !== newConfig.url) {
+     *     await this.connection.close();
+     *     this.connection = new Connection(newConfig.url);
+     *   }
+     * }
+     */
+    protected _configure(newConfig: any, oldConfig?: any): Promise<void>;
     /**
      * Start the service (override in subclass)
      *
@@ -131,14 +157,24 @@ export class ServiceBase extends EventEmitter {
      * Set the service state and emit event
      *
      * @private
-     * @param {string} newState - New state value
+     * @param {ServiceState} newState - New state value
+     * @emits {StateChangeEvent} EVENT_STATE_CHANGED
      */
     private _setState;
+    /**
+     * Set the service target state and emit event
+     *
+     * @private
+     * @param {ServiceState} newTargetState - New target state value
+     * @emits {TargetStateChangeEvent} EVENT_TARGET_STATE_CHANGED
+     */
+    private _setTargetState;
     /**
      * Set the health status and emit event if changed
      *
      * @private
      * @param {boolean} healthy - New health status
+     * @emits {HealthChangeEvent} EVENT_HEALTH_CHANGED
      */
     private _setHealthy;
     /**
@@ -147,14 +183,15 @@ export class ServiceBase extends EventEmitter {
      * @private
      * @param {string} operation - Operation that failed
      * @param {Error} error - Error that occurred
+     * @emits {ServiceErrorEvent} EVENT_ERROR
      */
     private _setError;
+    #private;
 }
 export default ServiceBase;
-export type ServiceOptions = import("./typedef.js").ServiceOptions;
-export type StopOptions = import("./typedef.js").StopOptions;
-export type HealthStatus = import("./typedef.js").HealthStatus;
+export type ServiceState = import("./typedef.js").ServiceState;
 export type StateChangeEvent = import("./typedef.js").StateChangeEvent;
+export type TargetStateChangeEvent = import("./typedef.js").TargetStateChangeEvent;
 export type HealthChangeEvent = import("./typedef.js").HealthChangeEvent;
 export type ServiceErrorEvent = import("./typedef.js").ServiceErrorEvent;
 import { EventEmitter } from '../../generic/events.js';