@uns-kit/core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Aljoša Vister
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @uns-kit/core
+
+Core utilities and runtime building blocks for building Unified Namespace (UNS) realtime transformers. The package bundles the process lifecycle manager, MQTT integrations, gRPC gateway helpers, configuration tooling, and shared type definitions that power the UNS ecosystem.
+
+## Installation
+
+```bash
+pnpm add @uns-kit/core
+# or
+npm install @uns-kit/core
+```
+
+## Key Features
+
+- **UnsProxyProcess** – plugin-ready runtime for managing UNS proxy instances and MQTT wiring.
+- **MQTT helpers** – resilient publishers, topic builders, throttled queues, and handover support.
+- **Configuration utilities** – Zod-powered config schema generation and secret resolution helpers.
+- **gRPC gateway helpers** – infrastructure to bridge Python workers into the UNS message fabric.
+
+## Usage
+
+Most projects start by creating an `UnsProxyProcess` and registering plugins:
+
+```ts
+import UnsProxyProcess from "@uns-kit/core/uns/uns-proxy-process";
+
+const process = new UnsProxyProcess("mqtt-broker.svc:1883", { processName: "my-rtt" });
+```
+
+See the individual plugin packages (`@uns-kit/cron`, `@uns-kit/api`, `@uns-kit/temporal`) for examples on extending the process with runtime capabilities.
+
+## Development
+
+```bash
+# Lint and type-check the sources
+pnpm run typecheck
+
+# Emit JavaScript and declaration files to dist/
+pnpm run build
+```
+
+## License
+
+MIT © Aljoša Vister

package/dist/app-config.d.ts

