@uns-kit/core 0.0.1

package/dist/uns/handover-manager.js

@@ -0,0 +1,227 @@
+import logger from "../logger.js";
+import { HandoverManagerEventEmitter } from "./handover-manager-event-emitter.js";
+import { MqttTopicBuilder } from "../uns-mqtt/mqtt-topic-builder.js";
+import { ACTIVE_TIMEOUT, PACKAGE_INFO } from "./process-config.js";
+/**
+ * HandoverManager is responsible for all handover-related logic,
+ * including handling incoming MQTT messages, issuing handover requests,
+ * and processing handover responses.
+ */
+export class HandoverManager {
+    event = new HandoverManagerEventEmitter();
+    processName;
+    mqttProxy;
+    unsMqttProxies;
+    requestingHandover = false;
+    handoverInProgress = false;
+    topicBuilder;
+    activeTimeout;
+    active = false;
+    handoverRequestEnabled = false;
+    handoverEnabled = true;
+    forceStartEnabled = false;
+    constructor(processName, mqttProxy, unsMqttProxies, handoverRequestEnabled, handoverEnabled, forceStartEnabled) {
+        this.processName = processName;
+        this.mqttProxy = mqttProxy;
+        this.unsMqttProxies = unsMqttProxies;
+        this.handoverRequestEnabled = handoverRequestEnabled;
+        this.handoverEnabled = handoverEnabled;
+        this.forceStartEnabled = forceStartEnabled;
+        // Instantiate the topic builder.
+        this.topicBuilder = new MqttTopicBuilder(`uns-infra/${PACKAGE_INFO.name}/${PACKAGE_INFO.version}/${processName}/`);
+        // Set status as active after a timeout if no other active process are detected.
+        this.activeTimeout = setTimeout(() => {
+            logger.info(`${this.processName} - No active message received within timeout. Assuming no other process is running.`);
+            this.active = true;
+            this.event.emit("handoverManager", { active: this.active });
+            // Activate all UNS proxy instance publishers and subscribers.
+            this.unsMqttProxies.forEach((unsProxy) => {
+                unsProxy.setPublisherActive();
+                unsProxy.setSubscriberActive();
+            });
+        }, ACTIVE_TIMEOUT);
+    }
+    /**
+     * Main entry point for handling incoming MQTT messages.
+     * It checks the topic and delegates to the corresponding handler.
+     */
+    async handleMqttMessage(event) {
+        try {
+            // Check if the packet is active messages from other processes and this process is not active.
+            if (this.requestingHandover === false &&
+                this.topicBuilder.getActiveTopic() !== event.topic &&
+                this.active === false &&
+                this.handoverInProgress === false) {
+                logger.info(`${this.processName} - Another process is active on ${event.topic}.`);
+                if (this.handoverRequestEnabled) {
+                    // Requester process
+                    // Publish a handover request message after 10 seconds to the handover topic.
+                    clearTimeout(this.activeTimeout); // Clear the active timeout if it exists - prevent this process from becoming active after a timeout.
+                    this.activeTimeout = undefined;
+                    this.event.emit("handoverManager", { active: this.active });
+                    this.requestingHandover = true;
+                    logger.info(`${this.processName} - Requesting handover in 10 seconds.`);
+                    setTimeout(async () => {
+                        const eventHandoverTopic = new MqttTopicBuilder(MqttTopicBuilder.extractBaseTopic(event.topic)).getHandoverTopic();
+                        logger.info(`${this.processName} - Requesting handover ${eventHandoverTopic}.`);
+                        this.handoverInProgress = true;
+                        await this.mqttProxy.publish(eventHandoverTopic, JSON.stringify({ type: "handover_request" }), {
+                            retain: false,
+                            properties: {
+                                responseTopic: this.topicBuilder.getHandoverTopic(),
+                                userProperties: {
+                                    processName: this.processName,
+                                },
+                            },
+                        });
+                    }, 10000);
+                }
+                else {
+                    if (this.forceStartEnabled) {
+                        // Force start the process even if another process is active.
+                        logger.info(`${this.processName} - Force starting the process.`);
+                        logger.warn(`${this.processName} - Warning: Source and destination being the same may lead to duplicate messages.`);
+                        clearTimeout(this.activeTimeout); // Clear the active timeout if it exists - prevent this process from becoming active after a timeout.
+                        this.activeTimeout = undefined;
+                        this.active = true;
+                        this.event.emit("handoverManager", { active: this.active });
+                        // Activate all UNS proxy instance publishers and subscribers.
+                        this.unsMqttProxies.forEach((unsProxy) => {
+                            unsProxy.setPublisherActive();
+                            unsProxy.setSubscriberActive();
+                        });
+                    }
+                    else {
+                        logger.info(`${this.processName} - Waiting for the other process on topic ${event.topic} to become passive.`);
+                        this.activeTimeout.refresh();
+                    }
+                }
+            }
+            // Check if the packet is an handover message, sent to a handover topic.
+            if (event.topic === this.topicBuilder.getHandoverTopic() && this.handoverEnabled) {
+                if (event.packet?.properties?.userProperties?.processName && event.packet.properties.userProperties.processName !== this.processName) {
+                    await this.handleHandover(event);
+                }
+            }
+        }
+        catch (error) {
+            logger.error(`${this.processName} - Error processing MQTT message: ${error.message}`);
+            return;
+        }
+    }
+    /**
+     * Handles handovers.
+     */
+    async handleHandover(event) {
+        try {
+            const response = JSON.parse(event.message.toString());
+            // Responder process
+            // Check if the message is a handover request and publish MULTIPLE handover_subscriber messages
+            if (response.type === "handover_request") {
+                logger.info(`${this.processName} - Received handover request from ${event.packet?.properties?.userProperties?.processName}. Accepting handover.`);
+                // Set all UNS proxy instance subscribers to passive and drain the queue.
+                const mqttWorkerData = [];
+                for (let i = 0; i < this.unsMqttProxies.length; i++) {
+                    const unsProxy = this.unsMqttProxies[i];
+                    const workerData = await unsProxy.setSubscriberPassiveAndDrainQueue();
+                    mqttWorkerData.push(workerData);
+                }
+                logger.info(`${this.processName} - Handover request accepted. Sending handover_subscriber messages.`);
+                // Publish handover_subscriber messages for each instance that has processed some data.
+                for (let i = 0; i < mqttWorkerData.length; i++) {
+                    const workerData = mqttWorkerData[i];
+                    if (workerData.batchSize > 0) {
+                        await this.mqttProxy.publish(event.packet.properties?.responseTopic ?? "", JSON.stringify({
+                            type: "handover_subscriber",
+                            batchSize: workerData.batchSize,
+                            referenceHash: workerData.referenceHash,
+                            instanceName: workerData.instanceName,
+                        }), {
+                            retain: false,
+                            properties: {
+                                responseTopic: this.topicBuilder.getHandoverTopic(),
+                                userProperties: {
+                                    processName: this.processName,
+                                },
+                            },
+                        });
+                    }
+                }
+                logger.info(`${this.processName} - Handover subscriber messages sent.`);
+                // Publish a single handover acknowledgment only when all
+                // handover_subscriber messages have been sent
+                this.active = false;
+                this.event.emit("handoverManager", { active: this.active });
+                await this.mqttProxy.publish(event.packet.properties?.responseTopic ?? "", JSON.stringify({
+                    type: "handover_fin",
+                }), {
+                    retain: false,
+                    properties: {
+                        responseTopic: this.topicBuilder.getHandoverTopic(),
+                        userProperties: {
+                            processName: this.processName,
+                        },
+                    },
+                });
+                logger.info(`${this.processName} - Handover fin message sent.`);
+                this.handoverInProgress = false;
+                this.requestingHandover = false;
+                this.unsMqttProxies.forEach((unsProxy) => {
+                    unsProxy.stop();
+                });
+            }
+            // Requestor process
+            // Check if the message is one of the handover_subscriber message in response to handover_request
+            // and publish a handover_ack message
+            if (response.type === "handover_subscriber") {
+                // Find correct unsProxy instance for handover_subscriber and set it active
+                this.unsMqttProxies.forEach((unsProxy) => {
+                    if (unsProxy.instanceName === response.instanceName) {
+                        unsProxy.setSubscriberActive(response.batchSize, response.referenceHash);
+                    }
+                });
+            }
+            // Requestor process
+            // Check if the message is a handover_fin at the end of handover_subscriber messages
+            if (response.type === "handover_fin") {
+                logger.info(`${this.processName} - Received handover fin from ${event.packet?.properties?.userProperties?.processName}.`);
+                // Maybe we should count the number of requests that were allrady made TODO
+                // this.handoverInProgress = false;
+                // this.requestingHandover = false;
+                this.active = true;
+                this.event.emit("handoverManager", { active: this.active });
+                logger.info(`${this.processName} - Handover completed.`);
+                // Activate all UNS proxy instance publishers and subscribers.
+                this.unsMqttProxies.forEach((unsProxy) => {
+                    unsProxy.setPublisherActive();
+                    unsProxy.setSubscriberActive();
+                });
+                // Maybe we should reply with handover_ack.
+                await this.mqttProxy.publish(event.packet.properties?.responseTopic ?? "", JSON.stringify({
+                    type: "handover_ack",
+                }), {
+                    retain: false,
+                    properties: {
+                        responseTopic: this.topicBuilder.getHandoverTopic(),
+                        userProperties: {
+                            processName: this.processName,
+                        },
+                    },
+                });
+                logger.info(`${this.processName} - Handover ack message sent.`);
+            }
+            // Responder process
+            // Check if the message is a handover_ack at the end of handover_fin messages
+            if (response.type === "handover_ack") {
+                logger.info(`${this.processName} - Received handover ack from ${event.packet?.properties?.userProperties?.processName}.`);
+                this.handoverInProgress = false;
+                this.requestingHandover = false;
+                logger.info(`${this.processName} - Handover completed. Exiting process.`);
+                process.exit(0);
+            }
+        }
+        catch (error) {
+            logger.error(`${this.processName} - Error processing handover response: ${error.message}`);
+        }
+    }
+}

