@obsrviq/tracker 0.4.2 → 0.6.0

package/src/websocket.ts

@@ -0,0 +1,143 @@
+import type { WsEvent } from '@obsrviq/types';
+import type { InstrumentCtx, Teardown } from './context.js';
+import { maskString } from './mask.js';
+import { tokenBucket } from './ratelimit.js';
+import { uuid } from './util.js';
+
+const FRAME_CAP = 4 * 1024; // 4 KB text-frame preview cap (mirrors network bodies)
+const MSG_RATE = 20; // sustained message-frame events/sec per socket
+const MSG_BURST = 40; // burst capacity
+
+function redactUrl(raw: string): string {
+  try {
+    const u = new URL(raw, location.href);
+    if (u.search) u.search = '?…';
+    return u.toString();
+  } catch {
+    return raw.split('?')[0] ?? raw;
+  }
+}
+
+function byteLen(s: string): number {
+  try {
+    return new TextEncoder().encode(s).length;
+  } catch {
+    return s.length;
+  }
+}
+
+type FrameInfo = Pick<WsEvent, 'encoding' | 'size' | 'body'>;
+
+/** Derive encoding + byte size (+ opt-in masked preview) from a frame payload.
+ *  Never reads binary payload bytes — only their length. */
+function frameInfo(data: unknown, capture: boolean): FrameInfo {
+  if (typeof data === 'string') {
+    const info: FrameInfo = { encoding: 'text', size: byteLen(data) };
+    if (capture) {
+      // Pre-cut giant frames (2× slack) so masking never regex-scans a multi-MB payload.
+      const cut = data.length > FRAME_CAP * 2 ? data.slice(0, FRAME_CAP * 2) : data;
+      const masked = maskString(cut);
+      const truncated = cut !== data || masked.length > FRAME_CAP;
+      info.body = {
+        preview: truncated ? masked.slice(0, FRAME_CAP) : masked,
+        truncated,
+        redacted: masked !== cut,
+      };
+    }
+    return info;
+  }
+  let size = 0;
+  if (typeof Blob !== 'undefined' && data instanceof Blob) size = data.size;
+  else if (data instanceof ArrayBuffer) size = data.byteLength;
+  else if (ArrayBuffer.isView(data)) size = (data as ArrayBufferView).byteLength;
+  return { encoding: 'binary', size };
+}
+
+/** Wrap the WebSocket constructor to capture connection lifecycle + frames.
+ *  Best-effort: never throws into the app; a capture failure never breaks send/recv. */
+export function instrumentWebSocket(ctx: InstrumentCtx): Teardown {
+  const Orig = typeof window !== 'undefined' ? window.WebSocket : undefined;
+  if (!Orig) return () => {};
+
+  const emit = (partial: Omit<WsEvent, 'id' | 'sessionId' | 'type' | 't' | 'ts'>) => {
+    try {
+      const ev: WsEvent = {
+        id: uuid(),
+        sessionId: ctx.sessionId,
+        type: 'ws',
+        t: ctx.clock.now(),
+        ts: ctx.clock.wall(),
+        ...partial,
+      };
+      ctx.emit(ev);
+    } catch {
+      /* swallow — capture must never affect the socket */
+    }
+  };
+
+  class WrappedWebSocket extends Orig {
+    constructor(url: string | URL, protocols?: string | string[]) {
+      super(url as string, protocols as string | string[] | undefined);
+      // The real socket is already live; capture setup must never throw into the app.
+      try {
+        const connId = uuid();
+        const redUrl = redactUrl(String(url));
+        const protos = protocols ? (Array.isArray(protocols) ? protocols : [protocols]) : undefined;
+        const capture = ctx.config.captureNetworkBodies;
+
+        // Per-socket frame throttle — a chatty socket (100s of msg/s) must not
+        // flood the buffer. Dropped frames are counted and reported on the next
+        // captured frame (or the close event). Lifecycle events (open/close/error)
+        // are never throttled.
+        const bucket = tokenBucket(MSG_RATE, MSG_BURST);
+        let droppedFrames = 0;
+        const emitFrame = (dir: 'send' | 'recv', data: unknown) => {
+          ctx.markActivity(); // dropped frames still count as app activity
+          if (!bucket.take()) {
+            droppedFrames++;
+            return;
+          }
+          const info = frameInfo(data, capture);
+          const dropped = droppedFrames;
+          droppedFrames = 0;
+          emit({ connId, url: redUrl, kind: 'message', dir, ...info, droppedFrames: dropped || undefined });
+        };
+
+        this.addEventListener('open', () => emit({ connId, url: redUrl, kind: 'open', protocols: protos }));
+        this.addEventListener('close', (e) =>
+          emit({
+            connId,
+            url: redUrl,
+            kind: 'close',
+            code: e.code,
+            reason: e.reason || undefined,
+            wasClean: e.wasClean,
+            droppedFrames: droppedFrames || undefined,
+          }),
+        );
+        this.addEventListener('error', () => emit({ connId, url: redUrl, kind: 'error' }));
+        this.addEventListener('message', (e: MessageEvent) => emitFrame('recv', e.data));
+
+        // Capture outgoing frames by shadowing send() on this instance. Call the
+        // real send FIRST — if it throws (e.g. send() while CONNECTING) the error
+        // propagates to the app and no phantom "send" frame is recorded.
+        const origSend = super.send.bind(this);
+        this.send = (data: string | ArrayBufferLike | Blob | ArrayBufferView) => {
+          origSend(data);
+          try {
+            emitFrame('send', data);
+          } catch {
+            /* ignore capture errors */
+          }
+        };
+      } catch {
+        /* capture setup failed — the real socket still works normally. */
+      }
+    }
+  }
+
+  window.WebSocket = WrappedWebSocket as unknown as typeof WebSocket;
+  return () => {
+    window.WebSocket = Orig;
+  };
+}