@@ -0,0 +1,177 @@
+export type AppConfig = {
+    uns: {
+        graphql: string;
+        rest: string;
+        instanceMode?: "wait" | "force" | "handover";
+        processName?: string | undefined;
+        handover?: boolean;
+        jwksWellKnownUrl?: string | undefined;
+        kidWellKnownUrl?: string | undefined;
+        env?: "dev" | "staging" | "test" | "prod";
+    };
+    input?: {
+        host: string | ({
+            /** Use the supplied host or IP address. */
+            provider: "inline";
+            /** Host or IP address that should be used directly. */
+            value: string;
+        } | {
+            /** Resolve the host from an external mapping. */
+            provider: "external";
+            /** Identifier used when resolving the host from HostResolverOptions. */
+            key: string;
+            /** Allow the external host to be missing without throwing during resolution. */
+            optional?: boolean | undefined;
+            /** Fallback host when optional is true and the external entry is missing. */
+            default?: string | undefined;
+        } | {
+            /** Resolve the host from local network interfaces. */
+            provider: "system";
+            /** Address family to return when scanning interfaces. */
+            family?: "IPv4" | "IPv6";
+            /** Specific interface to read (falls back to the first match when omitted). */
+            interfaceName?: string | undefined;
+            /** Allow the interface lookup to fail without throwing during resolution. */
+            optional?: boolean | undefined;
+            /** Fallback host/IP when optional is true and no interface matches. */
+            default?: string | undefined;
+        });
+        username?: string | undefined;
+        password?: (string | ({
+            /** Load the secret from an environment variable. */
+            provider: "env";
+            /** Name of the environment variable to read. */
+            key: string;
+            /** Allow the variable to be absent without throwing during resolution. */
+            optional?: boolean | undefined;
+            /** Fallback value when optional is true and the variable is missing. */
+            default?: string | undefined;
+        } | {
+            /** Load the secret from Infisical. */
+            provider: "infisical";
+            /** Secret folder path in Infisical, e.g. '/app/database'. */
+            path: string;
+            /** Secret key/name inside the given path. */
+            key: string;
+            /** Allow the secret to be absent without throwing during resolution. */
+            optional?: boolean | undefined;
+            /** Infisical environment override (defaults to current mode if omitted). */
+            environment?: string | undefined;
+            /** Optional Infisical project identifier when not using the default. */
+            projectId?: string | undefined;
+            /** Fallback value when the secret is missing and optional resolution is allowed. */
+            default?: string | undefined;
+        })) | undefined;
+        clientId?: string | undefined;
+    } | undefined;
+    output?: {
+        host: string | ({
+            /** Use the supplied host or IP address. */
+            provider: "inline";
+            /** Host or IP address that should be used directly. */
+            value: string;
+        } | {
+            /** Resolve the host from an external mapping. */
+            provider: "external";
+            /** Identifier used when resolving the host from HostResolverOptions. */
+            key: string;
+            /** Allow the external host to be missing without throwing during resolution. */
+            optional?: boolean | undefined;
+            /** Fallback host when optional is true and the external entry is missing. */
+            default?: string | undefined;
+        } | {
+            /** Resolve the host from local network interfaces. */
+            provider: "system";
+            /** Address family to return when scanning interfaces. */
+            family?: "IPv4" | "IPv6";
+            /** Specific interface to read (falls back to the first match when omitted). */
+            interfaceName?: string | undefined;
+            /** Allow the interface lookup to fail without throwing during resolution. */
+            optional?: boolean | undefined;
+            /** Fallback host/IP when optional is true and no interface matches. */
+            default?: string | undefined;
+        });
+        username?: string | undefined;
+        password?: (string | ({
+            /** Load the secret from an environment variable. */
+            provider: "env";
+            /** Name of the environment variable to read. */
+            key: string;
+            /** Allow the variable to be absent without throwing during resolution. */
+            optional?: boolean | undefined;
+            /** Fallback value when optional is true and the variable is missing. */
+            default?: string | undefined;
+        } | {
+            /** Load the secret from Infisical. */
+            provider: "infisical";
+            /** Secret folder path in Infisical, e.g. '/app/database'. */
+            path: string;
+            /** Secret key/name inside the given path. */
+            key: string;
+            /** Allow the secret to be absent without throwing during resolution. */
+            optional?: boolean | undefined;
+            /** Infisical environment override (defaults to current mode if omitted). */
+            environment?: string | undefined;
+            /** Optional Infisical project identifier when not using the default. */
+            projectId?: string | undefined;
+            /** Fallback value when the secret is missing and optional resolution is allowed. */
+            default?: string | undefined;
+        })) | undefined;
+        clientId?: string | undefined;
+    } | undefined;
+    infra: {
+        host: string | ({
+            /** Use the supplied host or IP address. */
+            provider: "inline";
+            /** Host or IP address that should be used directly. */
+            value: string;
+        } | {
+            /** Resolve the host from an external mapping. */
+            provider: "external";
+            /** Identifier used when resolving the host from HostResolverOptions. */
+            key: string;
+            /** Allow the external host to be missing without throwing during resolution. */
+            optional?: boolean | undefined;
+            /** Fallback host when optional is true and the external entry is missing. */
+            default?: string | undefined;
+        } | {
+            /** Resolve the host from local network interfaces. */
+            provider: "system";
+            /** Address family to return when scanning interfaces. */
+            family?: "IPv4" | "IPv6";
+            /** Specific interface to read (falls back to the first match when omitted). */
+            interfaceName?: string | undefined;
+            /** Allow the interface lookup to fail without throwing during resolution. */
+            optional?: boolean | undefined;
+            /** Fallback host/IP when optional is true and no interface matches. */
+            default?: string | undefined;
+        });
+        username?: string | undefined;
+        password?: (string | ({
+            /** Load the secret from an environment variable. */
+            provider: "env";
+            /** Name of the environment variable to read. */
+            key: string;
+            /** Allow the variable to be absent without throwing during resolution. */
+            optional?: boolean | undefined;
+            /** Fallback value when optional is true and the variable is missing. */
+            default?: string | undefined;
+        } | {
+            /** Load the secret from Infisical. */
+            provider: "infisical";
+            /** Secret folder path in Infisical, e.g. '/app/database'. */
+            path: string;
+            /** Secret key/name inside the given path. */
+            key: string;
+            /** Allow the secret to be absent without throwing during resolution. */
+            optional?: boolean | undefined;
+            /** Infisical environment override (defaults to current mode if omitted). */
+            environment?: string | undefined;
+            /** Optional Infisical project identifier when not using the default. */
+            projectId?: string | undefined;
+            /** Fallback value when the secret is missing and optional resolution is allowed. */
+            default?: string | undefined;
+        })) | undefined;
+        clientId?: string | undefined;
+    };
+};

package/dist/app-config.js

@@ -0,0 +1 @@
+export {};

package/dist/base-path.d.ts

@@ -0,0 +1 @@
+export declare const basePath: string;

package/dist/base-path.js

@@ -0,0 +1,5 @@
+import { fileURLToPath } from "url";
+import { dirname, resolve } from "path";
+const fName = fileURLToPath(import.meta.url);
+const dName = dirname(fName);
+export const basePath = resolve(dName, "..");

package/dist/config/project.config.extension.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+export declare const projectExtrasSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export type ProjectExtras = z.infer<typeof projectExtrasSchema>;

package/dist/config/project.config.extension.js

@@ -0,0 +1,3 @@
+import { z } from "zod";
+// Exported constant in PascalCase
+export const projectExtrasSchema = z.object({});

package/dist/config-file.d.ts

@@ -0,0 +1,12 @@
+import type { AppConfig } from "./app-config";
+import { type ResolvedAppConfig, type SecretResolverOptions } from "./uns-config/secret-resolver.js";
+export declare class ConfigFile {
+    private static rawCache?;
+    private static rawPath?;
+    private static resolvedCache?;
+    static loadRawConfig(configPath?: string): AppConfig;
+    static get(): AppConfig;
+    static loadConfig(configPath?: string, options?: SecretResolverOptions): Promise<ResolvedAppConfig>;
+    static loadResolvedConfig(options?: SecretResolverOptions): Promise<ResolvedAppConfig>;
+    static clearCache(): void;
+}

package/dist/config-file.js

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import path from "node:path";
+import { clearSecretResolverCaches, resolveConfigSecrets, } from "./uns-config/secret-resolver.js";
+const hasOptions = (options) => !!options && Object.values(options).some(value => value !== undefined);
+export class ConfigFile {
+    static rawCache;
+    static rawPath;
+    static resolvedCache;
+    static loadRawConfig(configPath) {
+        const p = configPath ?? path.resolve(process.cwd(), "config.json");
+        if (!this.rawCache || this.rawPath !== p) {
+            const raw = fs.readFileSync(p, "utf8");
+            this.rawCache = JSON.parse(raw); // no runtime validation
+            this.rawPath = p;
+            this.resolvedCache = undefined;
+        }
+        return this.rawCache;
+    }
+    static get() {
+        if (!this.rawCache) {
+            throw new Error("Config not loaded. Call ConfigFile.loadConfig() first.");
+        }
+        return this.rawCache;
+    }
+    static async loadConfig(configPath, options) {
+        const raw = this.loadRawConfig(configPath);
+        if (hasOptions(options)) {
+            return resolveConfigSecrets(raw, options);
+        }
+        if (!this.resolvedCache) {
+            this.resolvedCache = await resolveConfigSecrets(raw);
+        }
+        return this.resolvedCache;
+    }
+    static async loadResolvedConfig(options) {
+        return this.loadConfig(undefined, options);
+    }
+    static clearCache() {
+        this.rawCache = undefined;
+        this.resolvedCache = undefined;
+        this.rawPath = undefined;
+        clearSecretResolverCaches();
+    }
+}

package/dist/examples/data-example.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/data-example.js

