@hotmeshio/hotmesh 0.12.1 → 0.14.0

package/build/services/stream/providers/postgres/secured.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Secured SQL adapter for worker routers.
+ *
+ * Replaces raw SQL with calls to SECURITY DEFINER stored procedures.
+ * Workers using this adapter can only access their allowed streams —
+ * the stored procedures validate `app.allowed_streams` before executing.
+ */
+import { ILogger } from '../../../logger';
+import { PostgresClientType } from '../../../../types/postgres';
+import { ProviderClient } from '../../../../types/provider';
+import { StreamMessage } from '../../../../types/stream';
+/**
+ * Dequeue messages from worker_streams via stored procedure.
+ */
+export declare function fetchMessagesSecured(client: PostgresClientType & ProviderClient, schema: string, streamName: string, consumerName: string, options: {
+    batchSize?: number;
+    reservationTimeout?: number;
+    enableBackoff?: boolean;
+    initialBackoff?: number;
+    maxBackoff?: number;
+    maxRetries?: number;
+}, logger: ILogger): Promise<StreamMessage[]>;
+/**
+ * Ack/delete messages via stored procedure.
+ */
+export declare function ackAndDeleteSecured(client: PostgresClientType & ProviderClient, schema: string, streamName: string, messageIds: string[], logger: ILogger): Promise<number>;
+/**
+ * Dead-letter messages via stored procedure.
+ */
+export declare function deadLetterMessagesSecured(client: PostgresClientType & ProviderClient, schema: string, streamName: string, messageIds: string[], logger: ILogger): Promise<number>;
+/**
+ * Publish a response to engine_streams via stored procedure.
+ */
+export declare function publishMessagesSecured(client: PostgresClientType & ProviderClient, schema: string, streamName: string, messages: string[], logger: ILogger): Promise<string[]>;

