@dudousxd/nestjs-durable 0.60.0 → 0.62.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.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnEventEntry, OnErrorInput, LifecycleEventOf, WorkflowLifecycleEvent, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, EventBatchConfig, TenantVerifier, VerifiedTenant, TenantTokenSource, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, TenantFilter as TenantFilter$1, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, RepublishLifecycleTarget, RepublishLifecycleResult, WorkflowLifecycleLinks, EngineEvent, StepInvocation, LifecycleKind, TenantEvent, SignalOptions } from '@dudousxd/nestjs-durable-core';
1
+ import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnEventEntry, OnErrorInput, LifecycleEventOf, WorkflowLifecycleEvent, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, EventBatchConfig, TenantVerifier, VerifiedTenant, TenantTokenSource, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, RunWaiting, WorkflowLifecycleLinks, LifecycleKind, GroupHealth, ScheduleListQuery, ScheduleDescription, RepublishLifecycleTarget, RepublishLifecycleResult, ScheduleAction, EngineEvent, RunRequest, RunReply, TenantFilter as TenantFilter$1, StepInvocation, TenantEvent, SignalOptions } from '@dudousxd/nestjs-durable-core';
2
2
  export { AttributeFilter, DuplicateDurableCopyError, 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';
@@ -764,6 +764,27 @@ interface DurableModuleSharedOptions {
764
764
  controlPlane?: ControlPlane;
765
765
  /** Interval (ms) for the durable-timer poller. `0` disables it. Defaults to 1000. Operator only. */
766
766
  timerPollMs?: number;
767
+ /**
768
+ * The longest wait (ms) between two timer polls while there is nothing to do. After a poll that
769
+ * found no work the wait doubles from `timerPollMs` up to this, and goes back to `timerPollMs` as
770
+ * soon as there is work or any run event (here, or from another instance over the control plane).
771
+ * It never outlasts a known due time: before each longer wait the poller reads when the next timer,
772
+ * blocked-run recovery poll, persisted schedule or in-process `schedules` window is due. What it
773
+ * delays is recovery only: a crashed instance's runs, execution timeouts and the stalled/
774
+ * buffered-signal sweeps are picked up at most this late. A value at or below `timerPollMs` keeps
775
+ * the fixed tick, and so does an engine with neither a control plane nor a run queue (a run another
776
+ * instance starts reaches it only through the pending-run poll). Defaults to 5000. Operator only.
777
+ */
778
+ maxIdleIntervalMs?: number;
779
+ /**
780
+ * How often (ms) the timer poller lists the settled runs that still owe a lifecycle event, and
781
+ * heals the ones that missed a newly announced subscriber. That listing is the recovery path for a
782
+ * publish that never happened (the live publish gets a 30 s grace first) and filters runs by tag,
783
+ * so running it on every tick cost a scan of the runs table each second for nothing. The run-wait
784
+ * delivery and registry heartbeat still run every tick. A failed sweep is retried on the next tick.
785
+ * `0` sweeps on every tick (the old behavior). Defaults to 10000. Operator only.
786
+ */
787
+ owedLifecycleSweepMs?: number;
767
788
  /**
768
789
  * Auto-create the durable tables on boot via `store.ensureSchema()`. Defaults to true. Turn
769
790
  * off in production and call the store adapter's `ensure*DurableSchema()` from a migration.
@@ -1342,6 +1363,116 @@ declare class EntityService {
1342
1363
  getState<S = unknown>(name: string, key: string): Promise<S | undefined>;
1343
1364
  }
1344
1365
 
1366
+ /** Options for {@link federatedAppGateway}. */
1367
+ interface FederatedAppGatewayOptions {
1368
+ /**
1369
+ * A handle on the app's state store, used for READS only (runs, timelines, facets, schedules).
1370
+ * Typically a store adapter over the app's schema with a database user granted `SELECT` on it.
1371
+ * Nothing on this handle is written: actions go to the app (see {@link transport}).
1372
+ */
1373
+ store: StateStore;
1374
+ /**
1375
+ * A transport on the app's broker and prefix (e.g. `new BullMQTransport({ connection, prefix })`
1376
+ * with the app's own `prefix`), dedicated to this gateway. It carries the actions to the app as run
1377
+ * requests, which the app's own engine answers and executes, plus its live run events and worker
1378
+ * health. The gateway consumes no queue on it: the app's work is never taken by the console.
1379
+ */
1380
+ transport: Transport;
1381
+ /**
1382
+ * The token presented as the requester of each action, for an app whose engine verifies tenants
1383
+ * (`verifyTenant`, e.g. `hmacTenantVerifier(secret)`): `(namespace) => signTenantToken(namespace,
1384
+ * secret)`. Called with the namespace of the run or schedule acted on. Omitted: the namespace
1385
+ * itself is sent, which an app without `verifyTenant` trusts.
1386
+ */
1387
+ tenantToken?: (namespace: string) => string | Promise<string>;
1388
+ /**
1389
+ * Where the app's engines broadcast their lifecycle events (its `controlPlane`): what the console's
1390
+ * live tail of an app run listens on. Default: {@link transport} when it can broadcast (BullMQ
1391
+ * can), which is also the app's default. Only listened to, never published on.
1392
+ */
1393
+ controlPlane?: ControlPlane;
1394
+ /** How long an action waits for the app to answer. Default 10000 ms. */
1395
+ timeoutMs?: number;
1396
+ }
1397
+ /**
1398
+ * A `RunGateway` for ANOTHER app, for a federated console (the dashboard's `federation` option).
1399
+ * Reads come from the app's store; every action (cancel, retry, continue, signal, schedule
1400
+ * pause/resume/trigger, …) is published to the app over its broker as a run request, and the app's
1401
+ * own engine executes it, through the run-request responder every operator with a broker transport
1402
+ * already runs. The console process never drives, recovers or executes the app's runs.
1403
+ *
1404
+ * Each action names the namespace of the run (or schedule) it acts on as the requester, which the
1405
+ * app's responder checks the run against, exactly as it checks a tenant's request.
1406
+ */
1407
+ declare class FederatedAppGateway implements RunGateway {
1408
+ private readonly options;
1409
+ private readonly reads;
1410
+ private readonly pending;
1411
+ private listening;
1412
+ private readonly timeoutMs;
1413
+ /** Live-tail listeners by run id, fed by ONE subscription to the app's control channel. */
1414
+ private readonly tails;
1415
+ private tailing;
1416
+ constructor(options: FederatedAppGatewayOptions);
1417
+ topology(): DurableTopology;
1418
+ getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
1419
+ getFanMembers(runId: string, group: string, query: FanPageQuery): Promise<FanPage | null>;
1420
+ getRun(runId: string): Promise<WorkflowRun | null>;
1421
+ listRuns(query: RunQuery): Promise<RunListItem[]>;
1422
+ runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
1423
+ runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
1424
+ waitingFor(runIds: string[]): Promise<Record<string, RunWaiting>>;
1425
+ workflowLifecycle(workflow: string, opts?: {
1426
+ namespace?: string | undefined;
1427
+ }): Promise<WorkflowLifecycleLinks>;
1428
+ lifecycleSubscribers(workflow: string, kind: LifecycleKind, namespace: string): Promise<string[]>;
1429
+ /** The app's worker groups, read from its broker (read-only). `[]` when the transport can't. */
1430
+ workerHealth(): Promise<GroupHealth[]>;
1431
+ listSchedules(query: ScheduleListQuery): Promise<ScheduleDescription[]>;
1432
+ getSchedule(id: string): Promise<ScheduleDescription | null>;
1433
+ signalWaiter(token: string): Promise<string | null>;
1434
+ cancel(runId: string, opts?: {
1435
+ compensate?: boolean;
1436
+ }): Promise<RunResult | null>;
1437
+ retry(runId: string): Promise<RunResult | null>;
1438
+ continue(runId: string): Promise<RunResult | null>;
1439
+ retryWithInput(runId: string, input: unknown): Promise<{
1440
+ runId: string;
1441
+ } | null>;
1442
+ redispatchPending(runId: string): Promise<(RunResult & {
1443
+ redispatched: number;
1444
+ }) | null>;
1445
+ republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1446
+ /**
1447
+ * Pause, resume or trigger one of the app's persisted schedules, executed by the app. A schedule
1448
+ * that does not exist rejects with a `ScheduleNotFoundError`, as the engine's own client does.
1449
+ */
1450
+ scheduleAction(id: string, action: ScheduleAction): Promise<ScheduleDescription | RunResult>;
1451
+ /**
1452
+ * Deliver `payload` to the app's run waiting on `token`, by the app. Null when no run of the app
1453
+ * waits on it yet: unlike the engine's own `signal`, nothing is buffered for a later wait.
1454
+ */
1455
+ signal(token: string, payload: unknown): Promise<RunResult | null>;
1456
+ /**
1457
+ * The app's live events for `runId`, from the control channel its engines broadcast every event on
1458
+ * (see {@link FederatedAppGatewayOptions.controlPlane}). Nothing when there is none.
1459
+ */
1460
+ subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
1461
+ private controlPlane;
1462
+ private deliver;
1463
+ /** `act` with the namespace of `runId`, or null when the app has no such run. */
1464
+ private onRun;
1465
+ /** Send `body` to the app as a run request from `namespace`, and wait for its reply. */
1466
+ private request;
1467
+ private listen;
1468
+ private handleReply;
1469
+ }
1470
+ /**
1471
+ * A `RunGateway` over another app's store (reads) and broker (actions, executed by that app), for
1472
+ * the dashboard's `federation.apps`. See {@link FederatedAppGateway}.
1473
+ */
1474
+ declare function federatedAppGateway(options: FederatedAppGatewayOptions): FederatedAppGateway;
1475
+
1345
1476
  /**
1346
1477
  * The **co-located in-app worker** (uniform dispatch): active whenever an app supplies BOTH `store`
1347
1478
  * AND `connection` (`DurableModule.forRoot({ store, transport, connection, partition? })`) — the same
@@ -1442,6 +1573,10 @@ declare class RunRequestResponder {
1442
1573
  * failure never throws back into the transport (errors are captured into an error reply). */
1443
1574
  start(): void;
1444
1575
  private handle;
1576
+ /** The run alone (`getRun`, else from its detail), or null when it does not exist. */
1577
+ private runOf;
1578
+ /** `call`'s result as an `ok` reply, or its rejection as an error reply. */
1579
+ private answer;
1445
1580
  /**
1446
1581
  * `detail` scoped to `tenant` (see {@link scopeRunLinks}), with its lifecycle links
1447
1582
  * (`workflowLifecycle`, `lifecycleSubscribers`) narrowed to the subscriptions of `tenant`'s
@@ -1706,6 +1841,12 @@ declare class StoreRunGateway implements RunGateway {
1706
1841
  redispatched: number;
1707
1842
  }) | null>;
1708
1843
  republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1844
+ /** The persisted schedules (`[]` when the store does not persist them). */
1845
+ listSchedules(query: ScheduleListQuery): Promise<ScheduleDescription[]>;
1846
+ getSchedule(id: string): Promise<ScheduleDescription | null>;
1847
+ scheduleAction(id: string, action: ScheduleAction): Promise<ScheduleDescription | RunResult>;
1848
+ signal(token: string, payload: unknown): Promise<RunResult | null>;
1849
+ signalWaiter(token: string): Promise<string | null>;
1709
1850
  /**
1710
1851
  * Stream `runId`'s events. With tenancy, a run the caller may not see streams nothing; events of a
1711
1852
  * run that does not exist yet are held until its row shows whose it is.
@@ -1838,4 +1979,4 @@ declare class WorkflowService {
1838
1979
  republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1839
1980
  }
1840
1981
 
1841
- export { BAD_RUN_REQUEST, CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, type ContractClass, type ControlPlaneDurableOptions, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableModuleSharedOptions, type DurableRetentionOptions, DurableStartClient, type DurableStepInterceptor, type DurableStepMeta, type DurableTopologyName, 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, type LazyContract, ON_ERROR_METADATA, ON_EVENT_BATCH_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, 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, type StandaloneDurableOptions, Step, StepInterceptor, type StepOptions, StoreRunGateway, type SubscriberBatch, type SubscriberDebounce, type SubscriberDecorator, TENANT_REPUBLISH_MAX_LIMIT, type TenantCredentialsContract, type TenantDurableOptions, TenantEventRepublisher, type TenantFilter, type TenantLevel, type TenantRef, type TenantTokenOption, type TenantVerifierContract, type TenantVerifierInput, type TenantVerifierOption, 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 };
1982
+ export { BAD_RUN_REQUEST, CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, type ContractClass, type ControlPlaneDurableOptions, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableModuleSharedOptions, type DurableRetentionOptions, DurableStartClient, type DurableStepInterceptor, type DurableStepMeta, type DurableTopologyName, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, FederatedAppGateway, type FederatedAppGatewayOptions, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, type LazyContract, ON_ERROR_METADATA, ON_EVENT_BATCH_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, 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, type StandaloneDurableOptions, Step, StepInterceptor, type StepOptions, StoreRunGateway, type SubscriberBatch, type SubscriberDebounce, type SubscriberDecorator, TENANT_REPUBLISH_MAX_LIMIT, type TenantCredentialsContract, type TenantDurableOptions, TenantEventRepublisher, type TenantFilter, type TenantLevel, type TenantRef, type TenantTokenOption, type TenantVerifierContract, type TenantVerifierInput, type TenantVerifierOption, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, eventBatchOf, federatedAppGateway, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnEventEntry, OnErrorInput, LifecycleEventOf, WorkflowLifecycleEvent, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, EventBatchConfig, TenantVerifier, VerifiedTenant, TenantTokenSource, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, TenantFilter as TenantFilter$1, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, RepublishLifecycleTarget, RepublishLifecycleResult, WorkflowLifecycleLinks, EngineEvent, StepInvocation, LifecycleKind, TenantEvent, SignalOptions } from '@dudousxd/nestjs-durable-core';
1
+ import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnEventEntry, OnErrorInput, LifecycleEventOf, WorkflowLifecycleEvent, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, EventBatchConfig, TenantVerifier, VerifiedTenant, TenantTokenSource, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, RunWaiting, WorkflowLifecycleLinks, LifecycleKind, GroupHealth, ScheduleListQuery, ScheduleDescription, RepublishLifecycleTarget, RepublishLifecycleResult, ScheduleAction, EngineEvent, RunRequest, RunReply, TenantFilter as TenantFilter$1, StepInvocation, TenantEvent, SignalOptions } from '@dudousxd/nestjs-durable-core';
2
2
  export { AttributeFilter, DuplicateDurableCopyError, 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';
@@ -764,6 +764,27 @@ interface DurableModuleSharedOptions {
764
764
  controlPlane?: ControlPlane;
765
765
  /** Interval (ms) for the durable-timer poller. `0` disables it. Defaults to 1000. Operator only. */
766
766
  timerPollMs?: number;
767
+ /**
768
+ * The longest wait (ms) between two timer polls while there is nothing to do. After a poll that
769
+ * found no work the wait doubles from `timerPollMs` up to this, and goes back to `timerPollMs` as
770
+ * soon as there is work or any run event (here, or from another instance over the control plane).
771
+ * It never outlasts a known due time: before each longer wait the poller reads when the next timer,
772
+ * blocked-run recovery poll, persisted schedule or in-process `schedules` window is due. What it
773
+ * delays is recovery only: a crashed instance's runs, execution timeouts and the stalled/
774
+ * buffered-signal sweeps are picked up at most this late. A value at or below `timerPollMs` keeps
775
+ * the fixed tick, and so does an engine with neither a control plane nor a run queue (a run another
776
+ * instance starts reaches it only through the pending-run poll). Defaults to 5000. Operator only.
777
+ */
778
+ maxIdleIntervalMs?: number;
779
+ /**
780
+ * How often (ms) the timer poller lists the settled runs that still owe a lifecycle event, and
781
+ * heals the ones that missed a newly announced subscriber. That listing is the recovery path for a
782
+ * publish that never happened (the live publish gets a 30 s grace first) and filters runs by tag,
783
+ * so running it on every tick cost a scan of the runs table each second for nothing. The run-wait
784
+ * delivery and registry heartbeat still run every tick. A failed sweep is retried on the next tick.
785
+ * `0` sweeps on every tick (the old behavior). Defaults to 10000. Operator only.
786
+ */
787
+ owedLifecycleSweepMs?: number;
767
788
  /**
768
789
  * Auto-create the durable tables on boot via `store.ensureSchema()`. Defaults to true. Turn
769
790
  * off in production and call the store adapter's `ensure*DurableSchema()` from a migration.
@@ -1342,6 +1363,116 @@ declare class EntityService {
1342
1363
  getState<S = unknown>(name: string, key: string): Promise<S | undefined>;
1343
1364
  }
1344
1365
 
1366
+ /** Options for {@link federatedAppGateway}. */
1367
+ interface FederatedAppGatewayOptions {
1368
+ /**
1369
+ * A handle on the app's state store, used for READS only (runs, timelines, facets, schedules).
1370
+ * Typically a store adapter over the app's schema with a database user granted `SELECT` on it.
1371
+ * Nothing on this handle is written: actions go to the app (see {@link transport}).
1372
+ */
1373
+ store: StateStore;
1374
+ /**
1375
+ * A transport on the app's broker and prefix (e.g. `new BullMQTransport({ connection, prefix })`
1376
+ * with the app's own `prefix`), dedicated to this gateway. It carries the actions to the app as run
1377
+ * requests, which the app's own engine answers and executes, plus its live run events and worker
1378
+ * health. The gateway consumes no queue on it: the app's work is never taken by the console.
1379
+ */
1380
+ transport: Transport;
1381
+ /**
1382
+ * The token presented as the requester of each action, for an app whose engine verifies tenants
1383
+ * (`verifyTenant`, e.g. `hmacTenantVerifier(secret)`): `(namespace) => signTenantToken(namespace,
1384
+ * secret)`. Called with the namespace of the run or schedule acted on. Omitted: the namespace
1385
+ * itself is sent, which an app without `verifyTenant` trusts.
1386
+ */
1387
+ tenantToken?: (namespace: string) => string | Promise<string>;
1388
+ /**
1389
+ * Where the app's engines broadcast their lifecycle events (its `controlPlane`): what the console's
1390
+ * live tail of an app run listens on. Default: {@link transport} when it can broadcast (BullMQ
1391
+ * can), which is also the app's default. Only listened to, never published on.
1392
+ */
1393
+ controlPlane?: ControlPlane;
1394
+ /** How long an action waits for the app to answer. Default 10000 ms. */
1395
+ timeoutMs?: number;
1396
+ }
1397
+ /**
1398
+ * A `RunGateway` for ANOTHER app, for a federated console (the dashboard's `federation` option).
1399
+ * Reads come from the app's store; every action (cancel, retry, continue, signal, schedule
1400
+ * pause/resume/trigger, …) is published to the app over its broker as a run request, and the app's
1401
+ * own engine executes it, through the run-request responder every operator with a broker transport
1402
+ * already runs. The console process never drives, recovers or executes the app's runs.
1403
+ *
1404
+ * Each action names the namespace of the run (or schedule) it acts on as the requester, which the
1405
+ * app's responder checks the run against, exactly as it checks a tenant's request.
1406
+ */
1407
+ declare class FederatedAppGateway implements RunGateway {
1408
+ private readonly options;
1409
+ private readonly reads;
1410
+ private readonly pending;
1411
+ private listening;
1412
+ private readonly timeoutMs;
1413
+ /** Live-tail listeners by run id, fed by ONE subscription to the app's control channel. */
1414
+ private readonly tails;
1415
+ private tailing;
1416
+ constructor(options: FederatedAppGatewayOptions);
1417
+ topology(): DurableTopology;
1418
+ getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
1419
+ getFanMembers(runId: string, group: string, query: FanPageQuery): Promise<FanPage | null>;
1420
+ getRun(runId: string): Promise<WorkflowRun | null>;
1421
+ listRuns(query: RunQuery): Promise<RunListItem[]>;
1422
+ runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
1423
+ runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
1424
+ waitingFor(runIds: string[]): Promise<Record<string, RunWaiting>>;
1425
+ workflowLifecycle(workflow: string, opts?: {
1426
+ namespace?: string | undefined;
1427
+ }): Promise<WorkflowLifecycleLinks>;
1428
+ lifecycleSubscribers(workflow: string, kind: LifecycleKind, namespace: string): Promise<string[]>;
1429
+ /** The app's worker groups, read from its broker (read-only). `[]` when the transport can't. */
1430
+ workerHealth(): Promise<GroupHealth[]>;
1431
+ listSchedules(query: ScheduleListQuery): Promise<ScheduleDescription[]>;
1432
+ getSchedule(id: string): Promise<ScheduleDescription | null>;
1433
+ signalWaiter(token: string): Promise<string | null>;
1434
+ cancel(runId: string, opts?: {
1435
+ compensate?: boolean;
1436
+ }): Promise<RunResult | null>;
1437
+ retry(runId: string): Promise<RunResult | null>;
1438
+ continue(runId: string): Promise<RunResult | null>;
1439
+ retryWithInput(runId: string, input: unknown): Promise<{
1440
+ runId: string;
1441
+ } | null>;
1442
+ redispatchPending(runId: string): Promise<(RunResult & {
1443
+ redispatched: number;
1444
+ }) | null>;
1445
+ republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1446
+ /**
1447
+ * Pause, resume or trigger one of the app's persisted schedules, executed by the app. A schedule
1448
+ * that does not exist rejects with a `ScheduleNotFoundError`, as the engine's own client does.
1449
+ */
1450
+ scheduleAction(id: string, action: ScheduleAction): Promise<ScheduleDescription | RunResult>;
1451
+ /**
1452
+ * Deliver `payload` to the app's run waiting on `token`, by the app. Null when no run of the app
1453
+ * waits on it yet: unlike the engine's own `signal`, nothing is buffered for a later wait.
1454
+ */
1455
+ signal(token: string, payload: unknown): Promise<RunResult | null>;
1456
+ /**
1457
+ * The app's live events for `runId`, from the control channel its engines broadcast every event on
1458
+ * (see {@link FederatedAppGatewayOptions.controlPlane}). Nothing when there is none.
1459
+ */
1460
+ subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
1461
+ private controlPlane;
1462
+ private deliver;
1463
+ /** `act` with the namespace of `runId`, or null when the app has no such run. */
1464
+ private onRun;
1465
+ /** Send `body` to the app as a run request from `namespace`, and wait for its reply. */
1466
+ private request;
1467
+ private listen;
1468
+ private handleReply;
1469
+ }
1470
+ /**
1471
+ * A `RunGateway` over another app's store (reads) and broker (actions, executed by that app), for
1472
+ * the dashboard's `federation.apps`. See {@link FederatedAppGateway}.
1473
+ */
1474
+ declare function federatedAppGateway(options: FederatedAppGatewayOptions): FederatedAppGateway;
1475
+
1345
1476
  /**
1346
1477
  * The **co-located in-app worker** (uniform dispatch): active whenever an app supplies BOTH `store`
1347
1478
  * AND `connection` (`DurableModule.forRoot({ store, transport, connection, partition? })`) — the same
@@ -1442,6 +1573,10 @@ declare class RunRequestResponder {
1442
1573
  * failure never throws back into the transport (errors are captured into an error reply). */
1443
1574
  start(): void;
1444
1575
  private handle;
1576
+ /** The run alone (`getRun`, else from its detail), or null when it does not exist. */
1577
+ private runOf;
1578
+ /** `call`'s result as an `ok` reply, or its rejection as an error reply. */
1579
+ private answer;
1445
1580
  /**
1446
1581
  * `detail` scoped to `tenant` (see {@link scopeRunLinks}), with its lifecycle links
1447
1582
  * (`workflowLifecycle`, `lifecycleSubscribers`) narrowed to the subscriptions of `tenant`'s
@@ -1706,6 +1841,12 @@ declare class StoreRunGateway implements RunGateway {
1706
1841
  redispatched: number;
1707
1842
  }) | null>;
1708
1843
  republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1844
+ /** The persisted schedules (`[]` when the store does not persist them). */
1845
+ listSchedules(query: ScheduleListQuery): Promise<ScheduleDescription[]>;
1846
+ getSchedule(id: string): Promise<ScheduleDescription | null>;
1847
+ scheduleAction(id: string, action: ScheduleAction): Promise<ScheduleDescription | RunResult>;
1848
+ signal(token: string, payload: unknown): Promise<RunResult | null>;
1849
+ signalWaiter(token: string): Promise<string | null>;
1709
1850
  /**
1710
1851
  * Stream `runId`'s events. With tenancy, a run the caller may not see streams nothing; events of a
1711
1852
  * run that does not exist yet are held until its row shows whose it is.
@@ -1838,4 +1979,4 @@ declare class WorkflowService {
1838
1979
  republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1839
1980
  }
1840
1981
 
1841
- export { BAD_RUN_REQUEST, CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, type ContractClass, type ControlPlaneDurableOptions, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableModuleSharedOptions, type DurableRetentionOptions, DurableStartClient, type DurableStepInterceptor, type DurableStepMeta, type DurableTopologyName, 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, type LazyContract, ON_ERROR_METADATA, ON_EVENT_BATCH_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, 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, type StandaloneDurableOptions, Step, StepInterceptor, type StepOptions, StoreRunGateway, type SubscriberBatch, type SubscriberDebounce, type SubscriberDecorator, TENANT_REPUBLISH_MAX_LIMIT, type TenantCredentialsContract, type TenantDurableOptions, TenantEventRepublisher, type TenantFilter, type TenantLevel, type TenantRef, type TenantTokenOption, type TenantVerifierContract, type TenantVerifierInput, type TenantVerifierOption, 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 };
1982
+ export { BAD_RUN_REQUEST, CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, type ContractClass, type ControlPlaneDurableOptions, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableModuleSharedOptions, type DurableRetentionOptions, DurableStartClient, type DurableStepInterceptor, type DurableStepMeta, type DurableTopologyName, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, FederatedAppGateway, type FederatedAppGatewayOptions, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, type LazyContract, ON_ERROR_METADATA, ON_EVENT_BATCH_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, 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, type StandaloneDurableOptions, Step, StepInterceptor, type StepOptions, StoreRunGateway, type SubscriberBatch, type SubscriberDebounce, type SubscriberDecorator, TENANT_REPUBLISH_MAX_LIMIT, type TenantCredentialsContract, type TenantDurableOptions, TenantEventRepublisher, type TenantFilter, type TenantLevel, type TenantRef, type TenantTokenOption, type TenantVerifierContract, type TenantVerifierInput, type TenantVerifierOption, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, eventBatchOf, federatedAppGateway, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };