@twin.org/engine-core 0.0.2-next.2 → 0.0.2-next.20

package/dist/cjs/index.cjs

@@ -1,9 +1,11 @@
 'use strict';
 
+var node_worker_threads = require('node:worker_threads');
 var core = require('@twin.org/core');
 var entity = require('@twin.org/entity');
 var loggingConnectorConsole = require('@twin.org/logging-connector-console');
 var loggingModels = require('@twin.org/logging-models');
+var loggingService = require('@twin.org/logging-service');
 var modules = require('@twin.org/modules');
 var promises = require('node:fs/promises');
 var path = require('node:path');
@@ -69,13 +71,14 @@ class MemoryStateStorage {
  */
 class EngineCore {
     /**
-     * Name for the engine logger.
+     * Name for the engine logger, used for direct console logging.
      */
-    static LOGGER_TYPE_NAME = "engine";
+    static LOGGING_TYPE_NAME = "engine-logging-service";
     /**
      * Runtime name for the class.
+     * @internal
      */
-    CLASS_NAME = "EngineCore";
+    static _CLASS_NAME = "EngineCore";
     /**
      * The core context.
      */
@@ -86,20 +89,15 @@ class EngineCore {
      */
     _stateStorage;
     /**
-     * The logging connector for the engine.
+     * The logging component for the engine.
      * @internal
      */
-    _engineLoggingConnector;
+    _engineLoggingComponent;
     /**
      * Skip the bootstrap process.
      * @internal
      */
     _skipBootstrap;
-    /**
-     * The logger type name to use.
-     * @internal
-     */
-    _loggerTypeName;
     /**
      * The type initialisers.
      * @internal
@@ -110,6 +108,11 @@ class EngineCore {
      * @internal
      */
     _isStarted;
+    /**
+     * Is the engine a clone.
+     * @internal
+     */
+    _isClone;
     /**
      * Add type initialisers to the engine.
      * @internal
@@ -133,17 +136,17 @@ class EngineCore {
         this._skipBootstrap = options.skipBootstrap ?? false;
         this._populateTypeInitialisers = options.populateTypeInitialisers;
         this._customBootstrap = options.customBootstrap;
-        this._loggerTypeName = options.loggerTypeName ?? EngineCore.LOGGER_TYPE_NAME;
         this._typeInitialisers = [];
         this._context = {
             config: options.config,
-            defaultTypes: {},
+            registeredInstances: {},
             componentInstances: [],
-            state: { componentStates: {} },
+            state: {},
             stateDirty: false
         };
         this._stateStorage = options.stateStorage;
         this._isStarted = false;
+        this._isClone = false;
         if (core.Is.function(this._populateTypeInitialisers)) {
             this._populateTypeInitialisers(this, this._context);
         }
@@ -151,19 +154,27 @@ class EngineCore {
     /**
      * Add a type initialiser.
      * @param type The type to add the initialiser for.
-     * @param typeConfig The type config.
      * @param module The name of the module which contains the initialiser method.
      * @param method The name of the method to call.
      */
-    addTypeInitialiser(type, typeConfig, module, method) {
-        if (!core.Is.empty(typeConfig)) {
-            this._typeInitialisers.push({
-                type,
-                typeConfig,
-                module,
-                method
-            });
-        }
+    addTypeInitialiser(type, module, method) {
+        core.Guards.stringValue(EngineCore._CLASS_NAME, "type", type);
+        core.Guards.stringValue(EngineCore._CLASS_NAME, "module", module);
+        core.Guards.stringValue(EngineCore._CLASS_NAME, "method", method);
+        this._typeInitialisers.push({
+            type,
+            module,
+            method
+        });
+    }
+    /**
+     * Get the type config for a specific type.
+     * @param type The type to get the config for.
+     * @returns The type config or undefined if not found.
+     */
+    getTypeConfig(type) {
+        core.Guards.stringValue(EngineCore._CLASS_NAME, "type", type);
+        return this._context.config.types?.[type];
     }
     /**
      * Start the engine core.
@@ -174,37 +185,30 @@ class EngineCore {
             return false;
         }
         this.setupEngineLogger();
-        this.logInfo(core.I18n.formatMessage("engineCore.starting"));
+        this.logInfo(core.I18n.formatMessage(`${"engineCore"}.starting`));
         if (this._context.config.debug) {
-            this.logInfo(core.I18n.formatMessage("engineCore.debuggingEnabled"));
+            this.logInfo(core.I18n.formatMessage(`${"engineCore"}.debuggingEnabled`));
         }
         let canContinue;
         try {
             canContinue = await this.stateLoad();
             if (canContinue) {
-                for (const { type, typeConfig, module, method } of this._typeInitialisers) {
-                    await this.initialiseTypeConfig(type, typeConfig, module, method);
+                for (const { type, module, method } of this._typeInitialisers) {
+                    await this.initialiseTypeConfig(type, module, method);
                 }
                 await this.bootstrap();
-                this.logInfo(core.I18n.formatMessage("engineCore.componentsStarting"));
+                this.logInfo(core.I18n.formatMessage(`${"engineCore"}.componentsStarting`));
                 for (const instance of this._context.componentInstances) {
                     if (core.Is.function(instance.component.start)) {
-                        const instanceName = this.getInstanceName(instance);
-                        this.logInfo(core.I18n.formatMessage("engineCore.componentStarting", {
+                        this.logInfo(core.I18n.formatMessage(`${"engineCore"}.componentStarting`, {
                             element: instance.instanceType
                         }));
-                        const componentState = this._context.state.componentStates[instanceName] ?? {};
-                        const lastState = core.ObjectHelper.clone(componentState);
-                        await instance.component.start(this._context.state.nodeIdentity, this._loggerTypeName, componentState);
-                        if (!core.ObjectHelper.equal(lastState, componentState)) {
-                            this._context.state.componentStates[instanceName] = componentState;
-                            this._context.stateDirty = true;
-                        }
+                        await instance.component.start(this._context.state.nodeIdentity, EngineCore.LOGGING_TYPE_NAME);
                     }
                 }
-                this.logInfo(core.I18n.formatMessage("engineCore.componentsComplete"));
+                this.logInfo(core.I18n.formatMessage(`${"engineCore"}.componentsComplete`));
             }
-            this.logInfo(core.I18n.formatMessage("engineCore.started"));
+            this.logInfo(core.I18n.formatMessage(`${"engineCore"}.started`));
             this._isStarted = true;
         }
         catch (err) {
@@ -223,39 +227,55 @@ class EngineCore {
      * @returns Nothing.
      */
     async stop() {
-        this.logInfo(core.I18n.formatMessage("engineCore.stopping"));
-        this.logInfo(core.I18n.formatMessage("engineCore.componentsStopping"));
+        this.logInfo(core.I18n.formatMessage(`${"engineCore"}.stopping`));
+        this.logInfo(core.I18n.formatMessage(`${"engineCore"}.componentsStopping`));
         for (const instance of this._context.componentInstances) {
             if (core.Is.function(instance.component.stop)) {
-                const instanceName = this.getInstanceName(instance);
-                const componentState = this._context.state.componentStates[instanceName] ?? {};
-                const lastState = core.ObjectHelper.clone(componentState);
-                this.logInfo(core.I18n.formatMessage("engineCore.componentStopping", { element: instance.instanceType }));
+                this.logInfo(core.I18n.formatMessage(`${"engineCore"}.componentStopping`, {
+                    element: instance.instanceType
+                }));
                 try {
-                    await instance.component.stop(this._context.state.nodeIdentity, this._loggerTypeName, componentState);
-                    if (!core.ObjectHelper.equal(lastState, componentState)) {
-                        this._context.state.componentStates[instanceName] = componentState;
-                        this._context.stateDirty = true;
-                    }
+                    await instance.component.stop(this._context.state.nodeIdentity, EngineCore.LOGGING_TYPE_NAME);
                 }
                 catch (err) {
-                    this.logError(new core.GeneralError(this.CLASS_NAME, "componentStopFailed", {
+                    this.logError(new core.GeneralError(EngineCore._CLASS_NAME, "componentStopFailed", {
                         component: instance.instanceType
                     }, core.BaseError.fromError(err)));
                 }
             }
         }
         await this.stateSave();
-        this.logInfo(core.I18n.formatMessage("engineCore.componentsStopped"));
-        this.logInfo(core.I18n.formatMessage("engineCore.stopped"));
+        this.logInfo(core.I18n.formatMessage(`${"engineCore"}.componentsStopped`));
+        this.logInfo(core.I18n.formatMessage(`${"engineCore"}.stopped`));
+    }
+    /**
+     * Is the engine started.
+     * @returns True if the engine is started.
+     */
+    isStarted() {
+        return this._isStarted;
+    }
+    /**
+     * Is this the primary engine instance.
+     * @returns True if the engine is the primary instance.
+     */
+    isPrimary() {
+        return node_worker_threads.isMainThread && !this._isClone;
+    }
+    /**
+     * Is this engine instance a clone.
+     * @returns True if the engine instance is a clone.
+     */
+    isClone() {
+        return this._isClone;
     }
     /**
      * Log info.
      * @param message The message to log.
      */
     logInfo(message) {
-        this._engineLoggingConnector?.log({
-            source: this.CLASS_NAME,
+        this._engineLoggingComponent?.log({
+            source: EngineCore._CLASS_NAME,
             level: "info",
             message
         });
@@ -273,8 +293,8 @@ class EngineCore {
             if (this._context.config.debug && core.Is.stringValue(formattedError.stack)) {
                 message += `\n${formattedError.stack}`;
             }
-            this._engineLoggingConnector?.log({
-                source: this.CLASS_NAME,
+            this._engineLoggingComponent?.log({
+                source: EngineCore._CLASS_NAME,
                 level: "error",
                 message
             });
@@ -295,11 +315,48 @@ class EngineCore {
         return this._context.state;
     }
     /**
-     * Get the types for the component.
-     * @returns The default types.
+     * Get all the registered instances.
+     * @returns The registered instances.
      */
-    getDefaultTypes() {
-        return this._context.defaultTypes;
+    getRegisteredInstances() {
+        return this._context.registeredInstances;
+    }
+    /**
+     * Get the registered instance type for the component/connector.
+     * @param componentConnectorType The type of the component/connector.
+     * @param features The requested features of the component, if not specified the default entry will be retrieved.
+     * @returns The instance type matching the criteria if one is registered.
+     * @throws If a matching instance was not found.
+     */
+    getRegisteredInstanceType(componentConnectorType, features) {
+        core.Guards.stringValue(EngineCore._CLASS_NAME, "componentConnectorType", componentConnectorType);
+        const registeredType = this.getRegisteredInstanceTypeOptional(componentConnectorType, features);
+        if (!core.Is.stringValue(registeredType)) {
+            throw new core.GeneralError(EngineCore._CLASS_NAME, "instanceTypeNotFound", {
+                type: componentConnectorType,
+                features: (features ?? ["default"]).join(",")
+            });
+        }
+        return registeredType;
+    }
+    /**
+     * Get the registered instance type for the component/connector if it exists.
+     * @param componentConnectorType The type of the component/connector.
+     * @param features The requested features of the component, if not specified the default entry will be retrieved.
+     * @returns The instance type matching the criteria if one is registered.
+     */
+    getRegisteredInstanceTypeOptional(componentConnectorType, features) {
+        let registeredType;
+        const registeredTypes = this._context.registeredInstances[componentConnectorType];
+        if (core.Is.arrayValue(registeredTypes)) {
+            if (core.Is.arrayValue(features)) {
+                registeredType = registeredTypes.find(t => t.features?.every(f => features.includes(f)))?.type;
+            }
+            else {
+                registeredType = registeredTypes[0]?.type;
+            }
+        }
+        return registeredType;
     }
     /**
      * Get the data required to create a clone of the engine.
@@ -315,8 +372,7 @@ class EngineCore {
             config: this._context.config,
             state: this._context.state,
             typeInitialisers: this._typeInitialisers,
-            entitySchemas,
-            loggerTypeName: this._loggerTypeName
+            entitySchemas
         };
         return cloneData;
     }
@@ -326,20 +382,20 @@ class EngineCore {
      * @param silent Should the clone be silent.
      */
     populateClone(cloneData, silent) {
-        core.Guards.object(this.CLASS_NAME, "cloneData", cloneData);
-        core.Guards.object(this.CLASS_NAME, "cloneData.config", cloneData.config);
-        core.Guards.object(this.CLASS_NAME, "cloneData.state", cloneData.state);
-        core.Guards.array(this.CLASS_NAME, "cloneData.typeInitialisers", cloneData.typeInitialisers);
-        this._loggerTypeName = cloneData.loggerTypeName;
+        core.Guards.object(EngineCore._CLASS_NAME, "cloneData", cloneData);
+        core.Guards.object(EngineCore._CLASS_NAME, "cloneData.config", cloneData.config);
+        core.Guards.object(EngineCore._CLASS_NAME, "cloneData.state", cloneData.state);
+        core.Guards.array(EngineCore._CLASS_NAME, "cloneData.typeInitialisers", cloneData.typeInitialisers);
         this._skipBootstrap = true;
+        this._isClone = true;
         if (silent ?? false) {
             cloneData.config.silent = true;
         }
         this._context = {
             config: cloneData.config,
-            defaultTypes: {},
+            registeredInstances: {},
             componentInstances: [],
-            state: { componentStates: {} },
+            state: {},
             stateDirty: false
         };
         this._typeInitialisers = cloneData.typeInitialisers;
@@ -355,14 +411,41 @@ class EngineCore {
      * @param instanceMethod The function to initialise the instance.
      * @internal
      */
-    async initialiseTypeConfig(typeKey, typeConfig, module, method) {
+    async initialiseTypeConfig(typeKey, module, method) {
+        const typeConfig = this._context.config.types?.[typeKey];
         if (core.Is.arrayValue(typeConfig)) {
             const instanceMethod = await modules.ModuleHelper.getModuleEntry(module, method);
             for (let i = 0; i < typeConfig.length; i++) {
-                const instanceType = instanceMethod(this, this._context, typeConfig[i], typeConfig[i].overrideInstanceType);
-                if (core.Is.stringValue(instanceType) &&
-                    (core.Is.empty(this._context.defaultTypes[typeKey]) || typeConfig[i].isDefault)) {
-                    this._context.defaultTypes[typeKey] = instanceType;
+                this.logInfo(core.I18n.formatMessage("engineCore.configuring", {
+                    element: `${typeKey}: ${typeConfig[i].type}`
+                }));
+                const result = await instanceMethod(this, this._context, typeConfig[i]);
+                if (core.Is.stringValue(result.instanceType) && core.Is.object(result.component)) {
+                    const finalInstanceType = typeConfig[i].overrideInstanceType ?? result.instanceType;
+                    this._context.componentInstances.push({
+                        instanceType: finalInstanceType,
+                        component: result.component
+                    });
+                    result.factory?.register(finalInstanceType, () => result.component);
+                    this._context.registeredInstances[typeKey] ??= [];
+                    if (typeConfig[i].isDefault ?? false) {
+                        this._context.registeredInstances[typeKey].unshift({
+                            type: finalInstanceType,
+                            features: typeConfig[i].features
+                        });
+                    }
+                    else {
+                        this._context.registeredInstances[typeKey].push({
+                            type: finalInstanceType,
+                            features: typeConfig[i].features
+                        });
+                    }
+                }
+                else {
+                    throw new core.GeneralError("engineCore", "componentUnknownType", {
+                        type: typeConfig[i].type,
+                        componentType: typeKey
+                    });
                 }
             }
         }
@@ -373,7 +456,7 @@ class EngineCore {
      */
     setupEngineLogger() {
         const silent = this._context.config.silent ?? false;
-        const engineLogger = silent
+        const engineLoggerConnector = silent
             ? new loggingModels.SilentLoggingConnector()
             : new loggingConnectorConsole.ConsoleLoggingConnector({
                 config: {
@@ -382,12 +465,25 @@ class EngineCore {
                 }
             });
         this._context.componentInstances.push({
-            instanceType: this._loggerTypeName,
-            component: engineLogger
+            instanceType: EngineCore.LOGGING_TYPE_NAME,
+            component: engineLoggerConnector
         });
-        loggingModels.LoggingConnectorFactory.register(this._loggerTypeName, () => engineLogger);
-        this._engineLoggingConnector = engineLogger;
-        this._context.defaultTypes.loggingConnector = this._loggerTypeName;
+        loggingModels.LoggingConnectorFactory.register(EngineCore.LOGGING_TYPE_NAME, () => engineLoggerConnector);
+        this._context.registeredInstances.loggingConnector = [
+            {
+                type: EngineCore.LOGGING_TYPE_NAME
+            }
+        ];
+        const engineLoggerComponent = new loggingService.LoggingService({
+            loggingConnectorType: EngineCore.LOGGING_TYPE_NAME
+        });
+        this._engineLoggingComponent = engineLoggerComponent;
+        core.ComponentFactory.register(EngineCore.LOGGING_TYPE_NAME, () => engineLoggerComponent);
+        this._context.registeredInstances.loggingComponent = [
+            {
+                type: EngineCore.LOGGING_TYPE_NAME
+            }
+        ];
     }
     /**
      * Load the state.
@@ -397,10 +493,7 @@ class EngineCore {
     async stateLoad() {
         if (this._stateStorage) {
             try {
-                this._context.state = ((await this._stateStorage.load(this)) ?? {
-                    componentStates: {}
-                });
-                this._context.state.componentStates ??= {};
+                this._context.state = ((await this._stateStorage.load(this)) ?? {});
                 this._context.stateDirty = false;
                 return true;
             }
@@ -436,34 +529,28 @@ class EngineCore {
      */
     async bootstrap() {
         if (!this._skipBootstrap) {
-            this.logInfo(core.I18n.formatMessage("engineCore.bootstrapStarted"));
+            this.logInfo(core.I18n.formatMessage(`${"engineCore"}.bootstrapStarted`));
             // First bootstrap the components.
             for (const instance of this._context.componentInstances) {
                 if (core.Is.function(instance.component.bootstrap)) {
                     const instanceName = this.getInstanceName(instance);
-                    this.logInfo(core.I18n.formatMessage("engineCore.bootstrapping", {
+                    this.logInfo(core.I18n.formatMessage(`${"engineCore"}.bootstrapping`, {
                         element: instanceName
                     }));
-                    const componentState = this._context.state.componentStates[instanceName] ?? {};
-                    const lastState = core.ObjectHelper.clone(componentState);
-                    const bootstrapSuccess = await instance.component.bootstrap(this._loggerTypeName, componentState);
+                    const bootstrapSuccess = await instance.component.bootstrap(EngineCore.LOGGING_TYPE_NAME);
                     // If the bootstrap method failed then throw an error
                     if (!bootstrapSuccess) {
-                        throw new core.GeneralError(this.CLASS_NAME, "bootstrapFailed", {
+                        throw new core.GeneralError(EngineCore._CLASS_NAME, "bootstrapFailed", {
                             component: `${instance.component.CLASS_NAME}:${instance.instanceType}`
                         });
                     }
-                    if (!core.ObjectHelper.equal(lastState, componentState)) {
-                        this._context.state.componentStates[instanceName] = componentState;
-                        this._context.stateDirty = true;
-                    }
                 }
             }
             // Now perform any custom bootstrap operations
             if (core.Is.function(this._customBootstrap)) {
                 await this._customBootstrap(this, this._context);
             }
-            this.logInfo(core.I18n.formatMessage("engineCore.bootstrapComplete"));
+            this.logInfo(core.I18n.formatMessage(`${"engineCore"}.bootstrapComplete`));
         }
     }
     /**
@@ -568,6 +655,51 @@ class FileStateStorage {
     }
 }
 
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Helper class for engine modules.
+ */
+class EngineModuleHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "EngineModuleHelper";
+    /**
+     * Loads an engine component and constructs it with the relevant dependencies and configuration.
+     * @param engineCore The engine core.
+     * @param engineModuleConfig The configuration for the module.
+     * @returns The instantiated component.
+     */
+    static async loadComponent(engineCore, engineModuleConfig) {
+        const moduleClass = await modules.ModuleHelper.getModuleEntry(engineModuleConfig.moduleName, engineModuleConfig.className);
+        const isClass = core.Is.class(moduleClass);
+        if (!isClass) {
+            throw new core.GeneralError(EngineModuleHelper.CLASS_NAME, "moduleNotClass", {
+                moduleName: engineModuleConfig.moduleName,
+                className: engineModuleConfig.className
+            });
+        }
+        const constructorOptions = {};
+        if (core.Is.arrayValue(engineModuleConfig.dependencies)) {
+            for (const dependency of engineModuleConfig.dependencies) {
+                if (dependency.isOptional ?? false) {
+                    constructorOptions[dependency.propertyName] = engineCore.getRegisteredInstanceType(dependency.componentName, dependency.features);
+                }
+                else {
+                    constructorOptions[dependency.propertyName] =
+                        engineCore.getRegisteredInstanceTypeOptional(dependency.componentName, dependency.features);
+                }
+            }
+        }
+        if (core.Is.object(engineModuleConfig.config)) {
+            constructorOptions.config = engineModuleConfig.config;
+        }
+        return new moduleClass(constructorOptions);
+    }
+}
+
 exports.EngineCore = EngineCore;
+exports.EngineModuleHelper = EngineModuleHelper;
 exports.FileStateStorage = FileStateStorage;
 exports.MemoryStateStorage = MemoryStateStorage;