package/build/services/stream/providers/postgres/secured.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * Secured SQL adapter for worker routers.
+ *
+ * Replaces raw SQL with calls to SECURITY DEFINER stored procedures.
+ * Workers using this adapter can only access their allowed streams —
+ * the stored procedures validate `app.allowed_streams` before executing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishMessagesSecured = exports.deadLetterMessagesSecured = exports.ackAndDeleteSecured = exports.fetchMessagesSecured = void 0;
+const utils_1 = require("../../../../modules/utils");
+const utils_2 = require("../../../../modules/utils");
+/**
+ * Dequeue messages from worker_streams via stored procedure.
+ */
+async function fetchMessagesSecured(client, schema, streamName, consumerName, options = {}, logger) {
+    const enableBackoff = options?.enableBackoff ?? false;
+    const initialBackoff = options?.initialBackoff ?? 100;
+    const maxBackoff = options?.maxBackoff ?? 3000;
+    const maxRetries = options?.maxRetries ?? 3;
+    const batchSize = options?.batchSize || 1;
+    const reservationTimeout = options?.reservationTimeout || 30;
+    let backoff = initialBackoff;
+    let retries = 0;
+    try {
+        while (retries < maxRetries) {
+            retries++;
+            const res = await client.query(`SELECT * FROM ${schema}.worker_dequeue($1, $2, $3, $4)`, [streamName, batchSize, consumerName, reservationTimeout]);
+            const messages = res.rows.map((row) => {
+                const data = (0, utils_2.parseStreamMessage)(row.message);
+                const hasDefaultRetryPolicy = (row.max_retry_attempts === 3 || row.max_retry_attempts === 5) &&
+                    parseFloat(row.backoff_coefficient) === 10 &&
+                    row.maximum_interval_seconds === 120;
+                if (row.max_retry_attempts !== null && !hasDefaultRetryPolicy) {
+                    data._streamRetryConfig = {
+                        max_retry_attempts: row.max_retry_attempts,
+                        backoff_coefficient: parseFloat(row.backoff_coefficient),
+                        maximum_interval_seconds: row.maximum_interval_seconds,
+                    };
+                }
+                if (row.retry_attempt !== undefined && row.retry_attempt !== null) {
+                    data._retryAttempt = row.retry_attempt;
+                }
+                if (row.workflow_name) {
+                    if (data.metadata) {
+                        data.metadata.wfn = row.workflow_name;
+                    }
+                }
+                return {
+                    id: row.id.toString(),
+                    data,
+                    retry: row.max_retry_attempts !== null && !hasDefaultRetryPolicy
+                        ? {
+                            maximumAttempts: row.max_retry_attempts,
+                            backoffCoefficient: parseFloat(row.backoff_coefficient),
+                            maximumInterval: row.maximum_interval_seconds,
+                        }
+                        : undefined,
+                };
+            });
+            if (messages.length > 0 || !enableBackoff) {
+                return messages;
+            }
+            await (0, utils_1.sleepFor)(backoff);
+            backoff = Math.min(backoff * 2, maxBackoff);
+        }
+        return [];
+    }
+    catch (error) {
+        logger.error(`postgres-secured-dequeue-error-${streamName}`, { error });
+        throw error;
+    }
+}
+exports.fetchMessagesSecured = fetchMessagesSecured;
+/**
+ * Ack/delete messages via stored procedure.
+ */
+async function ackAndDeleteSecured(client, schema, streamName, messageIds, logger) {
+    try {
+        const ids = messageIds.map((id) => parseInt(id));
+        const res = await client.query(`SELECT ${schema}.worker_ack($1, $2)`, [streamName, ids]);
+        return res.rows[0]?.worker_ack ?? messageIds.length;
+    }
+    catch (error) {
+        logger.error(`postgres-secured-ack-error-${streamName}`, { error });
+        throw error;
+    }
+}
+exports.ackAndDeleteSecured = ackAndDeleteSecured;
+/**
+ * Dead-letter messages via stored procedure.
+ */
+async function deadLetterMessagesSecured(client, schema, streamName, messageIds, logger) {
+    try {
+        const ids = messageIds.map((id) => parseInt(id));
+        const res = await client.query(`SELECT ${schema}.worker_dead_letter($1, $2)`, [streamName, ids]);
+        return res.rows[0]?.worker_dead_letter ?? 0;
+    }
+    catch (error) {
+        logger.error(`postgres-secured-dead-letter-error-${streamName}`, {
+            error,
+            messageIds,
+        });
+        throw error;
+    }
+}
+exports.deadLetterMessagesSecured = deadLetterMessagesSecured;
+/**
+ * Publish a response to engine_streams via stored procedure.
+ */
+async function publishMessagesSecured(client, schema, streamName, messages, logger) {
+    try {
+        const ids = [];
+        for (const msg of messages) {
+            const data = JSON.parse(msg);
+            const retryConfig = data._streamRetryConfig;
+            const visibilityDelayMs = data._visibilityDelayMs;
+            const retryAttempt = data._retryAttempt ?? 0;
+            // Remove internal fields
+            delete data._streamRetryConfig;
+            delete data._visibilityDelayMs;
+            delete data._retryAttempt;
+            const cleanMessage = JSON.stringify(data);
+            const visibleAt = visibilityDelayMs && visibilityDelayMs > 0
+                ? new Date(Date.now() + visibilityDelayMs).toISOString()
+                : new Date().toISOString();
+            const hasRetryConfig = retryConfig && 'max_retry_attempts' in retryConfig;
+            const res = await client.query(`SELECT ${schema}.worker_respond($1, $2, $3, $4, $5, $6, $7)`, [
+                streamName,
+                cleanMessage,
+                hasRetryConfig ? retryConfig.max_retry_attempts : null,
+                hasRetryConfig ? retryConfig.backoff_coefficient : null,
+                hasRetryConfig ? retryConfig.maximum_interval_seconds : null,
+                visibleAt,
+                retryAttempt,
+            ]);
+            ids.push(res.rows[0]?.worker_respond?.toString() ?? '0');
+        }
+        return ids;
+    }
+    catch (error) {
+        logger.error(`postgres-secured-respond-error-${streamName}`, { error });
+        throw error;
+    }
+}
+exports.publishMessagesSecured = publishMessagesSecured;

