@dudousxd/nestjs-durable-core 0.85.6 → 0.85.7
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 +397 -94
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +114 -12
- package/dist/index.d.ts +114 -12
- package/dist/index.js +397 -94
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -1242,11 +1242,28 @@ interface StateStore {
|
|
|
1242
1242
|
*/
|
|
1243
1243
|
deleteRuns?(runIds: string[]): Promise<void>;
|
|
1244
1244
|
getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
|
|
1245
|
+
/**
|
|
1246
|
+
* The run's checkpoints at `seqs`, in `seq` order; a seq with no checkpoint is left out, and an
|
|
1247
|
+
* empty `seqs` reads nothing. The engine reads a batch of one run's step results' checkpoints
|
|
1248
|
+
* through it, one call per batch.
|
|
1249
|
+
*
|
|
1250
|
+
* Optional: a store that omits it gets one {@link getCheckpoint} per seq.
|
|
1251
|
+
*/
|
|
1252
|
+
getCheckpoints?(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
|
|
1245
1253
|
/**
|
|
1246
1254
|
* Persist a checkpoint and advance the run atomically. Durable semantics depend on this
|
|
1247
1255
|
* being a single transaction; stores without transactions cannot give the strong guarantee.
|
|
1248
1256
|
*/
|
|
1249
1257
|
saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
|
|
1258
|
+
/**
|
|
1259
|
+
* {@link saveCheckpoint} for many checkpoints in one call: each is written (inserted, or
|
|
1260
|
+
* overwriting the row at its `(runId, seq)`), in a few statements and one transaction, so a
|
|
1261
|
+
* rejection writes nothing. The entries name distinct rows. The engine writes a step fan's new
|
|
1262
|
+
* `pending` checkpoints through it before dispatching them.
|
|
1263
|
+
*
|
|
1264
|
+
* Optional: a store that omits it gets one {@link saveCheckpoint} per checkpoint.
|
|
1265
|
+
*/
|
|
1266
|
+
saveCheckpoints?(checkpoints: StepCheckpoint[]): Promise<void>;
|
|
1250
1267
|
/**
|
|
1251
1268
|
* Overwrite the checkpoint at `(runId, seq)` with `checkpoint`, but only while the stored row is
|
|
1252
1269
|
* still `pending`; resolves whether it wrote. The engine writes a dispatched step's row from two
|
|
@@ -2328,6 +2345,15 @@ interface RunConsumerOptions extends RunQueueOptions {
|
|
|
2328
2345
|
interface Transport {
|
|
2329
2346
|
/** engine → worker */
|
|
2330
2347
|
dispatch(task: RemoteTask): Promise<void>;
|
|
2348
|
+
/**
|
|
2349
|
+
* {@link dispatch} for many tasks in a few broker calls. Rejects if any task may not have been
|
|
2350
|
+
* dispatched (some may have been: the engine then dispatches the batch again one task at a time,
|
|
2351
|
+
* and a task delivered twice runs twice, as any redelivery does). The engine sends a step fan's
|
|
2352
|
+
* new steps through it.
|
|
2353
|
+
*
|
|
2354
|
+
* Optional: a transport that omits it gets one {@link dispatch} per task.
|
|
2355
|
+
*/
|
|
2356
|
+
dispatchMany?(tasks: RemoteTask[]): Promise<void>;
|
|
2331
2357
|
/** worker → engine: a step finished (ok or error). */
|
|
2332
2358
|
onResult(handler: (result: StepResult) => Promise<void>): void;
|
|
2333
2359
|
/** worker → engine: liveness signal for an in-flight long step. */
|
|
@@ -4679,6 +4705,23 @@ declare class WorkflowEngine {
|
|
|
4679
4705
|
private readonly wakeTurns;
|
|
4680
4706
|
/** Re-checks scheduled for runs whose wake found another instance's lease (see {@link execute}). */
|
|
4681
4707
|
private readonly leaseRetries;
|
|
4708
|
+
/**
|
|
4709
|
+
* Runs whose scheduled re-check resumes them whatever happened meanwhile. Without an entry the
|
|
4710
|
+
* re-check only stood for fan wakes kept as requests, and resumes the run only if a request is
|
|
4711
|
+
* still there: the turn that held the lease takes them once it ends (see {@link retryDroppedWake}).
|
|
4712
|
+
*/
|
|
4713
|
+
private readonly unconditionalRechecks;
|
|
4714
|
+
/** Runs a generic wake request was written for in the current re-check cycle (see {@link execute}). */
|
|
4715
|
+
private readonly genericWakeRequested;
|
|
4716
|
+
/** Why each run is being woken on this instance, until the turn that answers it starts. */
|
|
4717
|
+
private readonly wakeReasons;
|
|
4718
|
+
/**
|
|
4719
|
+
* The step fans each executing turn on this instance read with nothing in flight: first seq -> the
|
|
4720
|
+
* highest seq read. Written by {@link callRemoteAll}, read once the turn ends.
|
|
4721
|
+
*/
|
|
4722
|
+
private readonly turnSettledFans;
|
|
4723
|
+
/** The wake requests each executing turn on this instance serves (see {@link noteServedWakes}). */
|
|
4724
|
+
private readonly turnServedWakes;
|
|
4682
4725
|
/**
|
|
4683
4726
|
* Every run turn and child start this instance takes on itself, under one budget of
|
|
4684
4727
|
* {@link LOCAL_RUN_CONCURRENCY}: the runs it dispatches to itself, a fan's deferred child starts,
|
|
@@ -5003,6 +5046,8 @@ declare class WorkflowEngine {
|
|
|
5003
5046
|
* terminal too.
|
|
5004
5047
|
*/
|
|
5005
5048
|
resume(runId: string): Promise<RunResult>;
|
|
5049
|
+
/** Record why `runId` is being woken: a step fan's barrier opening, or (`undefined`) anything else. */
|
|
5050
|
+
private noteWakeReason;
|
|
5006
5051
|
/**
|
|
5007
5052
|
* {@link resume} for every IMPLICIT wake-up — a delivered signal/child completion, a late step
|
|
5008
5053
|
* result, a due timer, a redelivered dispatch, a queue-slot wake. A `failed` run is terminal to
|
|
@@ -5742,19 +5787,48 @@ declare class WorkflowEngine {
|
|
|
5742
5787
|
/**
|
|
5743
5788
|
* Keep a wake that found `runId`'s lease held by a turn executing elsewhere, durably, so that turn
|
|
5744
5789
|
* runs again once it ends instead of suspending on a snapshot that predates what the wake brought
|
|
5745
|
-
* (a signal, a child's completion). The request is a buffered
|
|
5746
|
-
* on
|
|
5790
|
+
* (a signal, a child's completion). The request is a buffered event under a name no workflow waits
|
|
5791
|
+
* on. It stays until a turn that started after it has settled: the holder looks at it after it
|
|
5792
|
+
* releases the lease ({@link honorWakeRequests}), and the turn that serves it drops it.
|
|
5747
5793
|
*
|
|
5748
5794
|
* Written first and looked at second, against a holder that releases first and looks second:
|
|
5749
5795
|
* whichever look runs last sees the other side's write. So when the run is no longer executing by
|
|
5750
|
-
* the time this re-reads it, the holder may have looked already, and this side
|
|
5751
|
-
*
|
|
5796
|
+
* the time this re-reads it, the holder may have looked already, and this side wakes the run
|
|
5797
|
+
* itself once the lease is free ({@link retryDroppedWake}). While the holder still runs, the run is
|
|
5798
|
+
* made due when the holder's lease runs out, so a holder that goes down before it settles leaves
|
|
5799
|
+
* the run to any instance's timer poll; a holder that settles sets the run's timer itself.
|
|
5752
5800
|
*/
|
|
5753
5801
|
private requestWakeAfterTurn;
|
|
5754
|
-
/**
|
|
5802
|
+
/**
|
|
5803
|
+
* After a turn that suspended released its lease: drop the wakes it served, and run again if a
|
|
5804
|
+
* wake was kept for it meanwhile, unless every such wake was a fan wake this turn already saw: it
|
|
5805
|
+
* read that fan with nothing in flight, at least as far as the batch that opened its barrier.
|
|
5806
|
+
* The run is made due before it is woken, so if this instance goes down before that turn runs,
|
|
5807
|
+
* the timer poll of another instance runs it once this instance's hold on it would have lapsed.
|
|
5808
|
+
*/
|
|
5755
5809
|
private honorWakeRequests;
|
|
5756
|
-
/**
|
|
5757
|
-
|
|
5810
|
+
/**
|
|
5811
|
+
* The wake requests kept for `runId`. With `legacy`, also those an older engine kept as buffered
|
|
5812
|
+
* signals, which are taken as they are read.
|
|
5813
|
+
*/
|
|
5814
|
+
private listWakeRequests;
|
|
5815
|
+
/** Delete `requests` (the ones kept as buffered events). */
|
|
5816
|
+
private dropWakeRequests;
|
|
5817
|
+
/**
|
|
5818
|
+
* Record, for the turn executing `runId` here, the wakes kept for the run so far. Called before the
|
|
5819
|
+
* turn reads the run's state, so the turn serves them: they are dropped once it has settled, and
|
|
5820
|
+
* until then stay for whoever runs the run next.
|
|
5821
|
+
*/
|
|
5822
|
+
private noteServedWakes;
|
|
5823
|
+
/**
|
|
5824
|
+
* Right after a turn of `runId` wrote its suspension, while it still holds the lease: if a wake
|
|
5825
|
+
* was kept for the run during the turn that the turn did not see, keep the run due when the lease
|
|
5826
|
+
* runs out. The suspension overwrote the timer the instance keeping the wake set, and this instance
|
|
5827
|
+
* may go down before it looks at the wake once it has released the lease.
|
|
5828
|
+
*/
|
|
5829
|
+
private keepDueForKeptWakes;
|
|
5830
|
+
/** Bring a suspended run's timer forward to `at` (never later than the one it has). */
|
|
5831
|
+
private makeDueBy;
|
|
5758
5832
|
/**
|
|
5759
5833
|
* A wake that found the run leased by another instance is dropped, and normally that is fine: the
|
|
5760
5834
|
* holder's turn either sees what the wake wrote, or re-checks once it releases the lease
|
|
@@ -6101,6 +6175,11 @@ declare class WorkflowEngine {
|
|
|
6101
6175
|
* capable+compatible worker has appeared, else re-parks with a fresh `wakeAt` (design §7.5). */
|
|
6102
6176
|
private dueBlockedRuns;
|
|
6103
6177
|
private callRemote;
|
|
6178
|
+
/**
|
|
6179
|
+
* Whether a `pending` step a turn just read only waits for its result: {@link callRemote} would
|
|
6180
|
+
* suspend on it without writing (no redispatch deadline to stamp, the one stamped not yet due).
|
|
6181
|
+
*/
|
|
6182
|
+
private stepIsWaiting;
|
|
6104
6183
|
/**
|
|
6105
6184
|
* `ctx.all` over a `@Step`: one durable step per input, dispatched together, joined once. The ctx
|
|
6106
6185
|
* reserves the whole position block up front, so replay re-derives the same seqs.
|
|
@@ -6113,7 +6192,11 @@ declare class WorkflowEngine {
|
|
|
6113
6192
|
* barrier ({@link stepFanStillRunning}) then wakes the parent once per wave, not once per result.
|
|
6114
6193
|
*/
|
|
6115
6194
|
private callRemoteAll;
|
|
6116
|
-
/**
|
|
6195
|
+
/**
|
|
6196
|
+
* Write the `pending` checkpoints of a step fan's new steps, then dispatch them: one
|
|
6197
|
+
* {@link StateStore.saveCheckpoints} call and one {@link TransportPool.dispatchMany} for the
|
|
6198
|
+
* batch, where the store and transport have them.
|
|
6199
|
+
*/
|
|
6117
6200
|
private sendStepFan;
|
|
6118
6201
|
/** Remember a step settled here, forgetting entries older than a lease so the map stays small. */
|
|
6119
6202
|
private noteSettledHere;
|
|
@@ -6128,6 +6211,12 @@ declare class WorkflowEngine {
|
|
|
6128
6211
|
* call rejecting means it wrote nothing, so the entries are then written one by one.
|
|
6129
6212
|
*/
|
|
6130
6213
|
private savePendingCheckpoints;
|
|
6214
|
+
/**
|
|
6215
|
+
* The checkpoints of one run at distinct `seqs`, each as its own outcome: one
|
|
6216
|
+
* {@link StateStore.getCheckpoints} call when the store has it, else one read each. The batch
|
|
6217
|
+
* call rejecting falls back to one read each, so a failing read fails only its own entry.
|
|
6218
|
+
*/
|
|
6219
|
+
private readCheckpoints;
|
|
6131
6220
|
/** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
|
|
6132
6221
|
* dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
|
|
6133
6222
|
* {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
|
|
@@ -6147,9 +6236,10 @@ declare class WorkflowEngine {
|
|
|
6147
6236
|
*
|
|
6148
6237
|
* Results of one run are settled in batches: the first starts a batch, and the ones that arrive
|
|
6149
6238
|
* while it is being written form the next. Under load a wide fan's results are written by one
|
|
6150
|
-
* {@link StateStore.saveCheckpointsIfPending} call per batch, and the fan's barrier is asked
|
|
6151
|
-
*
|
|
6152
|
-
* transport acknowledges nothing that is not durable yet.
|
|
6239
|
+
* {@link StateStore.saveCheckpointsIfPending} call per batch, and the fan's barrier is asked only
|
|
6240
|
+
* by a batch with no more of the fan's results queued behind it. A result resolves only once its
|
|
6241
|
+
* own write has committed, so the transport acknowledges nothing that is not durable yet. How
|
|
6242
|
+
* large a batch gets is bounded by how many results the transport hands over at once.
|
|
6153
6243
|
*/
|
|
6154
6244
|
private completeRemoteResult;
|
|
6155
6245
|
/** Settle `queue` (a run's queued results) batch by batch until it is empty, then retire it. */
|
|
@@ -6158,6 +6248,11 @@ declare class WorkflowEngine {
|
|
|
6158
6248
|
* Settle a batch of one run's step results. At most one of them resolves `true` (resume the run):
|
|
6159
6249
|
* that resume replays every write of the batch, so a second would only replay it again. A result
|
|
6160
6250
|
* whose read or write failed resolves its error, and the transport redelivers just that one.
|
|
6251
|
+
*
|
|
6252
|
+
* `queuedIn(from, to)` says whether a result for a seq in that range is already waiting for this
|
|
6253
|
+
* run's next batch on this instance. A fan with one waiting is not asked its barrier: that result
|
|
6254
|
+
* asks it once its own batch is written (as a settle, or as a redelivery of a settled step), so
|
|
6255
|
+
* under a backlog the barrier is read once per drained queue rather than once per batch.
|
|
6161
6256
|
*/
|
|
6162
6257
|
private completeRemoteResults;
|
|
6163
6258
|
/**
|
|
@@ -6172,7 +6267,8 @@ declare class WorkflowEngine {
|
|
|
6172
6267
|
* retry needs the parent to schedule it). Without it every result would replay the whole parent,
|
|
6173
6268
|
* which makes a fan of N steps cost O(N²) checkpoint reads. `barriers` holds the answer per fan
|
|
6174
6269
|
* for the rest of a batch. A barrier that cannot be read counts as open: a spare resume replays and
|
|
6175
|
-
* re-suspends, a lost one strands the run.
|
|
6270
|
+
* re-suspends, a lost one strands the run. A fan with a result waiting in `queuedIn` is left to
|
|
6271
|
+
* that result (see {@link completeRemoteResults}).
|
|
6176
6272
|
*/
|
|
6177
6273
|
private stepFanStillRunning;
|
|
6178
6274
|
/** How many steps of a step fan's seq range are still `pending`. */
|
|
@@ -6893,6 +6989,10 @@ declare class CodecStateStore implements StateStore {
|
|
|
6893
6989
|
readonly saveCheckpointIfPending?: (checkpoint: StepCheckpoint) => Promise<boolean>;
|
|
6894
6990
|
/** Encodes each checkpoint like {@link saveCheckpoint}. Bound only when the inner store has it. */
|
|
6895
6991
|
readonly saveCheckpointsIfPending?: (checkpoints: StepCheckpoint[]) => Promise<boolean[]>;
|
|
6992
|
+
/** Encodes each checkpoint written. Bound only when the inner store has it. */
|
|
6993
|
+
readonly saveCheckpoints?: (checkpoints: StepCheckpoint[]) => Promise<void>;
|
|
6994
|
+
/** Decodes each checkpoint read. Bound only when the inner store has it. */
|
|
6995
|
+
readonly getCheckpoints?: (runId: string, seqs: number[]) => Promise<StepCheckpoint[]>;
|
|
6896
6996
|
/** Forwarded verbatim — a count reads no payload. Bound only when the inner store has it. */
|
|
6897
6997
|
readonly countCheckpoints?: (runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]) => Promise<number>;
|
|
6898
6998
|
/** Forwarded verbatim — retention selects by status/updatedAt/scope, never by payload. Bound only
|
|
@@ -7438,7 +7538,9 @@ declare class InMemoryStateStore implements StateStore {
|
|
|
7438
7538
|
deleteRuns(runIds: string[]): Promise<void>;
|
|
7439
7539
|
pruneTerminalRuns(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
|
|
7440
7540
|
getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
|
|
7541
|
+
getCheckpoints(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
|
|
7441
7542
|
saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
|
|
7543
|
+
saveCheckpoints(checkpoints: StepCheckpoint[]): Promise<void>;
|
|
7442
7544
|
saveCheckpointIfPending(checkpoint: StepCheckpoint): Promise<boolean>;
|
|
7443
7545
|
saveCheckpointsIfPending(checkpoints: StepCheckpoint[]): Promise<boolean[]>;
|
|
7444
7546
|
listOrphanedRuns(nowMs: number, limit: number, namespace?: string, ownedBy?: OwnedLeaseReclaim): Promise<WorkflowRun[]>;
|
package/dist/index.d.ts
CHANGED
|
@@ -1242,11 +1242,28 @@ interface StateStore {
|
|
|
1242
1242
|
*/
|
|
1243
1243
|
deleteRuns?(runIds: string[]): Promise<void>;
|
|
1244
1244
|
getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
|
|
1245
|
+
/**
|
|
1246
|
+
* The run's checkpoints at `seqs`, in `seq` order; a seq with no checkpoint is left out, and an
|
|
1247
|
+
* empty `seqs` reads nothing. The engine reads a batch of one run's step results' checkpoints
|
|
1248
|
+
* through it, one call per batch.
|
|
1249
|
+
*
|
|
1250
|
+
* Optional: a store that omits it gets one {@link getCheckpoint} per seq.
|
|
1251
|
+
*/
|
|
1252
|
+
getCheckpoints?(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
|
|
1245
1253
|
/**
|
|
1246
1254
|
* Persist a checkpoint and advance the run atomically. Durable semantics depend on this
|
|
1247
1255
|
* being a single transaction; stores without transactions cannot give the strong guarantee.
|
|
1248
1256
|
*/
|
|
1249
1257
|
saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
|
|
1258
|
+
/**
|
|
1259
|
+
* {@link saveCheckpoint} for many checkpoints in one call: each is written (inserted, or
|
|
1260
|
+
* overwriting the row at its `(runId, seq)`), in a few statements and one transaction, so a
|
|
1261
|
+
* rejection writes nothing. The entries name distinct rows. The engine writes a step fan's new
|
|
1262
|
+
* `pending` checkpoints through it before dispatching them.
|
|
1263
|
+
*
|
|
1264
|
+
* Optional: a store that omits it gets one {@link saveCheckpoint} per checkpoint.
|
|
1265
|
+
*/
|
|
1266
|
+
saveCheckpoints?(checkpoints: StepCheckpoint[]): Promise<void>;
|
|
1250
1267
|
/**
|
|
1251
1268
|
* Overwrite the checkpoint at `(runId, seq)` with `checkpoint`, but only while the stored row is
|
|
1252
1269
|
* still `pending`; resolves whether it wrote. The engine writes a dispatched step's row from two
|
|
@@ -2328,6 +2345,15 @@ interface RunConsumerOptions extends RunQueueOptions {
|
|
|
2328
2345
|
interface Transport {
|
|
2329
2346
|
/** engine → worker */
|
|
2330
2347
|
dispatch(task: RemoteTask): Promise<void>;
|
|
2348
|
+
/**
|
|
2349
|
+
* {@link dispatch} for many tasks in a few broker calls. Rejects if any task may not have been
|
|
2350
|
+
* dispatched (some may have been: the engine then dispatches the batch again one task at a time,
|
|
2351
|
+
* and a task delivered twice runs twice, as any redelivery does). The engine sends a step fan's
|
|
2352
|
+
* new steps through it.
|
|
2353
|
+
*
|
|
2354
|
+
* Optional: a transport that omits it gets one {@link dispatch} per task.
|
|
2355
|
+
*/
|
|
2356
|
+
dispatchMany?(tasks: RemoteTask[]): Promise<void>;
|
|
2331
2357
|
/** worker → engine: a step finished (ok or error). */
|
|
2332
2358
|
onResult(handler: (result: StepResult) => Promise<void>): void;
|
|
2333
2359
|
/** worker → engine: liveness signal for an in-flight long step. */
|
|
@@ -4679,6 +4705,23 @@ declare class WorkflowEngine {
|
|
|
4679
4705
|
private readonly wakeTurns;
|
|
4680
4706
|
/** Re-checks scheduled for runs whose wake found another instance's lease (see {@link execute}). */
|
|
4681
4707
|
private readonly leaseRetries;
|
|
4708
|
+
/**
|
|
4709
|
+
* Runs whose scheduled re-check resumes them whatever happened meanwhile. Without an entry the
|
|
4710
|
+
* re-check only stood for fan wakes kept as requests, and resumes the run only if a request is
|
|
4711
|
+
* still there: the turn that held the lease takes them once it ends (see {@link retryDroppedWake}).
|
|
4712
|
+
*/
|
|
4713
|
+
private readonly unconditionalRechecks;
|
|
4714
|
+
/** Runs a generic wake request was written for in the current re-check cycle (see {@link execute}). */
|
|
4715
|
+
private readonly genericWakeRequested;
|
|
4716
|
+
/** Why each run is being woken on this instance, until the turn that answers it starts. */
|
|
4717
|
+
private readonly wakeReasons;
|
|
4718
|
+
/**
|
|
4719
|
+
* The step fans each executing turn on this instance read with nothing in flight: first seq -> the
|
|
4720
|
+
* highest seq read. Written by {@link callRemoteAll}, read once the turn ends.
|
|
4721
|
+
*/
|
|
4722
|
+
private readonly turnSettledFans;
|
|
4723
|
+
/** The wake requests each executing turn on this instance serves (see {@link noteServedWakes}). */
|
|
4724
|
+
private readonly turnServedWakes;
|
|
4682
4725
|
/**
|
|
4683
4726
|
* Every run turn and child start this instance takes on itself, under one budget of
|
|
4684
4727
|
* {@link LOCAL_RUN_CONCURRENCY}: the runs it dispatches to itself, a fan's deferred child starts,
|
|
@@ -5003,6 +5046,8 @@ declare class WorkflowEngine {
|
|
|
5003
5046
|
* terminal too.
|
|
5004
5047
|
*/
|
|
5005
5048
|
resume(runId: string): Promise<RunResult>;
|
|
5049
|
+
/** Record why `runId` is being woken: a step fan's barrier opening, or (`undefined`) anything else. */
|
|
5050
|
+
private noteWakeReason;
|
|
5006
5051
|
/**
|
|
5007
5052
|
* {@link resume} for every IMPLICIT wake-up — a delivered signal/child completion, a late step
|
|
5008
5053
|
* result, a due timer, a redelivered dispatch, a queue-slot wake. A `failed` run is terminal to
|
|
@@ -5742,19 +5787,48 @@ declare class WorkflowEngine {
|
|
|
5742
5787
|
/**
|
|
5743
5788
|
* Keep a wake that found `runId`'s lease held by a turn executing elsewhere, durably, so that turn
|
|
5744
5789
|
* runs again once it ends instead of suspending on a snapshot that predates what the wake brought
|
|
5745
|
-
* (a signal, a child's completion). The request is a buffered
|
|
5746
|
-
* on
|
|
5790
|
+
* (a signal, a child's completion). The request is a buffered event under a name no workflow waits
|
|
5791
|
+
* on. It stays until a turn that started after it has settled: the holder looks at it after it
|
|
5792
|
+
* releases the lease ({@link honorWakeRequests}), and the turn that serves it drops it.
|
|
5747
5793
|
*
|
|
5748
5794
|
* Written first and looked at second, against a holder that releases first and looks second:
|
|
5749
5795
|
* whichever look runs last sees the other side's write. So when the run is no longer executing by
|
|
5750
|
-
* the time this re-reads it, the holder may have looked already, and this side
|
|
5751
|
-
*
|
|
5796
|
+
* the time this re-reads it, the holder may have looked already, and this side wakes the run
|
|
5797
|
+
* itself once the lease is free ({@link retryDroppedWake}). While the holder still runs, the run is
|
|
5798
|
+
* made due when the holder's lease runs out, so a holder that goes down before it settles leaves
|
|
5799
|
+
* the run to any instance's timer poll; a holder that settles sets the run's timer itself.
|
|
5752
5800
|
*/
|
|
5753
5801
|
private requestWakeAfterTurn;
|
|
5754
|
-
/**
|
|
5802
|
+
/**
|
|
5803
|
+
* After a turn that suspended released its lease: drop the wakes it served, and run again if a
|
|
5804
|
+
* wake was kept for it meanwhile, unless every such wake was a fan wake this turn already saw: it
|
|
5805
|
+
* read that fan with nothing in flight, at least as far as the batch that opened its barrier.
|
|
5806
|
+
* The run is made due before it is woken, so if this instance goes down before that turn runs,
|
|
5807
|
+
* the timer poll of another instance runs it once this instance's hold on it would have lapsed.
|
|
5808
|
+
*/
|
|
5755
5809
|
private honorWakeRequests;
|
|
5756
|
-
/**
|
|
5757
|
-
|
|
5810
|
+
/**
|
|
5811
|
+
* The wake requests kept for `runId`. With `legacy`, also those an older engine kept as buffered
|
|
5812
|
+
* signals, which are taken as they are read.
|
|
5813
|
+
*/
|
|
5814
|
+
private listWakeRequests;
|
|
5815
|
+
/** Delete `requests` (the ones kept as buffered events). */
|
|
5816
|
+
private dropWakeRequests;
|
|
5817
|
+
/**
|
|
5818
|
+
* Record, for the turn executing `runId` here, the wakes kept for the run so far. Called before the
|
|
5819
|
+
* turn reads the run's state, so the turn serves them: they are dropped once it has settled, and
|
|
5820
|
+
* until then stay for whoever runs the run next.
|
|
5821
|
+
*/
|
|
5822
|
+
private noteServedWakes;
|
|
5823
|
+
/**
|
|
5824
|
+
* Right after a turn of `runId` wrote its suspension, while it still holds the lease: if a wake
|
|
5825
|
+
* was kept for the run during the turn that the turn did not see, keep the run due when the lease
|
|
5826
|
+
* runs out. The suspension overwrote the timer the instance keeping the wake set, and this instance
|
|
5827
|
+
* may go down before it looks at the wake once it has released the lease.
|
|
5828
|
+
*/
|
|
5829
|
+
private keepDueForKeptWakes;
|
|
5830
|
+
/** Bring a suspended run's timer forward to `at` (never later than the one it has). */
|
|
5831
|
+
private makeDueBy;
|
|
5758
5832
|
/**
|
|
5759
5833
|
* A wake that found the run leased by another instance is dropped, and normally that is fine: the
|
|
5760
5834
|
* holder's turn either sees what the wake wrote, or re-checks once it releases the lease
|
|
@@ -6101,6 +6175,11 @@ declare class WorkflowEngine {
|
|
|
6101
6175
|
* capable+compatible worker has appeared, else re-parks with a fresh `wakeAt` (design §7.5). */
|
|
6102
6176
|
private dueBlockedRuns;
|
|
6103
6177
|
private callRemote;
|
|
6178
|
+
/**
|
|
6179
|
+
* Whether a `pending` step a turn just read only waits for its result: {@link callRemote} would
|
|
6180
|
+
* suspend on it without writing (no redispatch deadline to stamp, the one stamped not yet due).
|
|
6181
|
+
*/
|
|
6182
|
+
private stepIsWaiting;
|
|
6104
6183
|
/**
|
|
6105
6184
|
* `ctx.all` over a `@Step`: one durable step per input, dispatched together, joined once. The ctx
|
|
6106
6185
|
* reserves the whole position block up front, so replay re-derives the same seqs.
|
|
@@ -6113,7 +6192,11 @@ declare class WorkflowEngine {
|
|
|
6113
6192
|
* barrier ({@link stepFanStillRunning}) then wakes the parent once per wave, not once per result.
|
|
6114
6193
|
*/
|
|
6115
6194
|
private callRemoteAll;
|
|
6116
|
-
/**
|
|
6195
|
+
/**
|
|
6196
|
+
* Write the `pending` checkpoints of a step fan's new steps, then dispatch them: one
|
|
6197
|
+
* {@link StateStore.saveCheckpoints} call and one {@link TransportPool.dispatchMany} for the
|
|
6198
|
+
* batch, where the store and transport have them.
|
|
6199
|
+
*/
|
|
6117
6200
|
private sendStepFan;
|
|
6118
6201
|
/** Remember a step settled here, forgetting entries older than a lease so the map stays small. */
|
|
6119
6202
|
private noteSettledHere;
|
|
@@ -6128,6 +6211,12 @@ declare class WorkflowEngine {
|
|
|
6128
6211
|
* call rejecting means it wrote nothing, so the entries are then written one by one.
|
|
6129
6212
|
*/
|
|
6130
6213
|
private savePendingCheckpoints;
|
|
6214
|
+
/**
|
|
6215
|
+
* The checkpoints of one run at distinct `seqs`, each as its own outcome: one
|
|
6216
|
+
* {@link StateStore.getCheckpoints} call when the store has it, else one read each. The batch
|
|
6217
|
+
* call rejecting falls back to one read each, so a failing read fails only its own entry.
|
|
6218
|
+
*/
|
|
6219
|
+
private readCheckpoints;
|
|
6131
6220
|
/** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
|
|
6132
6221
|
* dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
|
|
6133
6222
|
* {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
|
|
@@ -6147,9 +6236,10 @@ declare class WorkflowEngine {
|
|
|
6147
6236
|
*
|
|
6148
6237
|
* Results of one run are settled in batches: the first starts a batch, and the ones that arrive
|
|
6149
6238
|
* while it is being written form the next. Under load a wide fan's results are written by one
|
|
6150
|
-
* {@link StateStore.saveCheckpointsIfPending} call per batch, and the fan's barrier is asked
|
|
6151
|
-
*
|
|
6152
|
-
* transport acknowledges nothing that is not durable yet.
|
|
6239
|
+
* {@link StateStore.saveCheckpointsIfPending} call per batch, and the fan's barrier is asked only
|
|
6240
|
+
* by a batch with no more of the fan's results queued behind it. A result resolves only once its
|
|
6241
|
+
* own write has committed, so the transport acknowledges nothing that is not durable yet. How
|
|
6242
|
+
* large a batch gets is bounded by how many results the transport hands over at once.
|
|
6153
6243
|
*/
|
|
6154
6244
|
private completeRemoteResult;
|
|
6155
6245
|
/** Settle `queue` (a run's queued results) batch by batch until it is empty, then retire it. */
|
|
@@ -6158,6 +6248,11 @@ declare class WorkflowEngine {
|
|
|
6158
6248
|
* Settle a batch of one run's step results. At most one of them resolves `true` (resume the run):
|
|
6159
6249
|
* that resume replays every write of the batch, so a second would only replay it again. A result
|
|
6160
6250
|
* whose read or write failed resolves its error, and the transport redelivers just that one.
|
|
6251
|
+
*
|
|
6252
|
+
* `queuedIn(from, to)` says whether a result for a seq in that range is already waiting for this
|
|
6253
|
+
* run's next batch on this instance. A fan with one waiting is not asked its barrier: that result
|
|
6254
|
+
* asks it once its own batch is written (as a settle, or as a redelivery of a settled step), so
|
|
6255
|
+
* under a backlog the barrier is read once per drained queue rather than once per batch.
|
|
6161
6256
|
*/
|
|
6162
6257
|
private completeRemoteResults;
|
|
6163
6258
|
/**
|
|
@@ -6172,7 +6267,8 @@ declare class WorkflowEngine {
|
|
|
6172
6267
|
* retry needs the parent to schedule it). Without it every result would replay the whole parent,
|
|
6173
6268
|
* which makes a fan of N steps cost O(N²) checkpoint reads. `barriers` holds the answer per fan
|
|
6174
6269
|
* for the rest of a batch. A barrier that cannot be read counts as open: a spare resume replays and
|
|
6175
|
-
* re-suspends, a lost one strands the run.
|
|
6270
|
+
* re-suspends, a lost one strands the run. A fan with a result waiting in `queuedIn` is left to
|
|
6271
|
+
* that result (see {@link completeRemoteResults}).
|
|
6176
6272
|
*/
|
|
6177
6273
|
private stepFanStillRunning;
|
|
6178
6274
|
/** How many steps of a step fan's seq range are still `pending`. */
|
|
@@ -6893,6 +6989,10 @@ declare class CodecStateStore implements StateStore {
|
|
|
6893
6989
|
readonly saveCheckpointIfPending?: (checkpoint: StepCheckpoint) => Promise<boolean>;
|
|
6894
6990
|
/** Encodes each checkpoint like {@link saveCheckpoint}. Bound only when the inner store has it. */
|
|
6895
6991
|
readonly saveCheckpointsIfPending?: (checkpoints: StepCheckpoint[]) => Promise<boolean[]>;
|
|
6992
|
+
/** Encodes each checkpoint written. Bound only when the inner store has it. */
|
|
6993
|
+
readonly saveCheckpoints?: (checkpoints: StepCheckpoint[]) => Promise<void>;
|
|
6994
|
+
/** Decodes each checkpoint read. Bound only when the inner store has it. */
|
|
6995
|
+
readonly getCheckpoints?: (runId: string, seqs: number[]) => Promise<StepCheckpoint[]>;
|
|
6896
6996
|
/** Forwarded verbatim — a count reads no payload. Bound only when the inner store has it. */
|
|
6897
6997
|
readonly countCheckpoints?: (runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]) => Promise<number>;
|
|
6898
6998
|
/** Forwarded verbatim — retention selects by status/updatedAt/scope, never by payload. Bound only
|
|
@@ -7438,7 +7538,9 @@ declare class InMemoryStateStore implements StateStore {
|
|
|
7438
7538
|
deleteRuns(runIds: string[]): Promise<void>;
|
|
7439
7539
|
pruneTerminalRuns(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
|
|
7440
7540
|
getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
|
|
7541
|
+
getCheckpoints(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
|
|
7441
7542
|
saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
|
|
7543
|
+
saveCheckpoints(checkpoints: StepCheckpoint[]): Promise<void>;
|
|
7442
7544
|
saveCheckpointIfPending(checkpoint: StepCheckpoint): Promise<boolean>;
|
|
7443
7545
|
saveCheckpointsIfPending(checkpoints: StepCheckpoint[]): Promise<boolean[]>;
|
|
7444
7546
|
listOrphanedRuns(nowMs: number, limit: number, namespace?: string, ownedBy?: OwnedLeaseReclaim): Promise<WorkflowRun[]>;
|