package/dist/uns/process-config.d.ts

@@ -0,0 +1,10 @@
+export declare const PROCESS_NAME_FILE: string;
+export declare const PACKAGE_JSON_PATH: string;
+interface PackageInfo {
+    name: string;
+    version: string;
+}
+export declare const PACKAGE_INFO: PackageInfo;
+export declare const MQTT_UPDATE_INTERVAL = 10000;
+export declare const ACTIVE_TIMEOUT = 10000;
+export {};

package/dist/uns/process-config.js

@@ -0,0 +1,12 @@
+// process-config.ts
+import * as path from "path";
+import { readFileSync } from "fs";
+import { basePath } from "../base-path.js";
+// Path to the process name file
+export const PROCESS_NAME_FILE = path.join(basePath, "uns-process-name.conf");
+// Path to package.json to retrieve package name and version
+export const PACKAGE_JSON_PATH = path.join(basePath, "package.json");
+export const PACKAGE_INFO = JSON.parse(readFileSync(PACKAGE_JSON_PATH, "utf8"));
+// Other configuration values (update intervals, timeouts, etc.)
+export const MQTT_UPDATE_INTERVAL = 10000; // in milliseconds
+export const ACTIVE_TIMEOUT = 10000; // in milliseconds

package/dist/uns/process-name-service.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Retrieves a persistent process name.
+ * - Checks if a process name is provided via command-line args.
+ * - Otherwise, reads the process name from a file.
+ * - If the file does not exist, generates a new name and stores it.
+ */
+export declare function getProcessName(): string;

