@hotmeshio/hotmesh 0.13.0 → 0.14.0

package/build/services/durable/index.js

@@ -14,266 +14,83 @@ const handle_1 = require("./handle");
 const interruption_1 = require("./workflow/interruption");
 const interceptor_1 = require("./interceptor");
 /**
- * The Durable service provides a workflow framework backed by Postgres.
- * It offers entity-based memory management and composable, fault-tolerant
- * workflows authored in a familiar procedural style.
+ * Durable workflow engine backed by Postgres. Write workflows as plain
+ * async functions; the engine handles persistence, replay, retry, and
+ * crash recovery automatically.
+ *
+ * ## Architecture
+ *
+ * | Component | Role |
+ * |-----------|------|
+ * | {@link Worker} | Hosts workflow and activity functions |
+ * | {@link Client} | Starts workflows, sends signals, reads results |
+ * | {@link workflow} | In-workflow API (`proxyActivities`, `sleep`, `condition`, ...) |
+ *
+ * ## Workflow Primitives
+ *
+ * All methods below are available as `Durable.workflow.<method>` inside
+ * a workflow function. Each call is durable — results are persisted and
+ * replayed deterministically on recovery.
+ *
+ * | Primitive | Purpose |
+ * |-----------|---------|
+ * | `proxyActivities` | Execute side-effectful code with automatic retry |
+ * | `sleep` | Durable timer (survives restarts) |
+ * | `condition` | Pause until a named signal arrives (with optional timeout) |
+ * | `signal` | Deliver data to a waiting `condition` |
+ * | `executeChild` | Spawn a child workflow and await its result |
+ * | `startChild` | Fire-and-forget child workflow |
+ * | `continueAsNew` | Restart the workflow with new args (resets history) |
+ * | `patched` / `deprecatePatch` | Safe versioning for in-flight workflow code changes |
+ * | `CancellationScope.nonCancellable` | Shield cleanup code from cancellation |
+ * | `isCancellation` | Detect cooperative cancellation errors |
+ *
+ * ## Quick Start
  *
- * ## Core Features
- *
- * ### 1. Entity-Based Memory Model
- * Each workflow has a durable JSONB entity that serves as its memory:
  * ```typescript
- * export async function researchAgent(query: string) {
- *   const agent = await Durable.workflow.entity();
+ * import { Durable } from '@hotmeshio/hotmesh';
+ * import { Client as Postgres } from 'pg';
+ * import * as activities from './activities';
  *
- *   // Initialize entity state
- *   await agent.set({
- *     query,
- *     findings: [],
- *     status: 'researching'
+ * // 1. Define a workflow
+ * async function orderWorkflow(orderId: string): Promise<string> {
+ *   const { charge, notify } = Durable.workflow.proxyActivities<typeof activities>({
+ *     activities,
+ *     retry: { maximumAttempts: 3 },
  *   });
  *
- *   // Update state atomically
- *   await agent.merge({ status: 'analyzing' });
- *   await agent.append('findings', newFinding);
+ *   const receipt = await charge(orderId);
+ *   await Durable.workflow.sleep('1 hour');
+ *   await notify(orderId, receipt);
+ *   return receipt;
  * }
- * ```
- *
- * ### 2. Hook Functions & Workflow Coordination
- * Spawn and coordinate multiple perspectives/phases:
- * ```typescript
- * // Launch parallel research perspectives
- * await Durable.workflow.execHook({
- *   taskQueue: 'research',
- *   workflowName: 'optimisticView',
- *   args: [query],
- *   signalId: 'optimistic-complete'
- * });
- *
- * await Durable.workflow.execHook({
- *   taskQueue: 'research',
- *   workflowName: 'skepticalView',
- *   args: [query],
- *   signalId: 'skeptical-complete'
- * });
- *
- * // Wait for both perspectives
- * await Promise.all([
- *   Durable.workflow.waitFor('optimistic-complete'),
- *   Durable.workflow.waitFor('skeptical-complete')
- * ]);
- * ```
- *
- * ### 3. Durable Activities & Proxies
- * Define and execute durable activities with automatic retry:
- * ```typescript
- * // Default: activities use workflow's task queue
- * const activities = Durable.workflow.proxyActivities<{
- *   analyzeDocument: typeof analyzeDocument;
- *   validateFindings: typeof validateFindings;
- * }>({
- *   activities: { analyzeDocument, validateFindings },
- *   retryPolicy: {
- *     maximumAttempts: 3,
- *     backoffCoefficient: 2
- *   }
- * });
- *
- * // Activities are durable and automatically retried
- * const analysis = await activities.analyzeDocument(data);
- * const validation = await activities.validateFindings(analysis);
- * ```
- *
- * ### 4. Explicit Activity Registration
- * Register activity workers explicitly before workflows start:
- * ```typescript
- * // Register shared activity pool for interceptors
- * await Durable.registerActivityWorker({
- *   connection: {
- *     class: Postgres,
- *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
- *   },
- *   taskQueue: 'shared-activities'
- * }, sharedActivities, 'shared-activities');
- *
- * // Register custom activity pool for specific use cases
- * await Durable.registerActivityWorker({
- *   connection: {
- *     class: Postgres,
- *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
- *   },
- *   taskQueue: 'priority-activities'
- * }, priorityActivities, 'priority-activities');
- * ```
- *
- * ### 5. Workflow Composition
- * Build complex workflows through composition:
- * ```typescript
- * // Start a child workflow
- * const childResult = await Durable.workflow.execChild({
- *   taskQueue: 'analysis',
- *   workflowName: 'detailedAnalysis',
- *   args: [data],
- *   // Child workflow config
- *   config: {
- *     maximumAttempts: 5,
- *     backoffCoefficient: 2
- *   }
- * });
- *
- * // Fire-and-forget child workflow
- * await Durable.workflow.startChild({
- *   taskQueue: 'notifications',
- *   workflowName: 'sendUpdates',
- *   args: [updates]
- * });
- * ```
- *
- * ### 6. Workflow Interceptors
- * Add cross-cutting concerns through interceptors that run as durable functions:
- * ```typescript
- * // First register shared activity worker for interceptors
- * await Durable.registerActivityWorker({
- *   connection: {
- *     class: Postgres,
- *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
- *   },
- *   taskQueue: 'interceptor-activities'
- * }, { auditLog }, 'interceptor-activities');
- *
- * // Add audit interceptor that uses activities with explicit taskQueue
- * Durable.registerInterceptor({
- *   async execute(ctx, next) {
- *     try {
- *       // Interceptors use explicit taskQueue to prevent per-workflow queues
- *       const { auditLog } = Durable.workflow.proxyActivities<typeof activities>({
- *         activities: { auditLog },
- *         taskQueue: 'interceptor-activities', // Explicit shared queue
- *         retryPolicy: { maximumAttempts: 3 }
- *       });
- *
- *       await auditLog(ctx.get('workflowId'), 'started');
- *
- *       const result = await next();
- *
- *       await auditLog(ctx.get('workflowId'), 'completed');
- *
- *       return result;
- *     } catch (err) {
- *       // CRITICAL: Always check for HotMesh interruptions
- *       if (Durable.didInterrupt(err)) {
- *         throw err; // Rethrow for replay system
- *       }
- *       throw err;
- *     }
- *   }
- * });
- * ```
- *
- * ### 7. Activity Interceptors
- * Wrap individual proxied activity calls with cross-cutting logic.
- * Unlike workflow interceptors (which wrap the entire workflow), activity
- * interceptors execute around each `proxyActivities` call. They run inside
- * the workflow's execution context and have access to all Durable workflow
- * methods (`proxyActivities`, `sleepFor`, `waitFor`, `execChild`, etc.).
- * Multiple activity interceptors execute in onion order (first registered
- * is outermost).
- * ```typescript
- * // Simple logging interceptor
- * Durable.registerActivityInterceptor({
- *   async execute(activityCtx, workflowCtx, next) {
- *     console.log(`Activity ${activityCtx.activityName} starting`);
- *     try {
- *       const result = await next();
- *       console.log(`Activity ${activityCtx.activityName} completed`);
- *       return result;
- *     } catch (err) {
- *       if (Durable.didInterrupt(err)) throw err;
- *       console.error(`Activity ${activityCtx.activityName} failed`);
- *       throw err;
- *     }
- *   }
- * });
- *
- * // Interceptor that calls its own proxy activities
- * await Durable.registerActivityWorker({
- *   connection: {
- *     class: Postgres,
- *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
- *   },
- *   taskQueue: 'audit-activities'
- * }, { auditLog }, 'audit-activities');
  *
- * Durable.registerActivityInterceptor({
- *   async execute(activityCtx, workflowCtx, next) {
- *     try {
- *       const { auditLog } = Durable.workflow.proxyActivities<{
- *         auditLog: (id: string, action: string) => Promise<void>;
- *       }>({
- *         taskQueue: 'audit-activities',
- *         retryPolicy: { maximumAttempts: 3 }
- *       });
+ * // 2. Start a worker
+ * const connection = { class: Postgres, options: { connectionString: 'postgresql://...' } };
+ * await Durable.Worker.create({ connection, taskQueue: 'orders', workflow: orderWorkflow });
  *
- *       await auditLog(workflowCtx.get('workflowId'), `before:${activityCtx.activityName}`);
- *       const result = await next();
- *       await auditLog(workflowCtx.get('workflowId'), `after:${activityCtx.activityName}`);
- *       return result;
- *     } catch (err) {
- *       if (Durable.didInterrupt(err)) throw err;
- *       throw err;
- *     }
- *   }
+ * // 3. Start a workflow from the client
+ * const client = new Durable.Client({ connection });
+ * const handle = await client.workflow.start({
+ *   args: ['order-123'],
+ *   taskQueue: 'orders',
+ *   workflowName: 'orderWorkflow',
+ *   workflowId: Durable.guid(),
  * });
+ * const result = await handle.result();
  * ```
  *
- * ## Basic Usage Example
- *
- * ```typescript
- * import { Client, Worker, Durable } from '@hotmeshio/hotmesh';
- * import { Client as Postgres } from 'pg';
- * import * as activities from './activities';
- *
- * // (Optional) Register shared activity workers for interceptors
- * await Durable.registerActivityWorker({
- *   connection: {
- *     class: Postgres,
- *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
- *   },
- *   taskQueue: 'shared-activities'
- * }, sharedActivities, 'shared-activities');
- *
- * // Initialize worker
- * await Worker.create({
- *   connection: {
- *     class: Postgres,
- *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
- *   },
- *   taskQueue: 'default',
- *   workflow: workflows.example
- * });
- *
- * // Initialize client
- * const client = new Client({
- *   connection: {
- *     class: Postgres,
- *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
- *   }
- * });
+ * ## Interceptors
  *
- * // Start workflow
- * const handle = await client.workflow.start({
- *   args: ['input data'],
- *   taskQueue: 'default',
- *   workflowName: 'example',
- *   workflowId: Durable.guid()
- * });
+ * Cross-cutting concerns (logging, auth, metrics) attach via interceptors.
+ * See {@link registerInboundInterceptor} (wraps workflows) and
+ * {@link registerOutboundInterceptor} (wraps individual activity calls).
  *
- * // Get result
- * const result = await handle.result();
+ * ## Secured Workers
  *
- * // Cleanup
- * await Durable.shutdown();
- * ```
+ * For production isolation, workers can connect with scoped Postgres
+ * credentials that restrict access to specific task queues via stored
+ * procedures. See {@link WorkerService.create} and {@link provisionWorkerRole}.
  */
 class DurableClass {
     /**
@@ -288,8 +105,8 @@ class DurableClass {
      * logging, metrics, or tracing.
      *
      * Workflow interceptors run inside the workflow's async local storage context,
-     * so all Durable workflow methods (`proxyActivities`, `sleepFor`, `waitFor`,
-     * `execChild`, etc.) are available. When using Durable functions, always check
+     * so all Durable workflow methods (`proxyActivities`, `sleep`, `condition`,
+     * `executeChild`, etc.) are available. When using Durable functions, always check
      * for interruptions with `Durable.didInterrupt(err)` and rethrow them.
      *
      * @param interceptor The interceptor to register
@@ -297,7 +114,7 @@ class DurableClass {
      * @example
      * ```typescript
      * // Logging interceptor
-     * Durable.registerInterceptor({
+     * Durable.registerInboundInterceptor({
      *   async execute(ctx, next) {
      *     console.log(`Workflow ${ctx.get('workflowName')} starting`);
      *     try {
@@ -313,32 +130,32 @@ class DurableClass {
      * });
      * ```
      */
-    static registerInterceptor(interceptor) {
-        DurableClass.interceptorService.register(interceptor);
+    static registerInboundInterceptor(interceptor) {
+        DurableClass.interceptorService.registerInbound(interceptor);
     }
     /**
-     * Clear all registered interceptors (both workflow and activity).
+     * Clear all registered interceptors (both inbound and outbound).
      */
     static clearInterceptors() {
         DurableClass.interceptorService.clear();
     }
     /**
-     * Register an activity interceptor that wraps individual proxied
+     * Register an outbound interceptor that wraps individual proxied
      * activity calls within workflows. Interceptors execute in registration
      * order (first registered is outermost) using the onion pattern.
      *
-     * Activity interceptors run inside the workflow's execution context
+     * Outbound interceptors run inside the workflow's execution context
      * and have access to all Durable workflow methods (`proxyActivities`,
-     * `sleepFor`, `waitFor`, `execChild`, etc.). The `activityCtx` parameter
+     * `sleep`, `condition`, `executeChild`, etc.). The `activityCtx` parameter
      * provides `activityName`, `args`, and `options` for the call being
      * intercepted. The `workflowCtx` map provides workflow metadata
      * (`workflowId`, `workflowName`, `namespace`, etc.).
      *
-     * @param interceptor The activity interceptor to register
+     * @param interceptor The outbound interceptor to register
      *
      * @example
      * ```typescript
-     * Durable.registerActivityInterceptor({
+     * Durable.registerOutboundInterceptor({
      *   async execute(activityCtx, workflowCtx, next) {
      *     const start = Date.now();
      *     try {
@@ -353,14 +170,31 @@ class DurableClass {
      * });
      * ```
      */
-    static registerActivityInterceptor(interceptor) {
-        DurableClass.interceptorService.registerActivity(interceptor);
+    static registerOutboundInterceptor(interceptor) {
+        DurableClass.interceptorService.registerOutbound(interceptor);
+    }
+    /**
+     * Clear all registered outbound interceptors
+     */
+    static clearOutboundInterceptors() {
+        DurableClass.interceptorService.clearOutbound();
     }
     /**
-     * Clear all registered activity interceptors
+     * Register an activity inbound interceptor that wraps the actual activity
+     * function execution on the activity worker side. This runs inside the
+     * activity's `AsyncLocalStorage` context, NOT the workflow context.
+     *
+     * Use for logging, metrics, auth validation, or error enrichment at
+     * the point where the activity actually executes.
+     */
+    static registerActivityInboundInterceptor(interceptor) {
+        DurableClass.interceptorService.registerActivityInbound(interceptor);
+    }
+    /**
+     * Clear all registered activity inbound interceptors.
      */
-    static clearActivityInterceptors() {
-        DurableClass.interceptorService.clearActivity();
+    static clearActivityInboundInterceptors() {
+        DurableClass.interceptorService.clearActivityInbound();
     }
     /**
      * Get the interceptor service instance
@@ -370,8 +204,8 @@ class DurableClass {
         return DurableClass.interceptorService;
     }
     /**
-     * Shutdown everything. All connections, workers, and clients will be closed.
-     * Include in your signal handlers to ensure a clean shutdown.
+     * Gracefully shut down all workers, clients, and connections.
+     * Call from your process signal handlers (`SIGTERM`, `SIGINT`).
      */
     static async shutdown() {
         await DurableClass.Client.shutdown();
@@ -381,33 +215,30 @@ class DurableClass {
 }
 exports.Durable = DurableClass;
 /**
- * The Durable `Client` service is functionally
- * provides methods for starting, signaling, and querying workflows.
+ * Starts workflows, sends signals, and reads results. Instantiate
+ * with a connection, then use `client.workflow.start()` to launch
+ * a workflow and obtain a {@link Handle}.
  */
 DurableClass.Client = client_1.ClientService;
 /**
- * The Durable `Connection` service
- * manages database connections for the durable workflow engine.
+ * Declares connection options (class + config) for Postgres.
+ * The actual connection is established lazily when a workflow
+ * or worker is started.
  */
 DurableClass.Connection = connection_1.ConnectionService;
-/**
- * @private
- */
+/** @private */
 DurableClass.Search = search_1.Search;
-/**
- * @private
- */
+/** @private */
 DurableClass.Entity = entity_1.Entity;
 /**
- * The Handle provides methods to interact with a running
- * workflow. This includes exporting the workflow, sending signals, and
- * querying the state of the workflow. An instance of the Handle service
- * is typically accessed via the Durable.Client class (workflow.getHandle).
+ * A handle to a running or completed workflow. Provides methods to
+ * read results, send signals, query state, cancel, or interrupt.
+ * Obtained via `client.workflow.start()` or `client.workflow.getHandle()`.
  */
 DurableClass.Handle = handle_1.WorkflowHandleService;
 /**
- * The Durable `Worker` service
- * registers workflow and activity workers and connects them to the mesh.
+ * Hosts workflow and activity functions. Call `Worker.create()` with
+ * a connection, task queue, and workflow function to start processing.
  */
 DurableClass.Worker = worker_1.WorkerService;
 /**
@@ -437,7 +268,7 @@ DurableClass.Worker = worker_1.WorkerService;
  *     sendEmail: (to: string, msg: string) => Promise<void>;
  *   }>({
  *     taskQueue: 'payment',
- *     retryPolicy: { maximumAttempts: 3 }
+ *     retry: { maximumAttempts: 3 }
  *   });
  *
  *   const result = await processPayment(amount);
@@ -454,23 +285,24 @@ DurableClass.Worker = worker_1.WorkerService;
  */
 DurableClass.registerActivityWorker = worker_1.WorkerService.registerActivityWorker;
 /**
- * The Durable `activity` service provides context to
- * executing activity functions. Call `Durable.activity.getContext()`
- * inside an activity to access metadata, workflow ID, and other
- * context passed from the parent workflow.
+ * Activity-side context. Call `Durable.activity.getContext()` inside
+ * an activity function to access the activity name, arguments,
+ * parent workflow ID, and other execution metadata.
  */
 DurableClass.activity = activity_1.ActivityService;
 /**
- * The Durable `workflow` service
- * provides the workflow-internal API surface with methods for
- * managing workflows, including: `execChild`, `waitFor`, `sleep`, etc
+ * The workflow-internal API. Every method on this object
+ * (`proxyActivities`, `sleep`, `condition`, `signal`, `executeChild`,
+ * `continueAsNew`, `patched`, `CancellationScope`, etc.) is designed
+ * to be called **inside** a workflow function and participates in
+ * deterministic replay.
  */
 DurableClass.workflow = workflow_1.WorkflowService;
 /**
- * Checks if an error is a HotMesh reserved error type that indicates
- * a workflow interruption rather than a true error condition.
- *
- * @see {@link didInterrupt} for detailed documentation
+ * Returns `true` if the error is an engine control-flow signal (replay
+ * suspension) rather than an application error. **Always check this in
+ * `catch` blocks inside workflows and interceptors** — swallowing an
+ * interruption breaks the replay system.
  */
 DurableClass.didInterrupt = interruption_1.didInterrupt;
 DurableClass.interceptorService = new interceptor_1.InterceptorService();
@@ -478,3 +310,36 @@ DurableClass.interceptorService = new interceptor_1.InterceptorService();
  * Generate a unique identifier for workflow IDs
  */
 DurableClass.guid = utils_1.guid;
+/**
+ * Provision a scoped Postgres role for a worker. The role can only
+ * dequeue, ack, and respond on its assigned stream names via stored
+ * procedures — zero direct table access.
+ *
+ * @example
+ * ```typescript
+ * const cred = await Durable.provisionWorkerRole({
+ *   connection: { class: Postgres, options: adminOptions },
+ *   streamNames: ['payment-activity'],
+ * });
+ *
+ * await Worker.create({
+ *   connection: { class: Postgres, options: pgOptions },
+ *   taskQueue: 'payment',
+ *   workflow: paymentWorkflow,
+ *   workerCredentials: cred,
+ * });
+ * ```
+ */
+DurableClass.provisionWorkerRole = hotmesh_1.HotMesh.provisionWorkerRole;
+/** Rotate a secured worker role's password. */
+DurableClass.rotateWorkerPassword = hotmesh_1.HotMesh.rotateWorkerPassword;
+/** Revoke a secured worker role (disables login). */
+DurableClass.revokeWorkerRole = hotmesh_1.HotMesh.revokeWorkerRole;
+/** List all provisioned secured worker roles. */
+DurableClass.listWorkerRoles = hotmesh_1.HotMesh.listWorkerRoles;
+/**
+ * Register a global payload codec for encrypting/decrypting workflow
+ * data at rest. The codec's `encode`/`decode` methods are called
+ * automatically on all persisted workflow payloads.
+ */
+DurableClass.registerCodec = hotmesh_1.HotMesh.registerCodec;