@netgreener/runtime 0.1.8 → 0.1.10

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 (114) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/TUTORIAL.md +120 -29
  3. package/dist/aggregator.d.ts +12 -2
  4. package/dist/aggregator.js +135 -8
  5. package/dist/analyze/buildResourceFindings.d.ts +4 -0
  6. package/dist/analyze/buildResourceFindings.js +17 -0
  7. package/dist/analyze/cli.d.ts +1 -0
  8. package/dist/analyze/cli.js +22 -1
  9. package/dist/analyze/declaredExternalApis.d.ts +31 -0
  10. package/dist/analyze/declaredExternalApis.js +174 -0
  11. package/dist/analyze/index.d.ts +1 -0
  12. package/dist/analyze/index.js +1 -0
  13. package/dist/auto.d.ts +7 -0
  14. package/dist/auto.js +8 -0
  15. package/dist/bullmq.d.ts +2 -2
  16. package/dist/bullmq.js +28 -58
  17. package/dist/carbonLedger.d.ts +28 -0
  18. package/dist/carbonLedger.js +52 -0
  19. package/dist/cgroupV2.d.ts +44 -0
  20. package/dist/cgroupV2.js +174 -0
  21. package/dist/cli/helpText.d.ts +3 -3
  22. package/dist/cli/helpText.js +42 -35
  23. package/dist/cli/netgreener.d.ts +7 -7
  24. package/dist/cli/netgreener.js +23 -16
  25. package/dist/cli/runCli.d.ts +20 -0
  26. package/dist/cli/runCli.js +249 -0
  27. package/dist/cli/runPreload.d.ts +5 -0
  28. package/dist/cli/runPreload.js +43 -0
  29. package/dist/collectorMetadata.d.ts +1 -1
  30. package/dist/collectorMetadata.js +2 -0
  31. package/dist/config.d.ts +2 -0
  32. package/dist/config.js +6 -2
  33. package/dist/exporter.d.ts +7 -2
  34. package/dist/exporter.js +12 -6
  35. package/dist/express.js +17 -6
  36. package/dist/externalApiMeter.d.ts +51 -2
  37. package/dist/externalApiMeter.js +379 -26
  38. package/dist/fastify.js +17 -6
  39. package/dist/index.d.ts +12 -2
  40. package/dist/index.js +11 -1
  41. package/dist/init.d.ts +30 -0
  42. package/dist/init.js +31 -0
  43. package/dist/lifecycle.d.ts +45 -0
  44. package/dist/lifecycle.js +112 -0
  45. package/dist/managedCollectorLauncher.d.ts +37 -0
  46. package/dist/managedCollectorLauncher.js +162 -0
  47. package/dist/mcpToolMeter.d.ts +101 -0
  48. package/dist/mcpToolMeter.js +496 -0
  49. package/dist/n4/deploymentMatrix.d.ts +9 -5
  50. package/dist/n4/deploymentMatrix.js +13 -9
  51. package/dist/n4/missingnessInventory.js +3 -3
  52. package/dist/next.d.ts +89 -0
  53. package/dist/next.js +328 -0
  54. package/dist/nextConfig.d.ts +34 -0
  55. package/dist/nextConfig.js +73 -0
  56. package/dist/nextEntryTransform.d.ts +9 -0
  57. package/dist/nextEntryTransform.js +181 -0
  58. package/dist/occupancyTracker.d.ts +27 -0
  59. package/dist/occupancyTracker.js +87 -0
  60. package/dist/optimize/apply.d.ts +38 -0
  61. package/dist/optimize/apply.js +173 -0
  62. package/dist/optimize/cli.d.ts +26 -0
  63. package/dist/optimize/cli.js +323 -0
  64. package/dist/optimize/index.d.ts +6 -0
  65. package/dist/optimize/index.js +5 -0
  66. package/dist/optimize/llmApply.d.ts +22 -0
  67. package/dist/optimize/llmApply.js +80 -0
  68. package/dist/optimize/llmSession.d.ts +88 -0
  69. package/dist/optimize/llmSession.js +135 -0
  70. package/dist/optimize/provider.d.ts +17 -0
  71. package/dist/optimize/provider.js +119 -0
  72. package/dist/optimize/safePatches.d.ts +18 -0
  73. package/dist/optimize/safePatches.js +247 -0
  74. package/dist/optimize/types.d.ts +79 -0
  75. package/dist/optimize/types.js +6 -0
  76. package/dist/optimize/verification.d.ts +16 -0
  77. package/dist/optimize/verification.js +165 -0
  78. package/dist/processResources.d.ts +5 -0
  79. package/dist/processResources.js +28 -4
  80. package/dist/processRuntime.js +7 -28
  81. package/dist/processTree.d.ts +47 -0
  82. package/dist/processTree.js +148 -0
  83. package/dist/runContextEnrichment.d.ts +11 -0
  84. package/dist/runContextEnrichment.js +92 -0
  85. package/dist/runtime.d.ts +36 -1
  86. package/dist/runtime.js +140 -17
  87. package/dist/sdk/client.d.ts +152 -0
  88. package/dist/sdk/client.js +396 -0
  89. package/dist/sdk/gitUrl.d.ts +6 -0
  90. package/dist/sdk/gitUrl.js +87 -0
  91. package/dist/sdk/index.d.ts +5 -0
  92. package/dist/sdk/index.js +5 -0
  93. package/dist/serverlessHints.d.ts +9 -6
  94. package/dist/serverlessHints.js +10 -7
  95. package/dist/taskMeter.d.ts +14 -0
  96. package/dist/taskMeter.js +53 -0
  97. package/dist/types.d.ts +43 -0
  98. package/examples/aca-container-gate/Dockerfile +20 -0
  99. package/examples/aca-container-gate/azure-container-app.yaml +27 -0
  100. package/examples/aca-container-gate/gate.env +7 -0
  101. package/examples/aca-container-gate/server.mjs +117 -0
  102. package/examples/azure-functions-gate/.funcignore +6 -0
  103. package/examples/azure-functions-gate/README.md +25 -0
  104. package/examples/azure-functions-gate/host.json +15 -0
  105. package/examples/azure-functions-gate/package-lock.json +161 -0
  106. package/examples/azure-functions-gate/package.json +14 -0
  107. package/examples/azure-functions-gate/src/functions/health.js +27 -0
  108. package/examples/express-local-live-smoke.mjs +127 -0
  109. package/examples/extractRunId.mjs +11 -0
  110. package/examples/next-pilot-dry-run.mjs +32 -0
  111. package/examples/serverless-thin-gate.mjs +89 -0
  112. package/fixtures/run-smoke/hello.mjs +4 -0
  113. package/loaders/next-entry-loader.cjs +14 -0
  114. package/package.json +25 -2
