@hotmeshio/hotmesh 0.13.0 → 0.14.1

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

@@ -1,4 +1,5 @@
-import { ContextType, WorkflowInterceptor, ActivityInterceptor } from '../../types/durable';
+import { HotMesh } from '../hotmesh';
+import { ContextType, WorkflowInboundCallsInterceptor, WorkflowOutboundCallsInterceptor, ActivityInboundCallsInterceptor } from '../../types/durable';
 import { guid } from '../../modules/utils';
 import { ClientService } from './client';
 import { ConnectionService } from './connection';
@@ -10,266 +11,83 @@ import { WorkflowService } from './workflow';
 import { WorkflowHandleService } from './handle';
 import { didInterrupt } from './workflow/interruption';
 /**
- * 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.
  *
- * ## Core Features
+ * ## Architecture
  *
- * ### 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();
- *
- *   // Initialize entity state
- *   await agent.set({
- *     query,
- *     findings: [],
- *     status: 'researching'
- *   });
- *
- *   // Update state atomically
- *   await agent.merge({ status: 'analyzing' });
- *   await agent.append('findings', newFinding);
- * }
- * ```
- *
- * ### 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
- *   }
- * });
+ * | 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`, ...) |
  *
- * // 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');
+ * ## Workflow Primitives
  *
- * // 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 }
- *       });
+ * 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.
  *
- *       await auditLog(ctx.get('workflowId'), 'started');
+ * | 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 |
  *
- *       const result = await next();
+ * ## Quick Start
  *
- *       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 }
- *       });
- *
- *       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;
- *     }
- *   }
- * });
- * ```
- *
- * ## Basic Usage Example
- *
- * ```typescript
- * import { Client, Worker, Durable } from '@hotmeshio/hotmesh';
+ * import { 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');
+ * // 1. Define a workflow
+ * async function orderWorkflow(orderId: string): Promise<string> {
+ *   const { charge, notify } = Durable.workflow.proxyActivities<typeof activities>({
+ *     activities,
+ *     retry: { maximumAttempts: 3 },
+ *   });
  *
- * // Initialize worker
- * await Worker.create({
- *   connection: {
- *     class: Postgres,
- *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
- *   },
- *   taskQueue: 'default',
- *   workflow: workflows.example
- * });
+ *   const receipt = await charge(orderId);
+ *   await Durable.workflow.sleep('1 hour');
+ *   await notify(orderId, receipt);
+ *   return receipt;
+ * }
  *
- * // Initialize client
- * const client = new Client({
- *   connection: {
- *     class: Postgres,
- *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
- *   }
- * });
+ * // 2. Start a worker
+ * const connection = { class: Postgres, options: { connectionString: 'postgresql://...' } };
+ * await Durable.Worker.create({ connection, taskQueue: 'orders', workflow: orderWorkflow });
  *
- * // Start workflow
+ * // 3. Start a workflow from the client
+ * const client = new Durable.Client({ connection });
  * const handle = await client.workflow.start({
- *   args: ['input data'],
- *   taskQueue: 'default',
- *   workflowName: 'example',
- *   workflowId: Durable.guid()
+ *   args: ['order-123'],
+ *   taskQueue: 'orders',
+ *   workflowName: 'orderWorkflow',
+ *   workflowId: Durable.guid(),
  * });
- *
- * // Get result
  * const result = await handle.result();
- *
- * // Cleanup
- * await Durable.shutdown();
  * ```
+ *
+ * ## Interceptors
+ *
+ * Cross-cutting concerns (logging, auth, metrics) attach via interceptors.
+ * See {@link registerInboundInterceptor} (wraps workflows) and
+ * {@link registerOutboundInterceptor} (wraps individual activity calls).
+ *
+ * ## Secured Workers
+ *
+ * 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}.
  */
 declare class DurableClass {
     /**
@@ -277,33 +95,30 @@ declare class DurableClass {
      */
     constructor();
     /**
-     * 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}.
      */
     static Client: typeof 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.
      */
     static Connection: typeof ConnectionService;
-    /**
-     * @private
-     */
+    /** @private */
     static Search: typeof Search;
-    /**
-     * @private
-     */
+    /** @private */
     static Entity: typeof 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()`.
      */
     static Handle: typeof 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.
      */
     static Worker: typeof WorkerService;
     /**
@@ -333,7 +148,7 @@ declare class DurableClass {
      *     sendEmail: (to: string, msg: string) => Promise<void>;
      *   }>({
      *     taskQueue: 'payment',
-     *     retryPolicy: { maximumAttempts: 3 }
+     *     retry: { maximumAttempts: 3 }
      *   });
      *
      *   const result = await processPayment(amount);
@@ -350,23 +165,24 @@ declare class DurableClass {
      */
     static registerActivityWorker: typeof 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.
      */
     static activity: typeof 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.
      */
     static workflow: typeof 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.
      */
     static didInterrupt: typeof didInterrupt;
     private static interceptorService;
@@ -378,8 +194,8 @@ declare 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
@@ -387,7 +203,7 @@ declare class DurableClass {
      * @example
      * ```typescript
      * // Logging interceptor
-     * Durable.registerInterceptor({
+     * Durable.registerInboundInterceptor({
      *   async execute(ctx, next) {
      *     console.log(`Workflow ${ctx.get('workflowName')} starting`);
      *     try {
@@ -403,28 +219,28 @@ declare class DurableClass {
      * });
      * ```
      */
-    static registerInterceptor(interceptor: WorkflowInterceptor): void;
+    static registerInboundInterceptor(interceptor: WorkflowInboundCallsInterceptor): void;
     /**
-     * Clear all registered interceptors (both workflow and activity).
+     * Clear all registered interceptors (both inbound and outbound).
      */
     static clearInterceptors(): void;
     /**
-     * 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 {
@@ -439,18 +255,64 @@ declare class DurableClass {
      * });
      * ```
      */
-    static registerActivityInterceptor(interceptor: ActivityInterceptor): void;
+    static registerOutboundInterceptor(interceptor: WorkflowOutboundCallsInterceptor): void;
     /**
-     * Clear all registered activity interceptors
+     * Clear all registered outbound interceptors
+     */
+    static clearOutboundInterceptors(): void;
+    /**
+     * 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 clearActivityInterceptors(): void;
+    static registerActivityInboundInterceptor(interceptor: ActivityInboundCallsInterceptor): void;
+    /**
+     * Clear all registered activity inbound interceptors.
+     */
+    static clearActivityInboundInterceptors(): void;
     /**
      * Generate a unique identifier for workflow IDs
      */
     static guid: typeof guid;
     /**
-     * Shutdown everything. All connections, workers, and clients will be closed.
-     * Include in your signal handlers to ensure a clean shutdown.
+     * 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,
+     * });
+     * ```
+     */
+    static provisionWorkerRole: typeof import("../worker/credentials").provisionWorkerRole;
+    /** Rotate a secured worker role's password. */
+    static rotateWorkerPassword: typeof import("../worker/credentials").rotateWorkerPassword;
+    /** Revoke a secured worker role (disables login). */
+    static revokeWorkerRole: typeof import("../worker/credentials").revokeWorkerRole;
+    /** List all provisioned secured worker roles. */
+    static listWorkerRoles: typeof import("../worker/credentials").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.
+     */
+    static registerCodec: typeof HotMesh.registerCodec;
+    /**
+     * Gracefully shut down all workers, clients, and connections.
+     * Call from your process signal handlers (`SIGTERM`, `SIGINT`).
      */
     static shutdown(): Promise<void>;
 }