@wildo-ai/saas-workers-node-lib 1.1.11 → 1.1.13

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.
Files changed (40) hide show
  1. package/dist/esm/index.d.ts +1 -2
  2. package/dist/esm/index.d.ts.map +1 -1
  3. package/dist/esm/index.js +1 -2
  4. package/dist/esm/index.js.map +1 -1
  5. package/dist/esm/inject/models/container.d.ts.map +1 -1
  6. package/dist/esm/inject/models/container.js +1 -2
  7. package/dist/esm/inject/models/container.js.map +1 -1
  8. package/dist/esm/inject/models/service-types.d.ts.map +1 -1
  9. package/dist/esm/inject/models/service-types.js.map +1 -1
  10. package/dist/esm/runtime/middlewares/worker-jwt-verifier.middleware.d.ts +24 -3
  11. package/dist/esm/runtime/middlewares/worker-jwt-verifier.middleware.d.ts.map +1 -1
  12. package/dist/esm/runtime/middlewares/worker-jwt-verifier.middleware.js +84 -20
  13. package/dist/esm/runtime/middlewares/worker-jwt-verifier.middleware.js.map +1 -1
  14. package/dist/esm/runtime/middlewares/worker-request-context.middleware.d.ts.map +1 -1
  15. package/dist/esm/runtime/middlewares/worker-request-context.middleware.js.map +1 -1
  16. package/dist/esm/runtime/services/define-worker-init.d.ts +5 -2
  17. package/dist/esm/runtime/services/define-worker-init.d.ts.map +1 -1
  18. package/dist/esm/runtime/services/define-worker-init.js.map +1 -1
  19. package/dist/esm/runtime/services/read-worker-bootstrap-env.d.ts.map +1 -1
  20. package/dist/esm/runtime/services/read-worker-bootstrap-env.js.map +1 -1
  21. package/dist/esm/runtime/services/read-worker-http-surface-env.d.ts.map +1 -1
  22. package/dist/esm/runtime/services/read-worker-http-surface-env.js.map +1 -1
  23. package/dist/esm/runtime/services/start-worker-application.backend.service.d.ts +31 -20
  24. package/dist/esm/runtime/services/start-worker-application.backend.service.d.ts.map +1 -1
  25. package/dist/esm/runtime/services/start-worker-application.backend.service.js +45 -10
  26. package/dist/esm/runtime/services/start-worker-application.backend.service.js.map +1 -1
  27. package/dist/esm/runtime/services/worker-http-server.backend.service.d.ts +6 -5
  28. package/dist/esm/runtime/services/worker-http-server.backend.service.d.ts.map +1 -1
  29. package/dist/esm/runtime/services/worker-http-server.backend.service.js +6 -6
  30. package/dist/esm/runtime/services/worker-http-server.backend.service.js.map +1 -1
  31. package/dist/tsconfig.build.tsbuildinfo +1 -1
  32. package/package.json +7 -7
  33. package/src/index.ts +1 -2
  34. package/src/inject/models/container.ts +1 -2
  35. package/src/runtime/middlewares/__tests__/worker-jwt-verifier.rotation-cutoff.middleware.test.ts +104 -9
  36. package/src/runtime/middlewares/worker-jwt-verifier.middleware.ts +90 -22
  37. package/src/runtime/services/__tests__/start-worker-application.backend.service.test.ts +115 -2
  38. package/src/runtime/services/define-worker-init.ts +5 -2
  39. package/src/runtime/services/start-worker-application.backend.service.ts +61 -21
  40. package/src/runtime/services/worker-http-server.backend.service.ts +8 -5
@@ -1,10 +1,14 @@
1
1
  import { inject, injectable } from 'inversify';
2
2
  import {
3
+ describeCaughtError,
3
4
  getOtelSdkHandle,
4
5
  type ProviderRuntimeArtifact,
6
+ recordBackendStartOutcome,
5
7
  SAAS_SERVICE_TYPES,
6
8
  WildoWorkerBootstrapClientService,
7
9
  } from '@wildo-ai/saas-backend-lib';
