vrack2-core 0.0.1 → 1.0.0

package/lib/boot/BootClass.d.ts

@@ -0,0 +1,93 @@
+import Container from '../Container';
+import BasicType from '../validator/types/BasicType';
+/**
+ * Boot classes are designed to override behavior outside of the container.
+ * They can also extend the container's capabilities.
+ *
+ * Boot classes are similar to devices inside the container,
+ * but they do not fall into it and do not have connections.
+ *
+ * Boot classes are created inside a Bootstrap class.
+ * To do this, you need to create a list of classes and specify them for bootstrapping,
+ *
+ * here is an example of such a list
+ *
+ * ```ts
+ *      DeviceManager: { path: 'vrack2-core.DeviceManager', options: { storageDir: './storage' }},
+ *      DeviceStorage: { path: 'vrack2-core.DeviceFileStorage', options: {} },
+ *      StructureStorage: { path: 'vrack2-core.StructureStorage', options: {} },
+ *      DeviceMetrics: { path: 'vrack2-core.DeviceMetrics', options: {} }
+ * ```
+ * Where:
+ * ```
+ *   [key: string - Unique bootclass identifier] : {
+ *      path: string - Path to bootclass,
+ *      options: {any} - Bootclass settings
+ *   }
+ * ```
+ *
+ * @see DeviceManager For boot class example
+*/
+export default class BootClass {
+    /**
+     * A unique identifier that will be filled in when the class is created within Bootstrap.
+     * Can be used to refer to the class directly
+     *
+     * @example 'DeviceName'
+     * */
+    id: string;
+    /**
+     * The path to a VRack2-style class that will be populated when the class is created inside Bootstrap.
+     * Can be used to determine class membership
+     *
+     * @example 'vrack.KeyManager'
+    */
+    type: string;
+    /**
+     * Container for which Boot classes are loaded
+     * */
+    Container: Container;
+    /**
+     * Boot class parameters that will be passed from the settings of the list of boot classes
+     *
+     * @see checkOptions()
+    */
+    options: {
+        [key: string]: any;
+    };
+    /**
+     * Method returns rules for validation of boot class options
+     *
+     * @example
+     * ```ts
+     *   return {
+     *       keysPath: Rule.string().require().default('./keys.json')
+     *   }
+     * ```
+    */
+    checkOptions(): {
+        [key: string]: BasicType;
+    };
+    /**
+     * @param id Unique ID
+     * @param type Device type string
+     * @param Container Active loader container
+    */
+    constructor(id: string, type: string, Container: Container, options: {
+        [key: string]: any;
+    });
+    /**
+     * The method is the entry point to start the boot class
+    */
+    process(): void;
+    /**
+     * Similar to `process` but asynchronous,
+     * the bootstrap loader will wait for the execution of all
+     * the  `processPromise` methods of all bootstrap classes.
+    */
+    processPromise(): Promise<void>;
+    /**
+     * Method for calling container system errors
+     */
+    error(error: Error): void;
+}

package/lib/boot/BootClass.js

