@hotmeshio/hotmesh 0.0.53 → 0.0.55

package/services/durable/workflow.ts

@@ -14,10 +14,12 @@ import { asyncLocalStorage } from '../../modules/storage';
 import {
   deterministicRandom,
   formatISODate,
+  guid,
   sleepFor } from '../../modules/utils';
 import { Search } from './search';
 import { WorkerService } from './worker';
 import { HotMeshService as HotMesh } from '../hotmesh';
+import { SerializerService } from '../serializer';
 import {
   ActivityConfig,
   ChildResponseType,
@@ -28,8 +30,8 @@ import {
   WorkflowOptions
 } from "../../types/durable";
 import { JobInterruptOptions } from '../../types/job';
-import { StreamCode, StreamError, StreamStatus } from '../../types/stream';
-import { StringStringType } from '../../types';
+import { StreamCode, StreamStatus } from '../../types/stream';
+import { StringStringType } from '../../types/serializer';
 import {
   HMSH_CODE_DURABLE_CHILD,
   HMSH_CODE_DURABLE_FATAL,
@@ -41,19 +43,62 @@ import {
   HMSH_DURABLE_EXP_BACKOFF, 
   HMSH_DURABLE_MAX_ATTEMPTS,
   HMSH_DURABLE_MAX_INTERVAL} from '../../modules/enums';
-import { SerializerService } from '../serializer';
+import { DurableChildErrorType, DurableProxyErrorType } from '../../types/error';
 
 export class WorkflowService {
 
   /**
-   * Return a handle to the hotmesh client currently running the workflow
-   * @returns {Promise<HotMesh>} - a hotmesh client
+   * 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 async getHotMesh(): Promise<HotMesh> {
+  static async didRun(prefix: string): Promise<[boolean, number, any]> {
+    const {
+      COUNTER,
+      replay,
+      workflowDimension,
+    } = WorkflowService.getContext();
+    const execIndex = COUNTER.counter = COUNTER.counter + 1;
+    const sessionId = `-${prefix}${workflowDimension}-${execIndex}-`;
+    if (sessionId in replay) {
+      const restored = SerializerService.fromString(replay[sessionId]);
+      return [true, execIndex, restored];
+    }
+    return [false, execIndex, null];
+  }
+
+  /**
+   * 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 async isSideEffectAllowed(hotMeshClient: HotMesh, prefix: string): Promise<boolean> {
     const store = asyncLocalStorage.getStore();
-    const workflowTopic = store.get('workflowTopic');
-    const namespace = store.get('namespace');
-    return await WorkerService.getHotMesh(workflowTopic, { namespace });
+    const workflowId = store.get('workflowId');
+    const workflowDimension = store.get('workflowDimension') ?? '';
+    const COUNTER = store.get('counter');
+    const execIndex = COUNTER.counter = COUNTER.counter + 1;
+    const sessionId = `-${prefix}${workflowDimension}-${execIndex}-`;
+    const replay = store.get('replay') as StringStringType;
+    if (sessionId in replay) {
+      return false;
+    }
+    const keyParams = {
+      appId: hotMeshClient.appId,
+      jobId: workflowId
+    }
+    const workflowGuid = KeyService.mintKey(hotMeshClient.namespace, KeyType.JOB_STATE, keyParams);
+    const guidValue = Number(
+      await hotMeshClient.engine.store.exec(
+        'HINCRBYFLOAT',
+        workflowGuid,
+        sessionId,
+        '1') as string
+    );
+    return guidValue === 1;
   }
 
   /**
@@ -65,9 +110,11 @@ export class WorkflowService {
     const workflowId = store.get('workflowId');
     const replay = store.get('replay');
     const cursor = store.get('cursor');
+    const interruptionRegistry = store.get('interruptionRegistry');
     const workflowDimension = store.get('workflowDimension') ?? '';
     const workflowTopic = store.get('workflowTopic');
     const namespace = store.get('namespace');
+    const originJobId = store.get('originJobId');
     const workflowTrace = store.get('workflowTrace');
     const canRetry = store.get('canRetry');
     const workflowSpan = store.get('workflowSpan');
@@ -78,7 +125,9 @@ export class WorkflowService {
       COUNTER,
       counter: COUNTER.counter,
       cursor,
+      interruptionRegistry,
       namespace,
+      originJobId,
       raw,
       replay,
       workflowId,
@@ -89,6 +138,17 @@ export class WorkflowService {
     };
   }
 
+  /**
+   * Return a handle to the hotmesh client hosting the workflow execution
+   * @returns {Promise<HotMesh>} - a hotmesh client
+   */
+  static async getHotMesh(): Promise<HotMesh> {
+    const store = asyncLocalStorage.getStore();
+    const workflowTopic = store.get('workflowTopic');
+    const namespace = store.get('namespace');
+    return await WorkerService.getHotMesh(workflowTopic, { namespace });
+  }
+
   /**
    * Spawns a child workflow and awaits the return.
    * @template T - the result type
@@ -101,14 +161,15 @@ export class WorkflowService {
     //SYNC
     //check if the activity already ran (check $error/done)
     const isStartChild = options.await === false;
-    const [didRun, execIndex, result]: [boolean, number, ChildResponseType<T>] = await WorkflowService.didRun(isStartChild ? 'start' : 'child');
-    const store = asyncLocalStorage.getStore();
-    const canRetry = store.get('canRetry');
+    const prefix = isStartChild ? 'start' : 'child';
+    const [didRun, execIndex, result]: [boolean, number, ChildResponseType<T>] = await WorkflowService.didRun(prefix);
+    const context = WorkflowService.getContext();
+    const { canRetry, interruptionRegistry } = context;
 
     if (didRun) {
       if (result?.$error && (!result.$error.is_stream_error || (result.$error.is_stream_error && !canRetry))) {
         if (options?.config?.throwOnError !== false) {
-          //rethrow remote execution error (simulates throw)
+          //rethrow remote execution error (simulates local failure)
           const code: StreamCode = result.$error.code;
           const message = result.$error.message;
           const stack = result.$error.stack;
@@ -127,18 +188,36 @@ export class WorkflowService {
         return result.data as T;
       }
     }
-    //package the interruption inputs
-    const interruptionRegistry = store.get('interruptionRegistry');
-    const workflowId = store.get('workflowId');
-    const originJobId = store.get('originJobId');
-    const workflowDimension = store.get('workflowDimension') ?? '';
-    const entityOrEmptyString = options.entity ?? '';
-    const childJobId = options.workflowId ?? `${entityOrEmptyString}-${workflowId}-$${options.entity ?? options.workflowName}${workflowDimension}-${execIndex}`;
+    const interruptionMessage = WorkflowService.getChildInterruptPayload(context, options, execIndex);
+    //push the packaged inputs to the registry
+    interruptionRegistry.push({
+      code: HMSH_CODE_DURABLE_CHILD,
+      ...interruptionMessage,
+    });
+    //ASYNC
+    //sleep (allow others to be packaged / registered) and throw the error
+    await sleepFor(0);
+    throw new DurableChildError(interruptionMessage );
+  }
+
+  /**
+   * constructs the payload necessary to spawn a child job
+   * @private
+   */
+  static getChildInterruptPayload(context: WorkflowContext, options: WorkflowOptions, execIndex: number): DurableChildErrorType {
+    const { workflowId, originJobId, workflowDimension } = context;    let childJobId: string;
+    if (options.workflowId) {
+      childJobId = options.workflowId;
+    } else if (options.entity) {
+      childJobId = `${options.entity}-${workflowId.substring(0, 7)}-${guid()}-${workflowDimension}-${execIndex}`;
+    } else {
+      childJobId = `-${options.workflowName}-${guid()}-${workflowDimension}-${execIndex}`;
+    }
     const parentWorkflowId = workflowId;
     const taskQueueName = options.entity ?? options.taskQueue;
     const workflowName = options.entity ?? options.workflowName;
     const workflowTopic = `${taskQueueName}-${workflowName}`;
-    const interruptionMessage = {
+    return {
       arguments: [...(options.args || [])],
       await: options?.await ?? true,
       backoffCoefficient: options?.config?.backoffCoefficient ?? HMSH_DURABLE_EXP_BACKOFF,
@@ -151,15 +230,6 @@ export class WorkflowService {
       workflowId: childJobId,
       workflowTopic,
     };
-    //push the packaged inputs to the registry
-    interruptionRegistry.push({
-      code: HMSH_CODE_DURABLE_CHILD,
-      ...interruptionMessage,
-    });
-    //ASYNC
-    //sleep (allow others to be packaged / registered) and throw the error
-    await sleepFor(0);
-    throw new DurableChildError(interruptionMessage);
   }
 
   /**
@@ -174,7 +244,7 @@ export class WorkflowService {
    * const childJobId = await Durable.workflow.startChild({ ...options });
    */
   static async startChild(options: WorkflowOptions): Promise<string> {
-    return this.execChild({ ...options, await: false });
+    return WorkflowService.execChild({ ...options, await: false });
   }
 
   /**
@@ -234,31 +304,15 @@ export class WorkflowService {
         return result.data as T;
       }
       //package the interruption inputs
-      const store = asyncLocalStorage.getStore();
-      const interruptionRegistry = store.get('interruptionRegistry');
-      const workflowDimension = store.get('workflowDimension') ?? '';
-      const workflowId = store.get('workflowId');
-      const originJobId = store.get('originJobId');
-      const workflowTopic = store.get('workflowTopic');
-      const activityTopic = `${workflowTopic}-activity`;
-      const activityJobId = `-${workflowId}-$${activityName}${workflowDimension}-${execIndex}`;
-      let maximumInterval: number;
-      if (options.retryPolicy?.maximumInterval) {
-        maximumInterval = ms(options.retryPolicy.maximumInterval) / 1000;
-      }
-      const interruptionMessage = {
-        arguments: Array.from(arguments),
-        workflowDimension: workflowDimension,
-        index: execIndex,
-        originJobId: originJobId || workflowId,
-        parentWorkflowId: workflowId,
-        workflowId: activityJobId,
-        workflowTopic: activityTopic,
+      const context = WorkflowService.getContext();
+      const { interruptionRegistry } = context;
+      const interruptionMessage = WorkflowService.getProxyInterruptPayload(
+        context,
         activityName,
-        backoffCoefficient: options?.retryPolicy?.backoffCoefficient ?? undefined,
-        maximumAttempts: options?.retryPolicy?.maximumAttempts ?? undefined,
-        maximumInterval: maximumInterval ?? undefined,
-      };
+        execIndex,
+        Array.from(arguments),
+        options
+      );
       //push the packaged inputs to the registry
       interruptionRegistry.push({
         code: HMSH_CODE_DURABLE_PROXY,
@@ -271,6 +325,33 @@ export class WorkflowService {
     } as T;
   }
 
+  /**
+    * constructs the payload necessary to spawn a proxyActivity job
+    * @private
+    */
+  static getProxyInterruptPayload(context: WorkflowContext, activityName: string, execIndex: number, args: any[], options?: ActivityConfig): DurableProxyErrorType {
+    const { workflowDimension, workflowId, originJobId, workflowTopic } = context;
+    const activityTopic = `${workflowTopic}-activity`;
+    const activityJobId = `-${workflowId}-$${activityName}${workflowDimension}-${execIndex}`;
+    let maximumInterval: number;
+    if (options.retryPolicy?.maximumInterval) {
+      maximumInterval = ms(options.retryPolicy.maximumInterval) / 1000;
+    }
+    return {
+      arguments: args,
+      workflowDimension: workflowDimension,
+      index: execIndex,
+      originJobId: originJobId || workflowId,
+      parentWorkflowId: workflowId,
+      workflowId: activityJobId,
+      workflowTopic: activityTopic,
+      activityName,
+      backoffCoefficient: options?.retryPolicy?.backoffCoefficient ?? undefined,
+      maximumAttempts: options?.retryPolicy?.maximumAttempts ?? undefined,
+      maximumInterval: maximumInterval ?? undefined,
+    };
+  }
+
   /**
    * 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`.
@@ -290,52 +371,6 @@ export class WorkflowService {
     return new Search(workflowId, hotMeshClient, searchSessionId);
   }
 
-  /**
-   * Returns the synchronous output from the activity (replay)
-   * if available locally
-   * @param {string} prefix - one of: proxy, child, start, wait etc
-   * @returns 
-   */
-  static async didRun(prefix: string): Promise<[boolean, number, any]> {
-    const {
-      COUNTER,
-      replay,
-      workflowDimension,
-    } = WorkflowService.getContext();
-    const execIndex = COUNTER.counter = COUNTER.counter + 1;
-    const sessionId = `-${prefix}${workflowDimension}-${execIndex}-`;
-    if (sessionId in replay) {
-      return [true, execIndex, SerializerService.fromString(replay[sessionId])];
-    }
-    return [false, execIndex, null];
-  }
-
-  /**
-   * 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 async isSideEffectAllowed(hotMeshClient: HotMesh, prefix: string): Promise<boolean> {
-    const store = asyncLocalStorage.getStore();
-    const workflowId = store.get('workflowId');
-    const workflowDimension = store.get('workflowDimension') ?? '';
-    const COUNTER = store.get('counter');
-    const execIndex = COUNTER.counter = COUNTER.counter + 1;
-    const sessionId = `-${prefix}${workflowDimension}-${execIndex}-`;
-    const replay = store.get('replay') as StringStringType;
-    if (sessionId in replay) {
-      return false;
-    }
-    const keyParams = {
-      appId: hotMeshClient.appId,
-      jobId: workflowId
-    }
-    const workflowGuid = KeyService.mintKey(hotMeshClient.namespace, KeyType.JOB_STATE, keyParams);
-    const guidValue = Number(await hotMeshClient.engine.store.exec('HINCRBYFLOAT', workflowGuid, sessionId, '1') as string);
-    return guidValue === 1;
-  }
-
   /**
    * 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
@@ -440,9 +475,7 @@ export class WorkflowService {
    * Interrupts a running job
    */
   static async interrupt(jobId: string, options: JobInterruptOptions = {}): Promise<string | void> {
-    const store = asyncLocalStorage.getStore();
-    const workflowTopic = store.get('workflowTopic');
-    const namespace = store.get('namespace');
+    const { workflowTopic, namespace } = WorkflowService.getContext();
     const hotMeshClient = await WorkerService.getHotMesh(workflowTopic, { namespace });
     if (await WorkflowService.isSideEffectAllowed(hotMeshClient, 'interrupt')) {
       return await hotMeshClient.interrupt(`${hotMeshClient.appId}.execute`, jobId, options);

package/services/engine/index.ts

@@ -51,7 +51,8 @@ import {
   PartialJobState,
   JobStatus, 
   JobInterruptOptions,
-  JobCompletionOptions } from '../../types/job';
+  JobCompletionOptions, 
+  ExtensionType} from '../../types/job';
 import {
   HotMeshApps,
   HotMeshConfig,
@@ -566,10 +567,10 @@ class EngineService {
 
   // ********************** PUB/SUB ENTRY POINT **********************
   //publish (returns just the job id)
-  async pub(topic: string, data: JobData, context?: JobState): Promise<string> {
+  async pub(topic: string, data: JobData, context?: JobState, extended?: ExtensionType): Promise<string> {
     const activityHandler = await this.initActivity(topic, data, context);
     if (activityHandler) {
-      return await activityHandler.process();
+      return await activityHandler.process(extended);
     } else {
       throw new Error(`unable to process activity for topic ${topic}`);
     }

package/services/hotmesh/index.ts

@@ -12,7 +12,8 @@ import {
   JobData,
   JobOutput, 
   JobStatus, 
-  JobInterruptOptions} from '../../types/job';
+  JobInterruptOptions,
+  ExtensionType} from '../../types/job';
 import {
   HotMeshConfig,
   HotMeshManifest } from '../../types/hotmesh';
@@ -115,8 +116,8 @@ class HotMeshService {
   }
 
   // ************* PUB/SUB METHODS *************
-  async pub(topic: string, data: JobData = {}, context?: JobState): Promise<string> {
-    return await this.engine?.pub(topic, data, context);
+  async pub(topic: string, data: JobData = {}, context?: JobState, extended?: ExtensionType): Promise<string> {
+    return await this.engine?.pub(topic, data, context, extended);
   }
   async sub(topic: string, callback: JobMessageCallback): Promise<void> {
     return await this.engine?.sub(topic, callback);

package/types/durable.ts

@@ -1,6 +1,6 @@
 import { LogLevel } from './logger';
 import { RedisClass, RedisOptions } from './redis';
-import { StringStringType } from './serializer';
+import { StringAnyType, StringStringType } from './serializer';
 import { StreamData, StreamError } from './stream';
 
 /**
@@ -68,6 +68,16 @@ type WorkflowContext = {
    */
   namespace: string;
 
+  /**
+   * holds list of interruption payloads; if list is longer than 1 when the error is thrown, a `collator` subflow will be used
+   */
+  interruptionRegistry: any[];
+
+  /**
+   * entry point ancestor flow; might be the parent; will never be self
+   */
+  originJobId: string;
+
   /**
    * the workflow/job ID
    */
@@ -112,7 +122,7 @@ type WorkflowSearchOptions = {
   schema?: Record<string, { type: 'TEXT' | 'NUMERIC' | 'TAG', sortable?: boolean }>;
 
   /** Additional data as a key-value record */
-  data?: Record<string, string>;
+  data?: StringStringType;
 }
 
 
@@ -173,6 +183,11 @@ type WorkflowOptions = {
    */
   search?: WorkflowSearchOptions
 
+  /**
+   * marker data (begins with a -)
+   */
+  marker?: StringStringType
+
   /**
    * the workflow configuration object
    */
@@ -235,7 +250,7 @@ type SignalOptions = {
   /** 
    * Input data for the signal (any serializable object) 
    */
-  data: Record<string, any>; 
+  data: StringAnyType; 
 
   /** 
    * Execution ID, also known as the job ID 

package/types/error.ts

@@ -0,0 +1,52 @@
+export type DurableChildErrorType = {
+  arguments: string[],
+  await?: boolean,
+  backoffCoefficient?: number,
+  index: number,
+  maximumAttempts?: number,
+  maximumInterval?: number,
+  originJobId: string | null,
+  parentWorkflowId: string,
+  workflowDimension: string,
+  workflowId: string,
+  workflowTopic: string,
+};
+
+export type DurableWaitForAllErrorType = {
+  items: string[],
+  workflowId: string,
+  workflowTopic: string,
+  parentWorkflowId: string,
+  originJobId: string | null,
+  size: number,
+  index: number,
+  workflowDimension: string
+};
+
+export type DurableProxyErrorType = {
+  arguments: string[],
+  activityName: string,
+  backoffCoefficient?: number,
+  index: number,
+  maximumAttempts?: number,
+  maximumInterval?: number,
+  originJobId: string | null,
+  parentWorkflowId: string,
+  workflowDimension: string,
+  workflowId: string,
+  workflowTopic: string,
+};
+
+export type DurableWaitForErrorType = {
+  signalId: string,
+  index: number,
+  workflowDimension: string
+  workflowId: string;
+};
+
+export type DurableSleepErrorType = {
+  duration: number,
+  index: number,
+  workflowDimension: string,
+  workflowId: string,
+};

package/types/exporter.ts

@@ -2,7 +2,28 @@ import { StringAnyType } from "./serializer";
 
 export type ExportItem = [(string | null), string, any];
 
-export interface ExportOptions {};
+/**
+ * job export data can be large, particularly transitions the timeline
+ */
+export type ExportFields = 'data' | 'state' | 'status' | 'timeline' | 'transitions';
+
+export interface ExportOptions {
+  /**
+   * limit the export byte size by specifying an allowlist
+   */
+  allow?: Array<ExportFields>;
+
+  /**
+   * limit the export byte size by specifying a block list
+   */
+  block?: Array<ExportFields>;
+
+  /**
+   * If false, do not return timeline values (like child job response, proxy activity response, etc)
+   * @default true
+   */
+  values?: boolean;
+};
 
 export type JobAction = {
   cursor: number;
@@ -46,26 +67,15 @@ export interface ExportCycles {
   [key: string]: string[];
 };
 
-export type IdemParts = {
+export type TimelineType = {
+  key: string;
+  value: Record<string, any> | string | number | null;
   index: number;
   secondary?: number;
   dimension?: string;
 };
 
-export type IdemType = {
-  key: string;
-  value: string;
-  parts: IdemParts;
-};
-
-export interface TimelineEntry {
-  activity: string;
-  dimensions: string;
-  created: string;
-  updated: string;
-}
-
-export interface TimestampParts {
+export interface TransitionType {
   activity: string;
   dimensions: string;
   created: string;
@@ -73,13 +83,11 @@ export interface TimestampParts {
 }
 
 export interface DurableJobExport {
-  data: StringAnyType;
-  dependencies?: Record<string, any>[];
-  state: StringAnyType;
-  status: string;
-  timeline?: JobTimeline[];
-  idempotents: IdemType[];
-  replay: TimestampParts[];
+  data?: StringAnyType;
+  state?: StringAnyType;
+  status?: number;
+  timeline?: TimelineType[];
+  transitions?: TransitionType[];
 };
 
 export interface JobExport {

package/types/index.ts

@@ -51,6 +51,12 @@ export {
     WorkflowDataType,
     WorkflowOptions,
   } from './durable';
+export {
+  DurableChildErrorType,
+  DurableProxyErrorType,
+  DurableSleepErrorType,
+  DurableWaitForAllErrorType,
+  DurableWaitForErrorType } from "./error";
 export {
   ActivityAction,
   DependencyExport,
@@ -83,7 +89,8 @@ export {
   JobOutput,
   JobState,
   JobStatus,
-  PartialJobState } from './job';
+  PartialJobState,
+  ExtensionType } from './job';
 export { MappingStatements } from './map';
 export {
   Pipe,

package/types/job.ts

@@ -1,3 +1,5 @@
+import { StringStringType } from "./serializer";
+
 type JobData = Record<string, unknown|Record<string, unknown>>;
 type JobsData = Record<string, unknown>;
 
@@ -82,6 +84,30 @@ type JobMetadata = {
   expire?: number;
 };
 
+/**
+ * User-defined (extended) types for job data. Users may interleave
+ * data into the job hash safely by using the `ExtensionType` interface.
+ * The data will be prefixed as necessary using an underscore or
+ * dash to ensure it is not confused with system process data.
+ */
+type ExtensionType = {
+  /**
+   * Custom search data field (name/value pairs) to seed the Hash.
+   * Every field will be prefixed with an underscore before being
+   * stored with the initial Hash data set along side system
+   * process data.
+   */
+  search?: StringStringType;
+
+  /**
+   * Custom marker data field used for adding a searchable marker to the job.
+   * markers always begin with a dash (-). Any field that does not
+   * begin with a dash will be removed and will not be inserted with
+   * the initial data set.
+   */
+  marker?: StringStringType;
+}
+
 /**
  * job_status semaphore
  */
@@ -183,4 +209,5 @@ export {
   JobState,
   JobStatus,
   PartialJobState,
+  ExtensionType,
 };