@dudousxd/nestjs-durable-core 0.72.0 → 0.73.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 +285 -104
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +97 -5
- package/dist/index.d.ts +97 -5
- package/dist/index.js +276 -104
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -919,6 +919,17 @@ interface StateStore {
|
|
|
919
919
|
* module's `autoSchema` is on. Optional: stores that need no setup (in-memory) omit it.
|
|
920
920
|
*/
|
|
921
921
|
ensureSchema?(): Promise<void>;
|
|
922
|
+
/**
|
|
923
|
+
* Atomically read active runs sharing workflow/tag in this store's read scope, preserve durable
|
|
924
|
+
* admitted holders, and claim a free slot for an eligible FIFO waiter. The claim persists the
|
|
925
|
+
* reserved SINGLETON_ADMITTED_TAG in tags. Execution lease expiry never releases a slot; terminal
|
|
926
|
+
* status does. Optional for general stores, required when using singleton workflows. Implement
|
|
927
|
+
* with a database transaction that serializes competing claims BEFORE reading; list/update alone
|
|
928
|
+
* is unsafe across engine instances. If retryWakeAt is supplied, denial must atomically suspend
|
|
929
|
+
* the still-active candidate with that wakeAt while the same locks are held. Never overwrite a
|
|
930
|
+
* cancelling or terminal run on denial. Return false for missing/terminal/out-of-scope runs.
|
|
931
|
+
*/
|
|
932
|
+
tryAdmitSingleton?(runId: string, tag: string, workflow: string, limit: number, retryWakeAt?: number): Promise<boolean>;
|
|
922
933
|
createRun(run: WorkflowRun): Promise<void>;
|
|
923
934
|
updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
|
|
924
935
|
getRun(runId: string): Promise<WorkflowRun | null>;
|
|
@@ -2505,6 +2516,32 @@ declare function runInWorkflowCtx<T>(ctx: WorkflowCtx, fn: () => T): T;
|
|
|
2505
2516
|
* ambient workflow context (by design — a handler is not the workflow body).
|
|
2506
2517
|
*/
|
|
2507
2518
|
declare function currentWorkflowCtx(): WorkflowCtx | undefined;
|
|
2519
|
+
/**
|
|
2520
|
+
* The ambient STEP scope: which workflow ctx's checkpointed step body (if any) is executing on this
|
|
2521
|
+
* async path. The engine installs it around every in-body step execution (`ctx.localStep`,
|
|
2522
|
+
* `ctx.transaction`, and everything built on them) so the ctx primitives can refuse to run from
|
|
2523
|
+
* inside a step body — see {@link NestedWorkflowCallError}. `owner` is the identity of the ctx whose
|
|
2524
|
+
* step is running, so a DIFFERENT run's body executed inline from a step (e.g. a step that signals a
|
|
2525
|
+
* run which resumes on this async path) is never mistaken for a nested call.
|
|
2526
|
+
*
|
|
2527
|
+
* Shared per process under a `Symbol.for` key, for the same duplicate-copy reason as the ctx storage.
|
|
2528
|
+
*/
|
|
2529
|
+
interface StepScope {
|
|
2530
|
+
readonly owner: object;
|
|
2531
|
+
readonly step: string;
|
|
2532
|
+
}
|
|
2533
|
+
/** Run `fn` as the body of step `step` of the ctx identified by `owner`. Engine-internal. */
|
|
2534
|
+
declare function runInStepScope<T>(owner: object, step: string, fn: () => T): T;
|
|
2535
|
+
/** The step body currently executing on this async path, or `undefined` outside one. */
|
|
2536
|
+
declare function currentStepScope(): StepScope | undefined;
|
|
2537
|
+
/**
|
|
2538
|
+
* Run `fn` with NO ambient workflow ctx and no step scope — for a dispatched `@Step` handler. A
|
|
2539
|
+
* handler is not the workflow body (on a remote worker it never sees one), but an in-process
|
|
2540
|
+
* transport invokes it on the body's async path, where the parent's ctx would otherwise leak in and
|
|
2541
|
+
* turn a handler's `MyWorkflow.start()` into a journal-corrupting `ctx.startChild` of a parent that
|
|
2542
|
+
* is already suspended. Clearing it makes in-process and remote handlers behave identically.
|
|
2543
|
+
*/
|
|
2544
|
+
declare function runOutsideWorkflowCtx<T>(fn: () => T): T;
|
|
2508
2545
|
|
|
2509
2546
|
/**
|
|
2510
2547
|
* Run `fn` with `logger` as the ambient step logger. Engine-internal: wraps every execution of a
|
|
@@ -3415,8 +3452,8 @@ interface StartOptions {
|
|
|
3415
3452
|
/**
|
|
3416
3453
|
* Serialize runs of a workflow that share a key — a durable, FIFO mutex (e.g. one pipeline per base).
|
|
3417
3454
|
* Excess runs are admitted in creation order, `limit` at a time; the rest wait (suspended) and retry
|
|
3418
|
-
* admission on a timer until a slot frees.
|
|
3419
|
-
*
|
|
3455
|
+
* admission on a timer until a slot frees. The store atomically reserves durable slots before
|
|
3456
|
+
* ordering unadmitted waiters by `(createdAt, id)`, so later starts cannot displace a holder.
|
|
3420
3457
|
*/
|
|
3421
3458
|
interface SingletonConfig {
|
|
3422
3459
|
/** Derive the serialization key from the workflow input. */
|
|
@@ -3427,7 +3464,7 @@ interface SingletonConfig {
|
|
|
3427
3464
|
* Max GATED (waiting-for-admission) runs allowed to queue behind the `limit` in-flight ones. When
|
|
3428
3465
|
* set, `start` rejects with {@link SingletonQueueFullError} once in-flight + gated reaches
|
|
3429
3466
|
* `limit + maxQueueDepth` — back-pressure against an unbounded same-key backlog. Omit for the
|
|
3430
|
-
* default unbounded queue. Counts
|
|
3467
|
+
* default unbounded queue. Counts pending/running/suspended/blocked/cancelling runs sharing the key.
|
|
3431
3468
|
*/
|
|
3432
3469
|
maxQueueDepth?: number;
|
|
3433
3470
|
}
|
|
@@ -3870,7 +3907,23 @@ declare class WorkflowEngine {
|
|
|
3870
3907
|
start<TInput>(workflow: string, input: TInput, runId: string, opts?: StartOptions): Promise<RunResult>;
|
|
3871
3908
|
/** Read a run's current persisted state (or null if unknown). A thin pass-through to the store. */
|
|
3872
3909
|
getRun(runId: string): Promise<WorkflowRun | null>;
|
|
3910
|
+
/**
|
|
3911
|
+
* Re-execute a run's body (replaying its checkpoints). This is the EXPLICIT entry point: besides
|
|
3912
|
+
* driving a live run, it re-drives a `failed` run — the manual retry (prefer {@link requeue}, which
|
|
3913
|
+
* also resets the failure state so replay re-attempts the failed parts). Completed / cancelled /
|
|
3914
|
+
* dead runs are never re-executed. The engine's own implicit wake-ups (signals, step results,
|
|
3915
|
+
* timers, redelivered dispatches) go through {@link resumeImplicit}, which treats `failed` as
|
|
3916
|
+
* terminal too.
|
|
3917
|
+
*/
|
|
3873
3918
|
resume(runId: string): Promise<RunResult>;
|
|
3919
|
+
/**
|
|
3920
|
+
* {@link resume} for every IMPLICIT wake-up — a delivered signal/child completion, a late step
|
|
3921
|
+
* result, a due timer, a redelivered dispatch, a queue-slot wake. A `failed` run is terminal to
|
|
3922
|
+
* these: only an explicit retry ({@link requeue} / {@link resume}) may re-drive it. Otherwise a
|
|
3923
|
+
* stale waiter or a late result left behind by a failed run silently re-executes its body.
|
|
3924
|
+
*/
|
|
3925
|
+
private resumeImplicit;
|
|
3926
|
+
private resumeRun;
|
|
3874
3927
|
/**
|
|
3875
3928
|
* The registration for an UNREGISTERED run, INHERITED from its nearest REMOTE ancestor — or
|
|
3876
3929
|
* `undefined` if it has none (the skew-protection error case in {@link resume}). Callers check the
|
|
@@ -4385,6 +4438,8 @@ declare class WorkflowEngine {
|
|
|
4385
4438
|
private completeStep;
|
|
4386
4439
|
/** Checkpoint a step that failed terminally, so the failure point is visible (not just the run). */
|
|
4387
4440
|
private failStep;
|
|
4441
|
+
/** Admission persists the wait atomically; never overwrite a cancellation after it returns. */
|
|
4442
|
+
private singletonWaitResult;
|
|
4388
4443
|
private execute;
|
|
4389
4444
|
/**
|
|
4390
4445
|
* Advance a remote (cross-SDK) workflow one turn: hand its history to the executor (which dispatches
|
|
@@ -4883,6 +4938,26 @@ declare class NonDeterminismError extends Error {
|
|
|
4883
4938
|
readonly seq: number;
|
|
4884
4939
|
constructor(runId: string, seq: number, expected: string, recorded: string);
|
|
4885
4940
|
}
|
|
4941
|
+
/**
|
|
4942
|
+
* Thrown AT THE CALL SITE when a workflow-ctx primitive (`ctx.startChild`, `ctx.child`, `ctx.step`,
|
|
4943
|
+
* `ctx.sleep`, `ctx.sideEffect`, … — or a `MyWorkflow.start()`/`.execute()` static, which route to
|
|
4944
|
+
* them through the ambient ctx) is called from INSIDE the body of a checkpointed step
|
|
4945
|
+
* (`ctx.localStep`, `ctx.transaction`, `ctx.sideEffect`, `ctx.now`, `ctx.task`'s dispatch).
|
|
4946
|
+
*
|
|
4947
|
+
* A step body runs once and is replayed from its checkpoint WITHOUT re-running, so a primitive it
|
|
4948
|
+
* called claims a journal position on the first run that no replay ever claims again: every later
|
|
4949
|
+
* position shifts and the run dies on its next replay with a `NonDeterminismError` far from the
|
|
4950
|
+
* cause. Failing here instead names the real mistake. Move the call out of the step body (into the
|
|
4951
|
+
* workflow body), or — from a dispatched `@Step` handler — start a top-level run.
|
|
4952
|
+
*
|
|
4953
|
+
* A `FatalError` (code `nested_workflow_call`): the step is not retried, the run fails.
|
|
4954
|
+
*/
|
|
4955
|
+
declare class NestedWorkflowCallError extends FatalError {
|
|
4956
|
+
readonly runId: string;
|
|
4957
|
+
readonly primitive: string;
|
|
4958
|
+
readonly step: string;
|
|
4959
|
+
constructor(runId: string, primitive: string, step: string);
|
|
4960
|
+
}
|
|
4886
4961
|
/**
|
|
4887
4962
|
* Thrown by `ctx.all` when one or more parallel child workflows fail. Carries the per-item failures
|
|
4888
4963
|
* (input index, child run id, error message) and presents an aggregate message summarizing the count
|
|
@@ -5266,6 +5341,8 @@ interface PayloadCodec {
|
|
|
5266
5341
|
declare class CodecStateStore implements StateStore {
|
|
5267
5342
|
private readonly inner;
|
|
5268
5343
|
private readonly codec;
|
|
5344
|
+
/** Atomic claims touch only searchable metadata and bypass payload encoding. */
|
|
5345
|
+
readonly tryAdmitSingleton?: (runId: string, tag: string, workflow: string, limit: number, retryWakeAt?: number) => Promise<boolean>;
|
|
5269
5346
|
/**
|
|
5270
5347
|
* Forwarded verbatim — a facet cell counts `status`/`origin`, neither of which the codec touches
|
|
5271
5348
|
* (it encodes payloads: input/output/error). Bound as a PROPERTY, and only when the inner store
|
|
@@ -5734,8 +5811,9 @@ declare class InMemoryStateStore implements StateStore {
|
|
|
5734
5811
|
private key;
|
|
5735
5812
|
/** Drop then re-add a run's normalized attribute rows so the index tracks its current attributes. */
|
|
5736
5813
|
private reindexAttributes;
|
|
5814
|
+
tryAdmitSingleton(runId: string, tag: string, workflow: string, limit: number, retryWakeAt?: number): Promise<boolean>;
|
|
5737
5815
|
createRun(run: WorkflowRun): Promise<void>;
|
|
5738
|
-
updateRun(runId: string,
|
|
5816
|
+
updateRun(runId: string, inputPatch: Partial<WorkflowRun>): Promise<void>;
|
|
5739
5817
|
getRun(runId: string): Promise<WorkflowRun | null>;
|
|
5740
5818
|
deleteRun(runId: string): Promise<void>;
|
|
5741
5819
|
deleteRuns(runIds: string[]): Promise<void>;
|
|
@@ -5829,4 +5907,18 @@ declare class InMemoryTransport implements Transport, ControlPlane {
|
|
|
5829
5907
|
onControl(handler: (msg: ControlMessage) => void): void;
|
|
5830
5908
|
}
|
|
5831
5909
|
|
|
5832
|
-
|
|
5910
|
+
/** Reserved engine metadata: a durable singleton slot, independent of the execution lease. */
|
|
5911
|
+
declare const SINGLETON_ADMITTED_TAG = "durable:singleton:admitted";
|
|
5912
|
+
declare const SINGLETON_ACTIVE_STATUSES: RunStatus[];
|
|
5913
|
+
/** Call only inside a store's atomic admission transaction/critical section. */
|
|
5914
|
+
declare function singletonAdmissionTags(runs: WorkflowRun[], runId: string, tag: string, workflow: string, limit: number): string[] | null;
|
|
5915
|
+
/** Terminal runs release admission, including when later resumed directly rather than requeued. */
|
|
5916
|
+
declare function clearTerminalSingletonAdmission(runId: string, patch: Partial<WorkflowRun>, getRun: (id: string) => Promise<WorkflowRun | null>): Promise<Partial<WorkflowRun>>;
|
|
5917
|
+
/** Persist denial while admission locks are held; a cancelling/terminal run must never revive. */
|
|
5918
|
+
declare function singletonAdmissionDenialPatch(runs: WorkflowRun[], runId: string, tag: string, workflow: string, retryWakeAt?: number): {
|
|
5919
|
+
status: 'suspended';
|
|
5920
|
+
wakeAt: number;
|
|
5921
|
+
updatedAt: Date;
|
|
5922
|
+
} | undefined;
|
|
5923
|
+
|
|
5924
|
+
export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, CodecStateStore, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, STATE_STORE, STATE_STORE_CANONICAL, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepScope, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, announcementsOf, applyAttributeQuery, assertConcurrency, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, parseDuration, partitionOfToken, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduledRunId, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, useDurableExecution, warn, workflowName };
|
package/dist/index.d.ts
CHANGED
|
@@ -919,6 +919,17 @@ interface StateStore {
|
|
|
919
919
|
* module's `autoSchema` is on. Optional: stores that need no setup (in-memory) omit it.
|
|
920
920
|
*/
|
|
921
921
|
ensureSchema?(): Promise<void>;
|
|
922
|
+
/**
|
|
923
|
+
* Atomically read active runs sharing workflow/tag in this store's read scope, preserve durable
|
|
924
|
+
* admitted holders, and claim a free slot for an eligible FIFO waiter. The claim persists the
|
|
925
|
+
* reserved SINGLETON_ADMITTED_TAG in tags. Execution lease expiry never releases a slot; terminal
|
|
926
|
+
* status does. Optional for general stores, required when using singleton workflows. Implement
|
|
927
|
+
* with a database transaction that serializes competing claims BEFORE reading; list/update alone
|
|
928
|
+
* is unsafe across engine instances. If retryWakeAt is supplied, denial must atomically suspend
|
|
929
|
+
* the still-active candidate with that wakeAt while the same locks are held. Never overwrite a
|
|
930
|
+
* cancelling or terminal run on denial. Return false for missing/terminal/out-of-scope runs.
|
|
931
|
+
*/
|
|
932
|
+
tryAdmitSingleton?(runId: string, tag: string, workflow: string, limit: number, retryWakeAt?: number): Promise<boolean>;
|
|
922
933
|
createRun(run: WorkflowRun): Promise<void>;
|
|
923
934
|
updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
|
|
924
935
|
getRun(runId: string): Promise<WorkflowRun | null>;
|
|
@@ -2505,6 +2516,32 @@ declare function runInWorkflowCtx<T>(ctx: WorkflowCtx, fn: () => T): T;
|
|
|
2505
2516
|
* ambient workflow context (by design — a handler is not the workflow body).
|
|
2506
2517
|
*/
|
|
2507
2518
|
declare function currentWorkflowCtx(): WorkflowCtx | undefined;
|
|
2519
|
+
/**
|
|
2520
|
+
* The ambient STEP scope: which workflow ctx's checkpointed step body (if any) is executing on this
|
|
2521
|
+
* async path. The engine installs it around every in-body step execution (`ctx.localStep`,
|
|
2522
|
+
* `ctx.transaction`, and everything built on them) so the ctx primitives can refuse to run from
|
|
2523
|
+
* inside a step body — see {@link NestedWorkflowCallError}. `owner` is the identity of the ctx whose
|
|
2524
|
+
* step is running, so a DIFFERENT run's body executed inline from a step (e.g. a step that signals a
|
|
2525
|
+
* run which resumes on this async path) is never mistaken for a nested call.
|
|
2526
|
+
*
|
|
2527
|
+
* Shared per process under a `Symbol.for` key, for the same duplicate-copy reason as the ctx storage.
|
|
2528
|
+
*/
|
|
2529
|
+
interface StepScope {
|
|
2530
|
+
readonly owner: object;
|
|
2531
|
+
readonly step: string;
|
|
2532
|
+
}
|
|
2533
|
+
/** Run `fn` as the body of step `step` of the ctx identified by `owner`. Engine-internal. */
|
|
2534
|
+
declare function runInStepScope<T>(owner: object, step: string, fn: () => T): T;
|
|
2535
|
+
/** The step body currently executing on this async path, or `undefined` outside one. */
|
|
2536
|
+
declare function currentStepScope(): StepScope | undefined;
|
|
2537
|
+
/**
|
|
2538
|
+
* Run `fn` with NO ambient workflow ctx and no step scope — for a dispatched `@Step` handler. A
|
|
2539
|
+
* handler is not the workflow body (on a remote worker it never sees one), but an in-process
|
|
2540
|
+
* transport invokes it on the body's async path, where the parent's ctx would otherwise leak in and
|
|
2541
|
+
* turn a handler's `MyWorkflow.start()` into a journal-corrupting `ctx.startChild` of a parent that
|
|
2542
|
+
* is already suspended. Clearing it makes in-process and remote handlers behave identically.
|
|
2543
|
+
*/
|
|
2544
|
+
declare function runOutsideWorkflowCtx<T>(fn: () => T): T;
|
|
2508
2545
|
|
|
2509
2546
|
/**
|
|
2510
2547
|
* Run `fn` with `logger` as the ambient step logger. Engine-internal: wraps every execution of a
|
|
@@ -3415,8 +3452,8 @@ interface StartOptions {
|
|
|
3415
3452
|
/**
|
|
3416
3453
|
* Serialize runs of a workflow that share a key — a durable, FIFO mutex (e.g. one pipeline per base).
|
|
3417
3454
|
* Excess runs are admitted in creation order, `limit` at a time; the rest wait (suspended) and retry
|
|
3418
|
-
* admission on a timer until a slot frees.
|
|
3419
|
-
*
|
|
3455
|
+
* admission on a timer until a slot frees. The store atomically reserves durable slots before
|
|
3456
|
+
* ordering unadmitted waiters by `(createdAt, id)`, so later starts cannot displace a holder.
|
|
3420
3457
|
*/
|
|
3421
3458
|
interface SingletonConfig {
|
|
3422
3459
|
/** Derive the serialization key from the workflow input. */
|
|
@@ -3427,7 +3464,7 @@ interface SingletonConfig {
|
|
|
3427
3464
|
* Max GATED (waiting-for-admission) runs allowed to queue behind the `limit` in-flight ones. When
|
|
3428
3465
|
* set, `start` rejects with {@link SingletonQueueFullError} once in-flight + gated reaches
|
|
3429
3466
|
* `limit + maxQueueDepth` — back-pressure against an unbounded same-key backlog. Omit for the
|
|
3430
|
-
* default unbounded queue. Counts
|
|
3467
|
+
* default unbounded queue. Counts pending/running/suspended/blocked/cancelling runs sharing the key.
|
|
3431
3468
|
*/
|
|
3432
3469
|
maxQueueDepth?: number;
|
|
3433
3470
|
}
|
|
@@ -3870,7 +3907,23 @@ declare class WorkflowEngine {
|
|
|
3870
3907
|
start<TInput>(workflow: string, input: TInput, runId: string, opts?: StartOptions): Promise<RunResult>;
|
|
3871
3908
|
/** Read a run's current persisted state (or null if unknown). A thin pass-through to the store. */
|
|
3872
3909
|
getRun(runId: string): Promise<WorkflowRun | null>;
|
|
3910
|
+
/**
|
|
3911
|
+
* Re-execute a run's body (replaying its checkpoints). This is the EXPLICIT entry point: besides
|
|
3912
|
+
* driving a live run, it re-drives a `failed` run — the manual retry (prefer {@link requeue}, which
|
|
3913
|
+
* also resets the failure state so replay re-attempts the failed parts). Completed / cancelled /
|
|
3914
|
+
* dead runs are never re-executed. The engine's own implicit wake-ups (signals, step results,
|
|
3915
|
+
* timers, redelivered dispatches) go through {@link resumeImplicit}, which treats `failed` as
|
|
3916
|
+
* terminal too.
|
|
3917
|
+
*/
|
|
3873
3918
|
resume(runId: string): Promise<RunResult>;
|
|
3919
|
+
/**
|
|
3920
|
+
* {@link resume} for every IMPLICIT wake-up — a delivered signal/child completion, a late step
|
|
3921
|
+
* result, a due timer, a redelivered dispatch, a queue-slot wake. A `failed` run is terminal to
|
|
3922
|
+
* these: only an explicit retry ({@link requeue} / {@link resume}) may re-drive it. Otherwise a
|
|
3923
|
+
* stale waiter or a late result left behind by a failed run silently re-executes its body.
|
|
3924
|
+
*/
|
|
3925
|
+
private resumeImplicit;
|
|
3926
|
+
private resumeRun;
|
|
3874
3927
|
/**
|
|
3875
3928
|
* The registration for an UNREGISTERED run, INHERITED from its nearest REMOTE ancestor — or
|
|
3876
3929
|
* `undefined` if it has none (the skew-protection error case in {@link resume}). Callers check the
|
|
@@ -4385,6 +4438,8 @@ declare class WorkflowEngine {
|
|
|
4385
4438
|
private completeStep;
|
|
4386
4439
|
/** Checkpoint a step that failed terminally, so the failure point is visible (not just the run). */
|
|
4387
4440
|
private failStep;
|
|
4441
|
+
/** Admission persists the wait atomically; never overwrite a cancellation after it returns. */
|
|
4442
|
+
private singletonWaitResult;
|
|
4388
4443
|
private execute;
|
|
4389
4444
|
/**
|
|
4390
4445
|
* Advance a remote (cross-SDK) workflow one turn: hand its history to the executor (which dispatches
|
|
@@ -4883,6 +4938,26 @@ declare class NonDeterminismError extends Error {
|
|
|
4883
4938
|
readonly seq: number;
|
|
4884
4939
|
constructor(runId: string, seq: number, expected: string, recorded: string);
|
|
4885
4940
|
}
|
|
4941
|
+
/**
|
|
4942
|
+
* Thrown AT THE CALL SITE when a workflow-ctx primitive (`ctx.startChild`, `ctx.child`, `ctx.step`,
|
|
4943
|
+
* `ctx.sleep`, `ctx.sideEffect`, … — or a `MyWorkflow.start()`/`.execute()` static, which route to
|
|
4944
|
+
* them through the ambient ctx) is called from INSIDE the body of a checkpointed step
|
|
4945
|
+
* (`ctx.localStep`, `ctx.transaction`, `ctx.sideEffect`, `ctx.now`, `ctx.task`'s dispatch).
|
|
4946
|
+
*
|
|
4947
|
+
* A step body runs once and is replayed from its checkpoint WITHOUT re-running, so a primitive it
|
|
4948
|
+
* called claims a journal position on the first run that no replay ever claims again: every later
|
|
4949
|
+
* position shifts and the run dies on its next replay with a `NonDeterminismError` far from the
|
|
4950
|
+
* cause. Failing here instead names the real mistake. Move the call out of the step body (into the
|
|
4951
|
+
* workflow body), or — from a dispatched `@Step` handler — start a top-level run.
|
|
4952
|
+
*
|
|
4953
|
+
* A `FatalError` (code `nested_workflow_call`): the step is not retried, the run fails.
|
|
4954
|
+
*/
|
|
4955
|
+
declare class NestedWorkflowCallError extends FatalError {
|
|
4956
|
+
readonly runId: string;
|
|
4957
|
+
readonly primitive: string;
|
|
4958
|
+
readonly step: string;
|
|
4959
|
+
constructor(runId: string, primitive: string, step: string);
|
|
4960
|
+
}
|
|
4886
4961
|
/**
|
|
4887
4962
|
* Thrown by `ctx.all` when one or more parallel child workflows fail. Carries the per-item failures
|
|
4888
4963
|
* (input index, child run id, error message) and presents an aggregate message summarizing the count
|
|
@@ -5266,6 +5341,8 @@ interface PayloadCodec {
|
|
|
5266
5341
|
declare class CodecStateStore implements StateStore {
|
|
5267
5342
|
private readonly inner;
|
|
5268
5343
|
private readonly codec;
|
|
5344
|
+
/** Atomic claims touch only searchable metadata and bypass payload encoding. */
|
|
5345
|
+
readonly tryAdmitSingleton?: (runId: string, tag: string, workflow: string, limit: number, retryWakeAt?: number) => Promise<boolean>;
|
|
5269
5346
|
/**
|
|
5270
5347
|
* Forwarded verbatim — a facet cell counts `status`/`origin`, neither of which the codec touches
|
|
5271
5348
|
* (it encodes payloads: input/output/error). Bound as a PROPERTY, and only when the inner store
|
|
@@ -5734,8 +5811,9 @@ declare class InMemoryStateStore implements StateStore {
|
|
|
5734
5811
|
private key;
|
|
5735
5812
|
/** Drop then re-add a run's normalized attribute rows so the index tracks its current attributes. */
|
|
5736
5813
|
private reindexAttributes;
|
|
5814
|
+
tryAdmitSingleton(runId: string, tag: string, workflow: string, limit: number, retryWakeAt?: number): Promise<boolean>;
|
|
5737
5815
|
createRun(run: WorkflowRun): Promise<void>;
|
|
5738
|
-
updateRun(runId: string,
|
|
5816
|
+
updateRun(runId: string, inputPatch: Partial<WorkflowRun>): Promise<void>;
|
|
5739
5817
|
getRun(runId: string): Promise<WorkflowRun | null>;
|
|
5740
5818
|
deleteRun(runId: string): Promise<void>;
|
|
5741
5819
|
deleteRuns(runIds: string[]): Promise<void>;
|
|
@@ -5829,4 +5907,18 @@ declare class InMemoryTransport implements Transport, ControlPlane {
|
|
|
5829
5907
|
onControl(handler: (msg: ControlMessage) => void): void;
|
|
5830
5908
|
}
|
|
5831
5909
|
|
|
5832
|
-
|
|
5910
|
+
/** Reserved engine metadata: a durable singleton slot, independent of the execution lease. */
|
|
5911
|
+
declare const SINGLETON_ADMITTED_TAG = "durable:singleton:admitted";
|
|
5912
|
+
declare const SINGLETON_ACTIVE_STATUSES: RunStatus[];
|
|
5913
|
+
/** Call only inside a store's atomic admission transaction/critical section. */
|
|
5914
|
+
declare function singletonAdmissionTags(runs: WorkflowRun[], runId: string, tag: string, workflow: string, limit: number): string[] | null;
|
|
5915
|
+
/** Terminal runs release admission, including when later resumed directly rather than requeued. */
|
|
5916
|
+
declare function clearTerminalSingletonAdmission(runId: string, patch: Partial<WorkflowRun>, getRun: (id: string) => Promise<WorkflowRun | null>): Promise<Partial<WorkflowRun>>;
|
|
5917
|
+
/** Persist denial while admission locks are held; a cancelling/terminal run must never revive. */
|
|
5918
|
+
declare function singletonAdmissionDenialPatch(runs: WorkflowRun[], runId: string, tag: string, workflow: string, retryWakeAt?: number): {
|
|
5919
|
+
status: 'suspended';
|
|
5920
|
+
wakeAt: number;
|
|
5921
|
+
updatedAt: Date;
|
|
5922
|
+
} | undefined;
|
|
5923
|
+
|
|
5924
|
+
export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, CodecStateStore, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, STATE_STORE, STATE_STORE_CANONICAL, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepScope, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, announcementsOf, applyAttributeQuery, assertConcurrency, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, parseDuration, partitionOfToken, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduledRunId, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, useDurableExecution, warn, workflowName };
|