@@ -0,0 +1,101 @@
+"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 Validator_1 = __importDefault(require("../validator/Validator"));
+/**
+ * Boot classes are designed to override behavior outside of the container.
+ * They can also extend the container's capabilities.
+ *
+ * Boot classes are similar to devices inside the container,
+ * but they do not fall into it and do not have connections.
+ *
+ * Boot classes are created inside a Bootstrap class.
+ * To do this, you need to create a list of classes and specify them for bootstrapping,
+ *
+ * here is an example of such a list
+ *
+ * ```ts
+ *      DeviceManager: { path: 'vrack2-core.DeviceManager', options: { storageDir: './storage' }},
+ *      DeviceStorage: { path: 'vrack2-core.DeviceFileStorage', options: {} },
+ *      StructureStorage: { path: 'vrack2-core.StructureStorage', options: {} },
+ *      DeviceMetrics: { path: 'vrack2-core.DeviceMetrics', options: {} }
+ * ```
+ * Where:
+ * ```
+ *   [key: string - Unique bootclass identifier] : {
+ *      path: string - Path to bootclass,
+ *      options: {any} - Bootclass settings
+ *   }
+ * ```
+ *
+ * @see DeviceManager For boot class example
+*/
+class BootClass {
+    /**
+     * Method returns rules for validation of boot class options
+     *
+     * @example
+     * ```ts
+     *   return {
+     *       keysPath: Rule.string().require().default('./keys.json')
+     *   }
+     * ```
+    */
+    checkOptions() {
+        return {};
+    }
+    /**
+     * @param id Unique ID
+     * @param type Device type string
+     * @param Container Active loader container
+    */
+    constructor(id, type, Container, options) {
+        /**
+         * Boot class parameters that will be passed from the settings of the list of boot classes
+         *
+         * @see checkOptions()
+        */
+        this.options = {};
+        this.id = id;
+        this.type = type;
+        this.Container = Container;
+        this.options = options;
+        // Validating
+        const rules = this.checkOptions();
+        Validator_1.default.validate(rules, this.options);
+    }
+    /**
+     * The method is the entry point to start the boot class
+    */
+    process() { return; }
+    /**
+     * Similar to `process` but asynchronous,
+     * the bootstrap loader will wait for the execution of all
+     * the  `processPromise` methods of all bootstrap classes.
+    */
+    processPromise() {
+        return __awaiter(this, void 0, void 0, function* () { return; });
+    }
+    /**
+     * Method for calling container system errors
+     */
+    error(error) {
+        this.Container.emit('system.error', error);
+    }
+}
+exports.default = BootClass;

package/lib/boot/DeviceFileStorage.d.ts

@@ -0,0 +1,38 @@
+import BootClass from "./BootClass";
+import BasicType from "../validator/types/BasicType";
+/**
+ * File storage for devices that are used by default
+ * Uses container events to load and save storage state
+ *
+*/
+export default class DeviceFileStorage extends BootClass {
+    checkOptions(): {
+        [key: string]: BasicType;
+    };
+    process(): void;
+    /**
+     * loading a device storage file
+     * If the primary storage file does not exist, an attempt will be made
+     * to locate the backup temporary storage file.
+     *
+     * @param deviceId Device ID
+     * @returns {any} Imported JSON
+    */
+    loadDeviceStorage(deviceId: string): Promise<any>;
+    /**
+     * Save data device to storage
+     * First, a temporary file is created,
+     * and then the temporary file is copied to the main file
+     *
+     * @param deviceId Device ID
+     * @param trace Data object for storage
+    */
+    saveDeviceStorage(deviceId: string, trace: any): Promise<void>;
+    /**
+     * Forms the path to the storage file
+     *
+     * @param deviceId Device ID
+     * @param prefix Prefix between the device name and its extension
+    */
+    protected makeDeviceStoragePath(deviceId: string, prefix?: string): string;
+}

package/lib/boot/DeviceFileStorage.js

