@hotmeshio/hotmesh 0.8.0 → 0.9.0

package/build/services/activities/hook.js

@@ -9,7 +9,145 @@ const telemetry_1 = require("../telemetry");
 const stream_1 = require("../../types/stream");
 const activity_1 = require("./activity");
 /**
- * Supports `signal hook`, `time hook`, and `cycle hook` patterns
+ * A versatile pause/resume activity that supports three distinct patterns:
+ * **time hook** (sleep), **web hook** (external signal), and **passthrough**
+ * (immediate transition with optional data mapping).
+ *
+ * The hook activity is the most flexible activity type. Depending on its
+ * YAML configuration, it operates in one of the following modes:
+ *
+ * ## Time Hook (Sleep)
+ *
+ * Pauses the flow for a specified duration in seconds. The `sleep` value
+ * can be a literal number or a `@pipe` expression for dynamic delays
+ * (e.g., exponential backoff).
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: job.start
+ *       expire: 300
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         delay:
+ *           type: hook
+ *           sleep: 60                        # pause for 60 seconds
+ *           job:
+ *             maps:
+ *               paused_at: '{$self.output.metadata.ac}'
+ *
+ *         resume:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: delay
+ *         delay:
+ *           - to: resume
+ * ```
+ *
+ * ## Web Hook (External Signal)
+ *
+ * Registers a webhook listener on a named topic. The flow pauses until
+ * an external signal is sent to the hook's topic. The signal data becomes
+ * available as `$self.hook.data`. The `hooks` section at the graph level
+ * routes incoming signals to the waiting activity.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: order.placed
+ *       expire: 3600
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         wait_for_approval:
+ *           type: hook
+ *           hook:
+ *             type: object
+ *             properties:
+ *               approved: { type: boolean }
+ *           job:
+ *             maps:
+ *               approved: '{$self.hook.data.approved}'
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: wait_for_approval
+ *         wait_for_approval:
+ *           - to: done
+ *
+ *       hooks:
+ *         order.approval:                    # external topic that delivers the signal
+ *           - to: wait_for_approval
+ *             conditions:
+ *               match:
+ *                 - expected: '{t1.output.data.id}'
+ *                   actual: '{$self.hook.data.id}'
+ * ```
+ *
+ * ## Passthrough (No Hook)
+ *
+ * When neither `sleep` nor `hook` is configured, the hook activity acts
+ * as a passthrough: it maps data and immediately transitions to children.
+ * This is useful for data transformation, convergence points, or as a
+ * cycle pivot (with `cycle: true`).
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: job.start
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         pivot:
+ *           type: hook
+ *           cycle: true                      # enables re-entry from a cycle activity
+ *           output:
+ *             maps:
+ *               retryCount: 0
+ *           job:
+ *             maps:
+ *               counter: '{$self.output.data.retryCount}'
+ *
+ *         do_work:
+ *           type: worker
+ *           topic: work.do
+ *
+ *       transitions:
+ *         t1:
+ *           - to: pivot
+ *         pivot:
+ *           - to: do_work
+ * ```
+ *
+ * ## Execution Model
+ *
+ * - **With `sleep` or `hook`**: Category A (duplex). Leg 1 registers the
+ *   hook and saves state. Leg 2 fires when the timer expires or the
+ *   external signal arrives (via `processTimeHookEvent` or
+ *   `processWebHookEvent`).
+ * - **Without `sleep` or `hook`**: Category B (passthrough). Uses the
+ *   crash-safe `executeLeg1StepProtocol` to map data and transition
+ *   to adjacent activities.
+ *
+ * @see {@link HookActivity} for the TypeScript interface
  */
 class Hook extends activity_1.Activity {
     constructor(config, data, metadata, hook, engine, context) {
@@ -129,7 +267,7 @@ class Hook extends activity_1.Activity {
         }
         else if (this.config.sleep) {
             const duration = pipe_1.Pipe.resolve(this.config.sleep, this.context);
-            await this.engine.taskService.registerTimeHook(this.context.metadata.jid, this.context.metadata.gid, `${this.metadata.aid}${this.metadata.dad || ''}`, 'sleep', duration, this.metadata.dad || '');
+            await this.engine.taskService.registerTimeHook(this.context.metadata.jid, this.context.metadata.gid, `${this.metadata.aid}${this.metadata.dad || ''}`, 'sleep', duration, this.metadata.dad || '', transaction);
             return this.context.metadata.jid;
         }
     }

package/build/services/activities/interrupt.d.ts

@@ -3,6 +3,118 @@ import { TelemetryService } from '../telemetry';
 import { ActivityData, ActivityMetadata, ActivityType, InterruptActivity } from '../../types/activity';
 import { JobInterruptOptions, JobState } from '../../types/job';
 import { Activity } from './activity';
+/**
+ * Terminates a flow by sending an interrupt signal. The `interrupt` activity
+ * can target the current flow (self-interrupt) or any other flow by its
+ * job ID (remote interrupt). Interrupted jobs have their status set to a
+ * value less than -100,000,000, indicating abnormal termination.
+ *
+ * ## YAML Configuration — Self-Interrupt
+ *
+ * When no `target` is specified, the activity interrupts the current flow.
+ * The flow terminates immediately after this activity executes. Use
+ * conditional transitions to route to an interrupt only when needed.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: validation.check
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         validate:
+ *           type: worker
+ *           topic: validate.input
+ *
+ *         cancel:
+ *           type: interrupt
+ *           reason: 'Validation failed'
+ *           throw: true
+ *           code: 410
+ *           job:
+ *             maps:
+ *               cancelled_at: '{$self.output.metadata.ac}'
+ *
+ *         proceed:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: validate
+ *         validate:
+ *           - to: cancel
+ *             conditions:
+ *               code: 422               # interrupt only on validation failure
+ *           - to: proceed
+ * ```
+ *
+ * ## YAML Configuration — Remote Interrupt
+ *
+ * When `target` is specified, the activity interrupts another flow while
+ * the current flow continues to transition to adjacent activities.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: parent.flow
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *           job:
+ *             maps:
+ *               childJobId: '{$self.output.data.childJobId}'
+ *
+ *         stop_child:
+ *           type: interrupt
+ *           topic: child.flow.topic     # topic of the target flow
+ *           target: '{t1.output.data.childJobId}'
+ *           throw: false                # do not throw (silent cancellation)
+ *           descend: true               # also interrupt descendant sub-flows
+ *           job:
+ *             maps:
+ *               interrupted: true
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: stop_child
+ *         stop_child:
+ *           - to: done
+ * ```
+ *
+ * ## Configuration Properties
+ *
+ * | Property   | Type    | Default            | Description |
+ * |------------|---------|--------------------|-------------|
+ * | `target`   | string  | (current job)      | Job ID to interrupt. Supports `@pipe` expressions. |
+ * | `topic`    | string  | (current topic)    | Topic of the target flow |
+ * | `reason`   | string  | `'Job Interrupted'`| Error message attached to the interruption |
+ * | `throw`    | boolean | `true`             | Whether to throw a `JobInterrupted` error |
+ * | `descend`  | boolean | `false`            | Whether to cascade to child/descendant flows |
+ * | `code`     | number  | `410`              | Error code attached to the interruption |
+ * | `stack`    | string  | —                  | Optional stack trace |
+ *
+ * ## Execution Model
+ *
+ * - **Self-interrupt (no `target`)**: Category C. Verifies entry, maps job
+ *   data, sets status to -1, and fires the interrupt. No children.
+ * - **Remote interrupt (with `target`)**: Category B. Fires the interrupt
+ *   best-effort, then uses `executeLeg1StepProtocol` to transition to
+ *   adjacent activities.
+ *
+ * @see {@link InterruptActivity} for the TypeScript interface
+ */
 declare class Interrupt extends Activity {
     config: InterruptActivity;
     constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);

package/build/services/activities/interrupt.js

@@ -6,6 +6,118 @@ const collator_1 = require("../collator");
 const pipe_1 = require("../pipe");
 const telemetry_1 = require("../telemetry");
 const activity_1 = require("./activity");
+/**
+ * Terminates a flow by sending an interrupt signal. The `interrupt` activity
+ * can target the current flow (self-interrupt) or any other flow by its
+ * job ID (remote interrupt). Interrupted jobs have their status set to a
+ * value less than -100,000,000, indicating abnormal termination.
+ *
+ * ## YAML Configuration — Self-Interrupt
+ *
+ * When no `target` is specified, the activity interrupts the current flow.
+ * The flow terminates immediately after this activity executes. Use
+ * conditional transitions to route to an interrupt only when needed.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: validation.check
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         validate:
+ *           type: worker
+ *           topic: validate.input
+ *
+ *         cancel:
+ *           type: interrupt
+ *           reason: 'Validation failed'
+ *           throw: true
+ *           code: 410
+ *           job:
+ *             maps:
+ *               cancelled_at: '{$self.output.metadata.ac}'
+ *
+ *         proceed:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: validate
+ *         validate:
+ *           - to: cancel
+ *             conditions:
+ *               code: 422               # interrupt only on validation failure
+ *           - to: proceed
+ * ```
+ *
+ * ## YAML Configuration — Remote Interrupt
+ *
+ * When `target` is specified, the activity interrupts another flow while
+ * the current flow continues to transition to adjacent activities.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: parent.flow
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *           job:
+ *             maps:
+ *               childJobId: '{$self.output.data.childJobId}'
+ *
+ *         stop_child:
+ *           type: interrupt
+ *           topic: child.flow.topic     # topic of the target flow
+ *           target: '{t1.output.data.childJobId}'
+ *           throw: false                # do not throw (silent cancellation)
+ *           descend: true               # also interrupt descendant sub-flows
+ *           job:
+ *             maps:
+ *               interrupted: true
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: stop_child
+ *         stop_child:
+ *           - to: done
+ * ```
+ *
+ * ## Configuration Properties
+ *
+ * | Property   | Type    | Default            | Description |
+ * |------------|---------|--------------------|-------------|
+ * | `target`   | string  | (current job)      | Job ID to interrupt. Supports `@pipe` expressions. |
+ * | `topic`    | string  | (current topic)    | Topic of the target flow |
+ * | `reason`   | string  | `'Job Interrupted'`| Error message attached to the interruption |
+ * | `throw`    | boolean | `true`             | Whether to throw a `JobInterrupted` error |
+ * | `descend`  | boolean | `false`            | Whether to cascade to child/descendant flows |
+ * | `code`     | number  | `410`              | Error code attached to the interruption |
+ * | `stack`    | string  | —                  | Optional stack trace |
+ *
+ * ## Execution Model
+ *
+ * - **Self-interrupt (no `target`)**: Category C. Verifies entry, maps job
+ *   data, sets status to -1, and fires the interrupt. No children.
+ * - **Remote interrupt (with `target`)**: Category B. Fires the interrupt
+ *   best-effort, then uses `executeLeg1StepProtocol` to transition to
+ *   adjacent activities.
+ *
+ * @see {@link InterruptActivity} for the TypeScript interface
+ */
 class Interrupt extends activity_1.Activity {
     constructor(config, data, metadata, hook, engine, context) {
         super(config, data, metadata, hook, engine, context);
@@ -74,20 +186,21 @@ class Interrupt extends activity_1.Activity {
         }
     }
     async interruptSelf(telemetry) {
-        // Apply final updates to THIS job's state
         if (this.config.job?.maps) {
             this.mapJobData();
-            await this.setState();
         }
-        // Interrupt THIS job
-        const messageId = await this.interrupt();
-        // Notarize Leg1 completion and set status
+        // Bundle state + Leg1 completion + semaphore in one transaction
         telemetry.mapActivityAttributes();
         const transaction = this.store.transact();
+        if (this.config.job?.maps) {
+            await this.setState(transaction);
+        }
         await collator_1.CollatorService.notarizeLeg1Completion(this, transaction);
         await this.setStatus(-1, transaction);
         const txResponse = (await transaction.exec());
         const jobStatus = this.resolveStatus(txResponse);
+        // Interrupt fires AFTER proof commits (best-effort)
+        const messageId = await this.interrupt();
         telemetry.setActivityAttributes({
             'app.activity.mid': messageId,
             'app.job.jss': jobStatus,

package/build/services/activities/signal.d.ts

@@ -3,6 +3,111 @@ import { ActivityData, ActivityMetadata, ActivityType, SignalActivity } from '..
 import { JobState } from '../../types/job';
 import { ProviderTransaction } from '../../types/provider';
 import { Activity } from './activity';
+/**
+ * Sends a signal to one or more paused flows, resuming their execution.
+ * The `signal` activity is the counterpart to a `Hook` activity
+ * configured with a webhook listener. It allows any flow to reach into
+ * another flow and deliver data to a waiting hook, regardless of the
+ * relationship between the flows.
+ *
+ * ## YAML Configuration — Signal One
+ *
+ * Resumes a single paused flow by publishing to the hook's topic. Use
+ * `subtype: one` when you know the specific hook topic to signal.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: signal.start
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         resume_hook:
+ *           type: signal
+ *           subtype: one
+ *           topic: my.hook.topic          # the hook's registered topic
+ *           status: success               # optional: success (default) or pending
+ *           code: 200                     # optional: 200 (default) or 202 (keep-alive)
+ *           signal:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 approved: { type: boolean }
+ *             maps:
+ *               approved: true            # data delivered to the hook
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: resume_hook
+ *         resume_hook:
+ *           - to: done
+ * ```
+ *
+ * A `code: 202` signal delivers data but keeps the hook alive for
+ * additional signals. A `code: 200` (default) closes the hook.
+ *
+ * ## YAML Configuration — Signal All
+ *
+ * Resumes all paused flows that share a common job key facet. Use
+ * `subtype: all` for fan-out patterns where multiple waiting flows
+ * should be resumed simultaneously.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: signal.fan.out
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         resume_all:
+ *           type: signal
+ *           subtype: all
+ *           topic: hook.resume
+ *           key_name: parent_job_id       # index facet name
+ *           key_value: '{$job.metadata.jid}'
+ *           scrub: true                   # clean up indexes after use
+ *           resolver:
+ *             maps:
+ *               data:
+ *                 parent_job_id: '{$job.metadata.jid}'
+ *               scrub: true
+ *           signal:
+ *             maps:
+ *               done: true                # data delivered to all matching hooks
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: resume_all
+ *         resume_all:
+ *           - to: done
+ * ```
+ *
+ * ## Execution Model
+ *
+ * Signal is a **Category B (Leg1-only with children)** activity:
+ * - Bundles the hook signal with the Leg 1 completion marker in a
+ *   single transaction (`hookOne`) or fires best-effort (`hookAll`).
+ * - Executes the crash-safe `executeLeg1StepProtocol` to transition
+ *   to adjacent activities.
+ *
+ * @see {@link SignalActivity} for the TypeScript interface
+ */
 declare class Signal extends Activity {
     config: SignalActivity;
     constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);
@@ -13,10 +118,10 @@ declare class Signal extends Activity {
      * The signal activity will hook one. Accepts an optional transaction
      * so the hook publish can be bundled with the Leg1 completion marker.
      */
-    hookOne(transaction?: ProviderTransaction): Promise<string>;
+    signalOne(transaction?: ProviderTransaction): Promise<string>;
     /**
-     * The signal activity will hook all paused jobs that share the same job key.
+     * Signals all paused jobs that share the same job key, resuming their execution.
      */
-    hookAll(): Promise<string[]>;
+    signalAll(): Promise<string[]>;
 }
 export { Signal };

package/build/services/activities/signal.js

@@ -7,6 +7,111 @@ const mapper_1 = require("../mapper");
 const pipe_1 = require("../pipe");
 const telemetry_1 = require("../telemetry");
 const activity_1 = require("./activity");
+/**
+ * Sends a signal to one or more paused flows, resuming their execution.
+ * The `signal` activity is the counterpart to a `Hook` activity
+ * configured with a webhook listener. It allows any flow to reach into
+ * another flow and deliver data to a waiting hook, regardless of the
+ * relationship between the flows.
+ *
+ * ## YAML Configuration — Signal One
+ *
+ * Resumes a single paused flow by publishing to the hook's topic. Use
+ * `subtype: one` when you know the specific hook topic to signal.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: signal.start
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         resume_hook:
+ *           type: signal
+ *           subtype: one
+ *           topic: my.hook.topic          # the hook's registered topic
+ *           status: success               # optional: success (default) or pending
+ *           code: 200                     # optional: 200 (default) or 202 (keep-alive)
+ *           signal:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 approved: { type: boolean }
+ *             maps:
+ *               approved: true            # data delivered to the hook
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: resume_hook
+ *         resume_hook:
+ *           - to: done
+ * ```
+ *
+ * A `code: 202` signal delivers data but keeps the hook alive for
+ * additional signals. A `code: 200` (default) closes the hook.
+ *
+ * ## YAML Configuration — Signal All
+ *
+ * Resumes all paused flows that share a common job key facet. Use
+ * `subtype: all` for fan-out patterns where multiple waiting flows
+ * should be resumed simultaneously.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: signal.fan.out
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         resume_all:
+ *           type: signal
+ *           subtype: all
+ *           topic: hook.resume
+ *           key_name: parent_job_id       # index facet name
+ *           key_value: '{$job.metadata.jid}'
+ *           scrub: true                   # clean up indexes after use
+ *           resolver:
+ *             maps:
+ *               data:
+ *                 parent_job_id: '{$job.metadata.jid}'
+ *               scrub: true
+ *           signal:
+ *             maps:
+ *               done: true                # data delivered to all matching hooks
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: resume_all
+ *         resume_all:
+ *           - to: done
+ * ```
+ *
+ * ## Execution Model
+ *
+ * Signal is a **Category B (Leg1-only with children)** activity:
+ * - Bundles the hook signal with the Leg 1 completion marker in a
+ *   single transaction (`hookOne`) or fires best-effort (`hookAll`).
+ * - Executes the crash-safe `executeLeg1StepProtocol` to transition
+ *   to adjacent activities.
+ *
+ * @see {@link SignalActivity} for the TypeScript interface
+ */
 class Signal extends activity_1.Activity {
     constructor(config, data, metadata, hook, engine, context) {
         super(config, data, metadata, hook, engine, context);
@@ -32,10 +137,10 @@ class Signal extends activity_1.Activity {
             if (!collator_1.CollatorService.isGuidStep1Done(this.guidLedger)) {
                 const txn1 = this.store.transact();
                 if (this.config.subtype === 'all') {
-                    await this.hookAll();
+                    await this.signalAll();
                 }
                 else {
-                    await this.hookOne(txn1);
+                    await this.signalOne(txn1);
                 }
                 await this.setState(txn1);
                 if (this.adjacentIndex === 0) {
@@ -107,17 +212,17 @@ class Signal extends activity_1.Activity {
      * The signal activity will hook one. Accepts an optional transaction
      * so the hook publish can be bundled with the Leg1 completion marker.
      */
-    async hookOne(transaction) {
+    async signalOne(transaction) {
         const topic = pipe_1.Pipe.resolve(this.config.topic, this.context);
         const signalInputData = this.mapSignalData();
         const status = pipe_1.Pipe.resolve(this.config.status, this.context);
         const code = pipe_1.Pipe.resolve(this.config.code, this.context);
-        return await this.engine.hook(topic, signalInputData, status, code, transaction);
+        return await this.engine.signal(topic, signalInputData, status, code, transaction);
     }
     /**
-     * The signal activity will hook all paused jobs that share the same job key.
+     * Signals all paused jobs that share the same job key, resuming their execution.
      */
-    async hookAll() {
+    async signalAll() {
         //prep 1) generate `input signal data` (essentially the webhook payload)
         const signalInputData = this.mapSignalData();
         //prep 2) generate data that resolves the job key (per the YAML config)
@@ -130,8 +235,8 @@ class Signal extends activity_1.Activity {
         const key_name = pipe_1.Pipe.resolve(this.config.key_name, this.context);
         const key_value = pipe_1.Pipe.resolve(this.config.key_value, this.context);
         const indexQueryFacets = [`${key_name}:${key_value}`];
-        //execute: `hookAll` will now resume all paused jobs that share the same job key
-        return await this.engine.hookAll(this.config.topic, signalInputData, keyResolverData, indexQueryFacets);
+        //execute: `signalAll` will now resume all paused jobs that share the same job key
+        return await this.engine.signalAll(this.config.topic, signalInputData, keyResolverData, indexQueryFacets);
     }
 }
 exports.Signal = Signal;