@hotmeshio/hotmesh 0.18.1 → 0.19.1

package/build/modules/enums.d.ts

@@ -133,6 +133,7 @@ export declare const MAX_STREAM_RETRIES: number;
 export declare const MAX_DELAY = 2147483647;
 export declare const HMSH_MAX_RETRIES: number;
 export declare const HMSH_POISON_MESSAGE_THRESHOLD: number;
+export declare const HMSH_MAX_CYCLES: number;
 export declare const HMSH_MAX_TIMEOUT_MS: number;
 export declare const HMSH_GRADUATED_INTERVAL_MS: number;
 /**

package/build/modules/enums.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HMSH_RESERVATION_TIMEOUT_MAX_S = exports.HMSH_RESERVATION_TIMEOUT_S = exports.HMSH_ENGINE_CONCURRENCY = exports.HMSH_BATCH_SIZE_MIN = exports.HMSH_BATCH_SIZE = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_BLOCK_TIME_MS = exports.HMSH_DURABLE_INITIAL_INTERVAL = exports.HMSH_DURABLE_EXP_BACKOFF = exports.HMSH_DURABLE_MAX_INTERVAL = exports.HMSH_DURABLE_MAX_ATTEMPTS = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_POISON_MESSAGE_THRESHOLD = exports.HMSH_MAX_RETRIES = exports.MAX_DELAY = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.HMSH_EXPIRE_JOB_SECONDS = exports.HMSH_OTT_WAIT_TIME = exports.HMSH_DEPLOYMENT_PAUSE = exports.HMSH_DEPLOYMENT_DELAY = exports.HMSH_ACTIVATION_MAX_RETRY = exports.HMSH_QUORUM_DELAY_MS = exports.HMSH_QUORUM_ROLLCALL_CYCLES = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_DURABLE_RETRYABLE = exports.HMSH_CODE_DURABLE_FATAL = exports.HMSH_CODE_DURABLE_MAXED = exports.HMSH_CODE_DURABLE_TIMEOUT = exports.HMSH_CODE_DURABLE_WAIT = exports.HMSH_CODE_DURABLE_CONTINUE = exports.HMSH_CODE_DURABLE_PROXY = exports.HMSH_CODE_DURABLE_CHILD = exports.HMSH_CODE_DURABLE_ALL = exports.HMSH_CODE_DURABLE_SLEEP = exports.HMSH_CODE_UNACKED = exports.HMSH_CODE_TIMEOUT = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_INTERRUPT = exports.HMSH_CODE_NOTFOUND = exports.HMSH_CODE_PENDING = exports.HMSH_CODE_SUCCESS = exports.HMSH_PENDING_SIGNAL_EXPIRE = exports.HMSH_SIGNAL_EXPIRE = exports.HMSH_TELEMETRY = exports.HMSH_LOGLEVEL = void 0;
-exports.HMSH_ROUTER_POLL_FALLBACK_INTERVAL = exports.HMSH_NOTIFY_PAYLOAD_LIMIT = exports.DEFAULT_TASK_QUEUE = exports.HMSH_GUID_SIZE = exports.HMSH_ROUTER_SCOUT_INTERVAL_MS = exports.HMSH_ROUTER_SCOUT_INTERVAL_SECONDS = exports.HMSH_SCOUT_INTERVAL_SECONDS = exports.HMSH_FIDELITY_SECONDS = exports.HMSH_EXPIRE_DURATION = void 0;
+exports.HMSH_RESERVATION_TIMEOUT_S = exports.HMSH_ENGINE_CONCURRENCY = exports.HMSH_BATCH_SIZE_MIN = exports.HMSH_BATCH_SIZE = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_BLOCK_TIME_MS = exports.HMSH_DURABLE_INITIAL_INTERVAL = exports.HMSH_DURABLE_EXP_BACKOFF = exports.HMSH_DURABLE_MAX_INTERVAL = exports.HMSH_DURABLE_MAX_ATTEMPTS = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_MAX_CYCLES = exports.HMSH_POISON_MESSAGE_THRESHOLD = exports.HMSH_MAX_RETRIES = exports.MAX_DELAY = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.HMSH_EXPIRE_JOB_SECONDS = exports.HMSH_OTT_WAIT_TIME = exports.HMSH_DEPLOYMENT_PAUSE = exports.HMSH_DEPLOYMENT_DELAY = exports.HMSH_ACTIVATION_MAX_RETRY = exports.HMSH_QUORUM_DELAY_MS = exports.HMSH_QUORUM_ROLLCALL_CYCLES = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_DURABLE_RETRYABLE = exports.HMSH_CODE_DURABLE_FATAL = exports.HMSH_CODE_DURABLE_MAXED = exports.HMSH_CODE_DURABLE_TIMEOUT = exports.HMSH_CODE_DURABLE_WAIT = exports.HMSH_CODE_DURABLE_CONTINUE = exports.HMSH_CODE_DURABLE_PROXY = exports.HMSH_CODE_DURABLE_CHILD = exports.HMSH_CODE_DURABLE_ALL = exports.HMSH_CODE_DURABLE_SLEEP = exports.HMSH_CODE_UNACKED = exports.HMSH_CODE_TIMEOUT = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_INTERRUPT = exports.HMSH_CODE_NOTFOUND = exports.HMSH_CODE_PENDING = exports.HMSH_CODE_SUCCESS = exports.HMSH_PENDING_SIGNAL_EXPIRE = exports.HMSH_SIGNAL_EXPIRE = exports.HMSH_TELEMETRY = exports.HMSH_LOGLEVEL = void 0;
+exports.HMSH_ROUTER_POLL_FALLBACK_INTERVAL = exports.HMSH_NOTIFY_PAYLOAD_LIMIT = exports.DEFAULT_TASK_QUEUE = exports.HMSH_GUID_SIZE = exports.HMSH_ROUTER_SCOUT_INTERVAL_MS = exports.HMSH_ROUTER_SCOUT_INTERVAL_SECONDS = exports.HMSH_SCOUT_INTERVAL_SECONDS = exports.HMSH_FIDELITY_SECONDS = exports.HMSH_EXPIRE_DURATION = exports.HMSH_RESERVATION_TIMEOUT_MAX_S = void 0;
 /**
  * Determines the log level for the application. The default is 'info'.
  */
