@oxy.so/telemetry 0.1.2 → 1.1.0

package/README.md

@@ -4,12 +4,11 @@ Framework-agnostic primitives for anonymous, real-time Oxy activity telemetry.
 The package has no runtime dependencies and does not import Express, Socket.IO,
 Redis, React, React Native or Expo.
 
-Version: `0.1.2`.
-
 ## Entry points
 
 - `@oxy.so/telemetry` — shared header names and aggregate interfaces.
 - `@oxy.so/telemetry/browser` — ephemeral browser metadata.
+- `@oxy.so/telemetry/collector` — bounded HTTP/custom-transport flow aggregation.
 - `@oxy.so/telemetry/server` — pure validation, route bucketing and cardinality
   keys/interfaces.
 
@@ -33,7 +32,7 @@ session storage, IndexedDB or a URL. Closing or reloading the page loses it.
 `X-Oxy-Edge-Region` contains only the three-letter Cloudflare PoP code obtained
 from the same-origin `/cdn-cgi/trace` endpoint. The helper reads no IP field and
 returns, logs and persists none of the rest of the trace response. Discovery is
-cached per runtime, has a one-second timeout and is disabled on loopback.
+cached for 15 seconds per runtime (including failed discovery), has a one-second timeout and is disabled on loopback.
 
 Use `createBrowserTelemetry()` to create an isolated runtime or inject clock,
 crypto, location and trace-fetch dependencies in tests.
@@ -81,10 +80,10 @@ an IP, user/account/session IDs, request bodies, query strings and raw paths.
 The opaque activity ID exists only to estimate short-window cardinality and must
 not be persisted as an event log or joined to product identity.
 
-## Migration from `@oxyhq/*`
+## Migration from `@oxy.so/*`
 
 The first consumers will replace browser helpers currently owned privately by
-`@oxyhq/core` with imports from `@oxy.so/telemetry/browser`. API collectors will
+`@oxy.so/core` with imports from `@oxy.so/telemetry/browser`. API collectors will
 replace their local validation and bucketing logic with
 `@oxy.so/telemetry/server`. This package deliberately provides no compatibility
 re-export: consumers move imports directly to the new owner, then the old
@@ -95,21 +94,44 @@ exports while applications migrate their direct imports.
 
 ## Collector, realtime and reconnect
 
-The intended collector records only successful, non-control-plane requests. It
-increments request totals per `source region × bounded service × time window`
-and sends the ephemeral activity ID to a cardinality adapter, never to an event
-row or log.
+The collector records successful, failed and aborted HTTP requests. A completed
+response is a separate observed outbound flow; an aborted request never produces
+a fabricated response. Scope (`internal`/`external`), direction relative to the
+reporter (`inbound`/`outbound`) and type (`identity`, `ai`, `communication`,
+`media`, `platform`) are independent dimensions. Source and destination always
+follow the actual movement, even when two services share one region.
+
+`trafficMiddleware` attaches before routes and reads the verified service
+identity after route authentication. `instrumentTrafficFetch` observes actual
+outbound calls; internal destination regions come from the peer's `X-Oxy-Region`
+response, not a guessed IP location. Unlocated peers remain unlocated. Health,
+telemetry collection, infrastructure snapshots and service-token minting are
+excluded from observation where applicable to prevent control traffic feedback.
+Custom transports can call the collector's `record` method explicitly.
+
+Each collector retains at most 512 distinct pending flows and publishes chunks
+of at most 256. Publishing is best effort: a failed batch is discarded, with no
+durable retry queue. These are live operational observations, not billing or
+lossless historical request totals. No dashboard viewer is needed to collect.
 
 Realtime transport publishes aggregate buckets, not individual metadata. A
 socket event may carry `ActivityAggregate`: request count, approximate active
 clients, source/target regions, service and window timestamps. Transport and
 fan-out are application concerns and intentionally absent from this package.
 
