@wildo-ai/saas-minions-lib 1.1.13 → 1.1.14

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wildo-ai/saas-minions-lib",
3
- "version": "1.1.13",
3
+ "version": "1.1.14",
4
4
  "description": "Node minion runtime host layer for Wildo SaaS applications",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "author": "Wildo AI",
@@ -30,14 +30,13 @@
30
30
  "test:watch": "vitest"
31
31
  },
32
32
  "dependencies": {
33
- "@wildo-ai/platform-config-lib": "1.1.13",
34
- "@wildo-ai/saas-backend-lib": "1.1.13",
35
- "@wildo-ai/saas-models": "1.1.13",
33
+ "@wildo-ai/platform-config-lib": "1.1.14",
34
+ "@wildo-ai/saas-backend-lib": "1.1.14",
35
+ "@wildo-ai/saas-models": "1.1.14",
36
36
  "reflect-metadata": "0.2.2"
37
37
  },
38
38
  "devDependencies": {
39
39
  "@types/node": "^24.0.15",
40
- "@types/amqplib": "^0.10.8",
41
40
  "rimraf": "^6.1.4",
42
41
  "tsc-alias": "1.8.16",
43
42
  "tsc-watch": "7.2.1",
@@ -1,12 +1,11 @@
1
1
  import 'reflect-metadata';
2
2
  import { beforeEach, describe, expect, it, vi } from 'vitest';
3
- import type { Channel, ConsumeMessage } from 'amqplib';
4
3
  import type {
5
4
  JobPayloadStorageBackendService, JobStatusTrackingBackendService, LoggerService, WorkerShutdownManagerBackendService,
6
- RabbitMQAdapterBackendService, ScheduledExecutionResolver, ScheduledMessageVerifierBackendService,
5
+ QueueAdapter, QueueConsumeMessage, QueueMessageAcknowledger, ScheduledExecutionResolver, ScheduledMessageVerifierBackendService,
7
6
  } from '@wildo-ai/saas-backend-lib';
8
- import { JobPayloadSchema, JobType, ScheduledDeliveryLateness, ScheduledReplaySafety, ScheduledReviewOutcome, type JobPayload } from '@wildo-ai/saas-models';
9
- import { ScheduledDeliveryVerdict } from '@wildo-ai/saas-backend-lib';
7
+ import { JobInitiator, JobPayloadSchema, JobType, QueueNamingUtils, ScheduledDeliveryLateness, ScheduledReplaySafety, ScheduledReviewOutcome, type JobPayload } from '@wildo-ai/saas-models';
8
+ import { InMemoryQueueAdapterBackendService, ScheduledDeliveryVerdict } from '@wildo-ai/saas-backend-lib';
10
9
  import { MinionTickConsumerBackendService } from '../minion-tick-consumer.backend.service';
11
10
 
12
11
  // This suite pins the minion authentication/lifecycle adapter. Durable concurrency
@@ -30,11 +29,12 @@ vi.mock('@wildo-ai/saas-backend-lib', async (importOriginal) => ({
30
29
  /** The verifier's answer for an authentic, on-time tick (`ScheduledDeliveryVerdict.ADMISSIBLE`). */
31
30
  const onTime = (value: unknown) => ({ verdict: ScheduledDeliveryVerdict.ADMISSIBLE, value });
32
31
 
33
- function fixture() {
34
- let deliver: ((message: ConsumeMessage, channel: Channel) => Promise<void>) | undefined;
32
+ function fixture(adapterOverride?: QueueAdapter) {
33
+ let deliver: ((message: QueueConsumeMessage, acknowledger: QueueMessageAcknowledger) => Promise<void>) | undefined;
34
+ // The queue PORT only (#2303): no amqplib channel, so the consumer runs on any adapter.
35
35
  const adapter = {
36
36
  isConnected: vi.fn(() => true),
37
- getTopologyChannel: vi.fn().mockResolvedValue({ assertQueue: vi.fn() }),
37
+ assertQueue: vi.fn(),
38
38
  consume: vi.fn(async (_queue: string, callback: typeof deliver) => { deliver = callback; }),
39
39
  cancelConsumer: vi.fn(),
40
40
  };
@@ -47,7 +47,7 @@ function fixture() {
47
47
  const logger = { debugByType: () => vi.fn(), setDebugTypeLogging: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
48
48
  const shutdown = { jobStarted: vi.fn(), jobCompleted: vi.fn(), registerStopHandler: vi.fn() };
49
49
  const service = new MinionTickConsumerBackendService(
50
- adapter as unknown as RabbitMQAdapterBackendService,
50
+ adapterOverride ?? (adapter as unknown as QueueAdapter),
51
51
  verifier as unknown as ScheduledMessageVerifierBackendService,
52
52
  logger as unknown as LoggerService,
53
53
  {} as JobStatusTrackingBackendService,
@@ -59,7 +59,7 @@ function fixture() {
59
59
  service, adapter, verifier, tick, logger, channel, shutdown,
60
60
  deliver: async () => {
61
61
  if (!deliver) throw new Error('consumer was not registered');
62
- await deliver({ content: Buffer.from('signed-jwt') } as ConsumeMessage, channel as unknown as Channel);
62
+ await deliver({ content: Buffer.from('signed-jwt'), fields: { redelivered: false }, properties: {} }, channel);
63
63
  expect(shutdown.jobStarted.mock.calls.length).toBe(shutdown.jobCompleted.mock.calls.length);
64
64
  },
65
65
  };
@@ -105,6 +105,8 @@ describe('minion scheduled coordination boundary', () => {
105
105
  evidencePolicy: { policyRef: 'tick-v1', retainForMs: 86400000, resultFields: [] } });
106
106
  // The runner is started on a QUEUE only; the platform id shapes the queue name and is never handed to the scanner.
107
107
  expect(coordinator.start).toHaveBeenCalledWith(expect.stringContaining('worker'), expect.any(Function));
108
+ // #2303: the minion declares its tick queue through the port, durable and replicated (a quorum queue on RabbitMQ).
109
+ expect(f.adapter.assertQueue).toHaveBeenCalledWith(expect.stringContaining('minion-tick.worker'), { durable: true, replicated: true });
108
110
  expect(coordinator.admit).not.toHaveBeenCalled();
109
111
  // The consumer ADMITS (durable receipt), acknowledges, and only then LAUNCHES the run: holding the
110
112
  // delivery for the run's length left later ticks unreceived past their five-minute token.
@@ -259,4 +261,26 @@ describe('minion scheduled coordination boundary', () => {
259
261
  expect(coordinator.recordLateDelivery).not.toHaveBeenCalled();
260
262
  expect(f.channel.nack).toHaveBeenCalledWith(expect.anything(), false, false);
261
263
  });
264
+
265
+ // #2303: the consumer depends on the queue PORT, so it runs on an adapter that is not RabbitMQ. On the in-memory one a
266
+ // published tick is received, admitted and settled: acknowledged through the port, so nothing is left unsettled (the
267
+ // queue depth alone is 0 before the handler runs). Mutations: reach for the RabbitMQ topology channel again → `start`
268
+ // throws here, where no channel exists; drop the acknowledgement → the unsettled count stays 1.
269
+ it('receives, admits and settles a tick on the in-memory adapter, with no broker', async () => {
270
+ const logger = { debugByType: () => vi.fn(), setDebugTypeLogging: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
271
+ const memory = new InMemoryQueueAdapterBackendService(logger as unknown as LoggerService);
272
+ await memory.connect();
273
+ const f = fixture(memory);
274
+ await f.service.start({ applicationId: 'app-a', minionName: 'worker', handler: vi.fn() });
275
+ const queueName = QueueNamingUtils.buildMinionTickQueueName('app-a', 'worker');
276
+ await memory.publish(queueName, JobPayloadSchema.parse({
277
+ jobId: f.tick.jobId, jobType: JobType.MINION_TICK, applicationId: 'app-a', minionName: 'worker', inputDataJson: '{}',
278
+ initiatedBy: JobInitiator.CRONTAB, createdAt: new Date(), maxRetries: 0,
279
+ }));
280
+ await vi.waitFor(() => expect(coordinator.admit).toHaveBeenCalledTimes(1));
281
+ await vi.waitFor(() => expect(memory.getUnsettledCount(queueName)).toBe(0));
282
+ expect(await memory.getQueueDepth(queueName)).toBe(0);
283
+ await f.service.stop();
284
+ await memory.close();
285
+ });
262
286
  });
@@ -1,9 +1,7 @@
1
1
  import { inject, injectable } from 'inversify';
2
- import type { Channel, ConsumeMessage } from 'amqplib';
3
2
  import {
4
3
  describeCaughtError,
5
4
  LoggerService,
6
- RabbitMQAdapterBackendService,
7
5
  SAAS_SERVICE_TYPES,
8
6
  ScheduledMessageVerifierBackendService,
9
7
  ScheduledDeliveryVerdict,
@@ -13,9 +11,13 @@ import {
13
11
  WorkerShutdownManagerBackendService,
14
12
  type ScheduledExecutionResolver,
15
13
  type MinionTickJobToken,
14
+ type QueueAdapter,
15
+ type QueueConsumeMessage,
16
+ type QueueMessageAcknowledger,
17
+ assertMinionTickQueue,
16
18
  } from '@wildo-ai/saas-backend-lib';
17
19
  import {
18
- QueueNamingUtils, JobPayloadSchema, JobType, JobInitiator, JobStatus,
20
+ JobPayloadSchema, JobType, JobInitiator, JobStatus,
19
21
  type JobExecution, type ScheduledAttemptContext, type ScheduledEvidencePolicy, type ScheduledRecoveryPolicy, type ScheduledReconciliationResult,
20
22
  } from '@wildo-ai/saas-models';
21
23
 
@@ -65,8 +67,13 @@ export class MinionTickConsumerBackendService {
65
67
  protected readonly logDebug: (message: string, context?: Record<string, unknown>) => void;
66
68
 
67
69
  constructor(
68
- @inject(SAAS_SERVICE_TYPES.RabbitMQAdapterService)
69
- private readonly adapter: RabbitMQAdapterBackendService,
70
+ /**
71
+ * The queue PORT (#2303), not the RabbitMQ class: the token binds whichever adapter the runtime selected
72
+ * (`bindQueueAdapter`), so this consumer runs on any of them. It needs only a declaration, a subscription and the
73
+ * settlement of each delivery.
74
+ */
75
+ @inject(SAAS_SERVICE_TYPES.QueueAdapterService)
76
+ private readonly adapter: QueueAdapter,
70
77
  @inject(SAAS_SERVICE_TYPES.ScheduledMessageVerifierService)
71
78
  private readonly scheduledMessageVerifier: ScheduledMessageVerifierBackendService,
72
79
  @inject(SAAS_SERVICE_TYPES.Logger)
@@ -126,43 +133,32 @@ export class MinionTickConsumerBackendService {
126
133
  reconcile: reconcile ? (attempt) => reconcile(tick, attempt) : undefined,
127
134
  };
128
135
  };
129
- const queueName = QueueNamingUtils.buildMinionTickQueueName(applicationId, minionName);
130
-
131
136
  // M5 — adapter readiness guard. The minion entrypoint calls this
132
137
  // method AFTER `StartApplicationBackendService.initialize`, which
133
- // typically connects the RabbitMQ adapter. Throw a descriptive
134
- // error if the adapter is not connected so a misconfigured
135
- // bootstrap surfaces here rather than at the first cron tick.
138
+ // connects the queue adapter. Throw a descriptive error if it is not
139
+ // connected so a misconfigured bootstrap surfaces here rather than at
140
+ // the first cron tick.
136
141
  if (!this.adapter.isConnected()) {
137
142
  throw new Error(
138
- 'MinionTickConsumerBackendService.start called before the RabbitMQ adapter connected. ' +
143
+ 'MinionTickConsumerBackendService.start called before the queue adapter connected. ' +
139
144
  'Ensure the minion bootstrap completes before subscribing to the tick queue.',
140
145
  );
141
146
  }
142
147
 
143
- // H2 — the minion runtime OWNS and declares this per-minion tick queue.
144
- // The crontabs-batches-manager publisher is a producer only and passively
145
- // verifies the queue (`checkQueue`) rather than declaring it, so there is no
146
- // publisher-side declaration whose args this must match — the minion is the
147
- // sole topology owner here. `durable: true` + `x-queue-type: 'quorum'` is
148
- // the minion's own chosen shape (durable so ticks survive a broker restart).
148
+ // H2 — the minion runtime OWNS this per-minion tick queue's shape: durable and REPLICATED, so ticks survive a
149
+ // broker restart and the loss of one node. The crontabs-batches-manager publisher only verifies it (`checkQueue`).
150
+ // The backend's scheduled-delivery intake (#2303) declares it too, when a tick delivered over HTTP arrives before
151
+ // this minion has booted, and both go through `assertMinionTickQueue`, so the two declarations cannot differ.
149
152
  //
150
- // Declared on the adapter's dedicated topology channel (not the primary
151
- // publish/consume channel): a `406` arg-mismatch against a pre-existing
152
- // incompatible queue closes only that channel, so it can't tear down the
153
- // primary channel and crash-loop the minion bootstrap. The
154
- // `x-queue-type: 'quorum'` argument is not modelled by `QueueAssertOptions`,
155
- // so we declare directly on the channel rather than via `adapter.assertQueue`.
156
- const channel = await this.adapter.getTopologyChannel();
157
- await channel.assertQueue(queueName, {
158
- durable: true,
159
- arguments: {
160
- 'x-queue-type': 'quorum',
161
- },
162
- });
153
+ // Through the port (#2303): `replicated` is what RabbitMQ declares as a quorum queue
154
+ // (`x-queue-type: quorum`, the same arguments this consumer declared itself before),
155
+ // on the adapter's dedicated topology channel, so a `406` arg-mismatch against a
156
+ // pre-existing incompatible queue closes only that channel and is reported by the
157
+ // adapter's own topology refusal rather than tearing down the primary channel.
158
+ const queueName = await assertMinionTickQueue(this.adapter, applicationId, minionName);
163
159
 
164
- await this.adapter.consume(queueName, async (msg: ConsumeMessage, channel: Channel) => {
165
- await this.handleMessage(msg, channel, applicationId, minionName, queueName, resolver);
160
+ await this.adapter.consume(queueName, async (msg: QueueConsumeMessage, acknowledger: QueueMessageAcknowledger) => {
161
+ await this.handleMessage(msg, acknowledger, applicationId, minionName, queueName, resolver);
166
162
  });
167
163
 
168
164
  this.consumingQueueName = queueName;
@@ -217,8 +213,8 @@ export class MinionTickConsumerBackendService {
217
213
  }
218
214
 
219
215
  private async handleMessage(
220
- msg: ConsumeMessage,
221
- channel: Channel,
216
+ msg: QueueConsumeMessage,
217
+ acknowledger: QueueMessageAcknowledger,
222
218
  applicationId: string,
223
219
  expectedMinionName: string,
224
220
  queueName: string,
@@ -262,8 +258,8 @@ export class MinionTickConsumerBackendService {
262
258
  // Settlement failure is a broker problem, not a new business failure. Never
263
259
  // NACK after an ACK throws or run the handler again from this catch boundary.
264
260
  try {
265
- if (accepted) channel.ack(msg);
266
- else channel.nack(msg, false, false);
261
+ if (accepted) acknowledger.ack(msg);
262
+ else acknowledger.nack(msg, false, false);
267
263
  } catch (error) {
268
264
  this.logger.error('Minion tick settlement failed', { expectedMinionName, error: describeCaughtError(error) });
269
265
  }