@uns-kit/core 0.0.1

package/dist/uns-mqtt/mqtt-proxy.js

@@ -0,0 +1,245 @@
+import mqtt from "mqtt";
+import logger from "../logger.js";
+import { UnsEventEmitter } from "../uns/uns-event-emitter.js";
+import { DataSizeMeasurements, PhysicalMeasurements } from "../uns/uns-measurements.js";
+export default class MqttProxy {
+    event = new UnsEventEmitter();
+    statusTopic;
+    instanceName;
+    mqttHost;
+    mqttSubToTopics;
+    mqttSSL;
+    mqttClient;
+    startDate;
+    mqttParameters;
+    statusUpdateInterval;
+    transformationStatsInterval = null;
+    publishedMessageCount = 0;
+    publishedMessageBytes = 0;
+    subscribedMessageCount = 0;
+    subscribedMessageBytes = 0;
+    mqttWorker;
+    isConnected = false;
+    constructor(mqttHost, instanceName, mqttParameters, mqttWorker) {
+        this.mqttSSL = mqttParameters?.mqttSSL ?? false;
+        this.mqttSubToTopics = mqttParameters?.mqttSubToTopics ?? [];
+        this.mqttHost = mqttHost;
+        this.startDate = new Date();
+        this.instanceName = instanceName ?? "process";
+        this.statusTopic = `${mqttParameters?.statusTopic}`;
+        this.mqttParameters = mqttParameters ?? {};
+        this.mqttWorker = mqttWorker;
+    }
+    async start() {
+        logger.info(`${this.instanceName} - Connecting to MQTT broker...`);
+        return new Promise((resolve, reject) => {
+            try {
+                const username = this.mqttParameters.username;
+                const password = this.mqttParameters.password;
+                const options = {
+                    username,
+                    password,
+                    protocolVersion: 5,
+                    rejectUnauthorized: this.mqttSSL,
+                    will: {
+                        topic: `${this.statusTopic}alive`,
+                        payload: Buffer.from(""),
+                        qos: 0,
+                        retain: true,
+                        properties: { messageExpiryInterval: 3600 },
+                    },
+                    clientId: this.instanceName,
+                    clean: true,
+                };
+                const protocol = this.mqttSSL ? "mqtts" : "mqtt";
+                this.mqttClient = mqtt.connect(`${protocol}://${this.mqttHost}`, options);
+                const onConnect = () => {
+                    try {
+                        this.mqttClient.stream.setMaxListeners(0);
+                        logger.info(`${this.instanceName} - Connected to MQTT broker at ${this.mqttHost}`);
+                        if (this.mqttSubToTopics && this.mqttSubToTopics.length > 0) {
+                            logger.info(`${this.instanceName} - Subscribed to ${this.mqttSubToTopics.length} topics.`);
+                            this.mqttClient.subscribe(this.mqttSubToTopics, { qos: 0 });
+                        }
+                        if (this.statusTopic) {
+                            this.statusUpdateInterval = setInterval(() => this.emitStatusUpdates(), 10000);
+                        }
+                        this.transformationStatsInterval = setInterval(() => {
+                            this.emitTransformationStatistics();
+                        }, 60000);
+                        this.mqttClient.off("connect", onConnect);
+                        this.isConnected = true;
+                        resolve();
+                    }
+                    catch (error) {
+                        logger.error(`${this.instanceName} - Error in MQTT connect handler: ${error.message}`);
+                        this.isConnected = false;
+                        reject(error);
+                    }
+                };
+                this.mqttClient.on("connect", onConnect);
+                this.mqttClient.on("message", (topic, message, packet) => {
+                    try {
+                        logger.debug(`${this.instanceName} - Message received on topic ${topic}`);
+                        this.event.emit("input", {
+                            message: message.toString(),
+                            topic: topic,
+                            packet: packet,
+                        });
+                        this.updateSubscribeTransformationStats(message.length);
+                    }
+                    catch (error) {
+                        logger.error(`${this.instanceName} - Error in MQTT message handler: ${error.message}`);
+                    }
+                });
+                this.mqttClient.on("error", (error) => {
+                    logger.error(`${this.instanceName} - MQTT client error: ${error.message}`);
+                    this.isConnected = false;
+                    if ("code" in error) {
+                        this.event.emit("error", { code: error.code, message: error.message });
+                    }
+                    else {
+                        this.event.emit("error", { message: error.message, code: 0 });
+                    }
+                    reject(error);
+                });
+                this.mqttClient.on("reconnect", () => {
+                    logger.debug(`${this.instanceName} - Attempting to reconnect to MQTT broker...`);
+                });
+                this.mqttClient.on("close", () => {
+                    logger.debug(`${this.instanceName} - MQTT connection closed.`);
+                    this.isConnected = false;
+                });
+                this.mqttClient.on("offline", () => {
+                    logger.debug(`${this.instanceName} - MQTT client is offline.`);
+                    this.isConnected = false;
+                });
+                this.mqttClient.on("end", () => {
+                    logger.debug(`${this.instanceName} - MQTT client connection ended.`);
+                    this.isConnected = false;
+                });
+                this.mqttClient.on("disconnect", (packet) => {
+                    logger.debug(`${this.instanceName} - MQTT client disconnected. Reason: ${packet?.reasonCode}`);
+                    this.isConnected = false;
+                });
+            }
+            catch (error) {
+                logger.error(`${this.instanceName} - Error starting MQTT proxy: ${error.message}`);
+                this.isConnected = false;
+                reject(error);
+            }
+        });
+    }
+    async publish(topic, message, options) {
+        this.updatePublishTransformationStats(JSON.stringify(message).length);
+        return new Promise((resolve, reject) => {
+            if (!this.mqttClient || !this.mqttClient.connected) {
+                const error = new Error(`${this.instanceName} - MQTT client is not connected.`);
+                logger.error(error.message);
+                return reject(error);
+            }
+            this.mqttClient.publish(topic, message, options || {}, (err) => {
+                if (err) {
+                    logger.error(`${this.instanceName} - Error publishing to topic ${topic}: ${err.message}`);
+                    return reject(err);
+                }
+                logger.debug(`${this.instanceName} - Published message to topic ${topic}`);
+                resolve();
+            });
+        });
+    }
+    async subscribeAsync(topic, options) {
+        return this.mqttClient.subscribeAsync(topic, options);
+    }
+    async unsubscribeAsync(topic) {
+        return this.mqttClient.unsubscribeAsync(topic);
+    }
+    stop() {
+        logger.info(`${this.instanceName} - Disconnecting from MQTT broker...`);
+        try {
+            if (this.statusUpdateInterval) {
+                clearInterval(this.statusUpdateInterval);
+                this.statusUpdateInterval = null;
+            }
+            if (this.transformationStatsInterval) {
+                clearInterval(this.transformationStatsInterval);
+                this.transformationStatsInterval = null;
+            }
+            if (this.mqttClient) {
+                this.mqttClient.end(false, () => {
+                    this.isConnected = false;
+                    logger.info(`${this.instanceName} - Disconnected from MQTT broker.`);
+                });
+            }
+        }
+        catch (error) {
+            logger.error(`${this.instanceName} - Error during stop: ${error.message}`);
+            this.isConnected = false;
+        }
+    }
+    emitStatusUpdates() {
+        try {
+            const uptime = Math.round((new Date().getTime() - this.startDate.getTime()) / 60000);
+            this.event.emit("mqttProxyStatus", { event: "uptime", value: uptime, uom: PhysicalMeasurements.Minute, statusTopic: this.statusTopic + "uptime" });
+            this.event.emit("mqttProxyStatus", { event: "alive", value: 1, uom: DataSizeMeasurements.Bit, statusTopic: this.statusTopic + "alive" });
+            if (this.mqttWorker !== undefined) {
+                const tpValue = this.mqttWorker.getPublisherState() ? 1 : 0;
+                this.event.emit("mqttProxyStatus", { event: "t-publisher-active", value: tpValue, uom: DataSizeMeasurements.Bit, statusTopic: this.statusTopic + "t-publisher-active" });
+                const tsValue = this.mqttWorker.getSubscriberState() ? 1 : 0;
+                this.event.emit("mqttProxyStatus", { event: "t-subscriber-active", value: tsValue, uom: DataSizeMeasurements.Bit, statusTopic: this.statusTopic + "t-subscriber-active" });
+            }
+        }
+        catch (error) {
+            logger.error(`${this.instanceName} - Error publishing MQTT status: ${error.message}`);
+        }
+    }
+    updatePublishTransformationStats(messageSizeOut) {
+        this.publishedMessageCount += 1;
+        this.publishedMessageBytes += messageSizeOut;
+    }
+    updateSubscribeTransformationStats(messageSizeIn) {
+        this.subscribedMessageCount += 1;
+        this.subscribedMessageBytes += messageSizeIn;
+    }
+    async emitTransformationStatistics() {
+        if (this.statusTopic !== "") {
+            try {
+                this.event.emit("mqttProxyStatus", {
+                    event: "published-message-count",
+                    value: this.publishedMessageCount,
+                    uom: "",
+                    statusTopic: this.statusTopic + "published-message-count",
+                });
+                this.event.emit("mqttProxyStatus", {
+                    event: "published-message-bytes",
+                    value: Math.round(this.publishedMessageBytes / 1024),
+                    uom: DataSizeMeasurements.KiloByte,
+                    statusTopic: this.statusTopic + "published-message-bytes",
+                });
+                this.event.emit("mqttProxyStatus", {
+                    event: "subscribed-message-count",
+                    value: this.subscribedMessageCount,
+                    uom: "",
+                    statusTopic: this.statusTopic + "subscribed-message-count",
+                });
+                this.event.emit("mqttProxyStatus", {
+                    event: "subscribed-message-bytes",
+                    value: Math.round(this.subscribedMessageBytes / 1024),
+                    uom: DataSizeMeasurements.KiloByte,
+                    statusTopic: this.statusTopic + "subscribed-message-bytes",
+                });
+                this.publishedMessageCount = 0;
+                this.publishedMessageBytes = 0;
+                this.subscribedMessageCount = 0;
+                this.subscribedMessageBytes = 0;
+            }
+            catch (error) {
+                this.publishedMessageCount = 0;
+                this.publishedMessageBytes = 0;
+                this.subscribedMessageCount = 0;
+                this.subscribedMessageBytes = 0;
+                logger.error(`${this.instanceName} - Error emitting transformation statistics: ${error.message}`);
+            }
+        }
+    }
+}

