@wildo-ai/saas-workers-node-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.
Files changed (58) hide show
  1. package/LICENSE +34 -0
  2. package/dist/esm/index.d.ts +37 -0
  3. package/dist/esm/index.d.ts.map +1 -0
  4. package/dist/esm/index.js +37 -0
  5. package/dist/esm/index.js.map +1 -0
  6. package/dist/esm/inject/models/container.d.ts +7 -0
  7. package/dist/esm/inject/models/container.d.ts.map +1 -0
  8. package/dist/esm/inject/models/container.js +63 -0
  9. package/dist/esm/inject/models/container.js.map +1 -0
  10. package/dist/esm/inject/models/service-types.d.ts +6 -0
  11. package/dist/esm/inject/models/service-types.d.ts.map +1 -0
  12. package/dist/esm/inject/models/service-types.js +5 -0
  13. package/dist/esm/inject/models/service-types.js.map +1 -0
  14. package/dist/esm/runtime/middlewares/worker-jwt-verifier.middleware.d.ts +54 -0
  15. package/dist/esm/runtime/middlewares/worker-jwt-verifier.middleware.d.ts.map +1 -0
  16. package/dist/esm/runtime/middlewares/worker-jwt-verifier.middleware.js +61 -0
  17. package/dist/esm/runtime/middlewares/worker-jwt-verifier.middleware.js.map +1 -0
  18. package/dist/esm/runtime/middlewares/worker-request-context.middleware.d.ts +35 -0
  19. package/dist/esm/runtime/middlewares/worker-request-context.middleware.d.ts.map +1 -0
  20. package/dist/esm/runtime/middlewares/worker-request-context.middleware.js +30 -0
  21. package/dist/esm/runtime/middlewares/worker-request-context.middleware.js.map +1 -0
  22. package/dist/esm/runtime/services/define-worker-init.d.ts +85 -0
  23. package/dist/esm/runtime/services/define-worker-init.d.ts.map +1 -0
  24. package/dist/esm/runtime/services/define-worker-init.js +4 -0
  25. package/dist/esm/runtime/services/define-worker-init.js.map +1 -0
  26. package/dist/esm/runtime/services/read-worker-bootstrap-env.d.ts +47 -0
  27. package/dist/esm/runtime/services/read-worker-bootstrap-env.d.ts.map +1 -0
  28. package/dist/esm/runtime/services/read-worker-bootstrap-env.js +43 -0
  29. package/dist/esm/runtime/services/read-worker-bootstrap-env.js.map +1 -0
  30. package/dist/esm/runtime/services/read-worker-http-surface-env.d.ts +42 -0
  31. package/dist/esm/runtime/services/read-worker-http-surface-env.d.ts.map +1 -0
  32. package/dist/esm/runtime/services/read-worker-http-surface-env.js +49 -0
  33. package/dist/esm/runtime/services/read-worker-http-surface-env.js.map +1 -0
  34. package/dist/esm/runtime/services/start-worker-application.backend.service.d.ts +100 -0
  35. package/dist/esm/runtime/services/start-worker-application.backend.service.d.ts.map +1 -0
  36. package/dist/esm/runtime/services/start-worker-application.backend.service.js +297 -0
  37. package/dist/esm/runtime/services/start-worker-application.backend.service.js.map +1 -0
  38. package/dist/esm/runtime/services/worker-http-server.backend.service.d.ts +56 -0
  39. package/dist/esm/runtime/services/worker-http-server.backend.service.d.ts.map +1 -0
  40. package/dist/esm/runtime/services/worker-http-server.backend.service.js +128 -0
  41. package/dist/esm/runtime/services/worker-http-server.backend.service.js.map +1 -0
  42. package/dist/tsconfig.build.tsbuildinfo +1 -0
  43. package/package.json +61 -0
  44. package/src/index.ts +36 -0
  45. package/src/inject/models/container.ts +76 -0
  46. package/src/inject/models/service-types.ts +9 -0
  47. package/src/runtime/middlewares/__tests__/worker-jwt-verifier.rotation-cutoff.middleware.test.ts +62 -0
  48. package/src/runtime/middlewares/__tests__/worker-request-context.middleware.test.ts +85 -0
  49. package/src/runtime/middlewares/worker-jwt-verifier.middleware.ts +112 -0
  50. package/src/runtime/middlewares/worker-request-context.middleware.ts +47 -0
  51. package/src/runtime/services/__tests__/read-worker-http-surface-env.test.ts +66 -0
  52. package/src/runtime/services/__tests__/start-worker-application.backend.service.test.ts +315 -0
  53. package/src/runtime/services/__tests__/worker-http-server.backend.service.test.ts +69 -0
  54. package/src/runtime/services/define-worker-init.ts +92 -0
  55. package/src/runtime/services/read-worker-bootstrap-env.ts +86 -0
  56. package/src/runtime/services/read-worker-http-surface-env.ts +84 -0
  57. package/src/runtime/services/start-worker-application.backend.service.ts +346 -0
  58. package/src/runtime/services/worker-http-server.backend.service.ts +144 -0