package/dist/exporter.js CHANGED
@@ -12,15 +12,20 @@ import { createHash } from 'node:crypto';
12
12
  import { sendCollectorEvent, newCollectorEventId, CollectorIpcError, } from './collectorIpc.js';
13
13
  import { uploadRunSession, } from './uploader.js';
14
14
  import { flushModeRequestsThin } from './serverlessHints.js';
15
- function readExportMode(env = process.env) {
15
+ import { resolveLifecycle } from './lifecycle.js';
16
+ function readExportMode(env = process.env, opts) {
16
17
  // Explicit EXPORT_MODE always wins (including explicit ``direct``).
17
18
  const exportRaw = (env.NETGREENER_EXPORT_MODE || '').trim().toLowerCase();
18
19
  if (exportRaw === 'collector' || exportRaw === 'thin' || exportRaw === 'direct') {
19
20
  return exportRaw;
20
21
  }
21
- // Alias: FLUSH_MODE=thin when EXPORT_MODE unset — does not auto-detect platforms.
22
+ // Alias: FLUSH_MODE=thin when EXPORT_MODE unset.
22
23
  if (flushModeRequestsThin(env))
23
24
  return 'thin';
25
+ // Ephemeral lifecycle prefers thin when EXPORT_MODE unset (best_effort_bounded).
26
+ const lifecycle = opts?.lifecycle ?? resolveLifecycle({ env }).lifecycle;
27
+ if (lifecycle === 'ephemeral')
28
+ return 'thin';
24
29
  return 'direct';
25
30
  }
26
31
  function emitTimeoutMs(env = process.env) {
@@ -174,6 +179,7 @@ export class CollectorRunSessionExporter {
174
179
  session_metadata: payload.session_metadata,
175
180
  wall_time_utc: new Date().toISOString(),
176
181
  emitter: 'netgreener_node',
182
+ emitter_pid: process.pid,
177
183
  export_mode: 'collector',
178
184
  },
179
185
  });