package/build/services/stream/providers/postgres/stats.d.ts

@@ -44,6 +44,7 @@ export declare function getProviderSpecificFeatures(config?: StreamConfig): {
     supportsTrimming: boolean;
     supportsRetry: boolean;
     supportsNotifications: boolean;
+    supportsParallelProcessing: boolean;
     maxMessageSize: number;
     maxBatchSize: number;
 };

package/build/services/stream/providers/postgres/stats.js

@@ -107,6 +107,7 @@ function getProviderSpecificFeatures(config = {}) {
         supportsTrimming: true,
         supportsRetry: false,
         supportsNotifications: isNotificationsEnabled(config),
+        supportsParallelProcessing: true,
         maxMessageSize: 1024 * 1024,
         maxBatchSize: 256,
     };

package/build/services/stream/registry.d.ts

@@ -23,7 +23,7 @@ declare class StreamConsumerRegistry {
     }, logger: ILogger, config?: {
         reclaimDelay?: number;
         reclaimCount?: number;
-        retryPolicy?: any;
+        retry?: any;
     }): Promise<void>;
     /**
      * Register an engine callback for an appId.

package/build/services/stream/registry.js

@@ -30,7 +30,7 @@ class StreamConsumerRegistry {
                 reclaimDelay: config?.reclaimDelay,
                 reclaimCount: config?.reclaimCount,
                 throttle,
-                retryPolicy: config?.retryPolicy,
+                retry: config?.retry,
             }, stream, logger);
             entry = {
                 router,
@@ -117,10 +117,13 @@ class StreamConsumerRegistry {
             }
             const callback = entry.callbacks.get(wfn);
             if (!callback) {
-                entry.logger.debug('stream-consumer-registry-no-callback', {
+                entry.logger.info('stream-consumer-registry-replay', {
                     key,
                     wfn,
                     registered: [...entry.callbacks.keys()],
+                    reason: 'worker-not-yet-registered',
+                    action: 'republish-with-delay',
+                    delayMs: 500,
                 });
                 // Worker not registered yet. Re-publish with short visibility delay
                 // so it retries after the worker has time to register.

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

@@ -13,9 +13,18 @@ declare class TelemetryService {
     metadata: ActivityMetadata;
     context: JobState;
     leg: number;
+    /**
+     * Namespaces registered by the durable module. Engine-layer spans
+     * for these namespaces are suppressed in 'info' mode — the
+     * DurableTelemetryService emits the user-facing story instead.
+     */
+    static durableNamespaces: Set<string>;
     constructor(appId: string, config?: ActivityType, metadata?: ActivityMetadata, context?: JobState);
+    private isDurableApp;
     /**
-     * too chatty for production; only output traces, jobs, triggers and workers
+     * Gate engine-layer span creation. For durable namespaces in 'info'
+     * mode, returns false — DurableTelemetryService handles telemetry
+     * at the right abstraction level. In 'debug' mode, both layers emit.
      */
     private shouldCreateSpan;
     private static createNoopSpan;

package/build/services/telemetry/index.js

@@ -17,10 +17,18 @@ class TelemetryService {
         this.metadata = metadata;
         this.context = context;
     }