10
+ import { BackendStartOutcome } from '@wildo-ai/platform-core-shared';
11
+ import { narrowRuntimeProviderDataResidency } from '@wildo-ai/saas-models';
8
12
  import {
9
13
  assertProviderRuntimeEnvInSync,
10
14
  type AppWorkerBootstrapResponse,
@@ -16,18 +20,30 @@ import type {
16
20
  } from './define-worker-init';
17
21
  import { WorkerHttpServerBackendService } from './worker-http-server.backend.service';
18
22
 
23
+ /** What {@link StartWorkerApplicationBackendService.initialize} takes. */
24
+ export interface WorkerApplicationInitializationInput {
25
+ readonly config: WorkerInitializationConfig;
26
+ readonly applicationId: string;
27
+ /**
28
+ * `PLATFORM_APPLICATION_PRIMARY_SECRET` from the four-env
29
+ * bootstrap-env-contract — required so the worker's
30
+ * `WildoWorkerBootstrapClientService` can authenticate against the
31
+ * apps-manager `apps-to-manager/workers/:workerName/bootstrap`
32
+ * endpoint as APP_TO_PLATFORM.
33
+ */
34
+ readonly platformApplicationPrimarySecret: string;
35
+ }
36
+
19
37
  /**
20
- * Worker entrypoint per Q1 LOCKED of
21
- * `.claude/plans/minions-and-workers-implementation.md`: a standalone
38
+ * Worker entrypoint: a standalone
22
39
  * runtime kernel that does NOT consume the backend-api's heavy bootstrap
23
- * (no `AppConfigurationService`, no Mongo / Redis / RabbitMQ). Per the
24
- * Phase 1.5 mapping doc Table A, the worker only inherits these
25
- * `bootstrap-base` steps:
40
+ * (no `AppConfigurationService`, no Mongo / Redis / RabbitMQ). The worker
41
+ * only inherits these `bootstrap-base` steps:
26
42
  * - Env validation
27
43
  * - Apps-manager handshake (limited to fetching the trusted
28
44
  * `APPLICATION_WORKER_REQUEST` public key)
29
45
  * - Final validation gate
30
- * - SIGTERM handler (graceful shutdown per G-18 + KD-7)
46
+ * - SIGTERM handler (graceful shutdown)
31
47
  *
32
48
  * Plus the two worker-specific steps:
33
49
  * - HTTP server + controllers (with JWT verifier middleware)
@@ -61,18 +77,28 @@ export class StartWorkerApplicationBackendService {
61
77
  private readonly workerHttpServer: WorkerHttpServerBackendService,
62
78
  ) {}
63
79
 
64
- public async initialize(input: {
65
- config: WorkerInitializationConfig;
66
- applicationId: string;
67
- /**
68
- * `PLATFORM_APPLICATION_PRIMARY_SECRET` from the four-env
69
- * bootstrap-env-contract — required so the worker's
70
- * `WildoWorkerBootstrapClientService` can authenticate against the
71
- * apps-manager `apps-to-manager/workers/:workerName/bootstrap`
72
- * endpoint as APP_TO_PLATFORM.
73
- */
74
- platformApplicationPrimarySecret: string;
75
- }): Promise<void> {
80
+ /**
81
+ * Start the worker, and record how the start ended (#3288).
82
+ *
83
+ * The record is the backend's (`recordBackendStartOutcome`, under `APPLICATION_RUNTIME_SIGNALS_HOME/backend-start/`,
84
+ * filed as `workers.<name>`): `started` once the HTTP server listens, `failed` with the classified cause otherwise.
85
+ * A port another process holds is `port-in-use` with the port, read from the server's `EADDRINUSE`. The dev
86
+ * supervisor (`wildo-dev-runtime serve`) looks the record up by pid and names the holder, stops an orphan of this
87
+ * package or pauses on a foreign one, instead of crash-looping into `CRASH_RESPAWN_EXHAUSTED`. Nothing is written
88
+ * when the variable is absent, which is every non-local deployment.
89
+ */
90
+ public async initialize(input: WorkerApplicationInitializationInput): Promise<void> {
91
+ const serviceIdentifier = `workers.${input.config.workerName}`;
92
+ try {
93
+ await this.initializeWorker(input);
94
+ } catch (error) {
95
+ recordBackendStartOutcome({ outcome: BackendStartOutcome.FAILED, serviceIdentifier, message: describeCaughtError(error), failure: error });
96
+ throw error;
97
+ }
98
+ recordBackendStartOutcome({ outcome: BackendStartOutcome.STARTED, serviceIdentifier });
99
+ }
100
+
101
+ private async initializeWorker(input: WorkerApplicationInitializationInput): Promise<void> {
76
102
  const { config, applicationId, platformApplicationPrimarySecret } = input;
77
103
  this.providerRuntime = this.normalizeProviderRuntime(
78
104
  config.providerRuntime,
@@ -129,12 +155,17 @@ export class StartWorkerApplicationBackendService {
129
155
  publicKey: entry.publicKey,
130
156
  ...(entry.notAfter ? { notAfter: entry.notAfter } : {}),
131
157
  })),
158
+ // #2895 — a request naming a key this worker has not fetched yet (the first ones after a rotation) fetches the
159
+ // bootstrap again; the middleware bounds how often. A failed fetch keeps the previous bootstrap.
160
+ refreshKeysForUnknownKid: async () => {
161
+ this.bootstrapResponse = await this.workerBootstrapClient.getBootstrap({ force: true });
162
+ },
132
163
  });
