@oxy.so/telemetry 1.0.0 → 1.1.1

package/src/edge.ts

@@ -0,0 +1,117 @@
+import { trafficType, type TrafficAggregate } from './collector.js';
+import { normalizeEdgePop } from './server.js';
+
+/** Server-only bindings; never expose them through frontend build variables. */
+export interface EdgeActivityEnv {
+  OXY_EDGE_ACTIVITY_ENABLED?: string;
+  OXY_EDGE_ACTIVITY_API_KEY?: string;
+  OXY_EDGE_ACTIVITY_API_SECRET?: string;
+  OXY_EDGE_ACTIVITY_API_URL?: string;
+}
+export interface EdgeActivityContext { waitUntil(promise: Promise<unknown>): void }
+export interface EdgeActivityOptions {
+  service: string;
+  request: Request & { cf?: { colo?: unknown } };
+  env: EdgeActivityEnv;
+  ctx: EdgeActivityContext;
+  next: () => Response | Promise<Response>;
+  credential?: () => Promise<string>;
+  fetcher?: typeof fetch;
+  /** Only supply after existing authentication verified this service identity. */
+  peer?: { service: string; region?: string };
+  /** Fixed message only: never credentials, URLs or upstream error bodies. */
+  onError?: (message: string) => void;
+}
+interface CachedToken { key: string; secret: string; origin: string; token: string; expiresAt: number }
+// Share values only: Workers prohibit I/O promises/bodies crossing request contexts.
+const tokens = new WeakMap<EdgeActivityEnv, CachedToken>();
+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: Response): Promise<unknown> {
+  if (!response.body) throw new Error('Missing token response');
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > 16_384) { 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: EdgeActivityOptions, events: TrafficAggregate[]): Promise<void> {
+  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(), 4_000);
+  try {
+    let token: string;
+    if (options.credential) token = await Promise.race([
+      options.credential(),
+      new Promise<never>((_, 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() + 60_000) 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) as { token?: unknown; expiresIn?: unknown };
+        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 * 1_000 });
+      }
+    }
+    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. */
+export async function observeEdgeRequest(options: EdgeActivityOptions): Promise<Response> {
+  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 = 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?: Response) => {
+    const contentType = response?.headers.get('Content-Type') ?? '';
+    const activityType = /^(?:image|audio|video)\//i.test(contentType) ? 'media' : trafficType(path);
+    const common = { service: options.service, region, scope: options.peer ? 'internal' as const : 'external' as const, activityType, requests: 1, windowStartedAt: startedAt, emittedAt: new Date().toISOString() };
+    // The serving PoP is infrastructure metadata. Do not invent visitor location.
+    const events: TrafficAggregate[] = [{ ...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: Response;
+  try { response = await options.next(); }
+  catch (error) { complete(); throw error; }
+  complete(response);
+  return response;
+}

package/src/socket.ts

@@ -0,0 +1,131 @@
+import { normalizeInfrastructureRegion, type TrafficFlow, type TrafficType } from './collector.js';
+import { metadataFromHeaders, type TelemetryHeaders } from './server.js';
+
+export interface TrafficSocket {
+  handshake: { headers: TelemetryHeaders };
+  nsp?: { name: string };
+  onAny(listener: (event: string) => void): unknown;
+  onAnyOutgoing(listener: (event: string) => void): unknown;
+  offAny(listener: (event: string) => void): unknown;
+  offAnyOutgoing(listener: (event: string) => void): unknown;
+  once(event: 'disconnect', listener: () => void): unknown;
+  off(event: 'disconnect', listener: () => void): unknown;
+}
+
+const CATEGORIES: Record<string, TrafficType> = {
+  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. */
+export function socketTrafficType(event: string): TrafficType {
+  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.
+ */
+export function observeTrafficSocket(
+  socket: TrafficSocket,
+  collector: { record(flow: TrafficFlow): void },
+  service: string,
+  region: string,
+  options: { getPeer?: () => { service: string; region?: string } | undefined } = {},
+): () => void {
+  if (/^\/platform-(?:activity|stats)(?:\/|$)/.test(socket.nsp?.name ?? '')) return () => {};
+  let stopped = false;
+  const record = (event: string, direction: 'inbound' | 'outbound') => {
+    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 = metadataFromHeaders(socket.handshake.headers).edgePop;
+    const peerRegion = peerService ? 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: string) => record(event, 'inbound');
+  const outbound = (event: string) => 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;
+}
+
+export interface TrafficWebSocket {
+  readonly readyState: number;
+  // ws accepts data/options overloads; they are forwarded without inspecting
+  // or changing them. Keep this boundary permissive for Node ws versions.
+  send(...args: any[]): unknown;
+  on(event: 'message', listener: () => void): unknown;
+  once(event: 'close', listener: () => void): unknown;
+  off(event: 'message' | 'close', listener: () => void): unknown;
+}
+
+/** Raw ws application messages. Sends are attempts, never delivery receipts. */
+export function observeTrafficWebSocket(
+  socket: TrafficWebSocket,
+  collector: { record(flow: TrafficFlow): void },
+  service: string,
+  region: string,
+  options: {
+    headers?: TelemetryHeaders;
+    activityType?: TrafficType;
+    getPeer?: () => { service: string; region?: string } | undefined;
+  } = {},
+): () => void {
+  let stopped = false;
+  const record = (direction: 'inbound' | 'outbound') => {
+    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 = metadataFromHeaders(options.headers ?? {}).edgePop;
+    const peerRegion = peerService ? 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: TrafficWebSocket['send'] = function (this: TrafficWebSocket, ...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;
+}