package/dist/uns/process-name-service.js

@@ -0,0 +1,28 @@
+import { readFileSync, writeFileSync } from "fs";
+import { PROCESS_NAME_FILE } from "./process-config.js";
+import logger from "../logger.js";
+/**
+ * Retrieves a persistent process name.
+ * - Checks if a process name is provided via command-line args.
+ * - Otherwise, reads the process name from a file.
+ * - If the file does not exist, generates a new name and stores it.
+ */
+export function getProcessName() {
+    // Try to read the process name from the configuration file.
+    try {
+        return readFileSync(PROCESS_NAME_FILE, "utf8").trim();
+    }
+    catch {
+        // Generate a new process name if reading fails
+        const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+        const newProcessName = Array.from({ length: 6 }, () => chars.charAt(Math.floor(Math.random() * chars.length))).join("");
+        // Write the new process name to the file for persistence
+        try {
+            writeFileSync(PROCESS_NAME_FILE, newProcessName, "utf8");
+        }
+        catch (err) {
+            logger.error("Failed to write process name file:", err);
+        }
+        return newProcessName;
+    }
+}

package/dist/uns/status-monitor.d.ts

@@ -0,0 +1,35 @@
+import type MqttProxy from "../uns-mqtt/mqtt-proxy.js";
+export declare class StatusMonitor {
+    private mqttProxy;
+    private processStatusTopic;
+    private activeSupplier;
+    private memoryIntervalMs;
+    private statusIntervalMs;
+    private memoryInterval?;
+    private statusInterval?;
+    /**
+     * @param mqttProxy The MQTT proxy used to publish messages.
+     * @param processStatusTopic The base topic for the process (ending with a slash).
+     * @param activeSupplier A function returning the current active state (boolean).
+     * @param memoryIntervalMs Interval in milliseconds for publishing memory status.
+     * @param statusIntervalMs Interval in milliseconds for publishing active status.
+     */
+    constructor(mqttProxy: MqttProxy, processStatusTopic: string, activeSupplier: () => boolean, memoryIntervalMs: number, statusIntervalMs: number);
+    /**
+     * Starts the periodic memory and status updates.
+     */
+    start(): void;
+    /**
+     * Stops the periodic updates.
+     */
+    stop(): void;
+    /**
+     * Publishes memory usage updates via MQTT.
+     * In this example, only the `heapUsed` metric is published.
+     */
+    private publishMemoryUpdates;
+    /**
+     * Publishes the process active status via MQTT.
+     */
+    private publishStatusUpdates;
+}