package/dist/uns-mqtt/mqtt-topic-builder.d.ts

@@ -0,0 +1,51 @@
+/**
+ * MqttTopicBuilder is a utility class responsible for generating MQTT topics
+ * based on a standardized pattern using the package name, version, and process name.
+ *
+ * This centralizes all MQTT topic definitions so that changes to topic structures
+ * only need to be made in one place.
+ */
+export declare class MqttTopicBuilder {
+    private processStatusTopic;
+    /**
+     * Constructor for MqttTopicBuilder.
+     * It validates the provided process status topic and initializes the instance.
+     * @param processStatusTopic The base topic for the process status.
+     * Example: "uns-infra/packageName/version/processName/"
+     */
+    constructor(processStatusTopic: string);
+    /**
+     * Returns the process status topic.
+     *
+     * Example: "uns-infra/packageName/version/processName"
+     */
+    getProcessStatusTopic(): string;
+    /**
+     * Returns the topic used for publishing the active state.
+     *
+     * Example: "uns-infra/packageName/version/processName/active"
+     */
+    getActiveTopic(): string;
+    /**
+     * Returns the topic used for handover requests.
+     *
+     * Example: "uns-infra/packageName/version/processName/handover"
+     */
+    getHandoverTopic(): string;
+    /**
+     * Returns a wildcard topic for active status messages from any process.
+     * Useful for subscriptions that must capture status from multiple processes.
+     *
+     * Example: "uns-infra/packageName/+/+/active"
+     */
+    getWildcardActiveTopic(): string;
+    /**
+     * Extract base topic from a full topic string.
+     * This is useful for creating a topic builder from an existing topic.
+     * @param fullTopic The full topic string.
+     * Example: "uns-infra/packageName/version/processName/active"
+     * @returns The base topic string.
+     * Example: "uns-infra/packageName/version/processName/"
+     */
+    static extractBaseTopic(fullTopic: string): string;
+}