-Realtime events are not a durable replay log. After reconnect, a consumer first
-loads the collector's current aggregate snapshot and then resumes the live
-stream, deduplicating any overlapping window by its stable flow/window identity.
-Reconnect backoff, socket lifecycle and snapshot endpoints belong to the
-consumer and collector, not these pure primitives.
+Realtime activity events are not a durable replay log. The dashboard retains a
+60-second window of distinct flows and resumes live events on reconnect.
+Infrastructure is separate: the API broadcasts a complete snapshot on connection
+and on changes. Registration/removal updates immediately; heartbeats run every
+10 seconds and crashed instances expire after 45 seconds (observed at the next
+registry refresh). Only reporting instances are included. The publisher must be
+installed in each service before this can represent the whole ecosystem.
+
+The authenticated publisher is `createEcosystemTraffic` from `@oxy.so/core/server`.
+It exposes HTTP middleware, `wrapFetch`, `record` for explicit transport events,
+and `stop` for graceful removal. It requires an existing trusted service
+credential and a known infrastructure region (or explicit infrastructure
+coordinates). Credentials, user metadata and paths never enter public snapshots.
 
 ## Development
 

package/dist/cjs/browser.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getBrowserTelemetryHeaders = exports.getBrowserEdgeRegionHeader = exports.getBrowserActivityIdHeader = exports.DEFAULT_EDGE_TRACE_TIMEOUT_MS = exports.DEFAULT_ACTIVITY_ID_ROTATION_MS = void 0;
+exports.getBrowserTelemetryHeaders = exports.getBrowserEdgeRegionHeader = exports.getBrowserActivityIdHeader = exports.DEFAULT_EDGE_CACHE_MS = exports.DEFAULT_EDGE_TRACE_TIMEOUT_MS = exports.DEFAULT_ACTIVITY_ID_ROTATION_MS = void 0;
 exports.createBrowserTelemetry = createBrowserTelemetry;
 const index_js_1 = require("./index.js");
 exports.DEFAULT_ACTIVITY_ID_ROTATION_MS = 5 * 60 * 1000;
 exports.DEFAULT_EDGE_TRACE_TIMEOUT_MS = 1000;