package/dist/uns/status-monitor.js

@@ -0,0 +1,82 @@
+// status-monitor.ts
+import logger from "../logger.js";
+import { DataSizeMeasurements } from "./uns-measurements.js";
+import { UnsPacket } from "./uns-packet.js";
+export class StatusMonitor {
+    mqttProxy;
+    processStatusTopic;
+    activeSupplier;
+    memoryIntervalMs;
+    statusIntervalMs;
+    memoryInterval;
+    statusInterval;
+    /**
+     * @param mqttProxy The MQTT proxy used to publish messages.
+     * @param processStatusTopic The base topic for the process (ending with a slash).
+     * @param activeSupplier A function returning the current active state (boolean).
+     * @param memoryIntervalMs Interval in milliseconds for publishing memory status.
+     * @param statusIntervalMs Interval in milliseconds for publishing active status.
+     */
+    constructor(mqttProxy, processStatusTopic, activeSupplier, memoryIntervalMs, statusIntervalMs) {
+        this.mqttProxy = mqttProxy;
+        this.processStatusTopic = processStatusTopic;
+        this.activeSupplier = activeSupplier;
+        this.memoryIntervalMs = memoryIntervalMs;
+        this.statusIntervalMs = statusIntervalMs;
+    }
+    /**
+     * Starts the periodic memory and status updates.
+     */
+    start() {
+        this.memoryInterval = setInterval(() => this.publishMemoryUpdates(), this.memoryIntervalMs);
+        this.statusInterval = setInterval(() => this.publishStatusUpdates(), this.statusIntervalMs);
+    }
+    /**
+     * Stops the periodic updates.
+     */
+    stop() {
+        if (this.memoryInterval) {
+            clearInterval(this.memoryInterval);
+            this.memoryInterval = undefined;
+        }
+        if (this.statusInterval) {
+            clearInterval(this.statusInterval);
+            this.statusInterval = undefined;
+        }
+    }
+    /**
+     * Publishes memory usage updates via MQTT.
+     * In this example, only the `heapUsed` metric is published.
+     */
+    async publishMemoryUpdates() {
+        try {
+            const time = UnsPacket.formatToISO8601(new Date());
+            const memoryUsage = process.memoryUsage();
+            const heapUsedMessage = { data: { time, value: Math.round(memoryUsage.heapUsed / 1048576), uom: DataSizeMeasurements.MegaByte } };
+            let packet = await UnsPacket.unsPacketFromUnsMessage(heapUsedMessage);
+            this.mqttProxy.publish(`${this.processStatusTopic}heap-used`, JSON.stringify(packet));
+            const heapTotalMessage = { data: { time, value: Math.round(memoryUsage.heapTotal / 1048576), uom: DataSizeMeasurements.MegaByte } };
+            packet = await UnsPacket.unsPacketFromUnsMessage(heapTotalMessage);
+            this.mqttProxy.publish(`${this.processStatusTopic}heap-total`, JSON.stringify(packet));
+        }
+        catch (error) {
+            logger.error(`StatusMonitor - Error publishing memory updates: ${error.message}`);
+        }
+    }
+    /**
+     * Publishes the process active status via MQTT.
+     */
+    async publishStatusUpdates() {
+        try {
+            const time = UnsPacket.formatToISO8601(new Date());
+            const activeMessage = {
+                data: { time, value: Number(this.activeSupplier()) },
+            };
+            const packet = await UnsPacket.unsPacketFromUnsMessage(activeMessage);
+            this.mqttProxy.publish(`${this.processStatusTopic}active`, JSON.stringify(packet), { retain: false, });
+        }
+        catch (error) {
+            logger.error(`StatusMonitor - Error publishing status updates: ${error.message}`);
+        }
+    }
+}

