@netgreener/runtime 0.1.0

package/dist/express.js

@@ -0,0 +1,118 @@
+import { getRuntime, } from './runtime.js';
+import { getTenantStore, resolveTenantFromHttpRequest, runWithTenantContext, tenantConfigFromRuntime, } from './tenantContext.js';
+import { runWithRequestAttribution } from './requestContext.js';
+import { beginProcessResourceSample, endProcessResourceSample, } from './processResources.js';
+/**
+ * Bounded template for service_unit attribution.
+ * Never fall back to raw customer paths, baseUrl mounts, or query strings.
+ */
+export const UNKNOWN_ROUTE_TEMPLATE = '<unmatched>';
+const MAX_ROUTE_TEMPLATE_LEN = 512;
+/**
+ * Return only a framework-owned route template.
+ *
+ * Express ``req.path``, ``req.url``, and ``req.baseUrl`` may contain customer
+ * identifiers or query values — they are never safe metering fallbacks.
+ * Prefer resolving this at finish/close (after routing) rather than at entry.
+ */
+export function expressRouteTemplate(req) {
+    const route = req.route?.path;
+    if (typeof route !== 'string')
+        return UNKNOWN_ROUTE_TEMPLATE;
+    const template = route.trim();
+    if (!template ||
+        template.length > MAX_ROUTE_TEMPLATE_LEN ||
+        template.includes('?') ||
+        template.includes('#')) {
+        return UNKNOWN_ROUTE_TEMPLATE;
+    }
+    return template;
+}
+function httpServiceUnit(method, req) {
+    return `${method} ${expressRouteTemplate(req)}`;
+}
+/**
+ * Express middleware: record per-route latency/status into NetGreenerRuntime.
+ *
+ * Enable with NETGREENER_SERVICE_RUNTIME=1 and credentials (see README).
+ * Also installs outbound ``fetch`` metering (N2) when runtime is enabled.
+ *
+ * Route identity is resolved when the response finishes (or on sync handler
+ * throw), so Express can attach ``req.route`` after middleware entry.
+ *
+ * Manual ``setTenantContext`` after auth mutates the request tenant store in
+ * place; finish/close read that store rather than freezing the entry-time value.
+ */
+export function netgreenerExpressMiddleware(opts = {}) {
+    const runtime = getRuntime({
+        collector: 'express_middleware',
+        framework: 'express',
+        ...opts,
+    });
+    runtime.start();
+    const onSignal = () => {
+        void runtime.shutdown();
+    };
+    process.once('beforeExit', onSignal);
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    // Prefer programmatic RuntimeConfig over ambient process.env.
+    const tenantConfig = tenantConfigFromRuntime(runtime.config);
+    return function netgreenerMiddleware(req, res, next) {
+        if (!runtime.enabled) {
+            next();
+            return;
+        }
+        const entryTenant = resolveTenantFromHttpRequest(req, tenantConfig);
+        const method = (req.method || 'GET').toUpperCase();
+        const resolveServiceUnit = () => httpServiceUnit(method, req);
+        const handle = () => {
+            // Same mutable cell ``setTenantContext`` updates (manual auth binding).
+            const tenantStore = getTenantStore() ?? { current: entryTenant };
+            const started = process.hrtime.bigint();
+            const resourceMark = beginProcessResourceSample();
+            let recorded = false;
+            const finish = () => {
+                if (recorded)
+                    return;
+                recorded = true;
+                const ended = process.hrtime.bigint();
+                const durationMs = Number(ended - started) / 1e6;
+                const resources = endProcessResourceSample(resourceMark);
+                const path = expressRouteTemplate(req);
+                const statusCode = typeof res.statusCode === 'number' ? res.statusCode : 200;
+                // finish/close may run outside the request ALS — re-enter the live store.
+                runWithTenantContext(tenantStore.current, () => {
+                    runtime.recordHttp({
+                        method,
+                        path,
+                        statusCode,
+                        durationMs,
+                        cpuTimeMs: resources.cpuTimeMs,
+                        peakRssKb: resources.rssKb,
+                    });
+                });
+            };
+            res.on('finish', finish);
+            res.on('close', finish);
+            try {
+                next();
+            }
+            catch (err) {
+                // Do not record here: status may still change before finish/close.
+                // Preserve the original error without mutating response status.
+                throw err;
+            }
+        };
+        const withAttribution = () => runWithRequestAttribution({
+            resolveServiceUnit,
+            // Snapshot for workers / fallback; outbound captures at call entry.
+            serviceUnit: resolveServiceUnit(),
+        }, handle);
+        // Always enter a request-local tenant store (null clears inheritance).
+        runWithTenantContext(entryTenant, withAttribution);
+    };
+}
+export function getExpressRuntime() {
+    return getRuntime({ collector: 'express_middleware', framework: 'express' });
+}

package/dist/externalApiMeter.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Outbound external-API call metering (N2).
+ *
+ * Additive ``external_api_v0`` for Node flushes — usage metadata only
+ * (no prompts/bodies). Soft-wraps:
+ * - global ``fetch`` (primary)
+ * - ``axios`` Axios.prototype.request when axios is resolvable (optional peer)
+ * - ``undici.request`` / Dispatcher.request when undici is resolvable
+ *
+ * Uploads restore unwrapped ``fetch``. Axios→fetch adapter paths skip the
+ * fetch meter via ALS so the same call is not double-counted.
+ */
+import type { ExternalApiV0 } from './types.js';
+export declare function providerForHost(host: string): string;
+export declare function hostFromUrl(url: unknown): string;
+export declare function modelFromUrl(url: unknown): string | null;
+export declare function tokensFromUsage(usage: Record<string, unknown>): [number, number];
+export declare function usageFromSseText(text: string): {
+    input: number;
+    output: number;
+    model: string | null;
+};
+export declare function extractUsageFromResponse(response: Response, url: string): Promise<{
+    input: number;
+    output: number;
+    model: string | null;
+}>;
+/**
+ * Usage extraction for axios (and similar) bodies already buffered by the client.
+ * Does not read streams; returns zeros for stream/Buffer/unknown shapes.
+ */
+export declare function usageFromClientBody(data: unknown, url: string, contentType?: string | null): {
+    input: number;
+    output: number;
+    model: string | null;
+};
+export declare class ExternalApiAggregator {
+    private providers;
+    private byServiceUnit;
+    private byTenant;
+    private excludedHosts;
+    setExcludedHosts(hosts: Iterable<string>): void;
+    private isExcluded;
+    hasData(): boolean;
+    private recordProvider;
+    record(opts: {
+        host: string;
+        durationMs?: number;
+        error?: boolean;
+        inputTokens?: number;
+        outputTokens?: number;
+        serviceUnit?: string | null;
+        model?: string | null;
+        tenantId?: string | null;
+    }): void;
+    private providerRow;
+    buildV0(): ExternalApiV0 | null;
+    takeSnapshot(): ExternalApiAggregator;
+    private static mergeProvider;
+    mergeSnapshot(snapshot: ExternalApiAggregator): void;
+    clear(): void;
+}
+export declare function _awaitPendingUsageParses(): Promise<void>;
+export declare function getExternalAggregator(): ExternalApiAggregator;
+export declare function getOriginalFetch(): typeof fetch | null;
+export declare function buildExternalV0(): ExternalApiV0 | null;
+export declare function clearExternalAggregator(): void;
+/** Test helper — reset install state. */
+export declare function _resetOutboundInstrumentationForTests(): void;
+export declare function installOutboundInstrumentation(opts?: {
+    excludedHosts?: Iterable<string>;
+}): void;