@oxy.so/core 1.0.0 → 1.1.1

package/dist/esm/server/traffic.js

@@ -0,0 +1,104 @@
+import { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp.js';
+import { observeTrafficSocket, observeTrafficWebSocket } from '@oxy.so/telemetry/socket';
+import { randomUUID } from 'node:crypto';
+import { OxyServices } from '../OxyServices.js';
+import { createTrafficCollector, instrumentTrafficFetch, trafficMiddleware, resolveOxyServiceEndpoint, infrastructureLocation } from '@oxy.so/telemetry/collector';
+/** Install once per service process, before registering HTTP routes. */
+export function createEcosystemTraffic(options) {
+    const region = options.region ?? process.env.AWS_REGION ?? 'unknown';
+    const baseURL = options.baseURL ?? process.env.OXY_API_URL ?? 'https://api.oxy.so';
+    const activityKey = process.env.OXY_ACTIVITY_API_KEY;
+    const activitySecret = process.env.OXY_ACTIVITY_API_SECRET;
+    if (!options.credential && Boolean(activityKey) !== Boolean(activitySecret)) {
+        throw new Error('Ecosystem activity requires a complete OXY_ACTIVITY_API_KEY and OXY_ACTIVITY_API_SECRET pair');
+    }
+    const apiKey = activityKey || process.env.OXY_SERVICE_API_KEY;
+    const apiSecret = activitySecret || process.env.OXY_SERVICE_API_SECRET;
+    if (!options.credential && (!apiKey || !apiSecret))
+        throw new Error('Ecosystem activity requires OXY_SERVICE_API_KEY and OXY_SERVICE_API_SECRET');
+    const oxy = new OxyServices({ baseURL });
+    if (apiKey && apiSecret)
+        oxy.configureServiceAuth(apiKey, apiSecret);
+    const credential = options.credential ?? (() => oxy.getServiceToken());
+    const fetcher = globalThis.fetch.bind(globalThis);
+    const instanceId = randomUUID();
+    const location = options.location ?? infrastructureLocation(region);
+    if (!location)
+        throw new Error('Ecosystem activity requires a known infrastructure region or explicit location');
+    const post = async (path, data) => {
+        const token = await credential();
+        const response = await fetcher(new URL(path, baseURL), {
+            method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+            body: JSON.stringify(data), signal: AbortSignal.timeout(4000),
+        });
+        if (!response.ok)
+            throw new Error('Activity collection failed');
+    };
+    const collector = createTrafficCollector(events => post('/internal/activity', events));
+    let stopped = false;
+    let heartbeatWork = Promise.resolve();
+    let heartbeatPending = false;
+    const reportError = options.onError ?? (() => console.warn('Ecosystem activity publisher unavailable'));
+    const heartbeat = (removed = false) => {
+        if (!removed && (stopped || heartbeatPending))
+            return heartbeatWork;
+        heartbeatPending = true;
+        heartbeatWork = heartbeatWork.then(() => post('/internal/activity/infrastructure', { instanceId, service: options.service, region, ...location, status: options.ready?.() ? 'online' : 'unknown', removed })).catch(reportError).finally(() => { heartbeatPending = false; });
+        return heartbeatWork;
+    };
+    const flush = () => collector.flush().catch(reportError);
+    const cleanups = new Set();
+    const sockets = new WeakMap();
+    let fetchInstalled = false;
+    const wrapFetch = (fetcher) => {
+        const wrapped = instrumentTrafficFetch(fetcher, collector, options.service, region, options.resolveEndpoint ?? resolveOxyServiceEndpoint);
+        return Object.assign((...args) => withoutNodeHttpObservation(() => wrapped(...args)), fetcher);
+    };
+    const observeHttp = trafficMiddleware(collector, options.service, region);
+    const timer = setInterval(() => { void flush(); }, 2000);
+    timer.unref?.();
+    void heartbeat();
+    const heartbeatTimer = setInterval(() => { void heartbeat(); }, 10000);
+    heartbeatTimer.unref?.();
+    return {
+        record: flow => collector.record({ ...flow, service: options.service, region }),
+        middleware: observeHttp,
+        observeHttp,
+        wrapFetch,
+        installFetch() {
+            if (fetchInstalled || stopped)
+                return;
+            fetchInstalled = true;
+            const original = globalThis.fetch;
+            const wrapped = wrapFetch(original);
+            globalThis.fetch = wrapped;
+            cleanups.add(() => { if (globalThis.fetch === wrapped)
+                globalThis.fetch = original; });
+            cleanups.add(observeNodeHttp(collector, options.service, region, options.resolveEndpoint ?? resolveOxyServiceEndpoint));
+        },
+        observeWebSocket(socket, socketOptions) {
+            const existing = sockets.get(socket);
+            if (existing)
+                return existing;
+            const unobserve = observeTrafficWebSocket(socket, collector, options.service, region, socketOptions);
+            const cleanup = () => { unobserve(); socket.off('close', cleanup); cleanups.delete(cleanup); sockets.delete(socket); };
+            sockets.set(socket, cleanup);
+            socket.once('close', cleanup);
+            cleanups.add(cleanup);
+            return cleanup;
+        },
+        observeSocket(socket, socketOptions) {
+            const existing = sockets.get(socket);
+            if (existing)
+                return existing;
+            const unobserve = observeTrafficSocket(socket, collector, options.service, region, socketOptions);
+            const cleanup = () => { unobserve(); socket.off('disconnect', cleanup); cleanups.delete(cleanup); sockets.delete(socket); };
+            sockets.set(socket, cleanup);
+            socket.once('disconnect', cleanup);
+            cleanups.add(cleanup);
+            return cleanup;
+        },
+        async stop() { if (stopped)
+            return; stopped = true; cleanups.forEach(cleanup => cleanup()); cleanups.clear(); clearInterval(timer); clearInterval(heartbeatTimer); await flush(); await heartbeat(true); },
+    };
+}

package/dist/esm/server/trafficNodeHttp.js

@@ -0,0 +1,79 @@
+import http from 'node:http';
+import https from 'node:https';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { syncBuiltinESMExports } from 'node:module';
+import { normalizeInfrastructureRegion, trafficType } from '@oxy.so/telemetry/collector';
+const suppressed = new AsyncLocalStorage();
+export function withoutNodeHttpObservation(callback) { return suppressed.run(true, callback); }
+/** Node and Bun share the HTTP facade; Bun does not emit Node's HTTP diagnostic channels. */
+export function observeNodeHttp(collector, service, region, resolveEndpoint) {
+    const seen = new WeakSet();
+    const restoreRequests = new Set();
+    const observe = (request) => {
+        if (seen.has(request) || suppressed.getStore())
+            return request;
+        seen.add(request);
+        const host = request.getHeader('host') ?? request.host;
+        if (typeof host !== 'string')
+            return request;
+        const url = new URL(request.path || '/', `${request.protocol || 'http:'}//${host}`);
+        if (/^\/(?:internal\/activity|auth\/service-token|platform-infrastructure)(?:\/|$)/.test(url.pathname))
+            return request;
+        const peer = resolveEndpoint(url);
+        if (peer && !request.headersSent)
+            request.setHeader('X-Oxy-Source-Region', region);
+        const flow = { service, region, activityType: trafficType(url.pathname), scope: peer ? 'internal' : 'external', direction: 'outbound', sourceRegion: region, sourceService: service, targetService: peer?.service };
+        const emit = request.emit;
+        let recorded = false;
+        const restore = () => { if (request.emit === observedEmit)
+            request.emit = emit; restoreRequests.delete(restore); };
+        // Intercept notifications without adding an 'error' listener: observation
+        // must not turn an unhandled application error into a swallowed error.
+        const observedEmit = function (event, ...args) {
+            try {
+                if (!recorded && event === 'response') {
+                    recorded = true;
+                    const response = args[0];
+                    const targetRegion = peer ? normalizeInfrastructureRegion(response.headers['x-oxy-region']) : undefined;
+                    collector.record({ ...flow, targetRegion });
+                    collector.record({ ...flow, direction: 'inbound', sourceRegion: targetRegion, targetRegion: region, sourceService: peer?.service, targetService: service });
+                }
+                else if (!recorded && (event === 'error' || event === 'close')) {
+                    recorded = true;
+                    collector.record(flow);
+                }
+            }
+            catch { /* A metrics failure cannot change a request's behavior. */ }
+            if (event === 'close')
+                restore();
+            return emit.call(this, event, ...args);
+        };
+        request.emit = observedEmit;
+        restoreRequests.add(restore);
+        return request;
+    };
+    const safelyObserve = (request) => {
+        try {
+            return observe(request);
+        }
+        catch {
+            return request;
+        }
+    };
+    const patches = [http, https].map(module => {
+        const request = module.request;
+        const get = module.get;
+        const wrappedRequest = function (...args) { return safelyObserve(request.apply(module, args)); };
+        const wrappedGet = function (...args) { return safelyObserve(get.apply(module, args)); };
+        module.request = wrappedRequest;
+        module.get = wrappedGet;
+        return () => {
+            if (module.request === wrappedRequest)
+                module.request = request;
+            if (module.get === wrappedGet)
+                module.get = get;
+        };
+    });
+    syncBuiltinESMExports();
+    return () => { patches.forEach(restore => restore()); restoreRequests.forEach(restore => restore()); syncBuiltinESMExports(); };
+}

package/dist/esm/utils/textNormalization.js

@@ -83,7 +83,7 @@ const LEADING_HORIZONTAL_WHITESPACE = /\n +/g;
 /** Three or more line breaks: more than one blank line between paragraphs. */
 const EXCESS_BLANK_LINES = /\n{3,}/g;
 /**
- * Normalize a SINGLE-LINE text value: page/link-preview titles, `siteName`,
+ * Normalize a SINGLE-LINE text value such as a page title or `siteName`,
  * display names, image alt text, handles, profile field labels.
  *
  * A line break in such a value is never meaningful — it is an artifact of the