@netgreener/runtime 0.1.10 → 0.1.12

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 (39) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/dist/aggregator.d.ts +3 -0
  3. package/dist/aggregator.js +36 -13
  4. package/dist/analyze/buildResourceFindings.d.ts +1 -1
  5. package/dist/analyze/buildResourceFindings.js +4 -2
  6. package/dist/analyze/findingGuidance.d.ts +14 -0
  7. package/dist/analyze/findingGuidance.js +52 -0
  8. package/dist/analyze/index.d.ts +3 -2
  9. package/dist/analyze/index.js +3 -2
  10. package/dist/analyze/projectScan.d.ts +3 -1
  11. package/dist/analyze/projectScan.js +29 -6
  12. package/dist/analyze/resourceFindingCandidate.d.ts +6 -0
  13. package/dist/analyze/resourceFindingCandidate.js +11 -0
  14. package/dist/analyze/serviceDiscovery.d.ts +23 -1
  15. package/dist/analyze/serviceDiscovery.js +164 -4
  16. package/dist/cli/helpText.js +1 -0
  17. package/dist/cli/netgreener.js +8 -0
  18. package/dist/cli/runtimeCli.d.ts +2 -0
  19. package/dist/cli/runtimeCli.js +35 -0
  20. package/dist/config.js +3 -1
  21. package/dist/exporter.js +9 -0
  22. package/dist/externalApiMeter.js +12 -7
  23. package/dist/index.d.ts +1 -1
  24. package/dist/index.js +1 -1
  25. package/dist/managedCollectorLauncher.d.ts +2 -1
  26. package/dist/managedCollectorLauncher.js +2 -1
  27. package/dist/mcpToolMeter.js +6 -1
  28. package/dist/processResources.js +5 -2
  29. package/dist/runtime.d.ts +4 -5
  30. package/dist/runtime.js +86 -50
  31. package/dist/runtimeControls.d.ts +5 -0
  32. package/dist/runtimeControls.js +69 -0
  33. package/dist/runtimeHealth.d.ts +15 -0
  34. package/dist/runtimeHealth.js +47 -1
  35. package/dist/tenantContext.d.ts +4 -0
  36. package/dist/tenantContext.js +36 -10
  37. package/dist/uploader.js +45 -1
  38. package/fixtures/git/canonical_git_key_vectors.v1.json +66 -0
  39. package/package.json +1 -1
package/dist/runtime.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { meteringAllowed, startRuntimeControls } from './runtimeControls.js';
1
2
  import { hostname } from 'node:os';
2
3
  import { ServiceRuntimeAggregator } from './aggregator.js';
3
4
  import { carbonFactorDict } from './carbonLedger.js';
@@ -9,8 +10,7 @@ import { enrichRunContextForAnomaly } from './runContextEnrichment.js';
9
10
  import { getOccupancyTracker } from './occupancyTracker.js';
10
11
  import { getExternalAggregator, getOriginalFetch, installOutboundInstrumentation, } from './externalApiMeter.js';
11
12
  import { buildMcpLatencyV0, getMcpToolLedger, } from './mcpToolMeter.js';
12
- import { CPU_SOURCE_PROCESS, MEMORY_SOURCE_PROCESS, } from './processResources.js';
13
- import { CPU_SOURCE_DURATION_PROXY } from './n4/missingnessInventory.js';
13
+ import { CPU_SOURCE_PROCESS, MEMORY_SOURCE_PROCESS, beginProcessResourceSample, endProcessResourceSample, } from './processResources.js';
14
14
  import { buildRuntimeHealthV0, markHooksActive, mergeHealthIntoMetadata, noteExportAttempt, noteExportMode, noteExportResult, noteFlushSkippedInFlight, _resetRuntimeHealthForTests, } from './runtimeHealth.js';
15
15
  import { resolveLifecycle, } from './lifecycle.js';