@@ -291,14 +297,14 @@ export class CollectorRunSessionExporter {
291
297
  }
292
298
  }
293
299
  }
294
- export function resolveObservationExporter(env = process.env) {
295
- const mode = readExportMode(env);
300
+ export function resolveObservationExporter(env = process.env, opts) {
301
+ const mode = readExportMode(env, opts);
296
302
  if (mode === 'collector')
297
303
  return new CollectorRunSessionExporter();
298
304
  if (mode === 'thin')
299
305
  return new ThinRunSessionExporter();
300
306
  return new DirectRunSessionExporter();
301
307
  }
302
- export function exportModeFromEnv(env = process.env) {
303
- return readExportMode(env);
308
+ export function exportModeFromEnv(env = process.env, opts) {
309
+ return readExportMode(env, opts);
304
310
  }
package/dist/express.js CHANGED
@@ -2,6 +2,8 @@ import { getRuntime, } from './runtime.js';
2
2
  import { getTenantStore, resolveTenantFromHttpRequest, runWithTenantContext, tenantConfigFromRuntime, } from './tenantContext.js';
3
3
  import { runWithRequestAttribution } from './requestContext.js';
4
4
  import { beginProcessResourceSample, endProcessResourceSample, } from './processResources.js';
5
+ import { getOccupancyTracker } from './occupancyTracker.js';
6
+ import { randomUUID } from 'node:crypto';
5
7
  /**
6
8
  * Bounded template for service_unit attribution.
7
9
  * Never fall back to raw customer paths, baseUrl mounts, or query strings.
@@ -50,12 +52,15 @@ export function netgreenerExpressMiddleware(opts = {}) {
50
52
  ...opts,
51
53
  });
52
54
  runtime.start();
53
- const onSignal = () => {
54
- void runtime.shutdown();
55
- };
56
- process.once('beforeExit', onSignal);
57
- process.once('SIGINT', onSignal);
58
- process.once('SIGTERM', onSignal);
55
+ // Persistent only: ephemeral must not depend on process signals for correctness.
56
+ if (runtime.lifecycle === 'persistent') {
57
+ const onSignal = () => {
58
+ void runtime.shutdown();
59
+ };
60
+ process.once('beforeExit', onSignal);
61
+ process.once('SIGINT', onSignal);
62
+ process.once('SIGTERM', onSignal);
63
+ }
59
64
  // Prefer programmatic RuntimeConfig over ambient process.env.
60
65
  const tenantConfig = tenantConfigFromRuntime(runtime.config);
61
66
  return function netgreenerMiddleware(req, res, next) {
@@ -71,7 +76,10 @@ export function netgreenerExpressMiddleware(opts = {}) {
71
76
  const tenantStore = getTenantStore() ?? { current: entryTenant };
72
77
  const started = process.hrtime.bigint();
73
78
  const resourceMark = beginProcessResourceSample();
79
+ const requestId = randomUUID();
80
+ getOccupancyTracker().begin(requestId);
74
81
  let recorded = false;
82
+ runtime.beginRequest();
75
83
  const finish = () => {
76
84
  if (recorded)
77
85
  return;
@@ -81,6 +89,8 @@ export function netgreenerExpressMiddleware(opts = {}) {
81
89
  const resources = endProcessResourceSample(resourceMark);
82
90
  const path = expressRouteTemplate(req);
83
91
  const statusCode = typeof res.statusCode === 'number' ? res.statusCode : 200;
92
+ const serviceUnit = httpServiceUnit(method, req);
93
+ getOccupancyTracker().end(requestId, serviceUnit);
84
94
  // finish/close may run outside the request ALS — re-enter the live store.
85
95
  runWithTenantContext(tenantStore.current, () => {
86
96
  runtime.recordHttp({
@@ -92,6 +102,7 @@ export function netgreenerExpressMiddleware(opts = {}) {
92
102
  peakRssKb: resources.rssKb,
93
103
  });
94
104
  });
105
+ runtime.endRequest();
95
106
  };
96
107
  res.on('finish', finish);
97
108
  res.on('close', finish);
@@ -6,12 +6,13 @@
6
6
  * - global ``fetch`` (primary)
7
7
  * - ``axios`` Axios.prototype.request when axios is resolvable (optional peer)
8
8
  * - ``undici.request`` / Dispatcher.request when undici is resolvable
9
+ * (body teed via ``StreamUsageMeter`` for SSE/JSON usage — Python twin)
9
10
  *
10
11
  * Uploads restore unwrapped ``fetch``. Axios→fetch adapter paths skip the
11
12
  * fetch meter via ALS so the same call is not double-counted.
12
13
  */
13
14
  import type { ExternalApiV0 } from './types.js';
14
- export declare function providerForHost(host: string): string;
15
+ export declare function providerForHost(host: string, url?: string): string;
15
16
  export declare function hostFromUrl(url: unknown): string;
16
17
  export declare function modelFromUrl(url: unknown): string | null;
17
18
  export declare function tokensFromUsage(usage: Record<string, unknown>): [number, number];
@@ -25,9 +26,51 @@ export declare function extractUsageFromResponse(response: Response, url: string
25
26
  output: number;
26
27
  model: string | null;
27
28
  }>;
29
+ /**
30
+ * Accumulate SSE/NDJSON usage from a streamed body, then report once on finish.
31
+ * Twin of Python ``_StreamUsageMeter`` — does not steal the body from the caller;
32
+ * wraps read paths so chunks are teed into a bounded buffer.
33
+ */
34
+ export declare class StreamUsageMeter {
35
+ private readonly opts;
36
+ private _buf;
37
+ private _reported;
38
+ private _inTok;
39
+ private _outTok;
40
+ private _model;
41
+ private _error;
42
+ private readonly _finishPromise;
43
+ private _resolveFinish;
44
+ constructor(opts: {
45
+ host: string;
46
+ url: string;
47
+ start: number;
48
+ error: boolean;
49
+ serviceUnit: string | null;
50
+ tenantId: string | null;
51
+ parentToolCallId?: string | null;
52
+ });
53
+ /** Resolves after ``finish`` (for flush / test coordination). */
54
+ whenFinished(): Promise<void>;
55
+ feed(chunk: unknown): void;
56
+ applyUsage(usage: {
57
+ input: number;
58
+ output: number;
59
+ model: string | null;
60
+ }): void;
61
+ finish(extra?: {
62
+ error?: boolean;
63
+ }): void;
64
+ }
65
+ /**
66
+ * Tee usage from a Readable-like body without replacing it (keeps undici helpers).
67
+ * Returns false when the body cannot be instrumented.
68
+ */
69
+ export declare function attachStreamUsageMeter(body: unknown, meter: StreamUsageMeter): boolean;
28
70
  /**
29
71
  * Usage extraction for axios (and similar) bodies already buffered by the client.
30
- * Does not read streams; returns zeros for stream/Buffer/unknown shapes.
72
+ * Does not read streams; returns zeros for stream/Buffer/unknown shapes
73
+ * (stream tokens are recovered via ``attachStreamUsageMeter``).
31
74
  */
32
75
  export declare function usageFromClientBody(data: unknown, url: string, contentType?: string | null): {
33
76
  input: number;
@@ -40,6 +83,7 @@ export declare class ExternalApiAggregator {
40
83
  private byTenant;
41
84
  private excludedHosts;
42
85
  setExcludedHosts(hosts: Iterable<string>): void;
86
+ excludesHost(host: string): boolean;
43
87
  private isExcluded;
44
88
  hasData(): boolean;
45
89
  private recordProvider;
@@ -52,6 +96,7 @@ export declare class ExternalApiAggregator {
52
96
  serviceUnit?: string | null;
53
97
  model?: string | null;
54
98
  tenantId?: string | null;
99
+ url?: string;
55
100
  }): void;
56
101
  private providerRow;
57
102
  buildV0(): ExternalApiV0 | null;
@@ -60,6 +105,10 @@ export declare class ExternalApiAggregator {
60
105
  mergeSnapshot(snapshot: ExternalApiAggregator): void;
61
106
  clear(): void;
62
107
  }
108
+ /** In-flight metered ``fetch`` calls, including a stream usage parse still running. */
109
+ export declare function outboundHttpInFlight(): number;
110
+ /** Resolves immediately when no metered ``fetch`` is in flight. */
111
+ export declare function whenOutboundHttpIdle(): Promise<void>;
63
112
  export declare function _awaitPendingUsageParses(): Promise<void>;
64
113
  export declare function getExternalAggregator(): ExternalApiAggregator;
65
114
  export declare function getOriginalFetch(): typeof fetch | null;