@dudousxd/nestjs-durable 0.36.0 → 0.38.0

package/dist/index.d.cts

@@ -129,6 +129,9 @@ interface WorkflowMeta {
         maxSize: number;
         within: string | number;
     } | undefined;
+    /** Capabilities a live worker must advertise to run this workflow's turns (handshake §7.5). See
+     *  `WorkflowOptions`. */
+    requires?: string[] | undefined;
 }
 interface WorkflowOptions {
     name: string;
@@ -159,6 +162,14 @@ interface WorkflowOptions {
      * runs that get stuck or loop forever. Omit for no limit.
      */
     executionTimeout?: string | number;
+    /**
+     * Capabilities a live worker MUST advertise to run this workflow's turns (handshake design §7.5).
+     * Only meaningful for a group-served / remote workflow (an in-app worker or a cross-runtime body):
+     * the control-plane dispatches a turn only to a capability-capable + protocol-compatible worker, and
+     * if descriptors are published on its group but none qualifies the run parks `blocked` until the
+     * recovery poll finds one. Absent/empty = "runs anywhere" (a legacy fleet skips the guard, §7.7).
+     */
+    requires?: string[];
     /**
      * Validate the workflow input at `start` against a **class-validator DTO** (the same
      * `plainToInstance` + `validate` NestJS runs in controllers) — invalid input is rejected before any
@@ -266,6 +277,15 @@ interface StepOptions {
      * `retries`). Omit to wait indefinitely.
      */
     timeoutMs?: number;
+    /**
+     * Capabilities a live worker MUST advertise to run this step (handshake design §7.5). The
+     * control-plane routes the step only to workers whose descriptor advertises every name here; if
+     * descriptors are published on the step's group but none is capability-capable + protocol-compatible,
+     * the run parks `blocked` (never a silent hang) until the recovery poll finds one. Absent/empty =
+     * "runs anywhere" (the default — a legacy fleet publishing no descriptors skips the guard, §7.7). A
+     * per-call `ctx.step(ref, input, { requires })` overrides this.
+     */
+    requires?: string[];
 }
 /**
  * Marks a provider method as a durable step handler. An in-process transport (e.g. the
@@ -1040,13 +1060,16 @@ declare class TenantEventRepublisher {
  */
 declare const CONTEXT_ACCESSOR: unique symbol;
 /**
- * Injection token for the bound `RunGateway` — the read/control surface a consumer (a controller,
- * or the `RunRequestResponder`) uses instead of reaching for `WorkflowEngine`/`StateStore`
- * directly. `DurableModule` binds it to `StoreRunGateway` on worker/drive (operator) instances.
- * `Symbol.for` so re-resolving this module (e.g. across a dynamic-module boundary) still hits the
- * same registration.
+ * @deprecated Inject the `RunGateway` abstract class directly (it is its own DI token now):
+ * `constructor(private readonly gateway: RunGateway)`, provider `{ provide: RunGateway, useClass }`.
+ * This symbol is kept as a back-compat alias — it points at the `RunGateway` class, so existing
+ * `@Inject(RUN_GATEWAY)` sites resolve the very same token — and will be removed in a future major.
+ *
+ * `RunGateway` is owned by `@dudousxd/nestjs-durable-core` (a required peer dep of both this package
+ * and the dashboard), so the abstract class is a single shared token across packages without the
+ * previous `Symbol.for` value-sharing hack.
  */
-declare const RUN_GATEWAY: unique symbol;
+declare const RUN_GATEWAY: typeof RunGateway;
 
 /** Public entry point for starting and resuming workflow runs. */
 declare class WorkflowService {

package/dist/index.d.ts

@@ -129,6 +129,9 @@ interface WorkflowMeta {
         maxSize: number;
         within: string | number;
     } | undefined;
+    /** Capabilities a live worker must advertise to run this workflow's turns (handshake §7.5). See
+     *  `WorkflowOptions`. */
+    requires?: string[] | undefined;
 }
 interface WorkflowOptions {
     name: string;
@@ -159,6 +162,14 @@ interface WorkflowOptions {
      * runs that get stuck or loop forever. Omit for no limit.
      */
     executionTimeout?: string | number;
+    /**
+     * Capabilities a live worker MUST advertise to run this workflow's turns (handshake design §7.5).
+     * Only meaningful for a group-served / remote workflow (an in-app worker or a cross-runtime body):
+     * the control-plane dispatches a turn only to a capability-capable + protocol-compatible worker, and
+     * if descriptors are published on its group but none qualifies the run parks `blocked` until the
+     * recovery poll finds one. Absent/empty = "runs anywhere" (a legacy fleet skips the guard, §7.7).
+     */
+    requires?: string[];
     /**
      * Validate the workflow input at `start` against a **class-validator DTO** (the same
      * `plainToInstance` + `validate` NestJS runs in controllers) — invalid input is rejected before any
@@ -266,6 +277,15 @@ interface StepOptions {
      * `retries`). Omit to wait indefinitely.
      */
     timeoutMs?: number;
+    /**
+     * Capabilities a live worker MUST advertise to run this step (handshake design §7.5). The
+     * control-plane routes the step only to workers whose descriptor advertises every name here; if
+     * descriptors are published on the step's group but none is capability-capable + protocol-compatible,
+     * the run parks `blocked` (never a silent hang) until the recovery poll finds one. Absent/empty =
+     * "runs anywhere" (the default — a legacy fleet publishing no descriptors skips the guard, §7.7). A
+     * per-call `ctx.step(ref, input, { requires })` overrides this.
+     */
+    requires?: string[];
 }
 /**
  * Marks a provider method as a durable step handler. An in-process transport (e.g. the
@@ -1040,13 +1060,16 @@ declare class TenantEventRepublisher {
  */
 declare const CONTEXT_ACCESSOR: unique symbol;
 /**
- * Injection token for the bound `RunGateway` — the read/control surface a consumer (a controller,
- * or the `RunRequestResponder`) uses instead of reaching for `WorkflowEngine`/`StateStore`
- * directly. `DurableModule` binds it to `StoreRunGateway` on worker/drive (operator) instances.
- * `Symbol.for` so re-resolving this module (e.g. across a dynamic-module boundary) still hits the
- * same registration.
+ * @deprecated Inject the `RunGateway` abstract class directly (it is its own DI token now):
+ * `constructor(private readonly gateway: RunGateway)`, provider `{ provide: RunGateway, useClass }`.
+ * This symbol is kept as a back-compat alias — it points at the `RunGateway` class, so existing
+ * `@Inject(RUN_GATEWAY)` sites resolve the very same token — and will be removed in a future major.
+ *
+ * `RunGateway` is owned by `@dudousxd/nestjs-durable-core` (a required peer dep of both this package
+ * and the dashboard), so the abstract class is a single shared token across packages without the
+ * previous `Symbol.for` value-sharing hack.
  */
-declare const RUN_GATEWAY: unique symbol;
+declare const RUN_GATEWAY: typeof RunGateway;
 
 /** Public entry point for starting and resuming workflow runs. */
 declare class WorkflowService {

package/dist/index.js

@@ -28,7 +28,8 @@ function Workflow(options) {
       searchAttributes: options.searchAttributes,
       onEvent: options.onEvent,
       debounce: options.debounce,
-      batch: options.batch
+      batch: options.batch,
+      requires: options.requires
     };
     Reflect.defineMetadata(WORKFLOW_METADATA, meta, target);
     Object.defineProperty(target, WORKFLOW_NAME_KEY, {
@@ -50,7 +51,8 @@ function stepConfigFrom(options) {
     backoffMs: options.backoffMs,
     backoffMaxMs: options.backoffMaxMs,
     jitter: options.jitter,
-    timeoutMs: options.timeoutMs
+    timeoutMs: options.timeoutMs,
+    requires: options.requires
   };
   const hasAnyField = Object.values(config).some((value) => value !== void 0);
   return hasAnyField ? config : void 0;
@@ -482,7 +484,7 @@ function unavailableRunGateway() {
 __name(unavailableRunGateway, "unavailableRunGateway");
 
 // src/durable.module.ts
-import { DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL as DURABLE_OPTIONS_CANONICAL7, STATE_STORE, STATE_STORE_CANONICAL as STATE_STORE_CANONICAL4, TRANSPORT, TRANSPORT_CANONICAL as TRANSPORT_CANONICAL3, WorkflowEngine as WorkflowEngine6 } from "@dudousxd/nestjs-durable-core";
+import { DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL as DURABLE_OPTIONS_CANONICAL7, RunGateway as RunGateway2, STATE_STORE, STATE_STORE_CANONICAL as STATE_STORE_CANONICAL4, TRANSPORT, TRANSPORT_CANONICAL as TRANSPORT_CANONICAL3, WorkflowEngine as WorkflowEngine6 } from "@dudousxd/nestjs-durable-core";
 import { Inject as Inject8, Injectable as Injectable12, Module } from "@nestjs/common";
 import { DiscoveryModule, ModuleRef } from "@nestjs/core";
 
@@ -1416,8 +1418,9 @@ TimerPoller = _ts_decorate9([
 ], TimerPoller);
 
 // src/tokens.ts
+import { RunGateway } from "@dudousxd/nestjs-durable-core";
 var CONTEXT_ACCESSOR = Symbol.for("@dudousxd/nestjs-context:accessor");
-var RUN_GATEWAY = Symbol.for("nestjs-durable:run-gateway");
+var RUN_GATEWAY = RunGateway;
 
 // src/workflow.registrar.ts
 import { DURABLE_OPTIONS_CANONICAL as DURABLE_OPTIONS_CANONICAL6, RemoteWorkflowExecutor, STATE_STORE_CANONICAL as STATE_STORE_CANONICAL3, WorkflowEngine as WorkflowEngine4, bindWorkflowClass, parseDuration as parseDuration2, sanitizeQueueToken, tenantGroup, workflowName as workflowName2 } from "@dudousxd/nestjs-durable-core";
@@ -1553,6 +1556,7 @@ var WorkflowRegistrar = class {
         tags: meta.tags,
         singleton: meta.singleton,
         executionTimeout: meta.executionTimeout,
+        requires: meta.requires,
         validateInput,
         searchAttributesSchema: meta.searchAttributes,
         onEvent: getOnEvents(meta, workflowCtor),
@@ -1883,14 +1887,13 @@ var RunGatewayBootstrap = class RunGatewayBootstrap2 {
 RunGatewayBootstrap = _ts_decorate12([
   Injectable12(),
   _ts_param8(1, Inject8(TRANSPORT_CANONICAL3)),
-  _ts_param8(2, Inject8(RUN_GATEWAY)),
   _ts_param8(3, Inject8(STATE_STORE_CANONICAL4)),
   _ts_param8(4, Inject8(DURABLE_OPTIONS_CANONICAL7)),
   _ts_metadata12("design:type", Function),
   _ts_metadata12("design:paramtypes", [
     typeof WorkflowEngine6 === "undefined" ? Object : WorkflowEngine6,
     Object,
-    typeof RunGateway === "undefined" ? Object : RunGateway,
+    typeof RunGateway2 === "undefined" ? Object : RunGateway2,
     Object,
     typeof DurableModuleOptions === "undefined" ? Object : DurableModuleOptions
   ])
@@ -2035,7 +2038,7 @@ var DurableModule = class _DurableModule {
         // or (for a thin worker, no `store`) a `ProxyRunGateway` over `transport` when given, else a
         // gateway whose every method rejects with a clear tenant error.
         {
-          provide: RUN_GATEWAY,
+          provide: RunGateway2,
           useFactory: /* @__PURE__ */ __name((options, store, engine) => {
             if (options.store !== void 0) {
               if (!store) {
@@ -2068,7 +2071,7 @@ var DurableModule = class _DurableModule {
         TRANSPORT,
         TRANSPORT_CANONICAL3,
         DURABLE_OPTIONS_CANONICAL7,
-        RUN_GATEWAY
+        RunGateway2
       ]
     };
   }