@hotmeshio/hotmesh 0.12.1 → 0.14.0

package/build/services/hotmesh/init.d.ts

@@ -0,0 +1,42 @@
+import { EngineService } from '../engine';
+import { ILogger } from '../logger';
+import { QuorumService } from '../quorum';
+import { WorkerService } from '../worker';
+import { HotMeshConfig } from '../../types/hotmesh';
+import { ProviderConfig, ProvidersConfig } from '../../types/provider';
+import { RetryPolicy } from '../../types/stream';
+interface InitContext {
+    namespace: string;
+    appId: string;
+    guid: string;
+    engine: EngineService | null;
+    quorum: QuorumService | null;
+    workers: WorkerService[];
+}
+/**
+ * @private
+ */
+export declare function initEngine(instance: InitContext, config: HotMeshConfig, logger: ILogger): Promise<void>;
+/**
+ * @private
+ */
+export declare function initQuorum(instance: InitContext, config: HotMeshConfig, engine: EngineService, logger: ILogger): Promise<void>;
+/**
+ * @private
+ */
+export declare function doWork(instance: InitContext, config: HotMeshConfig, logger: ILogger): Promise<void>;
+/**
+ * Initialize task queue with proper precedence:
+ * 1. Use component-specific queue if set (engine/worker)
+ * 2. Use global config queue if set
+ * 3. Use default queue as fallback
+ * @private
+ */
+export declare function initTaskQueue(componentQueue?: string, globalQueue?: string): string;
+/**
+ * Apply retry policy to the stream connection within a ProviderConfig or ProvidersConfig.
+ * Handles both short-form (ProviderConfig) and long-form (ProvidersConfig) connection configs.
+ * @private
+ */
+export declare function applyRetryPolicy(connection: ProviderConfig | ProvidersConfig, retry: RetryPolicy): void;
+export {};

package/build/services/hotmesh/init.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyRetryPolicy = exports.initTaskQueue = exports.doWork = exports.initQuorum = exports.initEngine = void 0;
+const factory_1 = require("../connector/factory");
+const engine_1 = require("../engine");
+const quorum_1 = require("../quorum");
+const worker_1 = require("../worker");
+const enums_1 = require("../../modules/enums");
+/**
+ * @private
+ */
+async function initEngine(instance, config, logger) {
+    if (config.engine) {
+        //connections that are 'readonly' transfer
+        //this property directly to the engine,
+        //and ALWAYS take precendence.
+        if (config.engine.connection.readonly) {
+            config.engine.readonly = true;
+        }
+        // Apply retry policy to stream connection if provided
+        if (config.engine.retry) {
+            applyRetryPolicy(config.engine.connection, config.engine.retry);
+        }
+        // Initialize task queue for engine
+        config.engine.taskQueue = initTaskQueue(config.engine.taskQueue, config.taskQueue);
+        await factory_1.ConnectorService.initClients(config.engine);
+        instance.engine = await engine_1.EngineService.init(instance.namespace, instance.appId, instance.guid, config, logger);
+    }
+}
+exports.initEngine = initEngine;
+/**
+ * @private
+ */
+async function initQuorum(instance, config, engine, logger) {
+    if (engine) {
+        instance.quorum = await quorum_1.QuorumService.init(instance.namespace, instance.appId, instance.guid, config, engine, logger);
+    }
+}
+exports.initQuorum = initQuorum;
+/**
+ * @private
+ */
+async function doWork(instance, config, logger) {
+    // Initialize task queues for workers
+    if (config.workers) {
+        for (const worker of config.workers) {
+            // Apply retry policy to stream connection if provided
+            if (worker.retry) {
+                applyRetryPolicy(worker.connection, worker.retry);
+            }
+            worker.taskQueue = initTaskQueue(worker.taskQueue, config.taskQueue);
+        }
+    }
+    instance.workers = await worker_1.WorkerService.init(instance.namespace, instance.appId, instance.guid, config, logger);
+}
+exports.doWork = doWork;
+/**
+ * Initialize task queue with proper precedence:
+ * 1. Use component-specific queue if set (engine/worker)
+ * 2. Use global config queue if set
+ * 3. Use default queue as fallback
+ * @private
+ */
+function initTaskQueue(componentQueue, globalQueue) {
+    // Component-specific queue takes precedence
+    if (componentQueue) {
+        return componentQueue;
+    }
+    // Global config queue is next
+    if (globalQueue) {
+        return globalQueue;
+    }
+    // Default queue as fallback
+    return enums_1.DEFAULT_TASK_QUEUE;
+}
+exports.initTaskQueue = initTaskQueue;
+/**
+ * Apply retry policy to the stream connection within a ProviderConfig or ProvidersConfig.
+ * Handles both short-form (ProviderConfig) and long-form (ProvidersConfig) connection configs.
+ * @private
+ */
+function applyRetryPolicy(connection, retry) {
+    // Check if this is ProvidersConfig (has 'stream' property)
+    if ('stream' in connection && connection.stream) {
+        // Long-form: apply to the stream sub-config
+        connection.stream.retry = retry;
+    }
+    else {
+        // Short-form: apply directly to the connection
+        connection.retry = retry;
+    }
+}
+exports.applyRetryPolicy = applyRetryPolicy;