+    isDurableApp() {
+        return TelemetryService.durableNamespaces.has(this.appId);
+    }
     /**
-     * too chatty for production; only output traces, jobs, triggers and workers
+     * Gate engine-layer span creation. For durable namespaces in 'info'
+     * mode, returns false — DurableTelemetryService handles telemetry
+     * at the right abstraction level. In 'debug' mode, both layers emit.
      */
     shouldCreateSpan() {
+        if (this.isDurableApp() && enums_1.HMSH_TELEMETRY !== 'debug') {
+            return false;
+        }
         return (enums_1.HMSH_TELEMETRY === 'debug' ||
             this.config?.type === 'trigger' ||
             this.config?.type === 'worker');
@@ -73,16 +81,24 @@ class TelemetryService {
     }
     getActivityParentSpanId(leg) {
         if (leg === 1) {
-            return this.context[this.config.parent].output?.metadata?.l2s;
+            return this.context?.[this.config?.parent]?.output?.metadata?.l2s;
         }
         else {
-            return this.context['$self'].output?.metadata?.l1s;
+            return this.context?.['$self']?.output?.metadata?.l1s;
         }
     }
     getTraceId() {
         return this.context.metadata.trc;
     }
     startJobSpan() {
+        if (this.isDurableApp() && enums_1.HMSH_TELEMETRY !== 'debug') {
+            const trc = this.context?.metadata?.trc ?? '';
+            const spn = this.context?.metadata?.spn ?? '';
+            this.jobSpan = TelemetryService.createNoopSpan(trc, spn);
+            this.traceId = trc;
+            this.spanId = spn;
+            return this;
+        }
         const spanName = `JOB/${this.appId}/${this.config.subscribes}/1`;
         const traceId = this.getTraceId();
         const spanId = this.getJobParentSpanId();
@@ -117,6 +133,14 @@ class TelemetryService {
         });
     }
     startActivitySpan(leg = this.leg) {
+        if (this.isDurableApp() && enums_1.HMSH_TELEMETRY !== 'debug') {
+            const trc = this.context?.metadata?.trc ?? '';
+            const spn = this.context?.metadata?.spn ?? '';
+            this.span = TelemetryService.createNoopSpan(trc, spn);
+            this.traceId = trc;
+            this.spanId = spn;
+            return this;
+        }
         const spanName = `${this.config.type.toUpperCase()}/${this.appId}/${this.metadata.aid}/${leg}`;
         const traceId = this.getTraceId();
         const spanId = this.getActivityParentSpanId(leg);
@@ -141,10 +165,13 @@ class TelemetryService {
         else {
             type = 'FANOUT'; //exiting engine router (to worker router)
         }
-        // `EXECUTE` refers to the 'worker router' NOT the 'worker activity' run by the 'engine router'
-        // (Regardless, it's worker-related, so it matters and will be traced)
-        // `SYSTEM` refers to catastrophic errors, which are always traced
-        if (this.shouldCreateSpan() || type === 'EXECUTE' || type === 'SYSTEM') {
+        // For durable namespaces in 'info' mode, only SYSTEM spans pass —
+        // DurableTelemetryService emits the user-facing workflow story.
+        // In 'debug' mode or for non-durable apps, original gating applies:
+        // `EXECUTE` = worker router, `SYSTEM` = catastrophic errors (always traced).
+        if (this.isDurableApp() && enums_1.HMSH_TELEMETRY !== 'debug'
+            ? type === 'SYSTEM'
+            : this.shouldCreateSpan() || type === 'EXECUTE' || type === 'SYSTEM') {
             const topic = data.metadata.topic ? `/${data.metadata.topic}` : '';
             const spanName = `${type}/${this.appId}/${data.metadata.aid}${topic}`;
             const attributes = this.getStreamSpanAttrs(data);
@@ -310,3 +337,9 @@ class TelemetryService {
     }
 }
 exports.TelemetryService = TelemetryService;
+/**
+ * Namespaces registered by the durable module. Engine-layer spans
+ * for these namespaces are suppressed in 'info' mode — the
+ * DurableTelemetryService emits the user-facing story instead.
+ */
+TelemetryService.durableNamespaces = new Set();

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

@@ -0,0 +1,51 @@
+/**
+ * High-level worker credential lifecycle management.
+ *
+ * Creates an admin client from a connection config, delegates to the
+ * low-level Postgres credential functions, and cleans up the client.
+ * This is the canonical API — `HotMesh` and `Durable` re-export these
+ * as static convenience methods.
+ */
+import type { WorkerCredential, WorkerCredentialInfo } from '../stream/providers/postgres/credentials';
+import { ProviderConfig, ProvidersConfig } from '../../types/provider';
+/**
+ * Provision a scoped Postgres role for a worker router.
+ *
+ * The role can only dequeue/ack/respond on the specified stream
+ * names via SECURITY DEFINER stored procedures — it has **zero
+ * direct table access**.
+ */
+export declare function provisionWorkerRole(config: {
+    connection: ProviderConfig | ProvidersConfig;
+    namespace?: string;
+    streamNames: string[];
+    password?: string;
+}): Promise<WorkerCredential>;
+/**
+ * Rotate the password for an existing worker role.
+ */
+export declare function rotateWorkerPassword(config: {
+    connection: ProviderConfig | ProvidersConfig;
+    namespace?: string;
+    roleName: string;
+    newPassword?: string;
+}): Promise<{
+    password: string;
+}>;
+/**
+ * Revoke a worker role by disabling login. The role is not dropped,
+ * preserving the audit trail in the `worker_credentials` table.
+ */
+export declare function revokeWorkerRole(config: {
+    connection: ProviderConfig | ProvidersConfig;
+    namespace?: string;
+    roleName: string;
+}): Promise<void>;
+/**
+ * List all provisioned worker roles for a namespace.
+ */
+export declare function listWorkerRoles(config: {
+    connection: ProviderConfig | ProvidersConfig;
+    namespace?: string;
+}): Promise<WorkerCredentialInfo[]>;
+export type { WorkerCredential, WorkerCredentialInfo };

package/build/services/worker/credentials.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * High-level worker credential lifecycle management.
+ *
+ * Creates an admin client from a connection config, delegates to the
+ * low-level Postgres credential functions, and cleans up the client.
+ * This is the canonical API — `HotMesh` and `Durable` re-export these
+ * as static convenience methods.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listWorkerRoles = exports.revokeWorkerRole = exports.rotateWorkerPassword = exports.provisionWorkerRole = void 0;
+const credentials_1 = require("../stream/providers/postgres/credentials");
+/**
+ * Create a raw Postgres client from a connection config for admin
+ * operations (credential provisioning, rotation, revocation).
+ */
+async function createAdminClient(connection) {
+    const config = 'options' in connection
+        ? connection
+        : connection.store ?? connection;
+    const ClientClass = config.class;
+    const options = config.options;
+    const client = new ClientClass(options);
+    await client.connect();
+    return client;
+}
+/**
+ * Provision a scoped Postgres role for a worker router.
+ *
+ * The role can only dequeue/ack/respond on the specified stream
+ * names via SECURITY DEFINER stored procedures — it has **zero
+ * direct table access**.
+ */
+async function provisionWorkerRole(config) {
+    const namespace = config.namespace ?? 'durable';
+    const pgClient = await createAdminClient(config.connection);
+    try {
+        return await (0, credentials_1.provisionWorkerRole)(pgClient, namespace, config.streamNames, config.password);
+    }
+    finally {
+        await pgClient.end?.();
+    }
+}
+exports.provisionWorkerRole = provisionWorkerRole;
+/**
+ * Rotate the password for an existing worker role.
+ */
+async function rotateWorkerPassword(config) {
+    const namespace = config.namespace ?? 'durable';
+    const pgClient = await createAdminClient(config.connection);
+    try {
+        return await (0, credentials_1.rotateWorkerPassword)(pgClient, namespace, config.roleName, config.newPassword);
+    }
+    finally {
+        await pgClient.end?.();
+    }
+}
+exports.rotateWorkerPassword = rotateWorkerPassword;
+/**
+ * Revoke a worker role by disabling login. The role is not dropped,
+ * preserving the audit trail in the `worker_credentials` table.
+ */
+async function revokeWorkerRole(config) {
+    const namespace = config.namespace ?? 'durable';
+    const pgClient = await createAdminClient(config.connection);
+    try {
+        await (0, credentials_1.revokeWorkerRole)(pgClient, namespace, config.roleName);
+    }
+    finally {
+        await pgClient.end?.();
+    }
+}
+exports.revokeWorkerRole = revokeWorkerRole;
+/**
+ * List all provisioned worker roles for a namespace.
+ */
+async function listWorkerRoles(config) {
+    const namespace = config.namespace ?? 'durable';
+    const pgClient = await createAdminClient(config.connection);
+    try {
+        return await (0, credentials_1.listWorkerRoles)(pgClient, namespace);
+    }
+    finally {
+        await pgClient.end?.();
+    }
+}
+exports.listWorkerRoles = listWorkerRoles;

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

@@ -23,7 +23,7 @@ declare class WorkerService {
     reporting: boolean;
     inited: string;
     rollCallInterval: NodeJS.Timeout;
-    retryPolicy: import('../../types/stream').RetryPolicy | undefined;
+    retry: import('../../types/stream').RetryPolicy | undefined;
     /**
      * @private
      */
@@ -47,7 +47,7 @@ declare class WorkerService {
     /**
      * @private
      */
-    initStreamChannel(service: WorkerService, stream: ProviderClient, store: ProviderClient): Promise<void>;
+    initStreamChannel(service: WorkerService, stream: ProviderClient, store: ProviderClient, securedWorker?: boolean): Promise<void>;
     /**
      * @private
      */

package/build/services/worker/index.js

@@ -39,19 +39,19 @@ class WorkerService {
                 service.topic = worker.topic;
                 service.config = config;
                 service.logger = logger;
-                service.retryPolicy = worker.retryPolicy;
+                service.retry = worker.retry;
                 await service.initStoreChannel(service, worker.store);
                 await service.initSubChannel(service, worker.sub, worker.pub ?? worker.store);
                 await service.subscribe.subscribe(key_1.KeyType.QUORUM, service.subscriptionHandler(), appId);
                 await service.subscribe.subscribe(key_1.KeyType.QUORUM, service.subscriptionHandler(), appId, service.topic);
                 await service.subscribe.subscribe(key_1.KeyType.QUORUM, service.subscriptionHandler(), appId, service.guid);
-                await service.initStreamChannel(service, worker.stream, worker.store);
+                await service.initStreamChannel(service, worker.stream, worker.store, !!worker.workerCredentials);
                 if (worker.workflowName) {
                     // Use singleton consumer via registry (batched fetch + dispatch by workflow_name)
                     await registry_1.StreamConsumerRegistry.registerWorker(namespace, appId, guid, worker.topic, worker.workflowName, worker.callback, service.stream, service.store, logger, {
                         reclaimDelay: worker.reclaimDelay,
                         reclaimCount: worker.reclaimCount,
-                        retryPolicy: worker.retryPolicy,
+                        retry: worker.retry,
                     });
                     // Still need a router for publishing responses back to engine
                     service.router = await service.initRouter(worker, logger);
@@ -97,8 +97,8 @@ class WorkerService {
     /**
      * @private
      */
-    async initStreamChannel(service, stream, store) {
-        service.stream = await factory_2.StreamServiceFactory.init(stream, store, service.namespace, service.appId, service.logger);
+    async initStreamChannel(service, stream, store, securedWorker = false) {
+        service.stream = await factory_2.StreamServiceFactory.init(stream, store, service.namespace, service.appId, service.logger, { securedWorker });
     }
     /**
      * @private
@@ -114,7 +114,7 @@ class WorkerService {
             reclaimDelay: worker.reclaimDelay,
             reclaimCount: worker.reclaimCount,
             throttle,
-            retryPolicy: worker.retryPolicy,
+            retry: worker.retry,
         }, this.stream, logger);
     }
     /**
@@ -191,6 +191,7 @@ class WorkerService {
                 worker_topic: this.topic,
                 stream: this.store.mintKey(key_1.KeyType.STREAMS, params),
                 counts: this.router?.counts,
+                error_count: this.router?.errorCount,
                 timestamp: (0, utils_1.formatISODate)(new Date()),
                 inited: this.inited,
                 throttle: this.router?.throttle,

package/build/types/codec.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Synchronous codec for encoding/decoding serialized payload data.
+ *
+ * Register a `PayloadCodec` to transparently transform all serialized
+ * object values (`/s{json}`) before they are stored and after they are
+ * read. Common use cases: encryption at rest, compression, or custom
+ * binary encoding.
+ *
+ * ## How It Works
+ *
+ * The serializer stores JavaScript objects as `/s{json}`. When a codec
+ * is registered, objects are instead stored as `/b{encoded}`:
+ *
+ * ```
+ * Write: value → JSON.stringify → codec.encode(json) → "/b{encoded}"
+ * Read:  "/b{encoded}" → codec.decode(encoded) → JSON.parse → value
+ *        "/s{json}" → JSON.parse → value  (backward compatible)
+ * ```
+ *
+ * ## Constraints
+ *
+ * - **Synchronous** — `encode` and `decode` must be synchronous.
+ *   Use Node.js `crypto` (e.g., `createCipheriv`) or `zlib`
+ *   (e.g., `deflateSync`) for sync operations.
+ * - **String-safe** — `encode` output must be a valid UTF-8 string
+ *   (Postgres TEXT column). Use base64 encoding for binary output.
+ * - **Deterministic decode** — `decode(encode(x))` must equal `x`.
+ *
+ * ## Scope
+ *
+ * The codec applies to all data flowing through the serializer's
+ * `package`/`unpackage` path — job state, activity inputs/outputs,
+ * timeline markers, and workflow metadata. It does **not** apply to
+ * `search()`, `entity()`, or `enrich()` data, which bypass the
+ * serializer.
+ *
+ * ## Example: AES-256-GCM Encryption
+ *
+ * ```typescript
+ * import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';
+ * import { PayloadCodec } from '@hotmeshio/hotmesh';
+ *
+ * const key = randomBytes(32);
+ *
+ * const codec: PayloadCodec = {
+ *   encode(json: string): string {
+ *     const iv = randomBytes(12);
+ *     const cipher = createCipheriv('aes-256-gcm', key, iv);
+ *     const enc = Buffer.concat([cipher.update(json, 'utf8'), cipher.final()]);
+ *     const tag = cipher.getAuthTag();
+ *     return Buffer.concat([iv, tag, enc]).toString('base64');
+ *   },
+ *   decode(encoded: string): string {
+ *     const buf = Buffer.from(encoded, 'base64');
+ *     const iv = buf.subarray(0, 12);
+ *     const tag = buf.subarray(12, 28);
+ *     const data = buf.subarray(28);
+ *     const decipher = createDecipheriv('aes-256-gcm', key, iv);
+ *     decipher.setAuthTag(tag);
+ *     return Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8');
+ *   },
+ * };
+ *
+ * // Register globally — applies to all HotMesh and Durable instances
+ * HotMesh.registerCodec(codec);
+ * ```
+ */
+export interface PayloadCodec {
+    /**
+     * Encode a JSON string before storage. The output replaces
+     * the `/s{json}` prefix with `/b{encoded}`.
+     *
+     * @param json - The raw JSON string (result of JSON.stringify)
+     * @returns The encoded string (must be valid UTF-8)
+     */
+    encode(json: string): string;
+    /**
+     * Decode a previously encoded string back to the original JSON.
+     *
+     * @param encoded - The encoded string (from a previous `encode` call)
+     * @returns The original JSON string
+     */
+    decode(encoded: string): string;
+}

package/build/types/codec.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });