@uns-kit/temporal 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,43 @@
+# @uns-kit/temporal
+
+`@uns-kit/temporal` bridges Temporal.io workflows into the Unified Namespace. The plugin registers a `createTemporalProxy` method on `UnsProxyProcess`, tracks workflow metadata, and republishes workflow results via UNS topics.
+
+## Installation
+
+```bash
+pnpm add @uns-kit/temporal
+# or
+npm install @uns-kit/temporal
+```
+
+Install `@uns-kit/core` as well—the plugin augments its runtime.
+
+## Example
+
+```ts
+import UnsProxyProcess from "@uns-kit/core/uns/uns-proxy-process";
+import unsTemporalPlugin, { type UnsProxyProcessWithTemporal } from "@uns-kit/temporal";
+
+const process = new UnsProxyProcess("mqtt-broker:1883", { processName: "temporal-demo" }) as UnsProxyProcessWithTemporal;
+unsTemporalPlugin;
+
+const temporal = await process.createTemporalProxy("hv-etl", "temporal:7233", "hv-namespace");
+await temporal.initializeTemporalProxy({
+  topic: "factory/",
+  attribute: "hv-status",
+  attributeType: UnsAttributeType.Data,
+});
+
+await temporal.startWorkflow("TransformHvSclData", { coil_id: "42" }, "ETL_HV_SCL_TASK_QUEUE");
+```
+
+## Scripts
+
+```bash
+pnpm run typecheck
+pnpm run build
+```
+
+## License
+
+MIT © Aljoša Vister

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default } from "./uns-temporal-plugin.js";
+export { UnsTemporalProxy, type UnsProxyProcessWithTemporal } from "./uns-temporal-plugin.js";
+export * from "./temporal-interfaces.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { default } from "./uns-temporal-plugin.js";
+export { UnsTemporalProxy } from "./uns-temporal-plugin.js";
+export * from "./temporal-interfaces.js";

package/dist/temporal-example.d.ts

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

package/dist/temporal-example.js

@@ -0,0 +1,33 @@
+/**
+ * Change this file according to your specifications and rename it to index.ts
+ */
+import UnsProxyProcess from "@uns-kit/core/uns/uns-proxy-process";
+import unsTemporalPlugin from "./uns-temporal-plugin";
+import { ConfigFile } from "@uns-kit/core/config-file";
+import { UnsAttributeType } from "@uns-kit/core/graphql/schema";
+import logger from "@uns-kit/core/logger";
+/**
+ * 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 the temporal and register uns topic for temporal
+ */
+const unsProxyProcess = new UnsProxyProcess(config.infra.host, { processName: config.uns.processName });
+unsTemporalPlugin;
+const temporalTopic = {
+    attribute: "temporal-data",
+    topic: "sij/",
+    attributeType: UnsAttributeType.Data,
+    attributeNeedsPersistence: true,
+    dataGroup: "temporal",
+    description: "Temporal data example",
+    tags: ["temporal"],
+};
+const temporalProxy = await unsProxyProcess.createTemporalProxy("templateUnsTemporal", "temporal-1.sij.digital:7233", "hv");
+await temporalProxy.initializeTemporalProxy(temporalTopic);
+// Start temporal workflow
+const result = await temporalProxy.startWorkflow("TransformHvSclData", { 'coil_id': "42" }, "ETL_HV_SCL_TASK_QUEUE");
+logger.info(`Workflow result: ${JSON.stringify(result)}`);

package/dist/temporal-interfaces.d.ts

@@ -0,0 +1,10 @@
+import { UnsAttributeType } from "@uns-kit/core/graphql/schema";
+export interface ITemporalTopic {
+    attribute: string;
+    topic: string;
+    attributeType: UnsAttributeType;
+    attributeNeedsPersistence?: boolean | undefined;
+    dataGroup?: string | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+}

package/dist/temporal-interfaces.js

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

package/dist/uns-temporal-plugin.d.ts

