@dudousxd/nestjs-durable 0.52.7 → 0.54.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 +527 -46
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +185 -26
- package/dist/index.d.ts +185 -26
- package/dist/index.js +523 -54
- package/dist/index.js.map +1 -1
- package/package.json +6 -6
- package/skills/durable-signals-and-timers/SKILL.md +4 -2
package/dist/index.d.cts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, TenantVerifier, TenantTokenSource, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, StepInvocation, TenantEvent } from '@dudousxd/nestjs-durable-core';
|
|
2
|
-
export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, TenantTokenSource, TenantVerifier, VerifiedTenant, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, hmacTenantVerifier, prevCronFireMs, readSearchAttributes, runSchedules, scheduleRunIdAt, scheduledRunId, signTenantToken } from '@dudousxd/nestjs-durable-core';
|
|
1
|
+
import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnEventEntry, OnErrorInput, LifecycleEventOf, WorkflowLifecycleEvent, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, EventBatchConfig, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, TenantVerifier, TenantTokenSource, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, RepublishLifecycleTarget, RepublishLifecycleResult, WorkflowLifecycleLinks, EngineEvent, StepInvocation, LifecycleKind, TenantEvent } from '@dudousxd/nestjs-durable-core';
|
|
2
|
+
export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, EventSubscription, InferSearchAttributes, LIFECYCLE_PENDING_TAG, LifecycleEventOf, LifecycleKind, OnErrorInput, OnEventEntry, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, TenantTokenSource, TenantVerifier, VerifiedTenant, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowLifecycleEvent, WorkflowRun, hmacTenantVerifier, lifecycleRunId, lifecycleSourceOf, prevCronFireMs, readSearchAttributes, runCompletedEvent, runFailedEvent, runSchedules, scheduleRunIdAt, scheduledRunId, signTenantToken, triggeredRunsOf } from '@dudousxd/nestjs-durable-core';
|
|
3
3
|
import { z } from 'zod';
|
|
4
4
|
import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
|
|
5
5
|
import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
|
|
@@ -141,8 +141,8 @@ interface WorkflowMeta {
|
|
|
141
141
|
validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
|
|
142
142
|
/** Typed/validated `searchAttributes` shape. See `WorkflowOptions`. */
|
|
143
143
|
searchAttributes?: SearchAttributesSchema | undefined;
|
|
144
|
-
/**
|
|
145
|
-
onEvent?:
|
|
144
|
+
/** Events that start a fresh run of this workflow. See `WorkflowOptions`. */
|
|
145
|
+
onEvent?: OnEventEntry[] | undefined;
|
|
146
146
|
/** Debounce `onEvent` triggers — fire once it's quiet for this long. See `WorkflowOptions`. */
|
|
147
147
|
debounce?: string | number | undefined;
|
|
148
148
|
/** Batch `onEvent` triggers — fire on size or window. See `WorkflowOptions`. */
|
|
@@ -277,9 +277,10 @@ interface WorkflowOptions {
|
|
|
277
277
|
* Start a fresh run of this workflow whenever any of these events is published via
|
|
278
278
|
* `publishEvent(name, payload)` — the payload becomes the run's input. e.g.
|
|
279
279
|
* `onEvent: ['user.registered', 'user.invited']`. The same subscription can also be declared with
|
|
280
|
-
* the `@OnDurableEvent(...)` class decorator; the two are merged.
|
|
280
|
+
* the `@OnDurableEvent(...)` class decorator; the two are merged. An entry can also be
|
|
281
|
+
* `{ event, where }`, where `where(payload)` decides per event whether this workflow starts.
|
|
281
282
|
*/
|
|
282
|
-
onEvent?:
|
|
283
|
+
onEvent?: OnEventEntry[];
|
|
283
284
|
/**
|
|
284
285
|
* Coalesce `onEvent` triggers by **debouncing** — start one run only once events have been quiet
|
|
285
286
|
* for this long (resets on each event), with the LAST payload. e.g. `debounce: '30s'`.
|
|
@@ -458,11 +459,121 @@ declare const ON_EVENT_METADATA: unique symbol;
|
|
|
458
459
|
* Named "durable" on purpose: `@nestjs/event-emitter` exports an `@OnEvent` decorator, and in an
|
|
459
460
|
* app using both libs an auto-import picking the wrong one fails silently in either direction.
|
|
460
461
|
*/
|
|
461
|
-
declare function OnDurableEvent(...events:
|
|
462
|
+
declare function OnDurableEvent(...events: OnEventEntry[]): ClassDecorator;
|
|
463
|
+
/**
|
|
464
|
+
* Coalesce a subscriber's triggers by **debouncing**: start it once events have been quiet for
|
|
465
|
+
* `windowMs`, with the last one. `key` splits that per key: it receives the subscriber's input (what
|
|
466
|
+
* `input` builds), and each distinct key debounces on its own.
|
|
467
|
+
*/
|
|
468
|
+
interface SubscriberDebounce<TRunInput> {
|
|
469
|
+
windowMs: number | string;
|
|
470
|
+
key?: ((input: TRunInput) => string) | undefined;
|
|
471
|
+
}
|
|
472
|
+
/**
|
|
473
|
+
* Coalesce a subscriber's triggers by **batching**: start it with `{ events }` once `maxSize` arrive
|
|
474
|
+
* or `windowMs` passes since the first. `key` batches each distinct key on its own.
|
|
475
|
+
*/
|
|
476
|
+
interface SubscriberBatch<TRunInput> {
|
|
477
|
+
maxSize: number;
|
|
478
|
+
windowMs: number | string;
|
|
479
|
+
key?: ((input: TRunInput) => string) | undefined;
|
|
480
|
+
}
|
|
481
|
+
/** Options for {@link OnWorkflowCompleted} / {@link OnWorkflowFailed}. */
|
|
482
|
+
interface OnWorkflowSettledOptions<TEvent, TRunInput> {
|
|
483
|
+
/** Start only for the settled runs this returns true for, e.g. by `input` or `searchAttributes`. */
|
|
484
|
+
where?: ((event: TEvent) => boolean) | undefined;
|
|
485
|
+
/**
|
|
486
|
+
* The started run's input, built from the event. Without it the run receives the
|
|
487
|
+
* {@link WorkflowLifecycleEvent} itself. Lets an existing workflow subscribe with its own input
|
|
488
|
+
* shape, and keeps the settled run's whole input and output out of the new run's row.
|
|
489
|
+
*/
|
|
490
|
+
input?: ((event: TEvent) => TRunInput) | undefined;
|
|
491
|
+
/**
|
|
492
|
+
* Debounce this workflow's triggers (see {@link SubscriberDebounce}). Sets the workflow's
|
|
493
|
+
* `onEvent` coalescing, so it applies to every event it subscribes to; a different `debounce` or
|
|
494
|
+
* `batch` already declared on it fails at registration. Not with `batch`.
|
|
495
|
+
*/
|
|
496
|
+
debounce?: SubscriberDebounce<TRunInput> | undefined;
|
|
497
|
+
/**
|
|
498
|
+
* Batch this workflow's triggers (see {@link SubscriberBatch}); the run's input becomes
|
|
499
|
+
* `{ events: TRunInput[] }`. Same scope and conflicts as `debounce`. Not with `debounce`.
|
|
500
|
+
*/
|
|
501
|
+
batch?: SubscriberBatch<TRunInput> | undefined;
|
|
502
|
+
}
|
|
503
|
+
/** Options for {@link OnWorkflowFailed}: also which endings start the subscriber. */
|
|
504
|
+
interface OnWorkflowFailedOptions<TEvent, TRunInput> extends OnWorkflowSettledOptions<TEvent, TRunInput> {
|
|
505
|
+
/** The endings that start it. Defaults to all three: `failed`, `cancelled` and `dead`. */
|
|
506
|
+
statuses?: Array<'failed' | 'cancelled' | 'dead'> | undefined;
|
|
507
|
+
}
|
|
508
|
+
/** `O` with a required `batch` (and no `debounce`): the overload whose subscriber takes `{ events }`. */
|
|
509
|
+
type Batched<O, TRunInput> = O & {
|
|
510
|
+
batch: SubscriberBatch<TRunInput>;
|
|
511
|
+
debounce?: undefined;
|
|
512
|
+
};
|
|
513
|
+
/** `O` without `batch`: the overload whose subscriber takes `TRunInput` itself. */
|
|
514
|
+
type Unbatched<O> = O & {
|
|
515
|
+
batch?: undefined;
|
|
516
|
+
};
|
|
517
|
+
/**
|
|
518
|
+
* A class decorator that only accepts a workflow whose `run(ctx, input)` takes `TRunInput`, so a
|
|
519
|
+
* subscriber with the wrong input shape fails to compile instead of failing at runtime.
|
|
520
|
+
*/
|
|
521
|
+
type SubscriberDecorator<TRunInput> = <T extends abstract new (...args: never[]) => {
|
|
522
|
+
run: (ctx: never, input: TRunInput) => unknown;
|
|
523
|
+
}>(target: T) => void;
|
|
524
|
+
/**
|
|
525
|
+
* Start a fresh run of the decorated workflow whenever a run of `workflow` **completes**. The new
|
|
526
|
+
* run's input is the {@link WorkflowLifecycleEvent} (run id, input, output, tags, search
|
|
527
|
+
* attributes), or what `input` builds from it. The settling workflow does not know about its
|
|
528
|
+
* subscribers. Exactly once per settled run: see `runCompletedEvent` in
|
|
529
|
+
* `@dudousxd/nestjs-durable-core`.
|
|
530
|
+
*
|
|
531
|
+
* With a class ref, the decorated workflow's `run` input is type-checked against the event (or
|
|
532
|
+
* against `input`'s return type, or `{ events }` of it with `batch`). Child runs publish too, so a
|
|
533
|
+
* workflow that `etl` starts as a child also starts its subscribers.
|
|
534
|
+
*
|
|
535
|
+
* ```ts
|
|
536
|
+
* @Workflow({ name: 'refresh-summaries' })
|
|
537
|
+
* @OnWorkflowCompleted(IngestionWorkflow, {
|
|
538
|
+
* where: (e) => e.input.type === 'mvr',
|
|
539
|
+
* input: (e) => ({ baseId: e.input.baseId }),
|
|
540
|
+
* debounce: { windowMs: '30s', key: (input) => input.baseId },
|
|
541
|
+
* })
|
|
542
|
+
* class RefreshSummariesWorkflow {
|
|
543
|
+
* async run(ctx: WorkflowCtx, input: { baseId: string }) {}
|
|
544
|
+
* }
|
|
545
|
+
* ```
|
|
546
|
+
*/
|
|
547
|
+
declare function OnWorkflowCompleted<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options: Batched<OnWorkflowSettledOptions<LifecycleEventOf<C>, TRunInput>, TRunInput>): SubscriberDecorator<{
|
|
548
|
+
events: TRunInput[];
|
|
549
|
+
}>;
|
|
550
|
+
declare function OnWorkflowCompleted<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options?: Unbatched<OnWorkflowSettledOptions<LifecycleEventOf<C>, TRunInput>>): SubscriberDecorator<TRunInput>;
|
|
551
|
+
declare function OnWorkflowCompleted(workflow: string, options?: OnWorkflowSettledOptions<WorkflowLifecycleEvent, unknown>): ClassDecorator;
|
|
552
|
+
/**
|
|
553
|
+
* Start a fresh run of the decorated workflow whenever a run of `workflow` ends **failed,
|
|
554
|
+
* cancelled or dead** (narrow it with `statuses`). Same contract as {@link OnWorkflowCompleted};
|
|
555
|
+
* the event carries `error` and `status` instead of `output`.
|
|
556
|
+
*/
|
|
557
|
+
declare function OnWorkflowFailed<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options: Batched<OnWorkflowFailedOptions<LifecycleEventOf<C>, TRunInput>, TRunInput>): SubscriberDecorator<{
|
|
558
|
+
events: TRunInput[];
|
|
559
|
+
}>;
|
|
560
|
+
declare function OnWorkflowFailed<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options?: Unbatched<OnWorkflowFailedOptions<LifecycleEventOf<C>, TRunInput>>): SubscriberDecorator<TRunInput>;
|
|
561
|
+
declare function OnWorkflowFailed(workflow: string, options?: OnWorkflowFailedOptions<WorkflowLifecycleEvent, unknown>): ClassDecorator;
|
|
562
|
+
/** Metadata key for the `onEvent` coalescing `@OnWorkflowCompleted` / `@OnWorkflowFailed` declare. */
|
|
563
|
+
declare const ON_EVENT_BATCH_METADATA: unique symbol;
|
|
564
|
+
/**
|
|
565
|
+
* How a workflow coalesces its `onEvent` triggers: `@Workflow({ debounce | batch })`, or what its
|
|
566
|
+
* `@OnWorkflowCompleted` / `@OnWorkflowFailed` declare. Throws when both are set and differ, so a
|
|
567
|
+
* workflow never silently coalesces one way while its decorator says another.
|
|
568
|
+
*/
|
|
569
|
+
declare function eventBatchOf(meta: WorkflowMeta, target: object): EventBatchConfig | undefined;
|
|
462
570
|
/** @deprecated Renamed to `OnDurableEvent` — this alias clashes with `@nestjs/event-emitter`'s `@OnEvent` and will be removed in the next minor. */
|
|
463
571
|
declare const OnEvent: typeof OnDurableEvent;
|
|
464
|
-
/**
|
|
465
|
-
|
|
572
|
+
/**
|
|
573
|
+
* All events a workflow class subscribes to: `@Workflow({ onEvent })`, `@OnDurableEvent`,
|
|
574
|
+
* `@OnWorkflowCompleted` and `@OnWorkflowFailed`. Repeated bare names collapse to one.
|
|
575
|
+
*/
|
|
576
|
+
declare function getOnEvents(meta: WorkflowMeta, target: object): OnEventEntry[];
|
|
466
577
|
|
|
467
578
|
/**
|
|
468
579
|
* Retention config for the {@link RetentionPoller}. One or more {@link RetentionPolicy policies}
|
|
@@ -563,6 +674,11 @@ interface DurableModuleOptions {
|
|
|
563
674
|
* (a poison pill that crashes the process every boot). Omit for unlimited. Operator only.
|
|
564
675
|
*/
|
|
565
676
|
maxRecoveryAttempts?: number;
|
|
677
|
+
/**
|
|
678
|
+
* How long (ms) a run may stay unresumable because its workflow version is registered nowhere (a
|
|
679
|
+
* renamed or deleted workflow) before it is dead-lettered. Default 24h; `0` skips it forever.
|
|
680
|
+
*/
|
|
681
|
+
unregisteredWorkflowGraceMs?: number;
|
|
566
682
|
/**
|
|
567
683
|
* Opt-in liveness deadline (ms) for a remote (polyglot) workflow `advance`. If the worker neither
|
|
568
684
|
* returns a decision nor sends a run-scoped heartbeat within this window, the engine presumes it dead
|
|
@@ -1104,6 +1220,10 @@ declare function inAppWorkerProviders(): Provider[];
|
|
|
1104
1220
|
* responders reply `ok: true` with no `data` instead; `ProxyRunGateway` reads both.
|
|
1105
1221
|
*/
|
|
1106
1222
|
declare const UNSUPPORTED_RUN_REQUEST = "unsupported-request";
|
|
1223
|
+
/** The error `code` a responder replies with for a request it rejects as malformed or not allowed. */
|
|
1224
|
+
declare const BAD_RUN_REQUEST = "bad-request";
|
|
1225
|
+
/** The most settled runs one tenant republish reads; a larger `limit` is lowered to it. */
|
|
1226
|
+
declare const TENANT_REPUBLISH_MAX_LIMIT = 1000;
|
|
1107
1227
|
/** The narrow slice of `Transport` the responder needs — a tenant's read/control request in, a
|
|
1108
1228
|
* correlated reply out. Both are OPTIONAL on the full `Transport` interface (only broker
|
|
1109
1229
|
* transports carry the run-request/reply protocol); the caller capability-checks before wiring
|
|
@@ -1128,20 +1248,6 @@ interface RunRequestResponderOptions {
|
|
|
1128
1248
|
*/
|
|
1129
1249
|
warnWithoutVerifier?: boolean | undefined;
|
|
1130
1250
|
}
|
|
1131
|
-
/**
|
|
1132
|
-
* Operator-side consumer of a tenant's {@link RunRequest}s: answers each one against a
|
|
1133
|
-
* `RunGateway`, enforcing the tenant boundary before touching the run. For every runId-bearing
|
|
1134
|
-
* verb it loads the run via `getRunDetail` FIRST and compares `run.namespace` to the requesting
|
|
1135
|
-
* `msg.tenant` — a mismatch short-circuits into a `cross-tenant` error reply WITHOUT calling the
|
|
1136
|
-
* verb, so a tenant can never read or act on another tenant's run. `listRuns` is scoped by
|
|
1137
|
-
* overwriting the query's `namespace` with the requester's tenant, ignoring whatever the client
|
|
1138
|
-
* sent. This is the security boundary of the tenant run gateway — do not weaken it.
|
|
1139
|
-
*
|
|
1140
|
-
* With {@link RunRequestResponderOptions.verifyTenant}, every request is authenticated FIRST: the
|
|
1141
|
-
* wire `tenant` is treated as a signed token, the real tenant is derived from it, and an invalid
|
|
1142
|
-
* token short-circuits into an `unauthorized` error reply before any run is touched. A verifier
|
|
1143
|
-
* that throws becomes an error reply too.
|
|
1144
|
-
*/
|
|
1145
1251
|
declare class RunRequestResponder {
|
|
1146
1252
|
private readonly transport;
|
|
1147
1253
|
private readonly gateway;
|
|
@@ -1151,20 +1257,34 @@ declare class RunRequestResponder {
|
|
|
1151
1257
|
* failure never throws back into the transport (errors are captured into an error reply). */
|
|
1152
1258
|
start(): void;
|
|
1153
1259
|
private handle;
|
|
1260
|
+
/**
|
|
1261
|
+
* `detail` scoped to `tenant` (see {@link scopeRunLinks}), with its lifecycle links
|
|
1262
|
+
* (`workflowLifecycle`, `lifecycleSubscribers`) narrowed to the subscriptions of `tenant`'s
|
|
1263
|
+
* namespace, as the `workflowLifecycle` verb answers them.
|
|
1264
|
+
*/
|
|
1265
|
+
private scopeLifecycle;
|
|
1266
|
+
/**
|
|
1267
|
+
* Why a tenant republish naming `subscriber` is refused, or undefined when it may go ahead: the
|
|
1268
|
+
* subscriber must be owed the event of `workflow` settling (as `kind`, when given) by a run of
|
|
1269
|
+
* the tenant's namespace (the gateway's `lifecycleSubscribers`, else the tenant's
|
|
1270
|
+
* `workflowLifecycle` links), so a tenant cannot have the event owed to an arbitrary name. Without
|
|
1271
|
+
* `subscriber` there is nothing to check.
|
|
1272
|
+
*/
|
|
1273
|
+
private refuseSubscriber;
|
|
1154
1274
|
private callVerb;
|
|
1155
1275
|
}
|
|
1156
1276
|
|
|
1157
1277
|
/**
|
|
1158
1278
|
* An error reply from the control plane. `code` carries the reply's machine-readable reason when it
|
|
1159
1279
|
* sent one — `unauthorized` (the tenant token was rejected), `cross-tenant` (the run belongs to
|
|
1160
|
-
* another tenant), ... — so a caller can tell an authentication failure from a real one, as with
|
|
1280
|
+
* another tenant), `bad-request` (the request was malformed or not allowed), ... — so a caller can tell an authentication failure from a real one, as with
|
|
1161
1281
|
* Agora's proxy.
|
|
1162
1282
|
*/
|
|
1163
1283
|
/**
|
|
1164
1284
|
* The codes the run-request responder replies with. `string & {}` keeps a code from a newer control
|
|
1165
1285
|
* plane assignable without losing autocomplete on the known ones.
|
|
1166
1286
|
*/
|
|
1167
|
-
type RunGatewayErrorCode = 'unauthorized' | 'cross-tenant' | typeof UNSUPPORTED_RUN_REQUEST | (string & {});
|
|
1287
|
+
type RunGatewayErrorCode = 'unauthorized' | 'cross-tenant' | typeof BAD_RUN_REQUEST | typeof UNSUPPORTED_RUN_REQUEST | (string & {});
|
|
1168
1288
|
declare class RunGatewayError extends Error {
|
|
1169
1289
|
readonly code: RunGatewayErrorCode | undefined;
|
|
1170
1290
|
constructor(message: string, code?: RunGatewayErrorCode);
|
|
@@ -1246,6 +1366,20 @@ declare class ProxyRunGateway implements RunGateway {
|
|
|
1246
1366
|
redispatchPending(runId: string): Promise<(RunResult & {
|
|
1247
1367
|
redispatched: number;
|
|
1248
1368
|
}) | null>;
|
|
1369
|
+
/**
|
|
1370
|
+
* Republished on the control plane: a one-run target is checked against this tenant like
|
|
1371
|
+
* `retry`, a by-workflow one is read over this tenant's namespace only. A control plane too old to
|
|
1372
|
+
* know the verb fails it with an {@link UNSUPPORTED_RUN_REQUEST} error rather than a timeout.
|
|
1373
|
+
*/
|
|
1374
|
+
republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
|
|
1375
|
+
/** Answered by the control plane's engine; same version-skew error as {@link republishLifecycle}. */
|
|
1376
|
+
workflowLifecycle(workflow: string): Promise<WorkflowLifecycleLinks>;
|
|
1377
|
+
/**
|
|
1378
|
+
* A verb with no fallback on an older control plane: its unsupported-request error, or the empty
|
|
1379
|
+
* `ok: true` reply the oldest responders send for an unknown verb, becomes a
|
|
1380
|
+
* {@link RunGatewayError} with code {@link UNSUPPORTED_RUN_REQUEST}.
|
|
1381
|
+
*/
|
|
1382
|
+
private requestNewVerb;
|
|
1249
1383
|
subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
|
|
1250
1384
|
}
|
|
1251
1385
|
|
|
@@ -1294,6 +1428,18 @@ declare class StoreRunGateway implements RunGateway {
|
|
|
1294
1428
|
constructor(store: StateStore, engine: WorkflowEngine);
|
|
1295
1429
|
topology(): DurableTopology;
|
|
1296
1430
|
getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
|
|
1431
|
+
/**
|
|
1432
|
+
* What a run detail reads beyond the run row and its checkpoints: what this run's settling
|
|
1433
|
+
* started, the subscribers its lifecycle event goes to (of its namespace) and where it stands for
|
|
1434
|
+
* each, what started it, its workflow's lifecycle links, and the `ctx.waitForRun` waits on either
|
|
1435
|
+
* side of it with the other run's status. A few reads per detail: the run's own waiters while it
|
|
1436
|
+
* is suspended, the waiters on it (one prefix read), and one batched read of every linked run.
|
|
1437
|
+
*/
|
|
1438
|
+
private lifecycleLinks;
|
|
1439
|
+
workflowLifecycle(workflow: string, opts?: {
|
|
1440
|
+
namespace?: string | undefined;
|
|
1441
|
+
}): Promise<WorkflowLifecycleLinks>;
|
|
1442
|
+
lifecycleSubscribers(workflow: string, kind: LifecycleKind, namespace: string): Promise<string[]>;
|
|
1297
1443
|
getRun(runId: string): Promise<WorkflowRun | null>;
|
|
1298
1444
|
getFanMembers(runId: string, group: string, query: FanPageQuery): Promise<FanPage | null>;
|
|
1299
1445
|
listRuns(query: RunQuery): Promise<RunListItem[]>;
|
|
@@ -1338,6 +1484,7 @@ declare class StoreRunGateway implements RunGateway {
|
|
|
1338
1484
|
redispatchPending(runId: string): Promise<(RunResult & {
|
|
1339
1485
|
redispatched: number;
|
|
1340
1486
|
}) | null>;
|
|
1487
|
+
republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
|
|
1341
1488
|
subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
|
|
1342
1489
|
}
|
|
1343
1490
|
|
|
@@ -1452,6 +1599,18 @@ declare class WorkflowService {
|
|
|
1452
1599
|
id?: string;
|
|
1453
1600
|
buffer?: boolean;
|
|
1454
1601
|
}): Promise<number>;
|
|
1602
|
+
/**
|
|
1603
|
+
* The runs started by `runId` settling, through `@OnWorkflowCompleted` / `@OnWorkflowFailed` (or
|
|
1604
|
+
* an `onEvent` on `runCompletedEvent(...)`). Only subscribers registered on this engine are
|
|
1605
|
+
* considered. For the reverse link, `lifecycleSourceOf(run)` reads it from the run itself.
|
|
1606
|
+
*/
|
|
1607
|
+
triggeredRuns(runId: string): Promise<string[]>;
|
|
1608
|
+
/**
|
|
1609
|
+
* Publish settled runs' lifecycle events again: to a subscriber registered after they settled, or
|
|
1610
|
+
* one restricted by `subscriber`. Subscribers already started for a run are not started again.
|
|
1611
|
+
* See `WorkflowEngine.republishLifecycle`.
|
|
1612
|
+
*/
|
|
1613
|
+
republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
|
|
1455
1614
|
}
|
|
1456
1615
|
|
|
1457
|
-
export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, RunGatewayError, type RunGatewayErrorCode, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestResponderOptions, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };
|
|
1616
|
+
export { BAD_RUN_REQUEST, CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_BATCH_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, OnWorkflowCompleted, OnWorkflowFailed, type OnWorkflowFailedOptions, type OnWorkflowSettledOptions, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, RunGatewayError, type RunGatewayErrorCode, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestResponderOptions, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, type SubscriberBatch, type SubscriberDebounce, type SubscriberDecorator, TENANT_REPUBLISH_MAX_LIMIT, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, eventBatchOf, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, TenantVerifier, TenantTokenSource, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, StepInvocation, TenantEvent } from '@dudousxd/nestjs-durable-core';
|
|
2
|
-
export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, TenantTokenSource, TenantVerifier, VerifiedTenant, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, hmacTenantVerifier, prevCronFireMs, readSearchAttributes, runSchedules, scheduleRunIdAt, scheduledRunId, signTenantToken } from '@dudousxd/nestjs-durable-core';
|
|
1
|
+
import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnEventEntry, OnErrorInput, LifecycleEventOf, WorkflowLifecycleEvent, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, EventBatchConfig, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, TenantVerifier, TenantTokenSource, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, RepublishLifecycleTarget, RepublishLifecycleResult, WorkflowLifecycleLinks, EngineEvent, StepInvocation, LifecycleKind, TenantEvent } from '@dudousxd/nestjs-durable-core';
|
|
2
|
+
export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, EventSubscription, InferSearchAttributes, LIFECYCLE_PENDING_TAG, LifecycleEventOf, LifecycleKind, OnErrorInput, OnEventEntry, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, TenantTokenSource, TenantVerifier, VerifiedTenant, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowLifecycleEvent, WorkflowRun, hmacTenantVerifier, lifecycleRunId, lifecycleSourceOf, prevCronFireMs, readSearchAttributes, runCompletedEvent, runFailedEvent, runSchedules, scheduleRunIdAt, scheduledRunId, signTenantToken, triggeredRunsOf } from '@dudousxd/nestjs-durable-core';
|
|
3
3
|
import { z } from 'zod';
|
|
4
4
|
import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
|
|
5
5
|
import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
|
|
@@ -141,8 +141,8 @@ interface WorkflowMeta {
|
|
|
141
141
|
validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
|
|
142
142
|
/** Typed/validated `searchAttributes` shape. See `WorkflowOptions`. */
|
|
143
143
|
searchAttributes?: SearchAttributesSchema | undefined;
|
|
144
|
-
/**
|
|
145
|
-
onEvent?:
|
|
144
|
+
/** Events that start a fresh run of this workflow. See `WorkflowOptions`. */
|
|
145
|
+
onEvent?: OnEventEntry[] | undefined;
|
|
146
146
|
/** Debounce `onEvent` triggers — fire once it's quiet for this long. See `WorkflowOptions`. */
|
|
147
147
|
debounce?: string | number | undefined;
|
|
148
148
|
/** Batch `onEvent` triggers — fire on size or window. See `WorkflowOptions`. */
|
|
@@ -277,9 +277,10 @@ interface WorkflowOptions {
|
|
|
277
277
|
* Start a fresh run of this workflow whenever any of these events is published via
|
|
278
278
|
* `publishEvent(name, payload)` — the payload becomes the run's input. e.g.
|
|
279
279
|
* `onEvent: ['user.registered', 'user.invited']`. The same subscription can also be declared with
|
|
280
|
-
* the `@OnDurableEvent(...)` class decorator; the two are merged.
|
|
280
|
+
* the `@OnDurableEvent(...)` class decorator; the two are merged. An entry can also be
|
|
281
|
+
* `{ event, where }`, where `where(payload)` decides per event whether this workflow starts.
|
|
281
282
|
*/
|
|
282
|
-
onEvent?:
|
|
283
|
+
onEvent?: OnEventEntry[];
|
|
283
284
|
/**
|
|
284
285
|
* Coalesce `onEvent` triggers by **debouncing** — start one run only once events have been quiet
|
|
285
286
|
* for this long (resets on each event), with the LAST payload. e.g. `debounce: '30s'`.
|
|
@@ -458,11 +459,121 @@ declare const ON_EVENT_METADATA: unique symbol;
|
|
|
458
459
|
* Named "durable" on purpose: `@nestjs/event-emitter` exports an `@OnEvent` decorator, and in an
|
|
459
460
|
* app using both libs an auto-import picking the wrong one fails silently in either direction.
|
|
460
461
|
*/
|
|
461
|
-
declare function OnDurableEvent(...events:
|
|
462
|
+
declare function OnDurableEvent(...events: OnEventEntry[]): ClassDecorator;
|
|
463
|
+
/**
|
|
464
|
+
* Coalesce a subscriber's triggers by **debouncing**: start it once events have been quiet for
|
|
465
|
+
* `windowMs`, with the last one. `key` splits that per key: it receives the subscriber's input (what
|
|
466
|
+
* `input` builds), and each distinct key debounces on its own.
|
|
467
|
+
*/
|
|
468
|
+
interface SubscriberDebounce<TRunInput> {
|
|
469
|
+
windowMs: number | string;
|
|
470
|
+
key?: ((input: TRunInput) => string) | undefined;
|
|
471
|
+
}
|
|
472
|
+
/**
|
|
473
|
+
* Coalesce a subscriber's triggers by **batching**: start it with `{ events }` once `maxSize` arrive
|
|
474
|
+
* or `windowMs` passes since the first. `key` batches each distinct key on its own.
|
|
475
|
+
*/
|
|
476
|
+
interface SubscriberBatch<TRunInput> {
|
|
477
|
+
maxSize: number;
|
|
478
|
+
windowMs: number | string;
|
|
479
|
+
key?: ((input: TRunInput) => string) | undefined;
|
|
480
|
+
}
|
|
481
|
+
/** Options for {@link OnWorkflowCompleted} / {@link OnWorkflowFailed}. */
|
|
482
|
+
interface OnWorkflowSettledOptions<TEvent, TRunInput> {
|
|
483
|
+
/** Start only for the settled runs this returns true for, e.g. by `input` or `searchAttributes`. */
|
|
484
|
+
where?: ((event: TEvent) => boolean) | undefined;
|
|
485
|
+
/**
|
|
486
|
+
* The started run's input, built from the event. Without it the run receives the
|
|
487
|
+
* {@link WorkflowLifecycleEvent} itself. Lets an existing workflow subscribe with its own input
|
|
488
|
+
* shape, and keeps the settled run's whole input and output out of the new run's row.
|
|
489
|
+
*/
|
|
490
|
+
input?: ((event: TEvent) => TRunInput) | undefined;
|
|
491
|
+
/**
|
|
492
|
+
* Debounce this workflow's triggers (see {@link SubscriberDebounce}). Sets the workflow's
|
|
493
|
+
* `onEvent` coalescing, so it applies to every event it subscribes to; a different `debounce` or
|
|
494
|
+
* `batch` already declared on it fails at registration. Not with `batch`.
|
|
495
|
+
*/
|
|
496
|
+
debounce?: SubscriberDebounce<TRunInput> | undefined;
|
|
497
|
+
/**
|
|
498
|
+
* Batch this workflow's triggers (see {@link SubscriberBatch}); the run's input becomes
|
|
499
|
+
* `{ events: TRunInput[] }`. Same scope and conflicts as `debounce`. Not with `debounce`.
|
|
500
|
+
*/
|
|
501
|
+
batch?: SubscriberBatch<TRunInput> | undefined;
|
|
502
|
+
}
|
|
503
|
+
/** Options for {@link OnWorkflowFailed}: also which endings start the subscriber. */
|
|
504
|
+
interface OnWorkflowFailedOptions<TEvent, TRunInput> extends OnWorkflowSettledOptions<TEvent, TRunInput> {
|
|
505
|
+
/** The endings that start it. Defaults to all three: `failed`, `cancelled` and `dead`. */
|
|
506
|
+
statuses?: Array<'failed' | 'cancelled' | 'dead'> | undefined;
|
|
507
|
+
}
|
|
508
|
+
/** `O` with a required `batch` (and no `debounce`): the overload whose subscriber takes `{ events }`. */
|
|
509
|
+
type Batched<O, TRunInput> = O & {
|
|
510
|
+
batch: SubscriberBatch<TRunInput>;
|
|
511
|
+
debounce?: undefined;
|
|
512
|
+
};
|
|
513
|
+
/** `O` without `batch`: the overload whose subscriber takes `TRunInput` itself. */
|
|
514
|
+
type Unbatched<O> = O & {
|
|
515
|
+
batch?: undefined;
|
|
516
|
+
};
|
|
517
|
+
/**
|
|
518
|
+
* A class decorator that only accepts a workflow whose `run(ctx, input)` takes `TRunInput`, so a
|
|
519
|
+
* subscriber with the wrong input shape fails to compile instead of failing at runtime.
|
|
520
|
+
*/
|
|
521
|
+
type SubscriberDecorator<TRunInput> = <T extends abstract new (...args: never[]) => {
|
|
522
|
+
run: (ctx: never, input: TRunInput) => unknown;
|
|
523
|
+
}>(target: T) => void;
|
|
524
|
+
/**
|
|
525
|
+
* Start a fresh run of the decorated workflow whenever a run of `workflow` **completes**. The new
|
|
526
|
+
* run's input is the {@link WorkflowLifecycleEvent} (run id, input, output, tags, search
|
|
527
|
+
* attributes), or what `input` builds from it. The settling workflow does not know about its
|
|
528
|
+
* subscribers. Exactly once per settled run: see `runCompletedEvent` in
|
|
529
|
+
* `@dudousxd/nestjs-durable-core`.
|
|
530
|
+
*
|
|
531
|
+
* With a class ref, the decorated workflow's `run` input is type-checked against the event (or
|
|
532
|
+
* against `input`'s return type, or `{ events }` of it with `batch`). Child runs publish too, so a
|
|
533
|
+
* workflow that `etl` starts as a child also starts its subscribers.
|
|
534
|
+
*
|
|
535
|
+
* ```ts
|
|
536
|
+
* @Workflow({ name: 'refresh-summaries' })
|
|
537
|
+
* @OnWorkflowCompleted(IngestionWorkflow, {
|
|
538
|
+
* where: (e) => e.input.type === 'mvr',
|
|
539
|
+
* input: (e) => ({ baseId: e.input.baseId }),
|
|
540
|
+
* debounce: { windowMs: '30s', key: (input) => input.baseId },
|
|
541
|
+
* })
|
|
542
|
+
* class RefreshSummariesWorkflow {
|
|
543
|
+
* async run(ctx: WorkflowCtx, input: { baseId: string }) {}
|
|
544
|
+
* }
|
|
545
|
+
* ```
|
|
546
|
+
*/
|
|
547
|
+
declare function OnWorkflowCompleted<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options: Batched<OnWorkflowSettledOptions<LifecycleEventOf<C>, TRunInput>, TRunInput>): SubscriberDecorator<{
|
|
548
|
+
events: TRunInput[];
|
|
549
|
+
}>;
|
|
550
|
+
declare function OnWorkflowCompleted<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options?: Unbatched<OnWorkflowSettledOptions<LifecycleEventOf<C>, TRunInput>>): SubscriberDecorator<TRunInput>;
|
|
551
|
+
declare function OnWorkflowCompleted(workflow: string, options?: OnWorkflowSettledOptions<WorkflowLifecycleEvent, unknown>): ClassDecorator;
|
|
552
|
+
/**
|
|
553
|
+
* Start a fresh run of the decorated workflow whenever a run of `workflow` ends **failed,
|
|
554
|
+
* cancelled or dead** (narrow it with `statuses`). Same contract as {@link OnWorkflowCompleted};
|
|
555
|
+
* the event carries `error` and `status` instead of `output`.
|
|
556
|
+
*/
|
|
557
|
+
declare function OnWorkflowFailed<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options: Batched<OnWorkflowFailedOptions<LifecycleEventOf<C>, TRunInput>, TRunInput>): SubscriberDecorator<{
|
|
558
|
+
events: TRunInput[];
|
|
559
|
+
}>;
|
|
560
|
+
declare function OnWorkflowFailed<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options?: Unbatched<OnWorkflowFailedOptions<LifecycleEventOf<C>, TRunInput>>): SubscriberDecorator<TRunInput>;
|
|
561
|
+
declare function OnWorkflowFailed(workflow: string, options?: OnWorkflowFailedOptions<WorkflowLifecycleEvent, unknown>): ClassDecorator;
|
|
562
|
+
/** Metadata key for the `onEvent` coalescing `@OnWorkflowCompleted` / `@OnWorkflowFailed` declare. */
|
|
563
|
+
declare const ON_EVENT_BATCH_METADATA: unique symbol;
|
|
564
|
+
/**
|
|
565
|
+
* How a workflow coalesces its `onEvent` triggers: `@Workflow({ debounce | batch })`, or what its
|
|
566
|
+
* `@OnWorkflowCompleted` / `@OnWorkflowFailed` declare. Throws when both are set and differ, so a
|
|
567
|
+
* workflow never silently coalesces one way while its decorator says another.
|
|
568
|
+
*/
|
|
569
|
+
declare function eventBatchOf(meta: WorkflowMeta, target: object): EventBatchConfig | undefined;
|
|
462
570
|
/** @deprecated Renamed to `OnDurableEvent` — this alias clashes with `@nestjs/event-emitter`'s `@OnEvent` and will be removed in the next minor. */
|
|
463
571
|
declare const OnEvent: typeof OnDurableEvent;
|
|
464
|
-
/**
|
|
465
|
-
|
|
572
|
+
/**
|
|
573
|
+
* All events a workflow class subscribes to: `@Workflow({ onEvent })`, `@OnDurableEvent`,
|
|
574
|
+
* `@OnWorkflowCompleted` and `@OnWorkflowFailed`. Repeated bare names collapse to one.
|
|
575
|
+
*/
|
|
576
|
+
declare function getOnEvents(meta: WorkflowMeta, target: object): OnEventEntry[];
|
|
466
577
|
|
|
467
578
|
/**
|
|
468
579
|
* Retention config for the {@link RetentionPoller}. One or more {@link RetentionPolicy policies}
|
|
@@ -563,6 +674,11 @@ interface DurableModuleOptions {
|
|
|
563
674
|
* (a poison pill that crashes the process every boot). Omit for unlimited. Operator only.
|
|
564
675
|
*/
|
|
565
676
|
maxRecoveryAttempts?: number;
|
|
677
|
+
/**
|
|
678
|
+
* How long (ms) a run may stay unresumable because its workflow version is registered nowhere (a
|
|
679
|
+
* renamed or deleted workflow) before it is dead-lettered. Default 24h; `0` skips it forever.
|
|
680
|
+
*/
|
|
681
|
+
unregisteredWorkflowGraceMs?: number;
|
|
566
682
|
/**
|
|
567
683
|
* Opt-in liveness deadline (ms) for a remote (polyglot) workflow `advance`. If the worker neither
|
|
568
684
|
* returns a decision nor sends a run-scoped heartbeat within this window, the engine presumes it dead
|
|
@@ -1104,6 +1220,10 @@ declare function inAppWorkerProviders(): Provider[];
|
|
|
1104
1220
|
* responders reply `ok: true` with no `data` instead; `ProxyRunGateway` reads both.
|
|
1105
1221
|
*/
|
|
1106
1222
|
declare const UNSUPPORTED_RUN_REQUEST = "unsupported-request";
|
|
1223
|
+
/** The error `code` a responder replies with for a request it rejects as malformed or not allowed. */
|
|
1224
|
+
declare const BAD_RUN_REQUEST = "bad-request";
|
|
1225
|
+
/** The most settled runs one tenant republish reads; a larger `limit` is lowered to it. */
|
|
1226
|
+
declare const TENANT_REPUBLISH_MAX_LIMIT = 1000;
|
|
1107
1227
|
/** The narrow slice of `Transport` the responder needs — a tenant's read/control request in, a
|
|
1108
1228
|
* correlated reply out. Both are OPTIONAL on the full `Transport` interface (only broker
|
|
1109
1229
|
* transports carry the run-request/reply protocol); the caller capability-checks before wiring
|
|
@@ -1128,20 +1248,6 @@ interface RunRequestResponderOptions {
|
|
|
1128
1248
|
*/
|
|
1129
1249
|
warnWithoutVerifier?: boolean | undefined;
|
|
1130
1250
|
}
|
|
1131
|
-
/**
|
|
1132
|
-
* Operator-side consumer of a tenant's {@link RunRequest}s: answers each one against a
|
|
1133
|
-
* `RunGateway`, enforcing the tenant boundary before touching the run. For every runId-bearing
|
|
1134
|
-
* verb it loads the run via `getRunDetail` FIRST and compares `run.namespace` to the requesting
|
|
1135
|
-
* `msg.tenant` — a mismatch short-circuits into a `cross-tenant` error reply WITHOUT calling the
|
|
1136
|
-
* verb, so a tenant can never read or act on another tenant's run. `listRuns` is scoped by
|
|
1137
|
-
* overwriting the query's `namespace` with the requester's tenant, ignoring whatever the client
|
|
1138
|
-
* sent. This is the security boundary of the tenant run gateway — do not weaken it.
|
|
1139
|
-
*
|
|
1140
|
-
* With {@link RunRequestResponderOptions.verifyTenant}, every request is authenticated FIRST: the
|
|
1141
|
-
* wire `tenant` is treated as a signed token, the real tenant is derived from it, and an invalid
|
|
1142
|
-
* token short-circuits into an `unauthorized` error reply before any run is touched. A verifier
|
|
1143
|
-
* that throws becomes an error reply too.
|
|
1144
|
-
*/
|
|
1145
1251
|
declare class RunRequestResponder {
|
|
1146
1252
|
private readonly transport;
|
|
1147
1253
|
private readonly gateway;
|
|
@@ -1151,20 +1257,34 @@ declare class RunRequestResponder {
|
|
|
1151
1257
|
* failure never throws back into the transport (errors are captured into an error reply). */
|
|
1152
1258
|
start(): void;
|
|
1153
1259
|
private handle;
|
|
1260
|
+
/**
|
|
1261
|
+
* `detail` scoped to `tenant` (see {@link scopeRunLinks}), with its lifecycle links
|
|
1262
|
+
* (`workflowLifecycle`, `lifecycleSubscribers`) narrowed to the subscriptions of `tenant`'s
|
|
1263
|
+
* namespace, as the `workflowLifecycle` verb answers them.
|
|
1264
|
+
*/
|
|
1265
|
+
private scopeLifecycle;
|
|
1266
|
+
/**
|
|
1267
|
+
* Why a tenant republish naming `subscriber` is refused, or undefined when it may go ahead: the
|
|
1268
|
+
* subscriber must be owed the event of `workflow` settling (as `kind`, when given) by a run of
|
|
1269
|
+
* the tenant's namespace (the gateway's `lifecycleSubscribers`, else the tenant's
|
|
1270
|
+
* `workflowLifecycle` links), so a tenant cannot have the event owed to an arbitrary name. Without
|
|
1271
|
+
* `subscriber` there is nothing to check.
|
|
1272
|
+
*/
|
|
1273
|
+
private refuseSubscriber;
|
|
1154
1274
|
private callVerb;
|
|
1155
1275
|
}
|
|
1156
1276
|
|
|
1157
1277
|
/**
|
|
1158
1278
|
* An error reply from the control plane. `code` carries the reply's machine-readable reason when it
|
|
1159
1279
|
* sent one — `unauthorized` (the tenant token was rejected), `cross-tenant` (the run belongs to
|
|
1160
|
-
* another tenant), ... — so a caller can tell an authentication failure from a real one, as with
|
|
1280
|
+
* another tenant), `bad-request` (the request was malformed or not allowed), ... — so a caller can tell an authentication failure from a real one, as with
|
|
1161
1281
|
* Agora's proxy.
|
|
1162
1282
|
*/
|
|
1163
1283
|
/**
|
|
1164
1284
|
* The codes the run-request responder replies with. `string & {}` keeps a code from a newer control
|
|
1165
1285
|
* plane assignable without losing autocomplete on the known ones.
|
|
1166
1286
|
*/
|
|
1167
|
-
type RunGatewayErrorCode = 'unauthorized' | 'cross-tenant' | typeof UNSUPPORTED_RUN_REQUEST | (string & {});
|
|
1287
|
+
type RunGatewayErrorCode = 'unauthorized' | 'cross-tenant' | typeof BAD_RUN_REQUEST | typeof UNSUPPORTED_RUN_REQUEST | (string & {});
|
|
1168
1288
|
declare class RunGatewayError extends Error {
|
|
1169
1289
|
readonly code: RunGatewayErrorCode | undefined;
|
|
1170
1290
|
constructor(message: string, code?: RunGatewayErrorCode);
|
|
@@ -1246,6 +1366,20 @@ declare class ProxyRunGateway implements RunGateway {
|
|
|
1246
1366
|
redispatchPending(runId: string): Promise<(RunResult & {
|
|
1247
1367
|
redispatched: number;
|
|
1248
1368
|
}) | null>;
|
|
1369
|
+
/**
|
|
1370
|
+
* Republished on the control plane: a one-run target is checked against this tenant like
|
|
1371
|
+
* `retry`, a by-workflow one is read over this tenant's namespace only. A control plane too old to
|
|
1372
|
+
* know the verb fails it with an {@link UNSUPPORTED_RUN_REQUEST} error rather than a timeout.
|
|
1373
|
+
*/
|
|
1374
|
+
republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
|
|
1375
|
+
/** Answered by the control plane's engine; same version-skew error as {@link republishLifecycle}. */
|
|
1376
|
+
workflowLifecycle(workflow: string): Promise<WorkflowLifecycleLinks>;
|
|
1377
|
+
/**
|
|
1378
|
+
* A verb with no fallback on an older control plane: its unsupported-request error, or the empty
|
|
1379
|
+
* `ok: true` reply the oldest responders send for an unknown verb, becomes a
|
|
1380
|
+
* {@link RunGatewayError} with code {@link UNSUPPORTED_RUN_REQUEST}.
|
|
1381
|
+
*/
|
|
1382
|
+
private requestNewVerb;
|
|
1249
1383
|
subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
|
|
1250
1384
|
}
|
|
1251
1385
|
|
|
@@ -1294,6 +1428,18 @@ declare class StoreRunGateway implements RunGateway {
|
|
|
1294
1428
|
constructor(store: StateStore, engine: WorkflowEngine);
|
|
1295
1429
|
topology(): DurableTopology;
|
|
1296
1430
|
getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
|
|
1431
|
+
/**
|
|
1432
|
+
* What a run detail reads beyond the run row and its checkpoints: what this run's settling
|
|
1433
|
+
* started, the subscribers its lifecycle event goes to (of its namespace) and where it stands for
|
|
1434
|
+
* each, what started it, its workflow's lifecycle links, and the `ctx.waitForRun` waits on either
|
|
1435
|
+
* side of it with the other run's status. A few reads per detail: the run's own waiters while it
|
|
1436
|
+
* is suspended, the waiters on it (one prefix read), and one batched read of every linked run.
|
|
1437
|
+
*/
|
|
1438
|
+
private lifecycleLinks;
|
|
1439
|
+
workflowLifecycle(workflow: string, opts?: {
|
|
1440
|
+
namespace?: string | undefined;
|
|
1441
|
+
}): Promise<WorkflowLifecycleLinks>;
|
|
1442
|
+
lifecycleSubscribers(workflow: string, kind: LifecycleKind, namespace: string): Promise<string[]>;
|
|
1297
1443
|
getRun(runId: string): Promise<WorkflowRun | null>;
|
|
1298
1444
|
getFanMembers(runId: string, group: string, query: FanPageQuery): Promise<FanPage | null>;
|
|
1299
1445
|
listRuns(query: RunQuery): Promise<RunListItem[]>;
|
|
@@ -1338,6 +1484,7 @@ declare class StoreRunGateway implements RunGateway {
|
|
|
1338
1484
|
redispatchPending(runId: string): Promise<(RunResult & {
|
|
1339
1485
|
redispatched: number;
|
|
1340
1486
|
}) | null>;
|
|
1487
|
+
republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
|
|
1341
1488
|
subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
|
|
1342
1489
|
}
|
|
1343
1490
|
|
|
@@ -1452,6 +1599,18 @@ declare class WorkflowService {
|
|
|
1452
1599
|
id?: string;
|
|
1453
1600
|
buffer?: boolean;
|
|
1454
1601
|
}): Promise<number>;
|
|
1602
|
+
/**
|
|
1603
|
+
* The runs started by `runId` settling, through `@OnWorkflowCompleted` / `@OnWorkflowFailed` (or
|
|
1604
|
+
* an `onEvent` on `runCompletedEvent(...)`). Only subscribers registered on this engine are
|
|
1605
|
+
* considered. For the reverse link, `lifecycleSourceOf(run)` reads it from the run itself.
|
|
1606
|
+
*/
|
|
1607
|
+
triggeredRuns(runId: string): Promise<string[]>;
|
|
1608
|
+
/**
|
|
1609
|
+
* Publish settled runs' lifecycle events again: to a subscriber registered after they settled, or
|
|
1610
|
+
* one restricted by `subscriber`. Subscribers already started for a run are not started again.
|
|
1611
|
+
* See `WorkflowEngine.republishLifecycle`.
|
|
1612
|
+
*/
|
|
1613
|
+
republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
|
|
1455
1614
|
}
|
|
1456
1615
|
|
|
1457
|
-
export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, RunGatewayError, type RunGatewayErrorCode, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestResponderOptions, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };
|
|
1616
|
+
export { BAD_RUN_REQUEST, CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_BATCH_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, OnWorkflowCompleted, OnWorkflowFailed, type OnWorkflowFailedOptions, type OnWorkflowSettledOptions, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, RunGatewayError, type RunGatewayErrorCode, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestResponderOptions, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, type SubscriberBatch, type SubscriberDebounce, type SubscriberDecorator, TENANT_REPUBLISH_MAX_LIMIT, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, eventBatchOf, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };
|