@dbos-inc/dbos-sdk 4.24.13-preview → 4.24.14-preview

package/dist/src/system_database.js

@@ -9,7 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SystemDatabase = exports.ensureSystemDatabase = exports.grantDbosSchemaPermissions = exports.DBOS_STREAM_CLOSED_SENTINEL = exports.DEFAULT_POOL_SIZE = exports.DBOS_FUNCNAME_CLOSESTREAM = exports.DBOS_FUNCNAME_WRITESTREAM = exports.DBOS_FUNCNAME_GETSTATUS = exports.DBOS_FUNCNAME_SLEEP = exports.DBOS_FUNCNAME_GETEVENT = exports.DBOS_FUNCNAME_SETEVENT = exports.DBOS_FUNCNAME_RECV = exports.DBOS_FUNCNAME_SEND = void 0;
+exports.SystemDatabase = exports.ensureSystemDatabase = exports.grantDbosSchemaPermissions = exports.DEFAULT_NOTIFICATION_COALESCE_MS = exports.DBOS_STREAMS_CHANNEL = exports.DBOS_WORKFLOW_EVENTS_CHANNEL = exports.DBOS_NOTIFICATIONS_CHANNEL = exports.DBOS_STREAM_CLOSED_SENTINEL = exports.DEFAULT_POOL_SIZE = exports.DBOS_FUNCNAME_CLOSESTREAM = exports.DBOS_FUNCNAME_WRITESTREAM = exports.DBOS_FUNCNAME_GETSTATUS = exports.DBOS_FUNCNAME_SLEEP = exports.DBOS_FUNCNAME_GETEVENT = exports.DBOS_FUNCNAME_SETEVENT = exports.DBOS_FUNCNAME_RECV = exports.DBOS_FUNCNAME_SEND = void 0;
 const dbos_executor_1 = require("./dbos-executor");
 const pg_1 = require("pg");
 const error_1 = require("./error");
@@ -32,6 +32,12 @@ exports.DBOS_FUNCNAME_WRITESTREAM = 'DBOS.writeStream';
 exports.DBOS_FUNCNAME_CLOSESTREAM = 'DBOS.closeStream';
 exports.DEFAULT_POOL_SIZE = 10;
 exports.DBOS_STREAM_CLOSED_SENTINEL = '__DBOS_STREAM_CLOSED__';