133
164
  this.workerHttpServer.markReady();
134
165
  this.isInitialized = true;
135
166
 
136
167
  // Audit A-11 + A-3: install the worker's own graceful-shutdown handler (the JSDoc's "SIGTERM
137
- // handler per G-18 + KD-7", previously claimed but absent). See `registerGracefulShutdown`.
168
+ // handler", previously claimed but absent). See `registerGracefulShutdown`.
138
169
  this.registerGracefulShutdown();
139
170
  }
140
171
 
@@ -172,8 +203,8 @@ export class StartWorkerApplicationBackendService {
172
203
 
173
204
  /**
174
205
  * Install the worker's SIGTERM/SIGINT graceful-shutdown handler — the JSDoc's "SIGTERM handler
175
- * per G-18 + KD-7" that audit A-11 found was claimed but absent (a signal would hard-kill the
176
- * worker, dropping any final telemetry). The worker is deliberately queue-free (KD-3), so it does
206
+ * (graceful shutdown)" that audit A-11 found was claimed but absent (a signal would hard-kill the
207
+ * worker, dropping any final telemetry). The worker is deliberately queue-free, so it does
177
208
  * NOT use the RabbitMQ-coupled `WorkerShutdownManager`; instead it runs its own cleanup
178
209
  * (`shutdown()`) and flushes OTel telemetry before exit — the worker-local analogue of the
179
210
  * platform hosts' note-6 flush. `process.once` keeps the host killable (the handler exits).
@@ -333,6 +364,9 @@ export class StartWorkerApplicationBackendService {
333
364
  // sibling's opt-in must not load a package into this process.
334
365
  const projectedAugmentations = Object.entries(providerRuntime.providerRuntimeAugmentations ?? {})
335
366
  .filter(([providerRef]) => projectedProviderRefs.includes(providerRef));
367
+ // Narrowed with the refs too (#3513): the region a sibling's provider is bound to is not this host's to apply.
368
+ const projectedProcessingRegions = Object.entries(providerRuntime.providerProcessingRegions ?? {})
369
+ .filter(([providerRef]) => projectedProviderRefs.includes(providerRef));
336
370
 
337
371
  return {
338
372
  __AUTOGENERATED__: providerRuntime.__AUTOGENERATED__,
@@ -342,6 +376,12 @@ export class StartWorkerApplicationBackendService {
342
376
  providerRefs: projectedProviderRefs,
343
377
  providerRuntimeImports: projectedProviderRuntimeImports,
344
378
  ...(projectedAugmentations.length === 0 ? {} : { providerRuntimeAugmentations: Object.fromEntries(projectedAugmentations) }),
379
+ ...(projectedProcessingRegions.length === 0 ? {} : { providerProcessingRegions: Object.fromEntries(projectedProcessingRegions) }),
380
+ // Narrowed with the refs too (#2294), and never dropped: a projection that lost it would load this host's providers
381
+ // without the residency the application declared, which is the one thing the loader's re-check exists to prevent.
382
+ ...(providerRuntime.providerDataResidency === undefined
383
+ ? {}
384
+ : { providerDataResidency: narrowRuntimeProviderDataResidency(providerRuntime.providerDataResidency, projectedProviderRefs) }),
345
385
  providerGraphDigest: providerRuntime.providerGraphDigest,
346
386
  lockfileSectionDigest: providerRuntime.lockfileSectionDigest,
347
387
  artifactKind: 'backend',
@@ -10,8 +10,7 @@ import { createWorkerRequestContextMiddleware } from '../middlewares/worker-requ
10
10
  /**
11
11
  * Lightweight HTTP server install for the Wildo worker runtime.
12
12
  *
13
- * Per KD-3 of `.claude/plans/minions-and-workers-implementation.md`, the
14
- * worker is a stateless HTTP-only runtime. The server here intentionally
13
+ * The worker is a stateless HTTP-only runtime. The server here intentionally
15
14
  * does NOT pull `HttpServerBackendService` from `saas-backend-lib` — that
16
15
  * service depends on `AppConfigurationService`, `RedisService`,
17
16
  * `WebSocketService`, `ControllersRegistryHandlerBackendService`, etc.,
@@ -25,7 +24,7 @@ import { createWorkerRequestContextMiddleware } from '../middlewares/worker-requ
25
24
  * `WildoWorkerConfig.http.{healthPath,readyPath}` (no JWT required —
26
25
  * K8s probe traffic is unauthenticated by design).
27
26
  * - Optional `metricsPath` mounted unauthenticated for in-cluster
28
- * prom-client scraping (KD-3: no public ingress, so this is fine).
27
+ * prom-client scraping (no public ingress, so this is fine).
29
28
  * - All other routes are gated by the
30
29
  * `APPLICATION_WORKER_REQUEST`-keyed JWT verifier; worker code
31
30
  * registers them via `WorkerInitializationConfig.registerRoutes`.
@@ -36,8 +35,8 @@ import { createWorkerRequestContextMiddleware } from '../middlewares/worker-requ
36
35
  * backend-lib logs share the dispatching request's id and `req.correlationId`
37
36
  * is available to handlers. The kernel itself still logs via `console` by
38
37
  * design (it injects no `LoggerService`). Subsequent slices may layer in
39
- * prom-client metrics scaffolding and graceful-shutdown drain (KD-7
40
- * `gracePeriodSec`); the surface above is otherwise the minimum needed to
38
+ * prom-client metrics scaffolding and graceful-shutdown drain
39
+ * (`gracePeriodSec`); the surface above is otherwise the minimum needed to
41
40
  * verify a backend-api → worker round-trip end-to-end.
42
41
  */
43
42
  @injectable()
@@ -51,6 +50,8 @@ export class WorkerHttpServerBackendService {
51
50
  providerRuntime?: ProviderRuntimeArtifact;
52
51
  getCurrentPublicKey: () => string;
53
52
  getRotatedPublicKeys?: () => Array<{ kid: string; publicKey: string; notAfter?: Date | string }>;
53
+ /** Fetch the bootstrap again when a request names an unknown `kid` (#2895); see the verifier middleware. */
54
+ refreshKeysForUnknownKid?: () => Promise<void>;
54
55
  metricsHandler?: RequestHandler;
55
56
  }): Promise<void> {
56
57
  if (this.app) {
@@ -62,6 +63,7 @@ export class WorkerHttpServerBackendService {
62
63
  providerRuntime,
63
64
  getCurrentPublicKey,
64
65
  getRotatedPublicKeys,
66
+ refreshKeysForUnknownKid,
65
67
  metricsHandler,
66
68
  } = input;
67
69
  const app = express();
@@ -93,6 +95,7 @@ export class WorkerHttpServerBackendService {
93
95
  const verifyJwt = createWorkerJwtVerifierMiddleware({
94
96
  getCurrentPublicKey,
95
97
  getRotatedPublicKeys,
98
+ ...(refreshKeysForUnknownKid ? { refreshKeysForUnknownKid } : {}),
96
99
  });
97
100
 
98
101
  if (config.registerRoutes) {