16
16
  function vercelDeploymentHosts() {
@@ -53,11 +53,9 @@ export class NetGreenerRuntime {
53
53
  /** In-flight HTTP/task units — gates ephemeral idle flush. */
54
54
  inFlight = 0;
55
55
  invokeFlushScheduled = false;
56
- /**
57
- * Sticky window id until a successful export — preserves idempotency across
58
- * retry of the same in-memory snapshot (serverless / network retry).
59
- */
60
- stickyWindowId = null;
56
+ /** Exact pending window; observations arriving during retries stay separate. */
57
+ pendingPayload = null;
58
+ cpuWindowMark = beginProcessResourceSample();
61
59
  constructor(opts = {}) {
62
60
  this.config = opts.config ?? loadRuntimeConfig();
63
61
  this.collector = opts.collector ?? 'express_middleware';
@@ -75,7 +73,7 @@ export class NetGreenerRuntime {
75
73
  return this.lifecycleInfo.lifecycle;
76
74
  }
77
75
  get enabled() {
78
- return configReady(this.config).ok;
76
+ return configReady(this.config).ok && meteringAllowed(this.config);
79
77
  }
80
78
  ensureOutboundMeter() {
81
79
  if (this.outboundInstalled || !this.enabled)
@@ -109,8 +107,27 @@ export class NetGreenerRuntime {
109
107
  if (this.started)
110
108
  return;
111
109
  this.started = true;
112
- if (!this.enabled)
110
+ if (!configReady(this.config).ok)
113
111
  return;
112
+ let pauseCpu = null;
113
+ let pauseAt = 0;
114
+ if (!meteringAllowed(this.config)) {
115
+ pauseAt = Date.now();
116
+ pauseCpu = process.cpuUsage();
117
+ }
118
+ startRuntimeControls(this.config, this.uploadFetch(), (enabled) => {
119
+ if (!enabled) {
120
+ pauseAt = Date.now();
121
+ pauseCpu = process.cpuUsage();
122
+ }
123
+ else if (pauseCpu) {
124
+ const delta = process.cpuUsage(pauseCpu);
125
+ this.cpuWindowMark.cpuStart.user += delta.user;
126
+ this.cpuWindowMark.cpuStart.system += delta.system;
127
+ this.aggregator.excludePausedTime(Date.now() - pauseAt);
128
+ pauseCpu = null;
129
+ }
130
+ });
114
131
  markHooksActive({
115
132
  processKind: this.framework,
116
133
  exportMode: this.exporter.mode,
@@ -208,6 +225,28 @@ export class NetGreenerRuntime {
208
225
  ...(sample.peakRssKb !== undefined ? { peakRssKb: sample.peakRssKb } : {}),
209
226
  });
210
227
  }
228
+ async exportPendingWindow() {
229
+ const payload = this.pendingPayload;
230
+ noteExportAttempt(this.exporter.mode);
231
+ let result;
232
+ try {
233
+ result = await this.exporter.exportRunSessionWindow(this.config, structuredClone(payload), this.uploadFetch());
234
+ }
235
+ catch (err) {
236
+ result = { ok: false, error: err instanceof Error ? err.message : String(err) };
237
+ }
238
+ noteExportResult(result.ok, result.ok ? undefined : 'error' in result ? result.error : 'export_failed');
239
+ if (result.ok)
240
+ this.pendingPayload = null;
241
+ // Observers must not mutate a pending retry or turn an ACK into a retry.
242
+ try {
243
+ this.onFlush?.(result, structuredClone(payload));
244
+ }
245
+ catch {
246
+ /* Export state is independent of application observer failures. */
247
+ }
248
+ return result;
249
+ }
211
250
  async flush(kind = 'manual') {
212
251
  if (!this.enabled)
213
252
  return null;
@@ -215,6 +254,15 @@ export class NetGreenerRuntime {
215
254
  noteFlushSkippedInFlight();
216
255
  return null;
217
256
  }
257
+ if (this.pendingPayload) {
258
+ this.flushing = true;
259
+ try {
260
+ return await this.exportPendingWindow();
261
+ }
262
+ finally {
263
+ this.flushing = false;
264
+ }
265
+ }
218
266
  const externalAgg = getExternalAggregator();
219
267
  const hasRuntime = this.aggregator.hasData();
220
268
  const hasExternal = externalAgg.hasData();
@@ -225,17 +273,16 @@ export class NetGreenerRuntime {
225
273
  noteExportMode(this.exporter.mode);
226
274
  const snapshot = hasRuntime ? this.aggregator.takeSnapshot() : null;
227
275
  const externalSnapshot = hasExternal ? externalAgg.takeSnapshot() : null;
276
+ const previousCpuMark = this.cpuWindowMark;
228
277
  try {
229
278
  const windowStartedMs = snapshot
230
279
  ? snapshot.windowStartedMs()
231
280
  : Date.now() - 1000;
232
281
  const windowSeconds = Math.max(0.001, (Date.now() - windowStartedMs) / 1000);
233
- // Crude trend energy: TDP * utilization proxy from request busy time.
234
- const busySeconds = snapshot
235
- ? snapshot.hasMeasuredCpu()
236
- ? snapshot.totalMeasuredCpuMs() / 1000
237
- : snapshot.totalDurationMs() / 1000
238
- : 0;
282
+ const windowCpuSeconds = endProcessResourceSample(this.cpuWindowMark).cpuTimeMs / 1000;
283
+ this.cpuWindowMark = beginProcessResourceSample();
284
+ // Trend energy estimate from one process CPU delta, not overlapping requests.
285
+ const busySeconds = snapshot ? windowCpuSeconds : 0;
239
286
  const util = Math.min(1, busySeconds / Math.max(windowSeconds, 0.001));
240
287
  const windowEnergyKwh = (this.config.estimateTdpWatts * util * windowSeconds) / 1000 / 3600;
241
288
  const occupancy = getOccupancyTracker().takeWindowSnapshot();
@@ -251,6 +298,7 @@ export class NetGreenerRuntime {
251
298
  windowEnergyKwh,
252
299
  windowSeconds,
253
300
  windowRamGbHours,
301
+ windowCpuSeconds,
254
302
  occupancy,
255
303
  })
256
304
  : null;
@@ -271,9 +319,7 @@ export class NetGreenerRuntime {
271
319
  const latencyV0 = buildMcpLatencyV0(mcpV0, externalV0 ?? null, windowSeconds);
272
320
  const end = new Date();
273
321
  const start = new Date(end.getTime() - windowSeconds * 1000);
274
- // Reuse sticky id until success so retries do not mint a new window.
275
- const windowId = this.stickyWindowId ?? newRuntimeWindowId();
276
- this.stickyWindowId = windowId;
322
+ const windowId = newRuntimeWindowId();
277
323
  // Prefer effective RuntimeConfig over ambient process.env.
278
324
  const tenantConfig = tenantConfigFromRuntime(this.config);
279
325
  const runContext = {
@@ -296,7 +342,6 @@ export class NetGreenerRuntime {
296
342
  tenantConfig,
297
343
  activeContext: getTenantContext(),
298
344
  });
299
- const measuredCpu = snapshot?.hasMeasuredCpu() ?? false;
300
345
  const measuredRss = snapshot?.hasMeasuredRss() ?? false;
301
346
  const carbonFactor = carbonFactorDict();
302
347
  const session_metadata = {
@@ -306,11 +351,7 @@ export class NetGreenerRuntime {
306
351
  ...(mcpV0 ? { mcp_tool_v0: mcpV0 } : {}),
307
352
  ...(latencyV0 ? { mcp_latency_v0: latencyV0 } : {}),
308
353
  measurement_provenance: {
309
- cpu_source: runtimeV0
310
- ? measuredCpu
311
- ? CPU_SOURCE_PROCESS
312
- : CPU_SOURCE_DURATION_PROXY
313
- : 'unavailable',
354
+ cpu_source: runtimeV0 ? CPU_SOURCE_PROCESS : 'unavailable',
314
355
  memory_source: measuredRss ? MEMORY_SOURCE_PROCESS : 'unavailable',
315
356
  energy_model: runtimeV0 ? 'tdp_utilization_estimate' : 'unavailable',
316
357
  gpu_scope: 'none',
@@ -348,26 +389,11 @@ export class NetGreenerRuntime {
348
389
  runtime_window_id: windowId,
349
390
  session_metadata,
350
391
  };
351
- noteExportAttempt(this.exporter.mode);
352
- const result = await this.exporter.exportRunSessionWindow(this.config, payload, this.uploadFetch());
353
- noteExportResult(result.ok, result.ok ? undefined : 'error' in result ? result.error : 'export_failed');
354
- mergeHealthIntoMetadata(session_metadata, buildRuntimeHealthV0());
355
- if (!result.ok) {
356
- if (snapshot)
357
- this.aggregator.mergeSnapshot(snapshot);
358
- if (externalSnapshot)
359
- externalAgg.mergeSnapshot(externalSnapshot);
360
- if (mcpSnapshot)
361
- getMcpToolLedger().mergeSnapshot(mcpSnapshot);
362
- // Keep stickyWindowId so the next flush retries the same window id.
363
- }
364
- else {
365
- this.stickyWindowId = null;
366
- }
367
- this.onFlush?.(result, payload);
368
- return result;
392
+ this.pendingPayload = structuredClone(payload);
393
+ return await this.exportPendingWindow();
369
394
  }
370
395
  catch (err) {
396
+ this.cpuWindowMark = previousCpuMark;
371
397
  noteExportResult(false, err instanceof Error ? err.message : String(err));
372
398
  if (snapshot)
373
399
  this.aggregator.mergeSnapshot(snapshot);
@@ -379,13 +405,18 @@ export class NetGreenerRuntime {
379
405
  ok: false,
380
406
  error: err instanceof Error ? err.message : String(err),
381
407
  };
382
- this.onFlush?.(result, {
383
- project_id: this.config.projectId,
384
- start_time: new Date().toISOString(),
385
- end_time: new Date().toISOString(),
386
- runtime_window_id: this.stickyWindowId ?? newRuntimeWindowId(),
387
- session_metadata: {},
388
- });
408
+ try {
409
+ this.onFlush?.(result, {
410
+ project_id: this.config.projectId,
411
+ start_time: new Date().toISOString(),
412
+ end_time: new Date().toISOString(),
413
+ runtime_window_id: newRuntimeWindowId(),
414
+ session_metadata: {},
415
+ });
416
+ }
417
+ catch {
418
+ /* Observer errors must never escape telemetry flush. */
419
+ }
389
420
  return result;
390
421
  }
391
422
  finally {
@@ -394,7 +425,12 @@ export class NetGreenerRuntime {
394
425
  }
395
426
  async shutdown() {
396
427
  this.stop();
397
- return this.flush('shutdown');
428
+ const hadPending = this.pendingPayload !== null;
429
+ const result = await this.flush('shutdown');
430
+ if (hadPending && result?.ok) {
431
+ return (await this.flush('shutdown')) ?? result;
432
+ }
433
+ return result;
398
434
  }
399
435
  }
400
436
  let globalRuntime = null;
@@ -0,0 +1,5 @@
1
+ import type { RuntimeConfig } from './config.js';
2
+ export declare function meteringAllowed(config?: RuntimeConfig): boolean;
3
+ export declare function applyRuntimeControls(config: RuntimeConfig, enabled: boolean, orgId?: number): void;
4
+ export declare function refreshRuntimeControls(config: RuntimeConfig, fetchImpl: typeof fetch): Promise<void>;
5
+ export declare function startRuntimeControls(config: RuntimeConfig, fetchImpl: typeof fetch, onChange?: (enabled: boolean) => void): void;
@@ -0,0 +1,69 @@
1
+ /** Company policy cache shared by JavaScript/TypeScript hooks and exporters. */
2
+ import { createHash } from 'node:crypto';
3
+ import { jwtPayloadUnverified } from './tenantContext.js';
4
+ const states = new Map();
5
+ let activeKey;
6
+ function accountKey(config) {
7
+ return createHash('sha256').update(JSON.stringify([config.apiUrl, config.organizationId, config.token])).digest('hex');
8
+ }
9
+ function stateFor(config) {
10
+ const key = accountKey(config);
11
+ let state = states.get(key);
12
+ if (!state) {
13
+ const claim = jwtPayloadUnverified(`Bearer ${config.token}`)?.org_id;
14
+ const id = config.organizationId ?? Number(claim);
15
+ state = { enabled: true, orgId: Number.isSafeInteger(id) && Number(id) > 0 ? Number(id) : null, refreshing: false, listeners: new Set() };
16
+ states.set(key, state);
17
+ }
18
+ return state;
19
+ }
20
+ export function meteringAllowed(config) {
21
+ return (config ? stateFor(config) : activeKey ? states.get(activeKey) : undefined)?.enabled ?? true;
22
+ }
23
+ export function applyRuntimeControls(config, enabled, orgId) {
24
+ const state = stateFor(config);
25
+ if (orgId != null && Number.isSafeInteger(orgId) && orgId > 0)
26
+ state.orgId = orgId;
27
+ activeKey = accountKey(config);
28
+ if (state.enabled === enabled)
29
+ return;
30
+ state.enabled = enabled;
31
+ for (const listener of state.listeners)
32
+ listener(enabled);
33
+ }
34
+ export async function refreshRuntimeControls(config, fetchImpl) {
35
+ const state = stateFor(config);
36
+ if (config.dryRun || state.orgId == null || state.refreshing)
37
+ return;
38
+ state.refreshing = true;
39
+ try {
40
+ const response = await fetchImpl(`${config.apiUrl}/api/v1/organizations/${state.orgId}/runtime-controls`, {
41
+ headers: { Authorization: `Bearer ${config.token}`, 'X-Organization-ID': String(state.orgId) },
42
+ signal: AbortSignal.timeout(5000),
43
+ });
44
+ if (!response.ok)
45
+ return;
46
+ const data = await response.json();
47
+ if (data.org_id === state.orgId && typeof data.metering_enabled === 'boolean') {
48
+ applyRuntimeControls(config, data.metering_enabled);
49
+ }
50
+ }
51
+ catch {
52
+ // Retain the last known policy, including a known pause, during outages.
53
+ }
54
+ finally {
55
+ state.refreshing = false;
56
+ }
57
+ }
58
+ export function startRuntimeControls(config, fetchImpl, onChange) {
59
+ if (config.dryRun || !config.enabled)
60
+ return;
61
+ activeKey = accountKey(config);
62
+ const state = stateFor(config);
63
+ if (onChange)
64
+ state.listeners.add(onChange);
65
+ if (state.timer)
66
+ return;
67
+ state.timer = setInterval(() => { void refreshRuntimeControls(config, fetchImpl); }, 30_000);
68
+ state.timer.unref?.();
69
+ }
@@ -4,6 +4,21 @@
4
4
  * Additive ``runtime_health_v0`` twin of Python ``netgreener.runtime_health``.
5
5
  * Does not change upload defaults or invent collector spool metrics.
6
6
  */
7
+ export type RuntimeSetupCheck = {
8
+ name: string;
9
+ status: 'pass' | 'fail' | 'not_verified';
10
+ detail: string;
11
+ };
12
+ export declare function inspectRuntimeSetup(env?: NodeJS.ProcessEnv): {
13
+ schema: "netgreener_runtime_status_v1";
14
+ scope: "local_configuration";
15
+ ready: boolean;
16
+ enabled: boolean;
17
+ dry_run: boolean;
18
+ lifecycle: import("./lifecycle.js").RuntimeLifecycle;
19
+ export_mode: import("./exporter.js").ExportMode;
20
+ checks: RuntimeSetupCheck[];
21
+ };
7
22
  export type RuntimeHealthStatus = 'ok' | 'degraded' | 'conflict' | 'unknown';
8
23
  export type RuntimeHealthV0 = {
9
24
  schema_version: 1;
@@ -4,6 +4,52 @@
4
4
  * Additive ``runtime_health_v0`` twin of Python ``netgreener.runtime_health``.
5
5
  * Does not change upload defaults or invent collector spool metrics.
6
6
  */
7
+ import { configReady, loadRuntimeConfig } from './config.js';
8
+ import { exportModeFromEnv } from './exporter.js';
9
+ import { resolveLifecycle } from './lifecycle.js';
10
+ import { normalizeCollectorEndpoint } from './collectorIpc.js';
11
+ export function inspectRuntimeSetup(env = process.env) {
12
+ const config = loadRuntimeConfig(env);
13
+ const lifecycle = resolveLifecycle({ env }).lifecycle;
14
+ const exportMode = exportModeFromEnv(env, { lifecycle });
15
+ let validApiUrl = false;
16
+ try {
17
+ const url = new URL(config.apiUrl);
18
+ validApiUrl = ['https:', 'http:'].includes(url.protocol) && Boolean(url.hostname);
19
+ }
20
+ catch { }
21
+ let validDelivery = exportMode !== 'collector';
22
+ if (exportMode === 'collector') {
23
+ try {
24
+ const endpoint = new URL(normalizeCollectorEndpoint(env.NETGREENER_COLLECTOR_ENDPOINT || ''));
25
+ validDelivery = endpoint.protocol === 'tcp:'
26
+ ? Boolean(endpoint.hostname && Number(endpoint.port) > 0 && Number(endpoint.port) <= 65535)
27
+ : endpoint.protocol === 'unix:' && process.platform !== 'win32' && endpoint.pathname.startsWith('/');
28
+ }
29
+ catch { }
30
+ }
31
+ const checks = [
32
+ { name: 'runtime_enabled', status: config.enabled ? 'pass' : 'fail', detail: 'Set the token and project ID to enable automatically; NETGREENER_SERVICE_RUNTIME=0 disables it.' },
33
+ { name: 'credentials', status: config.token ? 'pass' : 'fail', detail: 'NETGREENER_TOKEN is checked for presence only; authentication is not verified.' },
34
+ { name: 'project', status: config.projectId > 0 ? 'pass' : 'fail', detail: 'NETGREENER_PROJECT_ID must be a positive safe integer; project access is not verified.' },
35
+ { name: 'api_url', status: validApiUrl ? 'pass' : 'fail', detail: 'NETGREENER_API_URL must be an HTTP(S) URL; the endpoint is not contacted.' },
36
+ { name: 'delivery', status: validDelivery ? 'pass' : 'fail', detail: 'Collector mode requires a valid TCP host/port or supported Unix socket endpoint; availability is not verified.' },
37
+ ...['hooks', 'tenant_attribution', 'provider_instrumentation', 'upload'].map(name => ({
38
+ name, status: 'not_verified',
39
+ detail: 'Verify inside the running application with authenticated traffic and persisted telemetry.',
40
+ })),
41
+ ];
42
+ return {
43
+ schema: 'netgreener_runtime_status_v1',
44
+ scope: 'local_configuration',
45
+ ready: configReady(config).ok && checks.every(check => check.status !== 'fail'),
46
+ enabled: config.enabled,
47
+ dry_run: config.dryRun,
48
+ lifecycle,
49
+ export_mode: exportMode,
50
+ checks,
51
+ };
52
+ }
7
53
  const state = {
8
54
  hooksActive: false,
9
55
  processKind: 'process',
@@ -83,7 +129,7 @@ export function buildRuntimeHealthV0() {
83
129
  remediation.push('A flush was skipped while another was in flight — window data is retried on failure merge; reduce flush contention if drops grow.');
84
130
  }
85
131
  if (state.exportFail > 0) {
86
- remediation.push('Inspect prior export errors; failed windows are restored into the aggregator for retry.');
132
+ remediation.push('Inspect prior export errors; the exact pending window is retained in memory for retry. Direct mode does not survive process restart.');
87
133
  }
88
134
  }
89
135
  else if (state.exportOk > 0 || state.hooksActive) {
@@ -5,6 +5,9 @@ export type TenantContext = {
5
5
  tenantSource: string;
6
6
  tenantLabel?: string;
7
7
  };
8
+ export declare const MAX_TENANT_BUCKETS = 200;
9
+ export declare const TENANT_OVERFLOW_ID = "netgreener:tenant-overflow";
10
+ export declare function tenantBucketId(tenantId: string, buckets: ReadonlyMap<string, unknown>): string;
8
11
  /**
9
12
  * Mutable ALS cell so ``setTenantContext`` (manual auth) updates the same
10
13
  * object Express holds for finish/close after the request ALS exits.
@@ -35,6 +38,7 @@ export declare function tenantConfigFromRuntime(config: {
35
38
  tenantTaskKwarg: string;
36
39
  tenantLabelClaim: string | null;
37
40
  }): TenantConfig;
41
+ export declare function jwtPayloadUnverified(authorization: string | null): Record<string, unknown> | null;
38
42
  export declare function resolveTenantFromHttpRequest(req: {
39
43
  headers?: Record<string, unknown>;
40
44
  path?: string;
@@ -1,14 +1,21 @@
1
1
  import { AsyncLocalStorage } from 'node:async_hooks';
2
2
  const TENANT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
3
+ export const MAX_TENANT_BUCKETS = 200;
4
+ export const TENANT_OVERFLOW_ID = 'netgreener:tenant-overflow';
5
+ export function tenantBucketId(tenantId, buckets) {
6
+ return buckets.has(tenantId) || buckets.size < MAX_TENANT_BUCKETS - 1
7
+ ? tenantId : TENANT_OVERFLOW_ID;
8
+ }
3
9
  const storage = new AsyncLocalStorage();
4
10
  export function normalizeTenantId(value) {
5
11
  if (value === null || value === undefined)
6
12
  return null;
7
13
  const cleaned = String(value).trim();
8
- if (!cleaned || cleaned.includes('@'))
14
+ if (!cleaned || cleaned.includes('@') || cleaned === TENANT_OVERFLOW_ID)
15
+ return null;
16
+ if (cleaned.length > 128)
9
17
  return null;
10
- const clipped = cleaned.length > 128 ? cleaned.slice(0, 128) : cleaned;
11
- return TENANT_ID_RE.test(clipped) ? clipped : null;
18
+ return TENANT_ID_RE.test(cleaned) ? cleaned : null;
12
19
  }
13
20
  function tenantConfigFromSource(fields) {
14
21
  const source = (fields.source || 'none').trim().toLowerCase();
@@ -74,7 +81,7 @@ function headerValue(req, name) {
74
81
  }
75
82
  return null;
76
83
  }
77
- function jwtPayloadUnverified(authorization) {
84
+ export function jwtPayloadUnverified(authorization) {
78
85
  if (!authorization)
79
86
  return null;
80
87
  const auth = authorization.trim();
@@ -166,7 +173,19 @@ export function resolveTenantFromTaskData(data, config) {
166
173
  return { tenantId, tenantSource: `task_kwarg:${key}` };
167
174
  }
168
175
  export function runWithTenantContext(ctx, fn) {
169
- return storage.run({ current: ctx }, fn);
176
+ return storage.run({ current: normalizeTenantContext(ctx) }, fn);
177
+ }
178
+ function normalizeTenantContext(ctx) {
179
+ if (!ctx)
180
+ return null;
181
+ const tenantId = normalizeTenantId(ctx.tenantId);
182
+ if (!tenantId)
183
+ return null;
184
+ return {
185
+ tenantId,
186
+ tenantSource: String(ctx.tenantSource || 'manual').slice(0, 128),
187
+ ...(ctx.tenantLabel ? { tenantLabel: String(ctx.tenantLabel).trim().slice(0, 128) } : {}),
188
+ };
170
189
  }
171
190
  /**
172
191
  * Enter a mutable tenant cell for the remainder of this async chain (Fastify
@@ -174,7 +193,7 @@ export function runWithTenantContext(ctx, fn) {
174
193
  * handler runs inside one callback (Express ``next``).
175
194
  */
176
195
  export function enterTenantStore(ctx) {
177
- const store = { current: ctx };
196
+ const store = { current: normalizeTenantContext(ctx) };
178
197
  storage.enterWith(store);
179
198
  return store;
180
199
  }
@@ -191,12 +210,15 @@ export function getTenantContext() {
191
210
  * after the middleware ALS callback returns.
192
211
  */
193
212
  export function setTenantContext(ctx) {
213
+ const normalized = normalizeTenantContext(ctx);
214
+ if (!normalized)
215
+ throw new Error('invalid tenant_id');
194
216
  const store = storage.getStore();
195
217
  if (store) {
196
- store.current = ctx;
218
+ store.current = normalized;
197
219
  return;
198
220
  }
199
- storage.enterWith({ current: ctx });
221
+ storage.enterWith({ current: normalized });
200
222
  }
201
223
  export function collectWindowTenantIds(runtimeV0, externalV0) {
202
224
  const ids = new Set();
@@ -212,14 +234,18 @@ export function collectWindowTenantIds(runtimeV0, externalV0) {
212
234
  }
213
235
  export function attachWindowTenantToRunContext(runContext, opts) {
214
236
  const tenantIds = collectWindowTenantIds(opts.runtimeV0, opts.externalV0);
237
+ if (tenantIds.has(TENANT_OVERFLOW_ID))
238
+ return runContext;
215
239
  if (tenantIds.size !== 1)
216
240
  return runContext;
217
241
  const tenantId = [...tenantIds][0];
218
242
  runContext.tenant_id = tenantId;
219
- const source = configuredTenantSourceLabel(opts.tenantConfig) || opts.activeContext?.tenantSource;
243
+ const activeMatches = opts.activeContext?.tenantId === tenantId;
244
+ const source = (activeMatches ? opts.activeContext?.tenantSource : null)
245
+ || configuredTenantSourceLabel(opts.tenantConfig);
220
246
  if (source)
221
247
  runContext.tenant_source = source;
222
- const label = opts.activeContext?.tenantLabel;
248
+ const label = activeMatches ? opts.activeContext?.tenantLabel : undefined;
223
249
  if (label)
224
250
  runContext.tenant_label = label;
225
251
  return runContext;
package/dist/uploader.js CHANGED
@@ -1,4 +1,9 @@
1
+ import { applyRuntimeControls, meteringAllowed, startRuntimeControls } from './runtimeControls.js';
2
+ import { createHash } from 'node:crypto';
1
3
  import { validateRuntimeSessionMetadata } from './contract/validate.js';
4
+ // A 402 pauses all windows for this account, including new exporter instances.
5
+ // Collector delivery uses the Python durable queue and its persisted billing pause.
6
+ const billingPauses = new Map();
2
7
  export async function uploadRunSession(config, payload, fetchImpl = fetch) {
3
8
  const validation = validateRuntimeSessionMetadata(payload.session_metadata);
4
9
  if (!validation.ok) {
@@ -10,6 +15,10 @@ export async function uploadRunSession(config, payload, fetchImpl = fetch) {
10
15
  if (config.dryRun) {
11
16
  return { ok: true, status: 0, body: payload, dryRun: true };
12
17
  }
18
+ startRuntimeControls(config, fetchImpl);
19
+ if (!meteringAllowed(config)) {
20
+ return { ok: false, status: 423, error: 'Metering is paused by your organization administrator' };
21
+ }
13
22
  const url = `${config.apiUrl}/api/v1/runsessions/`;
14
23
  const headers = {
15
24
  Authorization: `Bearer ${config.token}`,
@@ -19,7 +28,27 @@ export async function uploadRunSession(config, payload, fetchImpl = fetch) {
19
28
  if (config.organizationId != null) {
20
29
  headers['X-Organization-ID'] = String(config.organizationId);
21
30
  }
31
+ const account = createHash('sha256').update(JSON.stringify([config.apiUrl, config.organizationId, config.token])).digest('hex');
32
+ const pause = billingPauses.get(account);
33
+ const pausedResult = () => ({
34
+ ok: false, status: 402, body: pause?.body,
35
+ error: 'Runtime uploads paused: insufficient organization credits. Add credits in the dashboard at /billing/credits.',
36
+ });
22
37
  try {
38
+ if (pause) {
39
+ if (Date.now() < pause.checkAfter)
40
+ return pausedResult();
41
+ pause.checkAfter = Date.now() + 300_000;
42
+ if (pause.orgId != null) {
43
+ const balance = await fetchImpl(`${config.apiUrl}/api/v1/billing/organizations/${pause.orgId}/credits`, { headers });
44
+ if (!balance.ok)
45
+ return pausedResult();
46
+ const data = await balance.json();
47
+ if (typeof data.balance_credits !== 'number' || data.balance_credits < pause.required)
48
+ return pausedResult();
49
+ }
50
+ billingPauses.delete(account);
51
+ }
23
52
  const res = await fetchImpl(url, {
24
53
  method: 'POST',
25
54
  headers,
@@ -34,10 +63,25 @@ export async function uploadRunSession(config, payload, fetchImpl = fetch) {
34
63
  /* keep text */
35
64
  }
36
65
  if (!res.ok) {
66
+ if (res.status === 423) {
67
+ const envelope = body;
68
+ applyRuntimeControls(config, false, (envelope?.detail ?? envelope?.error)?.org_id);
69
+ }
70
+ if (res.status === 402) {
71
+ const envelope = body;
72
+ const detail = envelope?.detail ?? envelope?.error;
73
+ const orgId = detail?.org_id ?? config.organizationId;
74
+ billingPauses.set(account, {
75
+ checkAfter: Date.now() + 300_000,
76
+ required: Math.max(1, Number(detail?.required_credits) || 1), orgId, body,
77
+ });
78
+ }
37
79
  return {
38
80
  ok: false,
39
81
  status: res.status,
40
- error: `upload failed HTTP ${res.status}`,
82
+ error: res.status === 402
83
+ ? 'Runtime uploads paused: insufficient organization credits. Add credits in the dashboard at /billing/credits.'
84
+ : `upload failed HTTP ${res.status}`,
41
85
  body,
42
86
  };
43
87
  }
@@ -0,0 +1,66 @@
1
+ {
2
+ "version": 1,
3
+ "description": "OP1 canonical git keys — CLI, SDK, Node, and VSCE must agree on every vector.",
4
+ "vectors": [
5
+ {
6
+ "in": "https://github.com/Org/NetGreener.git",
7
+ "out": "github.com/org/netgreener",
8
+ "note": "github https"
9
+ },
10
+ {
11
+ "in": "git@github.com:Org/NetGreener.git",
12
+ "out": "github.com/org/netgreener",
13
+ "note": "github ssh"
14
+ },
15
+ {
16
+ "in": "http://github.com/Org/NetGreener",
17
+ "out": "github.com/org/netgreener",
18
+ "note": "github http upgrade"
19
+ },
20
+ {
21
+ "in": "https://gitlab.com/Group/Sub/Repo.git",
22
+ "out": "gitlab.com/group/sub/repo",
23
+ "note": "gitlab nested path"
24
+ },
25
+ {
26
+ "in": "https://dev.azure.com/Contoso/Payments/_git/payments-api",
27
+ "out": "dev.azure.com/contoso/payments/payments-api",
28
+ "note": "ado https three-part"
29
+ },
30
+ {
31
+ "in": "https://dev.azure.com/Contoso/Payments/_git/payments-api.git",
32
+ "out": "dev.azure.com/contoso/payments/payments-api",
33
+ "note": "ado https with .git"
34
+ },
35
+ {
36
+ "in": "https://user:pat@dev.azure.com/Contoso/Payments/_git/payments-api",
37
+ "out": "dev.azure.com/contoso/payments/payments-api",
38
+ "note": "ado https strip credentials"
39
+ },
40
+ {
41
+ "in": "https://Contoso.visualstudio.com/Payments/_git/payments-api",
42
+ "out": "dev.azure.com/contoso/payments/payments-api",
43
+ "note": "ado visualstudio.com host"
44
+ },
45
+ {
46
+ "in": "git@ssh.dev.azure.com:v3/Contoso/Payments/payments-api",
47
+ "out": "dev.azure.com/contoso/payments/payments-api",
48
+ "note": "ado ssh v3"
49
+ },
50
+ {
51
+ "in": "ssh://git@ssh.dev.azure.com/v3/Contoso/Payments/payments-api",
52
+ "out": "dev.azure.com/contoso/payments/payments-api",
53
+ "note": "ado ssh:// v3"
54
+ },
55
+ {
56
+ "in": "",
57
+ "out": null,
58
+ "note": "empty"
59
+ },
60
+ {
61
+ "in": " ",
62
+ "out": null,
63
+ "note": "whitespace"
64
+ }
65
+ ]
66
+ }