@hotmeshio/hotmesh 0.13.0 → 0.14.0

package/build/services/activities/worker.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Worker = void 0;
-const errors_1 = require("../../modules/errors");
 const utils_1 = require("../../modules/utils");
 const collator_1 = require("../collator");
 const pipe_1 = require("../pipe");
@@ -74,7 +73,7 @@ const activity_1 = require("./activity");
  * ## Retry Policy
  *
  * Retry behavior is configured at the **worker level** (not in YAML) via
- * the `retryPolicy` option. Failed callbacks are retried with exponential
+ * the `retry` option. Failed callbacks are retried with exponential
  * backoff until `maximumAttempts` is exhausted. The `maximumInterval` caps
  * the delay between retries.
  *
@@ -85,7 +84,7 @@ const activity_1 = require("./activity");
  *   workers: [{
  *     topic: 'work.backoff',
  *     connection,
- *     retryPolicy: {
+ *     retry: {
  *       maximumAttempts: 5,          // retry up to 5 times
  *       backoffCoefficient: 2,       // exponential: 2^0, 2^1, 2^2, ... seconds
  *       maximumInterval: '30s',      // cap delay at 30 seconds
@@ -115,10 +114,6 @@ const activity_1 = require("./activity");
  * @see {@link WorkerActivity} for the TypeScript interface
  */
 class Worker extends activity_1.Activity {
-    constructor(config, data, metadata, hook, engine, context) {
-        super(config, data, metadata, hook, engine, context);
-    }
-    //********  INITIAL ENTRY POINT (A)  ********//
     async process() {
         this.logger.debug('worker-process', {
             jid: this.context.metadata.jid,
@@ -131,15 +126,12 @@ class Worker extends activity_1.Activity {
             telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
             telemetry.startActivitySpan(this.leg);
             this.mapInputData();
-            //save state and mark Leg1 complete
             const transaction = this.store.transact();
-            //todo: await this.registerTimeout();
             const messageId = await this.execActivity(transaction);
             await collator_1.CollatorService.notarizeLeg1Completion(this, transaction);
             await this.setState(transaction);
             await this.setStatus(0, transaction);
             const txResponse = (await transaction.exec());
-            //telemetry
             telemetry.mapActivityAttributes();
             const jobStatus = this.resolveStatus(txResponse);
             telemetry.setActivityAttributes({
@@ -149,34 +141,8 @@ class Worker extends activity_1.Activity {
             return this.context.metadata.aid;
         }
         catch (error) {
-            if (error instanceof errors_1.InactiveJobError) {
-                this.logger.error('await-inactive-job-error', { error });
-                return;
-            }
-            else if (error instanceof errors_1.GenerationalError) {
-                this.logger.info('process-event-generational-job-error', { error });
-                return;
-            }
-            else if (error instanceof errors_1.GetStateError) {
-                this.logger.error('worker-get-state-error', { error });
-                return;
-            }
-            else if (error instanceof errors_1.CollationError) {
-                if (error.fault === 'duplicate') {
-                    this.logger.info('worker-collation-overage', {
-                        job_id: this.context.metadata.jid,
-                        guid: this.context.metadata.guid,
-                    });
-                    return;
-                }
-                //unknown collation error
-                this.logger.error('worker-collation-error', { error });
-            }
-            else {
-                this.logger.error('worker-process-error', { error });
-            }
-            telemetry?.setActivityError(error.message);
-            throw error;
+            this.handleProcessError(error, telemetry, 'worker');
+            return;
         }
         finally {
             telemetry?.endActivitySpan();
@@ -189,11 +155,9 @@ class Worker extends activity_1.Activity {
     }
     async execActivity(transaction) {
         const topic = pipe_1.Pipe.resolve(this.config.subtype, this.context);
-        // Extract workflow name from job data (set by durable client) or derive from subscribes
         const jobData = this.context.data;
         let wfn = jobData?.workflowName || '';
         if (!wfn && this.config.subscribes) {
-            // Fallback: derive from subscribes by removing topic prefix
             wfn = this.config.subscribes.startsWith(`${topic}-`)
                 ? this.config.subscribes.substring(topic.length + 1)
                 : this.config.subscribes;

package/build/services/connector/factory.d.ts

@@ -11,6 +11,12 @@ export declare class ConnectorService {
     static connectClient(ProviderConfig: ProviderConfig, taskQueue?: string): Promise<ProviderNativeClient>;
     /**
      * Initialize `store`, `stream`, and `subscription` clients for any provider.
+     *
+     * When the target has `workerCredentials`, the `user` and `password`
+     * in all connection options are overridden with the scoped Postgres
+     * role credentials, and `securedWorker` is set so downstream stream
+     * services use SECURITY DEFINER stored procedures.
+     *
      * @private
      */
     static initClients(target: HotMeshEngine | HotMeshWorker): Promise<void>;

package/build/services/connector/factory.js

@@ -22,6 +22,12 @@ class ConnectorService {
     }
     /**
      * Initialize `store`, `stream`, and `subscription` clients for any provider.
+     *
+     * When the target has `workerCredentials`, the `user` and `password`
+     * in all connection options are overridden with the scoped Postgres
+     * role credentials, and `securedWorker` is set so downstream stream
+     * services use SECURITY DEFINER stored procedures.
+     *
      * @private
      */
     static async initClients(target) {
@@ -34,6 +40,24 @@ class ConnectorService {
                 sub: { ...connection },
             };
         }
+        // Apply scoped worker credentials to stream/sub only.
+        // The `store` connection retains full credentials because it is
+        // used by the engine for schema deployment, job-state reads, and
+        // other operations that require direct table access. Only the
+        // `stream` (dequeue/ack/respond) and `sub` (LISTEN/UNLISTEN)
+        // connections are scoped to the least-privilege worker role.
+        const workerCreds = target.workerCredentials;
+        if (workerCreds) {
+            for (const key of ['stream', 'sub']) {
+                if (connection[key]?.options) {
+                    connection[key].options = {
+                        ...connection[key].options,
+                        user: workerCreds.user,
+                        password: workerCreds.password,
+                    };
+                }
+            }
+        }
         // Extract taskQueue from target for connection pooling
         const taskQueue = target.taskQueue;
         // Expanded form

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

@@ -13,7 +13,7 @@ import { DurableActivityContext } from '../../types/durable';
  * export async function processData(data: string): Promise<string> {
  *   const ctx = Durable.activity.getContext();
  *   console.log(`Activity ${ctx.activityName} for workflow ${ctx.workflowId}`);
- *   console.log(`Metadata:`, ctx.argumentMetadata);
+ *   console.log(`Metadata:`, ctx.headers);
  *   return `Processed: ${data}`;
  * }
  * ```

package/build/services/durable/activity.js

@@ -16,7 +16,7 @@ const storage_1 = require("../../modules/storage");
  * export async function processData(data: string): Promise<string> {
  *   const ctx = Durable.activity.getContext();
  *   console.log(`Activity ${ctx.activityName} for workflow ${ctx.workflowId}`);
- *   console.log(`Metadata:`, ctx.argumentMetadata);
+ *   console.log(`Metadata:`, ctx.headers);
  *   return `Processed: ${data}`;
  * }
  * ```
@@ -37,7 +37,7 @@ class ActivityService {
         return {
             activityName: store.get('activityName'),
             arguments: store.get('arguments'),
-            argumentMetadata: store.get('argumentMetadata') ?? {},
+            headers: store.get('headers') ?? {},
             workflowId: store.get('workflowId'),
             workflowTopic: store.get('workflowTopic'),
         };

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

@@ -1,39 +1,34 @@
 import { HotMesh } from '../hotmesh';
 import { ClientConfig, ClientWorkflow, Connection, WorkflowOptions } from '../../types/durable';
 /**
- * The Durable `Client` service provides methods for
- * starting, signaling, and querying workflows.
- * Start a new workflow execution by calling
- * `workflow.start`. Note the direct connection to
- * Postgres.
+ * Workflow client. Starts workflows, sends signals, and reads results.
  *
- * NATS can be used as the message broker if advanced
- * messaging is required (i.e, patterned subscriptions).
  * @example
-
  * ```typescript
- * //client.ts
- * import { Client, HotMesh } from '@hotmeshio/hotmesh';
+ * import { Durable } from '@hotmeshio/hotmesh';
  * import { Client as Postgres } from 'pg';
-
- * async function run(): Promise<string> {
- *   const client = new Client({
- *     connection: {
- *       class: Postgres,
- *       options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
- *     }
- *   });
-
- *   const handle = await client.workflow.start({
- *     args: ['HotMesh'],
- *     taskQueue: 'default',
- *     workflowName: 'example',
- *     workflowId: HotMesh.guid()
- *   });
-
- *   return await handle.result();
- *   //returns ['Hello HotMesh', '¡Hola, HotMesh!']
- * }
+ *
+ * const client = new Durable.Client({
+ *   connection: {
+ *     class: Postgres,
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' },
+ *   },
+ * });
+ *
+ * // Start a workflow and await its result
+ * const handle = await client.workflow.start({
+ *   args: ['order-123'],
+ *   taskQueue: 'orders',
+ *   workflowName: 'orderWorkflow',
+ *   workflowId: Durable.guid(),
+ * });
+ * const result = await handle.result();
+ *
+ * // Send a signal to a running workflow
+ * await handle.signal('approval', { approved: true });
+ *
+ * // Cancel a running workflow
+ * await handle.cancel();
  * ```
  */
 export declare class ClientService {

package/build/services/durable/client.js

@@ -11,39 +11,34 @@ const search_1 = require("./search");
 const handle_1 = require("./handle");
 const factory_1 = require("./schemas/factory");
 /**
- * The Durable `Client` service provides methods for
- * starting, signaling, and querying workflows.
- * Start a new workflow execution by calling
- * `workflow.start`. Note the direct connection to
- * Postgres.
+ * Workflow client. Starts workflows, sends signals, and reads results.
  *
- * NATS can be used as the message broker if advanced
- * messaging is required (i.e, patterned subscriptions).
  * @example
-
  * ```typescript
- * //client.ts
- * import { Client, HotMesh } from '@hotmeshio/hotmesh';
+ * import { Durable } from '@hotmeshio/hotmesh';
  * import { Client as Postgres } from 'pg';
-
- * async function run(): Promise<string> {
- *   const client = new Client({
- *     connection: {
- *       class: Postgres,
- *       options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
- *     }
- *   });
-
- *   const handle = await client.workflow.start({
- *     args: ['HotMesh'],
- *     taskQueue: 'default',
- *     workflowName: 'example',
- *     workflowId: HotMesh.guid()
- *   });
-
- *   return await handle.result();
- *   //returns ['Hello HotMesh', '¡Hola, HotMesh!']
- * }
+ *
+ * const client = new Durable.Client({
+ *   connection: {
+ *     class: Postgres,
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' },
+ *   },
+ * });
+ *
+ * // Start a workflow and await its result
+ * const handle = await client.workflow.start({
+ *   args: ['order-123'],
+ *   taskQueue: 'orders',
+ *   workflowName: 'orderWorkflow',
+ *   workflowId: Durable.guid(),
+ * });
+ * const result = await handle.result();
+ *
+ * // Send a signal to a running workflow
+ * await handle.signal('approval', { approved: true });
+ *
+ * // Cancel a running workflow
+ * await handle.cancel();
  * ```
  */
 class ClientService {

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

@@ -1,13 +1,12 @@
 import { Connection } from '../../types/durable';
 import { ProviderConfig, ProvidersConfig } from '../../types/provider';
 /**
- * The Connection service is used to declare the class
- * and connection options but does not connect quite yet. Connection
- * happens at a later lifecycle stage when a workflow
- * is started by the Durable Client module (`(new Durable.Client())).start()`).
+ * Declares connection configuration (driver class + options) without
+ * opening a connection. The actual Postgres connection is established
+ * lazily when a Worker or Client is started.
  *
- * The config options optionall support a multi-connection setup
- * where the `store` connection explicitly defined along with `stream`, `sub`, etc.
+ * Supports both single-connection and split-connection layouts (separate
+ * `store`, `stream`, and `sub` connections for advanced deployments).
  */
 export declare class ConnectionService {
     /**
@@ -15,7 +14,14 @@ export declare class ConnectionService {
      */
     constructor();
     /**
-     * Instance initializer
+     * Create a connection configuration object.
+     *
+     * @param config - Single `{ class, options }` or split `{ store, stream, sub }`.
+     * @returns The normalized connection configuration.
      */
     static connect(config: ProviderConfig | ProvidersConfig): Promise<Connection>;
+    /**
+     * Alias for {@link connect}.
+     */
+    static create: typeof ConnectionService.connect;
 }

package/build/services/durable/connection.js

@@ -2,13 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConnectionService = void 0;
 /**
- * The Connection service is used to declare the class
- * and connection options but does not connect quite yet. Connection
- * happens at a later lifecycle stage when a workflow
- * is started by the Durable Client module (`(new Durable.Client())).start()`).
+ * Declares connection configuration (driver class + options) without
+ * opening a connection. The actual Postgres connection is established
+ * lazily when a Worker or Client is started.
  *
- * The config options optionall support a multi-connection setup
- * where the `store` connection explicitly defined along with `stream`, `sub`, etc.
+ * Supports both single-connection and split-connection layouts (separate
+ * `store`, `stream`, and `sub` connections for advanced deployments).
  */
 class ConnectionService {
     /**
@@ -16,7 +15,10 @@ class ConnectionService {
      */
     constructor() { }
     /**
-     * Instance initializer
+     * Create a connection configuration object.
+     *
+     * @param config - Single `{ class, options }` or split `{ store, stream, sub }`.
+     * @returns The normalized connection configuration.
      */
     static async connect(config) {
         return 'store' in config
@@ -28,4 +30,8 @@ class ConnectionService {
             };
     }
 }
+/**
+ * Alias for {@link connect}.
+ */
+ConnectionService.create = ConnectionService.connect;
 exports.ConnectionService = ConnectionService;

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

@@ -4,28 +4,24 @@ import { JobInterruptOptions } from '../../types/job';
 import { StreamError } from '../../types/stream';
 import { ExporterService } from './exporter';
 /**
- * The WorkflowHandleService provides methods to interact with a running
- * workflow. This includes exporting the workflow, sending signals, and
- * querying the state of the workflow. It is instanced/accessed via the
- * Durable.Client class.
+ * Handle to a running or completed workflow execution. Returned by
+ * `client.workflow.start()` and `client.workflow.getHandle()`.
  *
  * @example
  * ```typescript
- * import { Client } from '@hotmeshio/hotmesh';
- * import { Client as Postgres } from 'pg';
- *
- * const client = new Client({ connection: {
- *   class: Postgres,
- *   options: { connectionString: 'postgres://user:pass@localhost:5432/db' }
- * }});
- *
  * const handle = await client.workflow.start({
- *  args: ['HotMesh'],
- *  taskQueue: 'hello-world',
+ *   args: ['order-123'],
+ *   taskQueue: 'orders',
+ *   workflowName: 'orderWorkflow',
+ *   workflowId: Durable.guid(),
  * });
  *
- * //perform actions like send a signal
- * await handle.signal('my-signal', { data: 'Hello' });
+ * // Await the final result
+ * const result = await handle.result();
+ *
+ * // Or interact while running
+ * await handle.signal('approval', { approved: true });
+ * await handle.cancel();
  * ```
  */
 export declare class WorkflowHandleService {
@@ -41,7 +37,8 @@ export declare class WorkflowHandleService {
      */
     constructor(hotMesh: HotMesh, workflowTopic: string, workflowId: string);
     /**
-     * Exports the workflow state to a JSON object.
+     * Exports the full workflow state (job hash, metadata, activity
+     * results) as a JSON object.
      */
     export(options?: ExportOptions): Promise<DurableJobExport>;
     /**
@@ -56,43 +53,64 @@ export declare class WorkflowHandleService {
      */
     exportExecution(options?: ExecutionExportOptions): Promise<WorkflowExecution>;
     /**
-     * Sends a signal to the workflow. This is a way to send
-     * a message to a workflow that is paused due to having
-     * executed `Durable.workflow.waitFor`. The workflow
-     * will awaken if no other signals are pending.
+     * Delivers a named signal to the workflow. If the workflow is paused
+     * on `Durable.workflow.condition(signalId)`, it resumes with the
+     * provided data.
+     *
+     * @param signalId - Matches the `signalId` passed to `condition()`.
+     * @param data - Payload delivered to the waiting workflow.
      */
     signal(signalId: string, data: Record<any, any>): Promise<void>;
     /**
-     * Returns the job state of the workflow. If the workflow has completed
-     * this is also the job output. If the workflow is still running, this
-     * is the current state of the job, but it may change depending upon
-     * the activities that remain.
+     * Returns the current workflow state. For a completed workflow this
+     * is the final output; for a running workflow it reflects the latest
+     * persisted state (may change as activities complete).
+     *
+     * @param metadata - If `true`, returns the full job envelope including
+     *   internal metadata alongside the data.
      */
     state(metadata?: boolean): Promise<Record<string, any>>;
     /**
-     * Returns the current search state of the workflow. This is
-     * different than the job state or individual activity state.
-     * Search state represents name/value pairs that were added
-     * to the workflow.
+     * Returns key-value pairs previously written via
+     * `Durable.workflow.search()` or `Durable.workflow.enrich()`.
+     *
+     * @param fields - The field names to retrieve.
      */
     queryState(fields: string[]): Promise<Record<string, any>>;
     /**
-     * Returns the current status of the workflow. This is a semaphore
-     * value that represents the current state of the workflow, where
-     * 0 is complete and a negative value represents that the flow was
-     * interrupted.
+     * Returns the workflow's numeric status code: `0` = completed,
+     * positive = still running, negative = interrupted/errored.
      */
     status(): Promise<number>;
     /**
-     * Interrupts a running workflow. Standard Job Completion tasks will
-     * run. Subscribers will be notified and the job hash will be expired.
+     * Immediately terminates the workflow. The job is marked as interrupted,
+     * subscribers are notified, and the job hash is expired. Unlike
+     * {@link cancel}, this does **not** give the workflow a chance to
+     * run cleanup code.
      */
-    interrupt(options?: JobInterruptOptions): Promise<string>;
+    terminate(options?: JobInterruptOptions): Promise<string>;
     /**
-     * Waits for the workflow to complete and returns the result. If
-     * the workflow response includes an error, this method will rethrow
-     * the error, including the stack trace if available.
-     * Wrap calls in a try/catch as necessary to avoid unhandled exceptions.
+     * Requests cooperative cancellation of the workflow. Unlike
+     * `terminate()` (which terminates immediately), `cancel()` sets
+     * a durable flag that the workflow detects at its next durable
+     * operation (`sleep`, `proxyActivities`, `executeChild`, etc.).
+     * The workflow receives a `CancelledFailure` error that it can
+     * catch to perform cleanup before exiting.
+     *
+     * ```typescript
+     * const handle = await client.workflow.start({ ... });
+     * await handle.cancel();
+     * // Workflow will throw CancelledFailure at its next durable operation
+     * ```
+     */
+    cancel(): Promise<void>;
+    /**
+     * Blocks until the workflow completes and returns the result. If the
+     * workflow failed, the error is rethrown (with stack trace) unless
+     * `throwOnError: false` is set, in which case the error object is
+     * returned directly.
+     *
+     * @template T - The workflow's return type.
      */
     result<T>(config?: {
         state?: boolean;