@@ -0,0 +1,346 @@
1
+ import { inject, injectable } from 'inversify';
2
+ import {
3
+ getOtelSdkHandle,
4
+ type ProviderRuntimeArtifact,
5
+ SAAS_SERVICE_TYPES,
6
+ WildoWorkerBootstrapClientService,
7
+ } from '@wildo-ai/saas-backend-lib';
8
+ import {
9
+ assertProviderRuntimeEnvInSync,
10
+ type AppWorkerBootstrapResponse,
11
+ } from '@wildo-ai/platform-config-lib';
12
+ import { SAAS_WORKERS_NODE_SERVICE_TYPES } from '../../inject/models/service-types';
13
+ import type {
14
+ WorkerInitializationConfig,
15
+ WorkerProviderRuntimeArtifact,
16
+ } from './define-worker-init';
17
+ import { WorkerHttpServerBackendService } from './worker-http-server.backend.service';
18
+
19
+ /**
20
+ * Worker entrypoint per Q1 LOCKED of
21
+ * `.claude/plans/minions-and-workers-implementation.md`: a standalone
22
+ * 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:
26
+ * - Env validation
27
+ * - Apps-manager handshake (limited to fetching the trusted
28
+ * `APPLICATION_WORKER_REQUEST` public key)
29
+ * - Final validation gate
30
+ * - SIGTERM handler (graceful shutdown per G-18 + KD-7)
31
+ *
32
+ * Plus the two worker-specific steps:
33
+ * - HTTP server + controllers (with JWT verifier middleware)
34
+ * - K8s liveness writer (HTTP `/healthz` per `WildoWorkerConfig.http.healthPath`)
35
+ *
36
+ * Shipped behaviour:
37
+ * 1. Initializes `WildoWorkerBootstrapClientService` and prefetches the
38
+ * trusted public key.
39
+ * 2. Schedules the JWKS-style refresh loop; the cached bootstrap response
40
+ * feeds the JWT verifier on every inbound request, so a rotation
41
+ * rolls in without restarting the server.
42
+ * 3. Installs the lightweight `WorkerHttpServerBackendService` (express +
43
+ * helmet, no CORS, no websockets), mounts liveness/readiness probes
44
+ * unauthenticated, and gates everything else behind the
45
+ * `APPLICATION_WORKER_REQUEST` JWT verifier middleware.
46
+ * 4. Marks the readiness probe ready once the bootstrap response is
47
+ * loaded.
48
+ */
49
+ @injectable()
50
+ export class StartWorkerApplicationBackendService {
51
+ private bootstrapResponse?: AppWorkerBootstrapResponse;
52
+ private providerRuntime?: ProviderRuntimeArtifact;
53
+ private refreshTimer?: NodeJS.Timeout;
54
+ private isInitialized = false;
55
+ private signalHandlersRegistered = false;
56
+
57
+ constructor(
58
+ @inject(SAAS_SERVICE_TYPES.WildoWorkerBootstrapClientService)
59
+ private readonly workerBootstrapClient: WildoWorkerBootstrapClientService,
60
+ @inject(SAAS_WORKERS_NODE_SERVICE_TYPES.WorkerHttpServerService)
61
+ private readonly workerHttpServer: WorkerHttpServerBackendService,
62
+ ) {}
63
+
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> {
76
+ const { config, applicationId, platformApplicationPrimarySecret } = input;
77
+ this.providerRuntime = this.normalizeProviderRuntime(
78
+ config.providerRuntime,
79
+ config.workerName,
80
+ );
81
+
82
+ // Boot-time fail-closed reconciliation between the typed
83
+ // `wildo-provider-runtime.generated.ts` artifact and the
84
+ // `.wildo-providers.env` file mounted into this process. Catches
85
+ // stale-sync drift before the registry filter would silently boot
86
+ // with mismatched topology.
87
+ //
88
+ // Skipped when:
89
+ // - the artifact is absent (worker authored zero providers AND no
90
+ // scope block in `wildo.saas.config.ts`); or
91
+ // - the artifact has zero `providerRefs` (worker authored an
92
+ // explicit empty scope `providers: {}`). The CLI emitter
93
+ // deliberately does NOT write `.wildo-providers.env` in that
94
+ // case, so the env-vars are absent — running the assertion
95
+ // would raise a false-positive fail-closed.
96
+ // Defensive `?? []` — the schema marks `providerRefs` optional, so
97
+ // a hand-crafted artifact (test fixture / future format drift)
98
+ // could omit it. Without the fallback `.length` would TypeError
99
+ // before fail-closed produced its actionable message. Production
100
+ // CLI emit always defaults to `[]`, so this is hardening only.
101
+ const projectedProviderRefs = this.providerRuntime?.providerRefs ?? [];
102
+ if (this.providerRuntime && projectedProviderRefs.length > 0) {
103
+ assertProviderRuntimeEnvInSync({
104
+ artifactProviderRefs: projectedProviderRefs,
105
+ artifactSourceDigest: this.providerRuntime.sourceDigest,
106
+ hostKind: 'node-worker',
107
+ hostKey: config.workerName,
108
+ });
109
+ }
110
+
111
+ this.workerBootstrapClient.initialize({
112
+ appsManagerBaseUrl: config.appsManagerBootstrapUrl,
113
+ applicationId,
114
+ workerName: config.workerName,
115
+ platformApplicationPrimarySecret,
116
+ refreshIntervalMs: config.publicKeyRefreshIntervalMs,
117
+ });
118
+ this.bootstrapResponse = await this.workerBootstrapClient.getBootstrap();
119
+ this.scheduleRefresh(config.publicKeyRefreshIntervalMs);
120
+
121
+ await this.workerHttpServer.initialize({
122
+ config,
123
+ providerRuntime: this.providerRuntime,
124
+ getCurrentPublicKey: () => this.requireBootstrap().jwt.publicKey,
125
+ getRotatedPublicKeys: () =>
126
+ (this.requireBootstrap().jwt.rotatedPublicKeys ?? []).map((entry) => ({
127
+ kid: entry.kid,
128
+ publicKey: entry.publicKey,
129
+ ...(entry.notAfter ? { notAfter: entry.notAfter } : {}),
130
+ })),
131
+ });
132
+ this.workerHttpServer.markReady();
133
+ this.isInitialized = true;
134
+
135
+ // Audit A-11 + A-3: install the worker's own graceful-shutdown handler (the JSDoc's "SIGTERM
136
+ // handler per G-18 + KD-7", previously claimed but absent). See `registerGracefulShutdown`.
137
+ this.registerGracefulShutdown();
138
+ }
139
+
140
+ /**
141
+ * Returns the trusted public key + rotation metadata. The HTTP server's
142
+ * verifier middleware already reads this on every request via the
143
+ * `getCurrentPublicKey` / `getRotatedPublicKeys` callbacks; this getter
144
+ * exists so test code and the worker's own route handlers can inspect
145
+ * the active rotation state.
146
+ */
147
+ public getBootstrapResponse(): AppWorkerBootstrapResponse {
148
+ return this.requireBootstrap();
149
+ }
150
+
151
+ /**
152
+ * Returns the generated, backend-shaped provider runtime selected for the
153
+ * current worker. Undefined means the worker was started without a generated
154
+ * provider artifact (valid for provider-free workers).
155
+ */
156
+ public getProviderRuntime(): ProviderRuntimeArtifact | undefined {
157
+ return this.providerRuntime;
158
+ }
159
+
160
+ public async shutdown(gracePeriodMs?: number): Promise<void> {
161
+ this.workerHttpServer.markNotReady();
162
+ await this.workerHttpServer.shutdown(gracePeriodMs);
163
+ if (this.refreshTimer) {
164
+ clearInterval(this.refreshTimer);
165
+ this.refreshTimer = undefined;
166
+ }
167
+ this.bootstrapResponse = undefined;
168
+ this.providerRuntime = undefined;
169
+ this.isInitialized = false;
170
+ }
171
+
172
+ /**
173
+ * Install the worker's SIGTERM/SIGINT graceful-shutdown handler — the JSDoc's "SIGTERM handler
174
+ * per G-18 + KD-7" that audit A-11 found was claimed but absent (a signal would hard-kill the
175
+ * worker, dropping any final telemetry). The worker is deliberately queue-free (KD-3), so it does
176
+ * NOT use the RabbitMQ-coupled `WorkerShutdownManager`; instead it runs its own cleanup
177
+ * (`shutdown()`) and flushes OTel telemetry before exit — the worker-local analogue of the
178
+ * platform hosts' note-6 flush. `process.once` keeps the host killable (the handler exits).
179
+ * Idempotent.
180
+ */
181
+ private registerGracefulShutdown(): void {
182
+ if (this.signalHandlersRegistered) {
183
+ return;
184
+ }
185
+ this.signalHandlersRegistered = true;
186
+ process.once('SIGTERM', () => void this.gracefulShutdown('SIGTERM'));
187
+ process.once('SIGINT', () => void this.gracefulShutdown('SIGINT'));
188
+ }
189
+
190
+ private async gracefulShutdown(signal: string): Promise<void> {
191
+ // `console` is intentional — this runtime kernel injects no LoggerService.
192
+ // eslint-disable-next-line no-console
193
+ console.log(`[worker] received ${signal}, shutting down gracefully…`);
194
+ // Bounded force-exit so a stuck drain/flush can never wedge the process (mirrors the platform
195
+ // hosts' 5s budget). `unref()` keeps the timer from holding the loop open on its own.
196
+ const forceExit = setTimeout(() => process.exit(1), 5_000);
197
+ forceExit.unref();
198
+ try {
199
+ await this.shutdown();
200
+ // Audit A-3: flush the final OTel trace/log batch before exit. `process.exit` skips the
201
+ // preload's `beforeExit` backstop, so without this the worker's last batch is lost on a
202
+ // signal. No-op when telemetry is off (the global handle is undefined). Fail-open — a flush
203
+ // error must never turn a clean shutdown into a non-zero exit.
204
+ await getOtelSdkHandle()
205
+ ?.shutdown()
206
+ .catch(() => {
207
+ // best-effort flush
208
+ });
209
+ process.exit(0);
210
+ } catch {
211
+ process.exit(1);
212
+ }
213
+ }
214
+
215
+ private requireBootstrap(): AppWorkerBootstrapResponse {
216
+ if (!this.isInitialized || !this.bootstrapResponse) {
217
+ throw new Error(
218
+ 'StartWorkerApplicationBackendService.getBootstrapResponse() called before initialize() resolved.',
219
+ );
220
+ }
221
+ return this.bootstrapResponse;
222
+ }
223
+
224
+ private scheduleRefresh(intervalMs?: number): void {
225
+ if (this.refreshTimer) {
226
+ clearInterval(this.refreshTimer);
227
+ }
228
+ if (intervalMs === undefined || intervalMs <= 0) {
229
+ return;
230
+ }
231
+ this.refreshTimer = setInterval(() => {
232
+ void this.workerBootstrapClient
233
+ .getBootstrap({ force: true })
234
+ .then((response) => {
235
+ this.bootstrapResponse = response;
236
+ })
237
+ .catch(() => {
238
+ // Refresh failures keep the previously-cached key live so the
239
+ // verifier does not flap; the next interval re-attempts.
240
+ });
241
+ }, intervalMs);
242
+ if (typeof this.refreshTimer.unref === 'function') {
243
+ this.refreshTimer.unref();
244
+ }
245
+ }
246
+
247
+ /**
248
+ * Bridge the per-worker materialized provider runtime artifact into the
249
+ * `ProviderRuntimeArtifact` shape consumed by `StartApplicationBackendService`.
250
+ *
251
+ * Three accepted input shapes — see `StartMinionApplicationBackendService`
252
+ * for the same pattern. Summary:
253
+ *
254
+ * 1. `{ artifactKind: 'backend', scope: ... }` — already projected.
255
+ * 2. `{ artifactKind: 'nodeWorkers', scope: ..., scopes: undefined }` —
256
+ * pre-scoped per-worker module emitted by `wildo config sync`.
257
+ * 3. `{ artifactKind: 'nodeWorkers', scopes: { [name]: ... } }` —
258
+ * multi-scope artifact (legacy / non-CLI hosts).
259
+ */
260
+ private normalizeProviderRuntime(
261
+ providerRuntime: WorkerInitializationConfig['providerRuntime'],
262
+ workerName: string,
263
+ ): ProviderRuntimeArtifact | undefined {
264
+ if (!providerRuntime) {
265
+ return undefined;
266
+ }
267
+ if (providerRuntime.artifactKind === 'backend') {
268
+ return providerRuntime;
269
+ }
270
+ const artifactKind = providerRuntime.artifactKind;
271
+ if (artifactKind !== 'nodeWorkers') {
272
+ throw new Error(
273
+ `Unsupported provider runtime artifactKind '${artifactKind}' for worker '${workerName}'.`,
274
+ );
275
+ }
276
+
277
+ return this.selectWorkerProviderRuntimeScope(providerRuntime, workerName);
278
+ }
279
+
280
+ private selectWorkerProviderRuntimeScope(
281
+ providerRuntime: WorkerProviderRuntimeArtifact,
282
+ workerName: string,
283
+ ): ProviderRuntimeArtifact {
284
+ const preScopedScope = (providerRuntime as WorkerProviderRuntimeArtifact & {
285
+ scope?: ProviderRuntimeArtifact['scope'];
286
+ }).scope;
287
+ const scopes = providerRuntime.scopes as
288
+ | Record<string, ProviderRuntimeArtifact['scope']>
289
+ | undefined;
290
+
291
+ let scope: ProviderRuntimeArtifact['scope'] | undefined;
292
+
293
+ if (preScopedScope && (!scopes || Object.keys(scopes).length === 0)) {
294
+ scope = preScopedScope;
295
+ } else if (scopes) {
296
+ scope = scopes[workerName];
297
+ if (!scope) {
298
+ throw new Error(
299
+ `Provider runtime artifact does not contain a scope for worker '${workerName}'. `
300
+ + `Re-run \`wildo config sync\` and verify the worker is declared in `
301
+ + `wildo.saas.config.ts \`providers.scopes.workers\`.`,
302
+ );
303
+ }
304
+ }
305
+
306
+ if (!scope) {
307
+ throw new Error(
308
+ `Provider runtime artifact for worker '${workerName}' is missing both a `
309
+ + `pre-scoped \`scope\` and a multi-scope \`scopes\` map. The artifact is malformed.`,
310
+ );
311
+ }
312
+
313
+ // Recompute `providerRefs` from the projected per-host scope, NOT
314
+ // from the multi-scope union the parent artifact carries. The
315
+ // `buildMultiScopeArtifactMetadata` upstream computes
316
+ // `providerRefs` as the union across all hosts; preserving that
317
+ // here would make the boot-time `assertProviderRuntimeEnvInSync`
318
+ // guard treat sibling-scope refs as "this host has providers" and
319
+ // mistakenly run reconciliation on hosts whose own scope is empty.
320
+ // Mirrors `selectScopedProviderRuntimeArtifact` in
321
+ // `provider-runtime-artifacts.ts`.
322
+ const projectedProviderRefs = Object.keys(scope.providers ?? {}).sort();
323
+ // Narrowed with the refs, for the same reason (#330): the import map on a multi-scope artifact
324
+ // is the union across every host, and handing this host a sibling's package specifiers would
325
+ // tell it that it may load something it never declared.
326
+ const projectedProviderRuntimeImports = Object.fromEntries(
327
+ Object.entries(
328
+ providerRuntime.providerRuntimeImports ?? {},
329
+ ).filter(([providerRef]) => projectedProviderRefs.includes(providerRef)),
330
+ );
331
+
332
+ return {
333
+ __AUTOGENERATED__: providerRuntime.__AUTOGENERATED__,
334
+ generatedBy: providerRuntime.generatedBy,
335
+ generatedAt: providerRuntime.generatedAt,
336
+ sourceDigest: providerRuntime.sourceDigest,
337
+ providerRefs: projectedProviderRefs,
338
+ providerRuntimeImports: projectedProviderRuntimeImports,
339
+ providerGraphDigest: providerRuntime.providerGraphDigest,
340
+ lockfileSectionDigest: providerRuntime.lockfileSectionDigest,
341
+ artifactKind: 'backend',
342
+ modules: providerRuntime.modules,
343
+ scope,
344
+ };
345
+ }
346
+ }
@@ -0,0 +1,144 @@
1
+ import { injectable } from 'inversify';
2
+ import express, { type Express, type RequestHandler, Router } from 'express';
3
+ import helmet from 'helmet';
4
+ import type { Server } from 'http';
5
+ import type { ProviderRuntimeArtifact } from '@wildo-ai/saas-backend-lib';
6
+ import type { WorkerInitializationConfig } from './define-worker-init';
7
+ import { createWorkerJwtVerifierMiddleware } from '../middlewares/worker-jwt-verifier.middleware';
8
+ import { createWorkerRequestContextMiddleware } from '../middlewares/worker-request-context.middleware';
9
+
10
+ /**
11
+ * Lightweight HTTP server install for the Wildo worker runtime.
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
15
+ * does NOT pull `HttpServerBackendService` from `saas-backend-lib` — that
16
+ * service depends on `AppConfigurationService`, `RedisService`,
17
+ * `WebSocketService`, `ControllersRegistryHandlerBackendService`, etc.,
18
+ * none of which exist (or should exist) at the worker boundary.
19
+ *
20
+ * Surface:
21
+ * - `helmet` security headers (no CORS — workers are ClusterIP-only,
22
+ * never reached by browsers, never granted ingress).
23
+ * - `express.json()` body parser with a tight default limit.
24
+ * - Liveness / readiness probes mounted on the authored
25
+ * `WildoWorkerConfig.http.{healthPath,readyPath}` (no JWT required —
26
+ * K8s probe traffic is unauthenticated by design).
27
+ * - Optional `metricsPath` mounted unauthenticated for in-cluster
28
+ * prom-client scraping (KD-3: no public ingress, so this is fine).
29
+ * - All other routes are gated by the
30
+ * `APPLICATION_WORKER_REQUEST`-keyed JWT verifier; worker code
31
+ * registers them via `WorkerInitializationConfig.registerRoutes`.
32
+ *
33
+ * Correlation-id propagation (CC-8 / Phase 6) is wired: an early
34
+ * `createWorkerRequestContextMiddleware()` ingests the backend-stamped
35
+ * `x-correlation-id` into the request-context ALS frame, so a dispatch's
36
+ * backend-lib logs share the dispatching request's id and `req.correlationId`
37
+ * is available to handlers. The kernel itself still logs via `console` by
38
+ * 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
41
+ * verify a backend-api → worker round-trip end-to-end.
42
+ */
43
+ @injectable()
44
+ export class WorkerHttpServerBackendService {
45
+ private app?: Express;
46
+ private server?: Server;
47
+ private isReady = false;
48
+
49
+ public initialize(input: {
50
+ config: WorkerInitializationConfig;
51
+ providerRuntime?: ProviderRuntimeArtifact;
52
+ getCurrentPublicKey: () => string;
53
+ getRotatedPublicKeys?: () => Array<{ kid: string; publicKey: string; notAfter?: Date | string }>;
54
+ metricsHandler?: RequestHandler;
55
+ }): Promise<void> {
56
+ if (this.app) {
57
+ throw new Error('WorkerHttpServerBackendService.initialize called twice.');
58
+ }
59
+
60
+ const {
61
+ config,
62
+ providerRuntime,
63
+ getCurrentPublicKey,
64
+ getRotatedPublicKeys,
65
+ metricsHandler,
66
+ } = input;
67
+ const app = express();
68
+ app.disable('x-powered-by');
69
+ app.use(helmet());
70
+ app.use(express.json({ limit: '1mb' }));
71
+
72
+ app.get(config.http.healthPath, (_req, res) => {
73
+ res.status(200).json({ status: 'ok' });
74
+ });
75
+ app.get(config.http.readyPath, (_req, res) => {
76
+ if (this.isReady) {
77
+ res.status(200).json({ status: 'ready' });
78
+ } else {
79
+ res.status(503).json({ status: 'not_ready' });
80
+ }
81
+ });
82
+
83
+ if (config.http.metricsPath && metricsHandler) {
84
+ app.get(config.http.metricsPath, metricsHandler);
85
+ }
86
+
87
+ // Phase 6 — establish the correlation frame for dispatch traffic. Mounted AFTER the health / ready /
88
+ // metrics probes (they are registered above and short-circuit first, keeping high-frequency K8s probe
89
+ // traffic out of a frame) and BEFORE the authenticated router, so every worker dispatch — and the 404
90
+ // fallthrough — runs inside a frame carrying the backend-stamped `x-correlation-id`.
91
+ app.use(createWorkerRequestContextMiddleware());
92
+
93
+ const verifyJwt = createWorkerJwtVerifierMiddleware({
94
+ getCurrentPublicKey,
95
+ getRotatedPublicKeys,
96
+ });
97
+
98
+ if (config.registerRoutes) {
99
+ const authenticatedRouter = Router();
100
+ authenticatedRouter.use(verifyJwt);
101
+ config.registerRoutes(authenticatedRouter, { verifyJwt, providerRuntime });
102
+ app.use(authenticatedRouter);
103
+ }
104
+
105
+ app.use((_req, res) => {
106
+ res.status(404).json({ error: 'not_found' });
107
+ });
108
+
109
+ return new Promise((resolve, reject) => {
110
+ const server = app.listen(config.http.port, () => {
111
+ this.app = app;
112
+ this.server = server;
113
+ resolve();
114
+ });
115
+ server.on('error', reject);
116
+ });
117
+ }
118
+
119
+ public markReady(): void {
120
+ this.isReady = true;
121
+ }
122
+
123
+ public markNotReady(): void {
124
+ this.isReady = false;
125
+ }
126
+
127
+ public async shutdown(gracePeriodMs: number = 10_000): Promise<void> {
128
+ this.isReady = false;
129
+ if (!this.server) return;
130
+ const server = this.server;
131
+ await new Promise<void>((resolve) => {
132
+ const timer = setTimeout(() => {
133
+ server.closeAllConnections?.();
134
+ resolve();
135
+ }, gracePeriodMs);
136
+ server.close(() => {
137
+ clearTimeout(timer);
138
+ resolve();
139
+ });
140
+ });
141
+ this.server = undefined;
142
+ this.app = undefined;
143
+ }
144
+ }