@hotmeshio/hotmesh 0.0.52 → 0.0.54

package/build/services/durable/search.js

@@ -46,8 +46,8 @@ class Search {
                 const prefixes = search.prefix.map((prefix) => `${hotMeshPrefix}${prefix}`);
                 await store.exec('FT.CREATE', `${search.index}`, 'ON', 'HASH', 'PREFIX', prefixes.length.toString(), ...prefixes, 'SCHEMA', ...schema);
             }
-            catch (err) {
-                hotMeshClient.engine.logger.info('durable-client-search-err', { err });
+            catch (error) {
+                hotMeshClient.engine.logger.info('durable-client-search-err', { ...error });
             }
         }
     }
@@ -63,8 +63,8 @@ class Search {
             const searchIndexes = await store.exec('FT._LIST');
             return searchIndexes;
         }
-        catch (err) {
-            hotMeshClient.engine.logger.info('durable-client-search-list-err', { err });
+        catch (error) {
+            hotMeshClient.engine.logger.info('durable-client-search-list-err', { ...error });
             return [];
         }
     }
@@ -103,8 +103,8 @@ class Search {
         try {
             return await this.store.exec('HGET', this.jobId, this.safeKey(key));
         }
-        catch (err) {
-            this.hotMeshClient.logger.error('durable-search-get-error', { err });
+        catch (error) {
+            this.hotMeshClient.logger.error('durable-search-get-error', { ...error });
             return '';
         }
     }
@@ -116,8 +116,8 @@ class Search {
         try {
             return await this.store.exec('HMGET', this.jobId, ...safeArgs);
         }
-        catch (err) {
-            this.hotMeshClient.logger.error('durable-search-mget-error', { err });
+        catch (error) {
+            this.hotMeshClient.logger.error('durable-search-mget-error', { ...error });
             return [];
         }
     }

package/build/services/durable/worker.js

@@ -1,14 +1,19 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkerService = void 0;
+const ms_1 = __importDefault(require("ms"));
+const enums_1 = require("../../modules/enums");
 const errors_1 = require("../../modules/errors");
 const storage_1 = require("../../modules/storage");
-const factory_1 = require("./factory");
+const factory_1 = require("./schemas/factory");
 const hotmesh_1 = require("../hotmesh");
 const search_1 = require("./search");
 const stream_1 = require("../../types/stream");
-const enums_1 = require("../../modules/enums");
+const utils_1 = require("../../modules/utils");
 class WorkerService {
     static async activateWorkflow(hotMesh) {
         const app = await hotMesh.engine.store.getApp(hotMesh.engine.appId);
@@ -99,6 +104,7 @@ class WorkerService {
         WorkerService.instances.set(activityTopic, hotMeshWorker);
         return hotMeshWorker;
     }
+    //this is the linked worker function in the reentrant workflow test
     wrapActivityFunctions() {
         return async (data) => {
             try {
@@ -114,17 +120,40 @@ class WorkerService {
                 };
             }
             catch (err) {
-                this.activityRunner.engine.logger.error('durable-worker-activity-err', err);
+                this.activityRunner.engine.logger.error('durable-worker-activity-err', { name: err.name, message: err.message, stack: err.stack });
                 if (!(err instanceof errors_1.DurableTimeoutError) &&
                     !(err instanceof errors_1.DurableMaxedError) &&
                     !(err instanceof errors_1.DurableFatalError)) {
-                    err = new errors_1.DurableRetryError(err.message);
+                    //use code 599 as a proxy for all retryable errors
+                    // (basically anything not 596, 597, 598)
+                    return {
+                        status: stream_1.StreamStatus.SUCCESS,
+                        code: enums_1.HMSH_CODE_DURABLE_RETRYABLE,
+                        metadata: { ...data.metadata },
+                        data: {
+                            $error: {
+                                message: err.message,
+                                stack: err.stack,
+                                timestamp: (0, utils_1.formatISODate)(new Date()),
+                            }
+                        },
+                    };
                 }
                 return {
-                    status: stream_1.StreamStatus.ERROR,
+                    //always returrn success (the Durable module is just fine);
+                    //  it's the user's function that has failed
+                    status: stream_1.StreamStatus.SUCCESS,
                     code: err.code,
+                    stack: err.stack,
                     metadata: { ...data.metadata },
-                    data: { message: err.message }
+                    data: {
+                        $error: {
+                            message: err.message,
+                            stack: err.stack,
+                            timestamp: (0, utils_1.formatISODate)(new Date()),
+                            code: err.code,
+                        }
+                    },
                 };
             }
         };
@@ -150,14 +179,16 @@ class WorkerService {
     wrapWorkflowFunction(workflowFunction, workflowTopic, config) {
         return async (data) => {
             const counter = { counter: 0 };
+            const interruptionRegistry = [];
             try {
                 //incoming data payload has arguments and workflowId
                 const workflowInput = data.data;
                 const context = new Map();
-                context.set('raw', data);
-                context.set('namespace', config.namespace ?? factory_1.APP_ID);
+                context.set('canRetry', workflowInput.canRetry);
                 context.set('counter', counter);
-                context.set('workflowId', workflowInput.workflowId);
+                context.set('interruptionRegistry', interruptionRegistry);
+                context.set('namespace', config.namespace ?? factory_1.APP_ID);
+                context.set('raw', data);
                 context.set('workflowId', workflowInput.workflowId);
                 if (workflowInput.originJobId) {
                     //if present there is an origin job to which this job is subordinated; 
@@ -173,8 +204,8 @@ class WorkerService {
                     replayQuery = `-*${workflowInput.workflowDimension}-*`;
                 }
                 else {
-                    //last letter of words like 'hook', 'sleep', 'wait', 'signal', 'search', 'start'
-                    replayQuery = '-*[ehklpt]-*';
+                    //last letter of words like 'hook', 'sleep', 'wait', 'signal', 'search', 'start', 'proxy', 'child', 'collator'
+                    replayQuery = '-*[ehklptydr]-*';
                 }
                 context.set('workflowTopic', workflowTopic);
                 context.set('workflowName', workflowTopic.split('-').pop());
@@ -195,49 +226,110 @@ class WorkerService {
                 };
             }
             catch (err) {
-                //not an error...just a trigger to sleep
-                if (err instanceof errors_1.DurableSleepForError) {
+                if (err instanceof errors_1.DurableWaitForError || interruptionRegistry.length > 1) {
+                    //NOTE: this type is spawned when `Promise.all` is used OR if the interruption is a `waitFor`
+                    const workflowInput = data.data;
+                    const execIndex = counter.counter - interruptionRegistry.length + 1;
+                    const { workflowId, workflowTopic, workflowDimension, originJobId } = workflowInput;
+                    const collatorFlowId = `-${workflowId}-$${workflowDimension || ''}-$${execIndex}`;
+                    return {
+                        status: stream_1.StreamStatus.SUCCESS,
+                        code: enums_1.HMSH_CODE_DURABLE_ALL,
+                        metadata: { ...data.metadata },
+                        data: {
+                            code: enums_1.HMSH_CODE_DURABLE_ALL,
+                            items: [...interruptionRegistry],
+                            size: interruptionRegistry.length,
+                            workflowDimension: workflowDimension || '',
+                            index: execIndex,
+                            originJobId: originJobId || workflowId,
+                            parentWorkflowId: workflowId,
+                            workflowId: collatorFlowId,
+                            workflowTopic: workflowTopic,
+                        },
+                    };
+                }
+                else if (err instanceof errors_1.DurableSleepError) {
+                    //return the sleep interruption
                     return {
                         status: stream_1.StreamStatus.SUCCESS,
                         code: err.code,
                         metadata: { ...data.metadata },
                         data: {
                             code: err.code,
-                            message: JSON.stringify({ duration: err.duration, index: err.index, dimension: err.dimension }),
+                            message: JSON.stringify({ duration: err.duration, index: err.index, workflowDimension: err.workflowDimension }),
                             duration: err.duration,
                             index: err.index,
-                            dimension: err.dimension
+                            workflowDimension: err.workflowDimension,
                         }
                     };
-                    //not an error...just a trigger to wait for a signal
                 }
-                else if (err instanceof errors_1.DurableWaitForSignalError) {
+                else if (err instanceof errors_1.DurableProxyError) {
+                    //return the proxyActivity interruption
                     return {
                         status: stream_1.StreamStatus.SUCCESS,
                         code: err.code,
                         metadata: { ...data.metadata },
                         data: {
                             code: err.code,
-                            signals: err.signals,
-                            index: err.signals[0].index
+                            message: JSON.stringify({ message: err.message, workflowId: err.workflowId, activityName: err.activityName, dimension: err.workflowDimension }),
+                            arguments: err.arguments,
+                            workflowDimension: err.workflowDimension,
+                            index: err.index,
+                            originJobId: err.originJobId,
+                            parentWorkflowId: err.parentWorkflowId,
+                            workflowId: err.workflowId,
+                            workflowTopic: err.workflowTopic,
+                            activityName: err.activityName,
+                            backoffCoefficient: err.backoffCoefficient,
+                            maximumAttempts: err.maximumAttempts,
+                            maximumInterval: err.maximumInterval,
                         }
                     };
-                    //not an error...still waiting for all the signals to arrive
                 }
-                else if (err instanceof errors_1.DurableIncompleteSignalError) {
+                else if (err instanceof errors_1.DurableChildError) {
+                    //return the child interruption
+                    const msg = {
+                        message: err.message,
+                        workflowId: err.workflowId,
+                        dimension: err.workflowDimension
+                    };
                     return {
                         status: stream_1.StreamStatus.SUCCESS,
                         code: err.code,
                         metadata: { ...data.metadata },
-                        data: { code: err.code }
+                        data: {
+                            arguments: err.arguments,
+                            await: err.await,
+                            backoffCoefficient: err.backoffCoefficient || enums_1.HMSH_DURABLE_EXP_BACKOFF,
+                            code: err.code,
+                            index: err.index,
+                            message: JSON.stringify(msg),
+                            maximumAttempts: err.maximumAttempts || enums_1.HMSH_DURABLE_MAX_ATTEMPTS,
+                            maximumInterval: err.maximumInterval || (0, ms_1.default)(enums_1.HMSH_DURABLE_MAX_INTERVAL) / 1000,
+                            originJobId: err.originJobId,
+                            parentWorkflowId: err.parentWorkflowId,
+                            workflowDimension: err.workflowDimension,
+                            workflowId: err.workflowId,
+                            workflowTopic: err.workflowTopic,
+                        }
                     };
                 }
-                // all other errors are fatal (598, 597, 596) or will be retried (599)
+                // ALL other errors are actual fatal errors (598, 597, 596)
+                //  OR will be retried (599)
                 return {
-                    status: stream_1.StreamStatus.ERROR,
+                    status: stream_1.StreamStatus.SUCCESS,
                     code: err.code || new errors_1.DurableRetryError(err.message).code,
                     metadata: { ...data.metadata },
-                    data: { message: err.message, type: err.name }
+                    data: {
+                        $error: {
+                            message: err.message,
+                            type: err.name,
+                            name: err.name,
+                            stack: err.stack,
+                            code: err.code || new errors_1.DurableRetryError(err.message).code,
+                        }
+                    }
                 };
             }
         };

package/build/services/durable/workflow.d.ts

@@ -2,31 +2,68 @@ import { Search } from './search';
 import { HotMeshService as HotMesh } from '../hotmesh';
 import { ActivityConfig, HookOptions, ProxyType, WorkflowContext, WorkflowOptions } from "../../types/durable";
 import { JobInterruptOptions } from '../../types/job';
+import { DurableChildErrorType, DurableProxyErrorType } from '../../types/error';
 export declare class WorkflowService {
     /**
-     * Spawns a child workflow. await and return the result.
+     * Returns the synchronous output from the activity (replay)
+     * if available locally, revealing whether or not the activity already
+     * ran during a prior execution cycle
+     * @param {string} prefix - one of: proxy, child, start, wait etc
+     * @returns
+     */
+    static didRun(prefix: string): Promise<[boolean, number, any]>;
+    /**
+     * Those methods that may only be called once must be protected by flagging
+     * their execution with a unique key (the key is stored in the HASH alongside
+     * process state and job state)
+     * @private
+     */
+    static isSideEffectAllowed(hotMeshClient: HotMesh, prefix: string): Promise<boolean>;
+    /**
+     * Returns the current workflow context restored
+     * from Redis
+     */
+    static getContext(): WorkflowContext;
+    /**
+     * Return a handle to the hotmesh client hosting the workflow execution
+     * @returns {Promise<HotMesh>} - a hotmesh client
+     */
+    static getHotMesh(): Promise<HotMesh>;
+    /**
+     * Spawns a child workflow and awaits the return.
      * @template T - the result type
      * @param {WorkflowOptions} options - the workflow options
      * @returns {Promise<T>} - the result of the child workflow
+     * @example
+     * const result = await Durable.workflow.execChild<typeof resultType>({ ...options });
      */
-    static executeChild<T>(options: WorkflowOptions): Promise<T>;
+    static execChild<T>(options: WorkflowOptions): Promise<T>;
     /**
-     * Spawns a child workflow. return the childJobId.
-     * This method is used when the result of the child workflow is not needed.
+     * constructs the payload necessary to spawn a child job
+     * @private
+     */
+    static getChildInterruptPayload(context: WorkflowContext, options: WorkflowOptions, execIndex: number): DurableChildErrorType;
+    /**
+     * Spawns a child workflow and returns the child Job ID.
+     * This method guarantees the spawned child has reserved the Job ID,
+     * returning a 'DuplicateJobError' error if not. Otherwise,
+     * this is a fire-and-forget method.
+     *
      * @param {WorkflowOptions} options - the workflow options
      * @returns {Promise<string>} - the childJobId
+     * @example
+     * const childJobId = await Durable.workflow.startChild({ ...options });
      */
-    static startChild<T>(options: WorkflowOptions): Promise<string>;
+    static startChild(options: WorkflowOptions): Promise<string>;
     /**
-     * Wraps activities in a proxy that will durably run them
-     * @param {ActivityConfig} options - the activity configuration
-     * that will be used to wrap the activities. You must pass an
-     * `activities` object to this configuration. The activities object
-     * should be a key-value pair of activity names and their respective
-     * functions. This is typically done by importing the activities.
+     * Wraps activities in a proxy that durably runs/re-runs them to completion.
+     * TODO: verify that activities do not collide if named same on same server but bound to different workflows
      *
+     * @param {ActivityConfig} options - the activity configuration
+     * that will be used to wrap the activities.
      * @returns {ProxyType<ACT>} - a proxy object with the same keys as the
      * activities object, but with the values replaced by a wrapped function
+     *
      * @example
      * // import the activities
      * import * as activities from './activities';
@@ -36,29 +73,18 @@ export declare class WorkflowService {
      * const { activity1, activity2 } = WorkflowService.proxyActivities<typeof activities>({ activities });
      */
     static proxyActivities<ACT>(options?: ActivityConfig): ProxyType<ACT>;
+    static wrapActivity<T>(activityName: string, options?: ActivityConfig): T;
+    /**
+      * constructs the payload necessary to spawn a proxyActivity job
+      * @private
+      */
+    static getProxyInterruptPayload(context: WorkflowContext, activityName: string, execIndex: number, args: any[], options?: ActivityConfig): DurableProxyErrorType;
     /**
      * Returns a search session for use when reading/writing to the workflow HASH.
      * The search session provides access to methods like `get`, `mget`, `set`, `del`, and `incr`.
      * @returns {Promise<Search>} - a search session
      */
     static search(): Promise<Search>;
-    /**
-     * Return a handle to the hotmesh client currently running the workflow
-     * @returns {Promise<HotMesh>} - a hotmesh client
-     */
-    static getHotMesh(): Promise<HotMesh>;
-    /**
-     * Returns the current workflow context
-     * @returns {WorkflowContext} - the current workflow context
-     */
-    static getContext(): WorkflowContext;
-    /**
-     * Those methods that may only be called once must be protected by flagging
-     * their execution with a unique key (the key is stored in the HASH alongside
-     * process state and job state)
-     * @private
-     */
-    static isSideEffectAllowed(hotMeshClient: HotMesh, prefix: string): Promise<boolean>;
     /**
      * Returns a random number between 0 and 1. This number is deterministic
      * and will never vary for a given seed. This is useful for randomizing
@@ -67,8 +93,8 @@ export declare class WorkflowService {
      */
     static random(): number;
     /**
-     * Sends signal data into any other paused thread (which is paused and
-     * awaiting the signal) from within a hook-thread or the main-thread
+     * Sends signal data into any other paused thread (which is currently
+     * awaiting the signal)
      * @param {string} signalId - the signal id
      * @param {Record<any, any>} data - the signal data
      * @returns {Promise<string>} - the stream id
@@ -81,44 +107,33 @@ export declare class WorkflowService {
      * @param {HookOptions} options - the hook options
      */
     static hook(options: HookOptions): Promise<string>;
-    static getLocalState(): {
-        workflowId: any;
-        namespace: any;
-        workflowTopic: any;
-        workflowDimension: any;
-        counter: any;
-        replay: any;
-    };
     /**
      * Executes a function once and caches the result. If the function is called
      * again, the cached result is returned. This is useful for wrapping
      * expensive activity calls that should only be run once, but which might
-     * not require the configuration nuance/expense provided by proxyActivities.
+     * not require the cost and safety provided by proxyActivities.
      * @template T - the result type
      */
     static once<T>(fn: (...args: any[]) => Promise<T>, ...args: any[]): Promise<T>;
     /**
      * Interrupts a running job
-     *
-     * @param {string} jobId - the target job id
-     * @param {JobInterruptOptions} options - the interrupt options
-     * @returns {Promise<string>} - the stream id
      */
     static interrupt(jobId: string, options?: JobInterruptOptions): Promise<string | void>;
     /**
      * Sleeps the workflow for a duration. As the function is reentrant,
      * upon reentry, the function will traverse prior execution paths up
-     * until the sleep command and then resume execution from that point.
-     * @param {string} duration - for example: '1 minute', '2 hours', '3 days'
-     * @returns {Promise<number>}
+     * until the sleep command and then resume execution thereafter.
+     * @param {string} duration - See the `ms` package for syntax examples: '1 minute', '2 hours', '3 days'
+     * @returns {Promise<number>} - resolved duration in seconds
      */
     static sleepFor(duration: string): Promise<number>;
     /**
-     * Waits for a signal to awaken
-     * @param {string[]} signals - the signals to wait for
-     * @param {Record<string, string>} options - the options
-     * @returns {Promise<Record<any, any>[]>}
+     * Pauses the workflow until `signalId` is received.
+     * @template T - the result type
+     * @param {string} signalId - a unique, shareable guid (e.g, 'abc123')
+     * @returns {Promise<T>}
+     * @example
+     * const result = await Durable.workflow.waitFor<typeof resultType>('abc123');
      */
-    static waitForSignal(signals: string[], options?: Record<string, string>): Promise<Record<any, any>[]>;
-    static wrapActivity<T>(activityName: string, options?: ActivityConfig): T;
+    static waitFor<T>(signalId: string): Promise<T>;
 }