@hotmeshio/hotmesh 0.12.1 → 0.14.0

package/build/services/durable/telemetry.js

@@ -0,0 +1,137 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DurableTelemetryService = void 0;
+const package_json_1 = __importDefault(require("../../package.json"));
+const enums_1 = require("../../modules/enums");
+const telemetry_1 = require("../../types/telemetry");
+/**
+ * Emits OpenTelemetry spans for durable workflow execution. All methods
+ * are no-ops when no OTel SDK is registered — `@opentelemetry/api`
+ * returns a no-op tracer by default, so there is zero overhead without
+ * a configured exporter.
+ *
+ * ## Span Categories
+ *
+ * | Span | When | Mode |
+ * |------|------|------|
+ * | `WORKFLOW/START/{name}` | First execution (not replay) | `info` |
+ * | `WORKFLOW/COMPLETE/{name}` | Workflow returns successfully | `info` |
+ * | `WORKFLOW/ERROR/{name}` | Workflow throws a fatal error | `info` |
+ * | `ACTIVITY/{name}` | Real wall-clock activity execution on the worker | `info` |
+ * | `DISPATCH/{type}/{name}/{idx}` | Operation dispatched (first execution only) | `debug` |
+ * | `RETURN/{type}/{name}/{idx}` | Operation result returned (with ac/au duration) | `debug` |
+ *
+ * ## Gating
+ *
+ * - `isEnabled()` — true when `HMSH_TELEMETRY` is set (any value)
+ * - `isVerbose()` — true only when `HMSH_TELEMETRY === 'debug'`
+ *
+ * In `info` mode, engine-layer spans (stream hops, DAG activity spans)
+ * are suppressed for durable workflows — only the spans above are
+ * emitted. This keeps dashboards clean and focused on the user's
+ * workflow story. Set `HMSH_TELEMETRY=debug` to also see engine
+ * internals and per-operation DISPATCH/RETURN spans.
+ *
+ * ## Setup
+ *
+ * Register an OTel SDK with a trace exporter before starting workers:
+ *
+ * ```typescript
+ * import { NodeSDK } from '@opentelemetry/sdk-node';
+ * import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
+ * import { resourceFromAttributes } from '@opentelemetry/resources';
+ * import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
+ *
+ * const sdk = new NodeSDK({
+ *   resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: 'my-service' }),
+ *   traceExporter: new OTLPTraceExporter({
+ *     url: 'https://api.honeycomb.io/v1/traces',
+ *     headers: { 'x-honeycomb-team': process.env.HONEYCOMB_API_KEY },
+ *   }),
+ * });
+ * sdk.start();
+ * ```
+ *
+ * ```bash
+ * # Concise workflow telemetry (recommended for production)
+ * HMSH_TELEMETRY=info node worker.js
+ *
+ * # Full operational detail (debugging)
+ * HMSH_TELEMETRY=debug node worker.js
+ * ```
+ */
+class DurableTelemetryService {
+    static isEnabled() {
+        return !!enums_1.HMSH_TELEMETRY;
+    }
+    static isVerbose() {
+        return enums_1.HMSH_TELEMETRY === 'debug';
+    }
+    static getParentContext(traceId, spanId) {
+        const restoredSpanContext = {
+            traceId,
+            spanId,
+            isRemote: true,
+            traceFlags: 1,
+        };
+        return telemetry_1.trace.setSpanContext(telemetry_1.context.active(), restoredSpanContext);
+    }
+    /**
+     * Emit a point-in-time span (starts and ends immediately).
+     */
+    static emitPointSpan(traceId, parentSpanId, spanName, attributes, statusCode, statusMessage) {
+        const tracer = telemetry_1.trace.getTracer(package_json_1.default.name, package_json_1.default.version);
+        const parentContext = DurableTelemetryService.getParentContext(traceId, parentSpanId);
+        telemetry_1.context.with(parentContext, () => {
+            const span = tracer.startSpan(spanName, {
+                kind: telemetry_1.SpanKind.CLIENT,
+                attributes,
+            });
+            if (statusCode !== undefined) {
+                span.setStatus({ code: statusCode, message: statusMessage });
+            }
+            span.end();
+        });
+    }
+    /**
+     * Emit a duration span with explicit start/end times.
+     * Used for reconstructing operation durations from stored timestamps.
+     */
+    static emitDurationSpan(traceId, parentSpanId, spanName, startTimeMs, endTimeMs, attributes) {
+        const tracer = telemetry_1.trace.getTracer(package_json_1.default.name, package_json_1.default.version);
+        const parentContext = DurableTelemetryService.getParentContext(traceId, parentSpanId);
+        telemetry_1.context.with(parentContext, () => {
+            const span = tracer.startSpan(spanName, {
+                kind: telemetry_1.SpanKind.CLIENT,
+                attributes,
+                startTime: startTimeMs,
+            }, parentContext);
+            span.end(endTimeMs);
+        });
+    }
+    /**
+     * Start a span and return it for manual end (e.g., wrapping activity execution).
+     */
+    static startSpan(traceId, parentSpanId, spanName, attributes) {
+        const tracer = telemetry_1.trace.getTracer(package_json_1.default.name, package_json_1.default.version);
+        const parentContext = DurableTelemetryService.getParentContext(traceId, parentSpanId);
+        return tracer.startSpan(spanName, {
+            kind: telemetry_1.SpanKind.CLIENT,
+            attributes,
+        }, parentContext);
+    }
+    /**
+     * Parse ac/au timestamps from jmark results to epoch ms.
+     * Handles both ISO strings and numeric epoch values.
+     */
+    static parseTimestamp(ts) {
+        if (typeof ts === 'number')
+            return ts;
+        const parsed = Date.parse(ts);
+        return isNaN(parsed) ? Date.now() : parsed;
+    }
+}
+exports.DurableTelemetryService = DurableTelemetryService;

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