+// LISTEN/NOTIFY channels. Streams and workflow_events are pushed by the notifier loop off the write path; notifications fires from an in-transaction DB trigger so recv is never woken before its row commits.
+exports.DBOS_NOTIFICATIONS_CHANNEL = 'dbos_notifications_channel';
+exports.DBOS_WORKFLOW_EVENTS_CHANNEL = 'dbos_workflow_events_channel';
+exports.DBOS_STREAMS_CHANNEL = 'dbos_streams_channel';
+// Interval for coalescing LISTEN/NOTIFY notifications off the write path; caps the rate of notifying commits regardless of write throughput.
+exports.DEFAULT_NOTIFICATION_COALESCE_MS = 10;
 const QUEUE_COLUMN_BY_FIELD = {
     concurrency: 'concurrency',
     workerConcurrency: 'worker_concurrency',
@@ -390,6 +396,15 @@ class SystemDatabase {
     workflowEventsMap = new NotificationMap();
     streamsMap = new NotificationMap();
     customPool = false;
+    // Interval for coalescing LISTEN/NOTIFY notifications pushed off the write path (Postgres + L/N only).
+    notificationCoalesceMs = exports.DEFAULT_NOTIFICATION_COALESCE_MS;
+    // Coalesced NOTIFY payloads keyed by channel, flushed by the notifier loop; soft-private so tests can drive a flush.
+    pendingNotifications = new Map();
+    #notifierActive = false;
+    // Wakes the notifier out of its coalescing sleep so shutdown flushes promptly.
+    #notifierWake = null;
+    // The notifier loop's completion, awaited on destroy so a final flush precedes closing the pool.
+    #notifierLoop = undefined;
     /**
      * Caps how many DB-backed polling reads (from wait operations) may run
      * concurrently against the pool, so a polling storm cannot check out every
@@ -399,12 +414,13 @@ class SystemDatabase {
     runningWorkflowMap = new Map(); // Map from workflowID to workflow promise, queue name and partition key
     // Per-partition-key created_at cursors: keep per-key queue order monotonic across batches
     #batchCreatedAtCursors = new Map();
-    constructor(systemDatabaseUrl, logger, serializer, sysDbPoolSize = exports.DEFAULT_POOL_SIZE, systemDatabasePool, schemaName = 'dbos', useListenNotify = true, pollingConcurrency) {
+    constructor(systemDatabaseUrl, logger, serializer, sysDbPoolSize = exports.DEFAULT_POOL_SIZE, systemDatabasePool, schemaName = 'dbos', useListenNotify = true, pollingConcurrency, notificationCoalesceMs = exports.DEFAULT_NOTIFICATION_COALESCE_MS) {
         this.systemDatabaseUrl = systemDatabaseUrl;
         this.logger = logger;
         this.serializer = serializer;
         this.schemaName = schemaName;
         this.shouldUseDBNotifications = useListenNotify;
+        this.notificationCoalesceMs = notificationCoalesceMs;
         if (systemDatabasePool) {
             this.pool = systemDatabasePool;
             this.customPool = true;
@@ -439,12 +455,22 @@ class SystemDatabase {
         await ensureSystemDatabase(this.systemDatabaseUrl, this.logger, this.customPool ? this.pool : undefined, this.schemaName, this.shouldUseDBNotifications);
         if (this.shouldUseDBNotifications) {
             await this.#listenForNotifications();
+            // Push coalesced stream and event notifications off the write path.
+            this.#notifierActive = true;
+            this.#notifierLoop = this.#runNotifier();
         }
     }
     async destroy() {
         if (this.reconnectTimeout) {
             clearTimeout(this.reconnectTimeout);
         }
+        // Stop the notifier and await its final flush before the pool closes.
+        this.#notifierActive = false;
+        this.#notifierWake?.();
+        if (this.#notifierLoop) {
+            await this.#notifierLoop;
+            this.#notifierLoop = undefined;
+        }
         if (this.notificationsClient) {
             try {
                 this.notificationsClient.release(true);
@@ -1698,6 +1724,8 @@ class SystemDatabase {
         const client = await this.pool.connect();
         try {
             await client.query('BEGIN ISOLATION LEVEL READ COMMITTED');
+            // Only a real write (not a replay) should wake readers.
+            let didWrite = false;
             await this.#runAndRecordResult(client, exports.DBOS_FUNCNAME_SETEVENT, workflowID, functionID, async () => {
                 await client.query(`INSERT INTO "${this.schemaName}".workflow_events (workflow_uuid, key, value, serialization)
              VALUES ($1, $2, $3, $4)
@@ -1709,9 +1737,14 @@ class SystemDatabase {
              VALUES ($1, $2, $3, $4, $5)
              ON CONFLICT (workflow_uuid, function_id, key)
              DO UPDATE SET value = $4, serialization = $5;`, [workflowID, functionID, key, message, serialization]);
+                didWrite = true;
                 return undefined;
             });
             await client.query('COMMIT');
+            // Notify only after commit, so a woken getEvent sees the value.
+            if (didWrite) {
+                this.#signalNotification(exports.DBOS_WORKFLOW_EVENTS_CHANNEL, `${workflowID}::${key}`);
+            }
         }
         catch (e) {
             this.logger.error(e);
@@ -1849,6 +1882,8 @@ class SystemDatabase {
             await client.query(`INSERT INTO "${this.schemaName}".streams (workflow_uuid, key, value, "offset", function_id, serialization)
          VALUES ($1, $2, $3, $4, $5, $6)`, [workflowID, key, serializedValue, nextOffset, functionID, serialization]);
             await client.query('COMMIT');
+            // Notify only after commit, so a woken reader sees the value.
+            this.#signalNotification(exports.DBOS_STREAMS_CHANNEL, `${workflowID}::${key}`);
         }
         catch (e) {
             this.logger.error(e);
@@ -1863,9 +1898,11 @@ class SystemDatabase {
         const client = await this.pool.connect();
         try {
             await client.query('BEGIN ISOLATION LEVEL READ COMMITTED');
+            // Only a real insert (not a replay) should wake readers.
+            let didWrite = false;
             await this.#runAndRecordResult(client, functionName, workflowID, functionID, async () => {
                 // Find the maximum offset for this workflow_uuid and key combination
-                const maxOffsetResult = await client.query(`SELECT MAX("offset") FROM "${this.schemaName}".streams 
+                const maxOffsetResult = await client.query(`SELECT MAX("offset") FROM "${this.schemaName}".streams
            WHERE workflow_uuid = $1 AND key = $2`, [workflowID, key]);
                 // Next offset is max + 1, or 0 if no records exist
                 const maxOffset = maxOffsetResult.rows[0].max;
@@ -1873,9 +1910,14 @@ class SystemDatabase {
                 // Insert the new stream entry
                 await client.query(`INSERT INTO "${this.schemaName}".streams (workflow_uuid, key, value, "offset", function_id, serialization)
            VALUES ($1, $2, $3, $4, $5, $6)`, [workflowID, key, serializedValue, nextOffset, functionID, serialization]);
+                didWrite = true;
                 return undefined;
             });
             await client.query('COMMIT');
+            // Notify only after commit, so a woken reader sees the value.
+            if (didWrite) {
+                this.#signalNotification(exports.DBOS_STREAMS_CHANNEL, `${workflowID}::${key}`);
+            }
         }
         catch (e) {
             this.logger.error(e);
@@ -1889,20 +1931,102 @@ class SystemDatabase {
     async closeStream(workflowID, functionID, key) {
         await this.writeStreamFromWorkflow(workflowID, functionID, key, exports.DBOS_STREAM_CLOSED_SENTINEL, 'portable_json', exports.DBOS_FUNCNAME_CLOSESTREAM);
     }
-    async readStream(workflowID, key, offset) {
-        const client = await this.pool.connect();
+    // Read the value at `offset` and the workflow's status in one query: status null = no such workflow, value undefined = nothing at that offset.
+    async readStreamValue(workflowID, key, offset) {
+        // LEFT JOIN so a workflow with nothing at offset still reports its status (single PK lookup); under the poll limiter, inside @dbRetry so the permit frees across backoff.
+        const result = await this.#pollWithLimiter(() => this.pool.query(
+        // "offset" is a reserved word, so alias it (stream_offset) to read it back plainly.
+        `SELECT ws.status AS status, s.value AS value, s.serialization AS serialization, s."offset" AS stream_offset
+         FROM "${this.schemaName}".workflow_status ws
+         LEFT OUTER JOIN "${this.schemaName}".streams s
+           ON s.workflow_uuid = ws.workflow_uuid AND s.key = $2 AND s."offset" = $3
+         WHERE ws.workflow_uuid = $1`, [workflowID, key, offset]));
+        if (result.rows.length === 0) {
+            return { status: null, value: undefined };
+        }
+        const row = result.rows[0];
+        // streams.offset is non-nullable, so a NULL here means the join matched nothing at offset.
+        if (row.stream_offset === null) {
+            return { status: row.status, value: undefined };
+        }
+        return { status: row.status, value: { serializedValue: row.value, serialization: row.serialization } };
+    }
+    #signalNotification(channel, payload) {
+        // Coalesce a wakeup on `channel` for `payload`; no-op without LISTEN/NOTIFY (clients, CockroachDB), which poll.
+        if (!this.shouldUseDBNotifications) {
+            return;
+        }
+        let batch = this.pendingNotifications.get(channel);
+        if (batch === undefined) {
+            batch = new Set();
+            this.pendingNotifications.set(channel, batch);
+        }
+        batch.add(payload);
+    }
+    // Periodically flush coalesced notifications across all channels, keeping the notifying commit off the write path.
+    async #runNotifier() {
+        while (this.#notifierActive) {
+            const { promise, cancel } = (0, utils_1.cancellableSleep)(this.notificationCoalesceMs);
+            this.#notifierWake = cancel;
+            await promise;
+            this.#notifierWake = null;
+            if (!this.#notifierActive) {
+                break;
+            }
+            try {
+                await this.flushNotifications();
+            }
+            catch (e) {
+                // Last resort: the flush drops its own failed batch, so this catches only unexpected errors that must not kill the push path.
+                if (this.#notifierActive) {
+                    this.logger.warn(`Notifier error: ${String(e)}`);
+                    const { promise: backoff } = (0, utils_1.cancellableSleep)(1000);
+                    await backoff;
+                }
+            }
+        }
+        // Final flush so values written just before shutdown still wake readers promptly.
         try {
-            const result = await client.query(`SELECT value, serialization FROM "${this.schemaName}".streams 
-         WHERE workflow_uuid = $1 AND key = $2 AND "offset" = $3`, [workflowID, key, offset]);
-            if (result.rows.length === 0) {
-                throw new Error(`No value found for workflow_uuid=${workflowID}, key=${key}, offset=${offset}`);
+            await this.flushNotifications();
+        }
+        catch (e) {
+            this.logger.warn(`Notifier final flush error: ${String(e)}`);
+        }
+    }
+    // Emit one notifying transaction per channel for all pending payloads; drop a channel's batch on failure. Soft-private so tests can drive it.
+    async flushNotifications() {
+        let hasPending = false;
+        for (const batch of this.pendingNotifications.values()) {
+            if (batch.size > 0) {
+                hasPending = true;
+                break;
             }
-            // Deserialize the value before returning
-            const row = result.rows[0];
-            return { serializedValue: row.value, serialization: row.serialization };
         }
-        finally {
-            client.release();
+        if (!hasPending) {
+            return;
+        }
+        // Grab and clear atomically (no await between), so writes during the flush start the next batch.
+        const batches = this.pendingNotifications;
+        this.pendingNotifications = new Map();
+        // One transaction per channel so an unsendable payload on one channel drops only its own batch.
+        for (const [channel, batch] of batches) {
+            if (batch.size === 0) {
+                continue;
+            }
+            try {
+                // One statement: one round trip, one async-notify queue-lock acquisition; unnest emits one notification per payload.
+                const client = await this.pool.connect();
+                try {
+                    await client.query(`SELECT pg_notify($1, p) FROM unnest($2::text[]) AS p`, [channel, Array.from(batch)]);
+                }
+                finally {
+                    client.release();
+                }
+            }
+            catch (e) {
+                // Drop the batch (don't requeue) on failure, e.g. a payload over pg_notify's 8000-byte limit; polling still delivers those values.
+                this.logger.warn(`Notifier flush error on ${channel}: ${String(e)}`);
+            }
         }
     }
     // ==================== Observability: Workflow Communications ====================
@@ -3188,9 +3312,9 @@ class SystemDatabase {
             let client = null;
             try {
                 client = await this.pool.connect();
-                await client.query('LISTEN dbos_notifications_channel;');
-                await client.query('LISTEN dbos_workflow_events_channel;');
-                await client.query('LISTEN dbos_streams_channel;');
+                await client.query(`LISTEN ${exports.DBOS_NOTIFICATIONS_CHANNEL};`);
+                await client.query(`LISTEN ${exports.DBOS_WORKFLOW_EVENTS_CHANNEL};`);
+                await client.query(`LISTEN ${exports.DBOS_STREAMS_CHANNEL};`);
                 // Self-test: verify LISTEN actually works by sending a NOTIFY and checking it arrives.
                 // If a transaction-mode pooler (e.g. PgBouncer pool_mode=transaction) is in the path,
                 // LISTEN succeeds but the subscription is silently lost when the backend is released.
@@ -3215,13 +3339,13 @@ class SystemDatabase {
                 const handler = (msg) => {
                     if (!this.shouldUseDBNotifications)
                         return;
-                    if (msg.channel === 'dbos_notifications_channel' && msg.payload) {
+                    if (msg.channel === exports.DBOS_NOTIFICATIONS_CHANNEL && msg.payload) {
                         this.notificationsMap.callCallbacks(msg.payload);
                     }
-                    else if (msg.channel === 'dbos_workflow_events_channel' && msg.payload) {
+                    else if (msg.channel === exports.DBOS_WORKFLOW_EVENTS_CHANNEL && msg.payload) {
                         this.workflowEventsMap.callCallbacks(msg.payload);
                     }
-                    else if (msg.channel === 'dbos_streams_channel' && msg.payload) {
+                    else if (msg.channel === exports.DBOS_STREAMS_CHANNEL && msg.payload) {
                         this.streamsMap.callCallbacks(msg.payload);
                     }
                 };
@@ -3386,7 +3510,7 @@ __decorate([
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [String, String, Number]),
     __metadata("design:returntype", Promise)
-], SystemDatabase.prototype, "readStream", null);
+], SystemDatabase.prototype, "readStreamValue", null);
 __decorate([
     dbRetry(),
     __metadata("design:type", Function),