+exports.DEFAULT_EDGE_CACHE_MS = 15000;
 function createUuid(cryptoApi) {
     if (!cryptoApi)
         return null;
@@ -27,6 +28,7 @@ function createBrowserTelemetry(options = {}) {
     let activityId = null;
     let activityIdCreatedAt = 0;
     let edgePopPromise = null;
+    let edgePopReadAt = -Infinity;
     const getActivityIdHeader = () => {
         const hasInjectedBrowser = Boolean(options.location);
         const hasBrowserRuntime = typeof window !== 'undefined' && typeof document !== 'undefined';
@@ -64,7 +66,11 @@ function createBrowserTelemetry(options = {}) {
         }
     };
     const getEdgeRegionHeader = async () => {
-        edgePopPromise ?? (edgePopPromise = discoverEdgePop());
+        const now = (options.now ?? Date.now)();
+        if (!edgePopPromise || now < edgePopReadAt || now - edgePopReadAt >= (options.edgeCacheMs ?? exports.DEFAULT_EDGE_CACHE_MS)) {
+            edgePopReadAt = now;
+            edgePopPromise = discoverEdgePop();
+        }
         const edgePop = await edgePopPromise;
         return edgePop ? { [index_js_1.OXY_EDGE_REGION_HEADER]: edgePop } : {};
     };

package/dist/cjs/collector.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trafficType = trafficType;
+exports.createTrafficCollector = createTrafficCollector;
+exports.trafficMiddleware = trafficMiddleware;
+exports.instrumentTrafficFetch = instrumentTrafficFetch;
+exports.resolveOxyServiceEndpoint = resolveOxyServiceEndpoint;
+exports.infrastructureLocation = infrastructureLocation;
+exports.normalizeInfrastructureRegion = normalizeInfrastructureRegion;
+const server_js_1 = require("./server.js");
+const TYPES = {
+    auth: 'identity', session: 'identity', users: 'identity', profiles: 'identity', accounts: 'identity',
+    ai: 'ai', inference: 'ai', models: 'ai', chat: 'ai', completions: 'ai',
+    stream: 'media', tracks: 'media', episodes: 'media', recordings: 'media', rooms: 'media',
+    messages: 'communication', notifications: 'communication', mail: 'communication',
+    media: 'media', files: 'media', assets: 'media', upload: 'media', uploads: 'media', cdn: 'media', storage: 'media', images: 'media', audio: 'media', videos: 'media',
+};
+function trafficType(path) {
+    const parts = path.split('?')[0].split('/').filter(Boolean);
+    if (parts[0] === 'alia')
+        parts.shift();
+    if (parts[0] === 'api')
+        parts.shift();
+    if (/^v\d+$/.test(parts[0] ?? ''))
+        parts.shift();
+    return TYPES[parts[0] ?? ''] ?? 'platform';
+}
+function createTrafficCollector(publish, now = Date.now) {
+    const pending = new Map();
+    let flushing = null;
+    return {
+        record(flow) {
+            const key = JSON.stringify(flow);
+            const existing = pending.get(key);
+            if (existing)
+                existing.requests++;
+            else if (pending.size < 512)
+                pending.set(key, { flow, requests: 1, startedAt: now() });
+        },
+        async flush() {
+            while (flushing)
+                await flushing;
+            if (pending.size === 0)
+                return;
+            const emittedAt = new Date(now()).toISOString();
+            const events = [...pending.values()].map(({ flow, requests, startedAt }) => ({ ...flow, requests, windowStartedAt: new Date(startedAt).toISOString(), emittedAt }));
+            pending.clear();
+            flushing = (async () => {
+                for (let offset = 0; offset < events.length; offset += 256)
+                    await publish(events.slice(offset, offset + 256));
+            })();
+            try {
+                await flushing;
+            }
+            finally {
+                flushing = null;
+            }
+        },
+    };
+}
+function trafficMiddleware(collector, service, region) {
+    return (request, response, next) => {
+        response.setHeader?.('X-Oxy-Region', region);
+        const path = request.path ?? request.url ?? '/';
+        // Never report collection itself, probes or the dashboard transport.
+        if (/^\/(?:api\/)?(?:health|ready|live|platform-stats|platform-activity|platform-infrastructure|infra-status)(?:\/|$)/.test(path) || path.startsWith('/internal/activity') || path.startsWith('/auth/service-token') || path.startsWith('/cdn-cgi/')) {
+            next();
+            return;
+        }
+        const { edgePop } = (0, server_js_1.metadataFromHeaders)(request.headers);
+        const activityType = trafficType(path);
+        let finished = false;
+        const inboundFlow = () => {
+            // Read service identity AFTER the route's shared auth middleware resolved it.
+            const name = request.serviceApp?.appName?.toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 40);
+            const internal = Boolean(name);
+            const forwardedRegion = request.headers['x-oxy-source-region'];
+            const peerRegion = internal ? normalizeInfrastructureRegion(forwardedRegion) : edgePop ? `edge-${edgePop}` : undefined;
+            return { region, service, activityType, scope: internal ? 'internal' : 'external', direction: 'inbound', sourceRegion: peerRegion, targetRegion: region, sourceService: name, targetService: service };
+        };
+        const finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            const flow = inboundFlow();
+            collector.record(flow);
+            collector.record({ ...flow, direction: 'outbound', sourceRegion: region, targetRegion: flow.sourceRegion, sourceService: service, targetService: flow.sourceService });
+        };
+        response.once('finish', finish);
+        // Failed/aborted requests are still real inbound activity. Do not invent a
+        // completed outbound response when the connection closes prematurely.
+        response.once('close', () => {
+            if (finished)
+                return;
+            finished = true;
+            collector.record(inboundFlow());
+        });
+        next();
+    };
+}
+function instrumentTrafficFetch(fetcher, collector, service, region, resolveEndpoint) {
+    return Object.assign(async (input, init) => {
+        const url = new URL(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url);
+        // Collection/auth control traffic cannot generate a feedback loop.
+        if (url.pathname.startsWith('/internal/activity') || url.pathname.startsWith('/auth/service-token') || url.pathname === '/platform-infrastructure')
+            return fetcher(input, init);
+        const peer = resolveEndpoint(url);
+        const flow = {
+            service, region, scope: peer ? 'internal' : 'external', direction: 'outbound',
+            activityType: trafficType(url.pathname), sourceRegion: region, targetRegion: peer?.region,
+            sourceService: service, targetService: peer?.service,
+        };
+        const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+        if (peer)
+            headers.set('X-Oxy-Source-Region', region);
+        let response;
+        try {
+            response = await fetcher(input, { ...init, headers });
+        }
+        catch (error) {
+            collector.record({ ...flow, targetRegion: undefined });
+            throw error;
+        }
+        const targetRegion = peer ? normalizeInfrastructureRegion(response.headers.get('X-Oxy-Region') ?? undefined) : undefined;
+        collector.record({ ...flow, targetRegion });
+        collector.record({ ...flow, direction: 'inbound', sourceRegion: targetRegion, targetRegion: region, sourceService: peer?.service, targetService: service });
+        return response;
+    }, fetcher);
+}
+// Exact deployed API hosts; an arbitrary caller-supplied hostname cannot claim
+// to be an internal service. Region is infrastructure metadata, never IP geo.
+const OXY_API_SERVICES = {
+    'api.oxy.so': 'oxy-api', 'api.website.oxy.so': 'website',
+    'website-api.oxy.so': 'website', 'api.mention.earth': 'mention',
+    'api.mercaria.co': 'mercaria', 'api.alia.onl': 'alia', 'kaana.ai': 'kaana',
+    'api.homiio.com': 'homiio', 'api.syra.fm': 'syra',
+    'mention.earth': 'mention', 'mcp.mention.earth': 'mention-mcp',
+    'api.clarity.surf': 'clarity', 'api.peable.to': 'peable',
+    'api.crowdsource.oxy.so': 'crowdsource', 'api.moovo.now': 'moovo',
+    'api.allo.you': 'allo', 'api.noted.oxy.so': 'noted', 'api.schedio.app': 'schedio', 'api.tnp.network': 'tnp-api',
+};
+function resolveOxyServiceEndpoint(url) {
+    const service = OXY_API_SERVICES[url.hostname];
+    return url.protocol === 'https:' && service ? { service, region: 'us-west-2' } : undefined;
+}
+const REGION_LOCATIONS = {
+    'us-west-2': { label: 'Oregon', coordinates: [-122.6765, 45.5231] },
+    'us-west-1': { label: 'Northern California', coordinates: [-121.89, 37.34] },
+    'us-east-1': { label: 'Northern Virginia', coordinates: [-77.49, 39.04] },
+    'us-east-2': { label: 'Ohio', coordinates: [-82.99, 39.96] },
+    'eu-west-1': { label: 'Ireland', coordinates: [-6.26, 53.35] },
+    'eu-west-2': { label: 'London', coordinates: [-0.1276, 51.5072] },
+    'eu-west-3': { label: 'Paris', coordinates: [2.3522, 48.8566] },
+    'eu-central-1': { label: 'Frankfurt', coordinates: [8.6821, 50.1109] },
+    'eu-central-2': { label: 'Zurich', coordinates: [8.54, 47.38] },
+    'eu-north-1': { label: 'Stockholm', coordinates: [18.07, 59.33] },
+    'eu-south-1': { label: 'Milan', coordinates: [9.19, 45.46] },
+    'eu-south-2': { label: 'Spain', coordinates: [-0.89, 41.65] },
+    'ap-northeast-1': { label: 'Tokyo', coordinates: [139.69, 35.69] },
+    'ap-northeast-2': { label: 'Seoul', coordinates: [126.98, 37.57] },
+    'ap-northeast-3': { label: 'Osaka', coordinates: [135.5, 34.69] },
+    'ap-southeast-1': { label: 'Singapore', coordinates: [103.82, 1.35] },
+    'ap-southeast-2': { label: 'Sydney', coordinates: [151.21, -33.87] },
+    'ap-southeast-3': { label: 'Jakarta', coordinates: [106.85, -6.21] },
+    'ap-southeast-4': { label: 'Melbourne', coordinates: [144.96, -37.81] },
+    'ap-south-1': { label: 'Mumbai', coordinates: [72.88, 19.08] },
+    'ap-south-2': { label: 'Hyderabad', coordinates: [78.49, 17.38] },
+    'ap-east-1': { label: 'Hong Kong', coordinates: [114.17, 22.32] },
+    'ca-central-1': { label: 'Canada', coordinates: [-73.57, 45.5] },
+    'ca-west-1': { label: 'Calgary', coordinates: [-114.07, 51.05] },
+    'sa-east-1': { label: 'São Paulo', coordinates: [-46.63, -23.55] },
+    'af-south-1': { label: 'Cape Town', coordinates: [18.42, -33.92] },
+    'me-south-1': { label: 'Bahrain', coordinates: [50.59, 26.22] },
+    'me-central-1': { label: 'UAE', coordinates: [54.37, 24.45] },
+    'il-central-1': { label: 'Tel Aviv', coordinates: [34.78, 32.09] },
+};
+function infrastructureLocation(region) { return REGION_LOCATIONS[region]; }
+function normalizeInfrastructureRegion(value) {
+    return typeof value === 'string' && /^[a-z]{2}(?:-[a-z]+)+-\d$/.test(value) ? value : undefined;
+}