package/build/services/hotmesh/jobs.d.ts

@@ -0,0 +1,67 @@
+import { EngineService } from '../engine';
+import { JobData, JobOutput, JobStatus, JobInterruptOptions } from '../../types/job';
+import { ExportOptions, JobExport } from '../../types/exporter';
+import { StringAnyType, StringStringType } from '../../types/serializer';
+import { JobStatsInput, GetStatsOptions, IdsResponse, StatsResponse } from '../../types/stats';
+import { StreamCode, StreamStatus } from '../../types/stream';
+interface JobsContext {
+    engine: EngineService | null;
+}
+/**
+ * Exports the full job state as a structured JSON object.
+ */
+export declare function exportJob(instance: JobsContext, jobId: string, options?: ExportOptions): Promise<JobExport>;
+/**
+ * Returns all raw key-value pairs for a job's HASH record.
+ */
+export declare function getRaw(instance: JobsContext, jobId: string): Promise<StringStringType>;
+/**
+ * Reporter-related method to get the status of a job.
+ * @private
+ */
+export declare function getStats(instance: JobsContext, topic: string, query: JobStatsInput): Promise<StatsResponse>;
+/**
+ * Returns the numeric status semaphore for a job.
+ */
+export declare function getStatus(instance: JobsContext, jobId: string): Promise<JobStatus>;
+/**
+ * Returns the structured job state (data and metadata) for a job.
+ */
+export declare function getState(instance: JobsContext, topic: string, jobId: string): Promise<JobOutput>;
+/**
+ * Returns specific searchable fields from a job's HASH record.
+ */
+export declare function getQueryState(instance: JobsContext, jobId: string, fields: string[]): Promise<StringAnyType>;
+/**
+ * @private
+ */
+export declare function getIds(instance: JobsContext, topic: string, query: JobStatsInput, queryFacets?: string[]): Promise<IdsResponse>;
+/**
+ * @private
+ */
+export declare function resolveQuery(instance: JobsContext, topic: string, query: JobStatsInput): Promise<GetStatsOptions>;
+/**
+ * Interrupts (terminates) an active workflow job.
+ */
+export declare function interrupt(instance: JobsContext, topic: string, jobId: string, options?: JobInterruptOptions): Promise<string>;
+/**
+ * Requests cooperative cancellation of an active workflow job.
+ * Writes a durable cancel marker to the job hash via the store.
+ * The workflow detects this at its next durable operation and
+ * throws CancelledFailure which can be caught for cleanup.
+ */
+export declare function cancel(instance: JobsContext, jobId: string): Promise<void>;
+/**
+ * Immediately deletes a completed job from the system.
+ */
+export declare function scrub(instance: JobsContext, jobId: string): Promise<void>;
+/**
+ * Sends a signal to a paused workflow, resuming its execution.
+ */
+export declare function signal(instance: JobsContext, topic: string, data: JobData, status?: StreamStatus, code?: StreamCode): Promise<string>;
+/**
+ * Fan-out variant of `signal()`.
+ * @private
+ */
+export declare function signalAll(instance: JobsContext, hookTopic: string, data: JobData, query: JobStatsInput, queryFacets?: string[]): Promise<string[]>;
+export {};

