@wildo-ai/saas-minions-lib 1.1.3
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/LICENSE +34 -0
- package/dist/esm/base-classes/services/services/minion-scoped-services-registry-handler.backend.service.d.ts +22 -0
- package/dist/esm/base-classes/services/services/minion-scoped-services-registry-handler.backend.service.d.ts.map +1 -0
- package/dist/esm/base-classes/services/services/minion-scoped-services-registry-handler.backend.service.js +234 -0
- package/dist/esm/base-classes/services/services/minion-scoped-services-registry-handler.backend.service.js.map +1 -0
- package/dist/esm/index.d.ts +9 -0
- package/dist/esm/index.d.ts.map +1 -0
- package/dist/esm/index.js +9 -0
- package/dist/esm/index.js.map +1 -0
- package/dist/esm/inject/models/container.d.ts +7 -0
- package/dist/esm/inject/models/container.d.ts.map +1 -0
- package/dist/esm/inject/models/container.js +55 -0
- package/dist/esm/inject/models/container.js.map +1 -0
- package/dist/esm/inject/models/service-types.d.ts +7 -0
- package/dist/esm/inject/models/service-types.d.ts.map +1 -0
- package/dist/esm/inject/models/service-types.js +6 -0
- package/dist/esm/inject/models/service-types.js.map +1 -0
- package/dist/esm/runtime/queue/minion-tick-consumer.backend.service.d.ts +47 -0
- package/dist/esm/runtime/queue/minion-tick-consumer.backend.service.d.ts.map +1 -0
- package/dist/esm/runtime/queue/minion-tick-consumer.backend.service.js +157 -0
- package/dist/esm/runtime/queue/minion-tick-consumer.backend.service.js.map +1 -0
- package/dist/esm/runtime/services/define-minion-init.d.ts +98 -0
- package/dist/esm/runtime/services/define-minion-init.d.ts.map +1 -0
- package/dist/esm/runtime/services/define-minion-init.js +4 -0
- package/dist/esm/runtime/services/define-minion-init.js.map +1 -0
- package/dist/esm/runtime/services/own-schedule-reader.backend.service.d.ts +75 -0
- package/dist/esm/runtime/services/own-schedule-reader.backend.service.d.ts.map +1 -0
- package/dist/esm/runtime/services/own-schedule-reader.backend.service.js +124 -0
- package/dist/esm/runtime/services/own-schedule-reader.backend.service.js.map +1 -0
- package/dist/esm/runtime/services/start-minion-application.backend.service.d.ts +48 -0
- package/dist/esm/runtime/services/start-minion-application.backend.service.d.ts.map +1 -0
- package/dist/esm/runtime/services/start-minion-application.backend.service.js +304 -0
- package/dist/esm/runtime/services/start-minion-application.backend.service.js.map +1 -0
- package/dist/tsconfig.build.tsbuildinfo +1 -0
- package/package.json +56 -0
- package/src/base-classes/services/services/__tests__/minion-scoped-services-registry-handler.backend.service.test.ts +252 -0
- package/src/base-classes/services/services/minion-scoped-services-registry-handler.backend.service.ts +337 -0
- package/src/index.ts +11 -0
- package/src/inject/models/__tests__/container.test.ts +30 -0
- package/src/inject/models/container.ts +68 -0
- package/src/inject/models/service-types.ts +11 -0
- package/src/runtime/queue/minion-tick-consumer.backend.service.ts +181 -0
- package/src/runtime/services/__tests__/own-schedule-reader.backend.service.test.ts +118 -0
- package/src/runtime/services/__tests__/start-minion-application.backend.service.test.ts +422 -0
- package/src/runtime/services/define-minion-init.ts +113 -0
- package/src/runtime/services/own-schedule-reader.backend.service.ts +146 -0
- package/src/runtime/services/start-minion-application.backend.service.ts +398 -0
|
@@ -0,0 +1,422 @@
|
|
|
1
|
+
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
|
|
2
|
+
import type {
|
|
3
|
+
AppConfigurationService,
|
|
4
|
+
LoggerService,
|
|
5
|
+
StartApplicationBackendService,
|
|
6
|
+
} from '@wildo-ai/saas-backend-lib';
|
|
7
|
+
import { PROVIDER_RUNTIME_ENV_KEYS } from '@wildo-ai/platform-config-lib';
|
|
8
|
+
import {
|
|
9
|
+
defineMinionInit,
|
|
10
|
+
type MinionProviderRuntimeArtifact,
|
|
11
|
+
} from '../define-minion-init';
|
|
12
|
+
import { MinionTickConsumerBackendService } from '../../queue/minion-tick-consumer.backend.service';
|
|
13
|
+
import { StartMinionApplicationBackendService } from '../start-minion-application.backend.service';
|
|
14
|
+
import { ApplicationRuntimeProfile, RuntimePrincipalBackendService } from '@wildo-ai/saas-backend-lib';
|
|
15
|
+
import type { OwnScheduleReaderBackendService } from '../own-schedule-reader.backend.service';
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Set the runtime env keys that `assertProviderRuntimeEnvInSync` reads
|
|
19
|
+
* at boot, simulating the `.wildo-providers.env` mount that production
|
|
20
|
+
* minion processes always have. Tests that DON'T set these will trip
|
|
21
|
+
* the fail-closed reconciliation guard — by design.
|
|
22
|
+
*/
|
|
23
|
+
function withMatchingProviderRuntimeEnv(input: {
|
|
24
|
+
refs: ReadonlyArray<string>;
|
|
25
|
+
digest: string;
|
|
26
|
+
}): void {
|
|
27
|
+
vi.stubEnv(PROVIDER_RUNTIME_ENV_KEYS.REFS, [...input.refs].sort().join(','));
|
|
28
|
+
vi.stubEnv(PROVIDER_RUNTIME_ENV_KEYS.RUNTIME_DIGEST, input.digest);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function createTickConsumerStub() {
|
|
32
|
+
return {
|
|
33
|
+
start: vi.fn().mockResolvedValue(undefined),
|
|
34
|
+
stop: vi.fn().mockResolvedValue(undefined),
|
|
35
|
+
isRunning: vi.fn().mockReturnValue(false),
|
|
36
|
+
} as unknown as MinionTickConsumerBackendService;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
function createAppConfigServiceStub(applicationId = 'wonder-todos') {
|
|
40
|
+
return {
|
|
41
|
+
applicationId,
|
|
42
|
+
} as unknown as AppConfigurationService;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
function createLoggerStub(): LoggerService {
|
|
46
|
+
return {
|
|
47
|
+
info: vi.fn(),
|
|
48
|
+
warn: vi.fn(),
|
|
49
|
+
error: vi.fn(),
|
|
50
|
+
debug: vi.fn(),
|
|
51
|
+
debugByType: vi.fn(() => vi.fn()),
|
|
52
|
+
setDebugTypeLogging: vi.fn(),
|
|
53
|
+
} as unknown as LoggerService;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function instantiate(delegate: StartApplicationBackendService): {
|
|
57
|
+
service: StartMinionApplicationBackendService;
|
|
58
|
+
tickConsumer: MinionTickConsumerBackendService;
|
|
59
|
+
runtimePrincipal: RuntimePrincipalBackendService;
|
|
60
|
+
systemAccess: any;
|
|
61
|
+
} {
|
|
62
|
+
const tickConsumer = createTickConsumerStub();
|
|
63
|
+
// A REAL principal, not a stub: this harness is the only place that proves a minion
|
|
64
|
+
// declares its identity at startup, and a stub would let a broken initialize() pass.
|
|
65
|
+
const runtimePrincipal = new RuntimePrincipalBackendService();
|
|
66
|
+
// The tick context hands the author the CONTAINED system-access door; the stub only
|
|
67
|
+
// needs identity here, since what this harness proves is that the context is assembled
|
|
68
|
+
// and passed — the door's own containment + fail-closed behaviour is pinned in
|
|
69
|
+
// `system-access.service.test.ts`.
|
|
70
|
+
const systemAccess = { listAsSystem: vi.fn(), readAsSystem: vi.fn() } as any;
|
|
71
|
+
const service = new StartMinionApplicationBackendService(
|
|
72
|
+
delegate,
|
|
73
|
+
createAppConfigServiceStub(),
|
|
74
|
+
tickConsumer,
|
|
75
|
+
createLoggerStub(),
|
|
76
|
+
runtimePrincipal,
|
|
77
|
+
systemAccess,
|
|
78
|
+
{ read: vi.fn().mockResolvedValue([]) } as unknown as OwnScheduleReaderBackendService,
|
|
79
|
+
);
|
|
80
|
+
return { service, tickConsumer, runtimePrincipal, systemAccess };
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
describe('StartMinionApplicationBackendService', () => {
|
|
84
|
+
afterEach(() => {
|
|
85
|
+
vi.unstubAllEnvs();
|
|
86
|
+
});
|
|
87
|
+
|
|
88
|
+
it('maps minion startup onto the backend runtime with headless, cron-sync and job-consumer guards', async () => {
|
|
89
|
+
const initialize = vi.fn().mockResolvedValue(undefined);
|
|
90
|
+
const delegate = {
|
|
91
|
+
initialize,
|
|
92
|
+
shutdown: vi.fn().mockResolvedValue(undefined),
|
|
93
|
+
isApplicationInitialized: vi.fn().mockReturnValue(true),
|
|
94
|
+
} as unknown as StartApplicationBackendService;
|
|
95
|
+
const { service } = instantiate(delegate);
|
|
96
|
+
const providerRuntime: MinionProviderRuntimeArtifact = {
|
|
97
|
+
__AUTOGENERATED__: 'AUTO-GENERATED FILE. DO NOT EDIT. Regenerate with `wildo config sync`.',
|
|
98
|
+
generatedBy: 'wildo provider-runtime-artifact',
|
|
99
|
+
generatedAt: '2026-05-03T06:00:00.000Z',
|
|
100
|
+
sourceDigest: 'sha256:test',
|
|
101
|
+
providerRefs: ['openai'],
|
|
102
|
+
artifactKind: 'minions',
|
|
103
|
+
modules: {
|
|
104
|
+
declaredModules: {},
|
|
105
|
+
moduleIds: [],
|
|
106
|
+
moduleIdsByService: {},
|
|
107
|
+
},
|
|
108
|
+
scopes: {
|
|
109
|
+
marketingScrapper: {
|
|
110
|
+
providers: {
|
|
111
|
+
openai: {
|
|
112
|
+
engineCapabilities: [],
|
|
113
|
+
providerCapabilities: ['LLM_CHAT'],
|
|
114
|
+
protocols: ['LLM_PROVIDER'],
|
|
115
|
+
},
|
|
116
|
+
},
|
|
117
|
+
selection: {},
|
|
118
|
+
},
|
|
119
|
+
},
|
|
120
|
+
};
|
|
121
|
+
|
|
122
|
+
// Boot-time reconciliation requires the env file to be mounted.
|
|
123
|
+
// Production minion processes get this via docker-compose `env_file:`
|
|
124
|
+
// or K8s envFrom; in tests we stub the equivalent process.env keys.
|
|
125
|
+
withMatchingProviderRuntimeEnv({
|
|
126
|
+
refs: providerRuntime.providerRefs!,
|
|
127
|
+
digest: providerRuntime.sourceDigest,
|
|
128
|
+
});
|
|
129
|
+
|
|
130
|
+
const minionInit = defineMinionInit({
|
|
131
|
+
minionName: 'marketingScrapper',
|
|
132
|
+
runtimeProfile: ApplicationRuntimeProfile.MINION,
|
|
133
|
+
sharedResourceConfigurations: {} as any,
|
|
134
|
+
sharedResourceRelationships: [],
|
|
135
|
+
customServiceImplementations: [],
|
|
136
|
+
providerRuntime,
|
|
137
|
+
});
|
|
138
|
+
|
|
139
|
+
await service.initialize(minionInit);
|
|
140
|
+
|
|
141
|
+
expect(initialize).toHaveBeenCalledTimes(1);
|
|
142
|
+
// The `providerRuntime` assertion uses `objectContaining` (NOT exact match)
|
|
143
|
+
// so the test pins the load-bearing facts of the minion → backend
|
|
144
|
+
// projection — `artifactKind` flipped to `'backend'` and `scope` extracted
|
|
145
|
+
// from the minion's slot — without coupling the orchestration test to the
|
|
146
|
+
// shape evolution of the backend artifact itself. Fields like
|
|
147
|
+
// `lockfileSectionDigest`, `providerGraphDigest`, and `providerRefs` are
|
|
148
|
+
// added by the lockfile-tracking work in the active
|
|
149
|
+
// provider-migration-continuation plan; they belong in the projection's
|
|
150
|
+
// OWN unit tests, not in this top-level "the minion startup wires the
|
|
151
|
+
// right delegate input" smoke test.
|
|
152
|
+
expect(initialize).toHaveBeenCalledWith(expect.objectContaining({
|
|
153
|
+
sharedResourceConfigurations: minionInit.sharedResourceConfigurations,
|
|
154
|
+
sharedResourceRelationships: minionInit.sharedResourceRelationships,
|
|
155
|
+
customServiceImplementations: minionInit.customServiceImplementations,
|
|
156
|
+
providerRuntime: expect.objectContaining({
|
|
157
|
+
artifactKind: 'backend',
|
|
158
|
+
scope: providerRuntime.scopes.marketingScrapper,
|
|
159
|
+
modules: providerRuntime.modules,
|
|
160
|
+
sourceDigest: providerRuntime.sourceDigest,
|
|
161
|
+
}),
|
|
162
|
+
headlessMode: true,
|
|
163
|
+
skipCronSync: true,
|
|
164
|
+
// The minion must opt OUT of the shared application job consumers so it
|
|
165
|
+
// never competes with the backend-api pod for the scheduled/operations/
|
|
166
|
+
// callbacks queues (task_ddb489d1). Without this, RabbitMQ round-robins
|
|
167
|
+
// scheduled-cron ticks onto the minion, which dead-letters them.
|
|
168
|
+
skipJobConsumers: true,
|
|
169
|
+
serviceIdentifier: 'minions.marketingScrapper',
|
|
170
|
+
}));
|
|
171
|
+
expect(initialize.mock.calls[0]?.[0]?.servicesRegistryDecoratorFactory).toEqual(expect.any(Function));
|
|
172
|
+
expect(initialize.mock.calls[0]?.[0]?.afterResourcesRegistryInitialized).toEqual(expect.any(Function));
|
|
173
|
+
});
|
|
174
|
+
|
|
175
|
+
it('skips boot-time env reconciliation when the per-host scope is empty (no false-positive throw on union providerRefs)', async () => {
|
|
176
|
+
// A multi-scope artifact whose union `providerRefs` includes
|
|
177
|
+
// sibling refs the typed module preserves uncollapsed. The
|
|
178
|
+
// projection MUST recompute per-host refs from `scope.providers`
|
|
179
|
+
// — without this the minion startup would throw `env-missing` at
|
|
180
|
+
// boot because the CLI emitter deliberately does NOT write
|
|
181
|
+
// `.wildo-providers.env` for empty scopes. This pins the
|
|
182
|
+
// 2026-05-10 fix in `selectMinionProviderRuntimeScope`.
|
|
183
|
+
const initialize = vi.fn().mockResolvedValue(undefined);
|
|
184
|
+
const delegate = {
|
|
185
|
+
initialize,
|
|
186
|
+
shutdown: vi.fn().mockResolvedValue(undefined),
|
|
187
|
+
isApplicationInitialized: vi.fn().mockReturnValue(true),
|
|
188
|
+
} as unknown as StartApplicationBackendService;
|
|
189
|
+
const { service } = instantiate(delegate);
|
|
190
|
+
const providerRuntime: MinionProviderRuntimeArtifact = {
|
|
191
|
+
__AUTOGENERATED__: 'AUTO-GENERATED FILE. DO NOT EDIT. Regenerate with `wildo config sync`.',
|
|
192
|
+
generatedBy: 'wildo provider-runtime-artifact',
|
|
193
|
+
generatedAt: '2026-05-10T12:00:00.000Z',
|
|
194
|
+
sourceDigest: 'sha256:union',
|
|
195
|
+
// Multi-scope union — `openai` belongs to a sibling minion, NOT
|
|
196
|
+
// to `emptyMinion` whose own `scope.providers` is `{}`.
|
|
197
|
+
providerRefs: ['openai'],
|
|
198
|
+
artifactKind: 'minions',
|
|
199
|
+
modules: { declaredModules: {}, moduleIds: [], moduleIdsByService: {} },
|
|
200
|
+
scopes: {
|
|
201
|
+
emptyMinion: {
|
|
202
|
+
providers: {},
|
|
203
|
+
selection: {},
|
|
204
|
+
},
|
|
205
|
+
},
|
|
206
|
+
};
|
|
207
|
+
|
|
208
|
+
// Note: NO env stub. The fix means `assertProviderRuntimeEnvInSync`
|
|
209
|
+
// should NOT run for an empty-scope minion. Without the fix this
|
|
210
|
+
// would throw `env-missing` because the parent's union refs
|
|
211
|
+
// wrongly survive the projection.
|
|
212
|
+
await expect(
|
|
213
|
+
service.initialize(defineMinionInit({
|
|
214
|
+
minionName: 'emptyMinion',
|
|
215
|
+
runtimeProfile: ApplicationRuntimeProfile.MINION,
|
|
216
|
+
sharedResourceConfigurations: {} as any,
|
|
217
|
+
sharedResourceRelationships: [],
|
|
218
|
+
customServiceImplementations: [],
|
|
219
|
+
providerRuntime,
|
|
220
|
+
})),
|
|
221
|
+
).resolves.toBeUndefined();
|
|
222
|
+
|
|
223
|
+
expect(initialize).toHaveBeenCalledWith(expect.objectContaining({
|
|
224
|
+
providerRuntime: expect.objectContaining({
|
|
225
|
+
artifactKind: 'backend',
|
|
226
|
+
// After projection, providerRefs reflects the per-host scope (empty), NOT the union.
|
|
227
|
+
providerRefs: [],
|
|
228
|
+
}),
|
|
229
|
+
}));
|
|
230
|
+
});
|
|
231
|
+
|
|
232
|
+
it('preserves an explicit serviceIdentifier override', async () => {
|
|
233
|
+
const initialize = vi.fn().mockResolvedValue(undefined);
|
|
234
|
+
const delegate = {
|
|
235
|
+
initialize,
|
|
236
|
+
shutdown: vi.fn().mockResolvedValue(undefined),
|
|
237
|
+
isApplicationInitialized: vi.fn().mockReturnValue(false),
|
|
238
|
+
} as unknown as StartApplicationBackendService;
|
|
239
|
+
const { service } = instantiate(delegate);
|
|
240
|
+
|
|
241
|
+
await service.initialize(defineMinionInit({
|
|
242
|
+
minionName: 'marketingScrapper',
|
|
243
|
+
runtimeProfile: ApplicationRuntimeProfile.MINION,
|
|
244
|
+
serviceIdentifier: 'minions.marketingScrapper.blue',
|
|
245
|
+
sharedResourceConfigurations: {} as any,
|
|
246
|
+
sharedResourceRelationships: [],
|
|
247
|
+
customServiceImplementations: [],
|
|
248
|
+
}));
|
|
249
|
+
|
|
250
|
+
expect(initialize).toHaveBeenCalledWith(expect.objectContaining({
|
|
251
|
+
serviceIdentifier: 'minions.marketingScrapper.blue',
|
|
252
|
+
}));
|
|
253
|
+
});
|
|
254
|
+
|
|
255
|
+
it('fails fast when the generated minion runtime omits the current minion scope', async () => {
|
|
256
|
+
const initialize = vi.fn().mockResolvedValue(undefined);
|
|
257
|
+
const delegate = {
|
|
258
|
+
initialize,
|
|
259
|
+
shutdown: vi.fn().mockResolvedValue(undefined),
|
|
260
|
+
isApplicationInitialized: vi.fn().mockReturnValue(false),
|
|
261
|
+
} as unknown as StartApplicationBackendService;
|
|
262
|
+
const { service } = instantiate(delegate);
|
|
263
|
+
|
|
264
|
+
await expect(service.initialize(defineMinionInit({
|
|
265
|
+
minionName: 'marketingScrapper',
|
|
266
|
+
runtimeProfile: ApplicationRuntimeProfile.MINION,
|
|
267
|
+
sharedResourceConfigurations: {} as any,
|
|
268
|
+
sharedResourceRelationships: [],
|
|
269
|
+
customServiceImplementations: [],
|
|
270
|
+
providerRuntime: {
|
|
271
|
+
__AUTOGENERATED__: 'AUTO-GENERATED FILE. DO NOT EDIT. Regenerate with `wildo config sync`.',
|
|
272
|
+
generatedBy: 'wildo provider-runtime-artifact',
|
|
273
|
+
generatedAt: '2026-05-03T06:00:00.000Z',
|
|
274
|
+
sourceDigest: 'sha256:test',
|
|
275
|
+
artifactKind: 'minions',
|
|
276
|
+
modules: {
|
|
277
|
+
declaredModules: {},
|
|
278
|
+
moduleIds: [],
|
|
279
|
+
moduleIdsByService: {},
|
|
280
|
+
},
|
|
281
|
+
scopes: {},
|
|
282
|
+
},
|
|
283
|
+
}))).rejects.toThrow("Provider runtime artifact does not contain a scope for minion 'marketingScrapper'.");
|
|
284
|
+
expect(initialize).not.toHaveBeenCalled();
|
|
285
|
+
});
|
|
286
|
+
|
|
287
|
+
it('delegates lifecycle state helpers to the shared startup service', async () => {
|
|
288
|
+
const shutdown = vi.fn().mockResolvedValue(undefined);
|
|
289
|
+
const isApplicationInitialized = vi.fn()
|
|
290
|
+
.mockReturnValueOnce(true)
|
|
291
|
+
.mockReturnValueOnce(false);
|
|
292
|
+
const delegate = {
|
|
293
|
+
initialize: vi.fn().mockResolvedValue(undefined),
|
|
294
|
+
shutdown,
|
|
295
|
+
isApplicationInitialized,
|
|
296
|
+
} as unknown as StartApplicationBackendService;
|
|
297
|
+
const { service } = instantiate(delegate);
|
|
298
|
+
|
|
299
|
+
expect(service.isApplicationInitialized()).toBe(true);
|
|
300
|
+
expect(service.isApplicationInitialized()).toBe(false);
|
|
301
|
+
await service.shutdown();
|
|
302
|
+
|
|
303
|
+
expect(shutdown).toHaveBeenCalledTimes(1);
|
|
304
|
+
});
|
|
305
|
+
|
|
306
|
+
it('auto-starts the minion tick consumer with the registered onTick handler', async () => {
|
|
307
|
+
const initialize = vi.fn().mockResolvedValue(undefined);
|
|
308
|
+
const delegate = {
|
|
309
|
+
initialize,
|
|
310
|
+
shutdown: vi.fn().mockResolvedValue(undefined),
|
|
311
|
+
isApplicationInitialized: vi.fn().mockReturnValue(true),
|
|
312
|
+
} as unknown as StartApplicationBackendService;
|
|
313
|
+
const { service, tickConsumer } = instantiate(delegate);
|
|
314
|
+
const onTick = vi.fn().mockResolvedValue(undefined);
|
|
315
|
+
|
|
316
|
+
await service.initialize(defineMinionInit({
|
|
317
|
+
minionName: 'marketingScrapper',
|
|
318
|
+
runtimeProfile: ApplicationRuntimeProfile.MINION,
|
|
319
|
+
sharedResourceConfigurations: {} as any,
|
|
320
|
+
sharedResourceRelationships: [],
|
|
321
|
+
customServiceImplementations: [],
|
|
322
|
+
onTick,
|
|
323
|
+
}));
|
|
324
|
+
|
|
325
|
+
expect(tickConsumer.start).toHaveBeenCalledTimes(1);
|
|
326
|
+
expect(tickConsumer.start).toHaveBeenCalledWith(expect.objectContaining({
|
|
327
|
+
applicationId: 'wonder-todos',
|
|
328
|
+
minionName: 'marketingScrapper',
|
|
329
|
+
handler: expect.any(Function),
|
|
330
|
+
}));
|
|
331
|
+
|
|
332
|
+
// The handler is no longer the author's function by IDENTITY — startup adapts it to
|
|
333
|
+
// inject the framework-supplied `MinionTickContext`. Asserting identity would now
|
|
334
|
+
// pin the absence of that context, so this asserts the stronger property instead:
|
|
335
|
+
// invoking what the consumer received must call the author's onTick WITH the
|
|
336
|
+
// contained system-access door and the minion's own name.
|
|
337
|
+
const registered = (tickConsumer.start as any).mock.calls[0][0].handler;
|
|
338
|
+
const token = { jobId: 'job-1', minionName: 'marketingScrapper', applicationId: 'wonder-todos' };
|
|
339
|
+
await registered(token);
|
|
340
|
+
|
|
341
|
+
expect(onTick).toHaveBeenCalledTimes(1);
|
|
342
|
+
expect(onTick).toHaveBeenCalledWith(token, expect.objectContaining({
|
|
343
|
+
minionName: 'marketingScrapper',
|
|
344
|
+
systemAccess: expect.anything(),
|
|
345
|
+
}));
|
|
346
|
+
|
|
347
|
+
await service.shutdown();
|
|
348
|
+
expect(tickConsumer.stop).toHaveBeenCalledTimes(1);
|
|
349
|
+
});
|
|
350
|
+
|
|
351
|
+
it('still subscribes the tick consumer when no onTick handler is registered (logs a warning instead)', async () => {
|
|
352
|
+
const initialize = vi.fn().mockResolvedValue(undefined);
|
|
353
|
+
const delegate = {
|
|
354
|
+
initialize,
|
|
355
|
+
shutdown: vi.fn().mockResolvedValue(undefined),
|
|
356
|
+
isApplicationInitialized: vi.fn().mockReturnValue(true),
|
|
357
|
+
} as unknown as StartApplicationBackendService;
|
|
358
|
+
const { service, tickConsumer } = instantiate(delegate);
|
|
359
|
+
|
|
360
|
+
await service.initialize(defineMinionInit({
|
|
361
|
+
minionName: 'marketingScrapper',
|
|
362
|
+
runtimeProfile: ApplicationRuntimeProfile.MINION,
|
|
363
|
+
sharedResourceConfigurations: {} as any,
|
|
364
|
+
sharedResourceRelationships: [],
|
|
365
|
+
customServiceImplementations: [],
|
|
366
|
+
}));
|
|
367
|
+
|
|
368
|
+
expect(tickConsumer.start).toHaveBeenCalledTimes(1);
|
|
369
|
+
const firstCall = (tickConsumer.start as unknown as { mock: { calls: Array<[{ handler: unknown }]> } }).mock.calls[0];
|
|
370
|
+
expect(firstCall?.[0].handler).toEqual(expect.any(Function));
|
|
371
|
+
});
|
|
372
|
+
});
|
|
373
|
+
|
|
374
|
+
/**
|
|
375
|
+
* Step 3 / D9 — a minion must declare WHO it is before it can perform any privileged
|
|
376
|
+
* access, and it must do so structurally (framework-owned startup), never by relying on
|
|
377
|
+
* each minion author to remember. Attribution an author can forget is attribution that
|
|
378
|
+
* will be missing exactly when an auditor needs it.
|
|
379
|
+
*/
|
|
380
|
+
describe('StartMinionApplicationBackendService — runtime identity (D9)', () => {
|
|
381
|
+
function instantiateWithDelegate() {
|
|
382
|
+
const delegate = {
|
|
383
|
+
initialize: vi.fn().mockResolvedValue(undefined),
|
|
384
|
+
shutdown: vi.fn().mockResolvedValue(undefined),
|
|
385
|
+
isApplicationInitialized: vi.fn().mockReturnValue(true),
|
|
386
|
+
} as unknown as StartApplicationBackendService;
|
|
387
|
+
return instantiate(delegate);
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
it('declares the minion identity on the runtime principal at startup', async () => {
|
|
391
|
+
const { service, runtimePrincipal } = instantiateWithDelegate();
|
|
392
|
+
|
|
393
|
+
await service.initialize(defineMinionInit({
|
|
394
|
+
minionName: 'marketingScrapper',
|
|
395
|
+
runtimeProfile: ApplicationRuntimeProfile.MINION,
|
|
396
|
+
sharedResourceConfigurations: {} as any,
|
|
397
|
+
sharedResourceRelationships: [],
|
|
398
|
+
customServiceImplementations: [],
|
|
399
|
+
}));
|
|
400
|
+
|
|
401
|
+
expect(runtimePrincipal.describeForAudit()).toEqual({
|
|
402
|
+
runtimeProfile: ApplicationRuntimeProfile.MINION,
|
|
403
|
+
runtimeKey: 'marketingScrapper',
|
|
404
|
+
serviceIdentifier: 'minions.marketingScrapper',
|
|
405
|
+
});
|
|
406
|
+
});
|
|
407
|
+
|
|
408
|
+
it('honours an explicit serviceIdentifier (blue/green minion instances stay distinguishable)', async () => {
|
|
409
|
+
const { service, runtimePrincipal } = instantiateWithDelegate();
|
|
410
|
+
|
|
411
|
+
await service.initialize(defineMinionInit({
|
|
412
|
+
minionName: 'marketingScrapper',
|
|
413
|
+
runtimeProfile: ApplicationRuntimeProfile.MINION,
|
|
414
|
+
serviceIdentifier: 'minions.marketingScrapper.blue',
|
|
415
|
+
sharedResourceConfigurations: {} as any,
|
|
416
|
+
sharedResourceRelationships: [],
|
|
417
|
+
customServiceImplementations: [],
|
|
418
|
+
}));
|
|
419
|
+
|
|
420
|
+
expect(runtimePrincipal.describeForAudit().serviceIdentifier).toBe('minions.marketingScrapper.blue');
|
|
421
|
+
});
|
|
422
|
+
});
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
import type {
|
|
2
|
+
ProjectedMinionInitializationConfig,
|
|
3
|
+
ProviderRuntimeArtifact,
|
|
4
|
+
SystemAccessBackendService,
|
|
5
|
+
} from '@wildo-ai/saas-backend-lib';
|
|
6
|
+
import type { MinionTickHandler } from '../queue/minion-tick-consumer.backend.service';
|
|
7
|
+
import type { OwnScheduleReaderBackendService } from './own-schedule-reader.backend.service';
|
|
8
|
+
|
|
9
|
+
type ProviderRuntimeScope = ProviderRuntimeArtifact['scope'];
|
|
10
|
+
type ProviderRuntimeModules = ProviderRuntimeArtifact['modules'];
|
|
11
|
+
|
|
12
|
+
export interface MinionProviderRuntimeArtifact {
|
|
13
|
+
__AUTOGENERATED__: string;
|
|
14
|
+
generatedBy: ProviderRuntimeArtifact['generatedBy'];
|
|
15
|
+
generatedAt: string;
|
|
16
|
+
sourceDigest: string;
|
|
17
|
+
providerRefs?: ProviderRuntimeArtifact['providerRefs'];
|
|
18
|
+
/**
|
|
19
|
+
* Mirrored from the engine artifact so the per-host projection can FORWARD it (#330).
|
|
20
|
+
*
|
|
21
|
+
* This interface is a hand-written mirror of the CLI's multi-scope artifact, so a field the
|
|
22
|
+
* CLI emits and this shape omits is a field the projection can only reach through a cast —
|
|
23
|
+
* which would assert, across a package boundary, the very thing nobody checked.
|
|
24
|
+
*/
|
|
25
|
+
providerRuntimeImports?: ProviderRuntimeArtifact['providerRuntimeImports'];
|
|
26
|
+
providerGraphDigest?: ProviderRuntimeArtifact['providerGraphDigest'];
|
|
27
|
+
lockfileSectionDigest?: ProviderRuntimeArtifact['lockfileSectionDigest'];
|
|
28
|
+
artifactKind: 'minions';
|
|
29
|
+
modules: ProviderRuntimeModules;
|
|
30
|
+
scopes: Record<string, ProviderRuntimeScope>;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* The surface a minion's tick handler is given to do its work with.
|
|
35
|
+
*
|
|
36
|
+
* Handed to the handler rather than left for each author to resolve from the
|
|
37
|
+
* container, for the same reason the runtime identity is established in
|
|
38
|
+
* framework-owned startup: a boundary an author has to find is a boundary an author
|
|
39
|
+
* can get wrong. What arrives here is already the CONTAINED surface —
|
|
40
|
+
* `systemAccess` routes through the minion's `resourceAccess` ACL proxy, because
|
|
41
|
+
* minion startup rebinds the services registry to the scoped decorator before any
|
|
42
|
+
* tick is delivered.
|
|
43
|
+
*
|
|
44
|
+
* So a minion's effective authority is the INTERSECTION of two independent doors
|
|
45
|
+
* (see `.claude/plans/minion-runtime-scope.md` D6):
|
|
46
|
+
*
|
|
47
|
+
* - `resourceAccess` — operator-declared containment, enforced by the DI proxy;
|
|
48
|
+
* - the system-access door — the sanctioned per-tenant-authorization bypass, which
|
|
49
|
+
* for a minion is fail-closed on audit (D9 + OQ-5b): audited, or refused.
|
|
50
|
+
*
|
|
51
|
+
* Neither subsumes the other. A resource the ACL forbids is refused even though the
|
|
52
|
+
* system-access door would have allowed it, and a read the ACL permits is still
|
|
53
|
+
* refused if it cannot be recorded.
|
|
54
|
+
*/
|
|
55
|
+
export interface MinionTickContext {
|
|
56
|
+
/**
|
|
57
|
+
* The sanctioned privileged-access door, already contained by this minion's
|
|
58
|
+
* `resourceAccess` whitelist.
|
|
59
|
+
*
|
|
60
|
+
* Use this — never a repository directly (the `no-direct-repo-from-minion` ESLint
|
|
61
|
+
* rule enforces that) — so every access stays inside both doors and leaves an
|
|
62
|
+
* attributable audit record naming this minion.
|
|
63
|
+
*/
|
|
64
|
+
systemAccess: SystemAccessBackendService;
|
|
65
|
+
/** This minion's name, as declared in `wildo.saas.config.ts > minions`. */
|
|
66
|
+
minionName: string;
|
|
67
|
+
/**
|
|
68
|
+
* Read this minion's OWN cron schedule and recent runs (R4).
|
|
69
|
+
*
|
|
70
|
+
* Present only when the application declared the `own_cron_records` scope in
|
|
71
|
+
* this minion's `platformAccess`; otherwise the platform refuses and `read()`
|
|
72
|
+
* rejects. It is deliberately NOT absent from the type in that case — the
|
|
73
|
+
* authority decision belongs to the platform, and a client-side `undefined`
|
|
74
|
+
* would be this process guessing at it, which drifts the moment the
|
|
75
|
+
* declaration changes under a running minion.
|
|
76
|
+
*
|
|
77
|
+
* `read()` takes no arguments, and that is the contract rather than a
|
|
78
|
+
* convenience: the subject is derived from this runtime's attested identity,
|
|
79
|
+
* so another minion's schedule is not something this call could be asked for.
|
|
80
|
+
*/
|
|
81
|
+
ownSchedule: OwnScheduleReaderBackendService;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Tick handler invoked by `MinionTickConsumerBackendService` once per verified
|
|
86
|
+
* `MINION_TICK` token addressed to this minion (KD-12).
|
|
87
|
+
*/
|
|
88
|
+
export type MinionTickAuthorHandler = (
|
|
89
|
+
token: Parameters<MinionTickHandler>[0],
|
|
90
|
+
context: MinionTickContext,
|
|
91
|
+
) => Promise<void>;
|
|
92
|
+
|
|
93
|
+
export type MinionInitializationConfig = Omit<ProjectedMinionInitializationConfig, 'providerRuntime'> & {
|
|
94
|
+
providerRuntime?: ProviderRuntimeArtifact | MinionProviderRuntimeArtifact;
|
|
95
|
+
/**
|
|
96
|
+
* Tick handler invoked once per verified `MINION_TICK` token addressed to this
|
|
97
|
+
* minion (KD-12), receiving the framework-supplied {@link MinionTickContext}.
|
|
98
|
+
*
|
|
99
|
+
* Minion authors typically route the tick into the locally-hosted
|
|
100
|
+
* `flowsActorsRegistry` (per Q9 LOCKED — per-minion-local actor
|
|
101
|
+
* catalog). If omitted, the consumer still subscribes to the
|
|
102
|
+
* per-minion queue but logs a warning on every tick — useful as a
|
|
103
|
+
* fail-loud signal that ticks are arriving while the minion has not
|
|
104
|
+
* registered any tick-handling logic yet.
|
|
105
|
+
*/
|
|
106
|
+
onTick?: MinionTickAuthorHandler;
|
|
107
|
+
};
|
|
108
|
+
|
|
109
|
+
export function defineMinionInit(
|
|
110
|
+
config: MinionInitializationConfig,
|
|
111
|
+
): MinionInitializationConfig {
|
|
112
|
+
return config;
|
|
113
|
+
}
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A minion reading its OWN cron records from the platform (R4).
|
|
3
|
+
*
|
|
4
|
+
* ## The client is as selector-free as the route
|
|
5
|
+
*
|
|
6
|
+
* `read()` takes no arguments. Not a minion name, not an application id, not a
|
|
7
|
+
* job id — there is nothing to pass, so there is nothing an author could pass
|
|
8
|
+
* wrongly and nothing a later caller could parameterise. The route it calls
|
|
9
|
+
* derives its subject from the attestation, and this client's shape mirrors that
|
|
10
|
+
* rather than merely respecting it.
|
|
11
|
+
*
|
|
12
|
+
* That symmetry is deliberate. A client with a `minionName` argument that always
|
|
13
|
+
* happens to be filled with the caller's own name is one refactor away from being
|
|
14
|
+
* filled with something else, and the server would still be correct while every
|
|
15
|
+
* reader of this file had been taught the wrong mental model.
|
|
16
|
+
*
|
|
17
|
+
* ## Authority, and where it is decided
|
|
18
|
+
*
|
|
19
|
+
* Nothing here checks `platformAccess`. Two other places do, and both are better
|
|
20
|
+
* placed: apps-manager refuses to mint an attestation for a minion whose
|
|
21
|
+
* application declared no scope, and crontabs re-checks the scope before it
|
|
22
|
+
* queries. A third check here would be a client-side guess about a server-side
|
|
23
|
+
* decision — it would drift, and the day it drifted it would either refuse work
|
|
24
|
+
* the platform allows or promise work the platform refuses.
|
|
25
|
+
*
|
|
26
|
+
* So a minion without the scope gets a refusal from the platform, which is the
|
|
27
|
+
* party that knows.
|
|
28
|
+
*/
|
|
29
|
+
|
|
30
|
+
import 'reflect-metadata';
|
|
31
|
+
|
|
32
|
+
import { inject, injectable } from 'inversify';
|
|
33
|
+
|
|
34
|
+
import { ErrorCustomMessageReference, ErrorType, WildoHeaderKeys } from '@wildo-ai/saas-models';
|
|
35
|
+
import {
|
|
36
|
+
AppConfigurationService,
|
|
37
|
+
PlatformApplicationType,
|
|
38
|
+
RuntimePrincipalAttestationBackendService,
|
|
39
|
+
SAAS_SERVICE_TYPES,
|
|
40
|
+
type ErrorBuilderBackendService,
|
|
41
|
+
type LoggerService,
|
|
42
|
+
} from '@wildo-ai/saas-backend-lib';
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* One cron job that ticks this minion, with its recent runs.
|
|
46
|
+
*
|
|
47
|
+
* Typed structurally rather than importing the platform's `CronJob` — a minion
|
|
48
|
+
* runtime has no dependency on `platform-shared-lib` and giving it one to name a
|
|
49
|
+
* response body would be a package boundary crossed for a type alias.
|
|
50
|
+
*/
|
|
51
|
+
export interface OwnScheduleEntry {
|
|
52
|
+
job: {
|
|
53
|
+
jobId: string;
|
|
54
|
+
name?: string;
|
|
55
|
+
schedule?: { cron: string; timezone?: string; enabled?: boolean };
|
|
56
|
+
status?: string;
|
|
57
|
+
[field: string]: unknown;
|
|
58
|
+
};
|
|
59
|
+
recentExecutions: Array<{
|
|
60
|
+
status?: string;
|
|
61
|
+
startTime?: string;
|
|
62
|
+
endTime?: string;
|
|
63
|
+
error?: string;
|
|
64
|
+
[field: string]: unknown;
|
|
65
|
+
}>;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
const OWN_SCHEDULE_PATH = '/api/v1/runtime-self/cron-jobs';
|
|
69
|
+
|
|
70
|
+
@injectable()
|
|
71
|
+
export class OwnScheduleReaderBackendService {
|
|
72
|
+
private baseUrl: string | null = null;
|
|
73
|
+
|
|
74
|
+
constructor(
|
|
75
|
+
@inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
|
|
76
|
+
@inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
|
|
77
|
+
@inject(SAAS_SERVICE_TYPES.AppConfigService) private readonly appConfigService: AppConfigurationService,
|
|
78
|
+
@inject(SAAS_SERVICE_TYPES.RuntimePrincipalAttestationService)
|
|
79
|
+
private readonly attestations: RuntimePrincipalAttestationBackendService,
|
|
80
|
+
) {}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* This minion's cron job definitions and their recent runs.
|
|
84
|
+
*
|
|
85
|
+
* The attestation is fetched per call rather than held: the exchange caches it,
|
|
86
|
+
* so this costs nothing, and a client that cached it itself would eventually
|
|
87
|
+
* present an expired one.
|
|
88
|
+
*/
|
|
89
|
+
public async read(): Promise<OwnScheduleEntry[]> {
|
|
90
|
+
const baseUrl = this.resolveBaseUrl();
|
|
91
|
+
const attestation = await this.attestations.getAttestation(
|
|
92
|
+
PlatformApplicationType.PLATFORM_CRONTABS_BATCHES_MANAGER,
|
|
93
|
+
);
|
|
94
|
+
|
|
95
|
+
const response = await fetch(`${baseUrl}${OWN_SCHEDULE_PATH}`, {
|
|
96
|
+
method: 'GET',
|
|
97
|
+
headers: {
|
|
98
|
+
[WildoHeaderKeys.CONTENT_TYPE]: 'application/json',
|
|
99
|
+
// Deliberately the ONLY credential. A minion is not a platform service,
|
|
100
|
+
// so no `X-Service-Id`; and an application JWT would carry an identity
|
|
101
|
+
// meaning "some runtime of this app" — attaching one as well would only
|
|
102
|
+
// invite the server to read the weaker of the two.
|
|
103
|
+
[WildoHeaderKeys.RUNTIME_PRINCIPAL_TOKEN]: attestation,
|
|
104
|
+
},
|
|
105
|
+
});
|
|
106
|
+
|
|
107
|
+
if (!response.ok) {
|
|
108
|
+
// Surfaced rather than swallowed into an empty schedule. A refusal and "you
|
|
109
|
+
// have no jobs" are different answers, and returning `[]` for both would
|
|
110
|
+
// make a missing `platformAccess` declaration look like a correctly-empty
|
|
111
|
+
// schedule — the one failure an author cannot debug from the result.
|
|
112
|
+
throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
|
|
113
|
+
customMessageReference: ErrorCustomMessageReference.AUTHORIZATION,
|
|
114
|
+
context: {
|
|
115
|
+
message: 'The platform refused this runtime\'s own-schedule read',
|
|
116
|
+
status: response.status,
|
|
117
|
+
},
|
|
118
|
+
});
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
const body = (await response.json()) as { jobs?: OwnScheduleEntry[] } | null;
|
|
122
|
+
return body?.jobs ?? [];
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
private resolveBaseUrl(): string {
|
|
126
|
+
if (this.baseUrl) return this.baseUrl;
|
|
127
|
+
|
|
128
|
+
const baseUrl =
|
|
129
|
+
this.appConfigService.config.runtime.endPoints[PlatformApplicationType.PLATFORM_CRONTABS_BATCHES_MANAGER]
|
|
130
|
+
?.internalUrl;
|
|
131
|
+
|
|
132
|
+
if (!baseUrl) {
|
|
133
|
+
// A CONFIGURATION failure, not an authorization one. Blurring them would
|
|
134
|
+
// send an operator to inspect the minion's `platformAccess` declaration
|
|
135
|
+
// over what is really a missing endpoint in this deployment's topology.
|
|
136
|
+
throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
|
|
137
|
+
customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
|
|
138
|
+
context: { message: 'The crontabs-manager endpoint is not configured for this runtime' },
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
this.baseUrl = baseUrl.replace(/\/+$/, '');
|
|
143
|
+
this.logger.debug?.('Own-schedule reader bound to the crontabs endpoint', { baseUrl: this.baseUrl });
|
|
144
|
+
return this.baseUrl;
|
|
145
|
+
}
|
|
146
|
+
}
|