@drsamonline/gateway 0.0.0-stage → 0.12.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/src/workers.js ADDED
@@ -0,0 +1,298 @@
1
+ /**
2
+ * Background workers (B9.1).
3
+ *
4
+ * Nothing here is on the request path (I1). Each job is a timer that does one
5
+ * thing, records when it last ran, and can be stopped cleanly — because a
6
+ * gateway that will not exit on Ctrl-C is a gateway nobody restarts.
7
+ *
8
+ * Jobs today:
9
+ * prober hourly, liveness/readiness/suitability over the catalogue (B2.3)
10
+ * cache_sweep every few minutes, drop expired cache entries so memory is bounded
11
+ *
12
+ * Deliberately absent until their batches land: catalog_sync (B2.2),
13
+ * quota_telemetry (B2.3 follow-on), red_team_self_test (B6.2), canary_rollout (B9.2).
14
+ */
15
+
16
+ import { dirname, join } from 'node:path';
17
+ import { fileURLToPath } from 'node:url';
18
+ import { Prober } from '@drsamonline/prober';
19
+ import { runSelfTest } from '@drsamonline/redteam';
20
+ import { THRESHOLDS, checkBudgets, dedupe } from './alerts.js';
21
+ import { DriftMonitor, HistoryStore, driftFromLedger } from '@drsamonline/telemetry';
22
+ import { dedupeEntries, loadSeed } from '@drsamonline/catalog';
23
+
24
+ /**
25
+ * @param {{
26
+ * config: any, cache: any, ledger: any, logger?: any,
27
+ * catalogDir?: string, now?: () => number, prober?: any
28
+ * }} deps
29
+ */
30
+ export function startWorkers(deps) {
31
+ const { config, cache, ledger } = deps;
32
+ const logger = deps.logger ?? { info() {}, warn() {}, debug() {} };
33
+ const now = deps.now ?? Date.now;
34
+ const settings = config.workers ?? {};
35
+ const enabled = settings.enabled !== false;
36
+
37
+ /** @type {Array<{name: string, timer: any, intervalMs: number, lastRunAt: number|null, runs: number, lastError: string|null, lastResult: any}>} */
38
+ const jobs = [];
39
+ let prober = deps.prober ?? null;
40
+ let stopped = false;
41
+
42
+ if (enabled) {
43
+ // B2.7: created before any job, so /api/history works even when the prober
44
+ // is switched off — the history file is the record, not the prober's memory.
45
+ const history = new HistoryStore({
46
+ file: deps.historyFile ?? settings.historyFile ?? null,
47
+ maxRows: Number(settings.historyMaxRows ?? 20_000),
48
+ });
49
+ deps.history = history;
50
+
51
+ if (settings.prober?.enabled !== false) {
52
+ const entries = loadProbeTargets(deps.catalogDir);
53
+ if (entries.length) {
54
+ prober = new Prober({
55
+ entries,
56
+ intervalMs: Number(settings.prober?.intervalMs ?? 3600_000),
57
+ failuresBeforeDisable: Number(settings.prober?.failuresBeforeDisable ?? 3),
58
+ timeoutMs: Number(settings.prober?.timeoutMs ?? 8000),
59
+ now,
60
+ onResult: (result, state) => {
61
+ if (!result.ok) logger.warn(`probe ${result.provider}: ${result.reasons[0] ?? 'failed'} (${state.status})`);
62
+ },
63
+ });
64
+ jobs.push(
65
+ register('prober', Number(settings.prober?.intervalMs ?? 3600_000), async () => {
66
+ const results = await prober.runOnce();
67
+ // B2.7: one sample per target per pass — a timestamp, an id, a
68
+ // duration and a boolean. There is nowhere for a prompt to go.
69
+ for (const result of results) {
70
+ history.record({
71
+ modelId: result.pool_key ?? result.provider ?? 'unknown',
72
+ ok: Boolean(result.ok),
73
+ latencyMs: result.latencyMs ?? null,
74
+ state: result.ok ? 'closed' : 'open',
75
+ ts: result.checkedAt ?? Date.now(),
76
+ });
77
+ }
78
+ return { probed: results.length, verified: results.filter((r) => r.verified).length };
79
+ }),
80
+ );
81
+ } else {
82
+ logger.debug('prober: no catalogue entry has a base_url to probe yet');
83
+ }
84
+ }
85
+
86
+ // B6.2: attack our own routes on a schedule. A weekly run is enough to catch
87
+ // a provider that changed behaviour; a nightly one would spend quota for the
88
+ // same answer.
89
+ if (settings.redTeam?.enabled === true && deps.router) {
90
+ jobs.push(
91
+ register('red_team_self_test', Number(settings.redTeam.intervalMs ?? 7 * 24 * 3600_000), async () => {
92
+ const combo = settings.redTeam.combo ?? Object.keys(deps.config.combos ?? {})[0];
93
+ if (!combo) return { skipped: 'no combo to test' };
94
+ const report = await runSelfTest({ combo, chat: (input) => deps.router.chat(input) });
95
+ if (!report.pass) logger.warn(`red-team self-test: ${report.counts.critical} CRITICAL, ${report.counts.high} ambiguous on "${combo}"`);
96
+ return { combo, pass: report.pass, counts: report.counts };
97
+ }),
98
+ );
99
+ }
100
+
101
+ // B7.3: budget alerts. Cheap enough to run every minute, and deduped so a
102
+ // threshold fires once per scope per day rather than on every tick.
103
+ const sentAlerts = new Set();
104
+ /** @type {Array<any>} */
105
+ const alertLog = [];
106
+ const alertMs = intervalFor(settings.alertIntervalMs, 60_000);
107
+ if (alertMs) jobs.push(
108
+ register('budget_alerts', alertMs, async () => {
109
+ const fresh = dedupe(checkBudgets({ config: deps.config, ledger: deps.ledger }), sentAlerts);
110
+ for (const alert of fresh) {
111
+ logger.warn(alert.message);
112
+ alertLog.push({ ...alert, at: Date.now() });
113
+ if (alertLog.length > 50) alertLog.shift();
114
+ }
115
+ return { fired: fresh.length, thresholds: THRESHOLDS };
116
+ }),
117
+ );
118
+ deps.alerts = { log: () => [...alertLog], sent: () => [...sentAlerts] };
119
+
120
+ // B3.7: drift runs on a slow timer, off the request path, and never on the
121
+ // same samples twice — it reads what the ledger has recorded since last time.
122
+ const driftMonitor = new DriftMonitor({ baselineSamples: 10, threshold: Number(settings.driftThreshold ?? 5) });
123
+ const driftMs = intervalFor(settings.driftIntervalMs, 300_000);
124
+ if (driftMs) jobs.push(
125
+ register('drift_monitor', driftMs, async () => {
126
+ const records = deps.ledger.records ?? [];
127
+ const { alarms } = driftFromLedger({ records, monitor: driftMonitor, since: 0, minSamples: 10 });
128
+ for (const alarm of alarms) {
129
+ logger.warn(`drift on ${alarm.key}: ${alarm.alarm.direction} (cusum ${alarm.alarm.cusum}, baseline ${alarm.baseline}, now ${alarm.ewma})`);
130
+ }
131
+ return { series: driftMonitor.series.size, alarms: alarms.length };
132
+ }),
133
+ );
134
+ deps.drift = { snapshot: () => [...driftMonitor.series.keys()].map((k) => driftMonitor.snapshot(k)), alarms: () => driftMonitor.alarms() };
135
+
136
+ const sweepMs = intervalFor(settings.cacheSweepMs, 300_000);
137
+ if (cache?.sweep && sweepMs) {
138
+ jobs.push(register('cache_sweep', sweepMs, async () => cache.sweep()));
139
+ }
140
+ }
141
+
142
+ /**
143
+ * @param {string} name
144
+ * @param {number} intervalMs
145
+ * @param {() => Promise<any>} run
146
+ */
147
+ /**
148
+ * B9.6 — a worker that cannot pile up, cannot hammer a failing dependency, and
149
+ * cannot drift into a thundering herd with its siblings.
150
+ *
151
+ * overlap a tick that arrives while the previous one is still running is
152
+ * skipped, not queued: a slow probe should not become two
153
+ * backoff after a failure the interval doubles, up to 16x, and resets on
154
+ * the first success
155
+ * jitter the first tick is offset, so six jobs do not all fire at boot
156
+ */
157
+ /**
158
+ * An interval that is not a positive number means "this job is off".
159
+ *
160
+ * `setInterval(fn, 0)` is not a fast timer, it is a busy loop: the callback
161
+ * runs again the moment the previous one yields, which pegs a core and starves
162
+ * every other timer in the process. A config value of 0 read as "off" is the
163
+ * only sane interpretation, and `0 ?? fallback` does not give it — nullish
164
+ * coalescing only replaces null and undefined.
165
+ */
166
+ function intervalFor(value, fallback) {
167
+ const ms = Number(value ?? fallback);
168
+ return Number.isFinite(ms) && ms > 0 ? ms : null;
169
+ }
170
+
171
+ function register(name, intervalMs, run) {
172
+ const job = {
173
+ name,
174
+ timer: null,
175
+ intervalMs,
176
+ baseIntervalMs: intervalMs,
177
+ lastRunAt: null,
178
+ runs: 0,
179
+ skipped: 0,
180
+ failures: 0,
181
+ running: false,
182
+ lastError: null,
183
+ lastResult: null,
184
+ run, // swappable, which is how the overlap guard is tested
185
+ };
186
+
187
+ const reschedule = (target, intervalMs) => {
188
+ if (target.timer) clearInterval(target.timer);
189
+ target.intervalMs = intervalMs;
190
+ target.timer = setInterval(tick, intervalMs);
191
+ target.timer.unref?.();
192
+ };
193
+
194
+ const tick = async () => {
195
+ if (stopped) return;
196
+ if (job.running) {
197
+ job.skipped += 1;
198
+ return;
199
+ }
200
+ job.running = true;
201
+ try {
202
+ job.lastResult = await job.run();
203
+ job.lastError = null;
204
+ if (job.failures > 0) {
205
+ job.failures = 0;
206
+ reschedule(job, job.baseIntervalMs);
207
+ }
208
+ } catch (err) {
209
+ job.lastError = /** @type {any} */ (err)?.message ?? String(err);
210
+ job.failures += 1;
211
+ const backoff = Math.min(job.baseIntervalMs * 2 ** Math.min(job.failures, 4), job.baseIntervalMs * 16);
212
+ reschedule(job, backoff);
213
+ logger.warn(`${name} failed (${job.failures}x, next in ${Math.round(backoff / 1000)}s): ${job.lastError}`);
214
+ } finally {
215
+ job.running = false;
216
+ job.lastRunAt = now();
217
+ job.runs += 1;
218
+ }
219
+ };
220
+
221
+ // First run happens shortly after boot, not during it: startup must not wait
222
+ // on a network call (I5 wants a fresh install answering in 30s).
223
+ // B9.6: jitter the first tick so a restart does not fire every job at once
224
+ const kickoffMs = Number(settings.kickoffMs ?? 1500);
225
+ const kickoff = setTimeout(tick, kickoffMs + Math.floor(Math.random() * Math.max(1, kickoffMs)));
226
+ kickoff.unref?.();
227
+ job.runNow = tick;
228
+ job.timer = setInterval(tick, intervalMs);
229
+ job.timer.unref?.();
230
+ return job;
231
+ }
232
+
233
+ return {
234
+ jobs,
235
+ get prober() {
236
+ return prober;
237
+ },
238
+ // B2.7: the store is on the returned object, not only on `deps`, so a caller
239
+ // does not have to know how startWorkers was wired internally.
240
+ get history() {
241
+ return deps.history ?? null;
242
+ },
243
+ snapshot() {
244
+ return {
245
+ enabled,
246
+ jobs: jobs.map((j) => ({
247
+ name: j.name,
248
+ intervalMs: j.intervalMs,
249
+ runs: j.runs,
250
+ skipped: j.skipped,
251
+ failures: j.failures,
252
+ lastRunAt: j.lastRunAt,
253
+ nextRunAt: j.lastRunAt ? j.lastRunAt + j.intervalMs : null,
254
+ lastError: j.lastError,
255
+ lastResult: j.lastResult,
256
+ })),
257
+ probes: prober ? prober.snapshot() : [],
258
+ alerts: deps.alerts?.log?.() ?? [],
259
+ drift: deps.drift?.alarms?.() ?? [],
260
+ };
261
+ },
262
+ stop() {
263
+ stopped = true;
264
+ for (const job of jobs) {
265
+ if (job.timer) clearInterval(job.timer);
266
+ job.timer = null;
267
+ }
268
+ },
269
+ };
270
+ }
271
+
272
+ /**
273
+ * The catalogue entries worth probing: only those with a resolved base_url.
274
+ * An identity with no endpoint is not a probe target, and pretending otherwise
275
+ * would produce a failure that says nothing.
276
+ */
277
+ export function loadProbeTargets(catalogDir) {
278
+ // `sui start` runs from the user's project directory, where packages/catalog
279
+ // does not exist. Fall back to the catalogue that shipped with the package.
280
+ const candidates = catalogDir
281
+ ? [catalogDir]
282
+ : [join(process.cwd(), 'packages', 'catalog'), join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'packages', 'catalog')];
283
+
284
+ for (const dir of candidates) {
285
+ const entries = [];
286
+ let found = false;
287
+ for (const file of ['seed.json', 'generated.json']) {
288
+ try {
289
+ entries.push(...loadSeed(join(dir, file)));
290
+ found = true;
291
+ } catch {
292
+ /* a missing file is not an error: a trimmed checkout still runs */
293
+ }
294
+ }
295
+ if (found) return dedupeEntries(entries).filter((e) => e.base_url);
296
+ }
297
+ return [];
298
+ }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.