package/build/services/hotmesh/jobs.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signalAll = exports.signal = exports.scrub = exports.cancel = exports.interrupt = exports.resolveQuery = exports.getIds = exports.getQueryState = exports.getState = exports.getStatus = exports.getStats = exports.getRaw = exports.exportJob = void 0;
+/**
+ * Exports the full job state as a structured JSON object.
+ */
+async function exportJob(instance, jobId, options = {}) {
+    return await instance.engine?.export(jobId, options);
+}
+exports.exportJob = exportJob;
+/**
+ * Returns all raw key-value pairs for a job's HASH record.
+ */
+async function getRaw(instance, jobId) {
+    return await instance.engine?.getRaw(jobId);
+}
+exports.getRaw = getRaw;
+/**
+ * Reporter-related method to get the status of a job.
+ * @private
+ */
+async function getStats(instance, topic, query) {
+    return await instance.engine?.getStats(topic, query);
+}
+exports.getStats = getStats;
+/**
+ * Returns the numeric status semaphore for a job.
+ */
+async function getStatus(instance, jobId) {
+    return instance.engine?.getStatus(jobId);
+}
+exports.getStatus = getStatus;
+/**
+ * Returns the structured job state (data and metadata) for a job.
+ */
+async function getState(instance, topic, jobId) {
+    return instance.engine?.getState(topic, jobId);
+}
+exports.getState = getState;
+/**
+ * Returns specific searchable fields from a job's HASH record.
+ */
+async function getQueryState(instance, jobId, fields) {
+    return await instance.engine?.getQueryState(jobId, fields);
+}
+exports.getQueryState = getQueryState;
+/**
+ * @private
+ */
+async function getIds(instance, topic, query, queryFacets = []) {
+    return await instance.engine?.getIds(topic, query, queryFacets);
+}
+exports.getIds = getIds;
+/**
+ * @private
+ */
+async function resolveQuery(instance, topic, query) {
+    return await instance.engine?.resolveQuery(topic, query);
+}
+exports.resolveQuery = resolveQuery;
+/**
+ * Interrupts (terminates) an active workflow job.
+ */
+async function interrupt(instance, topic, jobId, options = {}) {
+    return await instance.engine?.interrupt(topic, jobId, options);
+}
+exports.interrupt = interrupt;
+/**
+ * Requests cooperative cancellation of an active workflow job.
+ * Writes a durable cancel marker to the job hash via the store.
+ * The workflow detects this at its next durable operation and
+ * throws CancelledFailure which can be caught for cleanup.
+ */
+async function cancel(instance, jobId) {
+    await instance.engine?.store.setCancel(jobId, instance.engine.appId);
+}
+exports.cancel = cancel;
+/**
+ * Immediately deletes a completed job from the system.
+ */
+async function scrub(instance, jobId) {
+    await instance.engine?.scrub(jobId);
+}
+exports.scrub = scrub;
+/**
+ * Sends a signal to a paused workflow, resuming its execution.
+ */
+async function signal(instance, topic, data, status, code) {
+    return await instance.engine?.signal(topic, data, status, code);
+}
+exports.signal = signal;
+/**
+ * Fan-out variant of `signal()`.
+ * @private
+ */
+async function signalAll(instance, hookTopic, data, query, queryFacets = []) {
+    return await instance.engine?.signalAll(hookTopic, data, query, queryFacets);
+}
+exports.signalAll = signalAll;

package/build/services/hotmesh/pubsub.d.ts

@@ -0,0 +1,38 @@
+import { EngineService } from '../engine';
+import { JobState, JobData, JobOutput, ExtensionType } from '../../types/job';
+import { JobMessageCallback } from '../../types/quorum';
+import { StreamData, StreamDataResponse } from '../../types/stream';
+interface PubSubContext {
+    engine: EngineService | null;
+}
+/**
+ * Publishes a message to a workflow topic, starting a new job.
+ * Returns the job ID immediately (fire-and-forget).
+ */
+export declare function pub(instance: PubSubContext, topic: string, data?: JobData, context?: JobState, extended?: ExtensionType): Promise<string>;
+/**
+ * Subscribes to all output and interim emissions from a specific workflow topic.
+ */
+export declare function sub(instance: PubSubContext, topic: string, callback: JobMessageCallback): Promise<void>;
+/**
+ * Unsubscribes from a single workflow topic previously registered with `sub()`.
+ */
+export declare function unsub(instance: PubSubContext, topic: string): Promise<void>;
+/**
+ * Subscribes to workflow emissions matching a wildcard pattern.
+ */
+export declare function psub(instance: PubSubContext, wild: string, callback: JobMessageCallback): Promise<void>;
+/**
+ * Unsubscribes from a wildcard pattern previously registered with `psub()`.
+ */
+export declare function punsub(instance: PubSubContext, wild: string): Promise<void>;
+/**
+ * Publishes a message to a workflow topic and blocks until the workflow completes.
+ */
+export declare function pubsub(instance: PubSubContext, topic: string, data?: JobData, context?: JobState | null, timeout?: number): Promise<JobOutput>;
+/**
+ * Adds a transition message to the workstream, resuming Leg 2 of a paused
+ * reentrant activity.
+ */
+export declare function add(instance: PubSubContext, streamData: StreamData | StreamDataResponse): Promise<string>;
+export {};