@@ -2,28 +2,90 @@ import { HotMesh } from '../hotmesh';
 import { Connection, Registry, WorkerConfig, WorkerOptions } from '../../types/durable';
 import { StreamData, StreamDataResponse } from '../../types/stream';
 /**
- * The *Worker* service Registers worker functions and connects them to the mesh,
- * using the target backend provider/s (Postgres, NATS, etc).
+ * Hosts workflow and activity functions, connecting them to Postgres
+ * for durable execution, replay, and automatic retry.
+ *
+ * ## Connection Modes
+ *
+ * ### Standard (legacy) — full admin access
+ *
+ * The worker connects with the same Postgres credentials as the engine.
+ * Simple to set up; all workers share the same connection pool.
  *
- * @example
  * ```typescript
- * import { Durable } from '@hotmeshio/hotmesh';
- * import { Client as Postgres } from 'pg';
- * import * as workflows from './workflows';
+ * const worker = await Durable.Worker.create({
+ *   connection: {
+ *     class: Postgres,
+ *     options: { connectionString: 'postgres://user:pass@host:5432/hotmesh' },
+ *   },
+ *   taskQueue: 'orders',
+ *   workflow: orderWorkflow,
+ * });
+ * ```
  *
- * async function run() {
- *   const worker = await Durable.Worker.create({
- *     connection: {
- *       class: Postgres,
- *       options: { connectionString: 'postgres://user:password@localhost:5432/db' }
- *     },
- *     taskQueue: 'default',
- *     workflow: workflows.example,
- *   });
+ * ### Secured — scoped Postgres role (recommended for production)
  *
- *   await worker.run();
- * }
+ * The worker connects as a restricted Postgres role that can only
+ * dequeue/ack/respond on its assigned stream names. All data access
+ * goes through SECURITY DEFINER stored procedures that validate the
+ * role's `app.allowed_streams` session variable before executing.
+ *
+ * **Step 1**: Provision a scoped credential (run once, from the engine/admin):
+ * ```typescript
+ * const cred = await Durable.provisionWorkerRole({
+ *   connection: { class: Postgres, options: adminPgOptions },
+ *   namespace: 'durable',
+ *   streamNames: ['orders-activity'],
+ * });
+ * // cred = { roleName: 'hmsh_wrk_durable_orders_activity', password: '...' }
  * ```
+ *
+ * **Step 2**: Pass the credential when creating the worker:
+ * ```typescript
+ * const worker = await Durable.Worker.create({
+ *   connection: {
+ *     class: Postgres,
+ *     options: { host: 'pg.prod', port: 5432, database: 'hotmesh' },
+ *   },
+ *   taskQueue: 'orders',
+ *   workflow: orderWorkflow,
+ *   workerCredentials: { user: cred.roleName, password: cred.password },
+ * });
+ * ```
+ *
+ * The worker role **cannot**:
+ * - SELECT/INSERT/UPDATE/DELETE any table directly
+ * - Access `jobs`, `jobs_attributes`, or any engine tables
+ * - Dequeue messages from other workers' streams
+ * - LISTEN on other workers' notification channels
+ *
+ * See {@link Durable.provisionWorkerRole} for credential lifecycle management.
+ *
+ * ## Telemetry
+ *
+ * Workers automatically emit OpenTelemetry spans when an OTel SDK is
+ * registered. Initialize the SDK **before** calling `create()`:
+ *
+ * ```typescript
+ * import { NodeSDK } from '@opentelemetry/sdk-node';
+ * import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
+ * import { resourceFromAttributes } from '@opentelemetry/resources';
+ * import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
+ *
+ * const sdk = new NodeSDK({
+ *   resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: 'my-service' }),
+ *   traceExporter: new OTLPTraceExporter({
+ *     url: 'https://api.honeycomb.io/v1/traces',
+ *     headers: { 'x-honeycomb-team': process.env.HONEYCOMB_API_KEY },
+ *   }),
+ * });
+ * sdk.start();
+ * ```
+ *
+ * | `HMSH_TELEMETRY` | Spans emitted |
+ * |-------|---------------|
+ * | `'info'` (default) | `WORKFLOW/START`, `WORKFLOW/COMPLETE`, `WORKFLOW/ERROR`, `ACTIVITY/{name}` |
+ * | `'debug'` | All `info` spans + `DISPATCH/RETURN` per operation + engine internals |
  */
 export declare class WorkerService {
     /**
@@ -106,7 +168,7 @@ export declare class WorkerService {
      *     sendEmail: (to: string, subject: string) => Promise<void>;
      *   }>({
      *     taskQueue: 'payment',
-     *     retryPolicy: { maximumAttempts: 3 }
+     *     retry: { maximumAttempts: 3 }
      *   });
      *
      *   const result = await processPayment(amount);
@@ -135,19 +197,36 @@ export declare class WorkerService {
      *   taskQueue: 'shared'
      * }, { auditLog, collectMetrics }, 'shared');
      *
-     * const interceptor: WorkflowInterceptor = {
+     * const interceptor: WorkflowInboundCallsInterceptor = {
      *   async execute(ctx, next) {
      *     const { auditLog } = Durable.workflow.proxyActivities<{
      *       auditLog: (id: string, action: string) => Promise<void>;
      *     }>({
      *       taskQueue: 'shared',
-     *       retryPolicy: { maximumAttempts: 3 }
+     *       retry: { maximumAttempts: 3 }
      *     });
      *     await auditLog(ctx.get('workflowId'), 'started');
      *     return next();
      *   }
      * };
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Secured worker with scoped Postgres credentials (VNF-style isolation)
+     * // Step 1: Admin provisions a credential (one-time)
+     * const cred = await Durable.provisionWorkerRole({
+     *   connection: { class: Postgres, options: adminOptions },
+     *   streamNames: ['payment-activity'],
+     * });
+     *
+     * // Step 2: Worker connects with scoped role — can only access payment-activity
+     * await Durable.registerActivityWorker({
+     *   connection: { class: Postgres, options: { host: 'pg.prod', database: 'hotmesh' } },
+     *   taskQueue: 'payment',
+     *   workerCredentials: { user: cred.roleName, password: cred.password },
+     * }, { processPayment, refundPayment });
+     * ```
      */
     static registerActivityWorker(config: Partial<WorkerConfig>, activities: any, activityTaskQueue?: string): Promise<HotMesh>;
     /**
@@ -156,7 +235,7 @@ export declare class WorkerService {
      */
     static createActivityCallback(): (payload: StreamData) => Promise<StreamDataResponse>;
     /**
-     * Connects a worker to the mesh.
+     * Creates and starts a workflow worker.
      *
      * @example
      * ```typescript