package/dist/uns/uns-event-emitter.d.ts

@@ -0,0 +1,6 @@
+export declare class UnsEventEmitter<Events extends Record<string, any>> {
+    private listeners;
+    on<K extends keyof Events>(eventName: K, listener: (event: Events[K]) => void): void;
+    off<K extends keyof Events>(eventName: K, listener: (event: Events[K]) => void): void;
+    emit<K extends keyof Events>(eventName: K, event: Events[K]): void;
+}

package/dist/uns/uns-event-emitter.js

@@ -0,0 +1,19 @@
+export class UnsEventEmitter {
+    listeners = {};
+    on(eventName, listener) {
+        if (!this.listeners[eventName]) {
+            this.listeners[eventName] = [];
+        }
+        this.listeners[eventName].push(listener);
+    }
+    off(eventName, listener) {
+        if (!this.listeners[eventName])
+            return;
+        this.listeners[eventName] = this.listeners[eventName].filter((l) => l !== listener);
+    }
+    emit(eventName, event) {
+        if (!this.listeners[eventName])
+            return;
+        this.listeners[eventName].forEach((listener) => listener(event));
+    }
+}

package/dist/uns/uns-interfaces.d.ts

@@ -0,0 +1,156 @@
+import { UnsAttributeType } from "../graphql/schema";
+import { MeasurementUnit } from "./uns-measurements";
+import { UnsTags } from "./uns-tags";
+import { UnsTopics } from "./uns-topics";
+export type ISO8601 = `${number}-${string}-${string}T${string}:${string}:${string}.${string}Z`;
+export declare function isIOS8601Type(value: string): value is ISO8601;
+export type UnsAttribute = string;
+export declare const valueTypes: string[];
+export type ValueTypeString = typeof valueTypes[number];
+export type ValueType = string | number;
+export interface IUnsParameters {
+    mqttSubToTopics?: string | string[];
+    username?: string;
+    password?: string;
+    mqttSSL?: boolean;
+    publishThrottlingDelay?: number;
+    subscribeThrottlingDelay?: number;
+}
+export interface IUnsProcessParameters {
+    processName?: string | undefined;
+    mqttSubToTopics?: string | string[];
+    username?: string;
+    password?: string;
+    mqttSSL?: boolean;
+}
+export interface UnsEvents {
+    input: {
+        topic: string;
+        message: string;
+        packet: any;
+    };
+    mqttProxyStatus: {
+        event: string;
+        value: number;
+        uom: MeasurementUnit;
+        statusTopic: string;
+    };
+    error: {
+        code: number;
+        message: string;
+    };
+    mqttWorker: {
+        command: string;
+        instanceName: string;
+        batchSize: number;
+        referenceHash: string;
+    };
+    cronEvent: {};
+    apiGetEvent: {
+        req: any;
+        res: any;
+    };
+    unsProxyProducedTopics: {
+        producedTopics: ITopicObject[];
+        statusTopic: string;
+    };
+    unsProxyProducedApiEndpoints: {
+        producedApiEndpoints: IApiObject[];
+        statusTopic: string;
+    };
+}
+export interface IUnsExtendedData extends IUnsData {
+    valueType: ValueTypeString;
+}
+export interface IUnsData {
+    time: ISO8601;
+    value: ValueType;
+    dataGroup?: string;
+    uom?: MeasurementUnit;
+    foreignEventKey?: string;
+}
+export interface IUnsEvent {
+    time: ISO8601;
+    dataGroup?: string;
+    details?: string;
+    uniqueEventId?: string;
+}
+export interface IUnsTable {
+    time: ISO8601;
+    values: Record<string, string | number | undefined | null>;
+    dataGroup?: string;
+}
+export interface IUnsCommand {
+    time: ISO8601;
+    details?: string;
+}
+export interface IMqttMessage {
+    topic: UnsTopics;
+    attribute: UnsAttribute;
+    description?: string;
+    tags?: UnsTags[];
+    packet: IUnsPacket;
+    attributeNeedsPersistence?: boolean | null;
+}
+export interface IUnsPacket {
+    message: IUnsExtendedMessage;
+    messageSignature?: string;
+    interval?: number;
+    readonly version: string;
+    sequenceId?: number;
+}
+export interface IUnsPackatParameters {
+}
+export interface IUnsMessage {
+    command?: IUnsCommand;
+    data?: IUnsData;
+    event?: IUnsEvent;
+    table?: IUnsTable;
+    expiresAt?: ISO8601;
+    createdAt?: ISO8601;
+}
+export interface IUnsExtendedMessage extends IUnsMessage {
+    data?: IUnsExtendedData;
+}
+export interface ITopicObject {
+    timestamp: string;
+    attribute: string;
+    attributeType: UnsAttributeType;
+    topic: string;
+    description: string;
+    dataGroup: string;
+    tags: string[] | null;
+    attributeNeedsPersistence: boolean | null;
+}
+export interface IApiObject {
+    timestamp: string;
+    attribute: string;
+    topic: string;
+    attributeType: UnsAttributeType;
+    apiDescription?: string;
+    apiHost: string;
+    apiEndpoint: string;
+    apiSwaggerEndpoint: string;
+    apiMethod: "GET" | "POST" | "PUT" | "DELETE";
+    apiQueryParams: QueryParamDef[];
+}
+export interface QueryParamDef {
+    name: string;
+    type: "string" | "number" | "boolean";
+    required?: boolean;
+    description?: string;
+}
+export interface IApiProxyOptions {
+    jwtSecret?: string;
+    jwks?: {
+        wellKnownJwksUrl: string;
+        activeKidUrl?: string;
+        cacheTtlMs?: number;
+        algorithms?: ("RS256" | "RS384" | "RS512")[];
+    };
+}
+export interface IGetEndpointOptions {
+    apiDescription?: string;
+    tags?: string[];
+    queryParams?: QueryParamDef[];
+}

package/dist/uns/uns-interfaces.js

@@ -0,0 +1,5 @@
+export function isIOS8601Type(value) {
+    const iso8601Regex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+    return iso8601Regex.test(value);
+}
+export const valueTypes = ["string", "number"];