package/build/services/hotmesh/pubsub.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.add = exports.pubsub = exports.punsub = exports.psub = exports.unsub = exports.sub = exports.pub = void 0;
+/**
+ * Publishes a message to a workflow topic, starting a new job.
+ * Returns the job ID immediately (fire-and-forget).
+ */
+async function pub(instance, topic, data = {}, context, extended) {
+    return await instance.engine?.pub(topic, data, context, extended);
+}
+exports.pub = pub;
+/**
+ * Subscribes to all output and interim emissions from a specific workflow topic.
+ */
+async function sub(instance, topic, callback) {
+    return await instance.engine?.sub(topic, callback);
+}
+exports.sub = sub;
+/**
+ * Unsubscribes from a single workflow topic previously registered with `sub()`.
+ */
+async function unsub(instance, topic) {
+    return await instance.engine?.unsub(topic);
+}
+exports.unsub = unsub;
+/**
+ * Subscribes to workflow emissions matching a wildcard pattern.
+ */
+async function psub(instance, wild, callback) {
+    return await instance.engine?.psub(wild, callback);
+}
+exports.psub = psub;
+/**
+ * Unsubscribes from a wildcard pattern previously registered with `psub()`.
+ */
+async function punsub(instance, wild) {
+    return await instance.engine?.punsub(wild);
+}
+exports.punsub = punsub;
+/**
+ * Publishes a message to a workflow topic and blocks until the workflow completes.
+ */
+async function pubsub(instance, topic, data = {}, context, timeout) {
+    return await instance.engine?.pubsub(topic, data, context, timeout);
+}
+exports.pubsub = pubsub;
+/**
+ * Adds a transition message to the workstream, resuming Leg 2 of a paused
+ * reentrant activity.
+ */
+async function add(instance, streamData) {
+    return (await instance.engine.add(streamData));
+}
+exports.add = add;

package/build/services/hotmesh/quorum.d.ts

@@ -0,0 +1,30 @@
+import { EngineService } from '../engine';
+import { QuorumService } from '../quorum';
+import { WorkerService } from '../worker';
+import { QuorumMessage, QuorumMessageCallback, QuorumProfile, ThrottleOptions } from '../../types/quorum';
+interface QuorumContext {
+    engine: EngineService | null;
+    quorum: QuorumService | null;
+    workers: WorkerService[];
+}
+/**
+ * Broadcasts a roll call across the mesh and collects responses.
+ */
+export declare function rollCall(instance: QuorumContext, delay?: number): Promise<QuorumProfile[]>;
+/**
+ * Broadcasts a throttle command to the mesh via the quorum channel.
+ */
+export declare function throttle(instance: QuorumContext, options: ThrottleOptions): Promise<boolean>;
+/**
+ * Publishes a message to every mesh member via the quorum channel.
+ */
+export declare function pubQuorum(instance: QuorumContext, quorumMessage: QuorumMessage): Promise<boolean>;
+/**
+ * Subscribes to the quorum channel.
+ */
+export declare function subQuorum(instance: QuorumContext, callback: QuorumMessageCallback): Promise<void>;
+/**
+ * Unsubscribes a callback previously registered with `subQuorum()`.
+ */
+export declare function unsubQuorum(instance: QuorumContext, callback: QuorumMessageCallback): Promise<void>;
+export {};

