@dbos-inc/dbos-sdk 5.5.2-preview → 5.5.4-preview

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/dist/schemas/system_db_schema.d.ts +7 -0
  2. package/dist/schemas/system_db_schema.d.ts.map +1 -1
  3. package/dist/schemas/system_db_schema.js.map +1 -1
  4. package/dist/src/client.d.ts +26 -2
  5. package/dist/src/client.d.ts.map +1 -1
  6. package/dist/src/client.js +65 -1
  7. package/dist/src/client.js.map +1 -1
  8. package/dist/src/config.d.ts.map +1 -1
  9. package/dist/src/config.js +3 -0
  10. package/dist/src/config.js.map +1 -1
  11. package/dist/src/dbos-executor.d.ts +17 -0
  12. package/dist/src/dbos-executor.d.ts.map +1 -1
  13. package/dist/src/dbos-executor.js +19 -1
  14. package/dist/src/dbos-executor.js.map +1 -1
  15. package/dist/src/dbos.d.ts +61 -5
  16. package/dist/src/dbos.d.ts.map +1 -1
  17. package/dist/src/dbos.js +99 -22
  18. package/dist/src/dbos.js.map +1 -1
  19. package/dist/src/enterprise.d.ts +56 -1
  20. package/dist/src/enterprise.d.ts.map +1 -1
  21. package/dist/src/enterprise.js +26 -4
  22. package/dist/src/enterprise.js.map +1 -1
  23. package/dist/src/error.d.ts +42 -0
  24. package/dist/src/error.d.ts.map +1 -1
  25. package/dist/src/error.js +85 -1
  26. package/dist/src/error.js.map +1 -1
  27. package/dist/src/external_storage.d.ts +27 -0
  28. package/dist/src/external_storage.d.ts.map +1 -0
  29. package/dist/src/external_storage.js +28 -0
  30. package/dist/src/external_storage.js.map +1 -0
  31. package/dist/src/index.d.ts +4 -3
  32. package/dist/src/index.d.ts.map +1 -1
  33. package/dist/src/index.js +2 -1
  34. package/dist/src/index.js.map +1 -1
  35. package/dist/src/sysdb_migrations/internal/migrations.js +82 -0
  36. package/dist/src/sysdb_migrations/internal/migrations.js.map +1 -1
  37. package/dist/src/system_database.d.ts +20 -3
  38. package/dist/src/system_database.d.ts.map +1 -1
  39. package/dist/src/system_database.js +54 -10
  40. package/dist/src/system_database.js.map +1 -1
  41. package/dist/src/workflow.d.ts +3 -1
  42. package/dist/src/workflow.d.ts.map +1 -1
  43. package/dist/src/workflow.js +16 -3
  44. package/dist/src/workflow.js.map +1 -1
  45. package/dist/src/workflow_management.d.ts +4 -1
  46. package/dist/src/workflow_management.d.ts.map +1 -1
  47. package/dist/src/workflow_management.js +12 -6
  48. package/dist/src/workflow_management.js.map +1 -1
  49. package/dist/tsconfig.tsbuildinfo +1 -1
  50. package/package.json +1 -1
@@ -620,6 +620,15 @@ function dbRetry(options = {}) {
620
620
  }
621
621
  /** Build the system database these options describe. */
