@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 +136 -26
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +51 -3
- package/dist/index.d.ts +51 -3
- package/dist/index.js +135 -26
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -902,7 +902,8 @@ type RunStatus =
|
|
|
902
902
|
* are actually published (a legacy/pre-handshake fleet skips the guard, design §7.7).
|
|
903
903
|
*/
|
|
904
904
|
| 'blocked' | 'completed' | 'failed' | 'cancelled'
|
|
905
|
-
/** Dead-letter: recovery gave up after `maxRecoveryAttempts` (a poison pill)
|
|
905
|
+
/** Dead-letter: recovery gave up after `maxRecoveryAttempts` (a poison pill), or no instance has
|
|
906
|
+
* the run's workflow version registered past `unregisteredWorkflowGraceMs`. Terminal; inspect it. */
|
|
906
907
|
| 'dead';
|
|
907
908
|
/** One execution of a workflow. The unit of durability and the unit shown in the dashboard. */
|
|
908
909
|
interface WorkflowRun {
|
|
@@ -4478,6 +4479,17 @@ interface WorkflowEngineDeps {
|
|
|
4478
4479
|
* Omit for unlimited (the default — recovery always retries).
|
|
4479
4480
|
*/
|
|
4480
4481
|
maxRecoveryAttempts?: number | undefined;
|
|
4482
|
+
/**
|
|
4483
|
+
* How long (ms) a run may stay due while NO instance can resume it because its workflow version is
|
|
4484
|
+
* not registered anywhere, before it is moved to `dead` (code `workflow_not_registered`). A rolling
|
|
4485
|
+
* deploy skips such a run on purpose (skew protection): the pod still on the prior version picks it
|
|
4486
|
+
* up within seconds. A run that stays unresumable far past that — its workflow was renamed or
|
|
4487
|
+
* deleted — would otherwise be retried and logged on every tick forever. The clock starts when the
|
|
4488
|
+
* run became due (its `wakeAt` for a parked run, its last update otherwise), so a long sleep is not
|
|
4489
|
+
* counted. Default 24h; `0` disables (skip forever). A non-finite or negative value falls back to
|
|
4490
|
+
* the default.
|
|
4491
|
+
*/
|
|
4492
|
+
unregisteredWorkflowGraceMs?: number | undefined;
|
|
4481
4493
|
/**
|
|
4482
4494
|
* Opt-in liveness deadline (ms) for a remote workflow `advance`. If the worker neither returns a
|
|
4483
4495
|
* decision NOR sends a run-scoped {@link Heartbeat} within this window, the engine presumes it dead:
|
|
@@ -4629,6 +4641,13 @@ interface ListStalledRunsOptions {
|
|
|
4629
4641
|
/** Evaluate as of this clock time. Defaults to the engine clock. */
|
|
4630
4642
|
now?: number | undefined;
|
|
4631
4643
|
}
|
|
4644
|
+
/**
|
|
4645
|
+
* Thrown by {@link WorkflowEngine.resume} when nothing registered here (nor an inherited or
|
|
4646
|
+
* convention route) can run the run's pinned `workflow@version`.
|
|
4647
|
+
*/
|
|
4648
|
+
declare class WorkflowNotRegistered extends Error {
|
|
4649
|
+
constructor(workflow: string, version: string);
|
|
4650
|
+
}
|
|
4632
4651
|
/**
|
|
4633
4652
|
* The orchestrator. Owns workflow state and replays runs deterministically: each step's
|
|
4634
4653
|
* result is checkpointed, so on resume a completed step returns its saved output instead of
|
|
@@ -4651,6 +4670,7 @@ declare class WorkflowEngine {
|
|
|
4651
4670
|
*/
|
|
4652
4671
|
private readonly ownLeaseCutoffMs;
|
|
4653
4672
|
private readonly maxRecoveryAttempts?;
|
|
4673
|
+
private readonly unregisteredWorkflowGraceMs;
|
|
4654
4674
|
private readonly remoteAdvanceSilenceMs?;
|
|
4655
4675
|
private readonly reconcileMs;
|
|
4656
4676
|
private readonly timerBatchSize;
|
|
@@ -5372,6 +5392,33 @@ declare class WorkflowEngine {
|
|
|
5372
5392
|
* result to skip the resume, or `undefined` to proceed.
|
|
5373
5393
|
*/
|
|
5374
5394
|
private countRecovery;
|
|
5395
|
+
/** Tell everyone a run was just written `dead`: events, dead-letter routing, a waiting parent. */
|
|
5396
|
+
private announceDead;
|
|
5397
|
+
/** The synchronous half of {@link canResolveWorkflow}: callers check it first, so a registered run
|
|
5398
|
+
* pays no await (same rule as {@link resume}). */
|
|
5399
|
+
private isRegisteredHere;
|
|
5400
|
+
/**
|
|
5401
|
+
* Whether this instance can run `run`'s pinned `workflow@version`: registered here, inherited from a
|
|
5402
|
+
* remote ancestor, or routed by convention to a live worker group (the lookup {@link resume} does).
|
|
5403
|
+
*/
|
|
5404
|
+
private canResolveWorkflow;
|
|
5405
|
+
/**
|
|
5406
|
+
* A run whose lease this instance holds but whose `workflow@version` nothing here can run (see
|
|
5407
|
+
* {@link WorkflowNotRegistered}). Within {@link unregisteredWorkflowGraceMs} of becoming due it is a
|
|
5408
|
+
* rolling deploy's skew: the lease is released at once so the pod that still has the version takes
|
|
5409
|
+
* the run now, not after the lease expires. Past it, the workflow is gone from the whole fleet (a
|
|
5410
|
+
* capable pod would have taken the run long ago): dead-letter it.
|
|
5411
|
+
*
|
|
5412
|
+
* The age is read off `updatedAt` / `wakeAt`, so every path that would touch either (a recovery
|
|
5413
|
+
* count, a re-pend, a hand-off's lease-long `wakeAt`) must call this BEFORE writing — otherwise an
|
|
5414
|
+
* orphan never ages.
|
|
5415
|
+
*
|
|
5416
|
+
* Returns the `dead` result, `null` when the run left its status meanwhile (a lease-free
|
|
5417
|
+
* `cancel()`: settled, not ours to touch), or `undefined` when it was left for later.
|
|
5418
|
+
*/
|
|
5419
|
+
private settleUnregistered;
|
|
5420
|
+
/** Log a run skipped for an unregistered workflow — still there, still not progressing. */
|
|
5421
|
+
private logUnregisteredSkip;
|
|
5375
5422
|
/**
|
|
5376
5423
|
* Resume every suspended run whose durable timer is due. Call periodically (a poller) and on
|
|
5377
5424
|
* boot. A run still not due re-suspends cheaply without running new work.
|
|
@@ -5473,7 +5520,8 @@ declare class WorkflowEngine {
|
|
|
5473
5520
|
* Resume each run only if this instance can acquire its recovery lease — so when several
|
|
5474
5521
|
* replicas recover or poll at once, each run is picked up by exactly one of them.
|
|
5475
5522
|
*
|
|
5476
|
-
* A run this instance cannot resume is SKIPPED, not allowed to abort the batch
|
|
5523
|
+
* A run this instance cannot resume is SKIPPED, not allowed to abort the batch (a run whose workflow
|
|
5524
|
+
* stays registered nowhere past `unregisteredWorkflowGraceMs` is dead-lettered instead). The canonical
|
|
5477
5525
|
* case is skew protection: mid-rolling-deploy a pod leases a run whose workflow it does not have
|
|
5478
5526
|
* and `resume` throws by design — but the rest of the batch is runs it can drive perfectly well,
|
|
5479
5527
|
* and every caller here is a recovery sweep. Letting the first such run end the loop means one
|
|
@@ -7856,4 +7904,4 @@ declare function singletonAdmissionDenialPatch(runs: WorkflowRun[], runId: strin
|
|
|
7856
7904
|
updatedAt: Date;
|
|
7857
7905
|
} | undefined;
|
|
7858
7906
|
|
|
7859
|
-
export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, type BufferedSignalRow, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CORE_ORIGIN, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type CodecStateStoreOptions, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DEFAULT_STALLED_AFTER_MS, 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, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, type FindStalledRunsOptions, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryRunQueue, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OwnedLeaseReclaim, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, REMOTE_EVENT, RUN_HISTORY_FIXTURE_VERSION, 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 RunConsumerOptions, type RunDetail, type RunDetailOptions, type RunDispatch, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunQueueOptions, 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, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SchemaIssue, type SchemaValidationCode, SchemaValidationError, type SearchAttributes, type SearchAttributesSchema, type Settled, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StalePendingStep, type StalledRunInfo, 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 StepSettlement, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type TenantTokenSource, type TenantVerifier, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, type VerifiedTenant, 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, aggregatesCheckpoints, announcementsOf, applyAttributeQuery, assertConcurrency, assertRoutes, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, getRunsByIds, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, hmacTenantVerifier, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isRemoteEvent, isWorkflowControlFlowSignal, legacySingletonHolders, listSignalWaitersOfRuns, liveHandoff, log, markRemoteEvent, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, queryCheckpointsOf, readRunsByIds, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, resolveTenantToken, resolveWireTenant, retiredHandoffName, routeFor, runDetailEtag, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, signTenantToken, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantGroup, useDurableExecution, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };
|
|
7907
|
+
export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, type BufferedSignalRow, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CORE_ORIGIN, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type CodecStateStoreOptions, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DEFAULT_STALLED_AFTER_MS, 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, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, type FindStalledRunsOptions, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryRunQueue, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OwnedLeaseReclaim, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, REMOTE_EVENT, RUN_HISTORY_FIXTURE_VERSION, 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 RunConsumerOptions, type RunDetail, type RunDetailOptions, type RunDispatch, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunQueueOptions, 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, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SchemaIssue, type SchemaValidationCode, SchemaValidationError, type SearchAttributes, type SearchAttributesSchema, type Settled, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StalePendingStep, type StalledRunInfo, 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 StepSettlement, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type TenantTokenSource, type TenantVerifier, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, type VerifiedTenant, 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, WorkflowNotRegistered, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, aggregatesCheckpoints, announcementsOf, applyAttributeQuery, assertConcurrency, assertRoutes, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, getRunsByIds, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, hmacTenantVerifier, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isRemoteEvent, isWorkflowControlFlowSignal, legacySingletonHolders, listSignalWaitersOfRuns, liveHandoff, log, markRemoteEvent, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, queryCheckpointsOf, readRunsByIds, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, resolveTenantToken, resolveWireTenant, retiredHandoffName, routeFor, runDetailEtag, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, signTenantToken, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantGroup, useDurableExecution, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };
|
package/dist/index.d.ts
CHANGED
|
@@ -902,7 +902,8 @@ type RunStatus =
|
|
|
902
902
|
* are actually published (a legacy/pre-handshake fleet skips the guard, design §7.7).
|
|
903
903
|
*/
|
|
904
904
|
| 'blocked' | 'completed' | 'failed' | 'cancelled'
|
|
905
|
-
/** Dead-letter: recovery gave up after `maxRecoveryAttempts` (a poison pill)
|
|
905
|
+
/** Dead-letter: recovery gave up after `maxRecoveryAttempts` (a poison pill), or no instance has
|
|
906
|
+
* the run's workflow version registered past `unregisteredWorkflowGraceMs`. Terminal; inspect it. */
|
|
906
907
|
| 'dead';
|
|
907
908
|
/** One execution of a workflow. The unit of durability and the unit shown in the dashboard. */
|
|
908
909
|
interface WorkflowRun {
|
|
@@ -4478,6 +4479,17 @@ interface WorkflowEngineDeps {
|
|
|
4478
4479
|
* Omit for unlimited (the default — recovery always retries).
|
|
4479
4480
|
*/
|
|
4480
4481
|
maxRecoveryAttempts?: number | undefined;
|
|
4482
|
+
/**
|
|
4483
|
+
* How long (ms) a run may stay due while NO instance can resume it because its workflow version is
|
|
4484
|
+
* not registered anywhere, before it is moved to `dead` (code `workflow_not_registered`). A rolling
|
|
4485
|
+
* deploy skips such a run on purpose (skew protection): the pod still on the prior version picks it
|
|
4486
|
+
* up within seconds. A run that stays unresumable far past that — its workflow was renamed or
|
|
4487
|
+
* deleted — would otherwise be retried and logged on every tick forever. The clock starts when the
|
|
4488
|
+
* run became due (its `wakeAt` for a parked run, its last update otherwise), so a long sleep is not
|
|
4489
|
+
* counted. Default 24h; `0` disables (skip forever). A non-finite or negative value falls back to
|
|
4490
|
+
* the default.
|
|
4491
|
+
*/
|
|
4492
|
+
unregisteredWorkflowGraceMs?: number | undefined;
|
|
4481
4493
|
/**
|
|
4482
4494
|
* Opt-in liveness deadline (ms) for a remote workflow `advance`. If the worker neither returns a
|
|
4483
4495
|
* decision NOR sends a run-scoped {@link Heartbeat} within this window, the engine presumes it dead:
|
|
@@ -4629,6 +4641,13 @@ interface ListStalledRunsOptions {
|
|
|
4629
4641
|
/** Evaluate as of this clock time. Defaults to the engine clock. */
|
|
4630
4642
|
now?: number | undefined;
|
|
4631
4643
|
}
|
|
4644
|
+
/**
|
|
4645
|
+
* Thrown by {@link WorkflowEngine.resume} when nothing registered here (nor an inherited or
|
|
4646
|
+
* convention route) can run the run's pinned `workflow@version`.
|
|
4647
|
+
*/
|
|
4648
|
+
declare class WorkflowNotRegistered extends Error {
|
|
4649
|
+
constructor(workflow: string, version: string);
|
|
4650
|
+
}
|
|
4632
4651
|
/**
|
|
4633
4652
|
* The orchestrator. Owns workflow state and replays runs deterministically: each step's
|
|
4634
4653
|
* result is checkpointed, so on resume a completed step returns its saved output instead of
|
|
@@ -4651,6 +4670,7 @@ declare class WorkflowEngine {
|
|
|
4651
4670
|
*/
|
|
4652
4671
|
private readonly ownLeaseCutoffMs;
|
|
4653
4672
|
private readonly maxRecoveryAttempts?;
|
|
4673
|
+
private readonly unregisteredWorkflowGraceMs;
|
|
4654
4674
|
private readonly remoteAdvanceSilenceMs?;
|
|
4655
4675
|
private readonly reconcileMs;
|
|
4656
4676
|
private readonly timerBatchSize;
|
|
@@ -5372,6 +5392,33 @@ declare class WorkflowEngine {
|
|
|
5372
5392
|
* result to skip the resume, or `undefined` to proceed.
|
|
5373
5393
|
*/
|
|
5374
5394
|
private countRecovery;
|
|
5395
|
+
/** Tell everyone a run was just written `dead`: events, dead-letter routing, a waiting parent. */
|
|
5396
|
+
private announceDead;
|
|
5397
|
+
/** The synchronous half of {@link canResolveWorkflow}: callers check it first, so a registered run
|
|
5398
|
+
* pays no await (same rule as {@link resume}). */
|
|
5399
|
+
private isRegisteredHere;
|
|
5400
|
+
/**
|
|
5401
|
+
* Whether this instance can run `run`'s pinned `workflow@version`: registered here, inherited from a
|
|
5402
|
+
* remote ancestor, or routed by convention to a live worker group (the lookup {@link resume} does).
|
|
5403
|
+
*/
|
|
5404
|
+
private canResolveWorkflow;
|
|
5405
|
+
/**
|
|
5406
|
+
* A run whose lease this instance holds but whose `workflow@version` nothing here can run (see
|
|
5407
|
+
* {@link WorkflowNotRegistered}). Within {@link unregisteredWorkflowGraceMs} of becoming due it is a
|
|
5408
|
+
* rolling deploy's skew: the lease is released at once so the pod that still has the version takes
|
|
5409
|
+
* the run now, not after the lease expires. Past it, the workflow is gone from the whole fleet (a
|
|
5410
|
+
* capable pod would have taken the run long ago): dead-letter it.
|
|
5411
|
+
*
|
|
5412
|
+
* The age is read off `updatedAt` / `wakeAt`, so every path that would touch either (a recovery
|
|
5413
|
+
* count, a re-pend, a hand-off's lease-long `wakeAt`) must call this BEFORE writing — otherwise an
|
|
5414
|
+
* orphan never ages.
|
|
5415
|
+
*
|
|
5416
|
+
* Returns the `dead` result, `null` when the run left its status meanwhile (a lease-free
|
|
5417
|
+
* `cancel()`: settled, not ours to touch), or `undefined` when it was left for later.
|
|
5418
|
+
*/
|
|
5419
|
+
private settleUnregistered;
|
|
5420
|
+
/** Log a run skipped for an unregistered workflow — still there, still not progressing. */
|
|
5421
|
+
private logUnregisteredSkip;
|
|
5375
5422
|
/**
|
|
5376
5423
|
* Resume every suspended run whose durable timer is due. Call periodically (a poller) and on
|
|
5377
5424
|
* boot. A run still not due re-suspends cheaply without running new work.
|
|
@@ -5473,7 +5520,8 @@ declare class WorkflowEngine {
|
|
|
5473
5520
|
* Resume each run only if this instance can acquire its recovery lease — so when several
|
|
5474
5521
|
* replicas recover or poll at once, each run is picked up by exactly one of them.
|
|
5475
5522
|
*
|
|
5476
|
-
* A run this instance cannot resume is SKIPPED, not allowed to abort the batch
|
|
5523
|
+
* A run this instance cannot resume is SKIPPED, not allowed to abort the batch (a run whose workflow
|
|
5524
|
+
* stays registered nowhere past `unregisteredWorkflowGraceMs` is dead-lettered instead). The canonical
|
|
5477
5525
|
* case is skew protection: mid-rolling-deploy a pod leases a run whose workflow it does not have
|
|
5478
5526
|
* and `resume` throws by design — but the rest of the batch is runs it can drive perfectly well,
|
|
5479
5527
|
* and every caller here is a recovery sweep. Letting the first such run end the loop means one
|
|
@@ -7856,4 +7904,4 @@ declare function singletonAdmissionDenialPatch(runs: WorkflowRun[], runId: strin
|
|
|
7856
7904
|
updatedAt: Date;
|
|
7857
7905
|
} | undefined;
|
|
7858
7906
|
|
|
7859
|
-
export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, type BufferedSignalRow, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CORE_ORIGIN, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type CodecStateStoreOptions, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DEFAULT_STALLED_AFTER_MS, 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, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, type FindStalledRunsOptions, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryRunQueue, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OwnedLeaseReclaim, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, REMOTE_EVENT, RUN_HISTORY_FIXTURE_VERSION, 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 RunConsumerOptions, type RunDetail, type RunDetailOptions, type RunDispatch, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunQueueOptions, 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, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SchemaIssue, type SchemaValidationCode, SchemaValidationError, type SearchAttributes, type SearchAttributesSchema, type Settled, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StalePendingStep, type StalledRunInfo, 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 StepSettlement, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type TenantTokenSource, type TenantVerifier, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, type VerifiedTenant, 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, aggregatesCheckpoints, announcementsOf, applyAttributeQuery, assertConcurrency, assertRoutes, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, getRunsByIds, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, hmacTenantVerifier, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isRemoteEvent, isWorkflowControlFlowSignal, legacySingletonHolders, listSignalWaitersOfRuns, liveHandoff, log, markRemoteEvent, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, queryCheckpointsOf, readRunsByIds, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, resolveTenantToken, resolveWireTenant, retiredHandoffName, routeFor, runDetailEtag, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, signTenantToken, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantGroup, useDurableExecution, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };
|
|
7907
|
+
export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, type BufferedSignalRow, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CORE_ORIGIN, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type CodecStateStoreOptions, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DEFAULT_STALLED_AFTER_MS, 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, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, type FindStalledRunsOptions, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryRunQueue, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OwnedLeaseReclaim, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, REMOTE_EVENT, RUN_HISTORY_FIXTURE_VERSION, 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 RunConsumerOptions, type RunDetail, type RunDetailOptions, type RunDispatch, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunQueueOptions, 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, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SchemaIssue, type SchemaValidationCode, SchemaValidationError, type SearchAttributes, type SearchAttributesSchema, type Settled, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StalePendingStep, type StalledRunInfo, 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 StepSettlement, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type TenantTokenSource, type TenantVerifier, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, type VerifiedTenant, 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, WorkflowNotRegistered, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, aggregatesCheckpoints, announcementsOf, applyAttributeQuery, assertConcurrency, assertRoutes, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, getRunsByIds, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, hmacTenantVerifier, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isRemoteEvent, isWorkflowControlFlowSignal, legacySingletonHolders, listSignalWaitersOfRuns, liveHandoff, log, markRemoteEvent, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, queryCheckpointsOf, readRunsByIds, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, resolveTenantToken, resolveWireTenant, retiredHandoffName, routeFor, runDetailEtag, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, signTenantToken, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantGroup, useDurableExecution, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };
|
package/dist/index.js
CHANGED
|
@@ -4949,6 +4949,22 @@ var NamespaceMismatch = class NamespaceMismatch2 extends Error {
|
|
|
4949
4949
|
super("namespace-mismatch");
|
|
4950
4950
|
}
|
|
4951
4951
|
};
|
|
4952
|
+
var WorkflowNotRegistered = class extends Error {
|
|
4953
|
+
static {
|
|
4954
|
+
__name(this, "WorkflowNotRegistered");
|
|
4955
|
+
}
|
|
4956
|
+
constructor(workflow, version) {
|
|
4957
|
+
super(`workflow ${workflow}@${version} is not registered \u2014 keep the prior version deployed so in-flight runs can drain (skew protection)`);
|
|
4958
|
+
this.name = "WorkflowNotRegistered";
|
|
4959
|
+
}
|
|
4960
|
+
};
|
|
4961
|
+
var UNREGISTERED_DEAD_LETTER_FROM = [
|
|
4962
|
+
"pending",
|
|
4963
|
+
"running",
|
|
4964
|
+
"suspended",
|
|
4965
|
+
"cancelling",
|
|
4966
|
+
"blocked"
|
|
4967
|
+
];
|
|
4952
4968
|
var WorkflowEngine = class {
|
|
4953
4969
|
static {
|
|
4954
4970
|
__name(this, "WorkflowEngine");
|
|
@@ -4968,6 +4984,7 @@ var WorkflowEngine = class {
|
|
|
4968
4984
|
*/
|
|
4969
4985
|
ownLeaseCutoffMs;
|
|
4970
4986
|
maxRecoveryAttempts;
|
|
4987
|
+
unregisteredWorkflowGraceMs;
|
|
4971
4988
|
remoteAdvanceSilenceMs;
|
|
4972
4989
|
reconcileMs;
|
|
4973
4990
|
timerBatchSize;
|
|
@@ -5154,6 +5171,8 @@ var WorkflowEngine = class {
|
|
|
5154
5171
|
this.leaseMs = deps.leaseMs ?? 3e4;
|
|
5155
5172
|
this.ownLeaseCutoffMs = this.clock() + this.leaseMs;
|
|
5156
5173
|
this.maxRecoveryAttempts = deps.maxRecoveryAttempts;
|
|
5174
|
+
const grace = deps.unregisteredWorkflowGraceMs;
|
|
5175
|
+
this.unregisteredWorkflowGraceMs = grace !== void 0 && Number.isFinite(grace) && grace >= 0 ? grace : 24 * 60 * 60 * 1e3;
|
|
5157
5176
|
this.remoteAdvanceSilenceMs = deps.remoteAdvanceSilenceMs;
|
|
5158
5177
|
this.reconcileMs = deps.reconcileMs === void 0 ? 3e5 : deps.reconcileMs || void 0;
|
|
5159
5178
|
const stalledAfter = deps.stalledAfterMs;
|
|
@@ -5470,13 +5489,19 @@ var WorkflowEngine = class {
|
|
|
5470
5489
|
* that is lost brings it back due after that period. False when the transport refused the wakes,
|
|
5471
5490
|
* so the caller resumes them itself.
|
|
5472
5491
|
*/
|
|
5473
|
-
async handOffDue(runs, nowMs) {
|
|
5492
|
+
async handOffDue(runs, nowMs, settled) {
|
|
5474
5493
|
const claimed = [];
|
|
5475
5494
|
for (const run of runs) {
|
|
5476
5495
|
if (this.draining) break;
|
|
5477
5496
|
if (!await this.store.tryLockRun(run.id, this.instanceId, nowMs + this.leaseMs, nowMs)) {
|
|
5478
5497
|
continue;
|
|
5479
5498
|
}
|
|
5499
|
+
if (!this.isRegisteredHere(run) && !await this.canResolveWorkflow(run)) {
|
|
5500
|
+
const result = await this.settleUnregistered(run, nowMs);
|
|
5501
|
+
if (result) settled?.set(run.id, result);
|
|
5502
|
+
else if (result === void 0) this.logUnregisteredSkip(run);
|
|
5503
|
+
continue;
|
|
5504
|
+
}
|
|
5480
5505
|
try {
|
|
5481
5506
|
const patch = {
|
|
5482
5507
|
wakeAt: nowMs + this.leaseMs
|
|
@@ -6250,9 +6275,7 @@ var WorkflowEngine = class {
|
|
|
6250
6275
|
});
|
|
6251
6276
|
}
|
|
6252
6277
|
const registered = this.workflows.get(versionKey(run.workflow, run.workflowVersion)) ?? await this.findInheritedRegistration(run) ?? await this.resolveRemoteByConvention(run);
|
|
6253
|
-
if (!registered)
|
|
6254
|
-
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)`);
|
|
6255
|
-
}
|
|
6278
|
+
if (!registered) throw new WorkflowNotRegistered(run.workflow, run.workflowVersion);
|
|
6256
6279
|
return this.track(this.execute(run, registered.fn));
|
|
6257
6280
|
}
|
|
6258
6281
|
/**
|
|
@@ -6667,6 +6690,15 @@ var WorkflowEngine = class {
|
|
|
6667
6690
|
};
|
|
6668
6691
|
}
|
|
6669
6692
|
}
|
|
6693
|
+
if (!this.isRegisteredHere(run) && !await this.canResolveWorkflow(run)) {
|
|
6694
|
+
const settled2 = await this.settleUnregistered(run, nowMs);
|
|
6695
|
+
if (settled2) return {
|
|
6696
|
+
result: settled2,
|
|
6697
|
+
dispatch: false
|
|
6698
|
+
};
|
|
6699
|
+
if (settled2 === void 0) this.logUnregisteredSkip(run);
|
|
6700
|
+
return void 0;
|
|
6701
|
+
}
|
|
6670
6702
|
const settled = await this.countRecovery(run);
|
|
6671
6703
|
if (settled) return {
|
|
6672
6704
|
result: settled,
|
|
@@ -6738,25 +6770,10 @@ var WorkflowEngine = class {
|
|
|
6738
6770
|
updatedAt: /* @__PURE__ */ new Date()
|
|
6739
6771
|
});
|
|
6740
6772
|
await this.store.releaseRunLock(run.id);
|
|
6741
|
-
this.
|
|
6742
|
-
type: "run.failed",
|
|
6743
|
-
runId: run.id,
|
|
6744
|
-
workflow: run.workflow,
|
|
6745
|
-
namespace: run.namespace,
|
|
6746
|
-
error: error2
|
|
6747
|
-
});
|
|
6748
|
-
this.notifyDead({
|
|
6773
|
+
return this.announceDead({
|
|
6749
6774
|
...run,
|
|
6750
|
-
status: "dead",
|
|
6751
|
-
error: error2,
|
|
6752
6775
|
recoveryAttempts: attempts
|
|
6753
|
-
});
|
|
6754
|
-
this.notifyParent(run.id, failedCompletion(error2));
|
|
6755
|
-
return {
|
|
6756
|
-
runId: run.id,
|
|
6757
|
-
status: "dead",
|
|
6758
|
-
error: error2
|
|
6759
|
-
};
|
|
6776
|
+
}, error2);
|
|
6760
6777
|
}
|
|
6761
6778
|
await this.store.updateRun(run.id, {
|
|
6762
6779
|
recoveryAttempts: attempts,
|
|
@@ -6764,6 +6781,85 @@ var WorkflowEngine = class {
|
|
|
6764
6781
|
});
|
|
6765
6782
|
return void 0;
|
|
6766
6783
|
}
|
|
6784
|
+
/** Tell everyone a run was just written `dead`: events, dead-letter routing, a waiting parent. */
|
|
6785
|
+
announceDead(run, error2) {
|
|
6786
|
+
this.emit({
|
|
6787
|
+
type: "run.failed",
|
|
6788
|
+
runId: run.id,
|
|
6789
|
+
workflow: run.workflow,
|
|
6790
|
+
namespace: run.namespace,
|
|
6791
|
+
error: error2
|
|
6792
|
+
});
|
|
6793
|
+
this.notifyDead({
|
|
6794
|
+
...run,
|
|
6795
|
+
status: "dead",
|
|
6796
|
+
error: error2
|
|
6797
|
+
});
|
|
6798
|
+
this.notifyParent(run.id, failedCompletion(error2));
|
|
6799
|
+
return {
|
|
6800
|
+
runId: run.id,
|
|
6801
|
+
status: "dead",
|
|
6802
|
+
error: error2
|
|
6803
|
+
};
|
|
6804
|
+
}
|
|
6805
|
+
/** The synchronous half of {@link canResolveWorkflow}: callers check it first, so a registered run
|
|
6806
|
+
* pays no await (same rule as {@link resume}). */
|
|
6807
|
+
isRegisteredHere(run) {
|
|
6808
|
+
return this.workflows.has(versionKey(run.workflow, run.workflowVersion));
|
|
6809
|
+
}
|
|
6810
|
+
/**
|
|
6811
|
+
* Whether this instance can run `run`'s pinned `workflow@version`: registered here, inherited from a
|
|
6812
|
+
* remote ancestor, or routed by convention to a live worker group (the lookup {@link resume} does).
|
|
6813
|
+
*/
|
|
6814
|
+
async canResolveWorkflow(run) {
|
|
6815
|
+
if (this.isRegisteredHere(run)) return true;
|
|
6816
|
+
return await this.findInheritedRegistration(run) !== void 0 || await this.resolveRemoteByConvention(run) !== void 0;
|
|
6817
|
+
}
|
|
6818
|
+
/**
|
|
6819
|
+
* A run whose lease this instance holds but whose `workflow@version` nothing here can run (see
|
|
6820
|
+
* {@link WorkflowNotRegistered}). Within {@link unregisteredWorkflowGraceMs} of becoming due it is a
|
|
6821
|
+
* rolling deploy's skew: the lease is released at once so the pod that still has the version takes
|
|
6822
|
+
* the run now, not after the lease expires. Past it, the workflow is gone from the whole fleet (a
|
|
6823
|
+
* capable pod would have taken the run long ago): dead-letter it.
|
|
6824
|
+
*
|
|
6825
|
+
* The age is read off `updatedAt` / `wakeAt`, so every path that would touch either (a recovery
|
|
6826
|
+
* count, a re-pend, a hand-off's lease-long `wakeAt`) must call this BEFORE writing — otherwise an
|
|
6827
|
+
* orphan never ages.
|
|
6828
|
+
*
|
|
6829
|
+
* Returns the `dead` result, `null` when the run left its status meanwhile (a lease-free
|
|
6830
|
+
* `cancel()`: settled, not ours to touch), or `undefined` when it was left for later.
|
|
6831
|
+
*/
|
|
6832
|
+
async settleUnregistered(listed, nowMs) {
|
|
6833
|
+
const run = await this.store.getRun(listed.id);
|
|
6834
|
+
if (!run || !UNREGISTERED_DEAD_LETTER_FROM.includes(run.status)) {
|
|
6835
|
+
await this.store.releaseRunLock(listed.id);
|
|
6836
|
+
return null;
|
|
6837
|
+
}
|
|
6838
|
+
const dueSince = Math.max(run.updatedAt.getTime(), run.wakeAt ?? 0);
|
|
6839
|
+
if (this.unregisteredWorkflowGraceMs === 0 || nowMs - dueSince < this.unregisteredWorkflowGraceMs) {
|
|
6840
|
+
await this.store.releaseRunLock(run.id);
|
|
6841
|
+
return void 0;
|
|
6842
|
+
}
|
|
6843
|
+
const error2 = {
|
|
6844
|
+
message: `workflow ${run.workflow}@${run.workflowVersion} is not registered on any live instance (unresumable for over ${this.unregisteredWorkflowGraceMs}ms) \u2014 moved to dead-letter`,
|
|
6845
|
+
code: "workflow_not_registered"
|
|
6846
|
+
};
|
|
6847
|
+
const applied = await (this.store.updateRunIf ?? this.updateRunIfFallback).call(this.store, run.id, [
|
|
6848
|
+
run.status
|
|
6849
|
+
], {
|
|
6850
|
+
status: "dead",
|
|
6851
|
+
error: error2,
|
|
6852
|
+
updatedAt: /* @__PURE__ */ new Date()
|
|
6853
|
+
});
|
|
6854
|
+
await this.store.releaseRunLock(run.id);
|
|
6855
|
+
if (!applied) return null;
|
|
6856
|
+
console.warn(`[nestjs-durable] run ${run.id}: ${error2.message}`);
|
|
6857
|
+
return this.announceDead(run, error2);
|
|
6858
|
+
}
|
|
6859
|
+
/** Log a run skipped for an unregistered workflow — still there, still not progressing. */
|
|
6860
|
+
logUnregisteredSkip(run) {
|
|
6861
|
+
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));
|
|
6862
|
+
}
|
|
6767
6863
|
/**
|
|
6768
6864
|
* Resume every suspended run whose durable timer is due. Call periodically (a poller) and on
|
|
6769
6865
|
* boot. A run still not due re-suspends cheaply without running new work.
|
|
@@ -6788,11 +6884,12 @@ var WorkflowEngine = class {
|
|
|
6788
6884
|
...due,
|
|
6789
6885
|
...blocked
|
|
6790
6886
|
];
|
|
6791
|
-
|
|
6792
|
-
|
|
6887
|
+
const settled = /* @__PURE__ */ new Map();
|
|
6888
|
+
if (await this.handOffDue(runs, nowMs, settled)) {
|
|
6889
|
+
return runs.map((run) => settled.get(run.id) ?? {
|
|
6793
6890
|
runId: run.id,
|
|
6794
6891
|
status: run.status
|
|
6795
|
-
})
|
|
6892
|
+
});
|
|
6796
6893
|
}
|
|
6797
6894
|
}
|
|
6798
6895
|
const waiterByRun = indexWaitersByRun(await listSignalWaitersOfRuns(this.store, [
|
|
@@ -6873,8 +6970,13 @@ var WorkflowEngine = class {
|
|
|
6873
6970
|
const nowMs = this.clock();
|
|
6874
6971
|
const acquired = await this.store.tryLockRun(runId, this.instanceId, nowMs + this.leaseMs, nowMs);
|
|
6875
6972
|
if (!acquired) return null;
|
|
6876
|
-
return this.resumeImplicit(runId).catch((err) => {
|
|
6973
|
+
return this.resumeImplicit(runId).catch(async (err) => {
|
|
6877
6974
|
if (err instanceof NamespaceMismatch) return null;
|
|
6975
|
+
if (err instanceof WorkflowNotRegistered) {
|
|
6976
|
+
const run = await this.store.getRun(runId);
|
|
6977
|
+
const settled = run ? await this.settleUnregistered(run, nowMs) : null;
|
|
6978
|
+
if (settled !== void 0) return settled;
|
|
6979
|
+
}
|
|
6878
6980
|
throw err;
|
|
6879
6981
|
});
|
|
6880
6982
|
}
|
|
@@ -7129,7 +7231,8 @@ var WorkflowEngine = class {
|
|
|
7129
7231
|
* Resume each run only if this instance can acquire its recovery lease — so when several
|
|
7130
7232
|
* replicas recover or poll at once, each run is picked up by exactly one of them.
|
|
7131
7233
|
*
|
|
7132
|
-
* A run this instance cannot resume is SKIPPED, not allowed to abort the batch
|
|
7234
|
+
* A run this instance cannot resume is SKIPPED, not allowed to abort the batch (a run whose workflow
|
|
7235
|
+
* stays registered nowhere past `unregisteredWorkflowGraceMs` is dead-lettered instead). The canonical
|
|
7133
7236
|
* case is skew protection: mid-rolling-deploy a pod leases a run whose workflow it does not have
|
|
7134
7237
|
* and `resume` throws by design — but the rest of the batch is runs it can drive perfectly well,
|
|
7135
7238
|
* and every caller here is a recovery sweep. Letting the first such run end the loop means one
|
|
@@ -7153,6 +7256,11 @@ var WorkflowEngine = class {
|
|
|
7153
7256
|
const settled = onLocked ? await onLocked(run) : void 0;
|
|
7154
7257
|
results.push(settled ?? await this.resumeImplicit(run.id));
|
|
7155
7258
|
} catch (error2) {
|
|
7259
|
+
if (error2 instanceof WorkflowNotRegistered) {
|
|
7260
|
+
const settled = await this.settleUnregistered(run, nowMs).catch(() => void 0);
|
|
7261
|
+
if (settled) results.push(settled);
|
|
7262
|
+
if (settled !== void 0) continue;
|
|
7263
|
+
}
|
|
7156
7264
|
console.error(`[nestjs-durable] could not resume run ${run.id} (${run.workflow}@${run.workflowVersion}); leaving it for another instance:`, error2);
|
|
7157
7265
|
}
|
|
7158
7266
|
}
|
|
@@ -12913,6 +13021,7 @@ export {
|
|
|
12913
13021
|
WORKFLOW_NAME_KEY,
|
|
12914
13022
|
WorkflowBlocked,
|
|
12915
13023
|
WorkflowEngine,
|
|
13024
|
+
WorkflowNotRegistered,
|
|
12916
13025
|
WorkflowSuspended,
|
|
12917
13026
|
aggregateAnnouncements,
|
|
12918
13027
|
aggregatesCheckpoints,
|