@@ -0,0 +1,9 @@
+import type { ClientOptions, ConnectionOptions } from "@temporalio/client";
+import UnsProxyProcess, { type UnsProxyProcessPlugin } from "@uns-kit/core/uns/uns-proxy-process";
+import UnsTemporalProxy from "./uns-temporal-proxy.js";
+declare const unsTemporalPlugin: UnsProxyProcessPlugin;
+export default unsTemporalPlugin;
+export { UnsTemporalProxy };
+export type UnsProxyProcessWithTemporal = UnsProxyProcess & {
+    createTemporalProxy(instanceName: string, temporalAddress: string, temporalNamespace: string, connectionOverrides?: ConnectionOptions, clientOverrides?: ClientOptions): Promise<UnsTemporalProxy>;
+};

package/dist/uns-temporal-plugin.js

@@ -0,0 +1,40 @@
+import UnsProxyProcess from "@uns-kit/core/uns/uns-proxy-process";
+import UnsTemporalProxy from "./uns-temporal-proxy.js";
+const temporalProxyRegistry = new WeakMap();
+const getTemporalProxies = (instance) => {
+    let proxies = temporalProxyRegistry.get(instance);
+    if (!proxies) {
+        proxies = [];
+        temporalProxyRegistry.set(instance, proxies);
+    }
+    return proxies;
+};
+const unsTemporalPlugin = ({ define }) => {
+    define({
+        async createTemporalProxy(instanceName, temporalAddress, temporalNamespace, connectionOverrides, clientOverrides) {
+            await this.waitForProcessConnection();
+            const internals = this;
+            const connectionOptions = {
+                address: temporalAddress,
+                ...connectionOverrides,
+            };
+            const clientOptions = {
+                namespace: temporalNamespace,
+                ...clientOverrides,
+            };
+            const unsTemporalProxy = new UnsTemporalProxy(internals.processName, instanceName, connectionOptions, clientOptions);
+            unsTemporalProxy.event.on("unsProxyProducedTopics", (event) => {
+                internals.processMqttProxy.publish(event.statusTopic, JSON.stringify(event.producedTopics), {
+                    retain: true,
+                    properties: { messageExpiryInterval: 120000 },
+                });
+            });
+            internals.unsTemporalProxies.push(unsTemporalProxy);
+            getTemporalProxies(this).push(unsTemporalProxy);
+            return unsTemporalProxy;
+        },
+    });
+};
+UnsProxyProcess.use(unsTemporalPlugin);
+export default unsTemporalPlugin;
+export { UnsTemporalProxy };

package/dist/uns-temporal-proxy.d.ts

@@ -0,0 +1,27 @@
+import UnsProxy from "@uns-kit/core/uns/uns-proxy";
+import { ConnectionOptions, ClientOptions, Workflow } from '@temporalio/client';
+import { ITemporalTopic } from "./temporal-interfaces.js";
+export default class UnsTemporalProxy extends UnsProxy {
+    instanceName: string;
+    protected processStatusTopic: string;
+    private topicBuilder;
+    private processName;
+    private connectionOptions;
+    private clientOptions;
+    private client;
+    private unsTopic;
+    constructor(processName: string, instanceName: string, connectionOptions: ConnectionOptions, clientOptions: ClientOptions);
+    /**
+     * Initializes the Temporal proxy by registering the given topic and establishing a client connection.
+     * @param unsTopic - The topic object to register with Temporal.
+     * @returns A promise that resolves when initialization is complete.
+     * @throws If the Temporal client fails to initialize.
+     */
+    initializeTemporalProxy(temporalTopic: ITemporalTopic): Promise<void>;
+    /**
+     * Creates a temporal proxy for the UNS process.
+     * This method registers the UNS topic for temporal data.
+     */
+    private registerTemporalTopic;
+    startWorkflow(workflowTypeOrFunc: string | Workflow, arg: Record<string, any>, taskQueue: string, workflowId?: string): Promise<any>;
+}

package/dist/uns-temporal-proxy.js