package/dist/cjs/edge.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.observeEdgeRequest = observeEdgeRequest;
+const collector_js_1 = require("./collector.js");
+const server_js_1 = require("./server.js");
+// Share values only: Workers prohibit I/O promises/bodies crossing request contexts.
+const tokens = new WeakMap();
+const CONTROL = /^\/(?:api\/)?(?:health|ready|live|platform-stats|platform-activity|platform-infrastructure|infra-status|internal\/activity|auth\/service-token|cdn-cgi)(?:\/|$)/;
+async function smallJson(response) {
+    if (!response.body)
+        throw new Error('Missing token response');
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 16384) {
+                await reader.cancel();
+                throw new Error('Oversized token response');
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return JSON.parse(new TextDecoder().decode(bytes));
+}
+async function publish(options, events) {
+    const { env } = options;
+    const base = new URL(env.OXY_EDGE_ACTIVITY_API_URL ?? 'https://api.oxy.so');
+    if (base.protocol !== 'https:' || base.username || base.password || base.pathname !== '/' || base.search || base.hash)
+        throw new Error('Invalid activity origin');
+    const fetcher = options.fetcher ?? fetch;
+    const abort = new AbortController();
+    const timeout = setTimeout(() => abort.abort(), 4000);
+    try {
+        let token;
+        if (options.credential)
+            token = await Promise.race([
+                options.credential(),
+                new Promise((_, reject) => abort.signal.addEventListener('abort', () => reject(new Error('Activity credential timeout')), { once: true })),
+            ]);
+        else {
+            const key = env.OXY_EDGE_ACTIVITY_API_KEY;
+            const secret = env.OXY_EDGE_ACTIVITY_API_SECRET;
+            if (!key || !secret)
+                throw new Error('Missing edge activity credentials');
+            const cached = tokens.get(env);
+            if (cached && cached.key === key && cached.secret === secret && cached.origin === base.origin && cached.expiresAt > Date.now() + 60000)
+                token = cached.token;
+            else {
+                // Same exchange and expiry margin as OxyServices.getServiceToken().
+                const response = await fetcher(new URL('/auth/service-token', base), {
+                    method: 'POST', headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ apiKey: key, apiSecret: secret }), signal: abort.signal,
+                });
+                if (!response.ok) {
+                    await response.body?.cancel();
+                    throw new Error('Activity authentication failed');
+                }
+                const data = await smallJson(response);
+                if (typeof data.token !== 'string' || !data.token || typeof data.expiresIn !== 'number' || !Number.isFinite(data.expiresIn) || data.expiresIn <= 0)
+                    throw new Error('Invalid activity token');
+                token = data.token;
+                tokens.set(env, { key, secret, origin: base.origin, token, expiresAt: Date.now() + data.expiresIn * 1000 });
+            }
+        }
+        const response = await fetcher(new URL('/internal/activity', base), {
+            method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+            body: JSON.stringify(events), signal: abort.signal,
+        });
+        if (response.status === 401)
+            tokens.delete(env);
+        await response.body?.cancel();
+        if (!response.ok)
+            throw new Error('Activity ingestion failed');
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/** Returns the original response/stream and preserves original handler errors. */
+async function observeEdgeRequest(options) {
+    const report = () => { try {
+        (options.onError ?? console.error)('Edge activity publication failed');
+    }
+    catch { /* Never break serving. */ } };
+    const enabled = options.env.OXY_EDGE_ACTIVITY_ENABLED;
+    if (enabled === undefined || enabled === 'false')
+        return options.next();
+    if (enabled !== 'true' || !/^[a-z][a-z0-9-]{0,39}$/.test(options.service)) {
+        report();
+        return options.next();
+    }
+    const path = new URL(options.request.url).pathname;
+    if (CONTROL.test(path))
+        return options.next();
+    const pop = (0, server_js_1.normalizeEdgePop)(typeof options.request.cf?.colo === 'string' ? options.request.cf.colo : undefined);
+    const region = pop ? `edge-${pop}` : 'unknown';
+    const startedAt = new Date().toISOString();
+    const complete = (response) => {
+        const contentType = response?.headers.get('Content-Type') ?? '';
+        const activityType = /^(?:image|audio|video)\//i.test(contentType) ? 'media' : (0, collector_js_1.trafficType)(path);
+        const common = { service: options.service, region, scope: options.peer ? 'internal' : 'external', activityType, requests: 1, windowStartedAt: startedAt, emittedAt: new Date().toISOString() };
+        // The serving PoP is infrastructure metadata. Do not invent visitor location.
+        const events = [{ ...common, direction: 'inbound', sourceRegion: options.peer?.region, sourceService: options.peer?.service, targetRegion: region, targetService: options.service }];
+        if (response)
+            events.push({ ...common, direction: 'outbound', sourceRegion: region, sourceService: options.service, targetRegion: options.peer?.region, targetService: options.peer?.service });
+        try {
+            options.ctx.waitUntil(publish(options, events).catch(report));
+        }
+        catch {
+            report();
+        }
+    };
+    let response;
+    try {
+        response = await options.next();
+    }
+    catch (error) {
+        complete();
+        throw error;
+    }
+    complete(response);
+    return response;
+}