622
622
  function createSystemDatabase(options) {
623
+ const sysdb = createBaseSystemDatabase(options);
624
+ if (options.suspendMode) {
625
+ const { Suspend } = enterprise.load(enterprise.SUSPEND.description);
626
+ sysdb.suspend = new Suspend(sysdb);
627
+ }
628
+ return sysdb;
629
+ }
630
+ exports.createSystemDatabase = createSystemDatabase;
631
+ function createBaseSystemDatabase(options) {
623
632
  if (options.sharding) {
624
633
  const { ShardedSystemDatabase } = enterprise.load(enterprise.SHARDING.description);
625
634
  return new ShardedSystemDatabase({
@@ -637,7 +646,6 @@ function createSystemDatabase(options) {
637
646
  }
638
647
  return new SystemDatabase(options.systemDatabaseUrl, options.logger, options.serializer, options.sysDbPoolSize, options.systemDatabasePool, options.schemaName, options.useListenNotify, options.pollingConcurrency, options.notificationCoalesceMs, options.appName, options.observabilityQueryTimeoutMs, options.idleTransactionTimeoutMs);
639
648
  }
640
- exports.createSystemDatabase = createSystemDatabase;
641
649
  /**
642
650
  * General notes:
643
651
  * The responsibilities of the `SystemDatabase` are to store data for workflows, and
@@ -683,6 +691,7 @@ class SystemDatabase {
683
691
  shouldUseDBNotifications = true;
684
692
  notificationsMap = new NotificationMap();
685
693
  workflowEventsMap = new NotificationMap();
694
+ suspend = undefined;
686
695
  streamsMap = new NotificationMap();
687
696
  customPool = false;
688
697
  // Interval for coalescing LISTEN/NOTIFY notifications pushed off the write path (Postgres + L/N only).
@@ -2060,7 +2069,7 @@ class SystemDatabase {
2060
2069
  throw new error_1.DBOSNonExistentWorkflowError(`Workflow ${workflowID} does not exist`);
2061
2070
  }
2062
2071
  const status = statusRows[0].status;
2063
- if (status === workflow_1.StatusString.PENDING || status === workflow_1.StatusString.ENQUEUED || status === workflow_1.StatusString.DELAYED) {
2072
+ if ((0, workflow_1.isWorkflowActive)(status)) {
2064
2073
  throw new error_1.DBOSError(`Cannot rewind ${workflowID} (${status}): only a workflow in a terminal state can be rewound, so cancel it first`);
2065
2074
  }
2066
2075
  // Roll workflow_events back to the last value published before the cut, using
@@ -2625,7 +2634,7 @@ class SystemDatabase {
2625
2634
  const ids = this.wfIn(undefined, workflowIds, params);
2626
2635
  const { rows } = await this.#pollWithLimiter(() => this.pool.query(`SELECT workflow_uuid FROM "${this.schemaName}".workflow_status
2627
2636
  WHERE ${ids}
2628
- AND status NOT IN ('${workflow_1.StatusString.PENDING}', '${workflow_1.StatusString.ENQUEUED}', '${workflow_1.StatusString.DELAYED}')
2637
+ AND status NOT IN ('${workflow_1.StatusString.PENDING}', '${workflow_1.StatusString.ENQUEUED}', '${workflow_1.StatusString.DELAYED}', '${workflow_1.StatusString.SUSPENDED}')
2629
2638
  LIMIT 1`, params));
2630
2639
  return rows[0]?.workflow_uuid;
2631
2640
  }
@@ -2651,7 +2660,7 @@ class SystemDatabase {
2651
2660
  const ids = this.wfIn(undefined, workflowIds, params);
2652
2661
  const { rows } = await this.#pollWithLimiter(() => this.pool.query(`SELECT workflow_uuid FROM "${this.schemaName}".workflow_status
2653
2662
  WHERE ${ids}
2654
- AND status NOT IN ('${workflow_1.StatusString.PENDING}', '${workflow_1.StatusString.ENQUEUED}', '${workflow_1.StatusString.DELAYED}')`, params));
2663
+ AND status NOT IN ('${workflow_1.StatusString.PENDING}', '${workflow_1.StatusString.ENQUEUED}', '${workflow_1.StatusString.DELAYED}', '${workflow_1.StatusString.SUSPENDED}')`, params));
2655
2664
  return rows.map((row) => row.workflow_uuid);
2656
2665
  }
2657
2666
  // ==================== Sleep ====================
@@ -2725,6 +2734,16 @@ class SystemDatabase {
2725
2734
  return await this.sendDirectInternal(this.pool, destinationID, message, topic, serialization, idempotencyKey, shardKey);
2726
2735
  }
2727
2736
  async sendDirectInternal(db, destinationID, message, topic, serialization, idempotencyKey, shardKey) {
2737
+ if (db === this.pool) {
2738
+ // All sends need a transaction now because they wake up suspended workflows unconditionally.
2739
+ const client = await this.connect();
2740
+ try {
2741
+ return await this.inTransaction(client, () => this.sendDirectInternal(client, destinationID, message, topic, serialization, idempotencyKey, shardKey));
2742
+ }
2743
+ finally {
2744
+ client.release();
2745
+ }
2746
+ }
2728
2747
  topic = topic ?? this.nullTopic;
2729
2748
  // An idempotency key is scoped per destination: suffix it with the recipient's workflow ID.
2730
2749
  const messageUUID = idempotencyKey ? `${idempotencyKey}::${destinationID}` : (0, crypto_1.randomUUID)();
@@ -2746,6 +2765,21 @@ class SystemDatabase {
2746
2765
  }
2747
2766
  throw err;
2748
2767
  }
2768
+ await this.wakeReceivers(db, [destinationID], [topic]);
2769
+ }
2770
+ /**
2771
+ * Make SUSPENDED receivers waiting on one of `topics` due, for the background pass to re-enqueue.
2772
+ * Runs on every send, whether or not this process uses suspend mode, so any sender wakes a workflow
2773
+ * another process parked. A primary-key probe per destination; it matches nothing in the common case.
2774
+ *
2775
+ * The match is destinations x topics, so a batch sending A on topic X and B on topic Y also wakes A
2776
+ * if it waits on Y. The spurious wake-up is harmless: the replayed recv finds no message and parks again.
2777
+ */
2778
+ async wakeReceivers(db, destinations, topics) {
2779
+ const params = [topics];
2780
+ await db.query(`UPDATE "${this.schemaName}".workflow_status
2781
+ SET delay_until_epoch_ms = 0
2782
+ WHERE ${this.wfIn(undefined, destinations, params)} AND status = '${workflow_1.StatusString.SUSPENDED}' AND suspend_key = ANY($1::text[])`, params);
2749
2783
  }
2750
2784
  async recv(workflowID, functionID, timeoutFunctionID, topic, timeoutSeconds = dbos_executor_1.DBOSExecutor.defaultNotificationTimeoutSec, pollingIntervalMs) {
2751
2785
  topic = topic ?? this.nullTopic;
@@ -2799,6 +2833,11 @@ class SystemDatabase {
2799
2833
  this.notificationsMap.deregisterCallback(cbr);
2800
2834
  }
2801
2835
  }
2836
+ return await this.recvConsume(workflowID, functionID, topic, startTime);
2837
+ }
2838
+ /** Consume and return the oldest message on `topic`, or null if there is none, recording it as the recv at `functionID`. */
2839
+ async recvConsume(workflowID, functionID, topic, startTime) {
2840
+ topic = topic ?? this.nullTopic;
2802
2841
  await this.checkIfCanceled(workflowID);
2803
2842
  // Transactionally consume and return the message if it's in the DB, otherwise return null.
2804
2843
  let message = null;
@@ -3165,7 +3204,7 @@ class SystemDatabase {
3165
3204
  async cancelTimedOutWorkflows(limit) {
3166
3205
  const params = [workflow_1.StatusString.CANCELLED, Date.now(), limit];
3167
3206
  const scope = this.appNameFilter('application_name', this.appName, params);
3168
- // Literal statuses let the planner match idx_workflow_status_deadline under any plan mode.
3207
+ // Literal statuses let the planner match idx_workflow_status_deadline_v2 under any plan mode.
3169
3208
  // SKIP LOCKED leaves a row a dequeue or a peer's sweep holds for the next sweep.
3170
3209
  const { rows } = await this.pool.query(`UPDATE "${this.schemaName}".workflow_status
3171
3210
  SET status = $1, owner_xid = NULL, queue_name = NULL, deduplication_id = NULL, started_at_epoch_ms = NULL,
@@ -3173,7 +3212,7 @@ class SystemDatabase {
3173
3212
  completed_at = (EXTRACT(EPOCH FROM now()) * 1000)::bigint
3174
3213
  WHERE workflow_uuid IN (
3175
3214
  SELECT workflow_uuid FROM "${this.schemaName}".workflow_status
3176
- WHERE status IN ('${workflow_1.StatusString.ENQUEUED}', '${workflow_1.StatusString.PENDING}', '${workflow_1.StatusString.DELAYED}')
3215
+ WHERE status IN ('${workflow_1.StatusString.ENQUEUED}', '${workflow_1.StatusString.PENDING}', '${workflow_1.StatusString.DELAYED}', '${workflow_1.StatusString.SUSPENDED}')
3177
3216
  AND workflow_deadline_epoch_ms IS NOT NULL
3178
3217
  AND workflow_deadline_epoch_ms <= $2
3179
3218
  AND ${scope}
@@ -3724,9 +3763,9 @@ class SystemDatabase {
3724
3763
  // If queuesOnly, filter for queued workflows
3725
3764
  if (input.queuesOnly) {
3726
3765
  whereClauses.push(`queue_name IS NOT NULL`);
3727
- whereClauses.push(`status IN ($${paramCounter}, $${paramCounter + 1}, $${paramCounter + 2})`);
3728
- params.push(workflow_1.StatusString.ENQUEUED, workflow_1.StatusString.PENDING, workflow_1.StatusString.DELAYED);
3729
- paramCounter += 3;
3766
+ whereClauses.push(`status IN ($${paramCounter}, $${paramCounter + 1}, $${paramCounter + 2}, $${paramCounter + 3})`);
3767
+ params.push(workflow_1.StatusString.ENQUEUED, workflow_1.StatusString.PENDING, workflow_1.StatusString.DELAYED, workflow_1.StatusString.SUSPENDED);
3768
+ paramCounter += 4;
3730
3769
  }
3731
3770
  addFilter('name', input.workflowName);
3732
3771
  addFilter('queue_name', input.queueName);
@@ -4342,7 +4381,12 @@ class SystemDatabase {
4342
4381
  queues = await move('queues');
4343
4382
  schedules = await move('workflow_schedules');
4344
4383
  versions = await move('application_versions');
4345
- inFlight = await move('workflow_status', [workflow_1.StatusString.PENDING, workflow_1.StatusString.ENQUEUED, workflow_1.StatusString.DELAYED]);
4384
+ inFlight = await move('workflow_status', [
4385
+ workflow_1.StatusString.PENDING,
4386
+ workflow_1.StatusString.ENQUEUED,
4387
+ workflow_1.StatusString.DELAYED,
4388
+ workflow_1.StatusString.SUSPENDED,
4389
+ ]);
4346
4390
  await client.query('COMMIT');
4347
4391
  }
4348
4392
  catch (e) {