@@ -0,0 +1,112 @@
+"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 path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const ImportManager_1 = __importDefault(require("../ImportManager"));
+const BootClass_1 = __importDefault(require("./BootClass"));
+const Rule_1 = __importDefault(require("../validator/Rule"));
+/**
+ * File storage for devices that are used by default
+ * Uses container events to load and save storage state
+ *
+*/
+class DeviceFileStorage extends BootClass_1.default {
+    checkOptions() {
+        return {
+            storageDir: Rule_1.default.string().require().default('./storage')
+                .description('Dir for storage files')
+        };
+    }
+    process() {
+        if (!ImportManager_1.default.isDir(this.options.storageDir))
+            fs_1.default.mkdirSync(this.options.storageDir, { recursive: true });
+        // Before process load storage data
+        this.Container.on('beforeProcess', () => {
+            for (const id in this.Container.devices) {
+                try {
+                    this.Container.devices[id].storage = this.loadDeviceStorage(id);
+                }
+                catch (error) {
+                    this.Container.emit('system.error', error);
+                }
+            }
+        });
+        // On device save - save storage data
+        this.Container.on('device.save', (data) => {
+            try {
+                this.saveDeviceStorage(data.device, data.trace);
+            }
+            catch (error) {
+                this.Container.emit('system.error', error);
+            }
+        });
+    }
+    /**
+     * loading a device storage file
+     * If the primary storage file does not exist, an attempt will be made
+     * to locate the backup temporary storage file.
+     *
+     * @param deviceId Device ID
+     * @returns {any} Imported JSON
+    */
+    loadDeviceStorage(deviceId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const fp = this.makeDeviceStoragePath(deviceId);
+            const fptmp = this.makeDeviceStoragePath(deviceId, '-tmp');
+            if (!fs_1.default.existsSync(fp)) {
+                if (!fs_1.default.existsSync(fptmp))
+                    return {};
+                fs_1.default.renameSync(fptmp, fp);
+            }
+            return ImportManager_1.default.importJSON(fp);
+        });
+    }
+    /**
+     * Save data device to storage
+     * First, a temporary file is created,
+     * and then the temporary file is copied to the main file
+     *
+     * @param deviceId Device ID
+     * @param trace Data object for storage
+    */
+    saveDeviceStorage(deviceId, trace) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const fp = this.makeDeviceStoragePath(deviceId);
+            const dp = path_1.default.join(this.options.storageDir, this.Container.id);
+            const fptmp = this.makeDeviceStoragePath(deviceId, '-tmp');
+            if (!fs_1.default.existsSync(dp)) {
+                fs_1.default.mkdirSync(dp, { recursive: true });
+            }
+            fs_1.default.writeFileSync(fptmp, JSON.stringify(trace));
+            if (fs_1.default.existsSync(fp))
+                fs_1.default.rmSync(fp);
+            fs_1.default.renameSync(fptmp, fp);
+        });
+    }
+    /**
+     * Forms the path to the storage file
+     *
+     * @param deviceId Device ID
+     * @param prefix Prefix between the device name and its extension
+    */
+    makeDeviceStoragePath(deviceId, prefix = '') {
+        return path_1.default.join(this.options.storageDir, this.Container.id, deviceId + prefix + '.json');
+    }
+}
+exports.default = DeviceFileStorage;

package/lib/boot/DeviceManager.d.ts