@@ -0,0 +1,101 @@
+import UnsProxy from "@uns-kit/core/uns/uns-proxy";
+import logger from "@uns-kit/core/logger";
+import { MqttTopicBuilder } from "@uns-kit/core/uns-mqtt/mqtt-topic-builder";
+import * as path from "path";
+import { basePath } from "@uns-kit/core/base-path";
+import { readFileSync } from "fs";
+import { Connection, Client } from '@temporalio/client';
+import { UnsPacket } from "@uns-kit/core/uns/uns-packet";
+const packageJsonPath = path.join(basePath, "package.json");
+const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+export default class UnsTemporalProxy extends UnsProxy {
+    instanceName;
+    processStatusTopic;
+    topicBuilder;
+    processName;
+    connectionOptions;
+    clientOptions;
+    client;
+    unsTopic;
+    constructor(processName, instanceName, connectionOptions, clientOptions) {
+        super();
+        this.connectionOptions = connectionOptions;
+        this.clientOptions = clientOptions;
+        this.instanceName = instanceName;
+        this.processName = processName;
+        // Create the topic builder using packageJson values and the processName.
+        this.topicBuilder = new MqttTopicBuilder(`uns-infra/${packageJson.name}/${packageJson.version}/${processName}/`);
+        // Generate the processStatusTopic using the builder.
+        this.processStatusTopic = this.topicBuilder.getProcessStatusTopic();
+        // Derive the instanceStatusTopic by appending the instance name.
+        this.instanceStatusTopic = this.processStatusTopic + instanceName + "/";
+        // Concatenate processName with instanceName for the worker identification.
+        this.instanceNameWithSuffix = `${processName}-${instanceName}`;
+    }
+    /**
+     * Initializes the Temporal proxy by registering the given topic and establishing a client connection.
+     * @param unsTopic - The topic object to register with Temporal.
+     * @returns A promise that resolves when initialization is complete.
+     * @throws If the Temporal client fails to initialize.
+     */
+    async initializeTemporalProxy(temporalTopic) {
+        try {
+            const unsTopic = {
+                timestamp: UnsPacket.formatToISO8601(new Date()),
+                topic: temporalTopic.topic,
+                attribute: temporalTopic.attribute,
+                attributeType: temporalTopic.attributeType,
+                description: temporalTopic.description ?? "",
+                tags: temporalTopic.tags ?? [],
+                attributeNeedsPersistence: temporalTopic.attributeNeedsPersistence ?? true,
+                dataGroup: temporalTopic.dataGroup ?? "",
+            };
+            // Register the UNS topic for temporal data.
+            this.registerTemporalTopic(unsTopic);
+            this.clientOptions.connection = this.clientOptions.connection ?? await Connection.connect(this.connectionOptions);
+            this.client = new Client(this.clientOptions);
+        }
+        catch (error) {
+            logger.error(`Failed to initialize Temporal client: ${error.message}`);
+            throw error;
+        }
+    }
+    /**
+     * Creates a temporal proxy for the UNS process.
+     * This method registers the UNS topic for temporal data.
+     */
+    async registerTemporalTopic(unsTopic) {
+        try {
+            // Register the UNS topic for temporal data.
+            this.registerUniqueTopic(unsTopic);
+            this.unsTopic = unsTopic;
+        }
+        catch (error) {
+            logger.error(`Error creating temporal proxy: ${error.message}`);
+            throw error;
+        }
+    }
+    async startWorkflow(workflowTypeOrFunc, arg, taskQueue, workflowId) {
+        try {
+            const workflowInput = {
+                input_data: arg,
+                uns_params: {
+                    uns_attribute: this.unsTopic.attribute,
+                    uns_attribute_type: this.unsTopic.attributeType,
+                    uns_topic: this.unsTopic.topic
+                }
+            };
+            const workflowOptions = {
+                args: [workflowInput], // single JSON object
+                taskQueue,
+                workflowId: workflowId ?? `${this.instanceNameWithSuffix}-${Math.floor(Date.now() / 1000)}`
+            };
+            logger.info(`Starting workflow with options: ${JSON.stringify(workflowOptions)}`);
+            const handle = await this.client.workflow.start(workflowTypeOrFunc, workflowOptions);
+            return await handle.result();
+        }
+        catch (error) {
+            logger.error(`Failed to start/complete workflow: ${error.message}`);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@uns-kit/temporal",
+  "version": "0.0.1",
+  "description": "Temporal.io integration plugin for UnsProxyProcess, wiring workflows into the UNS.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Aljoša Vister <aljosa.vister@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uns-datahub/uns-kit.git",
+    "directory": "packages/uns-temporal"
+  },
+  "keywords": [
+    "uns",
+    "temporal",
+    "workflow",
+    "temporalio",
+    "mqtt",
+    "typescript"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./*": "./dist/*"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@temporalio/client": "^1.13.0",
+    "@uns-kit/core": "^0.0.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}