@dudousxd/nestjs-durable-core 0.94.0 → 0.95.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
@@ -3186,6 +3186,18 @@ interface Transport {
3186
3186
  * taking runs and resolves once the runs in flight have settled. Pair with {@link dispatchRuns}.
3187
3187
  */
3188
3188
  onDispatchedRun?(handler: (run: RunDispatch) => Promise<void>, opts: RunConsumerOptions): () => Promise<void>;
3189
+ /**
3190
+ * The live consumers of the run queue `opts` names ({@link onDispatchedRun}): the engine instances
3191
+ * executing this deployment's IN-PROCESS workflow bodies. They take no task queue, so they never
3192
+ * appear in the worker-heartbeat keyspace {@link listWorkerGroups}/{@link groupHealth} read, and a
3193
+ * control plane driving its own workflows looked like it had no worker at all. Kept in a keyspace of
3194
+ * its own on purpose: a worker heartbeat makes its group a target for convention routing and the
3195
+ * workflow directory, and nothing consumes a task queue under these names.
3196
+ *
3197
+ * Optional, like {@link groupHealth}: only a broker transport that can introspect liveness (BullMQ)
3198
+ * implements it. The engine folds the result into {@link WorkflowEngine.workerHealth}.
3199
+ */
3200
+ liveRunConsumers?(opts?: RunQueueOptions): Promise<WorkerHeartbeat[]>;
3189
3201
  /** control plane → tenant worker: publish a correlated {@link RunReply} on `<effectivePrefix>-run-reply`
3190
3202
  * (pub/sub; every tenant subscribes and filters by `requestId`). */
3191
3203
  publishRunReply?(reply: RunReply): Promise<void>;
@@ -7368,9 +7380,24 @@ declare class WorkflowEngine {
7368
7380
  /** Per-group worker health (queue backlog + live worker heartbeats). Covers {@link knownGroups}
7369
7381
  * (so a registered group with backlog and ZERO workers still reports — the alert case) UNION the
7370
7382
  * groups discovered from live heartbeats (so a local-step group like `pipeline`, not derivable
7371
- * from registrations, shows once its workers beat). Empty when no transport can introspect health
7372
- * (only the BullMQ transport implements `groupHealth`). */
7383
+ * from registrations, shows once its workers beat) UNION this engine's in-process workflows while
7384
+ * the run queue has a live consumer (see {@link inProcessWorkflowHealth}). Empty when no transport
7385
+ * can introspect health (only the BullMQ transport implements `groupHealth`). */
7373
7386
  workerHealth(extra?: string[]): Promise<GroupHealth[]>;
7387
+ /**
7388
+ * The workflows this deployment executes IN-PROCESS — registered here with a body, so a run of one
7389
+ * is driven by whichever engine instance takes it off the run queue — and the instances consuming
7390
+ * that queue right now. Those instances ARE the workers of these workflows, yet they consume no task
7391
+ * queue and so never wrote a worker heartbeat: a control plane running its own workflows showed
7392
+ * "0 live workers" while it completed runs. Each workflow is reported under the token a worker
7393
+ * serving it would use (`tenantGroup(name, namespace)`), with the run-queue consumers as its live
7394
+ * workers. The engine's internal `__` workflows are left out.
7395
+ *
7396
+ * Nothing when no run-queue consumer is live (a transport that cannot report one, or no driving
7397
+ * instance): the workflows are not served by anything the transport can see, and claiming a worker
7398
+ * for them would hide a starved queue.
7399
+ */
7400
+ private inProcessWorkflowHealth;
7374
7401
  /**
7375
7402
  * What workflows the LIVE fleet announces it can execute — the deployment-wide registry a picker
7376
7403
  * ("call this existing workflow") needs, and the one question this engine's own registry cannot
package/dist/index.d.ts CHANGED
@@ -3186,6 +3186,18 @@ interface Transport {
3186
3186
  * taking runs and resolves once the runs in flight have settled. Pair with {@link dispatchRuns}.
3187
3187
  */
3188
3188
  onDispatchedRun?(handler: (run: RunDispatch) => Promise<void>, opts: RunConsumerOptions): () => Promise<void>;
3189
+ /**
3190
+ * The live consumers of the run queue `opts` names ({@link onDispatchedRun}): the engine instances
3191
+ * executing this deployment's IN-PROCESS workflow bodies. They take no task queue, so they never
3192
+ * appear in the worker-heartbeat keyspace {@link listWorkerGroups}/{@link groupHealth} read, and a
3193
+ * control plane driving its own workflows looked like it had no worker at all. Kept in a keyspace of
3194
+ * its own on purpose: a worker heartbeat makes its group a target for convention routing and the
3195
+ * workflow directory, and nothing consumes a task queue under these names.
3196
+ *
3197
+ * Optional, like {@link groupHealth}: only a broker transport that can introspect liveness (BullMQ)
3198
+ * implements it. The engine folds the result into {@link WorkflowEngine.workerHealth}.
3199
+ */
3200
+ liveRunConsumers?(opts?: RunQueueOptions): Promise<WorkerHeartbeat[]>;
3189
3201
  /** control plane → tenant worker: publish a correlated {@link RunReply} on `<effectivePrefix>-run-reply`
3190
3202
  * (pub/sub; every tenant subscribes and filters by `requestId`). */
3191
3203
  publishRunReply?(reply: RunReply): Promise<void>;
@@ -7368,9 +7380,24 @@ declare class WorkflowEngine {
7368
7380
  /** Per-group worker health (queue backlog + live worker heartbeats). Covers {@link knownGroups}
7369
7381
  * (so a registered group with backlog and ZERO workers still reports — the alert case) UNION the
7370
7382
  * groups discovered from live heartbeats (so a local-step group like `pipeline`, not derivable
7371
- * from registrations, shows once its workers beat). Empty when no transport can introspect health
7372
- * (only the BullMQ transport implements `groupHealth`). */
7383
+ * from registrations, shows once its workers beat) UNION this engine's in-process workflows while
7384
+ * the run queue has a live consumer (see {@link inProcessWorkflowHealth}). Empty when no transport
7385
+ * can introspect health (only the BullMQ transport implements `groupHealth`). */
7373
7386
  workerHealth(extra?: string[]): Promise<GroupHealth[]>;
7387
+ /**
7388
+ * The workflows this deployment executes IN-PROCESS — registered here with a body, so a run of one
7389
+ * is driven by whichever engine instance takes it off the run queue — and the instances consuming
7390
+ * that queue right now. Those instances ARE the workers of these workflows, yet they consume no task
7391
+ * queue and so never wrote a worker heartbeat: a control plane running its own workflows showed
7392
+ * "0 live workers" while it completed runs. Each workflow is reported under the token a worker
7393
+ * serving it would use (`tenantGroup(name, namespace)`), with the run-queue consumers as its live
7394
+ * workers. The engine's internal `__` workflows are left out.
7395
+ *
7396
+ * Nothing when no run-queue consumer is live (a transport that cannot report one, or no driving
7397
+ * instance): the workflows are not served by anything the transport can see, and claiming a worker
7398
+ * for them would hide a starved queue.
7399
+ */
7400
+ private inProcessWorkflowHealth;
7374
7401
  /**
7375
7402
  * What workflows the LIVE fleet announces it can execute — the deployment-wide registry a picker
7376
7403
  * ("call this existing workflow") needs, and the one question this engine's own registry cannot
package/dist/index.js CHANGED
@@ -5023,6 +5023,24 @@ var TransportPool = class {
5023
5023
  return stops;
5024
5024
  }
5025
5025
  /**
5026
+ * The live run-queue consumers ({@link Transport.liveRunConsumers}) across every transport that
5027
+ * reports them, one per instance (its latest beat): an engine consuming the run queue of two
5028
+ * pinned transports is still one process.
5029
+ */
5030
+ async liveRunConsumers(opts) {
5031
+ const byInstance = /* @__PURE__ */ new Map();
5032
+ for (const { transport } of this.transports) {
5033
+ if (!transport.liveRunConsumers) continue;
5034
+ for (const beat of await transport.liveRunConsumers(opts)) {
5035
+ const seen = byInstance.get(beat.instanceId);
5036
+ if (!seen || beat.lastBeatAt > seen.lastBeatAt) byInstance.set(beat.instanceId, beat);
5037
+ }
5038
+ }
5039
+ return [
5040
+ ...byInstance.values()
5041
+ ];
5042
+ }
5043
+ /**
5026
5044
  * The live handshake descriptors advertised for `group` (design §7.2), merged across every transport
5027
5045
  * that can report them. Returns `[]` when NO transport implements
5028
5046
  * {@link Transport.readWorkerDescriptors} (a pure in-process pool) OR when descriptors are supported
@@ -11492,13 +11510,16 @@ var WorkflowEngine = class _WorkflowEngine {
11492
11510
  /** Per-group worker health (queue backlog + live worker heartbeats). Covers {@link knownGroups}
11493
11511
  * (so a registered group with backlog and ZERO workers still reports — the alert case) UNION the
11494
11512
  * groups discovered from live heartbeats (so a local-step group like `pipeline`, not derivable
11495
- * from registrations, shows once its workers beat). Empty when no transport can introspect health
11496
- * (only the BullMQ transport implements `groupHealth`). */
11513
+ * from registrations, shows once its workers beat) UNION this engine's in-process workflows while
11514
+ * the run queue has a live consumer (see {@link inProcessWorkflowHealth}). Empty when no transport
11515
+ * can introspect health (only the BullMQ transport implements `groupHealth`). */
11497
11516
  async workerHealth(extra = []) {
11517
+ const inProcess = await this.inProcessWorkflowHealth();
11498
11518
  const groups = /* @__PURE__ */ new Set([
11499
11519
  ...this.knownGroups(extra),
11500
11520
  ...await this.pool.listWorkerGroups(),
11501
- ...await this.inflightStepGroups()
11521
+ ...await this.inflightStepGroups(),
11522
+ ...inProcess.groups
11502
11523
  ]);
11503
11524
  const workflowTokens = /* @__PURE__ */ new Set();
11504
11525
  for (const def of this.workflows.values()) {
@@ -11511,14 +11532,54 @@ var WorkflowEngine = class _WorkflowEngine {
11511
11532
  if (!health) continue;
11512
11533
  const at = group.lastIndexOf("@");
11513
11534
  const baseToken = at === -1 ? group : group.slice(0, at);
11535
+ const consumers = inProcess.groups.has(group) ? inProcess.consumers.filter((c) => !health.liveWorkers.some((w) => w.instanceId === c.instanceId)).map((c) => ({
11536
+ ...c,
11537
+ group
11538
+ })) : [];
11514
11539
  out.push({
11515
11540
  ...health,
11541
+ liveWorkers: [
11542
+ ...health.liveWorkers,
11543
+ ...consumers
11544
+ ],
11516
11545
  kind: workflowTokens.has(baseToken) ? "workflow" : "step"
11517
11546
  });
11518
11547
  }
11519
11548
  return out;
11520
11549
  }
11521
11550
  /**
11551
+ * The workflows this deployment executes IN-PROCESS — registered here with a body, so a run of one
11552
+ * is driven by whichever engine instance takes it off the run queue — and the instances consuming
11553
+ * that queue right now. Those instances ARE the workers of these workflows, yet they consume no task
11554
+ * queue and so never wrote a worker heartbeat: a control plane running its own workflows showed
11555
+ * "0 live workers" while it completed runs. Each workflow is reported under the token a worker
11556
+ * serving it would use (`tenantGroup(name, namespace)`), with the run-queue consumers as its live
11557
+ * workers. The engine's internal `__` workflows are left out.
11558
+ *
11559
+ * Nothing when no run-queue consumer is live (a transport that cannot report one, or no driving
11560
+ * instance): the workflows are not served by anything the transport can see, and claiming a worker
11561
+ * for them would hide a starved queue.
11562
+ */
11563
+ async inProcessWorkflowHealth() {
11564
+ const groups = /* @__PURE__ */ new Set();
11565
+ for (const def of this.workflows.values()) {
11566
+ if (def.remote || def.hasBody === false || def.name.startsWith("__")) continue;
11567
+ groups.add(tenantGroup(sanitizeQueueToken(def.name), this.namespace));
11568
+ }
11569
+ if (groups.size === 0) return {
11570
+ groups,
11571
+ consumers: []
11572
+ };
11573
+ const consumers = await this.pool.liveRunConsumers({
11574
+ namespace: this.namespace
11575
+ }).catch(() => []);
11576
+ if (consumers.length === 0) groups.clear();
11577
+ return {
11578
+ groups,
11579
+ consumers
11580
+ };
11581
+ }
11582
+ /**
11522
11583
  * What workflows the LIVE fleet announces it can execute — the deployment-wide registry a picker
11523
11584
  * ("call this existing workflow") needs, and the one question this engine's own registry cannot
11524
11585
  * answer. {@link workflowBody} answers only for this process, and a missing body is ambiguous: it