@@ -0,0 +1,190 @@
+import CoreError from '../errors/CoreError';
+import BootClass from './BootClass';
+import BasicType from '../validator/types/BasicType';
+import IAction from '../actions/IAction';
+import IMetricSettings from '../metrics/IMetricSettings';
+import IPort from '../ports/IPort';
+import IValidationRule from '../validator/IValidationRule';
+export interface IDeviceVendor {
+    /** Group name = Vendor name  */
+    name: string;
+    /** Global devices dir */
+    dir: string;
+    /**
+     * List of all devices in group
+     * Like a
+     *
+     * ```
+     * ['Device1', 'Device2', 'Device3', 'Device4']
+     * ```
+    */
+    deviceList: Array<string>;
+    /**
+     * Errors in group
+     * Contains all errors collected in the group during initialization
+     *
+     * Errors like a DM_LIST_NOT_FOUND & DM_LIST_INCORRECT
+    */
+    errors: Array<CoreError>;
+    /**
+     * Not used now
+     * Vendor description
+    */
+    description: string;
+}
+/**
+ * An object based on this interface contains all
+ * the basic exported information about the device
+ *
+ * @see getDeviceInfo
+*/
+export interface IDeivceInfo {
+    /** List of device actions    */
+    actions: {
+        [key: string]: IAction;
+    };
+    /** List of device metrics */
+    metrics: {
+        [key: string]: IMetricSettings;
+    };
+    /** List of device inputs */
+    inputs: {
+        [key: string]: IPort;
+    };
+    /** List of device outputs */
+    outputs: {
+        [key: string]: IPort;
+    };
+    /** List of device options rules */
+    options: {
+        [key: string]: IValidationRule;
+    };
+    /** Device descriotion */
+    description: string;
+}
+/**
+ * BootClass which generates a list of available devices for the container.
+ * Provides the ability to initialize devices and provide information about them
+ *
+ *
+ * @see get
+*/
+export default class DeviceManager extends BootClass {
+    /**
+     * Contains a list of devices and their full path to the class
+     * Like a:
+     *
+     * ```js
+     * {
+     *     "vendorname.Devicename": '/path/to/js/file.js'
+     * }
+     * ```
+     * */
+    protected devices: Map<string, string>;
+    /**
+     * Vendor array.
+     *
+     * @see IDeviceVendor
+    */
+    protected vendorList: Array<IDeviceVendor>;
+    checkOptions(): {
+        [key: string]: BasicType;
+    };
+    process(): void;
+    /**
+     * Return vendor list
+     *
+     * @example
+     * ```ts
+     * ['vrack', 'basic', 'net']
+     * ```
+    */
+    getVendorList(): string[];
+    /**
+     * Returns a list of devices from a specific vendor
+     *
+     * @param vendor Vendor name
+     * @see getVendorList()
+    */
+    getVendorDeviceList(vendor: string): Array<string>;
+    /**
+     * Exports all basic device parameters and collects them in one object
+     * Used to generate documentation for the device
+     *
+     * @see IDeivceInfo
+    */
+    getDeviceInfo(vendor: string, device: string): Promise<IDeivceInfo>;
+    /**
+     * Method for updating the device list
+     * Updates the available device lists.
+     *
+     * Searches the directory specified in `options.dir` and adds all directories in it as vendors.
+     * Each folder attempts to read the list.json file to get a list of vendor devices
+     *
+     * Two types of list.json file definition are supported
+     *
+     * First type - array:
+     *
+     * ```json
+     * ['Device1', 'Device2', 'Device3']
+     * ```
+     * Second type - Object
+     * This approach allows you to point to devices that are deeper than the vendor's root folder
+     *
+     * ```json
+     * {
+     *   "Master": "devices/Master",
+     *   "Interval": "devices/Interval",
+     *   "Guard": "devices/Guard",
+     * }
+     * ```
+     *
+     * @see arrayDeviceListPrepare()
+     * @see objectDeviceListPrepare()
+    */
+    protected updateDeviceList(): void;
+    /**
+     * Return class of device
+     *
+     * Requires special device string of path
+     * example "vrack.System" where "vrack" is vendor and "System" is device class
+     * @param {string} device Device path string
+    */
+    get(device: string, updateList?: boolean): Promise<any>;
+    /**
+     * Find vendor by name
+     *
+     * Not found if return boolean
+    */
+    protected findVendor(vendor: string): boolean | IDeviceVendor;
+    /**
+     * Processes a list of devices as an Array
+     *
+     * Takes an Array of type
+     * ```
+     * ['DeviceName', 'DeviceName2']
+     * ```
+     * @return {Array<string>} Sorted list
+    */
+    protected arrayDeviceListPrepare(list: Array<string>, group: IDeviceVendor): string[];
+    /**
+     * Processes a list of devices as an object
+     *
+     * Takes an object of type
+     * ```
+     * {
+     *  DeviceName: 'path/to/Device'
+     * }
+     * ```
+     *
+     * return keys of list
+     * ```
+     * ['DeviceName']
+     * ```
+     *
+     * Set in this.devices for device name requiere path
+    */
+    protected objectDeviceListPrepare(list: {
+        [key: string]: string;
+    }, group: IDeviceVendor): string[];
+}