@@ -0,0 +1,44 @@
+/**
+ * Change this file according to your specifications and rename it to index.ts
+ */
+import UnsProxyProcess from "../uns/uns-proxy-process.js";
+import { ConfigFile } from "../config-file.js";
+import logger from "../logger.js";
+import { PhysicalMeasurements } from "../uns/uns-measurements.js";
+import { UnsPacket } from "../uns/uns-packet.js";
+/**
+ * Load the configuration from a file.
+ * On the server, this file is provided by the `uns-datahub-controller`.
+ * In the development environment, you are responsible for creating and maintaining this file and its contents.
+ */
+const config = await ConfigFile.loadConfig();
+/**
+ * Connect to input and output brokers
+ */
+const unsProxyProcess = new UnsProxyProcess(config.infra.host, { processName: config.uns.processName });
+const mqttInput = await unsProxyProcess.createUnsMqttProxy(config.input.host, "templateUnsRttInput", config.uns.instanceMode, config.uns.handover, {
+    mqttSubToTopics: ["raw/#"],
+});
+const mqttOutput = await unsProxyProcess.createUnsMqttProxy(config.output.host, "templateUnsRttOutput", config.uns.instanceMode, config.uns.handover, { publishThrottlingDelay: 1000 });
+/**
+ * Event listener for input events.
+ * Transform an input message and publish it with publishMqttMessage function.
+ */
+mqttInput.event.on("input", async (event) => {
+    try {
+        if (event.topic === "raw/data") {
+            const time = UnsPacket.formatToISO8601(new Date());
+            const values = event.message.split(",");
+            const numberValue = parseFloat(values[0]);
+            const message = { data: { dataGroup: "electricity", time, value: numberValue, uom: PhysicalMeasurements.MiliVolt } };
+            const topic = "sij/";
+            const tags = [];
+            const packet = await UnsPacket.unsPacketFromUnsMessage(message);
+            mqttOutput.publishMqttMessage({ topic, attribute: "data-number", packet, description: "Number value", tags });
+        }
+    }
+    catch (error) {
+        logger.error(`Error publishing message to MQTT: ${error.message}`);
+        throw error;
+    }
+});

package/dist/examples/load-test-data.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/load-test-data.js

@@ -0,0 +1,72 @@
+/**
+ * Load the configuration from a file.
+ * On the server, this file is provided by the `uns-datahub-controller`.
+ * In the development environment, you are responsible for creating and maintaining this file and its contents.
+ */
+import readline from "readline";
+import { ConfigFile } from "../config-file.js";
+import UnsMqttProxy from "../uns-mqtt/uns-mqtt-proxy.js";
+import logger from "../logger.js";
+/**
+ * This script initializes an MQTT output proxy for load testing purposes.
+ * It sets up a connection to the specified MQTT broker and configures
+ * a proxy instance. The load test is designed to evaluate the performance
+ * and reliability of the MQTT broker under simulated load conditions.
+ */
+async function main() {
+    try {
+        const config = await ConfigFile.loadConfig();
+        const mqttOutput = new UnsMqttProxy(config.output.host, "loadTest", "templateUnsRttLoadTest", { publishThrottlingDelay: 0 }, true);
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        rl.question(`Would you like to continue with load-test on ${config.output.host}? (Y/n) `, async (answer) => {
+            if (answer.toLowerCase() === "y" || answer.trim() === "") {
+                rl.question("How many iterations should be run? (default is 100) ", async (iterations) => {
+                    const maxIntervals = parseInt(iterations) || 100;
+                    rl.question("What should be the delay between intervals in milliseconds? (default is 0 ms) ", async (intervalDelay) => {
+                        const delay = parseInt(intervalDelay) || 0;
+                        logger.info(`Starting load test with ${maxIntervals} messages and ${delay} ms delay...`);
+                        let count = 0;
+                        const startTime = Date.now();
+                        while (count < maxIntervals) {
+                            try {
+                                const currentDate = new Date();
+                                const rawData = `${count},${currentDate.getTime()}`;
+                                await mqttOutput.publishMessage("raw/data", rawData);
+                            }
+                            catch (error) {
+                                logger.error("Error publishing message:", error.message);
+                            }
+                            count++;
+                            if (delay > 0) {
+                                await new Promise((resolve) => setTimeout(resolve, delay));
+                            }
+                        }
+                        logger.info(`Sleeping for 50ms.`);
+                        await new Promise((resolve) => setTimeout(resolve, 50));
+                        const endTime = Date.now();
+                        const duration = (endTime - startTime) / 1000;
+                        const messagesPerSecond = maxIntervals / duration;
+                        logger.info(`Load test completed in ${duration.toFixed(2)} seconds.`);
+                        logger.info(`Message rate: ${messagesPerSecond.toFixed(2)} msg/s.`);
+                        rl.close();
+                        process.exit(0);
+                    });
+                });
+            }
+            else {
+                logger.info("Load test aborted.");
+                rl.close();
+                process.exit(0);
+            }
+        });
+    }
+    catch (error) {
+        logger.error("Error initializing load test:", error.message);
+        process.exit(1);
+    }
+}
+main();

