@dudousxd/nestjs-durable-core 0.85.12 → 0.86.0

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.
package/dist/index.cjs CHANGED
@@ -85,6 +85,7 @@ __export(index_exports, {
85
85
  WORKFLOW_NAME_KEY: () => WORKFLOW_NAME_KEY,
86
86
  WorkflowBlocked: () => WorkflowBlocked,
87
87
  WorkflowEngine: () => WorkflowEngine,
88
+ WorkflowNotRegistered: () => WorkflowNotRegistered,
88
89
  WorkflowSuspended: () => WorkflowSuspended,
89
90
  aggregateAnnouncements: () => aggregateAnnouncements,
90
91
  aggregatesCheckpoints: () => aggregatesCheckpoints,
@@ -5166,6 +5167,22 @@ var NamespaceMismatch = class NamespaceMismatch2 extends Error {
5166
5167
  super("namespace-mismatch");
5167
5168
  }
5168
5169
  };
5170
+ var WorkflowNotRegistered = class extends Error {
5171
+ static {
5172
+ __name(this, "WorkflowNotRegistered");
5173
+ }
5174
+ constructor(workflow, version) {
5175
+ super(`workflow ${workflow}@${version} is not registered \u2014 keep the prior version deployed so in-flight runs can drain (skew protection)`);
5176
+ this.name = "WorkflowNotRegistered";
5177
+ }
5178
+ };
5179
+ var UNREGISTERED_DEAD_LETTER_FROM = [
5180
+ "pending",
5181
+ "running",
5182
+ "suspended",
5183
+ "cancelling",
5184
+ "blocked"
5185
+ ];
5169
5186
  var WorkflowEngine = class {
5170
5187
  static {
5171
5188
  __name(this, "WorkflowEngine");
@@ -5185,6 +5202,7 @@ var WorkflowEngine = class {
5185
5202
  */
5186
5203
  ownLeaseCutoffMs;
5187
5204
  maxRecoveryAttempts;
5205
+ unregisteredWorkflowGraceMs;
5188
5206
  remoteAdvanceSilenceMs;
5189
5207
  reconcileMs;
5190
5208
  timerBatchSize;
@@ -5371,6 +5389,8 @@ var WorkflowEngine = class {
5371
5389
  this.leaseMs = deps.leaseMs ?? 3e4;
5372
5390
  this.ownLeaseCutoffMs = this.clock() + this.leaseMs;
5373
5391
  this.maxRecoveryAttempts = deps.maxRecoveryAttempts;
5392
+ const grace = deps.unregisteredWorkflowGraceMs;
5393
+ this.unregisteredWorkflowGraceMs = grace !== void 0 && Number.isFinite(grace) && grace >= 0 ? grace : 24 * 60 * 60 * 1e3;
5374
5394
  this.remoteAdvanceSilenceMs = deps.remoteAdvanceSilenceMs;
5375
5395
  this.reconcileMs = deps.reconcileMs === void 0 ? 3e5 : deps.reconcileMs || void 0;
5376
5396
  const stalledAfter = deps.stalledAfterMs;
@@ -5687,13 +5707,19 @@ var WorkflowEngine = class {
5687
5707
  * that is lost brings it back due after that period. False when the transport refused the wakes,
5688
5708
  * so the caller resumes them itself.
5689
5709
  */
5690
- async handOffDue(runs, nowMs) {
5710
+ async handOffDue(runs, nowMs, settled) {
5691
5711
  const claimed = [];
5692
5712
  for (const run of runs) {
5693
5713
  if (this.draining) break;
5694
5714
  if (!await this.store.tryLockRun(run.id, this.instanceId, nowMs + this.leaseMs, nowMs)) {
5695
5715
  continue;
5696
5716
  }
5717
+ if (!this.isRegisteredHere(run) && !await this.canResolveWorkflow(run)) {
5718
+ const result = await this.settleUnregistered(run, nowMs);
5719
+ if (result) settled?.set(run.id, result);
5720
+ else if (result === void 0) this.logUnregisteredSkip(run);
5721
+ continue;
5722
+ }
5697
5723
  try {
5698
5724
  const patch = {
5699
5725
  wakeAt: nowMs + this.leaseMs
@@ -6467,9 +6493,7 @@ var WorkflowEngine = class {
6467
6493
  });
6468
6494
  }
6469
6495
  const registered = this.workflows.get(versionKey(run.workflow, run.workflowVersion)) ?? await this.findInheritedRegistration(run) ?? await this.resolveRemoteByConvention(run);
6470
- if (!registered) {
6471
- throw new Error(`workflow ${run.workflow}@${run.workflowVersion} is not registered \u2014 keep the prior version deployed so in-flight runs can drain (skew protection)`);
6472
- }
6496
+ if (!registered) throw new WorkflowNotRegistered(run.workflow, run.workflowVersion);
6473
6497
  return this.track(this.execute(run, registered.fn));
6474
6498
  }
6475
6499
  /**
@@ -6884,6 +6908,15 @@ var WorkflowEngine = class {
6884
6908
  };
6885
6909
  }
6886
6910
  }
6911
+ if (!this.isRegisteredHere(run) && !await this.canResolveWorkflow(run)) {
6912
+ const settled2 = await this.settleUnregistered(run, nowMs);
6913
+ if (settled2) return {
6914
+ result: settled2,
6915
+ dispatch: false
6916
+ };
6917
+ if (settled2 === void 0) this.logUnregisteredSkip(run);
6918
+ return void 0;
6919
+ }
6887
6920
  const settled = await this.countRecovery(run);
6888
6921
  if (settled) return {
6889
6922
  result: settled,
@@ -6955,25 +6988,10 @@ var WorkflowEngine = class {
6955
6988
  updatedAt: /* @__PURE__ */ new Date()
6956
6989
  });
6957
6990
  await this.store.releaseRunLock(run.id);
6958
- this.emit({
6959
- type: "run.failed",
6960
- runId: run.id,
6961
- workflow: run.workflow,
6962
- namespace: run.namespace,
6963
- error: error2
6964
- });
6965
- this.notifyDead({
6991
+ return this.announceDead({
6966
6992
  ...run,
6967
- status: "dead",
6968
- error: error2,
6969
6993
  recoveryAttempts: attempts
6970
- });
6971
- this.notifyParent(run.id, failedCompletion(error2));
6972
- return {
6973
- runId: run.id,
6974
- status: "dead",
6975
- error: error2
6976
- };
6994
+ }, error2);
6977
6995
  }
6978
6996
  await this.store.updateRun(run.id, {
6979
6997
  recoveryAttempts: attempts,
@@ -6981,6 +6999,85 @@ var WorkflowEngine = class {
6981
6999
  });
6982
7000
  return void 0;
6983
7001
  }
7002
+ /** Tell everyone a run was just written `dead`: events, dead-letter routing, a waiting parent. */
7003
+ announceDead(run, error2) {
7004
+ this.emit({
7005
+ type: "run.failed",
7006
+ runId: run.id,
7007
+ workflow: run.workflow,
7008
+ namespace: run.namespace,
7009
+ error: error2
7010
+ });
7011
+ this.notifyDead({
7012
+ ...run,
7013
+ status: "dead",
7014
+ error: error2
7015
+ });
7016
+ this.notifyParent(run.id, failedCompletion(error2));
7017
+ return {
7018
+ runId: run.id,
7019
+ status: "dead",
7020
+ error: error2
7021
+ };
7022
+ }
7023
+ /** The synchronous half of {@link canResolveWorkflow}: callers check it first, so a registered run
7024
+ * pays no await (same rule as {@link resume}). */
7025
+ isRegisteredHere(run) {
7026
+ return this.workflows.has(versionKey(run.workflow, run.workflowVersion));
7027
+ }
7028
+ /**
7029
+ * Whether this instance can run `run`'s pinned `workflow@version`: registered here, inherited from a
7030
+ * remote ancestor, or routed by convention to a live worker group (the lookup {@link resume} does).
7031
+ */
7032
+ async canResolveWorkflow(run) {
7033
+ if (this.isRegisteredHere(run)) return true;
7034
+ return await this.findInheritedRegistration(run) !== void 0 || await this.resolveRemoteByConvention(run) !== void 0;
7035
+ }
7036
+ /**
7037
+ * A run whose lease this instance holds but whose `workflow@version` nothing here can run (see
7038
+ * {@link WorkflowNotRegistered}). Within {@link unregisteredWorkflowGraceMs} of becoming due it is a
7039
+ * rolling deploy's skew: the lease is released at once so the pod that still has the version takes
7040
+ * the run now, not after the lease expires. Past it, the workflow is gone from the whole fleet (a
7041
+ * capable pod would have taken the run long ago): dead-letter it.
7042
+ *
7043
+ * The age is read off `updatedAt` / `wakeAt`, so every path that would touch either (a recovery
7044
+ * count, a re-pend, a hand-off's lease-long `wakeAt`) must call this BEFORE writing — otherwise an
7045
+ * orphan never ages.
7046
+ *
7047
+ * Returns the `dead` result, `null` when the run left its status meanwhile (a lease-free
7048
+ * `cancel()`: settled, not ours to touch), or `undefined` when it was left for later.
7049
+ */
7050
+ async settleUnregistered(listed, nowMs) {
7051
+ const run = await this.store.getRun(listed.id);
7052
+ if (!run || !UNREGISTERED_DEAD_LETTER_FROM.includes(run.status)) {
7053
+ await this.store.releaseRunLock(listed.id);
7054
+ return null;
7055
+ }
7056
+ const dueSince = Math.max(run.updatedAt.getTime(), run.wakeAt ?? 0);
7057
+ if (this.unregisteredWorkflowGraceMs === 0 || nowMs - dueSince < this.unregisteredWorkflowGraceMs) {
7058
+ await this.store.releaseRunLock(run.id);
7059
+ return void 0;
7060
+ }
7061
+ const error2 = {
7062
+ message: `workflow ${run.workflow}@${run.workflowVersion} is not registered on any live instance (unresumable for over ${this.unregisteredWorkflowGraceMs}ms) \u2014 moved to dead-letter`,
7063
+ code: "workflow_not_registered"
7064
+ };
7065
+ const applied = await (this.store.updateRunIf ?? this.updateRunIfFallback).call(this.store, run.id, [
7066
+ run.status
7067
+ ], {
7068
+ status: "dead",
7069
+ error: error2,
7070
+ updatedAt: /* @__PURE__ */ new Date()
7071
+ });
7072
+ await this.store.releaseRunLock(run.id);
7073
+ if (!applied) return null;
7074
+ console.warn(`[nestjs-durable] run ${run.id}: ${error2.message}`);
7075
+ return this.announceDead(run, error2);
7076
+ }
7077
+ /** Log a run skipped for an unregistered workflow — still there, still not progressing. */
7078
+ logUnregisteredSkip(run) {
7079
+ console.error(`[nestjs-durable] could not resume run ${run.id} (${run.workflow}@${run.workflowVersion}); leaving it for another instance:`, new WorkflowNotRegistered(run.workflow, run.workflowVersion));
7080
+ }
6984
7081
  /**
6985
7082
  * Resume every suspended run whose durable timer is due. Call periodically (a poller) and on
6986
7083
  * boot. A run still not due re-suspends cheaply without running new work.
@@ -7005,11 +7102,12 @@ var WorkflowEngine = class {
7005
7102
  ...due,
7006
7103
  ...blocked
7007
7104
  ];
7008
- if (await this.handOffDue(runs, nowMs)) {
7009
- return runs.map((run) => ({
7105
+ const settled = /* @__PURE__ */ new Map();
7106
+ if (await this.handOffDue(runs, nowMs, settled)) {
7107
+ return runs.map((run) => settled.get(run.id) ?? {
7010
7108
  runId: run.id,
7011
7109
  status: run.status
7012
- }));
7110
+ });
7013
7111
  }
7014
7112
  }
7015
7113
  const waiterByRun = indexWaitersByRun(await listSignalWaitersOfRuns(this.store, [
@@ -7090,8 +7188,13 @@ var WorkflowEngine = class {
7090
7188
  const nowMs = this.clock();
7091
7189
  const acquired = await this.store.tryLockRun(runId, this.instanceId, nowMs + this.leaseMs, nowMs);
7092
7190
  if (!acquired) return null;
7093
- return this.resumeImplicit(runId).catch((err) => {
7191
+ return this.resumeImplicit(runId).catch(async (err) => {
7094
7192
  if (err instanceof NamespaceMismatch) return null;
7193
+ if (err instanceof WorkflowNotRegistered) {
7194
+ const run = await this.store.getRun(runId);
7195
+ const settled = run ? await this.settleUnregistered(run, nowMs) : null;
7196
+ if (settled !== void 0) return settled;
7197
+ }
7095
7198
  throw err;
7096
7199
  });
7097
7200
  }
@@ -7346,7 +7449,8 @@ var WorkflowEngine = class {
7346
7449
  * Resume each run only if this instance can acquire its recovery lease — so when several
7347
7450
  * replicas recover or poll at once, each run is picked up by exactly one of them.
7348
7451
  *
7349
- * A run this instance cannot resume is SKIPPED, not allowed to abort the batch. The canonical
7452
+ * A run this instance cannot resume is SKIPPED, not allowed to abort the batch (a run whose workflow
7453
+ * stays registered nowhere past `unregisteredWorkflowGraceMs` is dead-lettered instead). The canonical
7350
7454
  * case is skew protection: mid-rolling-deploy a pod leases a run whose workflow it does not have
7351
7455
  * and `resume` throws by design — but the rest of the batch is runs it can drive perfectly well,
7352
7456
  * and every caller here is a recovery sweep. Letting the first such run end the loop means one
@@ -7370,6 +7474,11 @@ var WorkflowEngine = class {
7370
7474
  const settled = onLocked ? await onLocked(run) : void 0;
7371
7475
  results.push(settled ?? await this.resumeImplicit(run.id));
7372
7476
  } catch (error2) {
7477
+ if (error2 instanceof WorkflowNotRegistered) {
7478
+ const settled = await this.settleUnregistered(run, nowMs).catch(() => void 0);
7479
+ if (settled) results.push(settled);
7480
+ if (settled !== void 0) continue;
7481
+ }
7373
7482
  console.error(`[nestjs-durable] could not resume run ${run.id} (${run.workflow}@${run.workflowVersion}); leaving it for another instance:`, error2);
7374
7483
  }
7375
7484
  }
@@ -13131,6 +13240,7 @@ var InMemoryRunQueue = class {
13131
13240
  WORKFLOW_NAME_KEY,
13132
13241
  WorkflowBlocked,
13133
13242
  WorkflowEngine,
13243
+ WorkflowNotRegistered,
13134
13244
  WorkflowSuspended,
13135
13245
  aggregateAnnouncements,
13136
13246
  aggregatesCheckpoints,