package/dist/uns-mqtt/mqtt-topic-builder.js

@@ -0,0 +1,70 @@
+/**
+ * MqttTopicBuilder is a utility class responsible for generating MQTT topics
+ * based on a standardized pattern using the package name, version, and process name.
+ *
+ * This centralizes all MQTT topic definitions so that changes to topic structures
+ * only need to be made in one place.
+ */
+export class MqttTopicBuilder {
+    processStatusTopic;
+    /**
+     * Constructor for MqttTopicBuilder.
+     * It validates the provided process status topic and initializes the instance.
+     * @param processStatusTopic The base topic for the process status.
+     * Example: "uns-infra/packageName/version/processName/"
+     */
+    constructor(processStatusTopic) {
+        if (!/^uns-infra\/[^/]+\/[^/]+\/[^/]+\/$/.test(processStatusTopic)) {
+            throw new Error("processStatusTopic must follow the pattern 'uns-infra/<packageName>/<version>/<processName>/'");
+        }
+        this.processStatusTopic = processStatusTopic;
+    }
+    /**
+     * Returns the process status topic.
+     *
+     * Example: "uns-infra/packageName/version/processName"
+     */
+    getProcessStatusTopic() {
+        return this.processStatusTopic;
+    }
+    /**
+     * Returns the topic used for publishing the active state.
+     *
+     * Example: "uns-infra/packageName/version/processName/active"
+     */
+    getActiveTopic() {
+        return this.getProcessStatusTopic() + "active";
+    }
+    /**
+     * Returns the topic used for handover requests.
+     *
+     * Example: "uns-infra/packageName/version/processName/handover"
+     */
+    getHandoverTopic() {
+        return this.getProcessStatusTopic() + "handover";
+    }
+    /**
+     * Returns a wildcard topic for active status messages from any process.
+     * Useful for subscriptions that must capture status from multiple processes.
+     *
+     * Example: "uns-infra/packageName/+/+/active"
+     */
+    getWildcardActiveTopic() {
+        return this.getProcessStatusTopic().split('/').slice(0, 2).join('/') + '/+/+/active';
+    }
+    /**
+     * Extract base topic from a full topic string.
+     * This is useful for creating a topic builder from an existing topic.
+     * @param fullTopic The full topic string.
+     * Example: "uns-infra/packageName/version/processName/active"
+     * @returns The base topic string.
+     * Example: "uns-infra/packageName/version/processName/"
+     */
+    static extractBaseTopic(fullTopic) {
+        const parts = fullTopic.split('/');
+        if (parts.length < 4) {
+            throw new Error("Invalid topic format. Expected 'uns-infra/<packageName>/<version>/<processName>/'.");
+        }
+        return parts.slice(0, 4).join('/') + '/';
+    }
+}