package/dist/cjs/socket.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.socketTrafficType = socketTrafficType;
+exports.observeTrafficSocket = observeTrafficSocket;
+exports.observeTrafficWebSocket = observeTrafficWebSocket;
+const collector_js_1 = require("./collector.js");
+const server_js_1 = require("./server.js");
+const CATEGORIES = {
+    auth: 'identity', session: 'identity', user: 'identity', profile: 'identity',
+    chat: 'ai', agent: 'ai', inference: 'ai', completion: 'ai',
+    message: 'communication', notification: 'communication', typing: 'communication',
+    media: 'media', audio: 'media', video: 'media', stream: 'media', player: 'media',
+    track: 'media', playback: 'media', playlist: 'media', room: 'media',
+};
+/** Event names are reduced locally to five categories; payloads are never read. */
+function socketTrafficType(event) {
+    return CATEGORIES[event.toLowerCase().split(/[:/._-]/, 1)[0]] ?? 'platform';
+}
+/**
+ * Observes application events only, once per local socket. Socket.IO catch-all
+ * hooks exclude acknowledgements, ping/pong and transport frames. Outgoing
+ * packets describe sends, not delivery acknowledgements. No connection ID,
+ * event name, IP, credential, room name or payload enters a traffic record.
+ */
+function observeTrafficSocket(socket, collector, service, region, options = {}) {
+    if (/^\/platform-(?:activity|stats)(?:\/|$)/.test(socket.nsp?.name ?? ''))
+        return () => { };
+    let stopped = false;
+    const record = (event, direction) => {
+        if (stopped)
+            return;
+        const peer = options.getPeer?.();
+        const peerService = peer && /^[a-z][a-z0-9-]{0,39}$/.test(peer.service) ? peer.service : undefined;
+        const edgePop = (0, server_js_1.metadataFromHeaders)(socket.handshake.headers).edgePop;
+        const peerRegion = peerService ? (0, collector_js_1.normalizeInfrastructureRegion)(peer?.region) : edgePop ? `edge-${edgePop}` : undefined;
+        collector.record({
+            region, service, scope: peerService ? 'internal' : 'external', direction,
+            activityType: socketTrafficType(event),
+            sourceRegion: direction === 'inbound' ? peerRegion : region,
+            targetRegion: direction === 'inbound' ? region : peerRegion,
+            sourceService: direction === 'inbound' ? peerService : service,
+            targetService: direction === 'inbound' ? service : peerService,
+        });
+    };
+    const inbound = (event) => record(event, 'inbound');
+    const outbound = (event) => record(event, 'outbound');
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        socket.offAny(inbound);
+        socket.offAnyOutgoing(outbound);
+        socket.off('disconnect', stop);
+    };
+    socket.onAny(inbound);
+    socket.onAnyOutgoing(outbound);
+    socket.once('disconnect', stop);
+    return stop;
+}
+/** Raw ws application messages. Sends are attempts, never delivery receipts. */
+function observeTrafficWebSocket(socket, collector, service, region, options = {}) {
+    let stopped = false;
+    const record = (direction) => {
+        if (stopped)
+            return;
+        const peer = options.getPeer?.();
+        const peerService = peer && /^[a-z][a-z0-9-]{0,39}$/.test(peer.service) ? peer.service : undefined;
+        const edgePop = (0, server_js_1.metadataFromHeaders)(options.headers ?? {}).edgePop;
+        const peerRegion = peerService ? (0, collector_js_1.normalizeInfrastructureRegion)(peer?.region) : edgePop ? `edge-${edgePop}` : undefined;
+        collector.record({
+            service, region, scope: peerService ? 'internal' : 'external', direction,
+            activityType: options.activityType ?? 'communication',
+            sourceRegion: direction === 'inbound' ? peerRegion : region,
+            targetRegion: direction === 'inbound' ? region : peerRegion,
+            sourceService: direction === 'inbound' ? peerService : service,
+            targetService: direction === 'inbound' ? service : peerService,
+        });
+    };
+    const inbound = () => record('inbound');
+    const originalSend = socket.send;
+    const send = function (...args) {
+        const open = this.readyState === 1;
+        // Preserve overload arguments, callback identity, return value and throws.
+        const result = Reflect.apply(originalSend, this, args);
+        if (open)
+            record('outbound');
+        return result;
+    };
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        socket.off('message', inbound);
+        socket.off('close', stop);
+        if (socket.send === send)
+            socket.send = originalSend;
+    };
+    socket.send = send;
+    socket.on('message', inbound);
+    socket.once('close', stop);
+    return stop;
+}

