@dudousxd/nestjs-durable-core 0.86.2 → 0.88.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 +3765 -226
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1462 -80
- package/dist/index.d.ts +1462 -80
- package/dist/index.js +3712 -226
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -205,6 +205,13 @@ interface WorkflowRegistration {
|
|
|
205
205
|
code?: string;
|
|
206
206
|
workflow: string;
|
|
207
207
|
}[];
|
|
208
|
+
/**
|
|
209
|
+
* The `onEvent` event names this workflow subscribes to, lifecycle events (`run.completed:<wf>`,
|
|
210
|
+
* `run.failed:<wf>`) included. An engine settling a run reads them so it owes the run's lifecycle
|
|
211
|
+
* event to a subscriber that only another worker has. Absent = not stated, which subscribes to
|
|
212
|
+
* nothing.
|
|
213
|
+
*/
|
|
214
|
+
subscribes?: string[];
|
|
208
215
|
}
|
|
209
216
|
/**
|
|
210
217
|
* A worker's (or control-plane's) advertised identity, wire-protocol support, feature capabilities
|
|
@@ -484,6 +491,303 @@ declare class WorkflowBlocked extends Error {
|
|
|
484
491
|
*/
|
|
485
492
|
declare function planDispatch(requires: string[], liveDescriptors: readonly (RawWorkerDescriptor | WorkerDescriptor)[], cp: WorkerDescriptor, token: string): DispatchPlan;
|
|
486
493
|
|
|
494
|
+
/**
|
|
495
|
+
* A **workflow reference** is how one workflow names another to call it: either a registered workflow
|
|
496
|
+
* **name** (a string — the only option across runtimes, e.g. a Python workflow) or, for a same-runtime
|
|
497
|
+
* TypeScript workflow, its **class**. The class carries the input/output types through the call, so
|
|
498
|
+
* `ctx.child(ShippingWorkflow, input)` type-checks the input and returns a typed result — while a
|
|
499
|
+
* string stays available for the cross-runtime case.
|
|
500
|
+
*/
|
|
501
|
+
/**
|
|
502
|
+
* The symbol the `@Workflow` decorator stamps a workflow's registered name onto, so a class ref can
|
|
503
|
+
* be resolved back to its name. A global-registry symbol (`Symbol.for`) so it survives duplicate
|
|
504
|
+
* copies of this package in a dependency tree.
|
|
505
|
+
*/
|
|
506
|
+
declare const WORKFLOW_NAME_KEY: unique symbol;
|
|
507
|
+
/** Structural shape of a `@Workflow` class — its `run(ctx, input)` carries the input/output types. */
|
|
508
|
+
type WorkflowClass<TInput = unknown, TOutput = unknown> = abstract new (...args: never[]) => {
|
|
509
|
+
run(ctx: never, input: TInput): Promise<TOutput> | TOutput;
|
|
510
|
+
};
|
|
511
|
+
/** A workflow reference: a registered name (cross-runtime) or a workflow class (typed, same-runtime). */
|
|
512
|
+
type WorkflowRef<TInput = unknown, TOutput = unknown> = string | WorkflowClass<TInput, TOutput>;
|
|
513
|
+
/** The input type a workflow class's `run` accepts. */
|
|
514
|
+
type WorkflowInputOf<C> = C extends abstract new (...args: never[]) => {
|
|
515
|
+
run(ctx: never, input: infer I): unknown;
|
|
516
|
+
} ? I : unknown;
|
|
517
|
+
/** The output type a workflow class's `run` resolves to (Promise unwrapped). */
|
|
518
|
+
type WorkflowOutputOf<C> = C extends abstract new (...args: never[]) => {
|
|
519
|
+
run(ctx: never, input: never): infer R;
|
|
520
|
+
} ? Awaited<R> : unknown;
|
|
521
|
+
/**
|
|
522
|
+
* Resolve a {@link WorkflowRef} to its registered workflow name: a string is returned as-is; a
|
|
523
|
+
* `@Workflow` class is resolved via the name the decorator stamped on it. Throws if a class was
|
|
524
|
+
* never decorated (so it carries no registered name).
|
|
525
|
+
*/
|
|
526
|
+
declare function workflowName(ref: WorkflowRef): string;
|
|
527
|
+
|
|
528
|
+
/**
|
|
529
|
+
* Lifecycle events: when a run settles, the engine publishes `run.completed:<workflow>` or
|
|
530
|
+
* `run.failed:<workflow>` on the same bus as `publishEvent`, so another workflow can start on it
|
|
531
|
+
* through `onEvent` (or `@OnWorkflowCompleted` / `@OnWorkflowFailed` in `@dudousxd/nestjs-durable`)
|
|
532
|
+
* without the settling workflow knowing it exists.
|
|
533
|
+
*
|
|
534
|
+
* Delivery is exactly once per subscriber and settled run. The terminal status write also tags the
|
|
535
|
+
* run {@link LIFECYCLE_PENDING_TAG} plus one {@link LIFECYCLE_OWED_TAG_PREFIX} tag per subscriber
|
|
536
|
+
* the event is owed to: the ones registered on the settling process and the ones live workers
|
|
537
|
+
* announce. A process that dies before publishing, or that does not have a subscriber, leaves the
|
|
538
|
+
* marker for the timer poller's lifecycle sweep on any instance that does; the subscriber's run id
|
|
539
|
+
* is deterministic ({@link lifecycleRunId}), so publishing twice starts it once.
|
|
540
|
+
*
|
|
541
|
+
* When the settling process has no usable read of the fleet's announcements (none yet, or the last
|
|
542
|
+
* one failed), the terminal write tags the run {@link LIFECYCLE_PENDING_TAG} alone: the owed set is
|
|
543
|
+
* unresolved, and the first publish with a good read resolves it. A subscriber announced after the
|
|
544
|
+
* run settled is caught by the sweep's heal pass for {@link LIFECYCLE_HEAL_WINDOW_MS}; later than
|
|
545
|
+
* that, `engine.republishLifecycle` backfills it.
|
|
546
|
+
*/
|
|
547
|
+
/** The event published when a run of `workflow` completes. */
|
|
548
|
+
declare function runCompletedEvent(workflow: WorkflowRef): string;
|
|
549
|
+
/** The event published when a run of `workflow` ends failed, cancelled or dead. */
|
|
550
|
+
declare function runFailedEvent(workflow: WorkflowRef): string;
|
|
551
|
+
/**
|
|
552
|
+
* Tag written with a run's terminal status when some workflow subscribes to its lifecycle event,
|
|
553
|
+
* and removed once the event is published. A settled run still carrying it was never published.
|
|
554
|
+
* Carried with no {@link LIFECYCLE_OWED_TAG_PREFIX} tag, it means the owed set is unresolved: the
|
|
555
|
+
* settling process could not read the fleet's announcements, so the run is owed to every subscriber
|
|
556
|
+
* the first publish with a good read finds (minus the ones already started or failed).
|
|
557
|
+
*/
|
|
558
|
+
declare const LIFECYCLE_PENDING_TAG = "durable:lifecycle:pending";
|
|
559
|
+
/**
|
|
560
|
+
* Whether a run's `tags` (an array, or the JSON text a raw SQL select returns) still carry
|
|
561
|
+
* {@link LIFECYCLE_PENDING_TAG}. Retention never prunes such a run: its lifecycle event is owed.
|
|
562
|
+
*/
|
|
563
|
+
declare function carriesLifecyclePending(tags: unknown): boolean;
|
|
564
|
+
/** Prefix of the tags naming the subscribers a settled run started (`durable:triggered:<workflow>`). */
|
|
565
|
+
declare const LIFECYCLE_TRIGGERED_TAG_PREFIX = "durable:triggered:";
|
|
566
|
+
/**
|
|
567
|
+
* Prefix of the tags naming each subscriber a settled run's lifecycle event is still owed to
|
|
568
|
+
* (`durable:lifecycle:owed:<workflow>`). Written with {@link LIFECYCLE_PENDING_TAG} and removed one
|
|
569
|
+
* by one as the instances holding each subscriber publish to it; the pending tag goes with the last.
|
|
570
|
+
*/
|
|
571
|
+
declare const LIFECYCLE_OWED_TAG_PREFIX = "durable:lifecycle:owed:";
|
|
572
|
+
/**
|
|
573
|
+
* How long after a run settled an owed subscriber that no live worker announces and the sweeping
|
|
574
|
+
* instance does not have is kept. Past it the sweep drops the owed tag and reports
|
|
575
|
+
* `run.trigger_failed`, so a removed subscriber cannot keep a run from being pruned forever.
|
|
576
|
+
*/
|
|
577
|
+
declare const LIFECYCLE_ORPHAN_MS: number;
|
|
578
|
+
/**
|
|
579
|
+
* Prefix of the tags naming each subscriber whose start from a settled run's lifecycle event failed
|
|
580
|
+
* (`durable:trigger_failed:<workflow>`): its `where` threw, its input was rejected, its start threw,
|
|
581
|
+
* or the sweep dropped it as orphaned (see {@link LIFECYCLE_ORPHAN_MS}). Written in the same update
|
|
582
|
+
* that drops its owed tag, and removed by the update that records it started. The failure message
|
|
583
|
+
* is not stored; the `run.trigger_failed` event carries it.
|
|
584
|
+
*/
|
|
585
|
+
declare const LIFECYCLE_TRIGGER_FAILED_TAG_PREFIX = "durable:trigger_failed:";
|
|
586
|
+
/** The subscribers whose start from a run's lifecycle event failed, read from its failed tags. */
|
|
587
|
+
declare function triggerFailedSubscribersOf(tags: readonly string[] | undefined): string[];
|
|
588
|
+
/** The subscribers a settled run started, read from its {@link LIFECYCLE_TRIGGERED_TAG_PREFIX} tags. */
|
|
589
|
+
declare function triggeredSubscribersOf(tags: readonly string[] | undefined): string[];
|
|
590
|
+
/**
|
|
591
|
+
* Prefix of the tags naming each subscriber a settled run's lifecycle event was routed into a
|
|
592
|
+
* debounce/batch accumulator for (`durable:coalesced:<workflow>`). Such a subscriber starts no run
|
|
593
|
+
* of the source's id, so this tag is what records the delivery: written in the same update that drops
|
|
594
|
+
* its owed tag, it keeps a heal or a republish from routing the event again.
|
|
595
|
+
*/
|
|
596
|
+
declare const LIFECYCLE_COALESCED_TAG_PREFIX = "durable:coalesced:";
|
|
597
|
+
/** The subscribers a settled run's event was coalesced into, read from its coalesced tags. */
|
|
598
|
+
declare function coalescedSubscribersOf(tags: readonly string[] | undefined): string[];
|
|
599
|
+
/**
|
|
600
|
+
* How long after a run settled the lifecycle sweep still checks it for subscribers it missed: one
|
|
601
|
+
* the fleet announced only after the settling process last read the announcements. Such a
|
|
602
|
+
* subscriber is started (or owed to the instances that have it) as if it had been owed from the
|
|
603
|
+
* start. One announced later than this is backfill, for `engine.republishLifecycle`.
|
|
604
|
+
*/
|
|
605
|
+
declare const LIFECYCLE_HEAL_WINDOW_MS: number;
|
|
606
|
+
/** The subscribers a run's lifecycle event is still owed to, read from its owed tags. */
|
|
607
|
+
declare function owedSubscribersOf(tags: readonly string[] | undefined): string[];
|
|
608
|
+
/**
|
|
609
|
+
* Prefix of the tag holding the W3C `traceparent` of a run's root span
|
|
610
|
+
* (`durable:lifecycle:trace:<traceparent>`). Written with the run's first suspend, or with the
|
|
611
|
+
* lifecycle marker when it settles without suspending, when some workflow subscribes to the run's
|
|
612
|
+
* ending and the engine has a run trace provider (see `WorkflowEngine.setRunTraceparent`), so a
|
|
613
|
+
* subscriber's trace can link to its source run from any process.
|
|
614
|
+
*/
|
|
615
|
+
declare const LIFECYCLE_TRACE_TAG_PREFIX = "durable:lifecycle:trace:";
|
|
616
|
+
/** The traceparent a settled run recorded in its {@link LIFECYCLE_TRACE_TAG_PREFIX} tag, if any. */
|
|
617
|
+
declare function lifecycleTraceparentOf(tags: readonly string[] | undefined): string | undefined;
|
|
618
|
+
/** Whether `tag` is one the engine writes for lifecycle bookkeeping rather than one the run was given. */
|
|
619
|
+
declare function isLifecycleTag(tag: string): boolean;
|
|
620
|
+
/** The payload of a lifecycle event, read from the store after the run settled. */
|
|
621
|
+
interface WorkflowLifecycleEvent<TInput = unknown, TOutput = unknown> {
|
|
622
|
+
runId: string;
|
|
623
|
+
workflow: string;
|
|
624
|
+
workflowVersion: string;
|
|
625
|
+
/** `completed` on `run.completed:*`; `failed`, `cancelled` or `dead` on `run.failed:*`. */
|
|
626
|
+
status: RunStatus;
|
|
627
|
+
namespace?: string | undefined;
|
|
628
|
+
input: TInput;
|
|
629
|
+
/** Present on a completed run. */
|
|
630
|
+
output?: TOutput | undefined;
|
|
631
|
+
/** Present on a run that did not complete. */
|
|
632
|
+
error?: StepError | undefined;
|
|
633
|
+
tags?: string[] | undefined;
|
|
634
|
+
searchAttributes?: SearchAttributes | undefined;
|
|
635
|
+
}
|
|
636
|
+
/** The lifecycle event a run of workflow class `C` publishes, typed by its input and output. */
|
|
637
|
+
type LifecycleEventOf<C> = WorkflowLifecycleEvent<WorkflowInputOf<C>, WorkflowOutputOf<C>>;
|
|
638
|
+
/** Which lifecycle event a settled run publishes: `completed`, or `failed` for any other ending. */
|
|
639
|
+
type LifecycleKind = 'completed' | 'failed';
|
|
640
|
+
/**
|
|
641
|
+
* The id of the run a lifecycle event starts for `subscriber`. Deterministic, so the same settled
|
|
642
|
+
* run never starts the same subscriber twice, and either side of the link can be found from the other.
|
|
643
|
+
*/
|
|
644
|
+
declare function lifecycleRunId(sourceRunId: string, kind: LifecycleKind, subscriber: string): string;
|
|
645
|
+
/** The lifecycle event a run in `status` published, or undefined while it has not settled. */
|
|
646
|
+
declare function lifecycleKindOf(status: RunStatus | undefined): LifecycleKind | undefined;
|
|
647
|
+
/** The event name a run of `workflow` publishes when it settles as `kind`. */
|
|
648
|
+
declare function lifecycleEventName(workflow: string, kind: LifecycleKind): string;
|
|
649
|
+
/** The workflow and ending a lifecycle event name stands for, or undefined for any other event. */
|
|
650
|
+
declare function parseLifecycleEvent(event: string): {
|
|
651
|
+
workflow: string;
|
|
652
|
+
kind: LifecycleKind;
|
|
653
|
+
} | undefined;
|
|
654
|
+
/**
|
|
655
|
+
* One workflow that starts when another settles, as the dashboard's workflow page lists it. `local`
|
|
656
|
+
* is what the answering instance has registered, with what its subscription does to the payload;
|
|
657
|
+
* an entry only live workers announce (a Python subscriber, or a TypeScript one served elsewhere)
|
|
658
|
+
* states none of that, since the announcement carries only the event name.
|
|
659
|
+
*/
|
|
660
|
+
interface LifecycleSubscriptionLink {
|
|
661
|
+
/** The other end: the subscriber on `startsOnSettle`, the settling workflow on `startedBy`. */
|
|
662
|
+
workflow: string;
|
|
663
|
+
kind: LifecycleKind;
|
|
664
|
+
/** Registered on the answering instance (true) or only announced by live workers (false). */
|
|
665
|
+
local: boolean;
|
|
666
|
+
/** Announced by at least one live worker. */
|
|
667
|
+
announced: boolean;
|
|
668
|
+
/** The subscription filters payloads with `where`. */
|
|
669
|
+
where: boolean;
|
|
670
|
+
/** The subscription maps the payload to the run's input with `input`. */
|
|
671
|
+
input: boolean;
|
|
672
|
+
/** The subscriber coalesces events: debounced or batched, and whether per `key`. */
|
|
673
|
+
coalesce?: {
|
|
674
|
+
mode: 'debounce' | 'batch';
|
|
675
|
+
keyed: boolean;
|
|
676
|
+
} | undefined;
|
|
677
|
+
}
|
|
678
|
+
/**
|
|
679
|
+
* Who starts whom through lifecycle events, for one workflow: the subscribers of its
|
|
680
|
+
* `run.completed:<workflow>` / `run.failed:<workflow>` events, and the workflows whose settling
|
|
681
|
+
* starts it. Built from the answering instance's registry and the subscriptions live workers
|
|
682
|
+
* announce.
|
|
683
|
+
*/
|
|
684
|
+
interface WorkflowLifecycleLinks {
|
|
685
|
+
workflow: string;
|
|
686
|
+
/** Workflows that start when this one settles, sorted by workflow then kind. */
|
|
687
|
+
startsOnSettle: LifecycleSubscriptionLink[];
|
|
688
|
+
/** Workflows whose settling starts this one, sorted by workflow then kind. */
|
|
689
|
+
startedBy: LifecycleSubscriptionLink[];
|
|
690
|
+
}
|
|
691
|
+
/**
|
|
692
|
+
* The run whose settling started `run`, when a lifecycle event started it. Read from the run's id,
|
|
693
|
+
* which ends in `:<kind>:<its own workflow>`, so it holds whatever input the subscriber was given.
|
|
694
|
+
*/
|
|
695
|
+
declare function lifecycleSourceOf(run: {
|
|
696
|
+
id: string;
|
|
697
|
+
workflow: string;
|
|
698
|
+
}): {
|
|
699
|
+
runId: string;
|
|
700
|
+
kind: LifecycleKind;
|
|
701
|
+
} | undefined;
|
|
702
|
+
/**
|
|
703
|
+
* The runs `run`'s settling started, read from its {@link LIFECYCLE_TRIGGERED_TAG_PREFIX} tags.
|
|
704
|
+
* Empty for a run that has not settled or started nobody. Needs no subscriber registry, so any
|
|
705
|
+
* process holding the run row can answer it.
|
|
706
|
+
*/
|
|
707
|
+
declare function triggeredRunsOf(run: Pick<WorkflowRun, 'id' | 'status' | 'tags'>): string[];
|
|
708
|
+
/** The {@link WorkflowLifecycleEvent} a settled run publishes. */
|
|
709
|
+
declare function lifecycleEventOf(run: WorkflowRun): WorkflowLifecycleEvent;
|
|
710
|
+
/**
|
|
711
|
+
* Which settled runs `engine.republishLifecycle` publishes again: one run, or the settled runs of a
|
|
712
|
+
* workflow (`kind` narrows to completed or to every other ending; `since`/`until` bound when they
|
|
713
|
+
* settled; `limit` caps how many runs are read, default 1000; `namespace` reads one namespace only,
|
|
714
|
+
* the engine's own when unset). `subscriber` restricts it to one subscribing workflow.
|
|
715
|
+
*/
|
|
716
|
+
type RepublishLifecycleTarget = {
|
|
717
|
+
runId: string;
|
|
718
|
+
subscriber?: string | undefined;
|
|
719
|
+
} | {
|
|
720
|
+
workflow: string;
|
|
721
|
+
kind?: LifecycleKind | undefined;
|
|
722
|
+
since?: Date | undefined;
|
|
723
|
+
until?: Date | undefined;
|
|
724
|
+
subscriber?: string | undefined;
|
|
725
|
+
limit?: number | undefined;
|
|
726
|
+
namespace?: string | undefined;
|
|
727
|
+
};
|
|
728
|
+
/** What `engine.republishLifecycle` did: runs published, subscriber runs started, and the failures. */
|
|
729
|
+
interface RepublishLifecycleResult {
|
|
730
|
+
runs: number;
|
|
731
|
+
started: number;
|
|
732
|
+
failed: {
|
|
733
|
+
runId: string;
|
|
734
|
+
subscriber: string;
|
|
735
|
+
error: string;
|
|
736
|
+
}[];
|
|
737
|
+
}
|
|
738
|
+
/**
|
|
739
|
+
* The internal workflow whose runs make up the lifecycle subscription registry: one completed run
|
|
740
|
+
* per engine instance that has `onEvent` subscriptions, id {@link lifecycleRegistryRunId}, its
|
|
741
|
+
* subscriptions in `input` ({@link LifecycleRegistryEntry}) and its `updatedAt` the heartbeat. Kept
|
|
742
|
+
* in the state store, so an instance learns what the others subscribe to over any transport.
|
|
743
|
+
*/
|
|
744
|
+
declare const LIFECYCLE_REGISTRY_WORKFLOW = "__lifecycle_registry";
|
|
745
|
+
/** Tag every registry run carries. Retention never prunes a run that has it. */
|
|
746
|
+
declare const LIFECYCLE_REGISTRY_TAG = "durable:lifecycle:registry";
|
|
747
|
+
/** How often an engine refreshes its registry run (from the timer poller's lifecycle sweep). */
|
|
748
|
+
declare const LIFECYCLE_REGISTRY_HEARTBEAT_MS = 10000;
|
|
749
|
+
/** How long after its last heartbeat a registry run still counts as a live instance's. */
|
|
750
|
+
declare const LIFECYCLE_REGISTRY_TTL_MS = 35000;
|
|
751
|
+
/** How long after its last heartbeat a registry run is deleted, by any engine's sweep. */
|
|
752
|
+
declare const LIFECYCLE_REGISTRY_STALE_MS: number;
|
|
753
|
+
/** The id of the registry run of engine instance `instanceId`. */
|
|
754
|
+
declare function lifecycleRegistryRunId(instanceId: string): string;
|
|
755
|
+
/** What a registry run holds in `input`: the `onEvent` subscriptions of one engine instance. */
|
|
756
|
+
interface LifecycleRegistryEntry {
|
|
757
|
+
instanceId: string;
|
|
758
|
+
runtime: 'node';
|
|
759
|
+
/**
|
|
760
|
+
* The engine's namespace, or `null` for an engine with no namespace. Recorded because both write
|
|
761
|
+
* the registry run under `default`. An engine with no namespace sweeps and starts its subscribers
|
|
762
|
+
* for the runs of every namespace, so its subscriptions are owed by settled runs of any namespace;
|
|
763
|
+
* an engine with one, only by its own.
|
|
764
|
+
*/
|
|
765
|
+
engineNamespace: string | null;
|
|
766
|
+
/** Each subscribing workflow with the event names it starts on, lifecycle ones included. */
|
|
767
|
+
subscriptions: {
|
|
768
|
+
workflow: string;
|
|
769
|
+
events: string[];
|
|
770
|
+
}[];
|
|
771
|
+
}
|
|
772
|
+
/**
|
|
773
|
+
* The namespace whose settled runs owe their lifecycle events to the subscriptions of a registry
|
|
774
|
+
* run, or `null` for every namespace: the entry's `engineNamespace`, or for a row written without it,
|
|
775
|
+
* the row's `namespace`, read as every namespace when that is `default` (an engine with no namespace
|
|
776
|
+
* wrote it, as far as the row can tell).
|
|
777
|
+
*/
|
|
778
|
+
declare function lifecycleRegistryNamespace(input: unknown, rowNamespace: string | undefined): string | null;
|
|
779
|
+
/** The subscriptions a registry run's `input` holds; malformed entries are skipped. */
|
|
780
|
+
declare function lifecycleRegistrySubscriptions(input: unknown): {
|
|
781
|
+
workflow: string;
|
|
782
|
+
events: string[];
|
|
783
|
+
}[];
|
|
784
|
+
/**
|
|
785
|
+
* Whether retention must keep a run with these `tags` (an array, or the JSON text a raw SQL select
|
|
786
|
+
* returns): its lifecycle event is still owed ({@link carriesLifecyclePending}), or it is a
|
|
787
|
+
* lifecycle registry run ({@link LIFECYCLE_REGISTRY_TAG}).
|
|
788
|
+
*/
|
|
789
|
+
declare function retentionKeeps(tags: unknown): boolean;
|
|
790
|
+
|
|
487
791
|
/**
|
|
488
792
|
* A parallel fan (a `ctx.all`, a step fan, a polyglot `gather`) reduced to what a detail view needs
|
|
489
793
|
* to draw it: one node, its progress and its failures. A run detail with a 40,000-item fan otherwise
|
|
@@ -562,6 +866,69 @@ declare function fanPageBounds(query: FanPageQuery): {
|
|
|
562
866
|
limit: number;
|
|
563
867
|
};
|
|
564
868
|
|
|
869
|
+
/**
|
|
870
|
+
* One end of a `ctx.waitForRun` wait, as a run detail lists it: the run waited for (`waitsFor`) or
|
|
871
|
+
* the waiting run (`awaitedBy`), the waiting run's `seq` of the call, and the other run's status and
|
|
872
|
+
* namespace when it was read.
|
|
873
|
+
*/
|
|
874
|
+
interface RunWaitLink {
|
|
875
|
+
runId: string;
|
|
876
|
+
seq: number;
|
|
877
|
+
status?: RunStatus | undefined;
|
|
878
|
+
namespace?: string | undefined;
|
|
879
|
+
}
|
|
880
|
+
/**
|
|
881
|
+
* Where a settled run's lifecycle event stands for one subscriber:
|
|
882
|
+
* - `started`: its run exists (`runId`, a `durable:triggered:<subscriber>` tag);
|
|
883
|
+
* - `owed`: still pending (a `durable:lifecycle:owed:<subscriber>` tag);
|
|
884
|
+
* - `coalesced`: routed into a debounce/batch accumulator (a `durable:coalesced:<subscriber>` tag,
|
|
885
|
+
* or the caller's `coalesced` map; `runId` is the accumulator's, when it can be derived);
|
|
886
|
+
* - `failed`: its start failed (a `durable:trigger_failed:<subscriber>` tag): its `where` threw, its
|
|
887
|
+
* input was rejected, its start threw, or the sweep dropped it as orphaned. A republish retries it;
|
|
888
|
+
* - `not-started`: no run and nothing owed: its `where` declined the event, or it subscribed after
|
|
889
|
+
* the run settled.
|
|
890
|
+
*/
|
|
891
|
+
type LifecycleDeliveryState = 'started' | 'owed' | 'coalesced' | 'failed' | 'not-started';
|
|
892
|
+
/** One subscriber of a settled run's lifecycle event, as the run detail lists it. */
|
|
893
|
+
interface LifecycleDelivery {
|
|
894
|
+
subscriber: string;
|
|
895
|
+
state: LifecycleDeliveryState;
|
|
896
|
+
/** The subscriber's run when `started`; the accumulator run when `coalesced` and derivable. */
|
|
897
|
+
runId?: string | undefined;
|
|
898
|
+
/** The status of a `started` subscriber's run, when it was read. */
|
|
899
|
+
status?: RunStatus | undefined;
|
|
900
|
+
/** The namespace of a `started` subscriber's run, when it was read. */
|
|
901
|
+
namespace?: string | undefined;
|
|
902
|
+
/** When an `owed` subscriber became owed: the settled run's last update (epoch ms). */
|
|
903
|
+
owedSince?: number | undefined;
|
|
904
|
+
/**
|
|
905
|
+
* When the lifecycle sweep drops an `owed` subscriber that no live instance registers or
|
|
906
|
+
* announces for the run's namespace (epoch ms; see {@link LIFECYCLE_ORPHAN_MS}). Absent while one
|
|
907
|
+
* does.
|
|
908
|
+
*/
|
|
909
|
+
orphanAt?: number | undefined;
|
|
910
|
+
/**
|
|
911
|
+
* Why a `failed` subscriber did not start, when the caller knows it (the run's tags record only
|
|
912
|
+
* that it failed; the `run.trigger_failed` event carries the message). {@link lifecycleDeliveriesOf}
|
|
913
|
+
* leaves it unset.
|
|
914
|
+
*/
|
|
915
|
+
error?: string | undefined;
|
|
916
|
+
}
|
|
917
|
+
/**
|
|
918
|
+
* The {@link LifecycleDelivery} of each subscriber of a settled run, sorted by subscriber: the
|
|
919
|
+
* union of `subscribers` (the ones the run's event goes to now) and the owed, triggered, coalesced
|
|
920
|
+
* and trigger-failed tags. `live` names the subscribers a live instance registers or announces; an owed subscriber
|
|
921
|
+
* outside it gets `orphanAt`. `coalesced` maps each subscriber that coalesces its events to its
|
|
922
|
+
* accumulator run id (undefined when it cannot be derived). Empty for a run that has not settled.
|
|
923
|
+
*/
|
|
924
|
+
declare function lifecycleDeliveriesOf(run: Pick<WorkflowRun, 'id' | 'status' | 'tags' | 'updatedAt'>, opts: {
|
|
925
|
+
subscribers: readonly string[];
|
|
926
|
+
live: ReadonlySet<string>;
|
|
927
|
+
coalesced?: ReadonlyMap<string, string | undefined> | undefined;
|
|
928
|
+
}): LifecycleDelivery[];
|
|
929
|
+
/** The trace id of a W3C `traceparent` (`00-<trace id>-<span id>-<flags>`), or undefined. */
|
|
930
|
+
declare function traceIdOfTraceparent(traceparent: string | undefined): string | undefined;
|
|
931
|
+
|
|
565
932
|
/** A run as returned by the gateway's list — the durable run plus an optional {@link RunWaiting}
|
|
566
933
|
* descriptor the control plane resolves (what a suspended run is parked on), so the dashboard can
|
|
567
934
|
* name the wait in a list row without fetching each run's timeline. Additive: `waiting` is absent
|
|
@@ -576,6 +943,46 @@ interface DurableTopology {
|
|
|
576
943
|
role: 'control-plane' | 'tenant';
|
|
577
944
|
/** The tenant's isolation partition name; set only when `role` is 'tenant'. */
|
|
578
945
|
tenant?: string;
|
|
946
|
+
/**
|
|
947
|
+
* The engine behind the gateway, when it is not nestjs-durable's own (e.g. `'@nestjs/workflows'`
|
|
948
|
+
* for `@dudousxd/nestjs-durable-workflows-gateway`). Shown in the console header. Absent: durable.
|
|
949
|
+
*/
|
|
950
|
+
engine?: string;
|
|
951
|
+
/**
|
|
952
|
+
* Console features this gateway cannot serve, as `false`; the SPA hides their controls. A key
|
|
953
|
+
* left out (or no object at all, as from every durable gateway) means supported.
|
|
954
|
+
*/
|
|
955
|
+
capabilities?: ConsoleCapabilities;
|
|
956
|
+
}
|
|
957
|
+
/** See {@link DurableTopology.capabilities}. `false` hides the control; absent means supported. */
|
|
958
|
+
interface ConsoleCapabilities {
|
|
959
|
+
/** Search-attribute filters (`attributes` in a run query). */
|
|
960
|
+
searchAttributes?: boolean;
|
|
961
|
+
/** The tenant/namespace picker. */
|
|
962
|
+
namespaces?: boolean;
|
|
963
|
+
/** Tag filters. */
|
|
964
|
+
tags?: boolean;
|
|
965
|
+
/** Origin chips (which package/app started a run). */
|
|
966
|
+
origins?: boolean;
|
|
967
|
+
/** Breakpoints (`Continue`). */
|
|
968
|
+
breakpoints?: boolean;
|
|
969
|
+
/** Re-dispatching lost remote steps. */
|
|
970
|
+
redispatch?: boolean;
|
|
971
|
+
/** Republishing lifecycle events. */
|
|
972
|
+
republishLifecycle?: boolean;
|
|
973
|
+
/** The schedules panel. */
|
|
974
|
+
schedules?: boolean;
|
|
975
|
+
/** The workers / partitions health panel. */
|
|
976
|
+
workers?: boolean;
|
|
977
|
+
}
|
|
978
|
+
/** The run whose settling started a run, as its detail names it. */
|
|
979
|
+
interface LifecycleSource {
|
|
980
|
+
runId: string;
|
|
981
|
+
kind: 'completed' | 'failed';
|
|
982
|
+
status?: RunStatus | undefined;
|
|
983
|
+
namespace?: string | undefined;
|
|
984
|
+
/** The W3C trace id of the source run's span, when it recorded one. */
|
|
985
|
+
traceId?: string | undefined;
|
|
579
986
|
}
|
|
580
987
|
/** A run + its timeline + child ids — the detail view. Single source of truth: the dashboard server
|
|
581
988
|
* re-exports this instead of re-declaring it, and the dashboard client derives its wire mirror from
|
|
@@ -593,6 +1000,38 @@ interface RunDetail {
|
|
|
593
1000
|
fans?: FanSummary[] | undefined;
|
|
594
1001
|
/** How many children the run has, when `children` lists only the first of them. */
|
|
595
1002
|
childCount?: number | undefined;
|
|
1003
|
+
/**
|
|
1004
|
+
* Runs started by this run settling: subscribers of its `run.completed:<workflow>` or
|
|
1005
|
+
* `run.failed:<workflow>` event. Not children: they are not cancelled with it or awaited by it.
|
|
1006
|
+
*/
|
|
1007
|
+
triggered?: string[] | undefined;
|
|
1008
|
+
/**
|
|
1009
|
+
* The run whose settling started this one, when a lifecycle event started it, with the source
|
|
1010
|
+
* run's `status` and `namespace`, and the trace id of its span (`traceId`) when the source
|
|
1011
|
+
* recorded one (see `LIFECYCLE_TRACE_TAG_PREFIX`).
|
|
1012
|
+
*/
|
|
1013
|
+
triggeredBy?: LifecycleSource | undefined;
|
|
1014
|
+
/**
|
|
1015
|
+
* The workflows subscribed to this settled run's lifecycle event, registered on the answering
|
|
1016
|
+
* instance or announced by the live fleet. Present only when there is at least one, which is
|
|
1017
|
+
* when the run's lifecycle event can be republished.
|
|
1018
|
+
*/
|
|
1019
|
+
lifecycleSubscribers?: string[] | undefined;
|
|
1020
|
+
/**
|
|
1021
|
+
* Who starts whom through lifecycle events, for this run's workflow (see
|
|
1022
|
+
* `WorkflowEngine.workflowLifecycle`). Present only when the workflow starts or is started by some
|
|
1023
|
+
* other workflow.
|
|
1024
|
+
*/
|
|
1025
|
+
workflowLifecycle?: WorkflowLifecycleLinks | undefined;
|
|
1026
|
+
/**
|
|
1027
|
+
* Where a settled run's lifecycle event stands for each subscriber: started, owed, coalesced or
|
|
1028
|
+
* not started. Absent when the run has not settled or has no subscribers.
|
|
1029
|
+
*/
|
|
1030
|
+
lifecycleDeliveries?: LifecycleDelivery[] | undefined;
|
|
1031
|
+
/** The runs a suspended run waits for through `ctx.waitForRun`. */
|
|
1032
|
+
waitsFor?: RunWaitLink[] | undefined;
|
|
1033
|
+
/** The runs waiting for this one through `ctx.waitForRun`. */
|
|
1034
|
+
awaitedBy?: RunWaitLink[] | undefined;
|
|
596
1035
|
/**
|
|
597
1036
|
* A validator for this detail, when the gateway can compute one without reading the timeline:
|
|
598
1037
|
* it changes whenever the run or any of its checkpoints does. Absent when it cannot.
|
|
@@ -704,6 +1143,26 @@ declare abstract class RunGateway {
|
|
|
704
1143
|
abstract retryWithInput(runId: string, input: unknown): Promise<{
|
|
705
1144
|
runId: string;
|
|
706
1145
|
} | null>;
|
|
1146
|
+
/**
|
|
1147
|
+
* Publish settled runs' lifecycle events again (see `WorkflowEngine.republishLifecycle`). Optional:
|
|
1148
|
+
* only a gateway backed by the canonical store and an engine implements it.
|
|
1149
|
+
*/
|
|
1150
|
+
republishLifecycle?(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
|
|
1151
|
+
/**
|
|
1152
|
+
* Who starts whom through lifecycle events, for one workflow (see
|
|
1153
|
+
* `WorkflowEngine.workflowLifecycle`), only the subscriptions of `opts.namespace` when given.
|
|
1154
|
+
* Optional: a gateway backed by an engine, or a tenant proxy (scoped to its tenant by the
|
|
1155
|
+
* operator), implements it.
|
|
1156
|
+
*/
|
|
1157
|
+
workflowLifecycle?(workflow: string, opts?: {
|
|
1158
|
+
namespace?: string | undefined;
|
|
1159
|
+
}): Promise<WorkflowLifecycleLinks>;
|
|
1160
|
+
/**
|
|
1161
|
+
* The subscribers a run of `workflow` in `namespace` settling as `kind` owes its lifecycle event to
|
|
1162
|
+
* (see `WorkflowEngine.lifecycleSubscribers`). Optional: a gateway backed by an engine implements
|
|
1163
|
+
* it; the run-request responder checks a tenant republish's `subscriber` against it.
|
|
1164
|
+
*/
|
|
1165
|
+
lifecycleSubscribers?(workflow: string, kind: LifecycleKind, namespace: string): Promise<string[]>;
|
|
707
1166
|
/** Live lifecycle events for one run; returns an unsubscribe fn. Framework-agnostic (no rxjs). */
|
|
708
1167
|
abstract subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
|
|
709
1168
|
}
|
|
@@ -843,40 +1302,6 @@ declare function stepNameOf(ref: unknown): string | undefined;
|
|
|
843
1302
|
* it via {@link StepDispatchOpts} instead). */
|
|
844
1303
|
declare function stepConfigOf(ref: unknown): StepConfig | undefined;
|
|
845
1304
|
|
|
846
|
-
/**
|
|
847
|
-
* A **workflow reference** is how one workflow names another to call it: either a registered workflow
|
|
848
|
-
* **name** (a string — the only option across runtimes, e.g. a Python workflow) or, for a same-runtime
|
|
849
|
-
* TypeScript workflow, its **class**. The class carries the input/output types through the call, so
|
|
850
|
-
* `ctx.child(ShippingWorkflow, input)` type-checks the input and returns a typed result — while a
|
|
851
|
-
* string stays available for the cross-runtime case.
|
|
852
|
-
*/
|
|
853
|
-
/**
|
|
854
|
-
* The symbol the `@Workflow` decorator stamps a workflow's registered name onto, so a class ref can
|
|
855
|
-
* be resolved back to its name. A global-registry symbol (`Symbol.for`) so it survives duplicate
|
|
856
|
-
* copies of this package in a dependency tree.
|
|
857
|
-
*/
|
|
858
|
-
declare const WORKFLOW_NAME_KEY: unique symbol;
|
|
859
|
-
/** Structural shape of a `@Workflow` class — its `run(ctx, input)` carries the input/output types. */
|
|
860
|
-
type WorkflowClass<TInput = unknown, TOutput = unknown> = abstract new (...args: never[]) => {
|
|
861
|
-
run(ctx: never, input: TInput): Promise<TOutput> | TOutput;
|
|
862
|
-
};
|
|
863
|
-
/** A workflow reference: a registered name (cross-runtime) or a workflow class (typed, same-runtime). */
|
|
864
|
-
type WorkflowRef<TInput = unknown, TOutput = unknown> = string | WorkflowClass<TInput, TOutput>;
|
|
865
|
-
/** The input type a workflow class's `run` accepts. */
|
|
866
|
-
type WorkflowInputOf<C> = C extends abstract new (...args: never[]) => {
|
|
867
|
-
run(ctx: never, input: infer I): unknown;
|
|
868
|
-
} ? I : unknown;
|
|
869
|
-
/** The output type a workflow class's `run` resolves to (Promise unwrapped). */
|
|
870
|
-
type WorkflowOutputOf<C> = C extends abstract new (...args: never[]) => {
|
|
871
|
-
run(ctx: never, input: never): infer R;
|
|
872
|
-
} ? Awaited<R> : unknown;
|
|
873
|
-
/**
|
|
874
|
-
* Resolve a {@link WorkflowRef} to its registered workflow name: a string is returned as-is; a
|
|
875
|
-
* `@Workflow` class is resolved via the name the decorator stamped on it. Throws if a class was
|
|
876
|
-
* never decorated (so it carries no registered name).
|
|
877
|
-
*/
|
|
878
|
-
declare function workflowName(ref: WorkflowRef): string;
|
|
879
|
-
|
|
880
1305
|
/**
|
|
881
1306
|
* Core type contracts for nestjs-durable.
|
|
882
1307
|
*
|
|
@@ -996,9 +1421,10 @@ interface WorkflowRun {
|
|
|
996
1421
|
* The detail view (which has the timeline) still distinguishes sleep vs in-flight step precisely.
|
|
997
1422
|
*/
|
|
998
1423
|
interface RunWaiting {
|
|
999
|
-
on: 'signal' | 'webhook' | 'child' | 'breakpoint';
|
|
1424
|
+
on: 'signal' | 'webhook' | 'child' | 'breakpoint' | 'run';
|
|
1000
1425
|
/**
|
|
1001
|
-
* The token/name the run is parked on — the signal name, webhook token,
|
|
1426
|
+
* The token/name the run is parked on — the signal name, webhook token, awaited child id, or the id
|
|
1427
|
+
* of the run it waits on in `ctx.waitForRun`. For a
|
|
1002
1428
|
* breakpoint this is always the literal `'breakpoint'`: the real label (if any) lives on the pending
|
|
1003
1429
|
* `breakpoint`/`breakpoint:<label>` checkpoint, which the detail view's timeline already shows —
|
|
1004
1430
|
* naming it here would need an extra per-run checkpoint read, defeating the bulk waiter scan.
|
|
@@ -1067,6 +1493,21 @@ interface StepSettlement {
|
|
|
1067
1493
|
startedAt: Date;
|
|
1068
1494
|
finishedAt: Date;
|
|
1069
1495
|
}
|
|
1496
|
+
/**
|
|
1497
|
+
* A step's result as {@link StateStore.settleResultsIfPending} writes it onto the step's `pending`
|
|
1498
|
+
* checkpoint. Unlike a {@link StepSettlement}, what the result does not carry keeps the stored value:
|
|
1499
|
+
* `output` is written only for a `completed` result, `events` and `startedAt` only when present.
|
|
1500
|
+
*/
|
|
1501
|
+
interface StepResultSettlement {
|
|
1502
|
+
runId: string;
|
|
1503
|
+
seq: number;
|
|
1504
|
+
status: 'completed' | 'failed';
|
|
1505
|
+
output?: unknown;
|
|
1506
|
+
error?: StepError | undefined;
|
|
1507
|
+
events?: StepEvent[] | undefined;
|
|
1508
|
+
startedAt?: Date | undefined;
|
|
1509
|
+
finishedAt: Date;
|
|
1510
|
+
}
|
|
1070
1511
|
/**
|
|
1071
1512
|
* A structured event a step (or its worker) emits while running — a log line and/or a sub-step
|
|
1072
1513
|
* outcome. The dashboard renders these under the step, so you can see what happened inside a step
|
|
@@ -1319,6 +1760,29 @@ interface StateStore {
|
|
|
1319
1760
|
* Optional: a store that omits it gets {@link saveCheckpointsIfPending} with the whole rows.
|
|
1320
1761
|
*/
|
|
1321
1762
|
settleCheckpointsIfPending?(settlements: StepSettlement[]): Promise<boolean[]>;
|
|
1763
|
+
/**
|
|
1764
|
+
* Settle steps from their results and read them back, in one round trip where the store can: per
|
|
1765
|
+
* entry and in input order, while the row at `(runId, seq)` is still `pending` and its run is not
|
|
1766
|
+
* `cancelled` or `completed` (a late result for a finished run settles nothing), write the result
|
|
1767
|
+
* (see {@link StepResultSettlement} for what keeps its stored value) and resolve the row as it now
|
|
1768
|
+
* reads, without its `input` (as {@link getCheckpointsForSettle} reads it); `null` for an entry
|
|
1769
|
+
* that wrote nothing (the row is absent or already settled, or the run finished). Claims like
|
|
1770
|
+
* {@link settleCheckpointsIfPending}: a later entry for a row an earlier one settled loses, and a
|
|
1771
|
+
* rejection writes nothing. The engine settles a batch of one run's step results through it
|
|
1772
|
+
* without reading the rows first.
|
|
1773
|
+
*
|
|
1774
|
+
* Optional: a store that omits it gets {@link getCheckpointsForSettle} followed by
|
|
1775
|
+
* {@link settleCheckpointsIfPending}.
|
|
1776
|
+
*/
|
|
1777
|
+
settleResultsIfPending?(results: StepResultSettlement[]): Promise<(StepCheckpoint | null)[]>;
|
|
1778
|
+
/**
|
|
1779
|
+
* Write `checkpoint` only if the run has no checkpoint at its `seq` yet; resolves whether it wrote.
|
|
1780
|
+
* The engine writes a step it dispatches for the first time through it, instead of reading the
|
|
1781
|
+
* position first: a row already there (written by a turn it did not see) is then read and acted on.
|
|
1782
|
+
*
|
|
1783
|
+
* Optional: a store that omits it gets a {@link getCheckpoint} before the {@link saveCheckpoint}.
|
|
1784
|
+
*/
|
|
1785
|
+
insertCheckpointIfAbsent?(checkpoint: StepCheckpoint): Promise<boolean>;
|
|
1322
1786
|
/** Used by recovery on boot to find runs to resume (crashed, left `running`). */
|
|
1323
1787
|
listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
|
|
1324
1788
|
/**
|
|
@@ -1341,6 +1805,16 @@ interface StateStore {
|
|
|
1341
1805
|
listOrphanedRuns?(nowMs: number, limit: number, namespace?: string, ownedBy?: OwnedLeaseReclaim): Promise<WorkflowRun[]>;
|
|
1342
1806
|
/** The oldest `pending` runs awaiting dispatch (FIFO, by `createdAt`), capped at `limit`. */
|
|
1343
1807
|
listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
|
|
1808
|
+
/**
|
|
1809
|
+
* Claim up to `limit` of the oldest `pending` runs that no instance holds (no lease, or one that
|
|
1810
|
+
* expired by `nowMs`): lease each to `owner` until `leaseUntilMs` and resolve them as locked, in
|
|
1811
|
+
* one statement where the store can. Rows another claimer is locking right now are skipped, not
|
|
1812
|
+
* waited on (`FOR UPDATE SKIP LOCKED`), so instances polling at once split the backlog instead of
|
|
1813
|
+
* racing for the same rows. `namespace` and the read scope filter like {@link listPendingRuns}.
|
|
1814
|
+
*
|
|
1815
|
+
* Optional: a store that omits it gets {@link listPendingRuns} and a {@link tryLockRun} per run.
|
|
1816
|
+
*/
|
|
1817
|
+
claimPendingRuns?(limit: number, owner: string, leaseUntilMs: number, nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
|
|
1344
1818
|
/**
|
|
1345
1819
|
* Suspended runs whose durable timer is due (`wakeAt <= nowMs`), ready to resume — the most
|
|
1346
1820
|
* overdue first, at most `limit` of them when it is given. Every driving instance polls this each
|
|
@@ -1353,6 +1827,15 @@ interface StateStore {
|
|
|
1353
1827
|
* acquired — so concurrent engine instances never recover the same run twice.
|
|
1354
1828
|
*/
|
|
1355
1829
|
tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
|
|
1830
|
+
/**
|
|
1831
|
+
* {@link tryLockRun}, resolving the run as it reads once locked (`null` when the lease was not
|
|
1832
|
+
* acquired, or the run does not exist): the engine takes a run's lease and reads it in one round
|
|
1833
|
+
* trip where the store can. The read honors the store's read scope like {@link getRun}; a run
|
|
1834
|
+
* outside it is not locked.
|
|
1835
|
+
*
|
|
1836
|
+
* Optional: a store that omits it gets a {@link getRun} and a {@link tryLockRun}.
|
|
1837
|
+
*/
|
|
1838
|
+
tryLockRunAndGet?(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<WorkflowRun | null>;
|
|
1356
1839
|
/**
|
|
1357
1840
|
* Release a run's recovery lease so another instance can pick it up (e.g. once it suspends).
|
|
1358
1841
|
*
|
|
@@ -1433,6 +1916,40 @@ interface StateStore {
|
|
|
1433
1916
|
takeBufferedSignal(token: string): Promise<{
|
|
1434
1917
|
payload: unknown;
|
|
1435
1918
|
} | null>;
|
|
1919
|
+
/**
|
|
1920
|
+
* Take the oldest buffered signal (lowest id) whose token is one of `tokens`, with that token, or
|
|
1921
|
+
* null if none is buffered. Atomic like {@link takeBufferedSignal}: two concurrent callers never
|
|
1922
|
+
* take the same row. `ctx.waitForAny` resolves with it, so when several of its signals are already
|
|
1923
|
+
* buffered the one sent first wins, whichever condition it matches.
|
|
1924
|
+
*
|
|
1925
|
+
* Optional: without it `waitForAny` takes {@link takeBufferedSignal} token by token in the order
|
|
1926
|
+
* the conditions are declared.
|
|
1927
|
+
*/
|
|
1928
|
+
takeOldestBufferedSignal?(tokens: string[]): Promise<{
|
|
1929
|
+
token: string;
|
|
1930
|
+
payload: unknown;
|
|
1931
|
+
} | null>;
|
|
1932
|
+
/**
|
|
1933
|
+
* Record that the signal `id` was sent on `token`, unless it already was: resolves `true` when this
|
|
1934
|
+
* call recorded it (the signal is new) and `false` when an unexpired record for the same `token`
|
|
1935
|
+
* and `id` exists (a re-send). The record lasts until `expiresAt` (epoch ms); a record whose
|
|
1936
|
+
* `expiresAt <= nowMs` counts as absent and is replaced. Atomic: of two concurrent calls with the
|
|
1937
|
+
* same `token` and `id`, exactly one resolves `true`. Backs `engine.signal(token, payload, { id })`.
|
|
1938
|
+
*
|
|
1939
|
+
* Optional: a store without it can't deduplicate signals, and `signal(..., { id })` throws.
|
|
1940
|
+
*/
|
|
1941
|
+
claimSignalId?(token: string, id: string, expiresAt: number, nowMs: number): Promise<boolean>;
|
|
1942
|
+
/**
|
|
1943
|
+
* Delete the record {@link claimSignalId} made for `token` and `id`, if any. The engine calls it
|
|
1944
|
+
* when delivering the signal failed after the claim, so the sender's retry is not taken for a
|
|
1945
|
+
* duplicate.
|
|
1946
|
+
*/
|
|
1947
|
+
releaseSignalId?(token: string, id: string): Promise<void>;
|
|
1948
|
+
/**
|
|
1949
|
+
* Delete up to `limit` signal-id records that expired at or before `nowMs`; resolves how many it
|
|
1950
|
+
* deleted. Expired records are already ignored by {@link claimSignalId}; this only reclaims space.
|
|
1951
|
+
*/
|
|
1952
|
+
deleteExpiredSignalIds?(nowMs: number, limit: number): Promise<number>;
|
|
1436
1953
|
/**
|
|
1437
1954
|
* A page of buffered signals whose token starts with `tokenPrefix`, in insertion (`id`) order,
|
|
1438
1955
|
* starting after `afterId` (exclusive; `undefined` = from the start), at most `limit` rows. The
|
|
@@ -1805,6 +2322,17 @@ interface RunQuery {
|
|
|
1805
2322
|
* Empty array = matches nothing.
|
|
1806
2323
|
*/
|
|
1807
2324
|
workflows?: string[] | undefined;
|
|
2325
|
+
/**
|
|
2326
|
+
* Leave out the runs of these workflows (`workflow NOT IN (...)`), ANDed with everything else.
|
|
2327
|
+
* Empty array = excludes nothing. The run gateway uses it to keep engine bookkeeping runs (the
|
|
2328
|
+
* lifecycle registry) out of a console's lists and counts.
|
|
2329
|
+
*/
|
|
2330
|
+
excludeWorkflows?: string[] | undefined;
|
|
2331
|
+
/**
|
|
2332
|
+
* Only runs last updated at or after this epoch ms (`updated_at >= updatedAfter`), ANDed with
|
|
2333
|
+
* everything else. For a settled run that is when it settled, unless something wrote it since.
|
|
2334
|
+
*/
|
|
2335
|
+
updatedAfter?: number | undefined;
|
|
1808
2336
|
status?: RunStatus | undefined;
|
|
1809
2337
|
/**
|
|
1810
2338
|
* Match any of these statuses (a `status IN (...)` filter). ORed together, and ANDed with the other
|
|
@@ -2018,9 +2546,83 @@ interface SignalWaiter {
|
|
|
2018
2546
|
* group; without threading it through the waiter, the child-await checkpoint comes out untagged and the
|
|
2019
2547
|
* dashboard renders the fan as a sequential chain instead of one parallel group. Undefined for an
|
|
2020
2548
|
* ordinary (non-fan) signal/child await.
|
|
2549
|
+
*
|
|
2550
|
+
* `'$any'` (`ANY_WAIT_GROUP`) marks the waiter as one condition of a `ctx.waitForAny`: a signal
|
|
2551
|
+
* that takes it settles the wait only if no other condition did first, and is buffered again
|
|
2552
|
+
* otherwise (see `wait-any.ts`).
|
|
2021
2553
|
*/
|
|
2022
2554
|
parallelGroup?: string | undefined;
|
|
2023
2555
|
}
|
|
2556
|
+
/** Options for `engine.signal(token, payload, opts)`. */
|
|
2557
|
+
interface SignalOptions {
|
|
2558
|
+
/**
|
|
2559
|
+
* Deduplication id, unique per token — the id of the message, job or webhook delivery that causes
|
|
2560
|
+
* the signal. A signal sent again on the same token with the same id while the first is remembered
|
|
2561
|
+
* (see `idTtl`) is dropped: `signal()` resolves `null` and nothing is delivered or buffered, so a
|
|
2562
|
+
* sender that runs twice (a redelivered message, a retried job) signals once and the first payload
|
|
2563
|
+
* wins. The same id on another token is another signal. Needs a store with `claimSignalId` (every
|
|
2564
|
+
* bundled store).
|
|
2565
|
+
*
|
|
2566
|
+
* If storing the signal fails, `signal()` rejects and the id is forgotten, so a retry gets through.
|
|
2567
|
+
* A duplicate sent on the same engine while the first send is still in flight waits for it, and
|
|
2568
|
+
* sends in its place if it fails. Across instances a concurrent duplicate is dropped at once, so
|
|
2569
|
+
* the sender whose call rejected must retry.
|
|
2570
|
+
*/
|
|
2571
|
+
id?: string | undefined;
|
|
2572
|
+
/**
|
|
2573
|
+
* How long this signal's `id` is remembered (ms, or a duration like `'30d'`). Default: the engine's
|
|
2574
|
+
* `signalIdTtl` (7 days).
|
|
2575
|
+
*/
|
|
2576
|
+
idTtl?: string | number | undefined;
|
|
2577
|
+
}
|
|
2578
|
+
declare const waitConditionValue: unique symbol;
|
|
2579
|
+
/**
|
|
2580
|
+
* What a condition of {@link WorkflowCtx.waitForAny} waits for. Plain data: the same object travels
|
|
2581
|
+
* in a remote workflow's `waitAny` command.
|
|
2582
|
+
*
|
|
2583
|
+
* - `signal`: a signal sent on token `signal` (`engine.signal(token, payload)`); its value is the payload.
|
|
2584
|
+
* - `timer`: `ms` after the wait is first reached, or at `until` (epoch ms); its value is `null`.
|
|
2585
|
+
* - `child`: the run `childId` settling; its value is the run's output (a failed run throws).
|
|
2586
|
+
*/
|
|
2587
|
+
type WaitConditionSpec = {
|
|
2588
|
+
kind: 'signal';
|
|
2589
|
+
signal: string;
|
|
2590
|
+
} | {
|
|
2591
|
+
kind: 'timer';
|
|
2592
|
+
ms?: number | undefined;
|
|
2593
|
+
until?: number | undefined;
|
|
2594
|
+
} | {
|
|
2595
|
+
kind: 'child';
|
|
2596
|
+
childId: string;
|
|
2597
|
+
};
|
|
2598
|
+
/**
|
|
2599
|
+
* A condition for {@link WorkflowCtx.waitForAny}, made by `ctx.signalWait()`, `ctx.timer()` or
|
|
2600
|
+
* `ctx.childWait()`. `T` is the value it resolves with (type-only). Only a description: nothing is
|
|
2601
|
+
* waited for, and nothing journaled, until it is passed to `waitForAny`.
|
|
2602
|
+
*/
|
|
2603
|
+
type WaitCondition<T = unknown> = WaitConditionSpec & {
|
|
2604
|
+
/** Type-only: the `value` `waitForAny()` returns when this condition wins. Never set. */
|
|
2605
|
+
readonly [waitConditionValue]?: T;
|
|
2606
|
+
};
|
|
2607
|
+
/** One condition of a remote `waitAny` command: the spec plus its key in the conditions object. */
|
|
2608
|
+
type WaitAnyCondition = WaitConditionSpec & {
|
|
2609
|
+
key: string;
|
|
2610
|
+
};
|
|
2611
|
+
/** What a `waitForAny` resolved with, untyped: the winning condition's key and its value. */
|
|
2612
|
+
interface WaitAnyOutcome {
|
|
2613
|
+
key: string;
|
|
2614
|
+
value: unknown;
|
|
2615
|
+
}
|
|
2616
|
+
/**
|
|
2617
|
+
* What `ctx.waitForAny(name, conditions)` resolves with: the key of the condition that won and its
|
|
2618
|
+
* value, typed per key (check `key` to narrow `value`).
|
|
2619
|
+
*/
|
|
2620
|
+
type WaitAnyResult<C extends Record<string, WaitCondition<unknown>>> = {
|
|
2621
|
+
[K in keyof C & string]: {
|
|
2622
|
+
key: K;
|
|
2623
|
+
value: C[K] extends WaitCondition<infer T> ? T : never;
|
|
2624
|
+
};
|
|
2625
|
+
}[keyof C & string];
|
|
2024
2626
|
/**
|
|
2025
2627
|
* A DB-less tenant worker → control plane request to start a run. Published by a worker that has
|
|
2026
2628
|
* no direct DB access (the hosted-control-plane tenant model) onto the
|
|
@@ -2102,6 +2704,12 @@ type RunRequestKind = {
|
|
|
2102
2704
|
} | {
|
|
2103
2705
|
kind: 'waitingFor';
|
|
2104
2706
|
runIds: string[];
|
|
2707
|
+
} | {
|
|
2708
|
+
kind: 'republishLifecycle';
|
|
2709
|
+
target: RepublishLifecycleTarget;
|
|
2710
|
+
} | {
|
|
2711
|
+
kind: 'workflowLifecycle';
|
|
2712
|
+
workflow: string;
|
|
2105
2713
|
};
|
|
2106
2714
|
/** The control plane's answer to a {@link RunRequest}, correlated by `requestId`. */
|
|
2107
2715
|
interface RunReply {
|
|
@@ -2158,6 +2766,14 @@ interface RemoteTask {
|
|
|
2158
2766
|
*/
|
|
2159
2767
|
priority?: number | undefined;
|
|
2160
2768
|
attempt: number;
|
|
2769
|
+
/**
|
|
2770
|
+
* The engine instance that dispatched the task and wants its result back, when the transport
|
|
2771
|
+
* routes replies ({@link Transport.consumeRepliesFor}): that instance keeps the workflow body
|
|
2772
|
+
* parked on the step, so its result continues the body there instead of replaying it elsewhere.
|
|
2773
|
+
* A worker sends the result to that instance while it is alive, else to the shared results, like
|
|
2774
|
+
* a task without it. Absent when replies are not routed (a step fan's tasks never carry it).
|
|
2775
|
+
*/
|
|
2776
|
+
replyTo?: string | undefined;
|
|
2161
2777
|
}
|
|
2162
2778
|
interface StepResult {
|
|
2163
2779
|
runId: string;
|
|
@@ -2215,9 +2831,14 @@ interface WorkflowTask {
|
|
|
2215
2831
|
/** One resolved durable op in a run's history — a superset of a completed {@link StepCheckpoint}. */
|
|
2216
2832
|
interface HistoryEvent {
|
|
2217
2833
|
seq: number;
|
|
2218
|
-
kind: 'step' | 'call' | 'timer' | 'signal' | 'child';
|
|
2834
|
+
kind: 'step' | 'call' | 'timer' | 'signal' | 'child' | 'any';
|
|
2835
|
+
/** The op's name. For `any`, the `waitForAny` name. */
|
|
2219
2836
|
name?: string | undefined;
|
|
2220
|
-
/**
|
|
2837
|
+
/**
|
|
2838
|
+
* Resolved value: a step/call output, a child run's output, a signal payload. For `any`, the
|
|
2839
|
+
* `{ key, value }` the wait resolved with (a winning child's output unwrapped; a failed child
|
|
2840
|
+
* sets `error` and leaves `{ key }`).
|
|
2841
|
+
*/
|
|
2221
2842
|
output?: unknown;
|
|
2222
2843
|
/** Set when the op resolved to a failure (e.g. a failed remote step the workflow may catch). */
|
|
2223
2844
|
error?: StepError | undefined;
|
|
@@ -2267,6 +2888,16 @@ type WorkflowCommand =
|
|
|
2267
2888
|
seq: number;
|
|
2268
2889
|
signal: string;
|
|
2269
2890
|
}
|
|
2891
|
+
/** `ctx.waitForAny(name, conditions)` — block until the first of `conditions` happens. The engine
|
|
2892
|
+
* resolves it exactly as the in-process ctx does (see `wait-any.ts`), journals `{ key, value }` at
|
|
2893
|
+
* `seq` and replays it as an `any` {@link HistoryEvent}. A timer's `ms` counts from when the engine
|
|
2894
|
+
* first applies the command. */
|
|
2895
|
+
| {
|
|
2896
|
+
kind: 'waitAny';
|
|
2897
|
+
seq: number;
|
|
2898
|
+
name: string;
|
|
2899
|
+
conditions: WaitAnyCondition[];
|
|
2900
|
+
}
|
|
2270
2901
|
/** `ctx.start_child(workflow, input)` — start a child run with its own lifecycle. A worker's
|
|
2271
2902
|
* `ctx.all([...])` fan-out tags every dispatched child with the same `parallelGroup` so the
|
|
2272
2903
|
* dashboard can render the fan as one group (parity with the gathered `recordStep` tag). */
|
|
@@ -2415,6 +3046,14 @@ interface Transport {
|
|
|
2415
3046
|
dispatchMany?(tasks: RemoteTask[]): Promise<void>;
|
|
2416
3047
|
/** worker → engine: a step finished (ok or error). */
|
|
2417
3048
|
onResult(handler: (result: StepResult) => Promise<void>): void;
|
|
3049
|
+
/**
|
|
3050
|
+
* Also consume the results workers address to engine instance `replyTo` (tasks dispatched with
|
|
3051
|
+
* {@link RemoteTask.replyTo}), handing them to the {@link onResult} handlers. A transport that
|
|
3052
|
+
* implements it must never lose such a result: while `replyTo` is gone (crashed, scaled down,
|
|
3053
|
+
* drained), its results go, or are moved, to the shared results. Optional: a transport without it
|
|
3054
|
+
* gets tasks without `replyTo`, and every result comes back on the shared results.
|
|
3055
|
+
*/
|
|
3056
|
+
consumeRepliesFor?(replyTo: string): void;
|
|
2418
3057
|
/** worker → engine: liveness signal for an in-flight long step. */
|
|
2419
3058
|
onHeartbeat(handler: (beat: Heartbeat) => Promise<void>): void;
|
|
2420
3059
|
/** Release the transport's resources (broker workers, queues, connections) for a clean shutdown.
|
|
@@ -2667,7 +3306,24 @@ interface ChildCallOptions {
|
|
|
2667
3306
|
* (TS class) child, which runs in the engine and never hits a broker queue.
|
|
2668
3307
|
*/
|
|
2669
3308
|
priority?: number | undefined;
|
|
3309
|
+
/**
|
|
3310
|
+
* What happens to this child if it is still running when its parent ends:
|
|
3311
|
+
*
|
|
3312
|
+
* - `'cancel'`: cancelled with its saga undo (`cancel(child, { compensate: true })`);
|
|
3313
|
+
* - `'terminate'`: cancelled without compensating (`cancel(child)`);
|
|
3314
|
+
* - `'abandon'`: left running, also when the parent is CANCELLED (the cancel cascade skips it).
|
|
3315
|
+
*
|
|
3316
|
+
* Applied when the parent completes or fails in a workflow turn. A cancelled or timed-out parent
|
|
3317
|
+
* keeps cascading its cancel to its children as before, except `'abandon'` ones. Omitted: today's
|
|
3318
|
+
* behaviour (a finished parent leaves its children alone; a cancelled one cascades). In-process
|
|
3319
|
+
* (TS class) parents only: a workflow replayed by a remote worker ignores it.
|
|
3320
|
+
*/
|
|
3321
|
+
parentClose?: ParentClosePolicy | undefined;
|
|
2670
3322
|
}
|
|
3323
|
+
/** See {@link ChildCallOptions.parentClose}. */
|
|
3324
|
+
type ParentClosePolicy = 'cancel' | 'terminate' | 'abandon';
|
|
3325
|
+
/** The tag a child started with a `parentClose` policy carries: `parent-close:<policy>`. */
|
|
3326
|
+
declare const PARENT_CLOSE_TAG_PREFIX = "parent-close:";
|
|
2671
3327
|
interface StepOptions {
|
|
2672
3328
|
/** Max attempts before the step (and run) fails. */
|
|
2673
3329
|
retries?: number;
|
|
@@ -2807,6 +3463,11 @@ interface StepUndo<TInput, TOutput> {
|
|
|
2807
3463
|
* see {@link StepRef}); `Awaited<R>` unwraps a `Promise<TOutput>` return down to `TOutput`.
|
|
2808
3464
|
*/
|
|
2809
3465
|
type UndoOf<H> = H extends (input: infer I, ...rest: never[]) => infer R ? StepUndo<I, Awaited<R>> : never;
|
|
3466
|
+
/** Options for `ctx.waitForRun`. */
|
|
3467
|
+
interface WaitForRunOptions {
|
|
3468
|
+
/** Give up after this long (ms, or a duration like `'30m'`), throwing `SignalTimeoutError`. */
|
|
3469
|
+
timeoutMs?: number | string | undefined;
|
|
3470
|
+
}
|
|
2810
3471
|
/**
|
|
2811
3472
|
* The context handed to a workflow function. Every interaction with the outside world goes
|
|
2812
3473
|
* through it so the engine can checkpoint — the workflow body itself stays deterministic.
|
|
@@ -2893,6 +3554,46 @@ interface WorkflowCtx<A extends SearchAttributes = SearchAttributes> {
|
|
|
2893
3554
|
waitForSignal<TPayload>(token: string, opts?: {
|
|
2894
3555
|
timeoutMs?: number;
|
|
2895
3556
|
}): Promise<TPayload>;
|
|
3557
|
+
/**
|
|
3558
|
+
* Durable wait for whichever of several conditions happens first: a signal
|
|
3559
|
+
* ({@link signalWait}), a timer ({@link timer}) or a run settling ({@link childWait}). Resolves with
|
|
3560
|
+
* the winner's key and its value — a signal's payload, `null` for a timer, a child's output (a
|
|
3561
|
+
* child that failed throws, as {@link child} does) — journaled under `name` at ONE position, so a
|
|
3562
|
+
* replay returns the same winner.
|
|
3563
|
+
*
|
|
3564
|
+
* Only the winning signal is consumed: a signal that matched another condition stays buffered for
|
|
3565
|
+
* a later wait on its token. A losing timer never fires; a losing child keeps running, and a later
|
|
3566
|
+
* `ctx.child(..., childId)` still joins it. When several conditions are ready at once the signal
|
|
3567
|
+
* sent first wins (lowest buffered id), then a child that already finished, then the earliest due
|
|
3568
|
+
* timer. A signal that arrives after a timer's deadline loses to it, even if no worker ran at the
|
|
3569
|
+
* deadline. Timers count from when the wait is first reached.
|
|
3570
|
+
*
|
|
3571
|
+
* ```ts
|
|
3572
|
+
* const outcome = await ctx.waitForAny('delivery-or-cancel', {
|
|
3573
|
+
* delivered: ctx.signalWait<CarrierEvent>(`shipment.delivered:${order.id}`),
|
|
3574
|
+
* cancelled: ctx.signalWait<{ reason: string }>(`order.cancelled:${order.id}`),
|
|
3575
|
+
* timeout: ctx.timer('3d'),
|
|
3576
|
+
* });
|
|
3577
|
+
* if (outcome.key === 'delivered') await ctx.step(thank, outcome.value);
|
|
3578
|
+
* ```
|
|
3579
|
+
*/
|
|
3580
|
+
waitForAny<C extends Record<string, WaitCondition<unknown>>>(name: string, conditions: C): Promise<WaitAnyResult<C>>;
|
|
3581
|
+
/** A signal condition for {@link waitForAny}: a signal sent on `token`. Its value is the payload. */
|
|
3582
|
+
signalWait<TPayload = unknown>(token: string): WaitCondition<TPayload>;
|
|
3583
|
+
/**
|
|
3584
|
+
* A timer condition for {@link waitForAny}: `duration` (ms, or `'30m'`, `'3d'`…) after the wait is
|
|
3585
|
+
* first reached, or at `{ until }` (a `Date` or epoch ms). Its value is `null`.
|
|
3586
|
+
*/
|
|
3587
|
+
timer(duration: string | number | {
|
|
3588
|
+
until: Date | number;
|
|
3589
|
+
}): WaitCondition<null>;
|
|
3590
|
+
/**
|
|
3591
|
+
* A child condition for {@link waitForAny}: run `childId` settling (a child from
|
|
3592
|
+
* {@link startChild}, or any run id). Its value is the run's output; a run that failed, was
|
|
3593
|
+
* cancelled or died makes `waitForAny` throw. Pass the workflow class first to type the output.
|
|
3594
|
+
*/
|
|
3595
|
+
childWait<C extends WorkflowClass>(workflow: C, childId: string): WaitCondition<WorkflowOutputOf<C>>;
|
|
3596
|
+
childWait<TOutput = unknown>(childId: string): WaitCondition<TOutput>;
|
|
2896
3597
|
/**
|
|
2897
3598
|
* Wait for a named **event** published via `engine.publishEvent(name, payload)`, then resume with
|
|
2898
3599
|
* the payload. Unlike a signal (point-to-point by token), events are name-based pub/sub: pass an
|
|
@@ -2904,6 +3605,18 @@ interface WorkflowCtx<A extends SearchAttributes = SearchAttributes> {
|
|
|
2904
3605
|
match?: Record<string, unknown>;
|
|
2905
3606
|
timeoutMs?: number;
|
|
2906
3607
|
}): Promise<TPayload>;
|
|
3608
|
+
/**
|
|
3609
|
+
* Wait for **any** run, not only a child, to settle, and resume with its
|
|
3610
|
+
* {@link WorkflowLifecycleEvent}: `status`, plus `output` on a completed run or `error` on one that
|
|
3611
|
+
* failed, was cancelled or died. Resolves at once when the run already settled; a run that
|
|
3612
|
+
* continued as new settles when the last run of its chain does. `timeoutMs` (ms, or a duration
|
|
3613
|
+
* like `'1h'`) bounds the wait and throws `SignalTimeoutError`. A run id that does not exist fails
|
|
3614
|
+
* with a non-retryable `run <id> not found`. No compute consumed while waiting.
|
|
3615
|
+
*
|
|
3616
|
+
* Pass the workflow class first to type the event by that workflow's input and output.
|
|
3617
|
+
*/
|
|
3618
|
+
waitForRun<TOutput = unknown>(runId: string, opts?: WaitForRunOptions): Promise<WorkflowLifecycleEvent<unknown, TOutput>>;
|
|
3619
|
+
waitForRun<C extends WorkflowClass>(workflow: C, runId: string, opts?: WaitForRunOptions): Promise<LifecycleEventOf<C>>;
|
|
2907
3620
|
/**
|
|
2908
3621
|
* An external task with **async completion**: run `dispatch` once (checkpointed — e.g. send to a
|
|
2909
3622
|
* queue, kick off a non-durable worker or a foreign service like a Python process), then suspend
|
|
@@ -3117,7 +3830,7 @@ type UpdateResult = {
|
|
|
3117
3830
|
accepted: true;
|
|
3118
3831
|
run: RunResult | null;
|
|
3119
3832
|
};
|
|
3120
|
-
type EngineEventType = 'run.started' | 'run.completed' | 'run.failed' | 'run.suspended' | 'step.started' | 'step.completed' | 'step.failed' | 'step.progress' | 'run.blocked' | 'run.routed' | 'run.unrouted';
|
|
3833
|
+
type EngineEventType = 'run.started' | 'run.completed' | 'run.failed' | 'run.suspended' | 'step.started' | 'step.completed' | 'step.failed' | 'step.progress' | 'run.blocked' | 'run.routed' | 'run.unrouted' | 'run.triggered' | 'run.trigger_failed';
|
|
3121
3834
|
/**
|
|
3122
3835
|
* A lifecycle event emitted by the engine. The observability surfaces (dashboard, OTel, the
|
|
3123
3836
|
* Telescope integration) all subscribe to these rather than reaching into the store.
|
|
@@ -3159,6 +3872,14 @@ interface EngineEvent {
|
|
|
3159
3872
|
diagnostics?: DispatchDiagnostics | undefined;
|
|
3160
3873
|
/** Why a `run.unrouted` run's onError routes were not applied. */
|
|
3161
3874
|
reason?: string | undefined;
|
|
3875
|
+
/** The run a `run.triggered` event started. */
|
|
3876
|
+
triggeredRunId?: string | undefined;
|
|
3877
|
+
/**
|
|
3878
|
+
* On the `run.started` of a run a lifecycle event started: the W3C traceparent of the source run's
|
|
3879
|
+
* span, when it is known (see `WorkflowEngine.setRunTraceparent`). A tracer links the run's span
|
|
3880
|
+
* to it.
|
|
3881
|
+
*/
|
|
3882
|
+
sourceTraceparent?: string | undefined;
|
|
3162
3883
|
at: Date;
|
|
3163
3884
|
}
|
|
3164
3885
|
type EngineListener = (event: EngineEvent) => void;
|
|
@@ -3475,14 +4196,21 @@ declare class Entities {
|
|
|
3475
4196
|
private run;
|
|
3476
4197
|
}
|
|
3477
4198
|
|
|
3478
|
-
/**
|
|
4199
|
+
/**
|
|
4200
|
+
* How `onEvent` triggers are coalesced into fewer runs (see `@Workflow({ debounce | batch })`).
|
|
4201
|
+
* `key` splits the coalescing per key: it receives each trigger's input (after the subscription's
|
|
4202
|
+
* `input` mapping) and triggers with the same key share one accumulator, so a burst for one key
|
|
4203
|
+
* starts one run without holding back or swallowing another key's.
|
|
4204
|
+
*/
|
|
3479
4205
|
type EventBatchConfig = {
|
|
3480
4206
|
mode: 'debounce';
|
|
3481
4207
|
windowMs: number;
|
|
4208
|
+
key?: ((input: unknown) => string) | undefined;
|
|
3482
4209
|
} | {
|
|
3483
4210
|
mode: 'batch';
|
|
3484
4211
|
maxSize: number;
|
|
3485
4212
|
windowMs: number;
|
|
4213
|
+
key?: ((input: unknown) => string) | undefined;
|
|
3486
4214
|
};
|
|
3487
4215
|
/** The slice of the engine the accumulators need (so they stay a standalone module). */
|
|
3488
4216
|
interface AccumulatorHost {
|
|
@@ -3496,6 +4224,18 @@ interface AccumulatorHost {
|
|
|
3496
4224
|
runId: string;
|
|
3497
4225
|
}>;
|
|
3498
4226
|
}
|
|
4227
|
+
/**
|
|
4228
|
+
* The accumulator run id, which is also its signal token. Without a key it is the target's alone;
|
|
4229
|
+
* with one, the key is percent-encoded (`~` and the other characters `encodeURIComponent` keeps
|
|
4230
|
+
* included), so any string makes a safe id that cannot read as a continue-as-new suffix.
|
|
4231
|
+
*/
|
|
4232
|
+
declare function accumulatorRunId(target: string, key?: string): string;
|
|
4233
|
+
/**
|
|
4234
|
+
* How many routed event ids an accumulator remembers across bursts, so an event routed twice (a
|
|
4235
|
+
* lifecycle event published by two instances, or again by the sweep) counts once. The newest ids
|
|
4236
|
+
* are kept.
|
|
4237
|
+
*/
|
|
4238
|
+
declare const ACCUMULATOR_SEEN_MAX = 1000;
|
|
3499
4239
|
/**
|
|
3500
4240
|
* Built-in workflows that coalesce `onEvent` triggers. Each is a long-lived per-target accumulator
|
|
3501
4241
|
* fed by `signalWithStart`: it collects payloads then starts the target once, and `continueAsNew`s to
|
|
@@ -3505,8 +4245,12 @@ interface AccumulatorHost {
|
|
|
3505
4245
|
declare class EventAccumulators {
|
|
3506
4246
|
private readonly host;
|
|
3507
4247
|
constructor(host: AccumulatorHost);
|
|
3508
|
-
/**
|
|
3509
|
-
|
|
4248
|
+
/**
|
|
4249
|
+
* Route an `onEvent` payload into its target's debounce/batch accumulator: the target's one, or
|
|
4250
|
+
* with a `key`, the one for `String(config.key(payload))`. A `key` that throws rejects the route.
|
|
4251
|
+
* With `id`, the accumulator counts the event once however many times it is routed.
|
|
4252
|
+
*/
|
|
4253
|
+
route(target: string, config: EventBatchConfig, payload: unknown, id?: string): Promise<{
|
|
3510
4254
|
runId: string;
|
|
3511
4255
|
}>;
|
|
3512
4256
|
/** Fire the target with the LAST payload once events have been quiet for `windowMs`. */
|
|
@@ -3515,6 +4259,58 @@ declare class EventAccumulators {
|
|
|
3515
4259
|
private batch;
|
|
3516
4260
|
}
|
|
3517
4261
|
|
|
4262
|
+
/**
|
|
4263
|
+
* How many candidates a buffered-event scan considers (`listBufferedEvents(name, limit)`) before
|
|
4264
|
+
* giving up. An event's buffer is keyed by `name` only (see {@link eventMatches}'s match-based
|
|
4265
|
+
* consumption), so a hot name with many distinct payloads sitting unclaimed could in principle
|
|
4266
|
+
* accumulate an unbounded backlog; this caps the per-scan cost regardless. Shared by the workflow-ctx
|
|
4267
|
+
* consumer and the engine's reconcile sweep so both see the same window.
|
|
4268
|
+
*/
|
|
4269
|
+
declare const EVENT_BUFFER_SCAN_LIMIT = 50;
|
|
4270
|
+
/** The literal prefix EVERY event-waiter token starts with, regardless of `name` — `eventPrefix(name)`
|
|
4271
|
+
* always begins with this; exported so a caller that only needs to CLASSIFY a token (not fan out a
|
|
4272
|
+
* specific name) doesn't have to re-derive or duplicate the literal (see run-waiting.ts's own copy,
|
|
4273
|
+
* kept in sync with this one, and engine.ts's reconcile sweep). */
|
|
4274
|
+
declare const EVENT_TOKEN_PREFIX = "event:";
|
|
4275
|
+
/** Token prefix for every waiter on `name` — used by `listSignalWaiters` to fan an event out. */
|
|
4276
|
+
declare function eventPrefix(name: string): string;
|
|
4277
|
+
/** Whether `token` is an event-waiter token (vs. a plain signal / child / webhook / breakpoint one). */
|
|
4278
|
+
declare function isEventToken(token: string): boolean;
|
|
4279
|
+
/** Build the unique waiter token for one `waitForEvent` call (name + match + run position). */
|
|
4280
|
+
declare function eventToken(name: string, match: Record<string, unknown> | undefined, runId: string, seq: number): string;
|
|
4281
|
+
/** The event name embedded in an event waiter token (the 2nd `:`-segment is the base64 name), so a
|
|
4282
|
+
* dashboard can show "waiting on event `<name>`" instead of the opaque token. */
|
|
4283
|
+
declare function eventNameOf(token: string): string;
|
|
4284
|
+
/** The match criteria embedded in an event waiter token (the 3rd `:`-segment is the base64 match). */
|
|
4285
|
+
declare function eventMatchOf(token: string): Record<string, unknown>;
|
|
4286
|
+
/** Whether `payload` satisfies a waiter's `match`: every match key deep-equals the payload's value. */
|
|
4287
|
+
declare function eventMatches(payload: unknown, match: Record<string, unknown>): boolean;
|
|
4288
|
+
/**
|
|
4289
|
+
* One `onEvent` subscription: the event name, plus an optional `where` that decides, per payload,
|
|
4290
|
+
* whether this workflow starts, and an optional `input` that turns the payload into the started
|
|
4291
|
+
* run's input. A bare string is shorthand for `{ event }`. Both functions run in the publishing
|
|
4292
|
+
* process, so they only exist for subscriptions registered in TypeScript.
|
|
4293
|
+
*/
|
|
4294
|
+
interface EventSubscription {
|
|
4295
|
+
event: string;
|
|
4296
|
+
where?: ((payload: unknown) => boolean) | undefined;
|
|
4297
|
+
/** The started run's input, built from the payload. Defaults to the payload itself. */
|
|
4298
|
+
input?: ((payload: unknown) => unknown) | undefined;
|
|
4299
|
+
}
|
|
4300
|
+
/** An `onEvent` entry: an event name, or a {@link EventSubscription}. */
|
|
4301
|
+
type OnEventEntry = string | EventSubscription;
|
|
4302
|
+
/** Normalize an `onEvent` entry to its {@link EventSubscription} form. */
|
|
4303
|
+
declare function toEventSubscription(entry: OnEventEntry): EventSubscription;
|
|
4304
|
+
/**
|
|
4305
|
+
* Which of one workflow's subscriptions to an event takes `payload`: the first whose `where`
|
|
4306
|
+
* accepts it (a subscription without `where` accepts everything). A `where` that throws counts as
|
|
4307
|
+
* a rejection, and its error is returned so the caller can report it instead of losing it.
|
|
4308
|
+
*/
|
|
4309
|
+
declare function acceptingSubscription(subscriptions: readonly EventSubscription[], payload: unknown): {
|
|
4310
|
+
accepted?: EventSubscription;
|
|
4311
|
+
errors: unknown[];
|
|
4312
|
+
};
|
|
4313
|
+
|
|
3518
4314
|
/**
|
|
3519
4315
|
* The announced workflow registry (design §7.9) — the aggregate answer to "what workflows exist in
|
|
3520
4316
|
* this deployment?", built ONLY from what live workers say about themselves.
|
|
@@ -3640,6 +4436,10 @@ interface AnnouncedWorkflow {
|
|
|
3640
4436
|
code?: string;
|
|
3641
4437
|
workflow: string;
|
|
3642
4438
|
}[][];
|
|
4439
|
+
/** Every event any live announcer says this workflow subscribes to (sorted, de-duplicated). Empty =
|
|
4440
|
+
* nobody stated one. A union, not a disagreement: during a rollout the engine owes a lifecycle
|
|
4441
|
+
* event to a subscriber as long as some live worker still has it. */
|
|
4442
|
+
subscribes: string[];
|
|
3643
4443
|
/** Runtimes of the live announcers (sorted, de-duplicated). EMPTY on an `'observed'` entry: a
|
|
3644
4444
|
* heartbeat does not say what runtime wrote it, and the instance id's shape is a convention, not
|
|
3645
4445
|
* a statement, so it is not read as one. */
|
|
@@ -4031,7 +4831,13 @@ interface ScheduleOptions {
|
|
|
4031
4831
|
cron?: string | undefined;
|
|
4032
4832
|
/** Fixed interval (`'15m'`, or ms), windows aligned to the epoch. Exclusive with `cron`. */
|
|
4033
4833
|
every?: string | number | undefined;
|
|
4034
|
-
/**
|
|
4834
|
+
/**
|
|
4835
|
+
* An RFC 5545 recurrence rule (`'FREQ=WEEKLY;BYDAY=MO;BYHOUR=8'`, optionally with a
|
|
4836
|
+
* `DTSTART:…` line), evaluated in `timezone`. Exactly one of `cron`, `every` and `rrule`. See
|
|
4837
|
+
* {@link parseRRule} for the supported parts. No peer needed.
|
|
4838
|
+
*/
|
|
4839
|
+
rrule?: string | undefined;
|
|
4840
|
+
/** IANA timezone the cron / rrule is evaluated in (e.g. `America/Sao_Paulo`). Default UTC. */
|
|
4035
4841
|
timezone?: string | undefined;
|
|
4036
4842
|
/**
|
|
4037
4843
|
* Delay each fire by up to this much (`'30s'` or ms) — a stable per-(schedule, window) offset, so
|
|
@@ -4076,6 +4882,7 @@ interface ScheduleDescription {
|
|
|
4076
4882
|
namespace: string;
|
|
4077
4883
|
cron?: string | undefined;
|
|
4078
4884
|
everyMs?: number | undefined;
|
|
4885
|
+
rrule?: string | undefined;
|
|
4079
4886
|
timezone?: string | undefined;
|
|
4080
4887
|
jitterMs?: number | undefined;
|
|
4081
4888
|
overlap: 'allow' | 'skip';
|
|
@@ -4543,6 +5350,13 @@ interface WorkflowEngineDeps {
|
|
|
4543
5350
|
* bug to route around here.
|
|
4544
5351
|
*/
|
|
4545
5352
|
eventBufferTtlMs?: number | undefined;
|
|
5353
|
+
/**
|
|
5354
|
+
* How long `signal(token, payload, { id })` remembers an `id` (ms, or a duration like `'7d'`): a
|
|
5355
|
+
* re-send with the same token and id within it is dropped. Records past it are ignored, and
|
|
5356
|
+
* {@link WorkflowEngine.sweepExpiredSignalIds} deletes them. Keep it longer than any sender's
|
|
5357
|
+
* redelivery window. Default 7 days; a call can pass its own `idTtl`.
|
|
5358
|
+
*/
|
|
5359
|
+
signalIdTtl?: string | number | undefined;
|
|
4546
5360
|
/**
|
|
4547
5361
|
* Opt-in self-heal window (ms) for a remote step with NO `timeoutMs` whose dispatched job was LOST —
|
|
4548
5362
|
* the worker crashed mid-step leaving no result, or the transport dropped the job (a Redis
|
|
@@ -4572,6 +5386,14 @@ interface WorkflowEngineDeps {
|
|
|
4572
5386
|
* AND descriptors are published (a legacy fleet never parks blocked).
|
|
4573
5387
|
*/
|
|
4574
5388
|
blockedPollMs?: number | undefined;
|
|
5389
|
+
/**
|
|
5390
|
+
* How long (ms) the routing guard reuses the worker descriptors it read for a queue token before
|
|
5391
|
+
* reading them again. Every dispatch consults them, and on BullMQ each read is a `SCAN` of the
|
|
5392
|
+
* Redis keyspace; workers rewrite their descriptor every 10 s with a 35 s TTL, so a couple of
|
|
5393
|
+
* seconds of reuse changes nothing the guard can observe. Concurrent reads of one token share a
|
|
5394
|
+
* single request. Default 2000; `0` reads on every dispatch.
|
|
5395
|
+
*/
|
|
5396
|
+
workerDescriptorCacheMs?: number | undefined;
|
|
4575
5397
|
/**
|
|
4576
5398
|
* Build the public callback URL for a `ctx.webhook()` token (e.g.
|
|
4577
5399
|
* ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
|
|
@@ -4631,6 +5453,26 @@ interface WorkflowEngineDeps {
|
|
|
4631
5453
|
* run `runPending` on a worker pod to pick those up; or a broker-backed one for a worker pool.
|
|
4632
5454
|
*/
|
|
4633
5455
|
runDispatcher?: RunDispatcher | undefined;
|
|
5456
|
+
/**
|
|
5457
|
+
* How many parked workflow bodies this instance keeps in memory between turns (the sticky
|
|
5458
|
+
* continuation cache, see `sticky-continuation.ts`). A run whose body parked here on dispatched
|
|
5459
|
+
* `ctx.step` calls continues from where it stopped when its next turn runs on this instance,
|
|
5460
|
+
* instead of replaying from the top over its whole history: the turn re-reads only the steps it
|
|
5461
|
+
* parked on. Least recently used out first; an evicted run just replays. Default 1000 (about 26 KB
|
|
5462
|
+
* of heap per parked body, measured with a small body: ~26 MB at most). `0` turns
|
|
5463
|
+
* the cache off (every turn replays).
|
|
5464
|
+
*/
|
|
5465
|
+
stickyRuns?: number | undefined;
|
|
5466
|
+
/** How long a parked body may sit idle in the sticky cache before it is dropped. Default 5 min. */
|
|
5467
|
+
stickyIdleMs?: number | undefined;
|
|
5468
|
+
/**
|
|
5469
|
+
* Ask the transports that can ({@link Transport.consumeRepliesFor}, e.g. BullMQ) to send the result
|
|
5470
|
+
* of a dispatched `ctx.step` back to this instance, which holds the body parked on it, rather
|
|
5471
|
+
* than to whichever engine instance takes it off the shared results. With several engine
|
|
5472
|
+
* instances, that is what keeps the sticky continuation hitting. A result whose instance is gone
|
|
5473
|
+
* goes to the shared results and replays elsewhere. Default `true` while the sticky cache is on.
|
|
5474
|
+
*/
|
|
5475
|
+
routeReplies?: boolean | undefined;
|
|
4634
5476
|
}
|
|
4635
5477
|
/** Options for {@link WorkflowEngine.listStalledRuns}. */
|
|
4636
5478
|
interface ListStalledRunsOptions {
|
|
@@ -4673,12 +5515,29 @@ declare class WorkflowEngine {
|
|
|
4673
5515
|
private readonly unregisteredWorkflowGraceMs;
|
|
4674
5516
|
private readonly remoteAdvanceSilenceMs?;
|
|
4675
5517
|
private readonly reconcileMs;
|
|
5518
|
+
/** Parked workflow bodies kept between turns (see {@link WorkflowEngineDeps.stickyRuns}). */
|
|
5519
|
+
private readonly sticky;
|
|
5520
|
+
/** Pending runs claimed by {@link runPending} for the turn about to run them, as read by the claim. */
|
|
5521
|
+
private readonly claimedRuns;
|
|
5522
|
+
/** The continuation each turn executing here runs in, by run id, while the turn runs. */
|
|
5523
|
+
private readonly turnContinuations;
|
|
5524
|
+
/** Whether to ask transports to route step results back here (see {@link WorkflowEngineDeps.routeReplies}). */
|
|
5525
|
+
private readonly routeReplies;
|
|
5526
|
+
/** Whether a transport routes this instance's step results back to it. */
|
|
5527
|
+
private repliesRouted;
|
|
5528
|
+
/** The run row stamp (`updatedAt`, epoch ms) a turn here wrote when it settled `suspended`. */
|
|
5529
|
+
private readonly suspendStamps;
|
|
4676
5530
|
private readonly timerBatchSize;
|
|
4677
5531
|
private readonly eventBufferTtlMs;
|
|
5532
|
+
private readonly signalIdTtlMs;
|
|
5533
|
+
/** The deduplicated {@link signal} sends in flight here, by `token \u0000 id`. */
|
|
5534
|
+
private readonly signalIdSends;
|
|
4678
5535
|
private readonly remoteRedispatchMs;
|
|
4679
5536
|
private readonly remoteRedispatchMax;
|
|
4680
5537
|
/** How long a `blocked` run waits before the recovery poll re-checks the live fleet (design §7.5). */
|
|
4681
5538
|
private readonly blockedPollMs;
|
|
5539
|
+
private readonly workerDescriptorCacheMs;
|
|
5540
|
+
private readonly descriptorCache;
|
|
4682
5541
|
/** This engine's control-plane handshake descriptor — negotiated against each worker (design §7.3). */
|
|
4683
5542
|
private readonly cpDescriptor;
|
|
4684
5543
|
private readonly webhookUrl?;
|
|
@@ -4703,7 +5562,7 @@ declare class WorkflowEngine {
|
|
|
4703
5562
|
private readonly workflows;
|
|
4704
5563
|
/** The newest registered version per workflow name — used to `start` new runs. */
|
|
4705
5564
|
private readonly latest;
|
|
4706
|
-
/** Event name → workflow
|
|
5565
|
+
/** Event name → subscribing workflow name → that workflow's subscriptions to it. See `onEvent`. */
|
|
4707
5566
|
private readonly eventTriggers;
|
|
4708
5567
|
/** Durable-entity subsystem (registers the `__entity` runner; see `registerEntity`). */
|
|
4709
5568
|
private readonly entities;
|
|
@@ -4833,6 +5692,8 @@ declare class WorkflowEngine {
|
|
|
4833
5692
|
private readonly claimsMade;
|
|
4834
5693
|
/** Pager hooks for stranded runs (see {@link onStalled}). */
|
|
4835
5694
|
private readonly stalledListeners;
|
|
5695
|
+
/** `parentClose` policies recorded by the turn in flight, per parent run (see {@link settleParentClose}). */
|
|
5696
|
+
private readonly parentCloseIntents;
|
|
4836
5697
|
/** Runs already paged about, by id → the `updatedAt` of the paged episode (see {@link sweepStalled}). */
|
|
4837
5698
|
private readonly notifiedStalled;
|
|
4838
5699
|
private lastStalledSweepAt;
|
|
@@ -4959,7 +5820,7 @@ declare class WorkflowEngine {
|
|
|
4959
5820
|
validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
|
|
4960
5821
|
/** Typed/validated `searchAttributes` shape — see `RegisteredWorkflow.searchAttributesSchema`. */
|
|
4961
5822
|
searchAttributesSchema?: SearchAttributesSchema | undefined;
|
|
4962
|
-
onEvent?:
|
|
5823
|
+
onEvent?: OnEventEntry[] | undefined;
|
|
4963
5824
|
eventBatch?: EventBatchConfig | undefined;
|
|
4964
5825
|
/** Worker group to DISPATCH this workflow's turns to (uniform dispatch). Requires `executor`.
|
|
4965
5826
|
* Omit for the default inline fast path. See the method doc. */
|
|
@@ -5095,6 +5956,13 @@ declare class WorkflowEngine {
|
|
|
5095
5956
|
* store without `listBufferedSignals`/`deleteBufferedSignals`. Returns how many rows it deleted.
|
|
5096
5957
|
*/
|
|
5097
5958
|
sweepBufferedSignals(now?: number, budgetMs?: number): Promise<number>;
|
|
5959
|
+
/**
|
|
5960
|
+
* Delete the signal-id records (`signal(..., { id })`) that expired by `now`, in batches of
|
|
5961
|
+
* {@link SIGNAL_ID_SWEEP_BATCH}, at most `maxBatches` per call. Expired records already stop
|
|
5962
|
+
* deduplicating; this reclaims their rows. The NestJS timer poller calls it every tick. Returns how
|
|
5963
|
+
* many it deleted; 0 on a store without `deleteExpiredSignalIds`.
|
|
5964
|
+
*/
|
|
5965
|
+
sweepExpiredSignalIds(now?: number, maxBatches?: number): Promise<number>;
|
|
5098
5966
|
/**
|
|
5099
5967
|
* Register a pager hook for STRANDED runs: an in-flight run untouched past `stalledAfterMs` that is
|
|
5100
5968
|
* either suspended with NO wake timer (wake-forever: nothing will ever re-drive it) or parked on an
|
|
@@ -5123,9 +5991,310 @@ declare class WorkflowEngine {
|
|
|
5123
5991
|
*/
|
|
5124
5992
|
listStalledRuns(options?: ListStalledRunsOptions): Promise<StalledRunInfo[]>;
|
|
5125
5993
|
private notifyDead;
|
|
5126
|
-
/**
|
|
5127
|
-
*
|
|
5994
|
+
/**
|
|
5995
|
+
* Emit a locally-produced lifecycle event: deliver to subscribers AND broadcast it on the control
|
|
5996
|
+
* plane so other instances (e.g. a dashboard pod) can live-tail this run. A `run.completed` or
|
|
5997
|
+
* `run.failed` also publishes the run's lifecycle event (see {@link publishLifecycle}) and resumes
|
|
5998
|
+
* the runs waiting on it with `ctx.waitForRun` (see {@link deliverRunWaits}); `lifecycle: false`
|
|
5999
|
+
* marks a `run.completed` that is not a real completion (a continue-as-new handoff).
|
|
6000
|
+
*/
|
|
5128
6001
|
private emit;
|
|
6002
|
+
/**
|
|
6003
|
+
* Start every workflow subscribed to `name` that takes `payload` (see {@link acceptingSubscription}),
|
|
6004
|
+
* each under `runIdOf(workflow)` and with its subscription's `input` applied. `only` restricts it
|
|
6005
|
+
* to those subscribers. `remote` are subscribers only live workers announce (see
|
|
6006
|
+
* {@link announcedRemoteSubscribers}): each is started by name with the payload as its input, since
|
|
6007
|
+
* an announcement carries no `where` or `input`. `routeIdOf` names the event for a subscriber's
|
|
6008
|
+
* debounce/batch accumulator, which counts an id once. Returns the subscribers reached, with the
|
|
6009
|
+
* run each started (none when the payload went into its debounce/batch accumulator), and the ones
|
|
6010
|
+
* that could not be started, with why.
|
|
6011
|
+
*/
|
|
6012
|
+
private startSubscribers;
|
|
6013
|
+
/**
|
|
6014
|
+
* The subscribers of `event` that live workers announce for the settled runs of `namespace` (`null`:
|
|
6015
|
+
* any namespace, for an event no run published), are not registered on this engine with an `onEvent` for it, and that this engine can start: registered here (a `registerRemote`), or served
|
|
6016
|
+
* by convention on a live worker group of the same name (a Python `@workflow(on_event=...)`). One
|
|
6017
|
+
* this engine cannot start is left to the instances that can, so it stays owed rather than failing.
|
|
6018
|
+
*/
|
|
6019
|
+
private announcedRemoteSubscribers;
|
|
6020
|
+
/** The workflows registered on this engine that subscribe to `event`. */
|
|
6021
|
+
private localSubscribers;
|
|
6022
|
+
/**
|
|
6023
|
+
* Whether some workflow may subscribe to `workflow` settling as `kind`: one registered on this
|
|
6024
|
+
* engine, or one in the last read of the fleet's announcements. True while there is no usable read
|
|
6025
|
+
* (none yet, or the last one failed), since the terminal write then marks the run unresolved (see
|
|
6026
|
+
* {@link withLifecycleMarker}).
|
|
6027
|
+
*/
|
|
6028
|
+
private hasLifecycleSubscribers;
|
|
6029
|
+
/**
|
|
6030
|
+
* Whether this engine's own subscribers apply to the settled runs of `namespace`: an engine with
|
|
6031
|
+
* no namespace publishes the runs of every namespace, a namespaced one only its own.
|
|
6032
|
+
*/
|
|
6033
|
+
private servesNamespace;
|
|
6034
|
+
/** This engine's subscribers of `event` that apply to the settled runs of `namespace`. */
|
|
6035
|
+
private localSubscribersIn;
|
|
6036
|
+
/** Answers the traceparent of a run's span in this process; see {@link setRunTraceparent}. */
|
|
6037
|
+
private runTraceparent;
|
|
6038
|
+
/**
|
|
6039
|
+
* Install the function that answers the W3C `traceparent` of a run's span in this process, or
|
|
6040
|
+
* `undefined` to remove it. `attachDurableOtel` installs one. With it, the first suspend or the
|
|
6041
|
+
* terminal write of a run some workflow subscribes to also records the run's traceparent (a
|
|
6042
|
+
* {@link LIFECYCLE_TRACE_TAG_PREFIX} tag, see {@link withRunTrace}), and the `run.started` of a run
|
|
6043
|
+
* a lifecycle event started carries its source run's as `sourceTraceparent`, so the subscriber's
|
|
6044
|
+
* trace links to the source's.
|
|
6045
|
+
*/
|
|
6046
|
+
setRunTraceparent(provider: ((runId: string) => string | undefined) | undefined): void;
|
|
6047
|
+
/**
|
|
6048
|
+
* `{ sourceTraceparent }` for the `run.started` of `run`, when a lifecycle event started it and a
|
|
6049
|
+
* run trace provider is installed: the source run's recorded traceparent, else this process's.
|
|
6050
|
+
*/
|
|
6051
|
+
private sourceTraceOf;
|
|
6052
|
+
/** The last read of the subscriptions live workers announce. See {@link announcedSubscriptions}. */
|
|
6053
|
+
private announcedSubscriptionsSnapshot;
|
|
6054
|
+
private announcedSubscriptionsRead;
|
|
6055
|
+
/**
|
|
6056
|
+
* The `onEvent` subscriptions the live fleet announces, by event name: the fresh lifecycle
|
|
6057
|
+
* registry runs in the state store (see {@link heartbeatLifecycleRegistry}) and, on a transport
|
|
6058
|
+
* that reads them, each worker descriptor's `subscribes`. Each entry records the namespace its
|
|
6059
|
+
* announcer serves (`null` for an engine with no namespace) and whether a Node engine announced it
|
|
6060
|
+
* (every registry run is one). Read at most once per
|
|
6061
|
+
* {@link ANNOUNCED_ROUTES_TTL_MS}, concurrent callers sharing one read. Never throws: `ok: false`
|
|
6062
|
+
* means a read failed and only the local registry is known.
|
|
6063
|
+
*/
|
|
6064
|
+
private announcedSubscriptions;
|
|
6065
|
+
/**
|
|
6066
|
+
* The last read of the fleet's announcements as it is, without waiting: undefined before the first
|
|
6067
|
+
* read completes. Starts a read in the background when it is missing or older than
|
|
6068
|
+
* {@link ANNOUNCED_ROUTES_TTL_MS}. What the terminal write uses, so settling a run never waits on
|
|
6069
|
+
* the fleet.
|
|
6070
|
+
*/
|
|
6071
|
+
private cachedAnnouncedSubscriptions;
|
|
6072
|
+
/**
|
|
6073
|
+
* When this engine first saw each subscription (`<event>\u0000<subscriber>`), in its registry or in
|
|
6074
|
+
* a good read of the fleet's announcements. The sweep's heal pass looks only at the ones first seen
|
|
6075
|
+
* within {@link LIFECYCLE_HEAL_WINDOW_MS}; see {@link healLifecycleEvents}.
|
|
6076
|
+
*/
|
|
6077
|
+
private readonly subscriptionFirstSeen;
|
|
6078
|
+
/** Record the subscriptions of `snapshot` (a good read) and of this engine's registry as seen. */
|
|
6079
|
+
private noteSubscriptionsSeen;
|
|
6080
|
+
private readAnnouncedSubscriptions;
|
|
6081
|
+
/** How many registry runs one page of {@link listLifecycleRegistry} reads. */
|
|
6082
|
+
private static readonly LIFECYCLE_REGISTRY_PAGE;
|
|
6083
|
+
/**
|
|
6084
|
+
* The lifecycle registry runs this engine's namespace sees: its namespace's, plus `default`'s, where
|
|
6085
|
+
* the engines with no namespace keep theirs. Read a page of
|
|
6086
|
+
* {@link LIFECYCLE_REGISTRY_PAGE} at a time until a short page, so a large fleet is read whole.
|
|
6087
|
+
*/
|
|
6088
|
+
private listLifecycleRegistry;
|
|
6089
|
+
/** When this engine last wrote its registry run, or undefined before the first heartbeat. */
|
|
6090
|
+
private lifecycleRegistryBeatAt;
|
|
6091
|
+
/**
|
|
6092
|
+
* Refresh this engine's lifecycle registry run and delete stale ones. At most once per
|
|
6093
|
+
* {@link LIFECYCLE_REGISTRY_HEARTBEAT_MS}; {@link sweepLifecycleEvents} calls it on every tick.
|
|
6094
|
+
*
|
|
6095
|
+
* An engine with `onEvent` subscriptions keeps one completed run of the internal
|
|
6096
|
+
* {@link LIFECYCLE_REGISTRY_WORKFLOW} workflow, id `__lifecycle_registry:<instanceId>`, holding
|
|
6097
|
+
* them in `input` and its heartbeat in `updatedAt`. Other instances read the fresh ones
|
|
6098
|
+
* ({@link LIFECYCLE_REGISTRY_TTL_MS}) as announced subscriptions, so a settled run is owed to a
|
|
6099
|
+
* subscriber registered only elsewhere whatever the transport. Any engine deletes the runs not
|
|
6100
|
+
* refreshed for {@link LIFECYCLE_REGISTRY_STALE_MS}. Retention never prunes them
|
|
6101
|
+
* ({@link LIFECYCLE_REGISTRY_TAG}), and the run gateway leaves them out of run lists.
|
|
6102
|
+
*/
|
|
6103
|
+
heartbeatLifecycleRegistry(): Promise<void>;
|
|
6104
|
+
/** This engine's `onEvent` subscriptions, by subscribing workflow, as its registry run holds them. */
|
|
6105
|
+
private registrySubscriptions;
|
|
6106
|
+
private writeLifecycleRegistry;
|
|
6107
|
+
/**
|
|
6108
|
+
* The subscribers a run of `workflow` in `namespace` settling as `kind` owes its lifecycle event to:
|
|
6109
|
+
* the ones registered on this engine, when it publishes that namespace's runs (an engine with no
|
|
6110
|
+
* namespace publishes every namespace's), plus the ones live workers announce for that namespace
|
|
6111
|
+
* (see {@link announcedSubscriptions}): by announcers serving it, and by engines with no namespace.
|
|
6112
|
+
* Without `namespace`, every namespace's: what any run of `workflow` could owe. Empty for an
|
|
6113
|
+
* internal `__` workflow.
|
|
6114
|
+
*/
|
|
6115
|
+
lifecycleSubscribers(workflow: string, kind: LifecycleKind, namespace?: string): Promise<string[]>;
|
|
6116
|
+
/** {@link lifecycleSubscribers} from one given read of the fleet's announcements. */
|
|
6117
|
+
private lifecycleSubscribersIn;
|
|
6118
|
+
/**
|
|
6119
|
+
* The subscribers registered here that coalesce `run`'s lifecycle event (debounce/batch) and
|
|
6120
|
+
* accept it, each with the accumulator run the event went to: the subscription's `where`, `input`
|
|
6121
|
+
* and `key` applied to the event as `startSubscribers` does. Undefined when the key cannot be
|
|
6122
|
+
* computed. A subscriber whose `where` declines the event is left out, and so is every one when
|
|
6123
|
+
* this engine does not publish the run's namespace. Empty for a run that has not settled.
|
|
6124
|
+
*/
|
|
6125
|
+
coalescedSubscribers(run: WorkflowRun): Map<string, string | undefined>;
|
|
6126
|
+
/**
|
|
6127
|
+
* Who starts whom through lifecycle events, for `workflow`: the workflows that start when it
|
|
6128
|
+
* settles, and the workflows whose settling starts it. Built from this engine's registry and the
|
|
6129
|
+
* subscriptions live workers announce (see {@link announcedSubscriptions}); a failed fleet read
|
|
6130
|
+
* leaves the local registry alone. What a dashboard's workflow page shows.
|
|
6131
|
+
*
|
|
6132
|
+
* With `namespace`, only the subscriptions of that namespace: the ones announced by registry runs
|
|
6133
|
+
* and worker descriptors serving it, and this engine's own when it is that namespace's engine (an
|
|
6134
|
+
* engine with no namespace is `default`'s). What a tenant is shown.
|
|
6135
|
+
*/
|
|
6136
|
+
workflowLifecycle(workflow: string, opts?: {
|
|
6137
|
+
namespace?: string | undefined;
|
|
6138
|
+
}): Promise<WorkflowLifecycleLinks>;
|
|
6139
|
+
/**
|
|
6140
|
+
* `patch` (a terminal status write of `run`) plus the lifecycle marker, when some workflow
|
|
6141
|
+
* subscribes to that ending: {@link LIFECYCLE_PENDING_TAG} and one owed tag per subscriber (see
|
|
6142
|
+
* {@link lifecycleSubscribers}). Written in the same update as the status, so a run can never be
|
|
6143
|
+
* settled without a record of who its lifecycle event is still owed to.
|
|
6144
|
+
*
|
|
6145
|
+
* Uses the last read of the fleet's announcements without waiting for a new one (see
|
|
6146
|
+
* {@link cachedAnnouncedSubscriptions}). With no usable read (none yet, or the last one failed) the
|
|
6147
|
+
* marker is {@link LIFECYCLE_PENDING_TAG} alone, for any workflow but an internal `__` one: the
|
|
6148
|
+
* owed set is unresolved, and {@link publishSettled} resolves it once a read succeeds.
|
|
6149
|
+
*/
|
|
6150
|
+
private withLifecycleMarker;
|
|
6151
|
+
/**
|
|
6152
|
+
* `patch` (a suspend write of `run`) plus the run's {@link LIFECYCLE_TRACE_TAG_PREFIX} tag, when a
|
|
6153
|
+
* run trace provider is installed, some workflow subscribes to the run's ending, the provider
|
|
6154
|
+
* answers for the run and the run does not carry the tag yet. The first turn's suspend records the
|
|
6155
|
+
* run's root span this way, so a run that settles in a process that never saw its first turn still
|
|
6156
|
+
* links its subscribers' traces; a workflow nobody subscribes to gets no tag and no extra write.
|
|
6157
|
+
* Uses the last read of the fleet's announcements without waiting; with no usable read, any
|
|
6158
|
+
* workflow but an internal one may have subscribers, so it gets the tag.
|
|
6159
|
+
*/
|
|
6160
|
+
private withRunTrace;
|
|
6161
|
+
/**
|
|
6162
|
+
* The runs started by `runId` settling (see {@link publishLifecycle}), read from the run's own
|
|
6163
|
+
* tags, so it needs no subscriber registry. Empty for a run that has not settled or started
|
|
6164
|
+
* nobody. Pass the run itself when it is already loaded, to skip reading it again.
|
|
6165
|
+
*/
|
|
6166
|
+
triggeredRuns(source: string | WorkflowRun): Promise<string[]>;
|
|
6167
|
+
/** The live path of {@link publishSettled}: right after this instance settled the run. */
|
|
6168
|
+
private publishLifecycle;
|
|
6169
|
+
/** How long to wait before each new try at a run's lifecycle lease another publisher holds. */
|
|
6170
|
+
private static readonly LIFECYCLE_LEASE_BACKOFF_MS;
|
|
6171
|
+
/**
|
|
6172
|
+
* Run `fn` holding the lease on the settled run `runId` (`tryLockRun`, owner
|
|
6173
|
+
* `<instanceId>#lifecycle#<uuid>`, unique per call), so the live publish, the sweeps of every
|
|
6174
|
+
* instance and a republish update its lifecycle tags one at a time. Retried on the
|
|
6175
|
+
* {@link LIFECYCLE_LEASE_BACKOFF_MS} schedule while another holder has it (the settling execution
|
|
6176
|
+
* still holding its own, or another publisher); `busy` once those tries are spent.
|
|
6177
|
+
*/
|
|
6178
|
+
private withLifecycleLease;
|
|
6179
|
+
/**
|
|
6180
|
+
* Publish a settled run's lifecycle event (`run.completed:<workflow>` / `run.failed:<workflow>`)
|
|
6181
|
+
* to the subscribers this engine has, and settle their part of the marker: drop each one's owed
|
|
6182
|
+
* tag, record each subscriber it started as a `durable:triggered:<workflow>` tag and each one it
|
|
6183
|
+
* routed into a debounce/batch accumulator as a `durable:coalesced:<workflow>` tag, and drop
|
|
6184
|
+
* {@link LIFECYCLE_PENDING_TAG} once no owed tag is left. Subscribers registered only elsewhere
|
|
6185
|
+
* keep their owed tags for the instances that have them.
|
|
6186
|
+
*
|
|
6187
|
+
* Which subscribers: `only` when given (a republish), plus `owe`, owed to the instances that have
|
|
6188
|
+
* them; `heal`, the ones a heal pass found missing (see {@link healLifecycleEvents}); else the owed
|
|
6189
|
+
* ones. A run marked with the pending tag alone is unresolved: with a good read of the fleet's
|
|
6190
|
+
* announcements it is owed to every subscriber (see {@link lifecycleSubscribers}) that has not
|
|
6191
|
+
* started, coalesced or failed, and published as such; without one, this engine starts its own subscribers
|
|
6192
|
+
* that do not coalesce and the run stays unresolved.
|
|
6193
|
+
*
|
|
6194
|
+
* Runs under the run's lifecycle lease (see {@link withLifecycleLease}), reading the run again
|
|
6195
|
+
* inside it; `busy` when the lease could not be taken. Idempotent, since every subscriber run id is
|
|
6196
|
+
* deterministic and a debounce/batch accumulator counts the event once, so the live path, the
|
|
6197
|
+
* sweeps and a republish may all reach the same run. `run.triggered` and `run.trigger_failed` are
|
|
6198
|
+
* emitted by the publish whose write recorded them: a subscriber it reached whose triggered or
|
|
6199
|
+
* coalesced tag the run did not have, and one it failed to start whose failed tag the run did not
|
|
6200
|
+
* have.
|
|
6201
|
+
*
|
|
6202
|
+
* A subscriber whose `where` throws or whose start fails is reported as `run.trigger_failed`,
|
|
6203
|
+
* tagged {@link LIFECYCLE_TRIGGER_FAILED_TAG_PREFIX} in the same update, and not retried; a
|
|
6204
|
+
* subscriber it starts loses that tag. A failure to write the marker leaves it, and the sweep
|
|
6205
|
+
* publishes the run again. Returns the subscribers acted on, or undefined when there was nothing
|
|
6206
|
+
* for this engine to do.
|
|
6207
|
+
*/
|
|
6208
|
+
private publishSettled;
|
|
6209
|
+
/** {@link publishSettled}, under the run's lifecycle lease. */
|
|
6210
|
+
private publishSettledLocked;
|
|
6211
|
+
private reportTriggerFailed;
|
|
6212
|
+
/**
|
|
6213
|
+
* Drop the owed tags of `run`'s subscribers that no live worker announces and this engine does
|
|
6214
|
+
* not have, once the run settled more than {@link LIFECYCLE_ORPHAN_MS} ago, reporting each as
|
|
6215
|
+
* `run.trigger_failed` and tagging it {@link LIFECYCLE_TRIGGER_FAILED_TAG_PREFIX} in the same
|
|
6216
|
+
* update, under the run's lifecycle lease. Skipped when the fleet's announcements could not be
|
|
6217
|
+
* read, since a failed read would make every remote subscriber look orphaned.
|
|
6218
|
+
*/
|
|
6219
|
+
private dropOrphanedSubscribers;
|
|
6220
|
+
/** How long a settled run's marker is left to the live publish before the sweep takes it over. */
|
|
6221
|
+
private static readonly LIFECYCLE_SWEEP_GRACE_MS;
|
|
6222
|
+
/**
|
|
6223
|
+
* How many marked runs (and `ctx.waitForRun` waiters) one sweep examines at most, looking for
|
|
6224
|
+
* `limit` it can act on. Runs owed only to subscribers other instances have are skipped without a
|
|
6225
|
+
* store read, so they cannot fill the window and keep this instance from the ones it can publish.
|
|
6226
|
+
*/
|
|
6227
|
+
private static readonly LIFECYCLE_SWEEP_SCAN_MAX;
|
|
6228
|
+
/** How many recently settled runs of one workflow a heal pass reads at most. */
|
|
6229
|
+
private static readonly LIFECYCLE_HEAL_SCAN_CAP;
|
|
6230
|
+
/**
|
|
6231
|
+
* Publish the lifecycle event of every settled run still marked {@link LIFECYCLE_PENDING_TAG}:
|
|
6232
|
+
* one whose process died, or whose marker write failed, between settling it and publishing, one
|
|
6233
|
+
* owed to a subscriber the settling process does not have, or one whose owed set is unresolved.
|
|
6234
|
+
* Each instance publishes to the subscribers it has, and drops owed subscribers nobody has anymore
|
|
6235
|
+
* (see {@link dropOrphanedSubscribers}). Then heals the recently settled runs that missed a newly
|
|
6236
|
+
* announced subscriber (see {@link healLifecycleEvents}). Also delivers the `ctx.waitForRun` waits
|
|
6237
|
+
* whose run already settled (see {@link sweepRunWaits}). Called by the timer poller; a run settled
|
|
6238
|
+
* in the last {@link LIFECYCLE_SWEEP_GRACE_MS} is left to the live publish. Returns how many runs
|
|
6239
|
+
* it published to a subscriber.
|
|
6240
|
+
*
|
|
6241
|
+
* Reads the marked runs a page of `limit` at a time, skipping the ones it cannot act on, until it
|
|
6242
|
+
* has acted on `limit` runs (published, or dropped orphans) or examined
|
|
6243
|
+
* {@link LIFECYCLE_SWEEP_SCAN_MAX}. Pages advance by offset over a set the sweep itself shrinks,
|
|
6244
|
+
* so a run that moves into an earlier page is reached on the next tick, which starts over. A run
|
|
6245
|
+
* whose lifecycle lease another publisher holds is left for the next tick.
|
|
6246
|
+
*/
|
|
6247
|
+
sweepLifecycleEvents(nowMs?: number, limit?: number): Promise<number>;
|
|
6248
|
+
/**
|
|
6249
|
+
* The (run, subscriber) pairs this engine already healed, until when it remembers them; see
|
|
6250
|
+
* {@link healLifecycleEvents}.
|
|
6251
|
+
*/
|
|
6252
|
+
private readonly healedLifecycle;
|
|
6253
|
+
/**
|
|
6254
|
+
* Heal the runs settled in the last {@link LIFECYCLE_HEAL_WINDOW_MS} that missed a subscriber: one
|
|
6255
|
+
* the fleet announced only after the settling process last read the announcements, so it is in
|
|
6256
|
+
* none of the run's owed, triggered, coalesced or failed tags. Only subscriptions this engine first saw within
|
|
6257
|
+
* that window are checked (see {@link subscriptionFirstSeen}), since one the fleet already
|
|
6258
|
+
* announced when the run settled was in its owed set. Needs a good read of the fleet's
|
|
6259
|
+
* announcements.
|
|
6260
|
+
*
|
|
6261
|
+
* One `listRuns` per source workflow (`updatedAfter` the window, at most
|
|
6262
|
+
* {@link LIFECYCLE_HEAL_SCAN_CAP} runs), skipping unresolved runs (the sweep resolves those) and
|
|
6263
|
+
* the ones in their {@link LIFECYCLE_SWEEP_GRACE_MS}. Each missed subscriber is published like an
|
|
6264
|
+
* owed one (see {@link publishSettled}): started here when this engine can, owed to the instances
|
|
6265
|
+
* that have it otherwise. A subscriber whose `where` declines the event leaves no tag, so each
|
|
6266
|
+
* engine heals a pair once. Returns how many runs it published to a subscriber.
|
|
6267
|
+
*/
|
|
6268
|
+
private healLifecycleEvents;
|
|
6269
|
+
/**
|
|
6270
|
+
* Publish the lifecycle events of settled runs again, to subscribers that missed them: one
|
|
6271
|
+
* registered after the runs settled, or one whose run was deleted. Unlike the sweep it needs no
|
|
6272
|
+
* marker. Each subscriber's run id is deterministic, so one already started is not started again.
|
|
6273
|
+
*
|
|
6274
|
+
* Subscribers registered on this engine are started here. A subscriber only live workers announce
|
|
6275
|
+
* is owed the event again (the run is re-marked), so the sweep on an instance that has it starts
|
|
6276
|
+
* it. Only subscribers of the run's lifecycle event in its namespace are published to; a
|
|
6277
|
+
* `subscriber` that is not one is reported in `failed`. Reads at most `limit` (a positive integer,
|
|
6278
|
+
* default 1000) settled runs of a workflow, a page at a time.
|
|
6279
|
+
*/
|
|
6280
|
+
republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
|
|
6281
|
+
/** {@link republishLifecycle} for one settled run: start what is missing, report what failed. */
|
|
6282
|
+
private republishRun;
|
|
6283
|
+
/**
|
|
6284
|
+
* Resume the runs waiting on `targetRunId` with `ctx.waitForRun`, once it has settled. Each waiter
|
|
6285
|
+
* is taken before it is delivered to, so the settle path, the sweep and the waiting run's own
|
|
6286
|
+
* check never resume it twice. Returns how many it resumed.
|
|
6287
|
+
*/
|
|
6288
|
+
private deliverRunWaits;
|
|
6289
|
+
/**
|
|
6290
|
+
* Deliver the `ctx.waitForRun` waits whose run has settled but which were never resumed: a crash
|
|
6291
|
+
* between settling and delivering, or a run that settled by handing off to a continue-as-new
|
|
6292
|
+
* chain that has since ended. Checks the waited-on runs in waiter order, skipping the ones that
|
|
6293
|
+
* have not settled, until it has resumed waiters of `limit` runs or checked
|
|
6294
|
+
* {@link LIFECYCLE_SWEEP_SCAN_MAX}, so long waits on runs still in flight cannot keep it from a
|
|
6295
|
+
* wait owed a delivery. Returns how many waiters it resumed.
|
|
6296
|
+
*/
|
|
6297
|
+
sweepRunWaits(limit?: number): Promise<number>;
|
|
5129
6298
|
/** Events waiting for the control-plane publish in flight, in emit order (see {@link broadcastEvents}). */
|
|
5130
6299
|
private readonly eventsToBroadcast;
|
|
5131
6300
|
private broadcastingEvents;
|
|
@@ -5209,6 +6378,7 @@ declare class WorkflowEngine {
|
|
|
5209
6378
|
*/
|
|
5210
6379
|
private updateRunIfFallback;
|
|
5211
6380
|
private resumeRunNow;
|
|
6381
|
+
private resumeLoadedRun;
|
|
5212
6382
|
/**
|
|
5213
6383
|
* The registration for an UNREGISTERED run, INHERITED from its nearest REMOTE ancestor — or
|
|
5214
6384
|
* `undefined` if it has none (the skew-protection error case in {@link resume}). Callers check the
|
|
@@ -5544,6 +6714,11 @@ declare class WorkflowEngine {
|
|
|
5544
6714
|
* for a pod that does have the workflow — which is exactly what the skew-protection error asks
|
|
5545
6715
|
* for. Same posture as `publishEvent`'s per-subscriber isolation.
|
|
5546
6716
|
*/
|
|
6717
|
+
/**
|
|
6718
|
+
* Run `claimed` (pending runs this instance just leased, read as locked): every turn starts at
|
|
6719
|
+
* once, and each re-enters the lease taken for it without reading the run again.
|
|
6720
|
+
*/
|
|
6721
|
+
private runClaimed;
|
|
5547
6722
|
private resumeLeased;
|
|
5548
6723
|
/**
|
|
5549
6724
|
* Deliver an external signal to the run waiting on `token` and resume it with `payload`.
|
|
@@ -5554,7 +6729,8 @@ declare class WorkflowEngine {
|
|
|
5554
6729
|
* 1. **Resumes** every in-flight run waiting on it via `ctx.waitForEvent(name, { match })` whose
|
|
5555
6730
|
* match the payload satisfies (fan-out, vs `signal`'s point-to-point token).
|
|
5556
6731
|
* 2. **Starts** a fresh run of every workflow registered with `onEvent: [name]`, passing the
|
|
5557
|
-
* payload as input
|
|
6732
|
+
* payload as input, and of every workflow live workers announce as subscribing to it that this
|
|
6733
|
+
* engine can start by name (see {@link announcedRemoteSubscribers}). Idempotent by `evt:<id>:<workflow>` — pass `opts.id` to dedupe redeliveries
|
|
5558
6734
|
* of the same logical event (default: a fresh uuid, so each publish triggers once).
|
|
5559
6735
|
*
|
|
5560
6736
|
* Semantics (deliberate — mirrors `signalWithStart`'s reliability contract, so document it exactly):
|
|
@@ -5583,6 +6759,19 @@ declare class WorkflowEngine {
|
|
|
5583
6759
|
* same way.
|
|
5584
6760
|
*/
|
|
5585
6761
|
private deliverSignal;
|
|
6762
|
+
/**
|
|
6763
|
+
* Deliver to a waiter that is one condition of a `ctx.waitForAny` (see `wait-any.ts`): settle the
|
|
6764
|
+
* wait with this condition through the checkpoint's compare-and-set, then wake the run. A signal
|
|
6765
|
+
* that loses — the wait was settled by another condition first, or a timer of the wait came due
|
|
6766
|
+
* before it arrived (the timer then wins) — is not consumed: it is sent again on its token, where
|
|
6767
|
+
* it is buffered for the next wait (or reaches a waiter registered since).
|
|
6768
|
+
*/
|
|
6769
|
+
private deliverToWaitAny;
|
|
6770
|
+
/**
|
|
6771
|
+
* Put back a signal a `waitForAny` condition took but did not win with. A child's completion is
|
|
6772
|
+
* kept only where a parent can still consume it, as {@link deliverToParent} decides.
|
|
6773
|
+
*/
|
|
6774
|
+
private redeliverLosingSignal;
|
|
5586
6775
|
/**
|
|
5587
6776
|
* The `ctx.all` join barrier: true when `waiter` was one child of a fan (or of one wave of it)
|
|
5588
6777
|
* whose siblings are still out, so waking the parent now would only replay the fan and re-suspend.
|
|
@@ -5678,7 +6867,14 @@ declare class WorkflowEngine {
|
|
|
5678
6867
|
* Either way, the destructive `take*` ops (on the waiter row, on the buffer) arbitrate: whichever
|
|
5679
6868
|
* side actually removes the row is the one that delivers, so a signal is never delivered twice.
|
|
5680
6869
|
*/
|
|
5681
|
-
signal(token: string, payload: unknown): Promise<RunResult | null>;
|
|
6870
|
+
signal(token: string, payload: unknown, opts?: SignalOptions): Promise<RunResult | null>;
|
|
6871
|
+
/** One deduplicated {@link signal}: claim `id`, then deliver or buffer; a failure forgets the id. */
|
|
6872
|
+
private signalOnce;
|
|
6873
|
+
/**
|
|
6874
|
+
* {@link signal} without deduplication: deliver to the waiter on `token`, or buffer. `committed`
|
|
6875
|
+
* is called once the signal is durably delivered or buffered.
|
|
6876
|
+
*/
|
|
6877
|
+
private deliverOrBuffer;
|
|
5682
6878
|
/**
|
|
5683
6879
|
* Wake the run parked on `token` with `payload`, if there is one; otherwise do nothing — unlike
|
|
5684
6880
|
* {@link signal}, it never buffers. For a wake-up whose real payload is ALREADY buffered on the
|
|
@@ -5817,6 +7013,12 @@ declare class WorkflowEngine {
|
|
|
5817
7013
|
* explicitly cancelled one's does, or the children are orphans nobody is holding a reference to.
|
|
5818
7014
|
*/
|
|
5819
7015
|
private cancelChildren;
|
|
7016
|
+
/**
|
|
7017
|
+
* Apply the `parentClose` policies a parent's turn recorded (see {@link ChildCallOptions.parentClose})
|
|
7018
|
+
* when that parent completes or fails; forget them when it suspends (its next turn, here or on
|
|
7019
|
+
* another instance, records them again). Local events only: this is the instance that ran the turn.
|
|
7020
|
+
*/
|
|
7021
|
+
private settleParentClose;
|
|
5820
7022
|
/**
|
|
5821
7023
|
* The ids of the runs a run spawned — both awaited (`ctx.child`) and fire-and-forget
|
|
5822
7024
|
* (`ctx.startChild`, found via its `spawn:<id>` checkpoint). The canonical parent→children edge,
|
|
@@ -5946,12 +7148,9 @@ declare class WorkflowEngine {
|
|
|
5946
7148
|
* the timer poll of another instance runs it once this instance's hold on it would have lapsed.
|
|
5947
7149
|
*/
|
|
5948
7150
|
private honorWakeRequests;
|
|
5949
|
-
/**
|
|
5950
|
-
* The wake requests kept for `runId`. With `legacy`, also those an older engine kept as buffered
|
|
5951
|
-
* signals, which are taken as they are read.
|
|
5952
|
-
*/
|
|
7151
|
+
/** The wake requests kept for `runId`. */
|
|
5953
7152
|
private listWakeRequests;
|
|
5954
|
-
/** Delete `requests
|
|
7153
|
+
/** Delete `requests`. */
|
|
5955
7154
|
private dropWakeRequests;
|
|
5956
7155
|
/**
|
|
5957
7156
|
* Record, for the turn executing `runId` here, the wakes kept for the run so far. Called before the
|
|
@@ -6301,6 +7500,8 @@ declare class WorkflowEngine {
|
|
|
6301
7500
|
* - a `blocked` plan — descriptors exist but none can run it (park the run, never dispatch into it).
|
|
6302
7501
|
*/
|
|
6303
7502
|
private planRoute;
|
|
7503
|
+
/** The live descriptors for `token`, reused for {@link workerDescriptorCacheMs}; one read in flight. */
|
|
7504
|
+
private liveWorkerDescriptors;
|
|
6304
7505
|
/** Throw {@link WorkflowBlocked} when no live worker can run a dispatch to `token` — so the caller's
|
|
6305
7506
|
* run-execution catch parks the run `blocked` (with the plan) instead of persisting a `pending`
|
|
6306
7507
|
* checkpoint + dispatching into a queue nobody consumes (design §7.5). A no-op when the guard does
|
|
@@ -6321,6 +7522,13 @@ declare class WorkflowEngine {
|
|
|
6321
7522
|
* capable+compatible worker has appeared, else re-parks with a fresh `wakeAt` (design §7.5). */
|
|
6322
7523
|
private dueBlockedRuns;
|
|
6323
7524
|
private callRemote;
|
|
7525
|
+
/**
|
|
7526
|
+
* {@link callRemote}'s first dispatch of a step, written with
|
|
7527
|
+
* {@link StateStore.insertCheckpointIfAbsent}: resolves whether it wrote the `pending` row and
|
|
7528
|
+
* dispatched. `false` when the position already has a row, or when no live worker can take the
|
|
7529
|
+
* step (the read-first path then decides, so a step that is in fact done is never blocked).
|
|
7530
|
+
*/
|
|
7531
|
+
private dispatchIfAbsent;
|
|
6324
7532
|
/**
|
|
6325
7533
|
* Whether a `pending` step a turn just read only waits for its result: {@link callRemote} would
|
|
6326
7534
|
* suspend on it without writing (no redispatch deadline to stamp, the one stamped not yet due).
|
|
@@ -6366,6 +7574,29 @@ declare class WorkflowEngine {
|
|
|
6366
7574
|
* all at its front: pruning stops at the first fresh entry instead of walking the whole map.
|
|
6367
7575
|
*/
|
|
6368
7576
|
private noteRecent;
|
|
7577
|
+
/**
|
|
7578
|
+
* Whether this turn of `run` may run in a sticky continuation (see `sticky-continuation.ts`). Not
|
|
7579
|
+
* while the engine drains, for a cancel being compensated, nor when execution wrappers are
|
|
7580
|
+
* registered: a resumed body runs in the async scope of the turn that started it, and a wrapper
|
|
7581
|
+
* (a span, a log batch) expects one scope per turn.
|
|
7582
|
+
*/
|
|
7583
|
+
private stickyEligible;
|
|
7584
|
+
/**
|
|
7585
|
+
* The continuation this instance parked for `run`, if it is still the run's latest turn: the run
|
|
7586
|
+
* is `suspended` with the very stamp this instance's suspend wrote, on the same body and version.
|
|
7587
|
+
* Any other settle in between (another instance's turn, a retry, a cancel) changed the stamp, and
|
|
7588
|
+
* the run replays instead. Taking it removes it from the cache.
|
|
7589
|
+
*/
|
|
7590
|
+
private takeContinuation;
|
|
7591
|
+
/** Keep `cont` (parked, detached) for the run's next turn here, stamped with its suspend write. */
|
|
7592
|
+
private keepContinuation;
|
|
7593
|
+
/**
|
|
7594
|
+
* The checkpoints of the steps `cont` is parked on, as a replay would see them: in one read when
|
|
7595
|
+
* the store batches, and without the input of a step that completed (what
|
|
7596
|
+
* {@link StateStore.getCheckpointsForSettle} leaves out). A step still open or failed is read
|
|
7597
|
+
* whole, since a re-dispatch or a retry sends its input again.
|
|
7598
|
+
*/
|
|
7599
|
+
private readParked;
|
|
6369
7600
|
/**
|
|
6370
7601
|
* The run's checkpoints as a turn replays them: {@link StateStore.listCheckpointsForReplay} when
|
|
6371
7602
|
* the store has it (no input on a completed row), else {@link StateStore.listCheckpoints}.
|
|
@@ -6432,6 +7663,14 @@ declare class WorkflowEngine {
|
|
|
6432
7663
|
* under a backlog the barrier is read once per drained queue rather than once per batch.
|
|
6433
7664
|
*/
|
|
6434
7665
|
private completeRemoteResults;
|
|
7666
|
+
/**
|
|
7667
|
+
* {@link completeRemoteResults} on a store with {@link StateStore.settleResultsIfPending}: the
|
|
7668
|
+
* results settle their `pending` rows and read them back in one call, instead of a read of the rows
|
|
7669
|
+
* followed by the write. Only an entry that wrote nothing (a redelivery, or a step gone) is read
|
|
7670
|
+
* afterwards. A settled `completed` row is also handed to the run's parked body, if this instance
|
|
7671
|
+
* holds one, so its next turn does not read it again.
|
|
7672
|
+
*/
|
|
7673
|
+
private settleResultsReturning;
|
|
6435
7674
|
/**
|
|
6436
7675
|
* The outcomes for a batch of redelivered results (their steps already settled): one of them
|
|
6437
7676
|
* resumes the run if it is `suspended` and, for a step of a fan, the fan's barrier is open. A
|
|
@@ -7028,6 +8267,12 @@ declare function pageFanFromStore(store: CheckpointAggregatingStore, runId: stri
|
|
|
7028
8267
|
* plus its checkpoint buckets, and the threshold it was summarized with.
|
|
7029
8268
|
*/
|
|
7030
8269
|
declare function runDetailEtag(run: WorkflowRun, stats: CheckpointStat[], over: number): string;
|
|
8270
|
+
/**
|
|
8271
|
+
* `etag` extended with a fingerprint of `extras`, the parts of a detail read from outside the run
|
|
8272
|
+
* row and its checkpoints (another run's status, the fleet's subscriptions), so a change to them
|
|
8273
|
+
* also changes the validator. `etag` itself when `extras` is undefined.
|
|
8274
|
+
*/
|
|
8275
|
+
declare function extendEtag(etag: string, extras: unknown): string;
|
|
7031
8276
|
/** The ETag of one page of a fan: its group's buckets and the page asked for. */
|
|
7032
8277
|
declare function fanPageEtag(group: string, stats: CheckpointStat[], query: FanPageQuery): string;
|
|
7033
8278
|
/** Whether an `If-None-Match` header value names `etag` (weak comparison, as RFC 9110 asks for). */
|
|
@@ -7052,8 +8297,11 @@ declare function parseWebhookToken(token: string): {
|
|
|
7052
8297
|
* like any other), so without this case it would fall through to the generic `signal` branch with the
|
|
7053
8298
|
* raw `bp:<runId>:<seq>` token as its display name — a real bug. Named `'breakpoint'` here instead;
|
|
7054
8299
|
* the token carries no separate label to recover cheaply (see {@link RunWaiting.name}).
|
|
8300
|
+
*
|
|
8301
|
+
* A `ctx.waitForRun` token (`runwait:<target>#<runId>#<seq>`) is named by its target run, read
|
|
8302
|
+
* exactly against `waiter` when given, else from the token alone.
|
|
7055
8303
|
*/
|
|
7056
|
-
declare function classifyWaiterToken(token: string): RunWaiting;
|
|
8304
|
+
declare function classifyWaiterToken(token: string, waiter?: Pick<SignalWaiter, 'runId' | 'seq'>): RunWaiting;
|
|
7057
8305
|
/**
|
|
7058
8306
|
* Resolve a suspended run's {@link RunWaiting} from the pending signal waiters (indexed by `runId`).
|
|
7059
8307
|
* Event-only by design (see {@link RunWaiting}): a `waitForSignal`/`waitForEvent`/webhook/awaited-child
|
|
@@ -7169,6 +8417,15 @@ declare class CodecStateStore implements StateStore {
|
|
|
7169
8417
|
/** Encodes each settlement's payloads like {@link saveCheckpoint}. Bound only when the inner store
|
|
7170
8418
|
* has it, so the engine's whole-row fallback still kicks in through the wrapper. */
|
|
7171
8419
|
readonly settleCheckpointsIfPending?: (settlements: StepSettlement[]) => Promise<boolean[]>;
|
|
8420
|
+
/** Encodes each result's payloads, decodes each row read back. Bound only when the inner store
|
|
8421
|
+
* has it. */
|
|
8422
|
+
readonly settleResultsIfPending?: (results: StepResultSettlement[]) => Promise<(StepCheckpoint | null)[]>;
|
|
8423
|
+
/** Encodes like {@link saveCheckpoint}. Bound only when the inner store has it. */
|
|
8424
|
+
readonly insertCheckpointIfAbsent?: (checkpoint: StepCheckpoint) => Promise<boolean>;
|
|
8425
|
+
/** Decodes each run claimed. Bound only when the inner store has it. */
|
|
8426
|
+
readonly claimPendingRuns?: (limit: number, owner: string, leaseUntilMs: number, nowMs: number, namespace?: string) => Promise<WorkflowRun[]>;
|
|
8427
|
+
/** Decodes the run read. Bound only when the inner store has it. */
|
|
8428
|
+
readonly tryLockRunAndGet?: (runId: string, owner: string, leaseUntilMs: number, nowMs: number) => Promise<WorkflowRun | null>;
|
|
7172
8429
|
/** Encodes each checkpoint written. Bound only when the inner store has it. */
|
|
7173
8430
|
readonly saveCheckpoints?: (checkpoints: StepCheckpoint[]) => Promise<void>;
|
|
7174
8431
|
/** Decodes each checkpoint read like {@link listCheckpoints}. Bound only when the inner store has
|
|
@@ -7206,6 +8463,17 @@ declare class CodecStateStore implements StateStore {
|
|
|
7206
8463
|
readonly listBufferedSignals?: (tokenPrefix: string, afterId: string | undefined, limit: number) => Promise<BufferedSignalRow[]>;
|
|
7207
8464
|
/** Forwarded verbatim — deletes by row id. */
|
|
7208
8465
|
readonly deleteBufferedSignals?: (ids: string[]) => Promise<void>;
|
|
8466
|
+
/** Decodes the payload like {@link takeBufferedSignal}. Bound only when the inner store has it. */
|
|
8467
|
+
readonly takeOldestBufferedSignal?: (tokens: string[]) => Promise<{
|
|
8468
|
+
token: string;
|
|
8469
|
+
payload: unknown;
|
|
8470
|
+
} | null>;
|
|
8471
|
+
/** Forwarded verbatim — a signal id record carries no payload. */
|
|
8472
|
+
readonly claimSignalId?: (token: string, id: string, expiresAt: number, nowMs: number) => Promise<boolean>;
|
|
8473
|
+
/** Forwarded verbatim. */
|
|
8474
|
+
readonly releaseSignalId?: (token: string, id: string) => Promise<void>;
|
|
8475
|
+
/** Forwarded verbatim. */
|
|
8476
|
+
readonly deleteExpiredSignalIds?: (nowMs: number, limit: number) => Promise<number>;
|
|
7209
8477
|
/** Forwarded verbatim — a waiter carries no payload. */
|
|
7210
8478
|
readonly listSignalWaitersByRun?: (runIds: string[]) => Promise<SignalWaiter[]>;
|
|
7211
8479
|
/** Forwarded verbatim — a waiter carries no payload. */
|
|
@@ -7273,31 +8541,22 @@ declare class CodecStateStore implements StateStore {
|
|
|
7273
8541
|
}
|
|
7274
8542
|
|
|
7275
8543
|
/**
|
|
7276
|
-
*
|
|
7277
|
-
*
|
|
7278
|
-
*
|
|
7279
|
-
* accumulate an unbounded backlog; this caps the per-scan cost regardless. Shared by the workflow-ctx
|
|
7280
|
-
* consumer and the engine's reconcile sweep so both see the same window.
|
|
8544
|
+
* `ctx.waitForRun(runId)`: a durable wait for any run to settle, built on the signal-waiter table.
|
|
8545
|
+
* The waiter's token embeds the target run and the waiting call's own `runId#seq`, so no two calls
|
|
8546
|
+
* share one, and the engine finds a run's waiters by the {@link runWaitPrefix} of its id.
|
|
7281
8547
|
*/
|
|
7282
|
-
|
|
7283
|
-
|
|
7284
|
-
|
|
7285
|
-
|
|
7286
|
-
|
|
7287
|
-
declare
|
|
7288
|
-
/**
|
|
7289
|
-
|
|
7290
|
-
|
|
7291
|
-
|
|
7292
|
-
|
|
7293
|
-
declare function
|
|
7294
|
-
/** The event name embedded in an event waiter token (the 2nd `:`-segment is the base64 name), so a
|
|
7295
|
-
* dashboard can show "waiting on event `<name>`" instead of the opaque token. */
|
|
7296
|
-
declare function eventNameOf(token: string): string;
|
|
7297
|
-
/** The match criteria embedded in an event waiter token (the 3rd `:`-segment is the base64 match). */
|
|
7298
|
-
declare function eventMatchOf(token: string): Record<string, unknown>;
|
|
7299
|
-
/** Whether `payload` satisfies a waiter's `match`: every match key deep-equals the payload's value. */
|
|
7300
|
-
declare function eventMatches(payload: unknown, match: Record<string, unknown>): boolean;
|
|
8548
|
+
/** The literal every run-wait token starts with. */
|
|
8549
|
+
declare const RUN_WAIT_TOKEN_PREFIX = "runwait:";
|
|
8550
|
+
/** Token prefix shared by every waiter on `targetRunId`. */
|
|
8551
|
+
declare function runWaitPrefix(targetRunId: string): string;
|
|
8552
|
+
/** The waiter token for one `ctx.waitForRun(targetRunId)` call at `seq` of run `runId`. */
|
|
8553
|
+
declare function runWaitToken(targetRunId: string, runId: string, seq: number): string;
|
|
8554
|
+
/**
|
|
8555
|
+
* The run a `ctx.waitForRun` waiter waits on, or undefined when `waiter` is not one. Read against
|
|
8556
|
+
* the waiter's own `runId` and `seq`, so a target id containing `#` is still read exactly, and a
|
|
8557
|
+
* prefix listing for run `a` that also returns the waiters of run `a#b` can be told apart.
|
|
8558
|
+
*/
|
|
8559
|
+
declare function runWaitTargetOf(waiter: Pick<SignalWaiter, 'token' | 'runId' | 'seq'>): string | undefined;
|
|
7301
8560
|
|
|
7302
8561
|
interface MetricsSnapshot {
|
|
7303
8562
|
/** `routed`: failures handed to an onError handler; `unrouted`: routes the engine could not apply. */
|
|
@@ -7311,6 +8570,16 @@ interface MetricsSnapshot {
|
|
|
7311
8570
|
};
|
|
7312
8571
|
/** Routed failures by error code (`*` for a failure without one). */
|
|
7313
8572
|
routedByCode: Record<string, number>;
|
|
8573
|
+
/**
|
|
8574
|
+
* Subscriber runs a settled run's lifecycle event started (`run.triggered`), keyed by the settled
|
|
8575
|
+
* run's workflow, then by the subscriber. Exposed as `durable_runs_triggered_total{workflow,subscriber}`.
|
|
8576
|
+
*/
|
|
8577
|
+
triggeredBySubscriber: Record<string, Record<string, number>>;
|
|
8578
|
+
/**
|
|
8579
|
+
* Subscribers a settled run's lifecycle event could not start (`run.trigger_failed`), keyed the
|
|
8580
|
+
* same way. Exposed as `durable_runs_trigger_failed_total{workflow,subscriber}`.
|
|
8581
|
+
*/
|
|
8582
|
+
triggerFailedBySubscriber: Record<string, Record<string, number>>;
|
|
7314
8583
|
steps: {
|
|
7315
8584
|
started: number;
|
|
7316
8585
|
completed: number;
|
|
@@ -7696,6 +8965,41 @@ interface WorkflowHandler<TInput = unknown, TOutput = unknown, A extends SearchA
|
|
|
7696
8965
|
run(ctx: WorkflowCtx<A>, input: TInput): Promise<TOutput> | TOutput;
|
|
7697
8966
|
}
|
|
7698
8967
|
|
|
8968
|
+
/**
|
|
8969
|
+
* `ctx.waitForAny(name, conditions)`: one durable wait over several conditions (signals, timers,
|
|
8970
|
+
* child runs), resolved by the FIRST of them, journaled at one position. The machinery lives here so
|
|
8971
|
+
* the in-process ctx (`workflow-ctx.ts`) and the remote `waitAny` command (`engine.applyCommands`)
|
|
8972
|
+
* resolve it the same way, and the engine's signal delivery ({@link isAnyMember}) can settle it from
|
|
8973
|
+
* the sending side.
|
|
8974
|
+
*
|
|
8975
|
+
* How it stays exactly-once, and why a losing signal is not consumed:
|
|
8976
|
+
*
|
|
8977
|
+
* - The wait's position holds ONE checkpoint, `any:<name>`, written `pending` the first time the wait
|
|
8978
|
+
* is reached, with the conditions (timers resolved to absolute deadlines) as its `input`. Whoever
|
|
8979
|
+
* flips it to `completed` — through the store's compare-and-set {@link StateStore.saveCheckpointIfPending}
|
|
8980
|
+
* — is the winner. Nothing else arbitrates, so two conditions landing at once can't both win.
|
|
8981
|
+
* - Every signal/child condition registers an ordinary waiter on its own token, at the wait's
|
|
8982
|
+
* position, tagged {@link ANY_WAIT_GROUP}. A signal sent while the run waits takes that waiter, as
|
|
8983
|
+
* any signal does, and then tries the compare-and-set. If it loses (another condition already
|
|
8984
|
+
* won, or a timer's deadline passed first) the engine sends the payload again on its token
|
|
8985
|
+
* ({@link WorkflowEngine.signal}), so it is buffered for the next wait on that token instead of
|
|
8986
|
+
* being consumed.
|
|
8987
|
+
* - A signal buffered before the wait, or between registering and suspending, is taken here
|
|
8988
|
+
* ({@link takeOldestBuffered}); if that take then loses the compare-and-set, it goes back into the
|
|
8989
|
+
* buffer.
|
|
8990
|
+
* - The winner removes the other conditions' waiters. A losing timer is simply never fired (the run's
|
|
8991
|
+
* wake time moves on with its next wait). A losing child keeps running: its completion is buffered
|
|
8992
|
+
* as for any child nobody waits on, so a later `ctx.child(..., id)` still joins it.
|
|
8993
|
+
*/
|
|
8994
|
+
/** The `parallelGroup` that marks a signal waiter as one condition of a `waitForAny`. */
|
|
8995
|
+
declare const ANY_WAIT_GROUP = "$any";
|
|
8996
|
+
/** The checkpoint name of the wait called `name`. */
|
|
8997
|
+
declare function anyCheckpointName(name: string): string;
|
|
8998
|
+
/** Whether `cp` is a `waitForAny` checkpoint. */
|
|
8999
|
+
declare function isAnyCheckpoint(cp: StepCheckpoint): boolean;
|
|
9000
|
+
/** Whether `waiter` is one condition of a `waitForAny`. */
|
|
9001
|
+
declare function isAnyMember(waiter: SignalWaiter): boolean;
|
|
9002
|
+
|
|
7699
9003
|
/**
|
|
7700
9004
|
* A non-durable, in-process `StateStore` for tests and local development.
|
|
7701
9005
|
* The shipped `@dudousxd/nestjs-durable-store` package re-exports an equivalent.
|
|
@@ -7746,6 +9050,16 @@ declare class InMemoryStateStore implements StateStore {
|
|
|
7746
9050
|
saveCheckpointIfPending(checkpoint: StepCheckpoint): Promise<boolean>;
|
|
7747
9051
|
saveCheckpointsIfPending(checkpoints: StepCheckpoint[]): Promise<boolean[]>;
|
|
7748
9052
|
settleCheckpointsIfPending(settlements: StepSettlement[]): Promise<boolean[]>;
|
|
9053
|
+
readonly settleResultsIfPending?: (results: StepResultSettlement[]) => Promise<(StepCheckpoint | null)[]>;
|
|
9054
|
+
readonly insertCheckpointIfAbsent?: (checkpoint: StepCheckpoint) => Promise<boolean>;
|
|
9055
|
+
readonly tryLockRunAndGet?: (runId: string, owner: string, leaseUntilMs: number, nowMs: number) => Promise<WorkflowRun | null>;
|
|
9056
|
+
readonly claimPendingRuns?: (limit: number, owner: string, leaseUntilMs: number, nowMs: number, namespace?: string) => Promise<WorkflowRun[]>;
|
|
9057
|
+
constructor(opts?: {
|
|
9058
|
+
roundTripMethods?: boolean;
|
|
9059
|
+
});
|
|
9060
|
+
private settleResultsFallback;
|
|
9061
|
+
private insertIfAbsentFallback;
|
|
9062
|
+
private lockAndGetFallback;
|
|
7749
9063
|
listOrphanedRuns(nowMs: number, limit: number, namespace?: string, ownedBy?: OwnedLeaseReclaim): Promise<WorkflowRun[]>;
|
|
7750
9064
|
listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
|
|
7751
9065
|
listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
|
|
@@ -7771,6 +9085,15 @@ declare class InMemoryStateStore implements StateStore {
|
|
|
7771
9085
|
takeBufferedSignal(token: string): Promise<{
|
|
7772
9086
|
payload: unknown;
|
|
7773
9087
|
} | null>;
|
|
9088
|
+
takeOldestBufferedSignal(tokens: string[]): Promise<{
|
|
9089
|
+
token: string;
|
|
9090
|
+
payload: unknown;
|
|
9091
|
+
} | null>;
|
|
9092
|
+
/** `token \u0000 id -> expiresAt` of the signal ids {@link claimSignalId} recorded. */
|
|
9093
|
+
private readonly signalIds;
|
|
9094
|
+
claimSignalId(token: string, id: string, expiresAt: number, nowMs: number): Promise<boolean>;
|
|
9095
|
+
releaseSignalId(token: string, id: string): Promise<void>;
|
|
9096
|
+
deleteExpiredSignalIds(nowMs: number, limit: number): Promise<number>;
|
|
7774
9097
|
listBufferedSignals(tokenPrefix: string, afterId: string | undefined, limit: number): Promise<BufferedSignalRow[]>;
|
|
7775
9098
|
deleteBufferedSignals(ids: string[]): Promise<void>;
|
|
7776
9099
|
/** `id -> row`, so {@link removeBufferedEvent} can delete an exact row regardless of iteration
|
|
@@ -7934,4 +9257,63 @@ declare function singletonAdmissionDenialPatch(runs: WorkflowRun[], runId: strin
|
|
|
7934
9257
|
updatedAt: Date;
|
|
7935
9258
|
} | undefined;
|
|
7936
9259
|
|
|
7937
|
-
|
|
9260
|
+
/**
|
|
9261
|
+
* RFC 5545 recurrence rules for persisted schedules (`engine.schedules.create({ rrule })`), evaluated
|
|
9262
|
+
* in an IANA time zone with no dependency.
|
|
9263
|
+
*
|
|
9264
|
+
* Accepted text: `FREQ=WEEKLY;BYDAY=MO;BYHOUR=8`, optionally prefixed `RRULE:`, optionally preceded by
|
|
9265
|
+
* a `DTSTART:20260105T080000` line (local time in the schedule's zone, or UTC with a trailing `Z`).
|
|
9266
|
+
*
|
|
9267
|
+
* Supported parts: `FREQ` (`YEARLY`, `MONTHLY`, `WEEKLY`, `DAILY`, `HOURLY`, `MINUTELY`), `INTERVAL`,
|
|
9268
|
+
* `COUNT`, `UNTIL`, `BYMONTH`, `BYMONTHDAY` (negative counts from the month's end), `BYDAY` (with an
|
|
9269
|
+
* ordinal such as `1MO` or `-1FR` under `MONTHLY`/`YEARLY`), `BYHOUR`, `BYMINUTE`, `BYSECOND`, `WKST`.
|
|
9270
|
+
* Anything else (`BYSETPOS`, `BYWEEKNO`, `BYYEARDAY`, `SECONDLY`) is refused by name rather than
|
|
9271
|
+
* ignored.
|
|
9272
|
+
*
|
|
9273
|
+
* Without `DTSTART` the rule is anchored at 1970-01-01T00:00 in the zone: give one when the rule
|
|
9274
|
+
* uses `INTERVAL` > 1 or `COUNT`, or relies on DTSTART's defaults (a `WEEKLY` rule without `BYDAY`
|
|
9275
|
+
* repeats DTSTART's weekday; a missing `BYHOUR`/`BYMINUTE`/`BYSECOND` takes DTSTART's).
|
|
9276
|
+
*
|
|
9277
|
+
* Local times that don't exist (the hour skipped when clocks go forward) are skipped, as RFC 5545
|
|
9278
|
+
* says; an ambiguous one (the hour repeated when they go back) fires once, at its first instant.
|
|
9279
|
+
*/
|
|
9280
|
+
type Freq = 'YEARLY' | 'MONTHLY' | 'WEEKLY' | 'DAILY' | 'HOURLY' | 'MINUTELY';
|
|
9281
|
+
interface ByDay {
|
|
9282
|
+
weekday: number;
|
|
9283
|
+
nth?: number;
|
|
9284
|
+
}
|
|
9285
|
+
interface ParsedRRule {
|
|
9286
|
+
freq: Freq;
|
|
9287
|
+
interval: number;
|
|
9288
|
+
count?: number;
|
|
9289
|
+
/** Epoch ms, inclusive. */
|
|
9290
|
+
until?: number;
|
|
9291
|
+
byMonth?: number[];
|
|
9292
|
+
byMonthDay?: number[];
|
|
9293
|
+
byDay?: ByDay[];
|
|
9294
|
+
byHour?: number[];
|
|
9295
|
+
byMinute?: number[];
|
|
9296
|
+
bySecond?: number[];
|
|
9297
|
+
wkst: number;
|
|
9298
|
+
/** Epoch ms of DTSTART. */
|
|
9299
|
+
start: number;
|
|
9300
|
+
timezone: string;
|
|
9301
|
+
}
|
|
9302
|
+
/** Parse and validate a rule. Throws with the offending part named. */
|
|
9303
|
+
declare function parseRRule(text: string, timezone?: string): ParsedRRule;
|
|
9304
|
+
/** The first occurrence strictly after `afterMs`, or `null` when the rule has ended. */
|
|
9305
|
+
declare function nextRRuleFireMs(rule: ParsedRRule, afterMs: number): number | null;
|
|
9306
|
+
/** The latest occurrence at or before `atMs`, or `null` when there is none yet. */
|
|
9307
|
+
declare function prevRRuleFireMs(rule: ParsedRRule, atMs: number): number | null;
|
|
9308
|
+
|
|
9309
|
+
/**
|
|
9310
|
+
* {@link StateStore.settleResultsIfPending} built on a store's batched plain calls, for an adapter on
|
|
9311
|
+
* a database without `RETURNING` (MySQL) settling a batch of results: the batch's runs and rows are
|
|
9312
|
+
* read once each, the rows still `pending` of runs not finished are settled with
|
|
9313
|
+
* {@link StateStore.settleCheckpointsIfPending} (one batched, transactional call), and the rows it
|
|
9314
|
+
* settled are read back. A fixed number of statements however wide the batch, where settling each
|
|
9315
|
+
* result on its own would cost two per result.
|
|
9316
|
+
*/
|
|
9317
|
+
declare function settleResultsWithPlainCalls(store: Pick<StateStore, 'getRun' | 'getCheckpoint'> & Partial<Pick<StateStore, 'getRuns' | 'getCheckpointsForSettle' | 'getCheckpoints' | 'settleCheckpointsIfPending'>>, results: StepResultSettlement[]): Promise<(StepCheckpoint | null)[]>;
|
|
9318
|
+
|
|
9319
|
+
export { ACCUMULATOR_SEEN_MAX, ANY_WAIT_GROUP, 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, type ConsoleCapabilities, 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, type EventSubscription, 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, LIFECYCLE_COALESCED_TAG_PREFIX, LIFECYCLE_HEAL_WINDOW_MS, LIFECYCLE_ORPHAN_MS, LIFECYCLE_OWED_TAG_PREFIX, LIFECYCLE_PENDING_TAG, LIFECYCLE_REGISTRY_HEARTBEAT_MS, LIFECYCLE_REGISTRY_STALE_MS, LIFECYCLE_REGISTRY_TAG, LIFECYCLE_REGISTRY_TTL_MS, LIFECYCLE_REGISTRY_WORKFLOW, LIFECYCLE_TRACE_TAG_PREFIX, LIFECYCLE_TRIGGERED_TAG_PREFIX, LIFECYCLE_TRIGGER_FAILED_TAG_PREFIX, type LifecycleDelivery, type LifecycleDeliveryState, type LifecycleEventOf, type LifecycleKind, type LifecycleRegistryEntry, type LifecycleSource, type LifecycleSubscriptionLink, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OnEventEntry, type OwnedLeaseReclaim, PARENT_CLOSE_TAG_PREFIX, type ParentClosePolicy, type ParsedRRule, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, REMOTE_EVENT, RUN_HISTORY_FIXTURE_VERSION, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, RUN_WAIT_TOKEN_PREFIX, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RepublishLifecycleResult, type RepublishLifecycleTarget, 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 RunWaitLink, type RunWaiting, SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, SINGLETON_LOCK_CHUNK, 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, type SignalOptions, 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 StepResultSettlement, 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 WaitAnyCondition, type WaitAnyOutcome, type WaitAnyResult, type WaitCondition, type WaitConditionSpec, type WaitForRunOptions, 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 WorkflowLifecycleEvent, type WorkflowLifecycleLinks, WorkflowNotRegistered, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, acceptingSubscription, accumulatorRunId, aggregateAnnouncements, aggregatesCheckpoints, announcementsOf, anyCheckpointName, applyAttributeQuery, assertConcurrency, assertRoutes, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, carriesLifecyclePending, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, coalescedSubscribersOf, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, extendEtag, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, getRunsByIds, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, hmacTenantVerifier, indexWaitersByRun, info, isAnyCheckpoint, isAnyMember, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isLifecycleTag, isNonEmptyRunScope, isRemoteEvent, isWorkflowControlFlowSignal, legacySingletonHolders, lifecycleDeliveriesOf, lifecycleEventName, lifecycleEventOf, lifecycleKindOf, lifecycleRegistryNamespace, lifecycleRegistryRunId, lifecycleRegistrySubscriptions, lifecycleRunId, lifecycleSourceOf, lifecycleTraceparentOf, listSignalWaitersOfRuns, liveHandoff, log, markRemoteEvent, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, nextRRuleFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, owedSubscribersOf, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseLifecycleEvent, parseRRule, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, prevRRuleFireMs, queryCheckpointsOf, readRunsByIds, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, resolveTenantToken, resolveWireTenant, retentionKeeps, retiredHandoffName, routeFor, runCompletedEvent, runDetailEtag, runDurableExecution, runFailedEvent, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, runWaitPrefix, runWaitTargetOf, runWaitToken, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, settleResultsWithPlainCalls, signTenantToken, singletonAdmissionDenialPatch, singletonAdmissionTags, singletonClaimantIds, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantGroup, toEventSubscription, traceIdOfTraceparent, triggerFailedSubscribersOf, triggeredRunsOf, triggeredSubscribersOf, useDurableExecution, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };
|