@dudousxd/nestjs-durable-core 0.58.0 → 0.59.0

package/dist/index.js

@@ -822,6 +822,358 @@ function eventMatches(payload, match) {
 }
 __name(eventMatches, "eventMatches");
 
+// src/handshake/descriptor.ts
+var CURRENT_PROTOCOL_VERSION = 1;
+var LEGACY_V1_PROTOCOL = {
+  version: 1,
+  range: [
+    1,
+    1
+  ]
+};
+var LEGACY_V1_CAPABILITIES = Object.freeze([
+  "saga",
+  "signals",
+  "search-attributes",
+  "priority",
+  "entities",
+  "child-workflows",
+  "singleton",
+  "schedules",
+  "continue-as-new",
+  "queries",
+  "cancellation"
+]);
+function isLegacyDescriptor(raw) {
+  return raw.protocol === void 0;
+}
+__name(isLegacyDescriptor, "isLegacyDescriptor");
+function normalizeDescriptor(raw) {
+  return {
+    instanceId: raw.instanceId,
+    runtime: raw.runtime,
+    sdk: raw.sdk ?? {
+      name: "unknown",
+      version: "0"
+    },
+    protocol: raw.protocol ?? {
+      ...LEGACY_V1_PROTOCOL
+    },
+    capabilities: raw.capabilities ?? [
+      ...LEGACY_V1_CAPABILITIES
+    ],
+    workflows: raw.workflows ?? [],
+    steps: raw.steps ?? [],
+    ...raw.partition !== void 0 ? {
+      partition: raw.partition
+    } : {},
+    ...raw.namespace !== void 0 ? {
+      namespace: raw.namespace
+    } : {},
+    startedAt: raw.startedAt ?? 0
+  };
+}
+__name(normalizeDescriptor, "normalizeDescriptor");
+function canonicalizeForHash(d) {
+  const set = /* @__PURE__ */ __name((xs) => [
+    ...new Set(xs)
+  ].sort(), "set");
+  return {
+    instanceId: d.instanceId,
+    runtime: d.runtime,
+    sdk: {
+      name: d.sdk.name,
+      version: d.sdk.version
+    },
+    protocol: {
+      version: d.protocol.version,
+      range: [
+        d.protocol.range[0],
+        d.protocol.range[1]
+      ]
+    },
+    capabilities: set(d.capabilities),
+    workflows: set(d.workflows),
+    steps: set(d.steps),
+    partition: d.partition ?? null,
+    namespace: d.namespace ?? null,
+    startedAt: d.startedAt
+  };
+}
+__name(canonicalizeForHash, "canonicalizeForHash");
+function fnv1a64Hex(input) {
+  const OFFSET = 0xcbf29ce484222325n;
+  const PRIME = 0x100000001b3n;
+  const MASK = 0xffffffffffffffffn;
+  let hash = OFFSET;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= BigInt(input.charCodeAt(i) & 255);
+    hash ^= BigInt(input.charCodeAt(i) >> 8 & 255);
+    hash = hash * PRIME & MASK;
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+__name(fnv1a64Hex, "fnv1a64Hex");
+function descriptorHash(descriptor) {
+  const canonical = canonicalizeForHash(normalizeDescriptor(descriptor));
+  return fnv1a64Hex(JSON.stringify(canonical));
+}
+__name(descriptorHash, "descriptorHash");
+function heartbeatStatus(descriptor, opts = {}) {
+  return {
+    ts: opts.ts ?? Date.now(),
+    status: opts.status ?? "up",
+    descriptorHash: descriptorHash(descriptor)
+  };
+}
+__name(heartbeatStatus, "heartbeatStatus");
+
+// src/handshake/negotiate.ts
+var rangesOverlap = /* @__PURE__ */ __name((a, b) => Math.max(a[0], b[0]) <= Math.min(a[1], b[1]), "rangesOverlap");
+var difference = /* @__PURE__ */ __name((a, b) => {
+  const bset = new Set(b);
+  return [
+    ...new Set(a)
+  ].filter((x) => !bset.has(x)).sort();
+}, "difference");
+var intersection = /* @__PURE__ */ __name((a, b) => {
+  const bset = new Set(b);
+  return [
+    ...new Set(a)
+  ].filter((x) => bset.has(x)).sort();
+}, "intersection");
+function negotiate(localRaw, remoteRaw, opts = {}) {
+  const local = normalizeDescriptor(localRaw);
+  const remote = normalizeDescriptor(remoteRaw);
+  const localRange = local.protocol.range;
+  const remoteRange = remote.protocol.range;
+  const shared = intersection(local.capabilities, remote.capabilities);
+  const missingOnRemote = difference(local.capabilities, remote.capabilities);
+  const missingOnLocal = difference(remote.capabilities, local.capabilities);
+  const capabilities = {
+    shared,
+    missingOnRemote,
+    missingOnLocal
+  };
+  if (!rangesOverlap(localRange, remoteRange)) {
+    return {
+      outcome: "incompatible",
+      negotiatedProtocol: null,
+      protocol: {
+        localRange,
+        remoteRange
+      },
+      capabilities,
+      reason: {
+        code: "protocol.incompatible",
+        message: `no common protocol major: local speaks [${localRange[0]}, ${localRange[1]}], remote speaks [${remoteRange[0]}, ${remoteRange[1]}]`,
+        detail: {
+          localRange,
+          remoteRange
+        }
+      },
+      local,
+      remote
+    };
+  }
+  const negotiatedProtocol = Math.min(localRange[1], remoteRange[1]);
+  const required = opts.required ?? [];
+  const missingRequired = difference(required, remote.capabilities);
+  if (missingRequired.length > 0) {
+    return {
+      outcome: "degraded",
+      negotiatedProtocol,
+      protocol: {
+        localRange,
+        remoteRange
+      },
+      capabilities,
+      reason: {
+        code: "capability.unavailable",
+        message: `remote is missing required capability(ies): ${missingRequired.join(", ")}`,
+        detail: {
+          missingRequired,
+          missingOnRemote,
+          missingOnLocal
+        }
+      },
+      local,
+      remote
+    };
+  }
+  if (missingOnRemote.length > 0 || missingOnLocal.length > 0) {
+    const parts = [];
+    if (missingOnRemote.length > 0) parts.push(`remote lacks ${missingOnRemote.join(", ")}`);
+    if (missingOnLocal.length > 0) parts.push(`local lacks ${missingOnLocal.join(", ")}`);
+    return {
+      outcome: "degraded",
+      negotiatedProtocol,
+      protocol: {
+        localRange,
+        remoteRange
+      },
+      capabilities,
+      reason: {
+        code: "capability.unavailable",
+        message: `capability mismatch: ${parts.join("; ")}`,
+        detail: {
+          missingOnRemote,
+          missingOnLocal
+        }
+      },
+      local,
+      remote
+    };
+  }
+  return {
+    outcome: "compatible",
+    negotiatedProtocol,
+    protocol: {
+      localRange,
+      remoteRange
+    },
+    capabilities,
+    local,
+    remote
+  };
+}
+__name(negotiate, "negotiate");
+
+// src/handshake/routing.ts
+function requiredCapabilities(handler) {
+  const list = Array.isArray(handler) ? handler : handler.requires ?? [];
+  return [
+    ...new Set(list)
+  ];
+}
+__name(requiredCapabilities, "requiredCapabilities");
+function canRoute(handler, worker) {
+  const required = requiredCapabilities(handler);
+  if (required.length === 0) return true;
+  const advertised = new Set(normalizeDescriptor(worker).capabilities);
+  return required.every((cap) => advertised.has(cap));
+}
+__name(canRoute, "canRoute");
+function missingCapabilities(handler, worker) {
+  const advertised = new Set(normalizeDescriptor(worker).capabilities);
+  return requiredCapabilities(handler).filter((cap) => !advertised.has(cap));
+}
+__name(missingCapabilities, "missingCapabilities");
+function capableWorkers(handler, workers) {
+  return workers.filter((w) => canRoute(handler, w));
+}
+__name(capableWorkers, "capableWorkers");
+function resolveRouting(handler, workers) {
+  const requires = requiredCapabilities(handler);
+  const capable = capableWorkers(handler, workers).map(normalizeDescriptor);
+  if (capable.length > 0) {
+    return {
+      status: "routable",
+      workers: capable,
+      requires
+    };
+  }
+  const suffix = requires.length > 0 ? ` (requires ${requires.join(", ")})` : "";
+  return {
+    status: "blocked",
+    reason: `blocked: no compatible worker${suffix}`,
+    requires
+  };
+}
+__name(resolveRouting, "resolveRouting");
+
+// src/handshake/dispatch-routing.ts
+function controlPlaneDescriptor(opts) {
+  const version = CURRENT_PROTOCOL_VERSION;
+  return {
+    instanceId: opts.instanceId,
+    runtime: "node",
+    sdk: opts.sdk ?? {
+      name: "@dudousxd/nestjs-durable-core",
+      version: String(version)
+    },
+    protocol: opts.protocol ?? {
+      version,
+      range: [
+        version,
+        version
+      ]
+    },
+    capabilities: opts.capabilities ?? [],
+    workflows: [],
+    steps: [],
+    ...opts.partition !== void 0 ? {
+      partition: opts.partition
+    } : {},
+    ...opts.namespace !== void 0 ? {
+      namespace: opts.namespace
+    } : {},
+    startedAt: opts.startedAt ?? 0
+  };
+}
+__name(controlPlaneDescriptor, "controlPlaneDescriptor");
+var WorkflowBlocked = class extends Error {
+  static {
+    __name(this, "WorkflowBlocked");
+  }
+  plan;
+  constructor(plan) {
+    super(plan.reason), this.plan = plan;
+    this.name = "WorkflowBlocked";
+  }
+};
+function planDispatch(requires, liveDescriptors, cp, token) {
+  const required = requiredCapabilities({
+    requires
+  });
+  const workers = liveDescriptors.map(normalizeDescriptor);
+  const capable = workers.filter((w) => canRoute({
+    requires
+  }, w));
+  const compatible = capable.filter((w) => negotiate(cp, w).outcome !== "incompatible");
+  if (compatible.length > 0) return {
+    status: "routable",
+    workers: compatible
+  };
+  if (capable.length > 0) {
+    const workerRanges = capable.map((w) => w.protocol.range);
+    return {
+      status: "blocked",
+      code: "protocol.incompatible",
+      reason: `blocked: no protocol-compatible worker${required.length > 0 ? ` (requires ${required.join(", ")})` : ""}`,
+      requires: required,
+      diagnostics: {
+        code: "protocol.incompatible",
+        token,
+        requires: required,
+        liveWorkers: workers.length,
+        controlPlaneRange: cp.protocol.range,
+        workerRanges,
+        controlPlane: cp,
+        workers
+      }
+    };
+  }
+  const advertised = new Set(workers.flatMap((w) => w.capabilities));
+  const missingCapabilities2 = required.filter((cap) => !advertised.has(cap));
+  return {
+    status: "blocked",
+    code: "capability.unavailable",
+    reason: `blocked: no compatible worker${required.length > 0 ? ` (requires ${required.join(", ")})` : ""}`,
+    requires: required,
+    diagnostics: {
+      code: "capability.unavailable",
+      token,
+      requires: required,
+      liveWorkers: workers.length,
+      missingCapabilities: missingCapabilities2,
+      controlPlane: cp,
+      workers
+    }
+  };
+}
+__name(planDispatch, "planDispatch");
+
 // src/tenant-group.ts
 function tenantGroup(baseGroup, tenant) {
   return tenant !== void 0 && tenant !== "" && tenant !== "default" ? `${baseGroup}@${tenant}` : baseGroup;
@@ -1086,6 +1438,22 @@ var TransportPool = class {
       transport.onStartRun?.(handler);
     }
   }
+  /**
+  * The live handshake descriptors advertised for `group` (design §7.2), merged across every transport
+  * that can report them. Returns `[]` when NO transport implements
+  * {@link Transport.readWorkerDescriptors} (a pure in-process pool) OR when descriptors are supported
+  * but none is published — both are the "guard disengaged / legacy assume-compatible" case, so the
+  * engine's routing guard treats an empty result identically (design §7.7).
+  */
+  async readWorkerDescriptors(group) {
+    const descriptors = [];
+    for (const { transport } of this.transports) {
+      if (transport.readWorkerDescriptors) {
+        descriptors.push(...await transport.readWorkerDescriptors(group));
+      }
+    }
+    return descriptors;
+  }
   /** Distinct worker groups with a live heartbeat, merged across every transport that can report it. */
   async listWorkerGroups() {
     const groups = /* @__PURE__ */ new Set();
@@ -1181,6 +1549,8 @@ function resolveStepPolicy(config, opts) {
   if (jitter !== void 0) policy.jitter = jitter;
   const timeoutMs = opts?.timeoutMs ?? config?.timeoutMs;
   if (timeoutMs !== void 0) policy.timeoutMs = timeoutMs;
+  const requires = opts?.requires ?? config?.requires;
+  if (requires !== void 0) policy.requires = requires;
   return policy;
 }
 __name(resolveStepPolicy, "resolveStepPolicy");
@@ -1886,6 +2256,10 @@ var WorkflowEngine = class {
   eventBufferTtlMs;
   remoteRedispatchMs;
   remoteRedispatchMax;
+  /** How long a `blocked` run waits before the recovery poll re-checks the live fleet (design §7.5). */
+  blockedPollMs;
+  /** This engine's control-plane handshake descriptor — negotiated against each worker (design §7.3). */
+  cpDescriptor;
   webhookUrl;
   traceparent;
   context;
@@ -1957,6 +2331,13 @@ var WorkflowEngine = class {
     this.eventBufferTtlMs = deps.eventBufferTtlMs || void 0;
     this.remoteRedispatchMs = deps.remoteRedispatchMs || void 0;
     this.remoteRedispatchMax = Math.max(1, deps.remoteRedispatchMax ?? 10);
+    this.blockedPollMs = deps.blockedPollMs ?? 5e3;
+    this.cpDescriptor = controlPlaneDescriptor({
+      instanceId: `cp-${this.instanceId}`,
+      ...this.namespace !== void 0 ? {
+        namespace: this.namespace
+      } : {}
+    });
     this.webhookUrl = deps.webhookUrl;
     this.traceparent = deps.traceparent;
     this.context = deps.context;
@@ -2110,6 +2491,7 @@ var WorkflowEngine = class {
       searchAttributesSchema: opts?.searchAttributesSchema,
       onEvent: opts?.onEvent,
       eventBatch: opts?.eventBatch,
+      requires: opts?.requires,
       // A real, retained in-process body — so `workflowBody` can hand it to an in-app worker, and so
       // it is NOT confused with the throwing stub `registerRemote` installs for a body-less remote.
       hasBody: true
@@ -2158,6 +2540,7 @@ var WorkflowEngine = class {
       singleton: opts.singleton,
       executionTimeoutMs: opts.executionTimeout != null ? parseDuration(opts.executionTimeout) : void 0,
       validateInput: opts.validateInput,
+      requires: opts.requires,
       remote: {
         group: opts.group,
         executor: opts.executor
@@ -2641,9 +3024,13 @@ var WorkflowEngine = class {
   */
   async resumeDueTimers(nowMs = this.clock()) {
     const due = await this.store.listDueTimers(nowMs, this.namespace);
-    if (due.length === 0) return [];
+    const blocked = await this.dueBlockedRuns(nowMs);
+    if (due.length === 0 && blocked.length === 0) return [];
     const waiterByRun = indexWaitersByRun(await this.store.listSignalWaiters(""));
-    return this.resumeLeased(due, nowMs, (run) => this.reconcileSignalWaiter(run, waiterByRun.get(run.id)));
+    return this.resumeLeased([
+      ...due,
+      ...blocked
+    ], nowMs, (run) => this.reconcileSignalWaiter(run, waiterByRun.get(run.id)));
   }
   /**
   * The reconcile safety net's per-run check (see {@link resumeDueTimers}): if this suspended run has
@@ -3552,6 +3939,7 @@ var WorkflowEngine = class {
         error: outcome.error
       };
     }
+    if (outcome.kind === "blocked") return this.parkBlocked(run, outcome.blocked);
     const latest = await this.store.getRun(run.id);
     if (latest?.status === "cancelled") {
       return {
@@ -3651,6 +4039,8 @@ var WorkflowEngine = class {
         status: "suspended"
       };
     }
+    const wfPlan = await this.planRoute(tenantGroup(sanitizeQueueToken(remote.group), void 0), registered.requires);
+    if (wfPlan?.status === "blocked") return this.parkBlocked(run, wfPlan);
     const history = await this.remoteHistory(run.id);
     if (remote.executor.dispatch) {
       const taskId = `${run.id}:wf:${globalThis.crypto.randomUUID().slice(0, 8)}`;
@@ -4074,6 +4464,15 @@ var WorkflowEngine = class {
           status: "completed"
         };
       }
+      if (err instanceof WorkflowBlocked) {
+        if (this.cancelRequested.has(run.id)) {
+          return this.compensateAndCancel(run, compensations, replay);
+        }
+        return this.settleRun(run, {
+          kind: "blocked",
+          blocked: err.plan
+        });
+      }
       if (err instanceof WorkflowSuspended) {
         if (this.cancelRequested.has(run.id)) {
           return this.compensateAndCancel(run, compensations, replay);
@@ -4420,6 +4819,85 @@ var WorkflowEngine = class {
       run: result
     };
   }
+  /**
+  * Plan a dispatch to `token` for a handler requiring `requires` (handshake design §7.5). Returns:
+  * - `undefined` — NO live descriptors published on this token: the guard does not engage, so a
+  *   pre-handshake fleet (or an in-process transport that advertises none) keeps flowing exactly as
+  *   before (design §7.7);
+  * - a `routable` plan — ≥1 live worker is capability-capable AND protocol-compatible (dispatch);
+  * - a `blocked` plan — descriptors exist but none can run it (park the run, never dispatch into it).
+  */
+  async planRoute(token, requires) {
+    const descriptors = await this.pool.readWorkerDescriptors(token);
+    if (descriptors.length === 0) return void 0;
+    return planDispatch(requires ?? [], descriptors, this.cpDescriptor, token);
+  }
+  /** Throw {@link WorkflowBlocked} when no live worker can run a dispatch to `token` — so the caller's
+  *  run-execution catch parks the run `blocked` (with the plan) instead of persisting a `pending`
+  *  checkpoint + dispatching into a queue nobody consumes (design §7.5). A no-op when the guard does
+  *  not engage (no descriptors) or a capable+compatible worker exists. */
+  async ensureRoutable(token, requires) {
+    const plan = await this.planRoute(token, requires);
+    if (plan?.status === "blocked") throw new WorkflowBlocked(plan);
+  }
+  /**
+  * Park a run `blocked` (handshake design §7.5/§7.6): no live worker on its next-dispatch group is
+  * capability-capable + protocol-compatible. Persists the `blocked` status with a human reason + the
+  * machine `code` + a `wakeAt` so the blocked-recovery poll re-drives it, emits the LOUD structured
+  * `capability.unavailable`/`protocol.incompatible` diagnostics (both descriptors + the precise delta),
+  * and releases the run lease so any instance can re-drive it. Re-checks the persisted status first so
+  * a concurrent cancel/complete is never clobbered. `releaseRunLock` is idempotent, so a caller whose
+  * own `finally` also releases (the run-execution path) is safe.
+  */
+  async parkBlocked(run, blocked) {
+    const current = await this.store.getRun(run.id);
+    if (current && (current.status === "cancelled" || current.status === "completed")) {
+      await this.store.releaseRunLock(run.id);
+      return {
+        runId: run.id,
+        status: current.status,
+        output: current.output,
+        error: current.error
+      };
+    }
+    const error = {
+      message: blocked.reason,
+      code: blocked.code,
+      retryable: true
+    };
+    await this.store.updateRun(run.id, {
+      status: "blocked",
+      error,
+      wakeAt: this.clock() + this.blockedPollMs,
+      updatedAt: /* @__PURE__ */ new Date()
+    });
+    this.emit({
+      type: "run.blocked",
+      runId: run.id,
+      workflow: run.workflow,
+      namespace: run.namespace,
+      error,
+      requires: blocked.requires,
+      diagnostics: blocked.diagnostics
+    });
+    await this.store.releaseRunLock(run.id);
+    return {
+      runId: run.id,
+      status: "blocked",
+      error
+    };
+  }
+  /** Runs parked `blocked` whose recovery poll is due (`wakeAt <= nowMs`), namespace-scoped like
+  *  {@link resumeDueTimers}. Re-driving one re-checks the live fleet: it dispatches if a
+  *  capable+compatible worker has appeared, else re-parks with a fresh `wakeAt` (design §7.5). */
+  async dueBlockedRuns(nowMs) {
+    const blocked = await this.store.listRuns({
+      statuses: [
+        "blocked"
+      ]
+    });
+    return blocked.filter((r) => (this.namespace === void 0 || r.namespace === void 0 || r.namespace === this.namespace) && r.wakeAt !== void 0 && r.wakeAt <= nowMs);
+  }
   async callRemote(runId, seq, step, input, queue, transport, replay, admission) {
     const existing = replay?.get(seq) ?? await this.store.getCheckpoint(runId, seq);
     if (existing && existing.name !== step.name) {
@@ -4485,6 +4963,7 @@ var WorkflowEngine = class {
       if (this.clock() < existing.wakeAt) throw new WorkflowSuspended(existing.wakeAt);
       attempt = existing.attempts + 1;
     }
+    await this.ensureRoutable(tenantGroup(sanitizeQueueToken(step.name), step.partition), step.requires);
     const id = stepId(runId, seq);
     if (queue && this.admission.handles(queue)) {
       const decision = await this.admission.tryAdmit(queue, {
@@ -4671,6 +5150,7 @@ var WorkflowEngine = class {
   /** In-memory await path for a remote step with a liveness `timeoutMs` (re-dispatch on timeout). */
   async callRemoteInMemory(runId, seq, step, input, transport) {
     if (this.pool.size === 0) throw new Error("remote steps require a Transport");
+    await this.ensureRoutable(tenantGroup(sanitizeQueueToken(step.name), step.partition), step.requires);
     const validInput = step.input ? step.input.parse(input) : input;
     const id = stepId(runId, seq);
     const enqueuedAt = /* @__PURE__ */ new Date();
@@ -5569,6 +6049,7 @@ var InMemoryTransport = class {
 };
 export {
   CONTROL_FLOW_SIGNAL,
+  CURRENT_PROTOCOL_VERSION,
   CodecStateStore,
   ContinueAsNew,
   DURABLE_OPTIONS,
@@ -5585,6 +6066,8 @@ export {
   InMemoryAdmissionBackend,
   InMemoryStateStore,
   InMemoryTransport,
+  LEGACY_V1_CAPABILITIES,
+  LEGACY_V1_PROTOCOL,
   NonDeterminismError,
   QueueController,
   RemoteStepError,
@@ -5599,6 +6082,7 @@ export {
   TRANSPORT,
   TRANSPORT_CANONICAL,
   WORKFLOW_NAME_KEY,
+  WorkflowBlocked,
   WorkflowEngine,
   WorkflowSuspended,
   applyAttributeQuery,
@@ -5606,23 +6090,35 @@ export {
   attributeOperand,
   bindWorkflowClass,
   breakpointToken,
+  canRoute,
+  capableWorkers,
   classifyWaiterToken,
   collectMetrics,
+  controlPlaneDescriptor,
   createStepLogger,
   currentWorkflowCtx,
+  descriptorHash,
   eventMatchOf,
   eventMatches,
   eventNameOf,
   eventPrefix,
   eventToken,
+  heartbeatStatus,
   indexWaitersByRun,
   isEventToken,
+  isLegacyDescriptor,
   isWorkflowControlFlowSignal,
   matchesAttributes,
+  missingCapabilities,
+  negotiate,
   normalizeAttributeRows,
+  normalizeDescriptor,
   parseDuration,
+  planDispatch,
   prevCronFireMs,
   readSearchAttributes,
+  requiredCapabilities,
+  resolveRouting,
   resolveRunWaiting,
   runInWorkflowCtx,
   runSchedules,