package/dist/esm/browser.js

@@ -1,6 +1,7 @@
 import { OXY_ACTIVITY_ID_HEADER, OXY_EDGE_REGION_HEADER } from './index.js';
 export const DEFAULT_ACTIVITY_ID_ROTATION_MS = 5 * 60 * 1000;
 export const DEFAULT_EDGE_TRACE_TIMEOUT_MS = 1000;
+export const DEFAULT_EDGE_CACHE_MS = 15000;
 function createUuid(cryptoApi) {
     if (!cryptoApi)
         return null;
@@ -23,6 +24,7 @@ export function createBrowserTelemetry(options = {}) {
     let activityId = null;
     let activityIdCreatedAt = 0;
     let edgePopPromise = null;
+    let edgePopReadAt = -Infinity;
     const getActivityIdHeader = () => {
         const hasInjectedBrowser = Boolean(options.location);
         const hasBrowserRuntime = typeof window !== 'undefined' && typeof document !== 'undefined';
@@ -60,7 +62,11 @@ export function createBrowserTelemetry(options = {}) {
         }
     };
     const getEdgeRegionHeader = async () => {
-        edgePopPromise ?? (edgePopPromise = discoverEdgePop());
+        const now = (options.now ?? Date.now)();
+        if (!edgePopPromise || now < edgePopReadAt || now - edgePopReadAt >= (options.edgeCacheMs ?? DEFAULT_EDGE_CACHE_MS)) {
+            edgePopReadAt = now;
+            edgePopPromise = discoverEdgePop();
+        }
         const edgePop = await edgePopPromise;
         return edgePop ? { [OXY_EDGE_REGION_HEADER]: edgePop } : {};
     };