package/build/services/hotmesh/quorum.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unsubQuorum = exports.subQuorum = exports.pubQuorum = exports.throttle = exports.rollCall = void 0;
+const enums_1 = require("../../modules/enums");
+/**
+ * Broadcasts a roll call across the mesh and collects responses.
+ */
+async function rollCall(instance, delay) {
+    return await instance.quorum?.rollCall(delay);
+}
+exports.rollCall = rollCall;
+/**
+ * Broadcasts a throttle command to the mesh via the quorum channel.
+ */
+async function throttle(instance, options) {
+    let throttleValue;
+    if (options.throttle === -1) {
+        throttleValue = enums_1.MAX_DELAY;
+    }
+    else {
+        throttleValue = options.throttle;
+    }
+    if (!Number.isInteger(throttleValue) ||
+        throttleValue < 0 ||
+        throttleValue > enums_1.MAX_DELAY) {
+        throw new Error(`Throttle must be a non-negative integer and not exceed ${enums_1.MAX_DELAY} ms; send -1 to throttle indefinitely`);
+    }
+    const throttleMessage = {
+        type: 'throttle',
+        throttle: throttleValue,
+    };
+    if (options.guid) {
+        throttleMessage.guid = options.guid;
+    }
+    if (options.topic !== undefined) {
+        throttleMessage.topic = options.topic;
+    }
+    await instance.engine.store.setThrottleRate(throttleMessage);
+    return await instance.quorum?.pub(throttleMessage);
+}
+exports.throttle = throttle;
+/**
+ * Publishes a message to every mesh member via the quorum channel.
+ */
+async function pubQuorum(instance, quorumMessage) {
+    return await instance.quorum?.pub(quorumMessage);
+}
+exports.pubQuorum = pubQuorum;
+/**
+ * Subscribes to the quorum channel.
+ */
+async function subQuorum(instance, callback) {
+    return await instance.quorum?.sub(callback);
+}
+exports.subQuorum = subQuorum;
+/**
+ * Unsubscribes a callback previously registered with `subQuorum()`.
+ */
+async function unsubQuorum(instance, callback) {
+    return await instance.quorum?.unsub(callback);
+}
+exports.unsubQuorum = unsubQuorum;

package/build/services/hotmesh/validation.d.ts

@@ -0,0 +1,6 @@
+export declare function verifyAndSetNamespace(instance: {
+    namespace: string;
+}, namespace?: string): void;
+export declare function verifyAndSetAppId(instance: {
+    appId: string;
+}, appId: string): void;

package/build/services/hotmesh/validation.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyAndSetAppId = exports.verifyAndSetNamespace = void 0;
+const key_1 = require("../../modules/key");
+function verifyAndSetNamespace(instance, namespace) {
+    if (!namespace) {
+        instance.namespace = key_1.HMNS;
+    }
+    else if (!namespace.match(/^[A-Za-z0-9-]+$/)) {
+        throw new Error(`config.namespace [${namespace}] is invalid`);
+    }
+    else {
+        instance.namespace = namespace;
+    }
+}
+exports.verifyAndSetNamespace = verifyAndSetNamespace;
+function verifyAndSetAppId(instance, appId) {
+    if (!appId?.match(/^[A-Za-z0-9-]+$/)) {
+        throw new Error(`config.appId [${appId}] is invalid`);
+    }
+    else if (appId === 'a') {
+        throw new Error(`config.appId [${appId}] is reserved`);
+    }
+    else {
+        instance.appId = appId;
+    }
+}
+exports.verifyAndSetAppId = verifyAndSetAppId;

package/build/services/quorum/index.js

@@ -134,6 +134,7 @@ class QuorumService {
                 app_id: this.appId,
                 stream,
                 counts: this.engine.router.counts,
+                error_count: this.engine.router.errorCount,
                 timestamp: (0, utils_1.formatISODate)(new Date()),
                 inited: this.engine.inited,
                 throttle: this.engine.router.throttle,

package/build/services/router/consumption/index.d.ts

@@ -15,12 +15,18 @@ export declare class ConsumptionManager<S extends StreamService<ProviderClient,
     private reclaimCount;
     private appId;
     private role;
-    private errorCount;
-    private counts;
-    private hasReachedMaxBackoff;
+    /**
+     * Consumption stats are written directly to the parent Router so
+     * they are visible in quorum rollcall profiles.
+     */
+    private get errorCount();
+    private set errorCount(value);
+    private get counts();
+    private get hasReachedMaxBackoff();
+    private set hasReachedMaxBackoff(value);
     private router;
-    private retryPolicy;
-    constructor(stream: S, logger: ILogger, throttleManager: ThrottleManager, errorHandler: ErrorHandler, lifecycleManager: LifecycleManager<S>, reclaimDelay: number, reclaimCount: number, appId: string, role: any, router: any, retryPolicy?: import('../../../types/stream').RetryPolicy);
+    private retry;
+    constructor(stream: S, logger: ILogger, throttleManager: ThrottleManager, errorHandler: ErrorHandler, lifecycleManager: LifecycleManager<S>, reclaimDelay: number, reclaimCount: number, appId: string, role: any, router: any, retry?: import('../../../types/stream').RetryPolicy);
     createGroup(stream: string, group: string): Promise<void>;
     publishMessage(topic: string, streamData: StreamData | StreamDataResponse, transaction?: ProviderTransaction): Promise<string | ProviderTransaction>;
     consumeMessages(stream: string, group: string, consumer: string, callback: (streamData: StreamData) => Promise<StreamDataResponse | void>): Promise<void>;