@dudousxd/nestjs-durable-core 0.101.0 → 0.103.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 +769 -74
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1155 -824
- package/dist/index.d.ts +1155 -824
- package/dist/index.js +765 -74
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -266,6 +266,41 @@ interface WorkflowRegistration {
|
|
|
266
266
|
* nothing.
|
|
267
267
|
*/
|
|
268
268
|
subscribes?: string[];
|
|
269
|
+
/**
|
|
270
|
+
* The `@Workflow` options a control plane applies to this workflow when it serves it by convention
|
|
271
|
+
* (it knows a tenant's workflow by name alone). Only the data options travel: the ones that are
|
|
272
|
+
* functions of the input (a singleton or concurrency `key`, an input schema, `validateInput`) are
|
|
273
|
+
* evaluated by the starting app and carried on its start-run (see `StartRunMessage.singleton`).
|
|
274
|
+
* Absent = not stated, which applies nothing (the behaviour before this field).
|
|
275
|
+
*/
|
|
276
|
+
options?: AnnouncedWorkflowOptions;
|
|
277
|
+
/**
|
|
278
|
+
* The workflow this workflow's dead-lettered runs are routed to: an inline `@DeadLetter()` handler
|
|
279
|
+
* (`<name>.dlq`, served by the same worker), a `deadLetterWorkflow` reference, or the app's
|
|
280
|
+
* module-level default. A control plane serving the workflow by convention starts it, in the dead
|
|
281
|
+
* run's namespace, when no dead-letter route of its own applies. Absent = not stated.
|
|
282
|
+
*/
|
|
283
|
+
deadLetter?: string;
|
|
284
|
+
}
|
|
285
|
+
/**
|
|
286
|
+
* The JSON-safe `@Workflow` options a worker announces for a workflow (see
|
|
287
|
+
* {@link WorkflowRegistration.options}). Every field is optional and means "not stated" when absent.
|
|
288
|
+
*/
|
|
289
|
+
interface AnnouncedWorkflowOptions {
|
|
290
|
+
/** Static tags stamped on every run, merged with the start's own tags. */
|
|
291
|
+
tags?: string[];
|
|
292
|
+
/** Max wall-clock lifetime of a run, in ms (`@Workflow({ executionTimeout })`). */
|
|
293
|
+
executionTimeoutMs?: number;
|
|
294
|
+
/**
|
|
295
|
+
* The workflow is a singleton (`@Workflow({ singleton })`): its runs that share a key are admitted
|
|
296
|
+
* at most `limit` (default 1) at a time. The key is a function of the input, so the starter computes
|
|
297
|
+
* it and the run carries it as its `singleton:<key>` tag; this states the limit the control plane
|
|
298
|
+
* admits against on every turn.
|
|
299
|
+
*/
|
|
300
|
+
singleton?: {
|
|
301
|
+
limit?: number;
|
|
302
|
+
maxQueueDepth?: number;
|
|
303
|
+
};
|
|
269
304
|
}
|
|
270
305
|
/**
|
|
271
306
|
* One recurring start a tenant app declares (its `schedules` module option), as its worker
|
|
@@ -291,6 +326,16 @@ interface AnnouncedSchedule {
|
|
|
291
326
|
overlap?: 'allow' | 'skip';
|
|
292
327
|
/** Delay each fire by a stable offset of up to this many ms. */
|
|
293
328
|
jitterMs?: number;
|
|
329
|
+
/**
|
|
330
|
+
* The workflow's `@Workflow({ singleton })` key, evaluated by the app against this schedule's
|
|
331
|
+
* `input` (a key is a function of the input, which the control plane cannot run). Its fires are
|
|
332
|
+
* serialized with the app's other runs of that key. Absent = not a singleton.
|
|
333
|
+
*/
|
|
334
|
+
singleton?: {
|
|
335
|
+
key: string;
|
|
336
|
+
limit?: number;
|
|
337
|
+
maxQueueDepth?: number;
|
|
338
|
+
};
|
|
294
339
|
}
|
|
295
340
|
/**
|
|
296
341
|
* The schedules a tenant worker announces, and the wire tenant they belong to: the partition, or
|
|
@@ -964,69 +1009,6 @@ declare function fanPageBounds(query: FanPageQuery): {
|
|
|
964
1009
|
limit: number;
|
|
965
1010
|
};
|
|
966
1011
|
|
|
967
|
-
/**
|
|
968
|
-
* One end of a `ctx.waitForRun` wait, as a run detail lists it: the run waited for (`waitsFor`) or
|
|
969
|
-
* the waiting run (`awaitedBy`), the waiting run's `seq` of the call, and the other run's status and
|
|
970
|
-
* namespace when it was read.
|
|
971
|
-
*/
|
|
972
|
-
interface RunWaitLink {
|
|
973
|
-
runId: string;
|
|
974
|
-
seq: number;
|
|
975
|
-
status?: RunStatus | undefined;
|
|
976
|
-
namespace?: string | undefined;
|
|
977
|
-
}
|
|
978
|
-
/**
|
|
979
|
-
* Where a settled run's lifecycle event stands for one subscriber:
|
|
980
|
-
* - `started`: its run exists (`runId`, a `durable:triggered:<subscriber>` tag);
|
|
981
|
-
* - `owed`: still pending (a `durable:lifecycle:owed:<subscriber>` tag);
|
|
982
|
-
* - `coalesced`: routed into a debounce/batch accumulator (a `durable:coalesced:<subscriber>` tag,
|
|
983
|
-
* or the caller's `coalesced` map; `runId` is the accumulator's, when it can be derived);
|
|
984
|
-
* - `failed`: its start failed (a `durable:trigger_failed:<subscriber>` tag): its `where` threw, its
|
|
985
|
-
* input was rejected, its start threw, or the sweep dropped it as orphaned. A republish retries it;
|
|
986
|
-
* - `not-started`: no run and nothing owed: its `where` declined the event, or it subscribed after
|
|
987
|
-
* the run settled.
|
|
988
|
-
*/
|
|
989
|
-
type LifecycleDeliveryState = 'started' | 'owed' | 'coalesced' | 'failed' | 'not-started';
|
|
990
|
-
/** One subscriber of a settled run's lifecycle event, as the run detail lists it. */
|
|
991
|
-
interface LifecycleDelivery {
|
|
992
|
-
subscriber: string;
|
|
993
|
-
state: LifecycleDeliveryState;
|
|
994
|
-
/** The subscriber's run when `started`; the accumulator run when `coalesced` and derivable. */
|
|
995
|
-
runId?: string | undefined;
|
|
996
|
-
/** The status of a `started` subscriber's run, when it was read. */
|
|
997
|
-
status?: RunStatus | undefined;
|
|
998
|
-
/** The namespace of a `started` subscriber's run, when it was read. */
|
|
999
|
-
namespace?: string | undefined;
|
|
1000
|
-
/** When an `owed` subscriber became owed: the settled run's last update (epoch ms). */
|
|
1001
|
-
owedSince?: number | undefined;
|
|
1002
|
-
/**
|
|
1003
|
-
* When the lifecycle sweep drops an `owed` subscriber that no live instance registers or
|
|
1004
|
-
* announces for the run's namespace (epoch ms; see {@link LIFECYCLE_ORPHAN_MS}). Absent while one
|
|
1005
|
-
* does.
|
|
1006
|
-
*/
|
|
1007
|
-
orphanAt?: number | undefined;
|
|
1008
|
-
/**
|
|
1009
|
-
* Why a `failed` subscriber did not start, when the caller knows it (the run's tags record only
|
|
1010
|
-
* that it failed; the `run.trigger_failed` event carries the message). {@link lifecycleDeliveriesOf}
|
|
1011
|
-
* leaves it unset.
|
|
1012
|
-
*/
|
|
1013
|
-
error?: string | undefined;
|
|
1014
|
-
}
|
|
1015
|
-
/**
|
|
1016
|
-
* The {@link LifecycleDelivery} of each subscriber of a settled run, sorted by subscriber: the
|
|
1017
|
-
* union of `subscribers` (the ones the run's event goes to now) and the owed, triggered, coalesced
|
|
1018
|
-
* and trigger-failed tags. `live` names the subscribers a live instance registers or announces; an owed subscriber
|
|
1019
|
-
* outside it gets `orphanAt`. `coalesced` maps each subscriber that coalesces its events to its
|
|
1020
|
-
* accumulator run id (undefined when it cannot be derived). Empty for a run that has not settled.
|
|
1021
|
-
*/
|
|
1022
|
-
declare function lifecycleDeliveriesOf(run: Pick<WorkflowRun, 'id' | 'status' | 'tags' | 'updatedAt'>, opts: {
|
|
1023
|
-
subscribers: readonly string[];
|
|
1024
|
-
live: ReadonlySet<string>;
|
|
1025
|
-
coalesced?: ReadonlyMap<string, string | undefined> | undefined;
|
|
1026
|
-
}): LifecycleDelivery[];
|
|
1027
|
-
/** The trace id of a W3C `traceparent` (`00-<trace id>-<span id>-<flags>`), or undefined. */
|
|
1028
|
-
declare function traceIdOfTraceparent(traceparent: string | undefined): string | undefined;
|
|
1029
|
-
|
|
1030
1012
|
/**
|
|
1031
1013
|
* One loaded copy of this package: its version and the real path of its package root. Two copies are
|
|
1032
1014
|
* the same when their roots are, so the `src` and `dist` builds of one checkout, the ESM and CJS
|
|
@@ -1868,502 +1850,778 @@ declare function codeAndDetails(err: unknown): {
|
|
|
1868
1850
|
details?: unknown;
|
|
1869
1851
|
};
|
|
1870
1852
|
|
|
1871
|
-
/** Default idle threshold for a stranded run: 15 minutes. */
|
|
1872
|
-
declare const DEFAULT_STALLED_AFTER_MS: number;
|
|
1873
|
-
/** The oldest unresolved remote step of a run — the lost-dispatch signature when it is old. */
|
|
1874
|
-
interface StalePendingStep {
|
|
1875
|
-
seq: number;
|
|
1876
|
-
name: string;
|
|
1877
|
-
/** How many times this step has been (re-)dispatched. A lost dispatch typically sits at 1. */
|
|
1878
|
-
attempts: number;
|
|
1879
|
-
/** Milliseconds since the step was enqueued to the transport. */
|
|
1880
|
-
ageMs: number;
|
|
1881
|
-
/**
|
|
1882
|
-
* The step's lease (`wakeAt`, epoch ms) when it has one: a step with a `timeoutMs`, a heartbeat
|
|
1883
|
-
* renewing it, or `remoteRedispatchMs`. `null` when nothing is leasing the step.
|
|
1884
|
-
*/
|
|
1885
|
-
leaseUntil: number | null;
|
|
1886
|
-
}
|
|
1887
|
-
/** What an `engine.onStalled` listener (and {@link findStalledRuns}) receives: a stranded run and why. */
|
|
1888
|
-
interface StalledRunInfo {
|
|
1889
|
-
run: WorkflowRun;
|
|
1890
|
-
/** Milliseconds since the run's last activity (`updatedAt`). */
|
|
1891
|
-
ageMs: number;
|
|
1892
|
-
/** Suspended with NO wake timer — nothing will re-drive it (the `reconcileMs: 0` hazard). */
|
|
1893
|
-
wakeForever: boolean;
|
|
1894
|
-
/** The oldest pending remote step with no live lease, when that is the stranding signature. */
|
|
1895
|
-
stalePending: StalePendingStep | null;
|
|
1896
|
-
}
|
|
1897
|
-
/** Options for {@link findStalledRuns}. */
|
|
1898
|
-
interface FindStalledRunsOptions {
|
|
1899
|
-
/** Idle threshold in ms. Default {@link DEFAULT_STALLED_AFTER_MS}. */
|
|
1900
|
-
thresholdMs?: number | undefined;
|
|
1901
|
-
/** Max candidate runs inspected (newest first). Default 1000. */
|
|
1902
|
-
scan?: number | undefined;
|
|
1903
|
-
/** Evaluate as of this time (epoch ms). Default `Date.now()`. */
|
|
1904
|
-
now?: number | undefined;
|
|
1905
|
-
/** Only runs in this namespace. Omit for every namespace. */
|
|
1906
|
-
namespace?: string | undefined;
|
|
1907
|
-
}
|
|
1908
|
-
/**
|
|
1909
|
-
* The stranded runs in a store right now — the query behind `engine.sweepStalled`/`onStalled`,
|
|
1910
|
-
* `engine.listStalledRuns` and the CLI's `durable inspect --stale`. Works on a bare store, so an
|
|
1911
|
-
* ops script or a CLI can run it without an engine.
|
|
1912
|
-
*
|
|
1913
|
-
* A `running`/`suspended` run qualifies when it has been untouched for `thresholdMs` AND either:
|
|
1914
|
-
*
|
|
1915
|
-
* - it is suspended with NO wake timer (`wakeForever`): nothing will ever re-drive it; or
|
|
1916
|
-
* - its oldest pending REMOTE step is older than the threshold and has no lease in the future
|
|
1917
|
-
* (`stalePending`): the dispatch was most likely lost.
|
|
1918
|
-
*
|
|
1919
|
-
* Healthy long work is excluded: a long `ctx.sleep` has a future `wakeAt` and no pending step, and a
|
|
1920
|
-
* remote step with a `timeoutMs`, a heartbeat or `remoteRedispatchMs` carries a future lease. Issues
|
|
1921
|
-
* one `listCheckpoints` per idle candidate, bounded by `scan`: an operator read, not a hot path.
|
|
1922
|
-
*/
|
|
1923
|
-
declare function findStalledRuns(store: Pick<StateStore, 'listRuns' | 'listCheckpoints'>, options?: FindStalledRunsOptions): Promise<StalledRunInfo[]>;
|
|
1924
|
-
|
|
1925
1853
|
/**
|
|
1926
|
-
*
|
|
1927
|
-
*
|
|
1928
|
-
*
|
|
1929
|
-
*
|
|
1930
|
-
* worker presents IN the existing `tenant` wire field, which the operator's {@link TenantVerifier}
|
|
1931
|
-
* checks and DERIVES the real tenant from, never trusting the body.
|
|
1932
|
-
*
|
|
1933
|
-
* Wire-compatible with Agora (`@adonis-agora/durable`) byte for byte: the token is
|
|
1934
|
-
* `<claim>.<base64url(HMAC-SHA256(secret, claim))>`, where `claim` is the tenant name, optionally
|
|
1935
|
-
* followed by `.exp<epochMs>`. It fits the `tenant: string` field with NO envelope change, so an
|
|
1936
|
-
* operator that does not verify simply treats the whole string as the tenant name (and finds no
|
|
1937
|
-
* runs, a safe failure), while an operator configured with {@link hmacTenantVerifier} verifies the
|
|
1938
|
-
* signature and scopes to the embedded tenant. Agora and Aviary tokens are interchangeable.
|
|
1939
|
-
*
|
|
1940
|
-
* HMAC (shared secret) is the zero-infra default; a deployment that prefers asymmetric or issued
|
|
1941
|
-
* tokens supplies its own {@link TenantVerifier} instead.
|
|
1854
|
+
* A schedule definition — what `engine.schedules.create/upsert` take. Temporal-style: a persisted,
|
|
1855
|
+
* runtime-managed recurring start of `workflow` with `input`, fired by every driving engine's timer
|
|
1856
|
+
* poll (safe with many workers: each window's run id is deterministic, `start` is idempotent, and
|
|
1857
|
+
* advancing the schedule is a compare-and-set).
|
|
1942
1858
|
*/
|
|
1943
|
-
|
|
1944
|
-
|
|
1945
|
-
|
|
1946
|
-
|
|
1859
|
+
interface ScheduleOptions {
|
|
1860
|
+
/** Stable id, unique per store (e.g. `digest:user-42`). Part of every run id it starts. */
|
|
1861
|
+
id: string;
|
|
1862
|
+
/** The workflow to start — a registered name or `@Workflow` class. */
|
|
1863
|
+
workflow: WorkflowRef;
|
|
1864
|
+
/** The input every run starts with. */
|
|
1865
|
+
input?: unknown;
|
|
1866
|
+
/** Cron expression (5 fields, or 6 with leading seconds). Needs the `cron-parser` peer. */
|
|
1867
|
+
cron?: string | undefined;
|
|
1868
|
+
/** Fixed interval (`'15m'`, or ms), windows aligned to the epoch. Exclusive with `cron`. */
|
|
1869
|
+
every?: string | number | undefined;
|
|
1947
1870
|
/**
|
|
1948
|
-
*
|
|
1949
|
-
*
|
|
1950
|
-
*
|
|
1951
|
-
* its own namespace.
|
|
1871
|
+
* An RFC 5545 recurrence rule (`'FREQ=WEEKLY;BYDAY=MO;BYHOUR=8'`, optionally with a
|
|
1872
|
+
* `DTSTART:…` line), evaluated in `timezone`. Exactly one of `cron`, `every` and `rrule`. See
|
|
1873
|
+
* {@link parseRRule} for the supported parts. No peer needed.
|
|
1952
1874
|
*/
|
|
1953
|
-
|
|
1954
|
-
|
|
1955
|
-
|
|
1956
|
-
* Verifies a tenant's signed claim on the **operator** side, returning the {@link VerifiedTenant} it
|
|
1957
|
-
* authenticates as, or `null` (or throwing) to reject a tampered/invalid/absent token. The signed
|
|
1958
|
-
* token travels in the wire `tenant` field, so the responder passes that value as both `token` and
|
|
1959
|
-
* the advisory `tenant`.
|
|
1960
|
-
*/
|
|
1961
|
-
type TenantVerifier = (input: {
|
|
1962
|
-
/** The signed token presented on the request. */
|
|
1963
|
-
token?: string | undefined;
|
|
1964
|
-
/** The tenant the request *claims* to be. Advisory only: the verifier derives the real one. */
|
|
1965
|
-
tenant?: string | undefined;
|
|
1966
|
-
}) => VerifiedTenant | null | Promise<VerifiedTenant | null>;
|
|
1967
|
-
/**
|
|
1968
|
-
* Where the tenant side gets the token it presents: a static string, or a function called before
|
|
1969
|
-
* every request (so a short-lived token from {@link signTenantToken} with `ttlMs` can be re-minted
|
|
1970
|
-
* or fetched from a secret store without restarting the worker).
|
|
1971
|
-
*/
|
|
1972
|
-
type TenantTokenSource = string | (() => string | Promise<string>);
|
|
1973
|
-
/**
|
|
1974
|
-
* Mint the signed token a tenant worker presents:
|
|
1975
|
-
* `` `${tenant}.${base64url(HMAC-SHA256(secret, tenant))}` ``. The worker carries only the token
|
|
1976
|
-
* (never the secret); the operator verifies it with the SAME `secret` via {@link hmacTenantVerifier}.
|
|
1977
|
-
*/
|
|
1978
|
-
declare function signTenantToken(tenant: string, secret: string, opts?: {
|
|
1875
|
+
rrule?: string | undefined;
|
|
1876
|
+
/** IANA timezone the cron / rrule is evaluated in (e.g. `America/Sao_Paulo`). Default UTC. */
|
|
1877
|
+
timezone?: string | undefined;
|
|
1979
1878
|
/**
|
|
1980
|
-
*
|
|
1981
|
-
*
|
|
1982
|
-
* token never expires. Expiring and non-expiring tokens verify side by side. Tenant names
|
|
1983
|
-
* ending in `.exp<digits>` are reserved by this scheme.
|
|
1879
|
+
* Delay each fire by up to this much (`'30s'` or ms) — a stable per-(schedule, window) offset, so
|
|
1880
|
+
* thousands of schedules on the same cron don't all start in the same second.
|
|
1984
1881
|
*/
|
|
1985
|
-
|
|
1986
|
-
/** Injectable clock for tests. */
|
|
1987
|
-
now?: number;
|
|
1988
|
-
}): string;
|
|
1989
|
-
/**
|
|
1990
|
-
* Build the operator-side {@link TenantVerifier} for {@link signTenantToken} tokens under `secret`.
|
|
1991
|
-
* It recomputes the HMAC over the embedded claim and compares it in constant time, so a tampered
|
|
1992
|
-
* tenant, a forged/absent signature, a token signed with another secret, or an expired token all
|
|
1993
|
-
* return `null`. The tenant is DERIVED from the token's own claim.
|
|
1994
|
-
*
|
|
1995
|
-
* A LIST of secrets makes rotation a two-step deploy: verify with `[next, current]` everywhere first,
|
|
1996
|
-
* then re-mint tenant tokens with `next` at leisure. `capabilities`, if given, is a static grant
|
|
1997
|
-
* stamped onto every {@link VerifiedTenant} this verifier authenticates (informational: the
|
|
1998
|
-
* responder does not enforce it yet, see {@link VerifiedTenant.capabilities}).
|
|
1999
|
-
*/
|
|
2000
|
-
declare function hmacTenantVerifier(secret: string | string[], capabilities?: string[]): TenantVerifier;
|
|
2001
|
-
/**
|
|
2002
|
-
* Verify a wire message's `tenant`: with a verifier, the {@link VerifiedTenant} it derives (`null` on
|
|
2003
|
-
* reject); without one, the wire value trusted verbatim, with no capabilities.
|
|
2004
|
-
*/
|
|
2005
|
-
declare function verifyWireTenant(wireTenant: string, verifyTenant: TenantVerifier | undefined): Promise<VerifiedTenant | null>;
|
|
2006
|
-
/**
|
|
2007
|
-
* Whether a verified tenant process may claim the customer `tenantId` for a run it starts: its
|
|
2008
|
-
* `capabilities` hold `tenancy:*` (any customer) or `tenancy:<tenantId>`. An unverified process (no
|
|
2009
|
-
* verifier) holds none, so it never may.
|
|
2010
|
-
*/
|
|
2011
|
-
declare function grantsClientTenant(verified: VerifiedTenant | null, tenantId: string): boolean;
|
|
2012
|
-
/**
|
|
2013
|
-
* Resolve the tenant a wire message is ALLOWED to act as. With a verifier, the wire `tenant` is the
|
|
2014
|
-
* signed token: it is verified and the real tenant derived from it (`null` on reject). Without one,
|
|
2015
|
-
* the wire value is trusted verbatim (prefix/network isolation only, today's behaviour).
|
|
2016
|
-
*/
|
|
2017
|
-
declare function resolveWireTenant(wireTenant: string, verifyTenant: TenantVerifier | undefined): Promise<string | null>;
|
|
2018
|
-
/** Resolve a {@link TenantTokenSource} to the token string to put on the wire. */
|
|
2019
|
-
declare function resolveTenantToken(source: TenantTokenSource): Promise<string>;
|
|
2020
|
-
|
|
2021
|
-
type WorkflowFn = (ctx: WorkflowCtx, input: unknown) => Promise<unknown>;
|
|
2022
|
-
/**
|
|
2023
|
-
* Options for {@link WorkflowEngine.start}.
|
|
2024
|
-
*
|
|
2025
|
-
* Note the absence of `origin`: {@link WorkflowRun.origin} says which PACKAGE declared the workflow,
|
|
2026
|
-
* which is a property of the registered code, not of whoever started it. It is taken from the
|
|
2027
|
-
* registration and nothing here can override it — otherwise one caller could label its runs as
|
|
2028
|
-
* another lib's, and an origin filter would quietly lie.
|
|
2029
|
-
*/
|
|
2030
|
-
interface StartOptions {
|
|
1882
|
+
jitter?: string | number | undefined;
|
|
2031
1883
|
/**
|
|
2032
|
-
*
|
|
2033
|
-
*
|
|
2034
|
-
*
|
|
2035
|
-
* Resolved against the by-name@version registry, so it pins anything explicitly registered:
|
|
2036
|
-
* {@link WorkflowEngine.register}, {@link WorkflowEngine.registerRemote}, {@link WorkflowEngine.remote}.
|
|
2037
|
-
* A version that is NOT registered throws before a run row is created and NEVER falls back to
|
|
2038
|
-
* `latest` — a silent fallback is the exact failure this option exists to prevent (a caller that
|
|
2039
|
-
* asked for `name@3` and got `name@4` has no way to tell, and its run is already going).
|
|
2040
|
-
*
|
|
2041
|
-
* NOT available on a child inheriting its remote ancestor's routing (see `findInheritedRegistration`),
|
|
2042
|
-
* which INVENTS the version it stamps (the ancestor's). Convention routing to a live worker group of
|
|
2043
|
-
* the same name (`resolveRemoteByConvention`) honours a pin only when the live workers on that group
|
|
2044
|
-
* themselves DECLARE the pinned version (their announced registrations); a fleet that declares
|
|
2045
|
-
* another version, or none, is no evidence, and the pinned start throws rather than pretending. To
|
|
2046
|
-
* pin a cross-SDK workflow whose workers declare nothing, register it for real —
|
|
2047
|
-
* `engine.remote('name', { version: '2', group })` — which puts `name@2` in the registry.
|
|
2048
|
-
*
|
|
2049
|
-
* A tenant's start ({@link StartRunMessage.version}) does not throw: with no live worker declaring
|
|
2050
|
-
* the version yet, the run waits `blocked` (`no_live_worker`) until one does.
|
|
2051
|
-
*/
|
|
2052
|
-
version?: string | undefined;
|
|
2053
|
-
/** Run-scoped tags, merged with the workflow's static `@Workflow({ tags })` onto the run. */
|
|
2054
|
-
tags?: string[] | undefined;
|
|
2055
|
-
/** Typed, queryable run data stamped on the run (e.g. `{ amount: 200, tier: 'pro' }`). */
|
|
2056
|
-
searchAttributes?: SearchAttributes | undefined;
|
|
2057
|
-
/**
|
|
2058
|
-
* Dispatch priority for a remote run — stamped on the run and carried onto every {@link WorkflowTask}
|
|
2059
|
-
* the engine dispatches to advance it. Higher wins; absent = unprioritised. See {@link WorkflowRun.priority}.
|
|
1884
|
+
* The previous run of this schedule is still in flight when the next window comes due:
|
|
1885
|
+
* `'allow'` (default) starts the new one anyway; `'skip'` skips that window.
|
|
2060
1886
|
*/
|
|
2061
|
-
|
|
1887
|
+
overlap?: 'allow' | 'skip' | undefined;
|
|
2062
1888
|
/**
|
|
2063
|
-
*
|
|
2064
|
-
*
|
|
2065
|
-
*
|
|
1889
|
+
* Windows missed while nothing polled (all schedulers down): `'latest'` (default) fires the most
|
|
1890
|
+
* recent missed window once; `'skip'` drops them and waits for the next window. Never more than one
|
|
1891
|
+
* catch-up run per schedule.
|
|
2066
1892
|
*/
|
|
1893
|
+
catchup?: 'latest' | 'skip' | undefined;
|
|
1894
|
+
/** Create paused (never due until `resume`). On `upsert`, omit to keep the current paused state. */
|
|
1895
|
+
paused?: boolean | undefined;
|
|
1896
|
+
/** Free-form note shown with the schedule (why it exists / why it's paused). */
|
|
1897
|
+
note?: string | undefined;
|
|
1898
|
+
/** Namespace of the schedule and of the runs it starts. Defaults to the engine's own namespace. */
|
|
2067
1899
|
namespace?: string | undefined;
|
|
1900
|
+
/** Labels to find the schedule by — also stamped on every run it starts (plus `schedule:<id>`). */
|
|
1901
|
+
tags?: string[] | undefined;
|
|
1902
|
+
/** Search attributes stamped on every run it starts. */
|
|
1903
|
+
searchAttributes?: SearchAttributes | undefined;
|
|
1904
|
+
/** Dispatch priority for the runs it starts. */
|
|
1905
|
+
priority?: number | undefined;
|
|
2068
1906
|
/**
|
|
2069
|
-
* A start-time concurrency quota
|
|
2070
|
-
*
|
|
2071
|
-
*
|
|
1907
|
+
* A start-time concurrency quota applied to every run it starts (see `StartOptions.concurrency`):
|
|
1908
|
+
* a window whose start would exceed it is recorded as the schedule's `lastError` and skipped, and
|
|
1909
|
+
* the schedule moves on to its next window.
|
|
2072
1910
|
*/
|
|
2073
1911
|
concurrency?: ConcurrencyQuota | undefined;
|
|
2074
1912
|
/**
|
|
2075
|
-
*
|
|
2076
|
-
*
|
|
2077
|
-
*
|
|
2078
|
-
* timer poller (`resumeDueTimers`) starts it once due, on any instance. A time that is not in the
|
|
2079
|
-
* future starts the run at once, as if it were omitted.
|
|
2080
|
-
*
|
|
2081
|
-
* A delayed run reads `suspended` until it fires (so `start` returns `suspended`, and `waitForRun`
|
|
2082
|
-
* settles on that right away), and skips the `run.started` event's `pending → running` hop. It
|
|
2083
|
-
* counts as in flight for singleton back-pressure and concurrency quotas while it waits.
|
|
2084
|
-
*/
|
|
2085
|
-
startAt?: number | Date | undefined;
|
|
2086
|
-
/**
|
|
2087
|
-
* The customer this run belongs to (see {@link WorkflowRun.tenantId}). An explicit value always
|
|
2088
|
-
* wins; `null` starts it with no tenant. Omit it and the run takes the context tenant when tenancy
|
|
2089
|
-
* is on, else none.
|
|
1913
|
+
* The customer the schedule belongs to; every run it starts inherits it. An explicit value wins
|
|
1914
|
+
* (`null` = none); omit it and the schedule takes the context tenant when tenancy is on. On
|
|
1915
|
+
* `upsert`, omit to keep the schedule's current tenant.
|
|
2090
1916
|
*/
|
|
2091
1917
|
tenantId?: string | null | undefined;
|
|
2092
|
-
/** The kind of {@link tenantId}
|
|
1918
|
+
/** The kind of {@link tenantId}. Only read with an explicit `tenantId`. */
|
|
2093
1919
|
tenantKind?: string | undefined;
|
|
2094
1920
|
}
|
|
2095
|
-
/**
|
|
2096
|
-
|
|
2097
|
-
|
|
2098
|
-
|
|
2099
|
-
|
|
2100
|
-
|
|
2101
|
-
|
|
2102
|
-
|
|
2103
|
-
|
|
2104
|
-
|
|
2105
|
-
|
|
1921
|
+
/** A schedule as `engine.schedules.get/list` describe it. */
|
|
1922
|
+
interface ScheduleDescription {
|
|
1923
|
+
id: string;
|
|
1924
|
+
workflow: string;
|
|
1925
|
+
input: unknown;
|
|
1926
|
+
namespace: string;
|
|
1927
|
+
cron?: string | undefined;
|
|
1928
|
+
everyMs?: number | undefined;
|
|
1929
|
+
rrule?: string | undefined;
|
|
1930
|
+
timezone?: string | undefined;
|
|
1931
|
+
jitterMs?: number | undefined;
|
|
1932
|
+
overlap: 'allow' | 'skip';
|
|
1933
|
+
catchup: 'latest' | 'skip';
|
|
1934
|
+
paused: boolean;
|
|
1935
|
+
note?: string | undefined;
|
|
1936
|
+
tags?: string[] | undefined;
|
|
1937
|
+
searchAttributes?: SearchAttributes | undefined;
|
|
1938
|
+
priority?: number | undefined;
|
|
1939
|
+
concurrency?: ConcurrencyQuota | undefined;
|
|
1940
|
+
/** When it is next due (jitter included), or null if it never fires again / paused. */
|
|
1941
|
+
nextFireAt: Date | null;
|
|
1942
|
+
/** The last window it fired for, and the run that window started. */
|
|
1943
|
+
lastFireAt?: Date | undefined;
|
|
1944
|
+
lastRunId?: string | undefined;
|
|
1945
|
+
/** How many windows it has fired (manual triggers excluded). */
|
|
1946
|
+
fires: number;
|
|
1947
|
+
/** The last start failure (e.g. a concurrency limit), cleared by the next successful start. */
|
|
1948
|
+
lastError?: string | undefined;
|
|
1949
|
+
/** The customer the schedule and its runs belong to, when it has one. */
|
|
1950
|
+
tenantId?: string | undefined;
|
|
1951
|
+
tenantKind?: string | undefined;
|
|
2106
1952
|
/**
|
|
2107
|
-
*
|
|
2108
|
-
*
|
|
2109
|
-
* `limit + maxQueueDepth` — back-pressure against an unbounded same-key backlog. Omit for the
|
|
2110
|
-
* default unbounded queue. Counts pending/running/suspended/blocked/cancelling runs sharing the key.
|
|
1953
|
+
* Set on a schedule a tenant app ANNOUNCED (its `schedules` module option) and the control plane
|
|
1954
|
+
* adopted: the key the app declares it under. Its `namespace` is the app (partition).
|
|
2111
1955
|
*/
|
|
2112
|
-
|
|
1956
|
+
announcedKey?: string | undefined;
|
|
1957
|
+
/** An announced schedule that no live worker of its app announces any more: since when. */
|
|
1958
|
+
unannouncedSince?: Date | undefined;
|
|
1959
|
+
/** When the control plane paused it for staying unannounced past the grace period. */
|
|
1960
|
+
withdrawnAt?: Date | undefined;
|
|
1961
|
+
createdAt: Date;
|
|
1962
|
+
updatedAt: Date;
|
|
1963
|
+
}
|
|
1964
|
+
/** The tag on every schedule adopted from a tenant's announcement (and on the runs it starts). */
|
|
1965
|
+
declare const ANNOUNCED_SCHEDULE_TAG = "schedule:announced";
|
|
1966
|
+
/** The control plane's schedule id for the schedule `key` announced by the app on `namespace`. */
|
|
1967
|
+
declare function announcedScheduleId(namespace: string, key: string): string;
|
|
1968
|
+
/** Filter for `engine.schedules.list`. */
|
|
1969
|
+
type ScheduleListQuery = Omit<ScheduleQuery, 'dueBy'>;
|
|
1970
|
+
/** Thrown by `engine.schedules.create` when the id is taken (use `upsert` to replace). */
|
|
1971
|
+
declare class ScheduleAlreadyExistsError extends Error {
|
|
1972
|
+
readonly scheduleId: string;
|
|
1973
|
+
constructor(scheduleId: string);
|
|
1974
|
+
}
|
|
1975
|
+
/** Thrown by `engine.schedules.*` on an id that doesn't exist. */
|
|
1976
|
+
declare class ScheduleNotFoundError extends Error {
|
|
1977
|
+
readonly scheduleId: string;
|
|
1978
|
+
constructor(scheduleId: string);
|
|
1979
|
+
}
|
|
1980
|
+
/** What {@link ScheduleClient.syncAnnounced} did to a namespace's adopted schedules. */
|
|
1981
|
+
interface AnnouncedScheduleSync {
|
|
1982
|
+
/** Created, or re-applied because the announced definition changed. */
|
|
1983
|
+
adopted: string[];
|
|
1984
|
+
/** Announced again after missing (and resumed, when it had been withdrawn). */
|
|
1985
|
+
restored: string[];
|
|
1986
|
+
/** Missing from the announcement for the first time: the grace period starts. */
|
|
1987
|
+
missing: string[];
|
|
1988
|
+
/** Paused because it stayed unannounced past the grace period. */
|
|
1989
|
+
withdrawn: string[];
|
|
1990
|
+
/** Announced, but the definition does not evaluate (bad cron, both or neither cadence). */
|
|
1991
|
+
invalid: {
|
|
1992
|
+
key: string;
|
|
1993
|
+
error: string;
|
|
1994
|
+
}[];
|
|
1995
|
+
}
|
|
1996
|
+
/** The engine surface the schedule client drives. */
|
|
1997
|
+
interface ScheduleHost {
|
|
1998
|
+
start(workflow: string, input: unknown, runId: string, opts?: StartOptions): Promise<RunResult>;
|
|
1999
|
+
/**
|
|
2000
|
+
* The tenant start path, used to fire an announced schedule: a workflow no live worker serves yet
|
|
2001
|
+
* is parked `blocked` (`no_live_worker`) until one is, instead of throwing. Absent = `start`.
|
|
2002
|
+
*/
|
|
2003
|
+
startParked?(workflow: string, input: unknown, runId: string, opts?: StartOptions, singleton?: StartRunSingleton): Promise<RunResult>;
|
|
2004
|
+
getRun(runId: string): Promise<WorkflowRun | null>;
|
|
2005
|
+
/** True once the engine has begun shutting down; `tick` fires nothing more after that. */
|
|
2006
|
+
isDraining?(): boolean;
|
|
2007
|
+
/** The context tenant to stamp on a schedule created now (tenancy on), else undefined. */
|
|
2008
|
+
tenant?(): RunTenant | undefined;
|
|
2009
|
+
/** The tenancy matching filter for an app-facing call made now. Absent = sees everything. */
|
|
2010
|
+
tenantFilter?(): TenantFilter;
|
|
2011
|
+
}
|
|
2012
|
+
/** Engine-level knobs for the client. */
|
|
2013
|
+
interface ScheduleClientOptions {
|
|
2014
|
+
/** The engine's namespace: the default for new schedules, and which ones `tick` fires. */
|
|
2015
|
+
namespace?: string | undefined;
|
|
2016
|
+
clock?: (() => number) | undefined;
|
|
2113
2017
|
}
|
|
2114
2018
|
/**
|
|
2115
|
-
*
|
|
2116
|
-
*
|
|
2117
|
-
*
|
|
2118
|
-
*
|
|
2119
|
-
* ## Why a run has to carry this
|
|
2120
|
-
*
|
|
2121
|
-
* Such a run's `workflowVersion` is `'1'`, the engine's convention default. That value is a routing
|
|
2122
|
-
* placeholder, not an observation — and read back later it is indistinguishable from a worker that
|
|
2123
|
-
* genuinely declared version `'1'`. Any check comparing an authored pin against it therefore passes
|
|
2124
|
-
* whenever the pin is `'1'` and fails whenever it is not, regardless of what the callee actually is.
|
|
2125
|
-
* A check that cannot fail is worse than no check, because it reads as a guarantee.
|
|
2126
|
-
*
|
|
2127
|
-
* The tag is the difference, carried ON the run so a retrospective check needs no second read: a
|
|
2128
|
-
* caller that pinned a version can see that the version it is comparing against was never stated,
|
|
2129
|
-
* and say so, instead of reporting a match it did not really make. It is deliberately a tag rather
|
|
2130
|
-
* than a new column — every store already persists and queries tags, so this needs no migration and
|
|
2131
|
-
* shows up in run listings and dashboards for free. Follows the `singleton:<key>` precedent for an
|
|
2132
|
-
* engine-stamped reserved tag.
|
|
2019
|
+
* Persisted, runtime-managed schedules — `engine.schedules`. Unlike the code-registered
|
|
2020
|
+
* `schedules` module option, these live in the store: create/update/pause/delete them at runtime
|
|
2021
|
+
* (one per user, per tenant, per automation…), and every driving engine's timer poll fires the due
|
|
2022
|
+
* ones via {@link tick}.
|
|
2133
2023
|
*
|
|
2134
|
-
*
|
|
2135
|
-
*
|
|
2136
|
-
|
|
2137
|
-
|
|
2138
|
-
/**
|
|
2139
|
-
* The `error.code` of a run a tenant started while no live worker served it yet (see
|
|
2140
|
-
* `WorkflowEngine.startForTenant`). The run is parked `blocked` and the blocked-recovery poll starts
|
|
2141
|
-
* it as soon as a worker on its group (declaring its pinned version, when it has one) is live. It is
|
|
2142
|
-
* never dead-lettered for waiting: a start is a request queued for its consumer, however late that
|
|
2143
|
-
* consumer boots. Cancel it to drop it.
|
|
2144
|
-
*/
|
|
2145
|
-
declare const NO_LIVE_WORKER = "no_live_worker";
|
|
2146
|
-
/**
|
|
2147
|
-
* How long an adopted tenant schedule may go unannounced by every live worker of its app before the
|
|
2148
|
-
* control plane pauses it (see `WorkflowEngine.syncAnnouncedSchedules`). Long enough to ride out a
|
|
2149
|
-
* rolling deploy; a schedule is never deleted for missing.
|
|
2024
|
+
* Multi-worker safety comes from two properties, not from a lock: a window's run id is deterministic
|
|
2025
|
+
* (`sched:<id>:<windowMs>`), so racing starts of the same window collapse into one run; and a
|
|
2026
|
+
* schedule is advanced with a compare-and-set on its `nextFireAt`, so exactly one poller moves it on.
|
|
2027
|
+
* A crash between starting the run and advancing the schedule just re-fires the (idempotent) start.
|
|
2150
2028
|
*/
|
|
2151
|
-
declare
|
|
2152
|
-
|
|
2153
|
-
|
|
2154
|
-
|
|
2155
|
-
|
|
2029
|
+
declare class ScheduleClient {
|
|
2030
|
+
private readonly store;
|
|
2031
|
+
private readonly host;
|
|
2032
|
+
private readonly options;
|
|
2033
|
+
constructor(store: StateStore, host: ScheduleHost, options?: ScheduleClientOptions);
|
|
2034
|
+
private now;
|
|
2035
|
+
/** Whether the store persists schedules (implements the schedule methods). */
|
|
2036
|
+
get supported(): boolean;
|
|
2037
|
+
private requireStore;
|
|
2038
|
+
private filter;
|
|
2039
|
+
/** The schedule `id` if it exists and the caller may see it (tenancy), else null. */
|
|
2040
|
+
private visible;
|
|
2041
|
+
/** Create a schedule. Throws {@link ScheduleAlreadyExistsError} if the id is taken. */
|
|
2042
|
+
create(opts: ScheduleOptions): Promise<ScheduleDescription>;
|
|
2156
2043
|
/**
|
|
2157
|
-
*
|
|
2158
|
-
*
|
|
2159
|
-
*
|
|
2044
|
+
* Create the schedule, or replace the definition of an existing one (its history — last fire, last
|
|
2045
|
+
* run, fire count — is kept). The next fire is recomputed from now under the new definition, so a
|
|
2046
|
+
* window that already fired is never fired again by an upsert.
|
|
2160
2047
|
*/
|
|
2161
|
-
|
|
2162
|
-
/**
|
|
2163
|
-
|
|
2164
|
-
|
|
2165
|
-
|
|
2166
|
-
|
|
2167
|
-
|
|
2168
|
-
/**
|
|
2169
|
-
|
|
2048
|
+
upsert(opts: ScheduleOptions): Promise<ScheduleDescription>;
|
|
2049
|
+
/** The schedule `id`, or null (also null for another tenant's schedule). */
|
|
2050
|
+
get(id: string): Promise<ScheduleDescription | null>;
|
|
2051
|
+
/** Schedules matching `query` (and visible to the caller's tenant), soonest-due first. */
|
|
2052
|
+
list(query?: ScheduleListQuery): Promise<ScheduleDescription[]>;
|
|
2053
|
+
/** Delete the schedule. Runs it already started are left alone. Returns whether it existed. */
|
|
2054
|
+
delete(id: string): Promise<boolean>;
|
|
2055
|
+
/** Stop firing until {@link resume}. `note` records why (shown by `get`/`list`). */
|
|
2056
|
+
pause(id: string, note?: string): Promise<ScheduleDescription>;
|
|
2170
2057
|
/**
|
|
2171
|
-
*
|
|
2172
|
-
* {@link InMemoryAdmissionBackend} (per-instance caps). Inject a store/Redis-backed backend to make
|
|
2173
|
-
* concurrency / rate-limit / ordering GLOBAL across engine replicas.
|
|
2058
|
+
* Fire again from the next window after now — the windows skipped while paused are NOT caught up.
|
|
2174
2059
|
*/
|
|
2175
|
-
|
|
2176
|
-
/** Unique id for this engine instance, used for recovery leases. Defaults to a random id. */
|
|
2177
|
-
instanceId?: string | undefined;
|
|
2060
|
+
resume(id: string): Promise<ScheduleDescription>;
|
|
2178
2061
|
/**
|
|
2179
|
-
*
|
|
2180
|
-
*
|
|
2181
|
-
* namespace. Set distinct values to safely share ONE state store across non-interchangeable pools
|
|
2182
|
-
* (e.g. local dev vs a cluster). **Omit it to make this engine an OPERATOR** — an unset namespace
|
|
2183
|
-
* drives/recovers/resumes runs of EVERY namespace (the poll filters no-op, the resume/decision
|
|
2184
|
-
* guards fall through) and leaves the transport on its bare prefix. This is the hosted control
|
|
2185
|
-
* plane: "ver tudo = ausência de namespace".
|
|
2062
|
+
* Start one run of the schedule right now, outside its cadence (paused or not). The run id is
|
|
2063
|
+
* `sched:<id>:manual:<nowMs>`; it doesn't move the schedule's next fire.
|
|
2186
2064
|
*/
|
|
2187
|
-
|
|
2065
|
+
trigger(id: string): Promise<RunResult>;
|
|
2188
2066
|
/**
|
|
2189
|
-
*
|
|
2190
|
-
*
|
|
2191
|
-
* A message whose token is rejected (or whose verifier throws) is dropped without creating a run.
|
|
2192
|
-
* Absent: the wire `tenant` is trusted verbatim, as before.
|
|
2067
|
+
* Start one run of `record`: through the tenant start path for an announced schedule (its run waits
|
|
2068
|
+
* `blocked` for a live worker of its app instead of failing), else a plain `start`.
|
|
2193
2069
|
*/
|
|
2194
|
-
|
|
2195
|
-
/** Recovery lease duration in ms — how long this instance owns a run it picked up. Default 30s. */
|
|
2196
|
-
leaseMs?: number | undefined;
|
|
2070
|
+
private startFor;
|
|
2197
2071
|
/**
|
|
2198
|
-
*
|
|
2199
|
-
*
|
|
2200
|
-
*
|
|
2072
|
+
* Fire every due schedule (in this engine's namespace; all namespaces for an operator engine; only
|
|
2073
|
+
* those carrying `opts.tag` when given):
|
|
2074
|
+
* start its window's run and advance it to the next window. Called by the NestJS timer poller on
|
|
2075
|
+
* each tick when `persistedSchedules` is on; call it yourself from any other driver. Returns the
|
|
2076
|
+
* run ids started (or re-found, for an idempotent re-fire).
|
|
2201
2077
|
*/
|
|
2202
|
-
|
|
2078
|
+
tick(nowMs?: number, opts?: {
|
|
2079
|
+
tag?: string;
|
|
2080
|
+
}): Promise<string[]>;
|
|
2203
2081
|
/**
|
|
2204
|
-
*
|
|
2205
|
-
*
|
|
2206
|
-
*
|
|
2207
|
-
*
|
|
2208
|
-
*
|
|
2209
|
-
* run became due (its `wakeAt` for a parked run, its last update otherwise), so a long sleep is not
|
|
2210
|
-
* counted. Default 24h; `0` disables (skip forever). A non-finite or negative value falls back to
|
|
2211
|
-
* the default.
|
|
2082
|
+
* When {@link tick} next has a schedule to fire, if one is due by `byMs`: the earliest `nextFireAt`
|
|
2083
|
+
* of the unpaused schedules (of this engine's namespace, carrying `opts.tag` when given) due by
|
|
2084
|
+
* then, else `undefined`. One indexed
|
|
2085
|
+
* read (the due-schedule scan `tick` makes, with a later bound and a limit of one). A store that
|
|
2086
|
+
* does not persist schedules has none.
|
|
2212
2087
|
*/
|
|
2213
|
-
|
|
2088
|
+
nextFireAt(byMs: number, opts?: {
|
|
2089
|
+
tag?: string;
|
|
2090
|
+
}): Promise<number | undefined>;
|
|
2091
|
+
/** Fire one due schedule and advance it. Returns the run id started, if any. */
|
|
2092
|
+
private fire;
|
|
2214
2093
|
/**
|
|
2215
|
-
*
|
|
2216
|
-
*
|
|
2217
|
-
* it
|
|
2218
|
-
*
|
|
2219
|
-
* legitimately replaying a long turn (it keeps beating) is never re-driven — closing the duplicate-
|
|
2220
|
-
* side-effect hazard a fixed {@link RemoteWorkflowExecutor} `timeoutMs` cannot avoid. Omit (default)
|
|
2221
|
-
* for the prior unbounded await — byte-identical behavior when unset. If a `RemoteWorkflowExecutor` is
|
|
2222
|
-
* ALSO constructed with its own `timeoutMs`, the shorter of the two deadlines wins; prefer setting only
|
|
2223
|
-
* one (this rearmed window for heartbeat-aware workers, or the fixed `timeoutMs` otherwise).
|
|
2224
|
-
*
|
|
2225
|
-
* A turn DISPATCHED over a broker (a tenant's or another SDK's worker) is never left without a
|
|
2226
|
-
* deadline: unset, its window is {@link reconcileMs} (5 min by default), so a run whose worker died
|
|
2227
|
-
* holding the turn is re-driven instead of waiting forever. `reconcileMs: 0` with this unset keeps
|
|
2228
|
-
* the old unbounded wait.
|
|
2094
|
+
* An announced schedule whose previous run is still parked waiting for a live worker of its app
|
|
2095
|
+
* (the app is down): this window is folded into that run instead of parking one more. However long
|
|
2096
|
+
* the app is down, it finds at most one run per schedule waiting when it comes back, the same
|
|
2097
|
+
* bound `catchup: 'latest'` puts on windows missed while no scheduler polled.
|
|
2229
2098
|
*/
|
|
2230
|
-
|
|
2099
|
+
private waitingForWorker;
|
|
2231
2100
|
/**
|
|
2232
|
-
*
|
|
2233
|
-
*
|
|
2234
|
-
*
|
|
2235
|
-
*
|
|
2236
|
-
*
|
|
2237
|
-
*
|
|
2238
|
-
*
|
|
2239
|
-
*
|
|
2240
|
-
*
|
|
2241
|
-
*
|
|
2101
|
+
* Reconcile the schedules adopted from one app (`namespace`) with what its LIVE workers announce
|
|
2102
|
+
* now (`items`, one per key; the caller resolved disagreeing workers). The rule:
|
|
2103
|
+
* - an announced key with no schedule yet is created (id {@link announcedScheduleId}, tagged
|
|
2104
|
+
* {@link ANNOUNCED_SCHEDULE_TAG}, `catchup: 'latest'`); one whose definition changed is
|
|
2105
|
+
* re-applied like `upsert` (its history kept, its next fire recomputed from now). An equal
|
|
2106
|
+
* definition writes nothing, so any number of replicas announcing the same set is a no-op;
|
|
2107
|
+
* - a pause or resume made from the console survives: a re-applied definition keeps the current
|
|
2108
|
+
* paused state, unless the app's own declared `paused` changed;
|
|
2109
|
+
* - an adopted schedule the app no longer announces is marked missing, and paused ("withdrawn")
|
|
2110
|
+
* once it has stayed missing for `graceMs`. It is never deleted: its history stays, and an app
|
|
2111
|
+
* that announces it again (a rollback) gets it back, resumed unless an operator had paused it.
|
|
2242
2112
|
*
|
|
2243
|
-
*
|
|
2244
|
-
*
|
|
2113
|
+
* Call it only for an app that has at least one live worker stating its schedules: with none (the
|
|
2114
|
+
* app is down, or runs an SDK that does not announce schedules), nothing is withdrawn, and its
|
|
2115
|
+
* schedules keep firing into runs that wait for a worker.
|
|
2245
2116
|
*/
|
|
2246
|
-
|
|
2117
|
+
syncAnnounced(namespace: string, items: readonly AnnouncedSchedule[], opts: {
|
|
2118
|
+
nowMs?: number;
|
|
2119
|
+
graceMs: number;
|
|
2120
|
+
}): Promise<AnnouncedScheduleSync>;
|
|
2121
|
+
/** `overlap: 'skip'` and the previous run of this schedule is still in flight. */
|
|
2122
|
+
private overlapping;
|
|
2123
|
+
private mustGet;
|
|
2124
|
+
/** Explicit `opts.tenantId` → the existing schedule's tenant (upsert) → the context tenant → none. */
|
|
2125
|
+
private scheduleTenant;
|
|
2126
|
+
private write;
|
|
2127
|
+
}
|
|
2128
|
+
|
|
2129
|
+
/** Default idle threshold for a stranded run: 15 minutes. */
|
|
2130
|
+
declare const DEFAULT_STALLED_AFTER_MS: number;
|
|
2131
|
+
/** The oldest unresolved remote step of a run — the lost-dispatch signature when it is old. */
|
|
2132
|
+
interface StalePendingStep {
|
|
2133
|
+
seq: number;
|
|
2134
|
+
name: string;
|
|
2135
|
+
/** How many times this step has been (re-)dispatched. A lost dispatch typically sits at 1. */
|
|
2136
|
+
attempts: number;
|
|
2137
|
+
/** Milliseconds since the step was enqueued to the transport. */
|
|
2138
|
+
ageMs: number;
|
|
2247
2139
|
/**
|
|
2248
|
-
*
|
|
2249
|
-
*
|
|
2250
|
-
* {@link WorkflowEngine.onStalled} listeners are notified. Default 900 000 (15 min); floored at
|
|
2251
|
-
* 60 000. The sweep ({@link WorkflowEngine.sweepStalled}) only does work when a listener is
|
|
2252
|
-
* registered.
|
|
2140
|
+
* The step's lease (`wakeAt`, epoch ms) when it has one: a step with a `timeoutMs`, a heartbeat
|
|
2141
|
+
* renewing it, or `remoteRedispatchMs`. `null` when nothing is leasing the step.
|
|
2253
2142
|
*/
|
|
2254
|
-
|
|
2143
|
+
leaseUntil: number | null;
|
|
2144
|
+
}
|
|
2145
|
+
/** What an `engine.onStalled` listener (and {@link findStalledRuns}) receives: a stranded run and why. */
|
|
2146
|
+
interface StalledRunInfo {
|
|
2147
|
+
run: WorkflowRun;
|
|
2148
|
+
/** Milliseconds since the run's last activity (`updatedAt`). */
|
|
2149
|
+
ageMs: number;
|
|
2150
|
+
/** Suspended with NO wake timer — nothing will re-drive it (the `reconcileMs: 0` hazard). */
|
|
2151
|
+
wakeForever: boolean;
|
|
2152
|
+
/** The oldest pending remote step with no live lease, when that is the stranding signature. */
|
|
2153
|
+
stalePending: StalePendingStep | null;
|
|
2154
|
+
}
|
|
2155
|
+
/** Options for {@link findStalledRuns}. */
|
|
2156
|
+
interface FindStalledRunsOptions {
|
|
2157
|
+
/** Idle threshold in ms. Default {@link DEFAULT_STALLED_AFTER_MS}. */
|
|
2158
|
+
thresholdMs?: number | undefined;
|
|
2159
|
+
/** Max candidate runs inspected (newest first). Default 1000. */
|
|
2160
|
+
scan?: number | undefined;
|
|
2161
|
+
/** Evaluate as of this time (epoch ms). Default `Date.now()`. */
|
|
2162
|
+
now?: number | undefined;
|
|
2163
|
+
/** Only runs in this namespace. Omit for every namespace. */
|
|
2164
|
+
namespace?: string | undefined;
|
|
2165
|
+
}
|
|
2166
|
+
/**
|
|
2167
|
+
* The stranded runs in a store right now — the query behind `engine.sweepStalled`/`onStalled`,
|
|
2168
|
+
* `engine.listStalledRuns` and the CLI's `durable inspect --stale`. Works on a bare store, so an
|
|
2169
|
+
* ops script or a CLI can run it without an engine.
|
|
2170
|
+
*
|
|
2171
|
+
* A `running`/`suspended` run qualifies when it has been untouched for `thresholdMs` AND either:
|
|
2172
|
+
*
|
|
2173
|
+
* - it is suspended with NO wake timer (`wakeForever`): nothing will ever re-drive it; or
|
|
2174
|
+
* - its oldest pending REMOTE step is older than the threshold and has no lease in the future
|
|
2175
|
+
* (`stalePending`): the dispatch was most likely lost.
|
|
2176
|
+
*
|
|
2177
|
+
* Healthy long work is excluded: a long `ctx.sleep` has a future `wakeAt` and no pending step, and a
|
|
2178
|
+
* remote step with a `timeoutMs`, a heartbeat or `remoteRedispatchMs` carries a future lease. Issues
|
|
2179
|
+
* one `listCheckpoints` per idle candidate, bounded by `scan`: an operator read, not a hot path.
|
|
2180
|
+
*/
|
|
2181
|
+
declare function findStalledRuns(store: Pick<StateStore, 'listRuns' | 'listCheckpoints'>, options?: FindStalledRunsOptions): Promise<StalledRunInfo[]>;
|
|
2182
|
+
|
|
2183
|
+
/**
|
|
2184
|
+
* Layered tenant auth for the store-less cluster. On a tenant worker the `tenant` on a
|
|
2185
|
+
* {@link import('./interfaces').RunRequest} / {@link import('./interfaces').StartRunMessage} is only
|
|
2186
|
+
* a CLAIM: without a signed proof, any broker client can act as any tenant. This module is the
|
|
2187
|
+
* default defense in depth on top of prefix/network isolation: a symmetric HMAC token the tenant
|
|
2188
|
+
* worker presents IN the existing `tenant` wire field, which the operator's {@link TenantVerifier}
|
|
2189
|
+
* checks and DERIVES the real tenant from, never trusting the body.
|
|
2190
|
+
*
|
|
2191
|
+
* Wire-compatible with Agora (`@adonis-agora/durable`) byte for byte: the token is
|
|
2192
|
+
* `<claim>.<base64url(HMAC-SHA256(secret, claim))>`, where `claim` is the tenant name, optionally
|
|
2193
|
+
* followed by `.exp<epochMs>`. It fits the `tenant: string` field with NO envelope change, so an
|
|
2194
|
+
* operator that does not verify simply treats the whole string as the tenant name (and finds no
|
|
2195
|
+
* runs, a safe failure), while an operator configured with {@link hmacTenantVerifier} verifies the
|
|
2196
|
+
* signature and scopes to the embedded tenant. Agora and Aviary tokens are interchangeable.
|
|
2197
|
+
*
|
|
2198
|
+
* HMAC (shared secret) is the zero-infra default; a deployment that prefers asymmetric or issued
|
|
2199
|
+
* tokens supplies its own {@link TenantVerifier} instead.
|
|
2200
|
+
*/
|
|
2201
|
+
/** The identity a {@link TenantVerifier} derives from a tenant's signed claim. */
|
|
2202
|
+
interface VerifiedTenant {
|
|
2203
|
+
/** The tenant the token authenticates as. The responder trusts THIS, never the request body. */
|
|
2204
|
+
tenant: string;
|
|
2255
2205
|
/**
|
|
2256
|
-
*
|
|
2257
|
-
*
|
|
2258
|
-
*
|
|
2259
|
-
*
|
|
2206
|
+
* Capabilities the token grants, if the issuer scopes them. `tenancy:*` or `tenancy:<id>` lets the
|
|
2207
|
+
* process claim that customer tenant for the runs it starts (see `StartRunMessage.tenantId`). The
|
|
2208
|
+
* run-request responder does not enforce them: a verified tenant can call every verb, scoped to
|
|
2209
|
+
* its own namespace.
|
|
2260
2210
|
*/
|
|
2261
|
-
|
|
2211
|
+
capabilities?: string[] | undefined;
|
|
2212
|
+
}
|
|
2213
|
+
/**
|
|
2214
|
+
* Verifies a tenant's signed claim on the **operator** side, returning the {@link VerifiedTenant} it
|
|
2215
|
+
* authenticates as, or `null` (or throwing) to reject a tampered/invalid/absent token. The signed
|
|
2216
|
+
* token travels in the wire `tenant` field, so the responder passes that value as both `token` and
|
|
2217
|
+
* the advisory `tenant`.
|
|
2218
|
+
*/
|
|
2219
|
+
type TenantVerifier = (input: {
|
|
2220
|
+
/** The signed token presented on the request. */
|
|
2221
|
+
token?: string | undefined;
|
|
2222
|
+
/** The tenant the request *claims* to be. Advisory only: the verifier derives the real one. */
|
|
2223
|
+
tenant?: string | undefined;
|
|
2224
|
+
}) => VerifiedTenant | null | Promise<VerifiedTenant | null>;
|
|
2225
|
+
/**
|
|
2226
|
+
* Where the tenant side gets the token it presents: a static string, or a function called before
|
|
2227
|
+
* every request (so a short-lived token from {@link signTenantToken} with `ttlMs` can be re-minted
|
|
2228
|
+
* or fetched from a secret store without restarting the worker).
|
|
2229
|
+
*/
|
|
2230
|
+
type TenantTokenSource = string | (() => string | Promise<string>);
|
|
2231
|
+
/**
|
|
2232
|
+
* Mint the signed token a tenant worker presents:
|
|
2233
|
+
* `` `${tenant}.${base64url(HMAC-SHA256(secret, tenant))}` ``. The worker carries only the token
|
|
2234
|
+
* (never the secret); the operator verifies it with the SAME `secret` via {@link hmacTenantVerifier}.
|
|
2235
|
+
*/
|
|
2236
|
+
declare function signTenantToken(tenant: string, secret: string, opts?: {
|
|
2262
2237
|
/**
|
|
2263
|
-
*
|
|
2264
|
-
* {@link
|
|
2265
|
-
*
|
|
2266
|
-
*
|
|
2267
|
-
* have the {@link resumeDueTimers} reconcile pass prune rows past `publishedAt + eventBufferTtlMs`
|
|
2268
|
-
* as it encounters them. Scoped to event NAMES the current reconcile tick's registered waiters
|
|
2269
|
-
* reference (the sweep has no reason to otherwise enumerate every buffered name) — a name with a
|
|
2270
|
-
* stale buffered event but zero waiters ever registered against it is not visited by this pass; that
|
|
2271
|
-
* is an accepted gap given `listBufferedEvents` is name-scoped by design (see interfaces.ts), not a
|
|
2272
|
-
* bug to route around here.
|
|
2238
|
+
* Optional lifetime: the claim gains a `.exp<epochMs>` suffix, signed together with the tenant,
|
|
2239
|
+
* and {@link hmacTenantVerifier} rejects the token once that instant passes. Without it the
|
|
2240
|
+
* token never expires. Expiring and non-expiring tokens verify side by side. Tenant names
|
|
2241
|
+
* ending in `.exp<digits>` are reserved by this scheme.
|
|
2273
2242
|
*/
|
|
2274
|
-
|
|
2243
|
+
ttlMs?: number;
|
|
2244
|
+
/** Injectable clock for tests. */
|
|
2245
|
+
now?: number;
|
|
2246
|
+
}): string;
|
|
2247
|
+
/**
|
|
2248
|
+
* Build the operator-side {@link TenantVerifier} for {@link signTenantToken} tokens under `secret`.
|
|
2249
|
+
* It recomputes the HMAC over the embedded claim and compares it in constant time, so a tampered
|
|
2250
|
+
* tenant, a forged/absent signature, a token signed with another secret, or an expired token all
|
|
2251
|
+
* return `null`. The tenant is DERIVED from the token's own claim.
|
|
2252
|
+
*
|
|
2253
|
+
* A LIST of secrets makes rotation a two-step deploy: verify with `[next, current]` everywhere first,
|
|
2254
|
+
* then re-mint tenant tokens with `next` at leisure. `capabilities`, if given, is a static grant
|
|
2255
|
+
* stamped onto every {@link VerifiedTenant} this verifier authenticates (informational: the
|
|
2256
|
+
* responder does not enforce it yet, see {@link VerifiedTenant.capabilities}).
|
|
2257
|
+
*/
|
|
2258
|
+
declare function hmacTenantVerifier(secret: string | string[], capabilities?: string[]): TenantVerifier;
|
|
2259
|
+
/**
|
|
2260
|
+
* Verify a wire message's `tenant`: with a verifier, the {@link VerifiedTenant} it derives (`null` on
|
|
2261
|
+
* reject); without one, the wire value trusted verbatim, with no capabilities.
|
|
2262
|
+
*/
|
|
2263
|
+
declare function verifyWireTenant(wireTenant: string, verifyTenant: TenantVerifier | undefined): Promise<VerifiedTenant | null>;
|
|
2264
|
+
/**
|
|
2265
|
+
* Whether a verified tenant process may claim the customer `tenantId` for a run it starts: its
|
|
2266
|
+
* `capabilities` hold `tenancy:*` (any customer) or `tenancy:<tenantId>`. An unverified process (no
|
|
2267
|
+
* verifier) holds none, so it never may.
|
|
2268
|
+
*/
|
|
2269
|
+
declare function grantsClientTenant(verified: VerifiedTenant | null, tenantId: string): boolean;
|
|
2270
|
+
/**
|
|
2271
|
+
* Resolve the tenant a wire message is ALLOWED to act as. With a verifier, the wire `tenant` is the
|
|
2272
|
+
* signed token: it is verified and the real tenant derived from it (`null` on reject). Without one,
|
|
2273
|
+
* the wire value is trusted verbatim (prefix/network isolation only, today's behaviour).
|
|
2274
|
+
*/
|
|
2275
|
+
declare function resolveWireTenant(wireTenant: string, verifyTenant: TenantVerifier | undefined): Promise<string | null>;
|
|
2276
|
+
/** Resolve a {@link TenantTokenSource} to the token string to put on the wire. */
|
|
2277
|
+
declare function resolveTenantToken(source: TenantTokenSource): Promise<string>;
|
|
2278
|
+
|
|
2279
|
+
type WorkflowFn = (ctx: WorkflowCtx, input: unknown) => Promise<unknown>;
|
|
2280
|
+
/**
|
|
2281
|
+
* Options for {@link WorkflowEngine.start}.
|
|
2282
|
+
*
|
|
2283
|
+
* Note the absence of `origin`: {@link WorkflowRun.origin} says which PACKAGE declared the workflow,
|
|
2284
|
+
* which is a property of the registered code, not of whoever started it. It is taken from the
|
|
2285
|
+
* registration and nothing here can override it — otherwise one caller could label its runs as
|
|
2286
|
+
* another lib's, and an origin filter would quietly lie.
|
|
2287
|
+
*/
|
|
2288
|
+
interface StartOptions {
|
|
2275
2289
|
/**
|
|
2276
|
-
*
|
|
2277
|
-
*
|
|
2278
|
-
*
|
|
2279
|
-
*
|
|
2290
|
+
* Start THIS registered version instead of the newest one. Omit (the default) and the run starts on
|
|
2291
|
+
* the newest registered version, exactly as it always has — this option only ever narrows.
|
|
2292
|
+
*
|
|
2293
|
+
* Resolved against the by-name@version registry, so it pins anything explicitly registered:
|
|
2294
|
+
* {@link WorkflowEngine.register}, {@link WorkflowEngine.registerRemote}, {@link WorkflowEngine.remote}.
|
|
2295
|
+
* A version that is NOT registered throws before a run row is created and NEVER falls back to
|
|
2296
|
+
* `latest` — a silent fallback is the exact failure this option exists to prevent (a caller that
|
|
2297
|
+
* asked for `name@3` and got `name@4` has no way to tell, and its run is already going).
|
|
2298
|
+
*
|
|
2299
|
+
* NOT available on a child inheriting its remote ancestor's routing (see `findInheritedRegistration`),
|
|
2300
|
+
* which INVENTS the version it stamps (the ancestor's). Convention routing to a live worker group of
|
|
2301
|
+
* the same name (`resolveRemoteByConvention`) honours a pin only when the live workers on that group
|
|
2302
|
+
* themselves DECLARE the pinned version (their announced registrations); a fleet that declares
|
|
2303
|
+
* another version, or none, is no evidence, and the pinned start throws rather than pretending. To
|
|
2304
|
+
* pin a cross-SDK workflow whose workers declare nothing, register it for real —
|
|
2305
|
+
* `engine.remote('name', { version: '2', group })` — which puts `name@2` in the registry.
|
|
2306
|
+
*
|
|
2307
|
+
* A tenant's start ({@link StartRunMessage.version}) does not throw: with no live worker declaring
|
|
2308
|
+
* the version yet, the run waits `blocked` (`no_live_worker`) until one does.
|
|
2280
2309
|
*/
|
|
2281
|
-
|
|
2310
|
+
version?: string | undefined;
|
|
2311
|
+
/** Run-scoped tags, merged with the workflow's static `@Workflow({ tags })` onto the run. */
|
|
2312
|
+
tags?: string[] | undefined;
|
|
2313
|
+
/** Typed, queryable run data stamped on the run (e.g. `{ amount: 200, tier: 'pro' }`). */
|
|
2314
|
+
searchAttributes?: SearchAttributes | undefined;
|
|
2282
2315
|
/**
|
|
2283
|
-
*
|
|
2284
|
-
* the
|
|
2285
|
-
* flush/eviction, or BullMQ moving a stalled job to `failed` and removing it). The `pending`
|
|
2286
|
-
* checkpoint then has no result to resume on, and — BY DESIGN (see {@link reconcileMs}) — the
|
|
2287
|
-
* reconcile re-drive re-suspends a still-pending step rather than re-dispatching, so a slow-but-live
|
|
2288
|
-
* worker is never double-run. That safety means a genuinely-lost dispatch would otherwise hang
|
|
2289
|
-
* forever. When set, a reconcile re-drive that finds a remote step still `pending` PAST this window
|
|
2290
|
-
* re-dispatches it (bumping `attempts`, bounded by {@link remoteRedispatchMax}). Off by default:
|
|
2291
|
-
* re-dispatch can double-run a step whose original job is merely slow, so the window MUST exceed the
|
|
2292
|
-
* longest such step and the step MUST be idempotent. Prefer a per-step `timeoutMs` (tighter,
|
|
2293
|
-
* heartbeat-aware) where you can; this is the store-driven net for no-timeout steps that must
|
|
2294
|
-
* survive a lost dispatch. {@link WorkflowEngine.redispatchPending} is the manual counterpart.
|
|
2316
|
+
* Dispatch priority for a remote run — stamped on the run and carried onto every {@link WorkflowTask}
|
|
2317
|
+
* the engine dispatches to advance it. Higher wins; absent = unprioritised. See {@link WorkflowRun.priority}.
|
|
2295
2318
|
*/
|
|
2296
|
-
|
|
2319
|
+
priority?: number | undefined;
|
|
2297
2320
|
/**
|
|
2298
|
-
*
|
|
2299
|
-
*
|
|
2300
|
-
*
|
|
2321
|
+
* Override the namespace stamped on the run. Defaults to the engine's own `namespace`. Set by the
|
|
2322
|
+
* control plane when it starts a run on behalf of a tenant (a {@link StartRunMessage}'s `tenant`
|
|
2323
|
+
* maps here), so one DB-less-tenant-facing engine can create runs across many namespaces.
|
|
2301
2324
|
*/
|
|
2302
|
-
|
|
2325
|
+
namespace?: string | undefined;
|
|
2303
2326
|
/**
|
|
2304
|
-
*
|
|
2305
|
-
*
|
|
2306
|
-
*
|
|
2307
|
-
* re-parks with a fresh `wakeAt` each poll. Only relevant once a step/workflow declares `requires`
|
|
2308
|
-
* AND descriptors are published (a legacy fleet never parks blocked).
|
|
2327
|
+
* A start-time concurrency quota for this start — at most `limit` runs sharing `key` in flight;
|
|
2328
|
+
* over it, `start` throws {@link ConcurrencyLimitError} and creates nothing. Overrides the
|
|
2329
|
+
* workflow's registered `concurrency`. See {@link ConcurrencyQuota}.
|
|
2309
2330
|
*/
|
|
2310
|
-
|
|
2331
|
+
concurrency?: ConcurrencyQuota | undefined;
|
|
2311
2332
|
/**
|
|
2312
|
-
*
|
|
2313
|
-
*
|
|
2314
|
-
*
|
|
2315
|
-
*
|
|
2316
|
-
*
|
|
2333
|
+
* Delayed start: don't execute before this time (epoch ms, or a `Date`), compared against the
|
|
2334
|
+
* engine's clock. The run is created `suspended` with its `wakeAt` set to it, which is the same
|
|
2335
|
+
* durable timer a `ctx.sleep` parks on: nothing is held in memory, it survives restarts, and the
|
|
2336
|
+
* timer poller (`resumeDueTimers`) starts it once due, on any instance. A time that is not in the
|
|
2337
|
+
* future starts the run at once, as if it were omitted.
|
|
2338
|
+
*
|
|
2339
|
+
* A delayed run reads `suspended` until it fires (so `start` returns `suspended`, and `waitForRun`
|
|
2340
|
+
* settles on that right away), and skips the `run.started` event's `pending → running` hop. It
|
|
2341
|
+
* counts as in flight for singleton back-pressure and concurrency quotas while it waits.
|
|
2317
2342
|
*/
|
|
2318
|
-
|
|
2343
|
+
startAt?: number | Date | undefined;
|
|
2319
2344
|
/**
|
|
2320
|
-
*
|
|
2321
|
-
*
|
|
2322
|
-
*
|
|
2345
|
+
* The customer this run belongs to (see {@link WorkflowRun.tenantId}). An explicit value always
|
|
2346
|
+
* wins; `null` starts it with no tenant. Omit it and the run takes the context tenant when tenancy
|
|
2347
|
+
* is on, else none.
|
|
2323
2348
|
*/
|
|
2324
|
-
|
|
2349
|
+
tenantId?: string | null | undefined;
|
|
2350
|
+
/** The kind of {@link tenantId} (`organization`, `user`, …). Only read with an explicit `tenantId`. */
|
|
2351
|
+
tenantKind?: string | undefined;
|
|
2352
|
+
}
|
|
2353
|
+
/**
|
|
2354
|
+
* Serialize runs of a workflow that share a key — a durable, FIFO mutex (e.g. one pipeline per base).
|
|
2355
|
+
* Excess runs are admitted in creation order, `limit` at a time; the rest wait (suspended) and retry
|
|
2356
|
+
* admission on a timer until a slot frees. The store atomically reserves durable slots before
|
|
2357
|
+
* ordering unadmitted waiters by `(createdAt, id)`, so later starts cannot displace a holder.
|
|
2358
|
+
*/
|
|
2359
|
+
interface SingletonConfig {
|
|
2360
|
+
/** Derive the serialization key from the workflow input. */
|
|
2361
|
+
key: (input: unknown) => string;
|
|
2362
|
+
/** Max concurrent runs sharing the key. Default 1 (a mutex). */
|
|
2363
|
+
limit?: number;
|
|
2325
2364
|
/**
|
|
2326
|
-
*
|
|
2327
|
-
*
|
|
2328
|
-
* `
|
|
2365
|
+
* Max GATED (waiting-for-admission) runs allowed to queue behind the `limit` in-flight ones. When
|
|
2366
|
+
* set, `start` rejects with {@link SingletonQueueFullError} once in-flight + gated reaches
|
|
2367
|
+
* `limit + maxQueueDepth` — back-pressure against an unbounded same-key backlog. Omit for the
|
|
2368
|
+
* default unbounded queue. Counts pending/running/suspended/blocked/cancelling runs sharing the key.
|
|
2329
2369
|
*/
|
|
2330
|
-
|
|
2370
|
+
maxQueueDepth?: number;
|
|
2371
|
+
}
|
|
2372
|
+
/**
|
|
2373
|
+
* Stamped on a run whose workflow version NOBODY declared: a remote resolved by convention, served
|
|
2374
|
+
* by a worker that announces no version for it (an SDK too old to publish a descriptor, or a body
|
|
2375
|
+
* whose author simply never stated one).
|
|
2376
|
+
*
|
|
2377
|
+
* ## Why a run has to carry this
|
|
2378
|
+
*
|
|
2379
|
+
* Such a run's `workflowVersion` is `'1'`, the engine's convention default. That value is a routing
|
|
2380
|
+
* placeholder, not an observation — and read back later it is indistinguishable from a worker that
|
|
2381
|
+
* genuinely declared version `'1'`. Any check comparing an authored pin against it therefore passes
|
|
2382
|
+
* whenever the pin is `'1'` and fails whenever it is not, regardless of what the callee actually is.
|
|
2383
|
+
* A check that cannot fail is worse than no check, because it reads as a guarantee.
|
|
2384
|
+
*
|
|
2385
|
+
* The tag is the difference, carried ON the run so a retrospective check needs no second read: a
|
|
2386
|
+
* caller that pinned a version can see that the version it is comparing against was never stated,
|
|
2387
|
+
* and say so, instead of reporting a match it did not really make. It is deliberately a tag rather
|
|
2388
|
+
* than a new column — every store already persists and queries tags, so this needs no migration and
|
|
2389
|
+
* shows up in run listings and dashboards for free. Follows the `singleton:<key>` precedent for an
|
|
2390
|
+
* engine-stamped reserved tag.
|
|
2391
|
+
*
|
|
2392
|
+
* A run whose callee DOES declare a version never carries it; that run's version is the declared one
|
|
2393
|
+
* and a pin against it is genuinely checked.
|
|
2394
|
+
*/
|
|
2395
|
+
declare const VERSION_UNDECLARED_TAG = "version:undeclared";
|
|
2396
|
+
/**
|
|
2397
|
+
* The `error.code` of a run a tenant started while no live worker served it yet (see
|
|
2398
|
+
* `WorkflowEngine.startForTenant`). The run is parked `blocked` and the blocked-recovery poll starts
|
|
2399
|
+
* it as soon as a worker on its group (declaring its pinned version, when it has one) is live. It is
|
|
2400
|
+
* never dead-lettered for waiting: a start is a request queued for its consumer, however late that
|
|
2401
|
+
* consumer boots. Cancel it to drop it.
|
|
2402
|
+
*/
|
|
2403
|
+
declare const NO_LIVE_WORKER = "no_live_worker";
|
|
2404
|
+
/**
|
|
2405
|
+
* How long an adopted tenant schedule may go unannounced by every live worker of its app before the
|
|
2406
|
+
* control plane pauses it (see `WorkflowEngine.syncAnnouncedSchedules`). Long enough to ride out a
|
|
2407
|
+
* rolling deploy; a schedule is never deleted for missing.
|
|
2408
|
+
*/
|
|
2409
|
+
declare const DEFAULT_ANNOUNCED_SCHEDULE_GRACE_MS: number;
|
|
2410
|
+
interface WorkflowEngineDeps {
|
|
2411
|
+
store: StateStore;
|
|
2412
|
+
/** A single task transport. Shorthand for a one-entry `transports` pool (id `default`). */
|
|
2413
|
+
transport?: Transport | undefined;
|
|
2331
2414
|
/**
|
|
2332
|
-
*
|
|
2333
|
-
*
|
|
2334
|
-
*
|
|
2335
|
-
* supply this from `@dudousxd/nestjs-context` or your own request-scoped reader. The engine never
|
|
2336
|
-
* inspects the returned object's shape. Omit to send none.
|
|
2337
|
-
*
|
|
2338
|
-
* Re-evaluated at each (re)dispatch — including a retry or a resume that the engine drives AFTER a
|
|
2339
|
-
* crash/scale-down, which runs OUTSIDE the originating request scope. On such a path this provider
|
|
2340
|
-
* may return empty or stale values (the request-scoped tenant/user is gone). Treat the carrier as
|
|
2341
|
-
* best-effort correlation/propagation metadata only — do NOT treat it as an authorization boundary.
|
|
2415
|
+
* An ordered pool of named transports. The engine dispatches on the first and fails over to the
|
|
2416
|
+
* next on a dispatch error; a step pins one via `ctx.step(step, input, { transport: id })`. Use
|
|
2417
|
+
* this instead of `transport` for failover / multi-broker setups.
|
|
2342
2418
|
*/
|
|
2343
|
-
|
|
2419
|
+
transports?: NamedTransport[] | undefined;
|
|
2344
2420
|
/**
|
|
2345
|
-
*
|
|
2346
|
-
*
|
|
2347
|
-
*
|
|
2348
|
-
* Given the carrier produced by {@link context} (may be empty/undefined) and the step body `fn`, it
|
|
2349
|
-
* runs `fn` with that context ambiently established (e.g. inside `@dudousxd/nestjs-context`'s ALS)
|
|
2350
|
-
* and returns its result. Keep core dependency-free: supply this from the nestjs wiring (which owns
|
|
2351
|
-
* nestjs-context) or your own ALS bridge. The handler signature is unchanged — re-hydration is
|
|
2352
|
-
* ambient. Default: passthrough (`(_, fn) => fn()`), so behavior is byte-identical when unset.
|
|
2421
|
+
* Cross-instance broadcast pub/sub for lifecycle events + cancellation (see {@link ControlPlane}).
|
|
2422
|
+
* Separate from the task `transport`; omit for a single-instance / local-only setup. A transport
|
|
2423
|
+
* that can also broadcast may be passed here as well.
|
|
2353
2424
|
*/
|
|
2354
|
-
|
|
2425
|
+
controlPlane?: ControlPlane | undefined;
|
|
2426
|
+
/** Epoch-ms clock; injectable for tests. Defaults to `Date.now`. */
|
|
2427
|
+
clock?: (() => number) | undefined;
|
|
2355
2428
|
/**
|
|
2356
|
-
*
|
|
2357
|
-
*
|
|
2358
|
-
*
|
|
2359
|
-
* runs carry only an explicit `StartOptions.tenantId` and no read is filtered.
|
|
2429
|
+
* Flow-control admission backend for `ctx.step(step, input, { queue })`. Defaults to an in-process
|
|
2430
|
+
* {@link InMemoryAdmissionBackend} (per-instance caps). Inject a store/Redis-backed backend to make
|
|
2431
|
+
* concurrency / rate-limit / ordering GLOBAL across engine replicas.
|
|
2360
2432
|
*/
|
|
2361
|
-
|
|
2433
|
+
admission?: AdmissionBackend | undefined;
|
|
2434
|
+
/** Unique id for this engine instance, used for recovery leases. Defaults to a random id. */
|
|
2435
|
+
instanceId?: string | undefined;
|
|
2362
2436
|
/**
|
|
2363
|
-
*
|
|
2364
|
-
*
|
|
2437
|
+
* Worker-pool partition for this engine. Stamped on every run it creates; the poll paths
|
|
2438
|
+
* (`runPending`/`recoverIncomplete`/`resumeDueTimers`/`sweepTimeouts`) only act on runs in this
|
|
2439
|
+
* namespace. Set distinct values to safely share ONE state store across non-interchangeable pools
|
|
2440
|
+
* (e.g. local dev vs a cluster). **Omit it to make this engine an OPERATOR** — an unset namespace
|
|
2441
|
+
* drives/recovers/resumes runs of EVERY namespace (the poll filters no-op, the resume/decision
|
|
2442
|
+
* guards fall through) and leaves the transport on its bare prefix. This is the hosted control
|
|
2443
|
+
* plane: "ver tudo = ausência de namespace".
|
|
2365
2444
|
*/
|
|
2366
|
-
|
|
2445
|
+
namespace?: string | undefined;
|
|
2446
|
+
/**
|
|
2447
|
+
* Verifies the signed tenant token a store-less tenant worker presents in the `tenant` field of a
|
|
2448
|
+
* {@link StartRunMessage}, and DERIVES the run's namespace from it (see `hmacTenantVerifier`).
|
|
2449
|
+
* A message whose token is rejected (or whose verifier throws) is dropped without creating a run.
|
|
2450
|
+
* Absent: the wire `tenant` is trusted verbatim, as before.
|
|
2451
|
+
*/
|
|
2452
|
+
verifyTenant?: TenantVerifier | undefined;
|
|
2453
|
+
/** Recovery lease duration in ms — how long this instance owns a run it picked up. Default 30s. */
|
|
2454
|
+
leaseMs?: number | undefined;
|
|
2455
|
+
/**
|
|
2456
|
+
* Cap how many times crash-recovery may pick up the same still-`running` run before giving up and
|
|
2457
|
+
* moving it to the `dead` dead-letter state (a poison pill that crashes the process every boot).
|
|
2458
|
+
* Omit for unlimited (the default — recovery always retries).
|
|
2459
|
+
*/
|
|
2460
|
+
maxRecoveryAttempts?: number | undefined;
|
|
2461
|
+
/**
|
|
2462
|
+
* How long (ms) a run may stay due while NO instance can resume it because its workflow version is
|
|
2463
|
+
* not registered anywhere, before it is moved to `dead` (code `workflow_not_registered`). A rolling
|
|
2464
|
+
* deploy skips such a run on purpose (skew protection): the pod still on the prior version picks it
|
|
2465
|
+
* up within seconds. A run that stays unresumable far past that — its workflow was renamed or
|
|
2466
|
+
* deleted — would otherwise be retried and logged on every tick forever. The clock starts when the
|
|
2467
|
+
* run became due (its `wakeAt` for a parked run, its last update otherwise), so a long sleep is not
|
|
2468
|
+
* counted. Default 24h; `0` disables (skip forever). A non-finite or negative value falls back to
|
|
2469
|
+
* the default.
|
|
2470
|
+
*/
|
|
2471
|
+
unregisteredWorkflowGraceMs?: number | undefined;
|
|
2472
|
+
/**
|
|
2473
|
+
* Opt-in liveness deadline (ms) for a remote workflow `advance`. If the worker neither returns a
|
|
2474
|
+
* decision NOR sends a run-scoped {@link Heartbeat} within this window, the engine presumes it dead:
|
|
2475
|
+
* it rejects the advance with {@link RemoteWorkflowTimeout}, releases the lease, and lets recovery
|
|
2476
|
+
* re-drive (replaying completed steps from history). Each beat REARMS the window, so a worker still
|
|
2477
|
+
* legitimately replaying a long turn (it keeps beating) is never re-driven — closing the duplicate-
|
|
2478
|
+
* side-effect hazard a fixed {@link RemoteWorkflowExecutor} `timeoutMs` cannot avoid. Omit (default)
|
|
2479
|
+
* for the prior unbounded await — byte-identical behavior when unset. If a `RemoteWorkflowExecutor` is
|
|
2480
|
+
* ALSO constructed with its own `timeoutMs`, the shorter of the two deadlines wins; prefer setting only
|
|
2481
|
+
* one (this rearmed window for heartbeat-aware workers, or the fixed `timeoutMs` otherwise).
|
|
2482
|
+
*
|
|
2483
|
+
* A turn DISPATCHED over a broker (a tenant's or another SDK's worker) is never left without a
|
|
2484
|
+
* deadline: unset, its window is {@link reconcileMs} (5 min by default), so a run whose worker died
|
|
2485
|
+
* holding the turn is re-driven instead of waiting forever. `reconcileMs: 0` with this unset keeps
|
|
2486
|
+
* the old unbounded wait.
|
|
2487
|
+
*/
|
|
2488
|
+
remoteAdvanceSilenceMs?: number | undefined;
|
|
2489
|
+
/**
|
|
2490
|
+
* Fallback re-drive window (ms) for a run that SUSPENDS with no natural timer — i.e. it's waiting on
|
|
2491
|
+
* an EVENT to wake it (a child's completion, a signal, a remote step with no `timeoutMs`) rather than
|
|
2492
|
+
* a `ctx.sleep`. Those events re-drive the run directly; but if the wake is LOST (the delivering pod
|
|
2493
|
+
* crashed / rolled mid-handoff), the run would otherwise sit `suspended` forever with `wakeAt: null` —
|
|
2494
|
+
* invisible to both the timer poller (no `wakeAt`) and crash-recovery (no lease). This stamps a
|
|
2495
|
+
* fallback `wakeAt` so {@link resumeDueTimers} re-drives it after the window; the re-drive is an
|
|
2496
|
+
* idempotent replay (a still-pending dependency re-suspends via the checkpoint guard, a settled one
|
|
2497
|
+
* advances), so it's a safe self-heal, not a retry that can double-dispatch. The primary event path
|
|
2498
|
+
* still wins first for a healthy run (it re-drives long before this fires), so this only ever fires
|
|
2499
|
+
* for a genuinely-orphaned run. Default 5min; set `0` to disable (the prior wake-forever behavior).
|
|
2500
|
+
*
|
|
2501
|
+
* Also the default re-drive window of a workflow turn dispatched to a remote worker when
|
|
2502
|
+
* {@link remoteAdvanceSilenceMs} is unset (see there).
|
|
2503
|
+
*/
|
|
2504
|
+
reconcileMs?: number | undefined;
|
|
2505
|
+
/**
|
|
2506
|
+
* How long an in-flight run must sit untouched, with the stranded signature (a wake-forever
|
|
2507
|
+
* suspension, or an old pending remote step with no live lease), before the
|
|
2508
|
+
* {@link WorkflowEngine.onStalled} listeners are notified. Default 900 000 (15 min); floored at
|
|
2509
|
+
* 60 000. The sweep ({@link WorkflowEngine.sweepStalled}) only does work when a listener is
|
|
2510
|
+
* registered.
|
|
2511
|
+
*/
|
|
2512
|
+
stalledAfterMs?: number | undefined;
|
|
2513
|
+
/**
|
|
2514
|
+
* The most due timers one {@link WorkflowEngine.resumeDueTimers} pass loads and drives, most
|
|
2515
|
+
* overdue first. Every driving instance runs that pass each tick, so a wave of thousands of due
|
|
2516
|
+
* runs (a recovery after an outage, a fan's children waking together) is worked through in
|
|
2517
|
+
* batches instead of every instance loading and walking all of it. Default 500.
|
|
2518
|
+
*/
|
|
2519
|
+
timerBatchSize?: number | undefined;
|
|
2520
|
+
/**
|
|
2521
|
+
* Retention for a BUFFERED event that no `waitForEvent` ever claims (see
|
|
2522
|
+
* {@link WorkflowEngine.publishEvent}'s buffering — a publish matching no live waiter keeps ONE
|
|
2523
|
+
* copy around for a later matching wait). Default `undefined`: keep it until consumed, same as
|
|
2524
|
+
* {@link StateStore.bufferSignal}'s buffered signals — no silent expiry. Set a duration (ms) to
|
|
2525
|
+
* have the {@link resumeDueTimers} reconcile pass prune rows past `publishedAt + eventBufferTtlMs`
|
|
2526
|
+
* as it encounters them. Scoped to event NAMES the current reconcile tick's registered waiters
|
|
2527
|
+
* reference (the sweep has no reason to otherwise enumerate every buffered name) — a name with a
|
|
2528
|
+
* stale buffered event but zero waiters ever registered against it is not visited by this pass; that
|
|
2529
|
+
* is an accepted gap given `listBufferedEvents` is name-scoped by design (see interfaces.ts), not a
|
|
2530
|
+
* bug to route around here.
|
|
2531
|
+
*/
|
|
2532
|
+
eventBufferTtlMs?: number | undefined;
|
|
2533
|
+
/**
|
|
2534
|
+
* How long `signal(token, payload, { id })` remembers an `id` (ms, or a duration like `'7d'`): a
|
|
2535
|
+
* re-send with the same token and id within it is dropped. Records past it are ignored, and
|
|
2536
|
+
* {@link WorkflowEngine.sweepExpiredSignalIds} deletes them. Keep it longer than any sender's
|
|
2537
|
+
* redelivery window. Default 7 days; a call can pass its own `idTtl`.
|
|
2538
|
+
*/
|
|
2539
|
+
signalIdTtl?: string | number | undefined;
|
|
2540
|
+
/**
|
|
2541
|
+
* Opt-in self-heal window (ms) for a remote step with NO `timeoutMs` whose dispatched job was LOST —
|
|
2542
|
+
* the worker crashed mid-step leaving no result, or the transport dropped the job (a Redis
|
|
2543
|
+
* flush/eviction, or BullMQ moving a stalled job to `failed` and removing it). The `pending`
|
|
2544
|
+
* checkpoint then has no result to resume on, and — BY DESIGN (see {@link reconcileMs}) — the
|
|
2545
|
+
* reconcile re-drive re-suspends a still-pending step rather than re-dispatching, so a slow-but-live
|
|
2546
|
+
* worker is never double-run. That safety means a genuinely-lost dispatch would otherwise hang
|
|
2547
|
+
* forever. When set, a reconcile re-drive that finds a remote step still `pending` PAST this window
|
|
2548
|
+
* re-dispatches it (bumping `attempts`, bounded by {@link remoteRedispatchMax}). Off by default:
|
|
2549
|
+
* re-dispatch can double-run a step whose original job is merely slow, so the window MUST exceed the
|
|
2550
|
+
* longest such step and the step MUST be idempotent. Prefer a per-step `timeoutMs` (tighter,
|
|
2551
|
+
* heartbeat-aware) where you can; this is the store-driven net for no-timeout steps that must
|
|
2552
|
+
* survive a lost dispatch. {@link WorkflowEngine.redispatchPending} is the manual counterpart.
|
|
2553
|
+
*/
|
|
2554
|
+
remoteRedispatchMs?: number | undefined;
|
|
2555
|
+
/**
|
|
2556
|
+
* Max times {@link remoteRedispatchMs} re-dispatches one lost remote step before giving up and
|
|
2557
|
+
* failing it as a {@link RemoteStepError} (`code: 'remote_step_lost'`), so the run fails / dead-letters
|
|
2558
|
+
* instead of re-dispatching forever. Default 10. Ignored when `remoteRedispatchMs` is unset.
|
|
2559
|
+
*/
|
|
2560
|
+
remoteRedispatchMax?: number | undefined;
|
|
2561
|
+
/**
|
|
2562
|
+
* How long (ms) a run parked `blocked` (no capability-capable + protocol-compatible live worker,
|
|
2563
|
+
* handshake design §7.5) waits before the blocked-recovery poll re-drives it to re-check the live
|
|
2564
|
+
* fleet. Default 5000. The run proceeds the moment a capable+compatible worker appears; until then it
|
|
2565
|
+
* re-parks with a fresh `wakeAt` each poll. Only relevant once a step/workflow declares `requires`
|
|
2566
|
+
* AND descriptors are published (a legacy fleet never parks blocked).
|
|
2567
|
+
*/
|
|
2568
|
+
blockedPollMs?: number | undefined;
|
|
2569
|
+
/**
|
|
2570
|
+
* How long (ms) the routing guard reuses the worker descriptors it read for a queue token before
|
|
2571
|
+
* reading them again. Every dispatch consults them, and on BullMQ each read is a `SCAN` of the
|
|
2572
|
+
* Redis keyspace; workers rewrite their descriptor every 10 s with a 35 s TTL, so a couple of
|
|
2573
|
+
* seconds of reuse changes nothing the guard can observe. Concurrent reads of one token share a
|
|
2574
|
+
* single request. Default 2000; `0` reads on every dispatch.
|
|
2575
|
+
*/
|
|
2576
|
+
workerDescriptorCacheMs?: number | undefined;
|
|
2577
|
+
/**
|
|
2578
|
+
* Build the public callback URL for a `ctx.webhook()` token (e.g.
|
|
2579
|
+
* ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
|
|
2580
|
+
* {@link DurableWebhook.url}. Omit if you build URLs yourself from the token.
|
|
2581
|
+
*/
|
|
2582
|
+
webhookUrl?: ((token: string) => string) | undefined;
|
|
2583
|
+
/**
|
|
2584
|
+
* Provide the current W3C `traceparent` to stamp on each dispatched {@link RemoteTask}, so a
|
|
2585
|
+
* worker (including the Python SDK) continues the distributed trace. Keep core OTel-free: supply
|
|
2586
|
+
* `otelTraceparent` from `@dudousxd/nestjs-durable-otel`, or your own context reader. Omit to send none.
|
|
2587
|
+
*/
|
|
2588
|
+
traceparent?: (() => string | undefined) | undefined;
|
|
2589
|
+
/**
|
|
2590
|
+
* Provide an opaque context carrier (tenant / user / correlation ids) to attach to each dispatched
|
|
2591
|
+
* {@link RemoteTask} as its `context`, so a worker (including the Python SDK) re-exposes it to the
|
|
2592
|
+
* step handler — cross-process propagation alongside the {@link traceparent}. Keep core dependency-free:
|
|
2593
|
+
* supply this from `@dudousxd/nestjs-context` or your own request-scoped reader. The engine never
|
|
2594
|
+
* inspects the returned object's shape. Omit to send none.
|
|
2595
|
+
*
|
|
2596
|
+
* Re-evaluated at each (re)dispatch — including a retry or a resume that the engine drives AFTER a
|
|
2597
|
+
* crash/scale-down, which runs OUTSIDE the originating request scope. On such a path this provider
|
|
2598
|
+
* may return empty or stale values (the request-scoped tenant/user is gone). Treat the carrier as
|
|
2599
|
+
* best-effort correlation/propagation metadata only — do NOT treat it as an authorization boundary.
|
|
2600
|
+
*/
|
|
2601
|
+
context?: (() => Record<string, unknown> | undefined) | undefined;
|
|
2602
|
+
/**
|
|
2603
|
+
* Re-hydrate the originating context around a LOCAL step body, so a `@Step` reader sees the
|
|
2604
|
+
* tenant / user / correlation ids that were live when the run was started — even on a path the
|
|
2605
|
+
* engine drives outside the originating request scope (a resume after crash/scale-down, a timer).
|
|
2606
|
+
* Given the carrier produced by {@link context} (may be empty/undefined) and the step body `fn`, it
|
|
2607
|
+
* runs `fn` with that context ambiently established (e.g. inside `@dudousxd/nestjs-context`'s ALS)
|
|
2608
|
+
* and returns its result. Keep core dependency-free: supply this from the nestjs wiring (which owns
|
|
2609
|
+
* nestjs-context) or your own ALS bridge. The handler signature is unchanged — re-hydration is
|
|
2610
|
+
* ambient. Default: passthrough (`(_, fn) => fn()`), so behavior is byte-identical when unset.
|
|
2611
|
+
*/
|
|
2612
|
+
rehydrate?: (<T>(carrier: Record<string, unknown> | undefined, fn: () => T) => T) | undefined;
|
|
2613
|
+
/**
|
|
2614
|
+
* Tenancy (the customer a run belongs to): how to read the context tenant at `start`, the matching
|
|
2615
|
+
* filter for app-facing reads and control calls, and how to restore a run's tenant around each of
|
|
2616
|
+
* its turns. Supplied by the NestJS module from `@dudousxd/nestjs-context`. Unset = tenancy off:
|
|
2617
|
+
* runs carry only an explicit `StartOptions.tenantId` and no read is filtered.
|
|
2618
|
+
*/
|
|
2619
|
+
tenancy?: EngineTenancy | undefined;
|
|
2620
|
+
/**
|
|
2621
|
+
* Attempts for each saga compensation when the run fails (a transient undo — e.g. a refund API
|
|
2622
|
+
* hiccup — gets another try). Default 1 (no retry). Compensations must be idempotent.
|
|
2623
|
+
*/
|
|
2624
|
+
compensationRetries?: number | undefined;
|
|
2367
2625
|
/**
|
|
2368
2626
|
* Persist a `running` checkpoint when a local step's body begins, so an in-flight step shows up
|
|
2369
2627
|
* in the dashboard (and a fresh page load / REST query) the moment it starts — not only once it
|
|
@@ -2977,6 +3235,20 @@ declare class WorkflowEngine {
|
|
|
2977
3235
|
*/
|
|
2978
3236
|
listStalledRuns(options?: ListStalledRunsOptions): Promise<StalledRunInfo[]>;
|
|
2979
3237
|
private notifyDead;
|
|
3238
|
+
/**
|
|
3239
|
+
* The dead-letter workflow the live workers serving `run`'s workflow announce (a tenant's inline
|
|
3240
|
+
* `@DeadLetter()` handler, its `deadLetterWorkflow`, or its module-level default), or `undefined`
|
|
3241
|
+
* when the workflow is registered on this engine (its own routing applies), they announce none, or
|
|
3242
|
+
* they cannot be read. A dead-letter listener with a catch-all default (`DurableModule`'s
|
|
3243
|
+
* `deadLetterWorkflow`) checks it first, so the app's own route wins over the default.
|
|
3244
|
+
*/
|
|
3245
|
+
announcedDeadLetter(run: WorkflowRun): Promise<string | undefined>;
|
|
3246
|
+
/**
|
|
3247
|
+
* Start the announced dead-letter workflow of a dead run (see {@link announcedDeadLetter}) in the
|
|
3248
|
+
* run's namespace, as `dlq:<runId>` with the `DeadLetter` payload, through the tenant start path:
|
|
3249
|
+
* with no live worker of the app it waits `blocked` instead of being lost. Idempotent by run id.
|
|
3250
|
+
*/
|
|
3251
|
+
private routeAnnouncedDeadLetter;
|
|
2980
3252
|
/**
|
|
2981
3253
|
* Emit a locally-produced lifecycle event: deliver to subscribers AND broadcast it on the control
|
|
2982
3254
|
* plane so other instances (e.g. a dashboard pod) can live-tail this run. A `run.completed` or
|
|
@@ -3337,6 +3609,32 @@ declare class WorkflowEngine {
|
|
|
3337
3609
|
* redelivery is a no-op once the run exists (idempotent by run id).
|
|
3338
3610
|
*/
|
|
3339
3611
|
startForTenant(message: StartRunMessage, namespace: string, tenant: Pick<StartOptions, 'tenantId' | 'tenantKind'>): Promise<RunResult>;
|
|
3612
|
+
/**
|
|
3613
|
+
* The control plane's half of a tenant's `signalWithStart` (a `signalWithStart` run request):
|
|
3614
|
+
* start `start` like {@link startForTenant} unless its run exists, then signal `signal.token`.
|
|
3615
|
+
* Authorization is the caller's (the run-request responder): the run must belong to `namespace`,
|
|
3616
|
+
* and so must a run already waiting on the token. Delivered at once to a waiting run; with none
|
|
3617
|
+
* waiting yet it is buffered only when the token contains the run id (a run-scoped token), so a
|
|
3618
|
+
* tenant can never plant a payload for a wait another namespace opens later. `signalled: false`
|
|
3619
|
+
* when it was neither delivered nor buffered.
|
|
3620
|
+
*/
|
|
3621
|
+
signalWithStartForTenant(start: StartRunMessage & {
|
|
3622
|
+
runId: string;
|
|
3623
|
+
}, namespace: string, tenant: Pick<StartOptions, 'tenantId' | 'tenantKind'>, signal: {
|
|
3624
|
+
token: string;
|
|
3625
|
+
payload?: unknown;
|
|
3626
|
+
}): Promise<{
|
|
3627
|
+
runId: string;
|
|
3628
|
+
signalled: boolean;
|
|
3629
|
+
}>;
|
|
3630
|
+
/**
|
|
3631
|
+
* The control plane's half of a tenant's `publishEvent` (a `publishEvent` run request): resume the
|
|
3632
|
+
* runs of `namespace` waiting on event `name` whose match the payload satisfies. Starting the
|
|
3633
|
+
* tenant's own subscribers is the tenant's (it holds their `where` and `input`); nothing is
|
|
3634
|
+
* buffered, since a buffered event could reach another namespace's later wait. Returns how many
|
|
3635
|
+
* runs it resumed.
|
|
3636
|
+
*/
|
|
3637
|
+
publishEventForTenant(name: string, payload: unknown, namespace: string): Promise<number>;
|
|
3340
3638
|
/** A tenant start {@link startForTenant} could not admit, kept as a `failed` run with the reason. */
|
|
3341
3639
|
private recordRejectedStart;
|
|
3342
3640
|
/**
|
|
@@ -3505,6 +3803,15 @@ declare class WorkflowEngine {
|
|
|
3505
3803
|
* liveness changes between calls, exactly as {@link synthesizeRemoteChild} does.
|
|
3506
3804
|
*/
|
|
3507
3805
|
private resolveRemoteByConvention;
|
|
3806
|
+
/**
|
|
3807
|
+
* The registration the live workers of `group` announce for `workflow` (at `version`, when one of
|
|
3808
|
+
* them states it): where they disagree (a rolling deploy), the one from the worker that started
|
|
3809
|
+
* last, as for announced schedules. `undefined` when none announces it, `null` when the read
|
|
3810
|
+
* failed (what the workers state is then unknown, not "nothing"). Reads
|
|
3811
|
+
* through the descriptor cache ({@link workerDescriptorCacheMs}), so a turn costs no extra round
|
|
3812
|
+
* trip in steady state.
|
|
3813
|
+
*/
|
|
3814
|
+
private announcedRegistration;
|
|
3508
3815
|
/**
|
|
3509
3816
|
* The version the LIVE fleet declares for `workflow` on `group`, or `undefined` when it declares
|
|
3510
3817
|
* none — which is a fact about the fleet, not a failure to read it.
|
|
@@ -3614,6 +3921,24 @@ declare class WorkflowEngine {
|
|
|
3614
3921
|
* child: one unreachable child must not abort the sweep and leave every LATER timed-out run alive.
|
|
3615
3922
|
*/
|
|
3616
3923
|
sweepTimeouts(now?: number): Promise<void>;
|
|
3924
|
+
/**
|
|
3925
|
+
* The singleton limit last resolved for a workflow served by convention, by `<namespace>\0<name>`
|
|
3926
|
+
* (see {@link resolveRemoteByConvention}): what the singleton gate's release wake-up reads, since
|
|
3927
|
+
* it cannot wait on the fleet. One entry per convention singleton the fleet serves.
|
|
3928
|
+
*/
|
|
3929
|
+
private readonly conventionSingletonLimits;
|
|
3930
|
+
/** The last read of the announced execution timeouts (see {@link announcedTimeouts}). */
|
|
3931
|
+
private announcedTimeoutsRead;
|
|
3932
|
+
/**
|
|
3933
|
+
* The `executionTimeoutMs` live workers announce (`@Workflow({ executionTimeout })` on a tenant),
|
|
3934
|
+
* per workflow and namespace, for workflows this engine does not register (a registration here
|
|
3935
|
+
* applies its own). Where workers disagree, the one that started last wins. Read at most once per
|
|
3936
|
+
* {@link ANNOUNCED_TIMEOUTS_TTL_MS}; empty without a transport that reads the fleet, or when the
|
|
3937
|
+
* read fails.
|
|
3938
|
+
*/
|
|
3939
|
+
private announcedTimeouts;
|
|
3940
|
+
/** Cancel (`execution_timeout`) the in-flight runs of `workflow` in `namespace` created before `deadline`. */
|
|
3941
|
+
private cancelTimedOut;
|
|
3617
3942
|
/**
|
|
3618
3943
|
* Resume every run left incomplete by a crash or deploy. Called on boot. Completed steps
|
|
3619
3944
|
* replay from their checkpoints, so only the work that had not finished runs again.
|
|
@@ -4441,6 +4766,13 @@ declare class WorkflowEngine {
|
|
|
4441
4766
|
* — the caller has already ensured this is the decision for the currently-awaited turn.
|
|
4442
4767
|
*/
|
|
4443
4768
|
private applyDecision;
|
|
4769
|
+
/**
|
|
4770
|
+
* A remote turn that ended in `ctx.continueAsNew(input)`: record what the turn ran, complete this
|
|
4771
|
+
* run and start its continuation (`<runId>~N`) with `input` on a clean history — the in-process
|
|
4772
|
+
* engine's handoff, with the run's partition and tenant carried over. A run cancelled while the
|
|
4773
|
+
* turn replayed stays cancelled and starts nothing.
|
|
4774
|
+
*/
|
|
4775
|
+
private applyRemoteContinueAsNew;
|
|
4444
4776
|
/**
|
|
4445
4777
|
* Re-drive a run whose turn was computed from a history OLDER than the store's.
|
|
4446
4778
|
*
|
|
@@ -4539,6 +4871,59 @@ declare class WorkflowEngine {
|
|
|
4539
4871
|
* {@link redriveLostCall}). A terminal turn (completed/failed/cancelled) applies its commands only
|
|
4540
4872
|
* to record what already ran, and must never dispatch anything new. */
|
|
4541
4873
|
private applyCommands;
|
|
4874
|
+
/**
|
|
4875
|
+
* Park a remote turn on signal `token` at `seq`: register a waiter so `engine.signal(token)` lands
|
|
4876
|
+
* the resolving `signal` checkpoint here and resumes the run. If the signal was already delivered
|
|
4877
|
+
* (buffered before the workflow reached this point — e.g. signalWithStart), resolve it now and
|
|
4878
|
+
* re-drive on a macrotask, AFTER this turn suspends and frees the run lock (a re-entrant resume
|
|
4879
|
+
* bails).
|
|
4880
|
+
*/
|
|
4881
|
+
private parkRemoteOnSignal;
|
|
4882
|
+
/** Re-drive `runId` on a macrotask, after the current turn has suspended and freed its lease. */
|
|
4883
|
+
private resumeSoon;
|
|
4884
|
+
/**
|
|
4885
|
+
* Stamp the deadline of a BOUNDED remote wait at `deadlineSeq`, once: the first apply records
|
|
4886
|
+
* `now + timeoutMs` as a `timeout:<label>` timer, and every later one reads the recorded deadline
|
|
4887
|
+
* back (the in-process `stampDeadline`). The checkpoint's `input` names the wait it bounds, so the
|
|
4888
|
+
* deadline can drop that wait's waiter when it lapses — see {@link expireRemoteDeadlines}.
|
|
4889
|
+
*/
|
|
4890
|
+
private stampRemoteDeadline;
|
|
4891
|
+
/**
|
|
4892
|
+
* Before a remote turn reads its history: a bounded wait whose deadline has lapsed drops its waiter
|
|
4893
|
+
* (exact row only), so a signal or event arriving later cannot resolve a wait the turn already saw
|
|
4894
|
+
* time out — the in-process wait removes its waiter the same way when it finds the deadline past.
|
|
4895
|
+
* A delivery that took the waiter first wins: its checkpoint is read back into `checkpoints`, and the
|
|
4896
|
+
* worker's replay checks the wait before the deadline. Returns the (possibly extended) list.
|
|
4897
|
+
*/
|
|
4898
|
+
private expireRemoteDeadlines;
|
|
4899
|
+
/**
|
|
4900
|
+
* Claim one buffered event `name` whose payload satisfies `match` and that this run's tenant may
|
|
4901
|
+
* see — the remote twin of the in-process `waitForEvent`'s buffered consumption (oldest first; a
|
|
4902
|
+
* candidate claimed elsewhere first is skipped, not waited on). Expired candidates are pruned when
|
|
4903
|
+
* {@link eventBufferTtlMs} is set, like the reconcile sweep.
|
|
4904
|
+
*/
|
|
4905
|
+
private claimBufferedEvent;
|
|
4906
|
+
/** The lease a freshly dispatched remote `call` parks on: its liveness `timeoutMs` when its policy
|
|
4907
|
+
* sets one, else the lost-dispatch window (`remoteRedispatchMs`), else none. */
|
|
4908
|
+
private callLease;
|
|
4909
|
+
/**
|
|
4910
|
+
* A re-emitted remote `call` that carries its step's policy: apply the policy to the step's
|
|
4911
|
+
* checkpoint exactly as the in-process `ctx.step` path ({@link callRemote} / {@link
|
|
4912
|
+
* callRemoteInMemory}) applies it, so a step declared with retries, backoff or a timeout on a tenant
|
|
4913
|
+
* behaves as it does on a standalone engine. Returns the time to park the run on (`undefined`: no
|
|
4914
|
+
* timer, the step's result or the next turn moves it), or `null` when the policy has nothing to say
|
|
4915
|
+
* and the lost-dispatch self-heal ({@link redriveLostCall}) decides.
|
|
4916
|
+
*
|
|
4917
|
+
* - FAILED and retried (see `remoteCallRetries`): the first sight stamps the backoff deadline on
|
|
4918
|
+
* the failed checkpoint (`wakeAt`, durable and stable across replays); once due, the step is
|
|
4919
|
+
* dispatched again under the same `stepId` with `attempts + 1`.
|
|
4920
|
+
* - PENDING with a `timeoutMs`: the step's lease is `timeoutMs` from its dispatch. A lapsed lease
|
|
4921
|
+
* re-dispatches while attempts remain, then fails the step with a `remote_step_timeout` error the
|
|
4922
|
+
* workflow can catch, as `RemoteStepTimeout` would surface in-process.
|
|
4923
|
+
*/
|
|
4924
|
+
private applyCallPolicy;
|
|
4925
|
+
/** Dispatch a policed remote `call` again as attempt `attempt` (a retry, or a timed-out attempt). */
|
|
4926
|
+
private redispatchCall;
|
|
4542
4927
|
/**
|
|
4543
4928
|
* Undo the registered saga compensations in reverse and settle the run `cancelled`. Shared by EVERY
|
|
4544
4929
|
* exit path of a run with a compensating cancel in flight — whether the resumed replay returned,
|
|
@@ -4856,355 +5241,142 @@ declare class WorkflowEngine {
|
|
|
4856
5241
|
private settleResultsReturning;
|
|
4857
5242
|
/**
|
|
4858
5243
|
* The outcomes for a batch of redelivered results (their steps already settled): one of them
|
|
4859
|
-
* resumes the run if it is `suspended` and, for a step of a fan, the fan's barrier is open. A
|
|
4860
|
-
* resume of a run that had in fact moved on replays to its current wait and re-parks.
|
|
4861
|
-
*/
|
|
4862
|
-
private resumeForRedelivered;
|
|
4863
|
-
/**
|
|
4864
|
-
* The join barrier of a step fan: a result for one of its steps resumes the parent only once no
|
|
4865
|
-
* step of the fan is still `pending` (a settled wave), or on a failure (failFast surfaces it, and a
|
|
4866
|
-
* retry needs the parent to schedule it). Without it every result would replay the whole parent,
|
|
4867
|
-
* which makes a fan of N steps cost O(N²) checkpoint reads. `barriers` holds the answer per fan
|
|
4868
|
-
* for the rest of a batch. A barrier that cannot be read counts as open: a spare resume replays and
|
|
4869
|
-
* re-suspends, a lost one strands the run. A fan with a result waiting in `queuedIn` is left to
|
|
4870
|
-
* that result (see {@link completeRemoteResults}).
|
|
4871
|
-
*/
|
|
4872
|
-
private stepFanStillRunning;
|
|
4873
|
-
/** Whether any step of a step fan's seq range is still `pending`. */
|
|
4874
|
-
private stepFanHasPending;
|
|
4875
|
-
/**
|
|
4876
|
-
* Apply a remote workflow-turn {@link WorkflowDecision} durably — runs on WHATEVER instance receives
|
|
4877
|
-
* it over the broker (the dispatching one may be gone, or a point-to-point broker handed it to a
|
|
4878
|
-
* non-dispatcher). The durable, multi-instance-safe twin of {@link completeRemoteResult} for the
|
|
4879
|
-
* workflow TURN: look the run up by `decision.runId`, verify the decision matches the run's
|
|
4880
|
-
* CURRENTLY-awaited turn (`awaitingDecisionTaskId`) — so a stale / duplicate / foreign / re-driven
|
|
4881
|
-
* decision is dropped (applied AT MOST ONCE) — lease it, clear the marker, and apply the decision.
|
|
4882
|
-
*/
|
|
4883
|
-
private completeRemoteDecision;
|
|
4884
|
-
/** Earliest clock time a suspended turn's deadline is worth LOOKING at again (`runId` → clock ms) —
|
|
4885
|
-
* the read throttle for {@link rearmDecisionDeadline}, the run-scoped sibling of
|
|
4886
|
-
* {@link stepLeaseRearms}. */
|
|
4887
|
-
private readonly decisionDeadlineRearms;
|
|
4888
|
-
/**
|
|
4889
|
-
* A run-scoped heartbeat for a run suspended awaiting a workflow-turn decision (the dispatch path):
|
|
4890
|
-
* push its durable re-drive deadline (`wakeAt`) forward so a still-working worker's turn is not
|
|
4891
|
-
* re-dispatched. The durable counterpart of an inline turn's in-memory `heartbeatResets` rearm.
|
|
4892
|
-
*
|
|
4893
|
-
* THROTTLED exactly as {@link rearmStepLease} is, and for the same reason: a long workflow turn's
|
|
4894
|
-
* worker beats every couple of seconds, and each beat otherwise cost a `getRun` + `updateRun`.
|
|
4895
|
-
* The window here is `remoteAdvanceSilenceMs`, and a renewal buys at most one of them — so it is
|
|
4896
|
-
* only worth a write once the window is half spent, which leaves a full half-window of headroom
|
|
4897
|
-
* before the timer poller would re-drive the turn. The in-memory mark is a pure optimisation: a
|
|
4898
|
-
* cold (or different) instance re-derives the same answer from the run's own `wakeAt`.
|
|
4899
|
-
*/
|
|
4900
|
-
private rearmDecisionDeadline;
|
|
4901
|
-
/**
|
|
4902
|
-
* A slot freed on `queue` (a fleet-wide signal): resume this instance's runs blocked on it so they
|
|
4903
|
-
* re-contend now instead of at their retry tick. Snapshot-and-clear — a run still blocked after the
|
|
4904
|
-
* retry re-registers itself, and one that's gone (cancelled/admitted) is dropped. Best-effort.
|
|
4905
|
-
*/
|
|
4906
|
-
private wakeQueueWaiters;
|
|
4907
|
-
/** Release the flow-control slot a dispatched step held (if any), by its stepId. */
|
|
4908
|
-
private releaseQueueSlot;
|
|
4909
|
-
/** In-memory await path for a remote step with a liveness `timeoutMs` (re-dispatch on timeout). */
|
|
4910
|
-
private callRemoteInMemory;
|
|
4911
|
-
/**
|
|
4912
|
-
* Await `resultPromise`, but reject with `onTimeout()` if neither it settles nor a heartbeat for `id`
|
|
4913
|
-
* arrives within `timeoutMs`. Each heartbeat (delivered via `transport.onHeartbeat`, looked up in
|
|
4914
|
-
* `heartbeatResets` by `id`) REARMS the window, so a worker that keeps beating stays alive past
|
|
4915
|
-
* `timeoutMs`. Shared by the remote-STEP liveness (keyed by stepId) and the remote-WORKFLOW advance
|
|
4916
|
-
* liveness (keyed by runId); the caller supplies the timeout error and any extra cleanup via `onTimeout`.
|
|
4917
|
-
*/
|
|
4918
|
-
private awaitWithLivenessDeadline;
|
|
4919
|
-
/** Remote-STEP liveness: await a worker result, timing out (with the step's pending-map cleanup) to
|
|
4920
|
-
* `RemoteStepTimeout` if it neither lands nor beats within `timeoutMs`. See {@link awaitWithLivenessDeadline}. */
|
|
4921
|
-
private awaitWithHeartbeat;
|
|
4922
|
-
}
|
|
4923
|
-
/** Raised inside the workflow when a remote worker reports a step failure. */
|
|
4924
|
-
declare class RemoteStepError extends Error {
|
|
4925
|
-
readonly stepError?: StepError | undefined;
|
|
4926
|
-
constructor(stepError?: StepError);
|
|
4927
|
-
}
|
|
4928
|
-
/** Checkpoint names that record a parent→child edge: an awaited child, a folded group of them, a spawn. */
|
|
4929
|
-
declare const CHILD_EDGE_PREFIXES: string[];
|
|
4930
|
-
/** The child run ids a parent's {@link CHILD_EDGE_PREFIXES} checkpoints point at (others are skipped). */
|
|
4931
|
-
declare function childIdsOf(checkpoints: StepCheckpoint[]): string[];
|
|
4932
|
-
|
|
4933
|
-
/**
|
|
4934
|
-
* A schedule definition — what `engine.schedules.create/upsert` take. Temporal-style: a persisted,
|
|
4935
|
-
* runtime-managed recurring start of `workflow` with `input`, fired by every driving engine's timer
|
|
4936
|
-
* poll (safe with many workers: each window's run id is deterministic, `start` is idempotent, and
|
|
4937
|
-
* advancing the schedule is a compare-and-set).
|
|
4938
|
-
*/
|
|
4939
|
-
interface ScheduleOptions {
|
|
4940
|
-
/** Stable id, unique per store (e.g. `digest:user-42`). Part of every run id it starts. */
|
|
4941
|
-
id: string;
|
|
4942
|
-
/** The workflow to start — a registered name or `@Workflow` class. */
|
|
4943
|
-
workflow: WorkflowRef;
|
|
4944
|
-
/** The input every run starts with. */
|
|
4945
|
-
input?: unknown;
|
|
4946
|
-
/** Cron expression (5 fields, or 6 with leading seconds). Needs the `cron-parser` peer. */
|
|
4947
|
-
cron?: string | undefined;
|
|
4948
|
-
/** Fixed interval (`'15m'`, or ms), windows aligned to the epoch. Exclusive with `cron`. */
|
|
4949
|
-
every?: string | number | undefined;
|
|
4950
|
-
/**
|
|
4951
|
-
* An RFC 5545 recurrence rule (`'FREQ=WEEKLY;BYDAY=MO;BYHOUR=8'`, optionally with a
|
|
4952
|
-
* `DTSTART:…` line), evaluated in `timezone`. Exactly one of `cron`, `every` and `rrule`. See
|
|
4953
|
-
* {@link parseRRule} for the supported parts. No peer needed.
|
|
4954
|
-
*/
|
|
4955
|
-
rrule?: string | undefined;
|
|
4956
|
-
/** IANA timezone the cron / rrule is evaluated in (e.g. `America/Sao_Paulo`). Default UTC. */
|
|
4957
|
-
timezone?: string | undefined;
|
|
4958
|
-
/**
|
|
4959
|
-
* Delay each fire by up to this much (`'30s'` or ms) — a stable per-(schedule, window) offset, so
|
|
4960
|
-
* thousands of schedules on the same cron don't all start in the same second.
|
|
4961
|
-
*/
|
|
4962
|
-
jitter?: string | number | undefined;
|
|
4963
|
-
/**
|
|
4964
|
-
* The previous run of this schedule is still in flight when the next window comes due:
|
|
4965
|
-
* `'allow'` (default) starts the new one anyway; `'skip'` skips that window.
|
|
4966
|
-
*/
|
|
4967
|
-
overlap?: 'allow' | 'skip' | undefined;
|
|
4968
|
-
/**
|
|
4969
|
-
* Windows missed while nothing polled (all schedulers down): `'latest'` (default) fires the most
|
|
4970
|
-
* recent missed window once; `'skip'` drops them and waits for the next window. Never more than one
|
|
4971
|
-
* catch-up run per schedule.
|
|
4972
|
-
*/
|
|
4973
|
-
catchup?: 'latest' | 'skip' | undefined;
|
|
4974
|
-
/** Create paused (never due until `resume`). On `upsert`, omit to keep the current paused state. */
|
|
4975
|
-
paused?: boolean | undefined;
|
|
4976
|
-
/** Free-form note shown with the schedule (why it exists / why it's paused). */
|
|
4977
|
-
note?: string | undefined;
|
|
4978
|
-
/** Namespace of the schedule and of the runs it starts. Defaults to the engine's own namespace. */
|
|
4979
|
-
namespace?: string | undefined;
|
|
4980
|
-
/** Labels to find the schedule by — also stamped on every run it starts (plus `schedule:<id>`). */
|
|
4981
|
-
tags?: string[] | undefined;
|
|
4982
|
-
/** Search attributes stamped on every run it starts. */
|
|
4983
|
-
searchAttributes?: SearchAttributes | undefined;
|
|
4984
|
-
/** Dispatch priority for the runs it starts. */
|
|
4985
|
-
priority?: number | undefined;
|
|
4986
|
-
/**
|
|
4987
|
-
* A start-time concurrency quota applied to every run it starts (see `StartOptions.concurrency`):
|
|
4988
|
-
* a window whose start would exceed it is recorded as the schedule's `lastError` and skipped, and
|
|
4989
|
-
* the schedule moves on to its next window.
|
|
4990
|
-
*/
|
|
4991
|
-
concurrency?: ConcurrencyQuota | undefined;
|
|
4992
|
-
/**
|
|
4993
|
-
* The customer the schedule belongs to; every run it starts inherits it. An explicit value wins
|
|
4994
|
-
* (`null` = none); omit it and the schedule takes the context tenant when tenancy is on. On
|
|
4995
|
-
* `upsert`, omit to keep the schedule's current tenant.
|
|
4996
|
-
*/
|
|
4997
|
-
tenantId?: string | null | undefined;
|
|
4998
|
-
/** The kind of {@link tenantId}. Only read with an explicit `tenantId`. */
|
|
4999
|
-
tenantKind?: string | undefined;
|
|
5000
|
-
}
|
|
5001
|
-
/** A schedule as `engine.schedules.get/list` describe it. */
|
|
5002
|
-
interface ScheduleDescription {
|
|
5003
|
-
id: string;
|
|
5004
|
-
workflow: string;
|
|
5005
|
-
input: unknown;
|
|
5006
|
-
namespace: string;
|
|
5007
|
-
cron?: string | undefined;
|
|
5008
|
-
everyMs?: number | undefined;
|
|
5009
|
-
rrule?: string | undefined;
|
|
5010
|
-
timezone?: string | undefined;
|
|
5011
|
-
jitterMs?: number | undefined;
|
|
5012
|
-
overlap: 'allow' | 'skip';
|
|
5013
|
-
catchup: 'latest' | 'skip';
|
|
5014
|
-
paused: boolean;
|
|
5015
|
-
note?: string | undefined;
|
|
5016
|
-
tags?: string[] | undefined;
|
|
5017
|
-
searchAttributes?: SearchAttributes | undefined;
|
|
5018
|
-
priority?: number | undefined;
|
|
5019
|
-
concurrency?: ConcurrencyQuota | undefined;
|
|
5020
|
-
/** When it is next due (jitter included), or null if it never fires again / paused. */
|
|
5021
|
-
nextFireAt: Date | null;
|
|
5022
|
-
/** The last window it fired for, and the run that window started. */
|
|
5023
|
-
lastFireAt?: Date | undefined;
|
|
5024
|
-
lastRunId?: string | undefined;
|
|
5025
|
-
/** How many windows it has fired (manual triggers excluded). */
|
|
5026
|
-
fires: number;
|
|
5027
|
-
/** The last start failure (e.g. a concurrency limit), cleared by the next successful start. */
|
|
5028
|
-
lastError?: string | undefined;
|
|
5029
|
-
/** The customer the schedule and its runs belong to, when it has one. */
|
|
5030
|
-
tenantId?: string | undefined;
|
|
5031
|
-
tenantKind?: string | undefined;
|
|
5032
|
-
/**
|
|
5033
|
-
* Set on a schedule a tenant app ANNOUNCED (its `schedules` module option) and the control plane
|
|
5034
|
-
* adopted: the key the app declares it under. Its `namespace` is the app (partition).
|
|
5035
|
-
*/
|
|
5036
|
-
announcedKey?: string | undefined;
|
|
5037
|
-
/** An announced schedule that no live worker of its app announces any more: since when. */
|
|
5038
|
-
unannouncedSince?: Date | undefined;
|
|
5039
|
-
/** When the control plane paused it for staying unannounced past the grace period. */
|
|
5040
|
-
withdrawnAt?: Date | undefined;
|
|
5041
|
-
createdAt: Date;
|
|
5042
|
-
updatedAt: Date;
|
|
5043
|
-
}
|
|
5044
|
-
/** The tag on every schedule adopted from a tenant's announcement (and on the runs it starts). */
|
|
5045
|
-
declare const ANNOUNCED_SCHEDULE_TAG = "schedule:announced";
|
|
5046
|
-
/** The control plane's schedule id for the schedule `key` announced by the app on `namespace`. */
|
|
5047
|
-
declare function announcedScheduleId(namespace: string, key: string): string;
|
|
5048
|
-
/** Filter for `engine.schedules.list`. */
|
|
5049
|
-
type ScheduleListQuery = Omit<ScheduleQuery, 'dueBy'>;
|
|
5050
|
-
/** Thrown by `engine.schedules.create` when the id is taken (use `upsert` to replace). */
|
|
5051
|
-
declare class ScheduleAlreadyExistsError extends Error {
|
|
5052
|
-
readonly scheduleId: string;
|
|
5053
|
-
constructor(scheduleId: string);
|
|
5054
|
-
}
|
|
5055
|
-
/** Thrown by `engine.schedules.*` on an id that doesn't exist. */
|
|
5056
|
-
declare class ScheduleNotFoundError extends Error {
|
|
5057
|
-
readonly scheduleId: string;
|
|
5058
|
-
constructor(scheduleId: string);
|
|
5059
|
-
}
|
|
5060
|
-
/** What {@link ScheduleClient.syncAnnounced} did to a namespace's adopted schedules. */
|
|
5061
|
-
interface AnnouncedScheduleSync {
|
|
5062
|
-
/** Created, or re-applied because the announced definition changed. */
|
|
5063
|
-
adopted: string[];
|
|
5064
|
-
/** Announced again after missing (and resumed, when it had been withdrawn). */
|
|
5065
|
-
restored: string[];
|
|
5066
|
-
/** Missing from the announcement for the first time: the grace period starts. */
|
|
5067
|
-
missing: string[];
|
|
5068
|
-
/** Paused because it stayed unannounced past the grace period. */
|
|
5069
|
-
withdrawn: string[];
|
|
5070
|
-
/** Announced, but the definition does not evaluate (bad cron, both or neither cadence). */
|
|
5071
|
-
invalid: {
|
|
5072
|
-
key: string;
|
|
5073
|
-
error: string;
|
|
5074
|
-
}[];
|
|
5075
|
-
}
|
|
5076
|
-
/** The engine surface the schedule client drives. */
|
|
5077
|
-
interface ScheduleHost {
|
|
5078
|
-
start(workflow: string, input: unknown, runId: string, opts?: StartOptions): Promise<RunResult>;
|
|
5079
|
-
/**
|
|
5080
|
-
* The tenant start path, used to fire an announced schedule: a workflow no live worker serves yet
|
|
5081
|
-
* is parked `blocked` (`no_live_worker`) until one is, instead of throwing. Absent = `start`.
|
|
5082
|
-
*/
|
|
5083
|
-
startParked?(workflow: string, input: unknown, runId: string, opts?: StartOptions): Promise<RunResult>;
|
|
5084
|
-
getRun(runId: string): Promise<WorkflowRun | null>;
|
|
5085
|
-
/** True once the engine has begun shutting down; `tick` fires nothing more after that. */
|
|
5086
|
-
isDraining?(): boolean;
|
|
5087
|
-
/** The context tenant to stamp on a schedule created now (tenancy on), else undefined. */
|
|
5088
|
-
tenant?(): RunTenant | undefined;
|
|
5089
|
-
/** The tenancy matching filter for an app-facing call made now. Absent = sees everything. */
|
|
5090
|
-
tenantFilter?(): TenantFilter;
|
|
5091
|
-
}
|
|
5092
|
-
/** Engine-level knobs for the client. */
|
|
5093
|
-
interface ScheduleClientOptions {
|
|
5094
|
-
/** The engine's namespace: the default for new schedules, and which ones `tick` fires. */
|
|
5095
|
-
namespace?: string | undefined;
|
|
5096
|
-
clock?: (() => number) | undefined;
|
|
5097
|
-
}
|
|
5098
|
-
/**
|
|
5099
|
-
* Persisted, runtime-managed schedules — `engine.schedules`. Unlike the code-registered
|
|
5100
|
-
* `schedules` module option, these live in the store: create/update/pause/delete them at runtime
|
|
5101
|
-
* (one per user, per tenant, per automation…), and every driving engine's timer poll fires the due
|
|
5102
|
-
* ones via {@link tick}.
|
|
5103
|
-
*
|
|
5104
|
-
* Multi-worker safety comes from two properties, not from a lock: a window's run id is deterministic
|
|
5105
|
-
* (`sched:<id>:<windowMs>`), so racing starts of the same window collapse into one run; and a
|
|
5106
|
-
* schedule is advanced with a compare-and-set on its `nextFireAt`, so exactly one poller moves it on.
|
|
5107
|
-
* A crash between starting the run and advancing the schedule just re-fires the (idempotent) start.
|
|
5108
|
-
*/
|
|
5109
|
-
declare class ScheduleClient {
|
|
5110
|
-
private readonly store;
|
|
5111
|
-
private readonly host;
|
|
5112
|
-
private readonly options;
|
|
5113
|
-
constructor(store: StateStore, host: ScheduleHost, options?: ScheduleClientOptions);
|
|
5114
|
-
private now;
|
|
5115
|
-
/** Whether the store persists schedules (implements the schedule methods). */
|
|
5116
|
-
get supported(): boolean;
|
|
5117
|
-
private requireStore;
|
|
5118
|
-
private filter;
|
|
5119
|
-
/** The schedule `id` if it exists and the caller may see it (tenancy), else null. */
|
|
5120
|
-
private visible;
|
|
5121
|
-
/** Create a schedule. Throws {@link ScheduleAlreadyExistsError} if the id is taken. */
|
|
5122
|
-
create(opts: ScheduleOptions): Promise<ScheduleDescription>;
|
|
5123
|
-
/**
|
|
5124
|
-
* Create the schedule, or replace the definition of an existing one (its history — last fire, last
|
|
5125
|
-
* run, fire count — is kept). The next fire is recomputed from now under the new definition, so a
|
|
5126
|
-
* window that already fired is never fired again by an upsert.
|
|
5244
|
+
* resumes the run if it is `suspended` and, for a step of a fan, the fan's barrier is open. A
|
|
5245
|
+
* resume of a run that had in fact moved on replays to its current wait and re-parks.
|
|
5127
5246
|
*/
|
|
5128
|
-
|
|
5129
|
-
/** The schedule `id`, or null (also null for another tenant's schedule). */
|
|
5130
|
-
get(id: string): Promise<ScheduleDescription | null>;
|
|
5131
|
-
/** Schedules matching `query` (and visible to the caller's tenant), soonest-due first. */
|
|
5132
|
-
list(query?: ScheduleListQuery): Promise<ScheduleDescription[]>;
|
|
5133
|
-
/** Delete the schedule. Runs it already started are left alone. Returns whether it existed. */
|
|
5134
|
-
delete(id: string): Promise<boolean>;
|
|
5135
|
-
/** Stop firing until {@link resume}. `note` records why (shown by `get`/`list`). */
|
|
5136
|
-
pause(id: string, note?: string): Promise<ScheduleDescription>;
|
|
5247
|
+
private resumeForRedelivered;
|
|
5137
5248
|
/**
|
|
5138
|
-
*
|
|
5249
|
+
* The join barrier of a step fan: a result for one of its steps resumes the parent only once no
|
|
5250
|
+
* step of the fan is still `pending` (a settled wave), or on a failure (failFast surfaces it, and a
|
|
5251
|
+
* retry needs the parent to schedule it). Without it every result would replay the whole parent,
|
|
5252
|
+
* which makes a fan of N steps cost O(N²) checkpoint reads. `barriers` holds the answer per fan
|
|
5253
|
+
* for the rest of a batch. A barrier that cannot be read counts as open: a spare resume replays and
|
|
5254
|
+
* re-suspends, a lost one strands the run. A fan with a result waiting in `queuedIn` is left to
|
|
5255
|
+
* that result (see {@link completeRemoteResults}).
|
|
5139
5256
|
*/
|
|
5140
|
-
|
|
5257
|
+
private stepFanStillRunning;
|
|
5258
|
+
/** Whether any step of a step fan's seq range is still `pending`. */
|
|
5259
|
+
private stepFanHasPending;
|
|
5141
5260
|
/**
|
|
5142
|
-
*
|
|
5143
|
-
*
|
|
5261
|
+
* Apply a remote workflow-turn {@link WorkflowDecision} durably — runs on WHATEVER instance receives
|
|
5262
|
+
* it over the broker (the dispatching one may be gone, or a point-to-point broker handed it to a
|
|
5263
|
+
* non-dispatcher). The durable, multi-instance-safe twin of {@link completeRemoteResult} for the
|
|
5264
|
+
* workflow TURN: look the run up by `decision.runId`, verify the decision matches the run's
|
|
5265
|
+
* CURRENTLY-awaited turn (`awaitingDecisionTaskId`) — so a stale / duplicate / foreign / re-driven
|
|
5266
|
+
* decision is dropped (applied AT MOST ONCE) — lease it, clear the marker, and apply the decision.
|
|
5144
5267
|
*/
|
|
5145
|
-
|
|
5268
|
+
private completeRemoteDecision;
|
|
5269
|
+
/** Earliest clock time a suspended turn's deadline is worth LOOKING at again (`runId` → clock ms) —
|
|
5270
|
+
* the read throttle for {@link rearmDecisionDeadline}, the run-scoped sibling of
|
|
5271
|
+
* {@link stepLeaseRearms}. */
|
|
5272
|
+
private readonly decisionDeadlineRearms;
|
|
5146
5273
|
/**
|
|
5147
|
-
*
|
|
5148
|
-
*
|
|
5274
|
+
* A run-scoped heartbeat for a run suspended awaiting a workflow-turn decision (the dispatch path):
|
|
5275
|
+
* push its durable re-drive deadline (`wakeAt`) forward so a still-working worker's turn is not
|
|
5276
|
+
* re-dispatched. The durable counterpart of an inline turn's in-memory `heartbeatResets` rearm.
|
|
5277
|
+
*
|
|
5278
|
+
* THROTTLED exactly as {@link rearmStepLease} is, and for the same reason: a long workflow turn's
|
|
5279
|
+
* worker beats every couple of seconds, and each beat otherwise cost a `getRun` + `updateRun`.
|
|
5280
|
+
* The window here is `remoteAdvanceSilenceMs`, and a renewal buys at most one of them — so it is
|
|
5281
|
+
* only worth a write once the window is half spent, which leaves a full half-window of headroom
|
|
5282
|
+
* before the timer poller would re-drive the turn. The in-memory mark is a pure optimisation: a
|
|
5283
|
+
* cold (or different) instance re-derives the same answer from the run's own `wakeAt`.
|
|
5149
5284
|
*/
|
|
5150
|
-
private
|
|
5285
|
+
private rearmDecisionDeadline;
|
|
5151
5286
|
/**
|
|
5152
|
-
*
|
|
5153
|
-
*
|
|
5154
|
-
*
|
|
5155
|
-
* each tick when `persistedSchedules` is on; call it yourself from any other driver. Returns the
|
|
5156
|
-
* run ids started (or re-found, for an idempotent re-fire).
|
|
5287
|
+
* A slot freed on `queue` (a fleet-wide signal): resume this instance's runs blocked on it so they
|
|
5288
|
+
* re-contend now instead of at their retry tick. Snapshot-and-clear — a run still blocked after the
|
|
5289
|
+
* retry re-registers itself, and one that's gone (cancelled/admitted) is dropped. Best-effort.
|
|
5157
5290
|
*/
|
|
5158
|
-
|
|
5159
|
-
|
|
5160
|
-
|
|
5291
|
+
private wakeQueueWaiters;
|
|
5292
|
+
/** Release the flow-control slot a dispatched step held (if any), by its stepId. */
|
|
5293
|
+
private releaseQueueSlot;
|
|
5294
|
+
/** In-memory await path for a remote step with a liveness `timeoutMs` (re-dispatch on timeout). */
|
|
5295
|
+
private callRemoteInMemory;
|
|
5161
5296
|
/**
|
|
5162
|
-
*
|
|
5163
|
-
*
|
|
5164
|
-
*
|
|
5165
|
-
*
|
|
5166
|
-
*
|
|
5297
|
+
* Await `resultPromise`, but reject with `onTimeout()` if neither it settles nor a heartbeat for `id`
|
|
5298
|
+
* arrives within `timeoutMs`. Each heartbeat (delivered via `transport.onHeartbeat`, looked up in
|
|
5299
|
+
* `heartbeatResets` by `id`) REARMS the window, so a worker that keeps beating stays alive past
|
|
5300
|
+
* `timeoutMs`. Shared by the remote-STEP liveness (keyed by stepId) and the remote-WORKFLOW advance
|
|
5301
|
+
* liveness (keyed by runId); the caller supplies the timeout error and any extra cleanup via `onTimeout`.
|
|
5167
5302
|
*/
|
|
5168
|
-
|
|
5169
|
-
|
|
5170
|
-
|
|
5171
|
-
|
|
5172
|
-
|
|
5303
|
+
private awaitWithLivenessDeadline;
|
|
5304
|
+
/** Remote-STEP liveness: await a worker result, timing out (with the step's pending-map cleanup) to
|
|
5305
|
+
* `RemoteStepTimeout` if it neither lands nor beats within `timeoutMs`. See {@link awaitWithLivenessDeadline}. */
|
|
5306
|
+
private awaitWithHeartbeat;
|
|
5307
|
+
}
|
|
5308
|
+
/** Raised inside the workflow when a remote worker reports a step failure. */
|
|
5309
|
+
declare class RemoteStepError extends Error {
|
|
5310
|
+
readonly stepError?: StepError | undefined;
|
|
5311
|
+
constructor(stepError?: StepError);
|
|
5312
|
+
}
|
|
5313
|
+
/** Checkpoint names that record a parent→child edge: an awaited child, a folded group of them, a spawn. */
|
|
5314
|
+
declare const CHILD_EDGE_PREFIXES: string[];
|
|
5315
|
+
/** The child run ids a parent's {@link CHILD_EDGE_PREFIXES} checkpoints point at (others are skipped). */
|
|
5316
|
+
declare function childIdsOf(checkpoints: StepCheckpoint[]): string[];
|
|
5317
|
+
|
|
5318
|
+
/**
|
|
5319
|
+
* One end of a `ctx.waitForRun` wait, as a run detail lists it: the run waited for (`waitsFor`) or
|
|
5320
|
+
* the waiting run (`awaitedBy`), the waiting run's `seq` of the call, and the other run's status and
|
|
5321
|
+
* namespace when it was read.
|
|
5322
|
+
*/
|
|
5323
|
+
interface RunWaitLink {
|
|
5324
|
+
runId: string;
|
|
5325
|
+
seq: number;
|
|
5326
|
+
status?: RunStatus | undefined;
|
|
5327
|
+
namespace?: string | undefined;
|
|
5328
|
+
}
|
|
5329
|
+
/**
|
|
5330
|
+
* Where a settled run's lifecycle event stands for one subscriber:
|
|
5331
|
+
* - `started`: its run exists (`runId`, a `durable:triggered:<subscriber>` tag);
|
|
5332
|
+
* - `owed`: still pending (a `durable:lifecycle:owed:<subscriber>` tag);
|
|
5333
|
+
* - `coalesced`: routed into a debounce/batch accumulator (a `durable:coalesced:<subscriber>` tag,
|
|
5334
|
+
* or the caller's `coalesced` map; `runId` is the accumulator's, when it can be derived);
|
|
5335
|
+
* - `failed`: its start failed (a `durable:trigger_failed:<subscriber>` tag): its `where` threw, its
|
|
5336
|
+
* input was rejected, its start threw, or the sweep dropped it as orphaned. A republish retries it;
|
|
5337
|
+
* - `not-started`: no run and nothing owed: its `where` declined the event, or it subscribed after
|
|
5338
|
+
* the run settled.
|
|
5339
|
+
*/
|
|
5340
|
+
type LifecycleDeliveryState = 'started' | 'owed' | 'coalesced' | 'failed' | 'not-started';
|
|
5341
|
+
/** One subscriber of a settled run's lifecycle event, as the run detail lists it. */
|
|
5342
|
+
interface LifecycleDelivery {
|
|
5343
|
+
subscriber: string;
|
|
5344
|
+
state: LifecycleDeliveryState;
|
|
5345
|
+
/** The subscriber's run when `started`; the accumulator run when `coalesced` and derivable. */
|
|
5346
|
+
runId?: string | undefined;
|
|
5347
|
+
/** The status of a `started` subscriber's run, when it was read. */
|
|
5348
|
+
status?: RunStatus | undefined;
|
|
5349
|
+
/** The namespace of a `started` subscriber's run, when it was read. */
|
|
5350
|
+
namespace?: string | undefined;
|
|
5351
|
+
/** When an `owed` subscriber became owed: the settled run's last update (epoch ms). */
|
|
5352
|
+
owedSince?: number | undefined;
|
|
5173
5353
|
/**
|
|
5174
|
-
*
|
|
5175
|
-
*
|
|
5176
|
-
*
|
|
5177
|
-
* bound `catchup: 'latest'` puts on windows missed while no scheduler polled.
|
|
5354
|
+
* When the lifecycle sweep drops an `owed` subscriber that no live instance registers or
|
|
5355
|
+
* announces for the run's namespace (epoch ms; see {@link LIFECYCLE_ORPHAN_MS}). Absent while one
|
|
5356
|
+
* does.
|
|
5178
5357
|
*/
|
|
5179
|
-
|
|
5358
|
+
orphanAt?: number | undefined;
|
|
5180
5359
|
/**
|
|
5181
|
-
*
|
|
5182
|
-
*
|
|
5183
|
-
*
|
|
5184
|
-
* {@link ANNOUNCED_SCHEDULE_TAG}, `catchup: 'latest'`); one whose definition changed is
|
|
5185
|
-
* re-applied like `upsert` (its history kept, its next fire recomputed from now). An equal
|
|
5186
|
-
* definition writes nothing, so any number of replicas announcing the same set is a no-op;
|
|
5187
|
-
* - a pause or resume made from the console survives: a re-applied definition keeps the current
|
|
5188
|
-
* paused state, unless the app's own declared `paused` changed;
|
|
5189
|
-
* - an adopted schedule the app no longer announces is marked missing, and paused ("withdrawn")
|
|
5190
|
-
* once it has stayed missing for `graceMs`. It is never deleted: its history stays, and an app
|
|
5191
|
-
* that announces it again (a rollback) gets it back, resumed unless an operator had paused it.
|
|
5192
|
-
*
|
|
5193
|
-
* Call it only for an app that has at least one live worker stating its schedules: with none (the
|
|
5194
|
-
* app is down, or runs an SDK that does not announce schedules), nothing is withdrawn, and its
|
|
5195
|
-
* schedules keep firing into runs that wait for a worker.
|
|
5360
|
+
* Why a `failed` subscriber did not start, when the caller knows it (the run's tags record only
|
|
5361
|
+
* that it failed; the `run.trigger_failed` event carries the message). {@link lifecycleDeliveriesOf}
|
|
5362
|
+
* leaves it unset.
|
|
5196
5363
|
*/
|
|
5197
|
-
|
|
5198
|
-
nowMs?: number;
|
|
5199
|
-
graceMs: number;
|
|
5200
|
-
}): Promise<AnnouncedScheduleSync>;
|
|
5201
|
-
/** `overlap: 'skip'` and the previous run of this schedule is still in flight. */
|
|
5202
|
-
private overlapping;
|
|
5203
|
-
private mustGet;
|
|
5204
|
-
/** Explicit `opts.tenantId` → the existing schedule's tenant (upsert) → the context tenant → none. */
|
|
5205
|
-
private scheduleTenant;
|
|
5206
|
-
private write;
|
|
5364
|
+
error?: string | undefined;
|
|
5207
5365
|
}
|
|
5366
|
+
/**
|
|
5367
|
+
* The {@link LifecycleDelivery} of each subscriber of a settled run, sorted by subscriber: the
|
|
5368
|
+
* union of `subscribers` (the ones the run's event goes to now) and the owed, triggered, coalesced
|
|
5369
|
+
* and trigger-failed tags. `live` names the subscribers a live instance registers or announces; an owed subscriber
|
|
5370
|
+
* outside it gets `orphanAt`. `coalesced` maps each subscriber that coalesces its events to its
|
|
5371
|
+
* accumulator run id (undefined when it cannot be derived). Empty for a run that has not settled.
|
|
5372
|
+
*/
|
|
5373
|
+
declare function lifecycleDeliveriesOf(run: Pick<WorkflowRun, 'id' | 'status' | 'tags' | 'updatedAt'>, opts: {
|
|
5374
|
+
subscribers: readonly string[];
|
|
5375
|
+
live: ReadonlySet<string>;
|
|
5376
|
+
coalesced?: ReadonlyMap<string, string | undefined> | undefined;
|
|
5377
|
+
}): LifecycleDelivery[];
|
|
5378
|
+
/** The trace id of a W3C `traceparent` (`00-<trace id>-<span id>-<flags>`), or undefined. */
|
|
5379
|
+
declare function traceIdOfTraceparent(traceparent: string | undefined): string | undefined;
|
|
5208
5380
|
|
|
5209
5381
|
/** A run as returned by the gateway's list — the durable run plus an optional {@link RunWaiting}
|
|
5210
5382
|
* descriptor the control plane resolves (what a suspended run is parked on), so the dashboard can
|
|
@@ -5475,9 +5647,29 @@ declare abstract class RunGateway {
|
|
|
5475
5647
|
* Deliver `payload` to the run waiting on `token` (`WorkflowEngine.signal`). Null when no run waits
|
|
5476
5648
|
* on it. Optional, like {@link listSchedules}.
|
|
5477
5649
|
*/
|
|
5478
|
-
signal?(token: string, payload: unknown): Promise<RunResult | null>;
|
|
5650
|
+
signal?(token: string, payload: unknown, opts?: SignalOptions): Promise<RunResult | null>;
|
|
5479
5651
|
/** The id of the run waiting on signal `token`, or null when none waits on it yet. Optional. */
|
|
5480
5652
|
signalWaiter?(token: string): Promise<string | null>;
|
|
5653
|
+
/**
|
|
5654
|
+
* A tenant's `signalWithStart` (`WorkflowEngine.signalWithStartForTenant`): start `start` in
|
|
5655
|
+
* `namespace` unless its run exists, then signal it. Optional, like {@link listSchedules}.
|
|
5656
|
+
*/
|
|
5657
|
+
signalWithStartForTenant?(start: StartRunMessage & {
|
|
5658
|
+
runId: string;
|
|
5659
|
+
}, namespace: string, clientTenant: Pick<StartOptions, 'tenantId' | 'tenantKind'>, signal: {
|
|
5660
|
+
token: string;
|
|
5661
|
+
payload?: unknown;
|
|
5662
|
+
}): Promise<{
|
|
5663
|
+
runId: string;
|
|
5664
|
+
signalled: boolean;
|
|
5665
|
+
}>;
|
|
5666
|
+
/**
|
|
5667
|
+
* A tenant's `publishEvent`, scoped to `namespace` (`WorkflowEngine.publishEventForTenant`).
|
|
5668
|
+
* Resolves how many runs it resumed or started. Optional, like {@link listSchedules}.
|
|
5669
|
+
*/
|
|
5670
|
+
publishEventForTenant?(name: string, payload: unknown, namespace: string, opts?: {
|
|
5671
|
+
id?: string;
|
|
5672
|
+
}): Promise<number>;
|
|
5481
5673
|
/** Live lifecycle events for one run; returns an unsubscribe fn. Framework-agnostic (no rxjs). */
|
|
5482
5674
|
abstract subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
|
|
5483
5675
|
}
|
|
@@ -7013,6 +7205,21 @@ interface StartRunMessage {
|
|
|
7013
7205
|
* the tenant caller has already returned.
|
|
7014
7206
|
*/
|
|
7015
7207
|
concurrency?: ConcurrencyQuota | undefined;
|
|
7208
|
+
/**
|
|
7209
|
+
* The workflow's `@Workflow({ singleton })`, evaluated by the starting app against this input: the
|
|
7210
|
+
* serialization key, the limit and the queue depth. A control plane that serves the workflow by
|
|
7211
|
+
* convention (it has no registration of its own, so it cannot evaluate the key) stamps the run
|
|
7212
|
+
* `singleton:<key>` and admits it against `limit`, like a local singleton. A control plane with its
|
|
7213
|
+
* own registration of the workflow applies its own `singleton` instead, and one older than this
|
|
7214
|
+
* field ignores it.
|
|
7215
|
+
*/
|
|
7216
|
+
singleton?: StartRunSingleton | undefined;
|
|
7217
|
+
}
|
|
7218
|
+
/** A singleton key the starter evaluated (see {@link StartRunMessage.singleton}). */
|
|
7219
|
+
interface StartRunSingleton {
|
|
7220
|
+
key: string;
|
|
7221
|
+
limit?: number | undefined;
|
|
7222
|
+
maxQueueDepth?: number | undefined;
|
|
7016
7223
|
}
|
|
7017
7224
|
/**
|
|
7018
7225
|
* A tenant worker → control plane read/control request over the shared transport. Enqueued on
|
|
@@ -7084,6 +7291,23 @@ type RunRequestKind = {
|
|
|
7084
7291
|
kind: 'signal';
|
|
7085
7292
|
token: string;
|
|
7086
7293
|
payload: unknown;
|
|
7294
|
+
opts?: SignalOptions | undefined;
|
|
7295
|
+
} | {
|
|
7296
|
+
kind: 'signalWithStart';
|
|
7297
|
+
start: Omit<StartRunMessage, 'tenant'> & {
|
|
7298
|
+
runId: string;
|
|
7299
|
+
};
|
|
7300
|
+
signal: {
|
|
7301
|
+
token: string;
|
|
7302
|
+
payload?: unknown;
|
|
7303
|
+
};
|
|
7304
|
+
} | {
|
|
7305
|
+
kind: 'publishEvent';
|
|
7306
|
+
name: string;
|
|
7307
|
+
payload: unknown;
|
|
7308
|
+
opts?: {
|
|
7309
|
+
id?: string;
|
|
7310
|
+
} | undefined;
|
|
7087
7311
|
} | {
|
|
7088
7312
|
kind: 'schedule';
|
|
7089
7313
|
id: string;
|
|
@@ -7207,6 +7431,39 @@ interface WorkflowTask {
|
|
|
7207
7431
|
*/
|
|
7208
7432
|
priority?: number | undefined;
|
|
7209
7433
|
attempt: number;
|
|
7434
|
+
/**
|
|
7435
|
+
* The workflow-decision features the control plane that dispatched this turn can apply — see
|
|
7436
|
+
* {@link REMOTE_WORKFLOW_FEATURES}. A worker checks it before emitting a command an older control
|
|
7437
|
+
* plane would not understand, and fails the turn with a clear error instead. Absent on a task from
|
|
7438
|
+
* a control plane that predates feature negotiation: only the original command kinds are safe.
|
|
7439
|
+
*/
|
|
7440
|
+
features?: string[] | undefined;
|
|
7441
|
+
}
|
|
7442
|
+
/**
|
|
7443
|
+
* The workflow-decision features this control plane applies, advertised on every {@link WorkflowTask}
|
|
7444
|
+
* it dispatches (`task.features`):
|
|
7445
|
+
* - `callPolicy` — a `call` command's `policy` (retries, backoff, liveness `timeoutMs`) is enforced;
|
|
7446
|
+
* - `sleepUntil`, `waitSignalTimeout`, `waitEvent`, `spawnChild`, `continueAsNew` — the command kinds
|
|
7447
|
+
* of the same names.
|
|
7448
|
+
* A worker must not emit a command (or a `call` policy) whose feature the task does not list.
|
|
7449
|
+
*/
|
|
7450
|
+
declare const REMOTE_WORKFLOW_FEATURES: readonly ["callPolicy", "sleepUntil", "waitSignalTimeout", "waitEvent", "spawnChild", "continueAsNew"];
|
|
7451
|
+
/** One of {@link REMOTE_WORKFLOW_FEATURES}. */
|
|
7452
|
+
type RemoteWorkflowFeature = (typeof REMOTE_WORKFLOW_FEATURES)[number];
|
|
7453
|
+
/**
|
|
7454
|
+
* The durable dispatch policy a remote `call` command carries (feature `callPolicy`): the same fields,
|
|
7455
|
+
* defaults and semantics as the in-process `ctx.step` policy ({@link StepOptions}) — `retries` is the
|
|
7456
|
+
* total number of attempts; without `timeoutMs` a failed attempt is re-dispatched after `backoff`
|
|
7457
|
+
* unless the worker marked the error non-retryable; with `timeoutMs` an attempt that returns no
|
|
7458
|
+
* result within the window is re-dispatched (up to `retries`) and a reported failure is final.
|
|
7459
|
+
*/
|
|
7460
|
+
interface RemoteCallPolicy {
|
|
7461
|
+
retries?: number | undefined;
|
|
7462
|
+
backoff?: BackoffStrategy | undefined;
|
|
7463
|
+
backoffMs?: number | undefined;
|
|
7464
|
+
backoffMaxMs?: number | undefined;
|
|
7465
|
+
jitter?: boolean | undefined;
|
|
7466
|
+
timeoutMs?: number | undefined;
|
|
7210
7467
|
}
|
|
7211
7468
|
/** One resolved durable op in a run's history — a superset of a completed {@link StepCheckpoint}. */
|
|
7212
7469
|
interface HistoryEvent {
|
|
@@ -7222,6 +7479,11 @@ interface HistoryEvent {
|
|
|
7222
7479
|
output?: unknown;
|
|
7223
7480
|
/** Set when the op resolved to a failure (e.g. a failed remote step the workflow may catch). */
|
|
7224
7481
|
error?: StepError | undefined;
|
|
7482
|
+
/**
|
|
7483
|
+
* For a `call`: how many times the step was dispatched. A worker applying a `call` policy reads it
|
|
7484
|
+
* to decide whether a failed attempt is retried (see {@link RemoteCallPolicy}).
|
|
7485
|
+
*/
|
|
7486
|
+
attempts?: number | undefined;
|
|
7225
7487
|
}
|
|
7226
7488
|
/** A decision the workflow function produced at a `seq` that was not yet in history. */
|
|
7227
7489
|
type WorkflowCommand =
|
|
@@ -7236,6 +7498,10 @@ type WorkflowCommand =
|
|
|
7236
7498
|
group: string;
|
|
7237
7499
|
input: unknown;
|
|
7238
7500
|
parallelGroup?: string;
|
|
7501
|
+
/** The step's durable dispatch policy (feature `callPolicy`). Re-sent on every turn the step is
|
|
7502
|
+
* not resolved, so whichever control-plane instance applies the turn enforces it. A failed
|
|
7503
|
+
* attempt the policy retries is re-emitted with it instead of raised. */
|
|
7504
|
+
policy?: RemoteCallPolicy;
|
|
7239
7505
|
}
|
|
7240
7506
|
/** `ctx.step(name, body)` — a LOCAL step the worker already ran this turn; the engine persists its
|
|
7241
7507
|
* result so replay returns it instead of re-running (durability for side-effectful work).
|
|
@@ -7262,12 +7528,59 @@ type WorkflowCommand =
|
|
|
7262
7528
|
seq: number;
|
|
7263
7529
|
ms: number;
|
|
7264
7530
|
}
|
|
7531
|
+
/** `ctx.sleepUntil(when)` — a durable timer to an absolute epoch-ms deadline (feature `sleepUntil`). */
|
|
7532
|
+
| {
|
|
7533
|
+
kind: 'sleepUntil';
|
|
7534
|
+
seq: number;
|
|
7535
|
+
until: number;
|
|
7536
|
+
}
|
|
7265
7537
|
/** `ctx.wait_signal(name)` — block until a signal `name` is delivered to the run. */
|
|
7266
7538
|
| {
|
|
7267
7539
|
kind: 'waitSignal';
|
|
7268
7540
|
seq: number;
|
|
7269
7541
|
signal: string;
|
|
7270
7542
|
}
|
|
7543
|
+
/** `ctx.waitForSignal(name, { timeoutMs })` (feature `waitSignalTimeout`): like the in-process ctx it
|
|
7544
|
+
* takes TWO positions — `deadlineSeq` for the deadline timer (stamped once, at `now + timeoutMs`
|
|
7545
|
+
* when first applied) and `seq` for the wait. Whichever resolves first shows in history: the signal
|
|
7546
|
+
* at `seq`, or a `timer` at `deadlineSeq`, which the worker raises as a `SignalTimeoutError`. */
|
|
7547
|
+
| {
|
|
7548
|
+
kind: 'waitSignalTimeout';
|
|
7549
|
+
seq: number;
|
|
7550
|
+
deadlineSeq: number;
|
|
7551
|
+
signal: string;
|
|
7552
|
+
timeoutMs: number;
|
|
7553
|
+
}
|
|
7554
|
+
/** `ctx.waitForEvent(name, { match, timeoutMs })` (feature `waitEvent`): wait for a named event
|
|
7555
|
+
* published with `engine.publishEvent`, buffered events included. Bounded like
|
|
7556
|
+
* `waitSignalTimeout` when `timeoutMs` is set (then `deadlineSeq` is the deadline's position). */
|
|
7557
|
+
| {
|
|
7558
|
+
kind: 'waitEvent';
|
|
7559
|
+
seq: number;
|
|
7560
|
+
name: string;
|
|
7561
|
+
match?: Record<string, unknown>;
|
|
7562
|
+
deadlineSeq?: number;
|
|
7563
|
+
timeoutMs?: number;
|
|
7564
|
+
}
|
|
7565
|
+
/** `ctx.startChild(workflow, input, opts)` (feature `spawnChild`): start a child run WITHOUT awaiting
|
|
7566
|
+
* it. The worker returns `childId` immediately and the turn goes on; the control plane starts the
|
|
7567
|
+
* child once (idempotent by id) and journals a `spawn:<childId>` step at `seq`. */
|
|
7568
|
+
| {
|
|
7569
|
+
kind: 'spawnChild';
|
|
7570
|
+
seq: number;
|
|
7571
|
+
workflow: string;
|
|
7572
|
+
input: unknown;
|
|
7573
|
+
childId: string;
|
|
7574
|
+
priority?: number;
|
|
7575
|
+
}
|
|
7576
|
+
/** `ctx.continueAsNew(input)` (feature `continueAsNew`): the LAST command of a turn. The control
|
|
7577
|
+
* plane completes this run and starts its continuation (`<runId>~N`) with `input`, as the
|
|
7578
|
+
* in-process engine does. `seq` is the position the body had reached (not consumed). */
|
|
7579
|
+
| {
|
|
7580
|
+
kind: 'continueAsNew';
|
|
7581
|
+
seq: number;
|
|
7582
|
+
input: unknown;
|
|
7583
|
+
}
|
|
7271
7584
|
/** `ctx.waitForAny(name, conditions)` — block until the first of `conditions` happens. The engine
|
|
7272
7585
|
* resolves it exactly as the in-process ctx does (see `wait-any.ts`), journals `{ key, value }` at
|
|
7273
7586
|
* `seq` and replays it as an `any` {@link HistoryEvent}. A timer's `ms` counts from when the engine
|
|
@@ -9546,6 +9859,24 @@ declare function runSchedules(engine: ScheduleTickEngine, schedules: readonly Sc
|
|
|
9546
9859
|
*/
|
|
9547
9860
|
type ScheduleTickEngine = Pick<WorkflowEngine, 'start' | 'getRun'> & Partial<Pick<WorkflowEngine, 'isDraining' | 'listRuns'>>;
|
|
9548
9861
|
|
|
9862
|
+
/**
|
|
9863
|
+
* The durable dispatch policy of a `ctx.step` call as a remote `call` command carries it: the
|
|
9864
|
+
* `@Step`-declared config, with a per-call `opts` field winning wherever it is set — the same merge
|
|
9865
|
+
* the in-process `ctx.step` applies. `undefined` when neither declares any policy field, so a call
|
|
9866
|
+
* without one stays wire-identical to a call from before policies were carried.
|
|
9867
|
+
*/
|
|
9868
|
+
declare function remoteCallPolicyOf(config: StepConfig | undefined, opts: StepDispatchOpts | undefined): RemoteCallPolicy | undefined;
|
|
9869
|
+
/** Total dispatch attempts a policy allows (`retries`, at least one) — the in-process rule. */
|
|
9870
|
+
declare function remoteCallMaxAttempts(policy: RemoteCallPolicy | undefined): number;
|
|
9871
|
+
/**
|
|
9872
|
+
* Whether a remote `call` whose attempt `attempts` FAILED with `error` is dispatched again under
|
|
9873
|
+
* `policy`, exactly as the in-process durable path decides it: never with a liveness `timeoutMs`
|
|
9874
|
+
* (there only a timeout is retried, a reported failure is final), never for an error the worker
|
|
9875
|
+
* marked non-retryable, and only while attempts remain. The worker's replay and the control plane
|
|
9876
|
+
* both decide with this one function, so they cannot disagree about a retry.
|
|
9877
|
+
*/
|
|
9878
|
+
declare function remoteCallRetries(policy: RemoteCallPolicy | undefined, attempts: number, error: StepError | undefined): boolean;
|
|
9879
|
+
|
|
9549
9880
|
/**
|
|
9550
9881
|
* A {@link StepLogger} that appends to `events`, stamping each line with `now()`. Shared by the
|
|
9551
9882
|
* local-step path (`ctx.step`) and the remote-worker path (`runStepHandler`) so a step records
|
|
@@ -10113,4 +10444,4 @@ declare function prevRRuleFireMs(rule: ParsedRRule, atMs: number): number | null
|
|
|
10113
10444
|
*/
|
|
10114
10445
|
declare function settleResultsWithPlainCalls(store: Pick<StateStore, 'getRun' | 'getCheckpoint'> & Partial<Pick<StateStore, 'getRuns' | 'getCheckpointsForSettle' | 'getCheckpoints' | 'settleCheckpointsIfPending'>>, results: StepResultSettlement[]): Promise<(StepCheckpoint | null)[]>;
|
|
10115
10446
|
|
|
10116
|
-
export { ACCUMULATOR_SEEN_MAX, ANNOUNCED_SCHEDULE_TAG, ANY_WAIT_GROUP, type AccumulatorHost, type AccumulatorStartOptions, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedSchedule, type AnnouncedScheduleSync, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type AttributedEngineEvent, 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, type ConsoleFederation, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_ANNOUNCED_SCHEDULE_GRACE_MS, 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, DuplicateDurableCopyError, type DurableCopy, 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, type EngineTenancy, 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, NO_LIVE_WORKER, 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 RunAppAttribution, RunAppStamper, type RunAppTopologyOptions, 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 RunTenant, 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, type ScheduleAction, ScheduleAlreadyExistsError, type ScheduleAnnouncement, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduleTickEngine, 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 TenantFilter, type TenantRow, 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, announcedScheduleId, announcementsOf, anyCheckpointName, applyAttributeQuery, assertConcurrency, assertRoutes, assertSingleDurableCopy, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, bufferedEventReaches, buildWorkflowDirectory, canRoute, capableWorkers, carriesLifecyclePending, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, coalescedSubscribersOf, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneAttribution, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, durableCopies, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, extendEtag, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, getRunsByIds, grantsClientTenant, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, hmacTenantVerifier, indexWaitersByRun, info, inheritTenant, 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, matchesTenantPredicates, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, nextRRuleFireMs, nextScheduleFireAt, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, owedSubscribersOf, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseLifecycleEvent, parseRRule, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, prevRRuleFireMs, queryCheckpointsOf, readBufferedEvent, readRunsByIds, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, resolveTenantToken, resolveWireTenant, retentionKeeps, retiredHandoffName, routeFor, rowTenant, runCompletedEvent, runDetailEtag, runDurableExecution, runFailedEvent, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runTraceId, runValueFacetsFromRuns, runWaitPrefix, runWaitTargetOf, runWaitToken, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, scopeBufferedEvent, scopeTenantQuery, sealDurableCopies, settleResultsWithPlainCalls, signTenantToken, singletonAdmissionDenialPatch, singletonAdmissionTags, singletonClaimantIds, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantAppOf, tenantGroup, tenantIdsFor, tenantVisible, toEventSubscription, traceIdOfTraceparent, triggerFailedSubscribersOf, triggeredRunsOf, triggeredSubscribersOf, useDurableExecution, verifyWireTenant, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };
|
|
10447
|
+
export { ACCUMULATOR_SEEN_MAX, ANNOUNCED_SCHEDULE_TAG, ANY_WAIT_GROUP, type AccumulatorHost, type AccumulatorStartOptions, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedSchedule, type AnnouncedScheduleSync, type AnnouncedWorkflow, type AnnouncedWorkflowOptions, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type AttributedEngineEvent, 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, type ConsoleFederation, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_ANNOUNCED_SCHEDULE_GRACE_MS, 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, DuplicateDurableCopyError, type DurableCopy, 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, type EngineTenancy, 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, NO_LIVE_WORKER, 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, REMOTE_WORKFLOW_FEATURES, RUN_HISTORY_FIXTURE_VERSION, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, RUN_WAIT_TOKEN_PREFIX, type RawWorkerDescriptor, type RemoteCallPolicy, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, type RemoteWorkflowFeature, RemoteWorkflowTimeout, type RepublishLifecycleResult, type RepublishLifecycleTarget, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAppAttribution, RunAppStamper, type RunAppTopologyOptions, 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 RunTenant, 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, type ScheduleAction, ScheduleAlreadyExistsError, type ScheduleAnnouncement, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduleTickEngine, 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 StartRunSingleton, 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 TenantFilter, type TenantRow, 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, announcedScheduleId, announcementsOf, anyCheckpointName, applyAttributeQuery, assertConcurrency, assertRoutes, assertSingleDurableCopy, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, bufferedEventReaches, buildWorkflowDirectory, canRoute, capableWorkers, carriesLifecyclePending, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, coalescedSubscribersOf, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneAttribution, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, durableCopies, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, extendEtag, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, getRunsByIds, grantsClientTenant, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, hmacTenantVerifier, indexWaitersByRun, info, inheritTenant, 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, matchesTenantPredicates, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, nextRRuleFireMs, nextScheduleFireAt, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, owedSubscribersOf, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseLifecycleEvent, parseRRule, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, prevRRuleFireMs, queryCheckpointsOf, readBufferedEvent, readRunsByIds, readSearchAttributes, remoteCallMaxAttempts, remoteCallPolicyOf, remoteCallRetries, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, resolveTenantToken, resolveWireTenant, retentionKeeps, retiredHandoffName, routeFor, rowTenant, runCompletedEvent, runDetailEtag, runDurableExecution, runFailedEvent, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runTraceId, runValueFacetsFromRuns, runWaitPrefix, runWaitTargetOf, runWaitToken, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, scopeBufferedEvent, scopeTenantQuery, sealDurableCopies, settleResultsWithPlainCalls, signTenantToken, singletonAdmissionDenialPatch, singletonAdmissionTags, singletonClaimantIds, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantAppOf, tenantGroup, tenantIdsFor, tenantVisible, toEventSubscription, traceIdOfTraceparent, triggerFailedSubscribersOf, triggeredRunsOf, triggeredSubscribersOf, useDurableExecution, verifyWireTenant, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };
|