package/dist/examples/table-example.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Change this file according to your specifications and rename it to index.ts
+ */
+export {};

package/dist/examples/table-example.js

@@ -0,0 +1,52 @@
+/**
+ * Change this file according to your specifications and rename it to index.ts
+ */
+import UnsProxyProcess from "../uns/uns-proxy-process.js";
+import { ConfigFile } from "../config-file.js";
+import logger from "../logger.js";
+import { UnsPacket } from "../uns/uns-packet.js";
+/**
+ * Load the configuration from a file.
+ * On the server, this file is provided by the `uns-datahub-controller`.
+ * In the development environment, you are responsible for creating and maintaining this file and its contents.
+ */
+const config = await ConfigFile.loadConfig();
+/**
+ * Load and configure input and output brokers from config.json
+ */
+if (!config.infra?.host || !config.input?.host || !config.output?.host) {
+    throw new Error("Missing required configuration in config.json");
+}
+const unsProxyProcess = new UnsProxyProcess(config.infra.host, { processName: config.uns.processName });
+const mqttInput = await unsProxyProcess.createUnsMqttProxy(config.input.host, "templateUnsRttInput", config.uns.instanceMode, config.uns.handover, {
+    mqttSubToTopics: ["iba/zrm"],
+    publishThrottlingDelay: 0,
+    subscribeThrottlingDelay: 0
+});
+const mqttOutput = await unsProxyProcess.createUnsMqttProxy(config.output.host, "templateUnsRttOutput", config.uns.instanceMode, config.uns.handover, {
+    publishThrottlingDelay: 0,
+    subscribeThrottlingDelay: 0
+});
+/**
+ * The input worker connects to the IBA broker and listens for incoming messages.
+ * It processes the messages and transforms them into a table-type IUnsMessage.
+ * The resulting message is published to the output broker.
+ */
+mqttInput.event.on("input", async (event) => {
+    try {
+        if (event.topic === "iba/zrm") {
+            const jsonObject = JSON.parse(event.message);
+            const timestamp = jsonObject.Timestamp;
+            delete (jsonObject.Timestamp);
+            const time = UnsPacket.formatToISO8601(new Date(timestamp));
+            const message = { table: { dataGroup: "iba_test", values: jsonObject, time } };
+            const topic = "sij/acroni/hv/";
+            const tags = [];
+            const packet = await UnsPacket.unsPacketFromUnsMessage(message);
+            mqttOutput.publishMqttMessage({ topic, attribute: "zrm", packet, description: "Table", tags });
+        }
+    }
+    catch (error) {
+        logger.error(`Error publishing message to MQTT: ${error.message}`);
+    }
+});

package/dist/examples/uns-gateway.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/uns-gateway.js

@@ -0,0 +1,5 @@
+import { startUnsGateway } from "../uns-grpc/uns-gateway-server.js";
+const addr = await startUnsGateway();
+console.log(`UNS Gateway listening on ${addr.address} (UDS=${addr.isUDS})`);
+// Keep alive
+setInterval(() => { }, 1 << 30);