vrack2-core 0.0.1 → 1.0.0

package/README.md

@@ -1,6 +1,27 @@
-VRack2 core
------------
+VRack2 Core  
+============  
 
-The core set of components for running vrack2. Currently in an initial state and refining as needed. 
+Фреймворк для создания событийно-ориентированных сервисов на JavaScript/TypeScript. Определяет правила организации кода, структуру файлов и предоставляет базовые компоненты для их реализации.  
 
-Currently unsuitable for public use.
+Оптимально использовать VRack2 Core в составе VRack2, но допускается и самостоятельное использование.  
+
+Если вы хотите попробовать данный подход - настоятельно рекомендуется использовать вначале [VRack2](https://github.com/VRack2/vrack2) и его документацию. 
+
+--------
+
+**Использовать эту документацию имеет смысл только для более глубокого изучения устройства VRack2 или для создания сервиса независимого от VRack2**
+
+-------
+
+ - [VRack2](https://github.com/VRack2/vrack2) - Официальный репозиторий
+ - [VRack2-service](https://github.com/VRack2/vrack2-service) - Репозиторий для запуска сервисов на основе VRack2-Core, включая официальный VRack2.
+ - [VRack2 Manager](https://github.com/VRack2/vrack2-manager) - Интерфейс для работы с сервисами VRack2
+
+Основная документация для VRack2-Core на данный момент не готова. Часть документации в виде черновиков уже есть.
+
+**Документы для глубокого погружения:**
+
+ <!-- 1. [Быстрый старт](./docs/FastStart.md) -  -->
+ 1. [Общая структура](./docs/Structure.md)
+ 2. [Контейнер](./docs/Container.md)
+ 3. [Bootstrap Классы](./docs/Bootstrap.md)

package/docs/Bootstrap.md

@@ -0,0 +1,77 @@
+# Bootstrap Классы
+
+Bootstrap классы предоставляют механизм для расширения функционала сервисов без использования устройств. Они инициализируются после создания контейнера, но до его запуска, позволяя подписываться на события контейнера и изменять его поведение.
+
+## Основные возможности
+
+- Расширение возможностей контейнера
+- Изменение стандартного поведения контейнера
+- Замена стандартных Bootstrap классов
+- Интеграция с основным процессом загрузки
+
+## Стандартные Bootstrap Классы
+
+Следующие классы являются обязательными для загрузки контейнера:
+
+| Класс             | Описание |
+|-------------------|----------|
+| **DeviceManager** | Предоставляет информацию об устройствах (списки, информация об устройстве, создание экземпляров) |
+| **DeviceFileStorage** | Обеспечивает сохранение и восстановление сохраняемых данных устройств |
+| **DeviceMetrics** | Отвечает за сохранение метрик устройств |
+| **StructureStorage** | Обеспечивает обновление структуры контейнера |
+
+*Примечание:* Несмотря на обязательность этих классов, их можно заменить пользовательскими реализациями с аналогичным интерфейсом.
+
+## Настройка Bootstrap Классов
+
+Загрузкой Bootstrap классов занимается класс `MainProcess`. При его инициализации можно:
+
+1. Заменить список классов на пользовательский
+2. Изменить настройки, передаваемые в эти классы
+
+### Пример конфигурации
+
+```javascript
+const MainProcessEx = new MainProcessClass({ 
+    id, 
+    service, 
+    bootstrap: {
+        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: {} 
+        }
+    }
+})
+```
+
+**Примечания:**
+- Bootstrap классы привязываются к идентификатору
+- Пути указываются в формате `ImportManager`
+- Классы должны быть оформлены как npm модули
+
+## Создание пользовательских Bootstrap Классов
+
+Все Bootstrap классы должны наследовать базовый класс `vrack2-core.BootClass`.
+
+### Структура класса
+
+1. **checkOptions()** - метод для переопределения параметров (аналогично классу устройства)
+2. **process()** и **processPromise()** - методы для реализации основной логики класса
+
+В методах `process()` и `processPromise()` доступен объект `Container`, для которого запускается класс
+
+### Рекомендации
+
+Для разработки собственных Bootstrap классов рекомендуется изучить существующие реализации в VRack2 Core.

package/docs/Container.md

@@ -0,0 +1,124 @@
+
+# Container
+
+Класс `Container` представляет собой контейнер для управления устройствами, их соединениями и взаимодействием в рамках сервиса.
+
+Контейнер создается внутри класса `MainProcess`. Это сделано для удобного правильного инциализирования классов `Bootstrap` и `Container` которые содержат ссылки внутри себя на друг друга.
+
+Это центральный компонент, который:
+
+- Инициализирует устройства согласно объекту сервиса (обычно получается из файла сервиса)
+- Устанавливает соединения между портами устройств
+- Управляет жизненным циклом устройств
+- Обрабатывает действия и метрики устройств
+- Предоставляет структуру сервиса
+
+Контейнер наследуется от `EventEmitter` и эмитирует различные события на разных этапах работы.
+
+Функционал контейнера может расширяться с помощью [bootstrap классов](./Bootstrap.md). Он обязательно требует реализцию всех базовых bootstrap классов. Например `DeviceManager` предоставляет контейнеру возможность загружать классы устройств и инициализировать их, только с помощью него он знает что-то о наличии устройств.
+
+### Конструктор
+```typescript
+constructor(id: string, service: IServiceStructure, Bootstrap: Bootstrap, confFile?: string)
+```
+- `id` - уникальный ID сервиса
+- `service` - структура сервиса
+- `Bootstrap` - класс Bootstrap для контейнера
+- `confFile` - (опционально) путь к файлу конфигурации
+
+### init()
+Инициализирует контейнер:
+1. Загружает дополнительные конфигурации (если указаны)
+2. Инициализирует устройства
+3. Устанавливает соединения между устройствами
+
+### run()
+Запускает контейнер:
+1. Запускает процессы устройств
+
+## Обработка ошибок
+Контейнер определяет множество ошибок через ErrorManager:
+
+### Ошибки устройств:
+- `CTR_ERROR_INIT_DEVICE` - ошибка инициализации устройства (общая ошибка инициализации устройства. См. Вложенные ошибки)
+- `CTR_INCORRECT_DEVICE_ID` - некорректный ID устройства 
+- `CTR_DEVICE_DUBLICATE` - дублирование ID устройства
+- `CTR_ERROR_PREPARE_OPTIONS` - ошибка подготовки параметров
+- `CTR_DEVICE_ACTION_NF` - действие устройства не найдено
+- `CTR_DEVICE_NF` - устройство не найдено
+- `CTR_DEVICE_ACTION_HANDLER_NF` - обработчик действия не найден
+- `CTR_DEVICE_PROCESS_EXCEPTION` - исключение при выполнении process
+- `CTR_DEVICE_PROCESS_PROMISE_EXCEPTION` - исключение при выполнении processPromise
+
+### Ошибки портов:
+- `CTR_INCORRECT_DYNAMIC_PN` - некорректное имя динамического порта
+- `CTR_INCORRECT_PN` - некорректное имя порта
+- `CTR_INPUT_HANDLER_NF` - обработчик входа не найден
+- `CTR_DEVICE_PORT_NF` - порт на устройстве не найден
+
+### Ошибки соединений:
+- `CTR_CONNECTION_INCORRECT` - некорректный формат соединения
+- `CTR_CONNECTION_DEVICE_NF` - устройство соединения не найдено
+- `CTR_CONNECTION_PORT_NF` - порт соединения не найден
+- `CTR_INCOMPATIBLE_PORTS` - несовместимые порты
+
+
+## Внутренние события
+
+События указаны в порядке их запуска. Bootstrap классы могут подписываться на событий контейнера что бы расширять его возможности. Так делают часть стандартных bootstrap классов.
+
+ 1. **configure** - Запускается первым, перед заполнением файла конфигурации
+ 2. **beforeInit** - Перед началом инициализации
+ 3. **init** - Начало инициализации устройств
+ 4. **initDevice(device)** - Будет выполнятся для каждого инициализируемого устройства
+ 5. **afterInit** - После окончания инициализации устройств
+ 6. **beforeConnections** - Перед началом инциализации соединений
+ 7. **connections** - Начало инициализации соединений
+ 8. **connection(conn)** - Будет выполнено для каждого соединения
+ 9. **afterConnections** - После окончания инциализаций соеднинений
+ 10. **beforeProcess** - Перед выполнением `process` для каждого устройства
+ 11. **process(DeviceID)** - Будет выполнено для каждого устройства перед запуском `process`
+ 12. **afterProcess** - После окончания всех запусков `process`
+ 13. **beforeProcessPromise** - Перед выполнением `processPromise` каждого устройства
+ 14. **processPromise(DeviceID)** -  Будет выполнено для каждого устройства перед запуском `processPromise`
+ 15. **afterProcessPromise** - После окончания всех запусков `processPromise`
+ 16. **beforeLoaded** - Перед окончанием загрузки контейнера
+ 17. **loaded** - После окончания загрузки контейнера
+
+
+Описания структур передаваемых в указаных выше события
+
+### initDevice(device)
+
+Объект в виде структуры `IStructureDevice`
+
+```ts
+export default interface IStructureDevice {
+    /** Device ID */
+    id: string;
+    /** Device type in VRack style like a 'vendor.Device' */
+    type: string;
+    /** Device options */
+    options: { [key: string]: any; };
+    /** Device connections */
+    connections?: Array<string>
+}
+```
+
+
+### connection(сс)
+
+Объект в виде структуры: 
+
+```ts
+interface: {
+    outputDevice: string;
+    outputPort: string;
+    inputDevice: string;
+    inputPort: string;
+} 
+```
+
+### process(DeviceID) & processPromise(DeviceID)
+
+**DeviceID** - Строковый уникальный идентификатор устройсва. Доступ к любому устройсту внутри контейнера можно получить так `ContainerClass.devices[DeviceID]` или внутри устройства `this.Container.devices[DeviceID]`

package/docs/Device.md

@@ -0,0 +1,272 @@
+# Документация для класса `Device`
+
+## Общее описание
+Класс `Device` представляет базовый класс для всех устройств в системе. Это абстрактный класс, который определяет:
+- Основные свойства и методы всех устройств
+- Механизмы взаимодействия с контейнером
+- Систему портов для связи между устройствами
+- Обработку действий и метрик
+- Систему событий и сообщений
+
+Устройства наследуются от этого класса и реализуют свою специфическую логику.
+
+## Основные свойства
+
+Основные свойства устройства назнаются контейнером при инициализации устройства согласно файлу сервиса.
+
+  - **id** *string* - Уникальный идентификатор устройства в рамках контейнера. Обычно начинается с заглавной буквы. 
+  - **type** *string* - Тип устройства в формате "вендор.Устройство".
+  - **Container** *Container* - Ссылка на контейнер, который создал устройство
+  - **options** *any* - Параметры устройства
+
+## Переопределяемые методы и свойства
+
+#### preProcess()
+Вызывается на этапе инициализации устройства (до создания соединений). Тут еще есть возможность поменять количество портов, создать обработчики для входящих портов, или например обработчики для экшенов. На этом этапе только создается класс и назначаются основные свойства.
+
+#### process()
+Основной метод запуска устройства (после инициализации всех соединений).
+
+#### processPromise()
+Асинхронная версия process() - контейнер ждет завершения всех processPromise().
+
+
+### ports
+Объект для управления портами устройства:
+```typescript
+ports: {
+  input: { [key: string]: DevicePort }  // Входные порты
+  output: { [key: string]: DevicePort } // Выходные порты
+}
+```
+
+### Container
+Ссылка на контейнер, в котором находится устройство.
+```typescript
+Container: Container;
+```
+
+### options
+Параметры устройства, которые проверяются методом `checkOptions()`.
+```typescript
+options: { [key: string]: any } = {};
+```
+
+### shares
+Быстро обновляемые данные устройства, которые отправляются подписчикам после вызова `render()`.
+```typescript
+shares: any = {};
+```
+
+### storage
+Данные устройства, которые сохраняются между сеансами работы.
+```typescript
+storage: any = {}
+```
+
+## Основные методы
+
+### Конструктор
+```typescript
+constructor(id: string, type: string, Container: Container)
+```
+- `id` - уникальный ID устройства
+- `type` - тип устройства
+- `Container` - ссылка на контейнер
+
+### settings()
+Возвращает настройки устройства, включая список каналов связи.
+```typescript
+settings(): IDeviceSettings {
+  return {
+    channels: ['terminal', 'notify', 'event', 'action', 'alert', 'error', 'render']
+  }
+}
+```
+
+### description()
+Возвращает описание устройства (может содержать markdown).
+```typescript
+description(): string {
+  return ''
+}
+```
+
+### actions()
+Определяет список действий, которые можно выполнять с устройством.
+```typescript
+actions(): { [key: string]: BasicAction } { return {} }
+// Пример:
+// return {
+//   'test.action': Action.global().requirements({
+//     id: Rule.string().require().default('www').description('Some id')
+//   }).description('Test action')
+// }
+```
+
+### metrics()
+Определяет метрики устройства.
+```typescript
+metrics(): { [key: string]: BasicMetric } { return {} }
+// Пример:
+// return {
+//   'temperature': Metric.inS().retentions('1s:6h').description('Temperature metric')
+// }
+```
+
+### checkOptions()
+Определяет правила валидации параметров устройства.
+```typescript
+checkOptions(): { [key: string]: BasicType } { return {} }
+// Пример:
+// return {
+//   timeout: Rule.number().integer().min(0).description('Interval timeout').example(0)
+// }
+```
+
+### inputs() / outputs()
+Определяют входные и выходные порты устройства.
+```typescript
+inputs(): { [key: string]: BasicPort } { return {} }
+outputs(): { [key: string]: BasicPort } { return {} }
+// Пример:
+// return {
+//   'sensor.temperature': Port.standart(),
+//   'control.setpoint': Port.standart()
+// }
+```
+
+### Жизненный цикл устройства
+
+#### preProcess()
+Вызывается на этапе инициализации устройства (до создания соединений).
+
+#### process()
+Основной метод запуска устройства (после инициализации всех соединений).
+
+#### processPromise()
+Асинхронная версия process() - контейнер ждет завершения всех processPromise().
+
+### Методы работы с данными
+
+#### render()
+Отправляет данные из `shares` подписчикам.
+
+#### save()
+Сохраняет данные из `storage`.
+
+#### metric()
+Записывает значение метрики.
+```typescript
+metric(path: string, value: number, modify: 'last' | 'first' | 'max' | 'min' | 'avg' | 'sum' = 'last')
+```
+
+### Методы сообщений
+
+#### terminal() / notify() / event() / alert() / error()
+Отправляют сообщения разных типов.
+```typescript
+terminal(data: string, trace: { [key: string]: any }, ...args: any[])
+notify(data: string, trace: { [key: string]: any }, ...args: any[])
+// и т.д.
+```
+
+### Вспомогательные методы
+
+#### addInputHandler()
+Добавляет обработчик для входного порта.
+```typescript
+addInputHandler(name: string, action: (data: any) => any)
+// Пример:
+// this.addInputHandler('control.setpoint', (value) => { ... })
+```
+
+#### addActionHandler()
+Добавляет обработчик для действия.
+```typescript
+addActionHandler(name: string, action: (data: any) => any)
+// Пример:
+// this.addActionHandler('set.temperature', (data) => { ... })
+```
+
+#### terminate()
+Сигнализирует о критической ошибке и необходимости остановки устройства.
+```typescript
+terminate(error: Error, action: string)
+```
+
+## Интерфейсы
+
+### IDeviceSettings
+Настройки устройства:
+```typescript
+interface IDeviceSettings {
+  channels: Array<'terminal' | 'notify' | 'event' | 'action' | 'alert' | 'error' | 'render'>;
+}
+```
+
+### IDeviceEvent
+Структура события устройства:
+```typescript
+interface IDeviceEvent {
+  device: string;       // ID устройства
+  data: string;         // Данные события
+  trace: { [key: string]: any }; // Дополнительная информация
+}
+```
+
+## Пример использования
+```typescript
+class TemperatureSensor extends Device {
+  private currentTemp = 0;
+
+  description(): string {
+    return 'Датчик температуры с возможностью установки уставки';
+  }
+
+  actions() {
+    return {
+      'set.temperature': Action.global()
+        .requirements({
+          value: Rule.number().min(-50).max(100).description('Температура')
+        })
+        .description('Установка температуры')
+    };
+  }
+
+  metrics() {
+    return {
+      'temperature': Metric.inS().retentions('1s:6h').description('Текущая температура')
+    };
+  }
+
+  inputs() {
+    return {
+      'control.setpoint': Port.standart()
+    };
+  }
+
+  process() {
+    // Чтение температуры каждую секунду
+    setInterval(() => {
+      this.currentTemp = readTemperature();
+      this.metric('temperature', this.currentTemp);
+      this.render();
+    }, 1000);
+  }
+
+  // Обработчик действия
+  actionSetTemperature(data: { value: number }) {
+    this.currentTemp = data.value;
+    return { status: 'ok' };
+  }
+}
+```
+
+Класс `Device` предоставляет мощную основу для создания различных устройств с поддержкой:
+- Валидации параметров
+- Действий с внешним интерфейсом
+- Метрик для мониторинга
+- Портов для связи между устройствами
+- Различных типов сообщений
+- Жизненного цикла устройства

package/docs/FastStart.md

@@ -0,0 +1,111 @@
+Быстрый старт
+=============
+
+Если вы хотите вначале быстро запустить и попробовать свое первое приложение вне VRack2, это хороший вариант для вас.
+
+Для начала создадим папку:
+
+```bash
+mkdir myvapp
+```
+
+Перейдем в нее и проинициализируем npm
+
+```bash
+cd ./myvapp
+npm init
+```
+
+Можете просто нажимать Enter пока конфигуратор npm не закончит свою работу
+
+Установить vrack2-core:
+
+```bash
+npm install vrack2-core
+```
+
+Создадим еще необходимые директории
+
+```bash
+mkdir ./devices
+mkdir ./storage
+mkdir ./structure
+```
+
+
+Создадим файл запуска нашего сервиса `index.js` с содержимым
+
+```js
+import { ImportManager, MainProcess } from "vrack2-core";
+import { isMainThread, workerData } from "worker_threads";
+// Класс MainProcess
+let MainProcessPath = 'vrack2-core.MainProcess'
+// Файл структуры сервиса
+let processFile = './service.json'
+// Идентификатор контейнера - должен быть уникален только в случае запуска нескольких контейнеров
+let id = 'containerID'
+
+async function run (){ 
+    // Импортируем JSON file
+    const service = await ImportManager.importJSON(processFile) 
+    // Импортируем класс MainProcess
+    const MainProcessClass = await ImportManager.importClass(MainProcessPath)
+    // Создаем экземпляр
+    const MainProcessEx = new MainProcessClass({ id, service })
+    
+    MainProcessEx.run()
+}
+
+// Запуск 
+run()
+```
+
+Отредактируем файл `package.json` и добавим скрипт запуска
+
+```json
+"scripts": {
+    "start": "node ./index",
+}
+```
+
+Пришло время добавить набор устройств. Создадим папку:
+
+```bash
+mkdir ./devices/myvendor
+```
+
+Создадим файл `Interval.js` 
+
+```bash
+take ./devices/myvendor/Interval.js
+```
+
+Добавим содержимое:
+
+```js
+
+```
+
+Создадим файл `Debug.js` 
+
+```bash
+take ./devices/myvendor/Debug.js
+```
+
+Добавим содержимое:
+
+```js
+
+```
+
+Осталось добавить файл сервиса `service.json` с содержимым:
+
+```JSON
+
+```
+
+Теперь можно запустить сервис:
+
+```bash
+npm run start
+```