vrack2-core 0.0.1 → 1.0.1

package/docs/Structure.md

@@ -0,0 +1,148 @@
+
+# Структура приложения
+
+## 1. Базовые требования для запуска
+
+Минимальный набор для запуска сервиса:
+- [Файл запуска](#2-файл-запуска)
+- [Файловая структура](#3-файловая-структура)
+- [Файл сервиса](#4-файл-сервиса)
+
+
+## 2. Файл запуска
+
+Репозиторий VRack2 является минимально настроенной готовой структурой для запуска сервиса на VRack2 Core. В VRack2 есть возможность запустить любой файл сервиса указав его после команды запуска:
+
+Пример команды для запуска вашего файла сервиса:
+
+```bash
+npm run start "./devices/youvendor/service.json"
+```
+
+Таким образом можно запустить ваш файл сервиса без запуска VRack2. Вы можете сами написать или скопировать файл запуска из VRack2, но в таком случае вам  необходимо будет создать нужные папки и правильно указать параметры запуска сервиса в package.json. 
+
+Рекомендуется ознакомится с оригинальным файлом запуска. Он позволяет не только запускать любой файл сервиса, но и так же запускать воркеры которые являются так же сервисами VRack2 Core.
+
+Ниже приведена упращенная **последовательность выполнения:**
+
+ 1. Получение/формирование файла структуры сервиса
+ 2. Инициализация класса `MainProcess` - Упращает последовательность инициализации классов `Container` и `Bootstrap`. Это очень важно, потому что там используется сложная последовательность и линковка между друг другом. 
+ 3. Инициализаця класса `Container` - Будет вмещать в себя все устройства/связи создавая их по списку файла структуры,  а так же принимать все события внутри устройств
+ 4. Запуск `MainProcess.run()`
+ 5. Загрузка и запуск `Bootstrap` классов (это вспомогательные классы которые расширяют возможности устройств сервиса)
+    1. `DeviceManager` - Класс работы с устройствами (группы/устройства/инициализация/информация)
+    2. `DeviceStorage` - Класс обеспечивает сохрание и восстановление личных данных компонента (устройства)
+    3. `StructureStorage` - Класс для работы со структурой сервиса
+    4. `DeviceMetrics` - Класс для приема и обработки метрик устройств
+ 6. Запуск сервиса `Container.init()`
+    1. Инициализация устройств
+    2. Добавление соединений
+    3. Запуск процессов устройств
+
+
+## 3. Файловая структура
+
+Общая структура файлов проекта выглядит так:
+
+```
+devices/            # ! Необходимо создать (директория вендоров устройств)
+   {vendor}/        # Директория вендора (например, "vrack2")
+      {Device}      # Файл устройства (например, "Master")
+      list.json     # Файл регистрации устройств
+storage/            # ! Необходимо создать (файлы хранилища устройств)
+   {ContainerID}/   # Идентификатор контейнера (создается автоматически)
+      {DeviceName}  # Файл данных устройства (формат: JSON) (создается при сохранении данных внутри устройства)
+structure/          # ! Необходимо создать (файлы структур контейнеров)
+  {ContainerID}     # Файл структуры (формат: JSON) (создается автоматически)
+```
+
+### Организация устройств  
+
+Устройства располагаются в иерархии вендоров внутри директории `devices/`. Каждый вендор представляет собой отдельный модуль (возможно, отдельный репозиторий), что обеспечивает:  
+
+- Четкое разделение зависимостей между вендорами  
+- Независимую версию и обновление компонентов  
+- Возможность включать в состав вендора дополнительные файлы (конфигурации, package.json и т.д.)  
+
+**Структура пути к устройству:**  
+```
+devices/
+   {vendor}/       # Директория вендора (например, "vrack2")
+      {Device}      # Файл устройства (например, "Master")
+      list.json     # Файл регистрации устройств
+```
+
+#### Регистрация устройств  
+
+Для подключения устройств к системе необходимо зарегистрировать их в файле `list.json`. Поддерживается два формата:  
+
+1. **Простой массив** (для устройств в корне вендора):  
+```json
+["Device1", "Device2"]
+```
+
+2. **Объект с путями** (для сложной структуры, как в VRack2):  
+```json
+{
+  "Master": "devices/Master",
+  "Interval": "devices/Interval",
+  "System": "devices/System"
+}
+```
+
+**Важно:**  
+- Имена устройств всегда пишутся с заглавной буквы (прим. DeviceName)  
+- Пути указываются относительно директории вендора  
+
+#### Пример из VRack2  
+
+В VRack2 устройства пишуться на TypeScript и являются отдельным репозиторием. Поэтому исходные тексты лежать в директории `devices/vrack2/src` которые  компилируются в JavaScript в директорию `devices/vrack2/devices`.
+  
+```
+devices/
+  vrack2/
+    devices/       # Основная директория устройств
+      Master       # Пример устройства
+      System
+    list.json      # Содержит mapping устройств
+```
+
+### Хранилище устройств
+
+Устройства могут сохранять свое состояние в персистентное хранилище. Данные автоматически восстанавливаются при запуске устройства. 
+
+**Требования:**
+- Директория `storage/` должна быть создана вручную
+- Поддиректории и файлы создаются автоматически при сохранении данных
+
+**Структура хранилища:**
+```
+storage/
+  {ContainerID}/  # Идентификатор контейнера (создается автоматически)
+    {DeviceName}  # Файл данных устройства (формат: JSON)
+```
+
+### Хранилище структур контейнеров
+
+При загрузке контейнера - `StructureStorage`  автоматически сохраняет полную структурную информацию которая формируется в контейнере.
+
+**Структура содержит:**
+ - Полную информацию о самом устройстве без его конфигурации из файла сервиса
+ - Все соединения
+ - Визуальные параметры (цвета, расположение)
+
+**Требования:**
+- Директория `structure/` создается вручную
+- Файлы обновляются автоматически при изменениях
+
+**Расположение файлов:**
+```
+structure/
+  {ContainerID}  # Файл структуры (формат: JSON)
+```
+
+## 4. Файл сервиса
+
+Файл сервсиа лучше всего расположить внутри вашего основного репозитория с устройствами. В VRack2 так и сделано - файл сервиса расположен в репозитории устройств VRack2 `devices/vrack2/service.json`.
+
+Таким образом можно использовать один и тот же файл запуска для разных сервисов, в том числе и совместно с VRack2 без использования VRack2.

package/lib/Bootstrap.d.ts

@@ -0,0 +1,79 @@
+import BootClass from './boot/BootClass';
+import Container from './Container';
+/**
+ * Defines a list of bootstrap classes to load
+ *
+ * {
+ *   'ClassID': {
+ *      path: 'importclass.path',
+ *      options: {}
+ *    }
+ * }
+*/
+export interface IBootListConfig {
+    [key: string]: {
+        /** VRack-style bootclass path */
+        path: string;
+        /** Options for this bootclass */
+        options: {
+            [key: string]: any;
+        };
+    };
+}
+/**
+ * Bootstrap is a class for running bootclasses,
+ * which should work above Container and is required
+ * for Container to work.
+ *
+ * For example DeviceManager class - it is
+ * necessary for Container to work but it must be
+ * replaceable and customizable.
+ *
+ * Bootstrap handles the loading of DeviceManager and
+ * provides the ability to work with it from Container.
+ * Bootclasses are a forced exception.
+ *
+ * This is the minimum code that is needed to do everything
+ * else in the style of VRack service.
+ *
+*/
+export default class Bootstrap {
+    /**
+     * Loaded class list
+     *
+     * ```ts
+     * { UniqueID: Classinstance }
+     * ```
+    */
+    protected loaded: {
+        [key: string]: BootClass;
+    };
+    /**
+     * List of downloadable classes and their settings
+     *
+     * @see IBootListConfig
+    */
+    protected config: IBootListConfig;
+    constructor(config: IBootListConfig);
+    /**
+     * Load bootclasses
+     *
+     * Bootclass has some analogy to devices within VRack services.
+     * They also have options, process, processPromise methods similar to devices
+     *
+     * @param Container Container for which loading is performed
+    */
+    loadBootList(Container: Container): Promise<void>;
+    /**
+     * Getting an initialized class
+     *
+     * @example
+     * ```ts
+     * this.Container.Bootstrap.getBootClass('DeviceMetrics', DeviceMetrics) as DeviceMetrics
+     * ```
+     *
+     * @param id class identifier that was specified in the list
+     * @param cs Class to be compared with when receiving
+    */
+    getBootClass(id: string, cs: any): any;
+}

package/lib/Bootstrap.js

@@ -0,0 +1,103 @@
+"use strict";
+/*
+ * Copyright © 2024 Boris Bobylev. All rights reserved.
+ * Licensed under the Apache License, Version 2.0
+*/
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const _1 = require(".");
+const BootClass_1 = __importDefault(require("./boot/BootClass"));
+const ImportManager_1 = __importDefault(require("./ImportManager"));
+_1.ErrorManager.register('Bootstrap', 'yNHeX5fwDH5P', 'BTSP_CLASS_ID_NOT_FOUND', 'Bootstrap class id not found', {
+    id: _1.Rule.string().description('Class identify')
+});
+_1.ErrorManager.register('Bootstrap', 'ack6kwHSBtcf', 'BTSP_INSTANCE_OF_INCORRECT', 'Bootstrap class id is not a class defined by check', {
+    id: _1.Rule.string().description('Class identify')
+});
+_1.ErrorManager.register('Bootstrap', 'DMloqbZG9J36', 'BTSP_MUST_BE_BOOTCLASS', 'The class must be inherited from BootClass', {
+    path: _1.Rule.string().description('Class path')
+});
+/**
+ * Bootstrap is a class for running bootclasses,
+ * which should work above Container and is required
+ * for Container to work.
+ *
+ * For example DeviceManager class - it is
+ * necessary for Container to work but it must be
+ * replaceable and customizable.
+ *
+ * Bootstrap handles the loading of DeviceManager and
+ * provides the ability to work with it from Container.
+ * Bootclasses are a forced exception.
+ *
+ * This is the minimum code that is needed to do everything
+ * else in the style of VRack service.
+ *
+*/
+class Bootstrap {
+    constructor(config) {
+        /**
+         * Loaded class list
+         *
+         * ```ts
+         * { UniqueID: Classinstance }
+         * ```
+        */
+        this.loaded = {};
+        this.config = config;
+    }
+    /**
+     * Load bootclasses
+     *
+     * Bootclass has some analogy to devices within VRack services.
+     * They also have options, process, processPromise methods similar to devices
+     *
+     * @param Container Container for which loading is performed
+    */
+    loadBootList(Container) {
+        return __awaiter(this, void 0, void 0, function* () {
+            for (const cn in this.config) {
+                const conf = this.config[cn];
+                const ExClass = yield ImportManager_1.default.importClass(conf.path);
+                this.loaded[cn] = new ExClass(cn, ImportManager_1.default.importClassName(conf.path), Container, conf.options);
+                if (!(this.loaded[cn] instanceof BootClass_1.default)) {
+                    throw _1.ErrorManager.make('BTSP_INSTANCE_OF_INCORRECT', { path: conf.path });
+                }
+            }
+            for (const bc in this.loaded)
+                this.loaded[bc].process();
+            for (const bc in this.loaded)
+                yield this.loaded[bc].processPromise();
+        });
+    }
+    /**
+     * Getting an initialized class
+     *
+     * @example
+     * ```ts
+     * this.Container.Bootstrap.getBootClass('DeviceMetrics', DeviceMetrics) as DeviceMetrics
+     * ```
+     *
+     * @param id class identifier that was specified in the list
+     * @param cs Class to be compared with when receiving
+    */
+    getBootClass(id, cs) {
+        if (!this.loaded[id])
+            throw _1.ErrorManager.make('BTSP_CLASS_ID_NOT_FOUND', { id });
+        if (!(this.loaded[id] instanceof cs))
+            throw _1.ErrorManager.make('BTSP_INSTANCE_OF_INCORRECT', { id });
+        return this.loaded[id];
+    }
+}
+exports.default = Bootstrap;

package/lib/Container.d.ts

@@ -1,29 +1,225 @@
 /// <reference types="node" />
 import EventEmitter from "events";
-import DeviceManager from "./DeviceManager";
 import IServiceStructure from "./IServiceStructure";
 import IStructureDevice from "./IStructureDevice";
 import Device from "./service/Device";
 import BasicAction from "./actions/BasicAction";
 import IPort from "./ports/IPort";
+import IAction from "./actions/IAction";
+import Bootstrap from "./Bootstrap";
+import IMetricSettings from "./metrics/IMetricSettings";
+import BasicMetric from "./metrics/BasicMetric";
+/**
+ * Contains the structure of the service
+ *
+ * Where { DeviceID: DeviceStructure }
+*/
+export interface IContainerStructure {
+    [key: string]: {
+        /** Device ID */
+        id: string;
+        /** Device type like a 'vendor.Device'*/
+        type: string;
+        /** Actions list @see IAction */
+        actions: {
+            [key: string]: IAction;
+        };
+        /** List of ports with their connections  */
+        outputs: {
+            [key: string]: Array<{
+                device: string;
+                port: string;
+            }>;
+        };
+        /** List of ports with their connections  */
+        inputs: {
+            [key: string]: Array<{
+                device: string;
+                port: string;
+            }>;
+        };
+        /** List of all ports on the device */
+        ports: Array<IDeviceStructurePort>;
+        /** A list of device metrics */
+        metrics: {
+            [key: string]: IMetricSettings;
+        };
+        /** Device display settings */
+        settings: {
+            [key: string]: any;
+        };
+        /** Personalized display settings */
+        display?: {
+            header_bg?: string;
+            body_bg?: string;
+            group_bg?: string;
+            is_rotated?: boolean;
+            row?: number;
+            col?: number;
+        };
+    };
+}
+export interface IDeviceStructurePort extends IPort {
+    /** Port ID */
+    port: string;
+    /** Port direct */
+    direct: string;
+}
+/**
+ * Service Load Class. It loads all devices in the list,
+ * establishes connections between them, and performs device startup.
+ *
+ * This class is a bit complicated for a simple description.
+ * It is recommended to familiarize yourself with the source code
+*/
 export default class Container extends EventEmitter {
-    protected config: IServiceStructure;
-    protected DeviceManager: DeviceManager;
-    protected devices: {
+    /** Unique service ID */
+    id: string;
+    /** List of devices in container */
+    devices: {
         [key: string]: Device;
     };
+    /** Parent container if it exists */
+    parent?: Container;
+    /**
+     * Path to extended conf file for init loading
+     * @see fillConfFile()
+     * */
+    confFile?: string;
+    /**
+     * Container bootstrap class
+     *
+     * A different bootstrap class must be created for each container
+    */
+    Bootstrap: Bootstrap;
+    /** inited flag */
+    protected inited: boolean;
+    /** run flag */
+    protected runned: boolean;
+    /**
+     * Service structure config
+     *
+     * @see constructor
+    */
+    protected service: IServiceStructure;
+    /**
+     * List of all device actions
+     *
+     * [deviceID]: { action.name: BasicAction}
+    */
     protected deviceActions: {
         [key: string]: {
             [key: string]: BasicAction;
         };
     };
-    constructor(config: IServiceStructure, dm: DeviceManager);
+    /**
+     * List of all device metrics
+     *
+    */
+    protected deviceMetrics: {
+        [key: string]: {
+            [key: string]: BasicMetric;
+        };
+    };
+    /**
+     * Container structure
+    */
+    protected structure: IContainerStructure;
+    /**
+     * Create container needed service structure & device manager
+     *
+     * @param service Service structure
+     * @param bootstrap Bootstrap class Object
+     *
+     * */
+    constructor(id: string, service: IServiceStructure, Bootstrap: Bootstrap, confFile?: string);
+    /**
+     * Run container
+    */
     run(): Promise<void>;
+    /**
+     * Extends service from config file
+     *
+     * Sometimes there is a need to override the settings of some devices.
+     * To do this, you can use a special configuration file of the service.
+     * It contains the same as the main service file and replaces with its settings
+     * and parameters the settings and parameters of the main service.
+     *
+     * @see init()
+    */
+    protected fillConfFile(): void;
+    /**
+     * Creates device classes. Preprocesses the device,
+     * then adds ports to it and creates connections between ports.
+     *
+     * When adding and creating devices, ports and connections,
+     * the service structure is also created
+     *
+     * 1. Init device
+     * 2. Init individual device connections
+     * 3. Init other connections
+     *
+     * @see structure
+    */
+    init(): Promise<void>;
+    /**
+     * Run process & processPromise of all devices
+    */
+    runProcess(): Promise<void>;
+    /**
+     * Check device action and run him
+     *
+     * @param device Device ID
+     * @param action Device action (as 'action.name')
+     * @param data Data for action
+    */
+    deviceAction(device: string, action: string, data: any): Promise<any>;
+    /**
+     * Return structure
+    */
+    getStructure(): Promise<IContainerStructure>;
+    /**
+     * Init one device
+     *
+     * 1. Make device class object
+     * 2. Fill device options
+     * 3. Run device prepareOptions method
+     * 4. Validating device options
+     * 5. Check device actions
+     * 6. make device inputs ports
+     * 7. make device outputs ports
+     **/
     protected initDevice(dconf: IStructureDevice): Promise<void>;
+    /**
+     * Check device input handler
+     * Make CTR_INPUT_HANDLER_NF error if not exists
+     * @see initDevice make inputPorts
+    */
     protected checkInputHandler(port: string, handler: string, device: Device): void;
-    protected initConnection(conn: string): Promise<void>;
+    /**
+     * Init device connection
+     *
+     * @param conn Device connection string like a "DevID.port -> DevIDTO.port"
+    */
+    protected initConnection(conn: string): void;
+    /**
+     * Container Helper - parse connection string to format object
+     *
+     * @return Connection object
+    */
     private toConnection;
+    /**
+     * Check Port name (strict format a-zA-Z0-9.)
+     *
+     * @param port Port name
+    */
     protected checkPortName(port: string): void;
+    /**
+     * Convert dynamic port to ports list
+     *
+     * @param name Port name with %d symbols
+     * @param iPort IPort object (port settings)
+    */
     protected getPortList(name: string, iPort: IPort): {
         [key: string]: IPort;
     };