@@ -143,6 +143,7 @@ exports.MAX_STREAM_RETRIES = parseInt(process.env.MAX_STREAM_RETRIES, 10) || 2;
 exports.MAX_DELAY = 2147483647; // Maximum allowed delay in milliseconds for setTimeout
 exports.HMSH_MAX_RETRIES = parseInt(process.env.HMSH_MAX_RETRIES, 10) || 3;
 exports.HMSH_POISON_MESSAGE_THRESHOLD = parseInt(process.env.HMSH_POISON_MESSAGE_THRESHOLD, 10) || 5;
+exports.HMSH_MAX_CYCLES = parseInt(process.env.HMSH_MAX_CYCLES, 10) || 10000;
 exports.HMSH_MAX_TIMEOUT_MS = parseInt(process.env.HMSH_MAX_TIMEOUT_MS, 10) || 60000;
 exports.HMSH_GRADUATED_INTERVAL_MS = parseInt(process.env.HMSH_GRADUATED_INTERVAL_MS, 10) || 5000;
 // DURABLE

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.18.1",
+    "version": "0.19.1",
     "description": "Durable Workflow",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",

package/build/services/collator/index.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CollatorService = void 0;
 const errors_1 = require("../../modules/errors");
+const enums_1 = require("../../modules/enums");
 const collator_1 = require("../../types/collator");
 class CollatorService {
     /**
@@ -38,6 +39,13 @@ class CollatorService {
         const ancestors = activity.config.ancestors;
         const ancestorIndex = ancestors.indexOf(targetActivityId);
         const dimensions = activity.metadata.dad.split(','); //e.g., `,0,0,1,0`
+        // Safety cap: prevent infinite cycle loops
+        const currentCycle = parseInt(dimensions[ancestorIndex] || '0', 10);
+        if (currentCycle >= enums_1.HMSH_MAX_CYCLES) {
+            throw new Error(`Cycle limit exceeded for job ${activity.context.metadata.jid} ` +
+                `(${currentCycle} >= HMSH_MAX_CYCLES=${enums_1.HMSH_MAX_CYCLES}) at DAD ${activity.metadata.dad}. ` +
+                `Set HMSH_MAX_CYCLES env var to increase the limit.`);
+        }
         dimensions.length = ancestorIndex + 1;
         dimensions.push('0');
         return dimensions.join(',');

package/build/services/engine/dispatch.js

@@ -16,6 +16,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.processStreamMessage = void 0;
+const errors_1 = require("../../modules/errors");
 const stream_1 = require("../../types/stream");
 async function processStreamMessage(instance, streamData) {
     instance.logger.debug('engine-process', {
@@ -86,7 +87,24 @@ async function dispatchAwait(instance, streamData, context) {
         spn: streamData.metadata.spn,
     };
     const handler = (await instance.initActivity(streamData.metadata.topic, streamData.data, context));
-    await handler.process();
+    try {
+        await handler.process();
+    }
+    catch (error) {
+        if (error instanceof errors_1.DuplicateJobError) {
+            // The child workflow already exists from a prior spawn attempt
+            // (crash recovery). This AWAIT message is a replay — the child
+            // will deliver its RESULT back to the parent via the normal path.
+            // Acknowledge the message so it doesn't loop.
+            instance.logger.info('dispatch-await-child-exists', {
+                childJobId: error.jobId,
+                parentJobId: streamData.metadata.jid,
+                parentDad: streamData.metadata.dad,
+            });
+            return;
+        }
+        throw error;
+    }
 }
 async function dispatchResult(instance, streamData, context) {
     const handler = (await instance.initActivity(`.${context.metadata.aid}`, streamData.data, context));

package/build/services/hotmesh/quorum.js

@@ -25,7 +25,19 @@ async function throttle(instance, options) {
     if (options.guid) {
         throttleMessage.guid = options.guid;
     }
-    if (options.topic !== undefined) {
+    // Scope determines channel targeting:
+    // 'engines' → set topic to null (workers suppress null-topic throttles)
+    // 'workers' → requires a topic to route to worker channels only
+    // 'all' / undefined → default behavior (engines + workers)
+    if (options.scope === 'engines') {
+        throttleMessage.topic = null;
+    }
+    else if (options.scope === 'workers' && !options.topic) {
+        // Workers-only without a specific topic: broadcast to all worker channels
+        // by omitting topic (workers receive on global channel) but NOT setting null
+        // (which would suppress workers). The existing behavior is correct here.
+    }
+    else if (options.topic !== undefined) {
         throttleMessage.topic = options.topic;
     }
     await instance.engine.store.setThrottleRate(throttleMessage);

package/build/services/quorum/index.js

@@ -142,6 +142,7 @@ class QuorumService {
                 timestamp: (0, utils_1.formatISODate)(new Date()),
                 inited: this.engine.inited,
                 throttle: this.engine.router.throttle,
+                is_scout: this.engine.stream.isScout(),
                 reclaimDelay: this.engine.router.reclaimDelay,
                 reclaimCount: this.engine.router.reclaimCount,
                 system: await (0, utils_1.getSystemHealth)(),

package/build/services/stream/index.d.ts

@@ -44,6 +44,8 @@ export declare abstract class StreamService<ClientProvider extends ProviderClien
     }): Promise<StreamMessage[]>;
     reservationTimeout: number;
     abstract getStreamStats(streamName: string): Promise<StreamStats>;
+    /** Whether this instance currently holds the scout role. */
+    abstract isScout(): boolean;
     abstract getStreamDepth(streamName: string): Promise<number>;
     abstract getStreamDepths(streamName: {
         stream: string;

package/build/services/stream/providers/nats/nats.d.ts

@@ -33,6 +33,7 @@ declare class NatsStreamService extends StreamService<NatsClientType, NatsPubAck
         maxRetries?: number;
         limit?: number;
     }): Promise<StreamMessage[]>;
+    isScout(): boolean;
     getStreamStats(streamName: string): Promise<StreamStats>;
     getStreamDepth(streamName: string): Promise<number>;
     getStreamDepths(streamNames: {

package/build/services/stream/providers/nats/nats.js

@@ -153,6 +153,9 @@ class NatsStreamService extends index_1.StreamService {
     async retryMessages(streamName, groupName, options) {
         return [];
     }
+    isScout() {
+        return false; // NATS doesn't use the scout pattern
+    }
     async getStreamStats(streamName) {
         try {
             const info = await this.jsm.streams.info(streamName);

package/build/services/stream/providers/postgres/postgres.d.ts

@@ -96,6 +96,7 @@ declare class PostgresStreamService extends StreamService<PostgresClientType & P
         maxRetries?: number;
         limit?: number;
     }): Promise<StreamMessage[]>;
+    isScout(): boolean;
     getStreamStats(streamName: string): Promise<StreamStats>;
     getStreamDepth(streamName: string): Promise<number>;
     getStreamDepths(streamNames: {

package/build/services/stream/providers/postgres/postgres.js

@@ -290,6 +290,9 @@ class PostgresStreamService extends index_1.StreamService {
     async retryMessages(streamName, groupName, options) {
         return Messages.retryMessages(streamName, groupName, options);
     }
+    isScout() {
+        return this.scoutManager?.isCurrentlyScout() ?? false;
+    }
     async getStreamStats(streamName) {
         const target = this.resolveStreamTarget(streamName);
         return Stats.getStreamStats(this.streamClient, target.tableName, target.streamName, this.logger);

package/build/types/quorum.d.ts

@@ -29,6 +29,8 @@ export type ThrottleOptions = {
     guid?: string;
     /** target a worker quorum */
     topic?: string;
+    /** target engines only, workers only, or all (default: 'all') */
+    scope?: 'engines' | 'workers' | 'all';
     /** delay in milliseconds: 0 = resume, -1 = pause, >0 = delay per message */
     throttle: number;
 };
@@ -78,6 +80,8 @@ export interface QuorumProfile {
     reclaimDelay?: number;
     /** Max messages to reclaim per cycle. */
     reclaimCount?: number;
+    /** Whether this engine currently holds the scout role (polls for delayed messages). */
+    is_scout?: boolean;
     /** Host-level memory, CPU, and network stats. */
     system?: SystemHealth;
     /** Stringified worker callback function (only if `signature: true` in rollcall). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.18.1",
+  "version": "0.19.1",
   "description": "Durable Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",