package/dist/uns-mqtt/mqtt-worker-init.d.ts

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

package/dist/uns-mqtt/mqtt-worker-init.js

@@ -0,0 +1,5 @@
+import { isMainThread, parentPort, workerData } from "worker_threads";
+import { MqttWorker } from "./mqtt-worker.js";
+if (!isMainThread && parentPort) {
+    new MqttWorker(workerData);
+}

package/dist/uns-mqtt/mqtt-worker.d.ts

@@ -0,0 +1,20 @@
+import { IMqttWorkerData } from "./mqtt-interfaces.js";
+import { ThrottledPublisher, ThrottledSubscriber } from "./throttled-queue.js";
+export declare class MqttWorker {
+    private mqttProxy;
+    protected publisher: ThrottledPublisher;
+    protected subscriber: ThrottledSubscriber;
+    constructor(workerData: IMqttWorkerData);
+    /**
+     * Listen for incoming messages from the main thread and process them.
+     */
+    private initializeMessageListener;
+    /**
+     * Get the state of the publisher.
+     */
+    getPublisherState(): boolean;
+    /**
+     * Get the state of the subscriber.
+     */
+    getSubscriberState(): boolean;
+}

package/dist/uns-mqtt/mqtt-worker.js

@@ -0,0 +1,120 @@
+import { join } from "path";
+import { parentPort } from "worker_threads";
+import { basePath } from "../base-path.js";
+import logger from "../logger.js";
+import MqttProxy from "./mqtt-proxy.js";
+import { ThrottledPublisher, ThrottledSubscriber } from "./throttled-queue.js";
+export class MqttWorker {
+    mqttProxy;
+    publisher;
+    subscriber;
+    constructor(workerData) {
+        const publishThrottlingDelay = workerData.publishThrottlingDelay || 1;
+        const subscribeThrottlingDelay = workerData.subscribeThrottlingDelay || 1;
+        const persistToDisk = workerData.persistToDisk || false;
+        const mqttHost = workerData.mqttHost;
+        const instanceName = workerData.instanceNameWithSuffix;
+        const mqttParameters = workerData.mqttParameters;
+        const publisherActive = workerData.publisherActive;
+        const subscriberActive = workerData.subscriberActive;
+        // Initialize and start the MQTT proxy.
+        this.mqttProxy = new MqttProxy(mqttHost, instanceName, mqttParameters, this);
+        this.mqttProxy.start();
+        // Set up the event listener for incoming messages from the MQTT proxy.
+        this.mqttProxy.event.on("input", (event) => {
+            this.subscriber.enqueue(event.topic, event.message.toString());
+        });
+        // Set up the event listener for status messages from the MQTT proxy.
+        this.mqttProxy.event.on("mqttProxyStatus", (event) => {
+            parentPort?.postMessage({
+                command: "mqttProxyStatus",
+                event: event.event,
+                value: event.value,
+                statusTopic: event.statusTopic,
+                uom: event.uom,
+            });
+        });
+        // Define the publish function to be used by the ThrottledPublisher.
+        const publishFunction = async (topic, message, id, options) => {
+            this.mqttProxy.publish(topic, message, options).then(() => {
+                parentPort?.postMessage({
+                    command: "enqueueResult",
+                    id,
+                    status: "success",
+                    topic,
+                    message,
+                    options,
+                });
+            }, (reason) => {
+                logger.error(`${instanceName} - Error publishing message to topic ${topic}: ${reason.message}`);
+            });
+        };
+        // Create an instance of ThrottledPublisher.
+        this.publisher = new ThrottledPublisher(publishThrottlingDelay, publishFunction, persistToDisk, join(basePath, "/workerQueue/", "throttled-publisher-queue.json"), instanceName, publisherActive);
+        // Define the message handler for incoming messages.
+        const messageHandler = async (topic, message) => {
+            parentPort?.postMessage({
+                command: "input",
+                topic: topic,
+                message: message,
+            });
+        };
+        // Create an instance of ThrottledSubscriber.
+        this.subscriber = new ThrottledSubscriber(subscribeThrottlingDelay, messageHandler, persistToDisk, join(basePath, "/workerQueue/", "throttled-subscriber-queue.json"), instanceName, subscriberActive);
+        // Set up the message listener for commands from the main thread.
+        this.initializeMessageListener();
+    }
+    /**
+     * Listen for incoming messages from the main thread and process them.
+     */
+    initializeMessageListener() {
+        parentPort?.on("message", async (msg) => {
+            if (msg && msg.command === "enqueue" && msg.id && msg.topic && msg.message !== undefined) {
+                try {
+                    await this.publisher.enqueue(msg.topic, msg.message, msg.id, msg.options);
+                }
+                catch (error) {
+                    // Error
+                }
+            }
+            else if (msg && msg.command === "subscribeAsync" && msg.topics) {
+                this.mqttProxy.subscribeAsync(msg.topics);
+            }
+            else if (msg && msg.command === "unsubscribeAsync" && msg.topics) {
+                this.mqttProxy.unsubscribeAsync(msg.topics);
+            }
+            else if (msg && msg.command === "setPublisherActive") {
+                this.publisher.becomeActive({ batchSize: msg?.batchSize, referenceHash: msg?.referenceHash });
+            }
+            else if (msg && msg.command === "setPublisherPassive") {
+                const snapshot = await this.publisher.becomePassive(3);
+                parentPort?.postMessage({
+                    command: "handover_publisher",
+                    ...snapshot
+                });
+            }
+            else if (msg && msg.command === "setSubscriberActive") {
+                this.subscriber.becomeActive({ batchSize: msg?.batchSize, referenceHash: msg?.referenceHash });
+            }
+            else if (msg && msg.command === "setSubscriberPassive") {
+                const snapshot = await this.subscriber.becomePassive(3);
+                parentPort?.postMessage({
+                    command: "handover_subscriber",
+                    ...snapshot
+                });
+            }
+        });
+    }
+    /**
+     * Get the state of the publisher.
+     */
+    getPublisherState() {
+        return this.publisher.getState();
+    }
+    /**
+     * Get the state of the subscriber.
+     */
+    getSubscriberState() {
+        return this.subscriber.getState();
+    }
+}

package/dist/uns-mqtt/throttled-queue.d.ts

@@ -0,0 +1,166 @@
+import { IClientPublishOptions } from "mqtt";
+/**
+ * Abstract base class that encapsulates common functionality for managing
+ * a throttled in‑memory queue with an optional disk persistence.
+ */
+declare abstract class ThrottledQueue<T> {
+    protected queue: T[];
+    protected lastProcessedItems: T[];
+    protected isProcessing: boolean;
+    delay: number;
+    protected persistToDisk: boolean;
+    protected persistenceFilePath: string;
+    protected previousLoggedSize: number;
+    protected instanceName: string;
+    protected active: boolean;
+    private inactiveLogSent;
+    constructor(delay: number, persistToDisk: boolean, instanceName: string);
+    /**
+     * Process the queue items one at a time with a delay between each.
+     */
+    protected processQueue(): Promise<void>;
+    /**
+     * Log changes to the queue size at significant thresholds.
+     */
+    protected logQueueSize(): void;
+    /**
+     * Save the current queue to disk.
+     */
+    protected saveQueueToDisk(): void;
+    /**
+     * Load the queue from disk.
+     */
+    protected loadQueueFromDisk(): void;
+    /**
+     * Process a single queue item.
+     */
+    protected abstract processItem(item: T): Promise<void>;
+    /**
+     * Serialize a queue item for persistence.
+     */
+    protected abstract serializeItem(item: T): any;
+    /**
+     * Deserialize persisted data into a queue item.
+     */
+    protected abstract deserializeItem(data: any): T;
+}
+/**
+ * Interface representing a queued publish item.
+ */
+interface PublisherQueueItem {
+    topic: string;
+    message: string;
+    id: string;
+    options?: IClientPublishOptions;
+    resolve: () => void;
+    reject: (err: any) => void;
+}
+/**
+ * ThrottledPublisher: manages a queue of outgoing publish requests,
+ * sending one message at a time using a provided publish function.
+ */
+export declare class ThrottledPublisher extends ThrottledQueue<PublisherQueueItem> {
+    private publishFunction;
+    /**
+     * @param delay Delay between messages in milliseconds.
+     * @param publishFunction Function to perform the actual publish.
+     * @param persistToDisk Whether to persist the queue to disk.
+     * @param persistenceFilePath File path for queue persistence.
+     * @param instanceName Unique instance name for logging.
+     */
+    constructor(delay: number, publishFunction: (topic: string, message: string, id: string, options?: IClientPublishOptions) => Promise<void>, persistToDisk: boolean, persistenceFilePath: string, instanceName: string, active: boolean);
+    /**
+     * Enqueue a publish request.
+     */
+    enqueue(topic: string, message: string, id: string, options?: IClientPublishOptions): Promise<void>;
+    private computeHashForBatch;
+    /**
+     * Switch the publisher to a passive state and return a snapshot
+     */
+    becomeActive(snapshot: {
+        referenceHash: string;
+        batchSize: number;
+    }): void;
+    /**
+     * Switch the publisher to a passive state and return a snapshot
+     */
+    becomePassive(n: number): Promise<{
+        referenceHash: string;
+        batchSize: number;
+    }>;
+    getState(): boolean;
+    /**
+     * Process a single publish request.
+     */
+    protected processItem(item: PublisherQueueItem): Promise<void>;
+    /**
+     * Serialize a publish request for persistence.
+     */
+    protected serializeItem(item: PublisherQueueItem): any;
+    /**
+     * Deserialize persisted data into a publish request.
+     */
+    protected deserializeItem(data: any): PublisherQueueItem;
+}
+/**
+ * Interface representing a queued subscribe item.
+ */
+interface SubscriberQueueItem {
+    topic: string;
+    message: string;
+    timestamp: number;
+}
+/**
+ * ThrottledSubscriber: manages a queue of incoming messages and processes
+ * them one at a time using a provided message handler.
+ */
+export declare class ThrottledSubscriber extends ThrottledQueue<SubscriberQueueItem> {
+    private messageHandler;
+    /**
+     * @param delay Delay between processing messages in milliseconds.
+     * @param messageHandler Function to process incoming messages.
+     * @param persistToDisk Whether to persist the queue to disk.
+     * @param persistenceFilePath File path for queue persistence.
+     * @param instanceName Unique instance name for logging.
+     */
+    constructor(delay: number, messageHandler: (topic: string, message: string) => Promise<void>, persistToDisk: boolean, persistenceFilePath: string, instanceName: string, active: boolean);
+    /**
+     * Enqueue subscribe messages for processing.
+     */
+    enqueue(topic: string, message: string): void;
+    /**
+     * Process a single subscribe message.
+     */
+    protected processItem(item: SubscriberQueueItem): Promise<void>;
+    /**
+     * Serialize a subscribe message for persistence.
+     */
+    protected serializeItem(item: SubscriberQueueItem): any;
+    /**
+     * Deserialize persisted data into a subscribe message.
+     */
+    protected deserializeItem(data: any): SubscriberQueueItem;
+    /**
+     * Get the current state of the subscriber (active or passive).
+     */
+    getState(): boolean;
+    /**
+     * Computes a SHA‑256 hash for a given batch of subscriber items.
+     */
+    private computeHashForBatch;
+    /**
+     * Switch the subscriber to a passive state and return a snapshot.
+     */
+    becomePassive(n: number): Promise<{
+        referenceHash: string;
+        batchSize: number;
+    }>;
+    /**
+     * Switch the subscriber to an active state and resume processing.
+     */
+    becomeActive(snapshot: {
+        referenceHash: string;
+        batchSize: number;
+    }): void;
+}
+export {};