trickle-observe 0.2.97 → 0.2.98

package/dist/observe-register.js

@@ -1166,6 +1166,24 @@ if (enabled) {
             }
             catch { /* not critical */ }
         }
+        // WebSocket (ws)
+        if (request === 'ws' && !expressPatched.has('ws')) {
+            expressPatched.add('ws');
+            try {
+                const { patchWs } = require(path_1.default.join(__dirname, 'ws-observer.js'));
+                patchWs(exports, debug);
+            }
+            catch { /* not critical */ }
+        }
+        // socket.io-client
+        if (request === 'socket.io-client' && !expressPatched.has('socket.io-client')) {
+            expressPatched.add('socket.io-client');
+            try {
+                const { patchSocketIo } = require(path_1.default.join(__dirname, 'ws-observer.js'));
+                patchSocketIo(exports, debug);
+            }
+            catch { /* not critical */ }
+        }
         // Resolve to absolute path for dedup — do this FIRST since bundlers like
         // tsx/esbuild may use path aliases (e.g., @config/env) that don't start
         // with './' or '/'. We need the resolved path to decide if it's user code.

package/dist/ws-observer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * WebSocket observer — patches popular WebSocket libraries to capture
+ * message events, connection lifecycle, and timing.
+ *
+ * Supports:
+ *   - ws (most popular Node.js WebSocket library)
+ *   - Native WebSocket (browser/Deno/Bun)
+ *   - socket.io (real-time framework)
+ *
+ * Written to .trickle/websocket.jsonl as:
+ *   { "kind": "ws", "event": "message", "direction": "in",
+ *     "data": "...", "timestamp": 1710516000, "url": "ws://..." }
+ */
+/**
+ * Patch ws (node WebSocket library) to capture messages.
+ */
+export declare function patchWs(wsModule: any, debug: boolean): void;
+/**
+ * Patch socket.io client to capture emit/on events.
+ */
+export declare function patchSocketIo(ioModule: any, debug: boolean): void;

package/dist/ws-observer.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * WebSocket observer — patches popular WebSocket libraries to capture
+ * message events, connection lifecycle, and timing.
+ *
+ * Supports:
+ *   - ws (most popular Node.js WebSocket library)
+ *   - Native WebSocket (browser/Deno/Bun)
+ *   - socket.io (real-time framework)
+ *
+ * Written to .trickle/websocket.jsonl as:
+ *   { "kind": "ws", "event": "message", "direction": "in",
+ *     "data": "...", "timestamp": 1710516000, "url": "ws://..." }
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patchWs = patchWs;
+exports.patchSocketIo = patchSocketIo;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+let wsFile = null;
+const MAX_EVENTS = 200;
+let eventCount = 0;
+const MAX_DATA_LENGTH = 500;
+function getWsFile() {
+    if (wsFile)
+        return wsFile;
+    const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch { }
+    wsFile = path.join(dir, 'websocket.jsonl');
+    try {
+        fs.writeFileSync(wsFile, '');
+    }
+    catch { }
+    ;
+    return wsFile;
+}
+function writeWsEvent(event) {
+    if (eventCount >= MAX_EVENTS)
+        return;
+    eventCount++;
+    try {
+        fs.appendFileSync(getWsFile(), JSON.stringify(event) + '\n');
+    }
+    catch { }
+}
+function truncateData(data) {
+    if (data === undefined || data === null)
+        return data;
+    if (typeof data === 'string') {
+        return data.length > MAX_DATA_LENGTH ? data.substring(0, MAX_DATA_LENGTH) + '...' : data;
+    }
+    if (Buffer.isBuffer(data)) {
+        return `<Buffer(${data.length} bytes)>`;
+    }
+    if (typeof data === 'object') {
+        try {
+            const s = JSON.stringify(data);
+            return s.length > MAX_DATA_LENGTH ? JSON.parse(s.substring(0, MAX_DATA_LENGTH) + '..."}}') : data;
+        }
+        catch {
+            return String(data).substring(0, MAX_DATA_LENGTH);
+        }
+    }
+    return data;
+}
+/**
+ * Patch ws (node WebSocket library) to capture messages.
+ */
+function patchWs(wsModule, debug) {
+    const WsClass = wsModule.WebSocket || wsModule;
+    if (!WsClass?.prototype || WsClass.prototype.__trickle_ws_patched)
+        return;
+    const origSend = WsClass.prototype.send;
+    if (origSend) {
+        WsClass.prototype.send = function patchedSend(data, ...args) {
+            writeWsEvent({
+                kind: 'ws',
+                event: 'message',
+                direction: 'out',
+                url: this.url || this._url,
+                data: truncateData(data),
+                timestamp: Date.now(),
+            });
+            return origSend.call(this, data, ...args);
+        };
+    }
+    // Patch 'on' to capture incoming messages
+    const origOn = WsClass.prototype.on;
+    if (origOn) {
+        WsClass.prototype.on = function patchedOn(event, listener, ...args) {
+            if (event === 'message') {
+                const wrappedListener = (data, ...rest) => {
+                    writeWsEvent({
+                        kind: 'ws',
+                        event: 'message',
+                        direction: 'in',
+                        url: this.url || this._url,
+                        data: truncateData(data),
+                        timestamp: Date.now(),
+                    });
+                    return listener(data, ...rest);
+                };
+                return origOn.call(this, event, wrappedListener, ...args);
+            }
+            if (event === 'open') {
+                const wrappedListener = (...rest) => {
+                    writeWsEvent({
+                        kind: 'ws',
+                        event: 'connect',
+                        url: this.url || this._url,
+                        timestamp: Date.now(),
+                    });
+                    return listener(...rest);
+                };
+                return origOn.call(this, event, wrappedListener, ...args);
+            }
+            if (event === 'close') {
+                const wrappedListener = (code, reason, ...rest) => {
+                    writeWsEvent({
+                        kind: 'ws',
+                        event: 'close',
+                        url: this.url || this._url,
+                        data: { code, reason: String(reason || '').substring(0, 100) },
+                        timestamp: Date.now(),
+                    });
+                    return listener(code, reason, ...rest);
+                };
+                return origOn.call(this, event, wrappedListener, ...args);
+            }
+            return origOn.call(this, event, listener, ...args);
+        };
+    }
+    WsClass.prototype.__trickle_ws_patched = true;
+    if (debug)
+        console.log('[trickle/ws] WebSocket tracing enabled');
+}
+/**
+ * Patch socket.io client to capture emit/on events.
+ */
+function patchSocketIo(ioModule, debug) {
+    // socket.io-client: the default export is a function that returns a Socket
+    const Socket = ioModule.Socket || (ioModule.io && ioModule.io.Socket);
+    if (!Socket?.prototype || Socket.prototype.__trickle_sio_patched)
+        return;
+    const origEmit = Socket.prototype.emit;
+    if (origEmit) {
+        Socket.prototype.emit = function patchedEmit(event, ...args) {
+            if (event !== 'connect' && event !== 'disconnect' && !event.startsWith('__')) {
+                writeWsEvent({
+                    kind: 'ws',
+                    event: 'emit',
+                    direction: 'out',
+                    channel: event,
+                    data: truncateData(args[0]),
+                    timestamp: Date.now(),
+                });
+            }
+            return origEmit.call(this, event, ...args);
+        };
+    }
+    const origOn = Socket.prototype.on;
+    if (origOn) {
+        Socket.prototype.on = function patchedOn(event, listener, ...rest) {
+            if (event !== 'connect' && event !== 'disconnect' && !event.startsWith('__')) {
+                const wrappedListener = (...args) => {
+                    writeWsEvent({
+                        kind: 'ws',
+                        event: 'emit',
+                        direction: 'in',
+                        channel: event,
+                        data: truncateData(args[0]),
+                        timestamp: Date.now(),
+                    });
+                    return listener(...args);
+                };
+                return origOn.call(this, event, wrappedListener, ...rest);
+            }
+            return origOn.call(this, event, listener, ...rest);
+        };
+    }
+    Socket.prototype.__trickle_sio_patched = true;
+    if (debug)
+        console.log('[trickle/ws] socket.io tracing enabled');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trickle-observe",
-  "version": "0.2.97",
+  "version": "0.2.98",
   "description": "Runtime type observability for JavaScript applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/observe-register.ts

@@ -1154,6 +1154,24 @@ if (enabled) {
       } catch { /* not critical */ }
     }
 
+    // WebSocket (ws)
+    if (request === 'ws' && !expressPatched.has('ws')) {
+      expressPatched.add('ws');
+      try {
+        const { patchWs } = require(path.join(__dirname, 'ws-observer.js'));
+        patchWs(exports, debug);
+      } catch { /* not critical */ }
+    }
+
+    // socket.io-client
+    if (request === 'socket.io-client' && !expressPatched.has('socket.io-client')) {
+      expressPatched.add('socket.io-client');
+      try {
+        const { patchSocketIo } = require(path.join(__dirname, 'ws-observer.js'));
+        patchSocketIo(exports, debug);
+      } catch { /* not critical */ }
+    }
+
     // Resolve to absolute path for dedup — do this FIRST since bundlers like
     // tsx/esbuild may use path aliases (e.g., @config/env) that don't start
     // with './' or '/'. We need the resolved path to decide if it's user code.

package/src/ws-observer.ts

@@ -0,0 +1,190 @@
+/**
+ * WebSocket observer — patches popular WebSocket libraries to capture
+ * message events, connection lifecycle, and timing.
+ *
+ * Supports:
+ *   - ws (most popular Node.js WebSocket library)
+ *   - Native WebSocket (browser/Deno/Bun)
+ *   - socket.io (real-time framework)
+ *
+ * Written to .trickle/websocket.jsonl as:
+ *   { "kind": "ws", "event": "message", "direction": "in",
+ *     "data": "...", "timestamp": 1710516000, "url": "ws://..." }
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface WsEvent {
+  kind: 'ws';
+  event: 'connect' | 'message' | 'close' | 'error' | 'emit';
+  direction?: 'in' | 'out';
+  url?: string;
+  data?: unknown;
+  channel?: string;
+  timestamp: number;
+}
+
+let wsFile: string | null = null;
+const MAX_EVENTS = 200;
+let eventCount = 0;
+const MAX_DATA_LENGTH = 500;
+
+function getWsFile(): string {
+  if (wsFile) return wsFile;
+  const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  wsFile = path.join(dir, 'websocket.jsonl');
+  try { fs.writeFileSync(wsFile, ''); } catch {};
+  return wsFile;
+}
+
+function writeWsEvent(event: WsEvent): void {
+  if (eventCount >= MAX_EVENTS) return;
+  eventCount++;
+  try {
+    fs.appendFileSync(getWsFile(), JSON.stringify(event) + '\n');
+  } catch {}
+}
+
+function truncateData(data: unknown): unknown {
+  if (data === undefined || data === null) return data;
+  if (typeof data === 'string') {
+    return data.length > MAX_DATA_LENGTH ? data.substring(0, MAX_DATA_LENGTH) + '...' : data;
+  }
+  if (Buffer.isBuffer(data)) {
+    return `<Buffer(${data.length} bytes)>`;
+  }
+  if (typeof data === 'object') {
+    try {
+      const s = JSON.stringify(data);
+      return s.length > MAX_DATA_LENGTH ? JSON.parse(s.substring(0, MAX_DATA_LENGTH) + '..."}}') : data;
+    } catch {
+      return String(data).substring(0, MAX_DATA_LENGTH);
+    }
+  }
+  return data;
+}
+
+/**
+ * Patch ws (node WebSocket library) to capture messages.
+ */
+export function patchWs(wsModule: any, debug: boolean): void {
+  const WsClass = wsModule.WebSocket || wsModule;
+  if (!WsClass?.prototype || (WsClass.prototype as any).__trickle_ws_patched) return;
+
+  const origSend = WsClass.prototype.send;
+  if (origSend) {
+    WsClass.prototype.send = function patchedSend(data: any, ...args: any[]) {
+      writeWsEvent({
+        kind: 'ws',
+        event: 'message',
+        direction: 'out',
+        url: this.url || this._url,
+        data: truncateData(data),
+        timestamp: Date.now(),
+      });
+      return origSend.call(this, data, ...args);
+    };
+  }
+
+  // Patch 'on' to capture incoming messages
+  const origOn = WsClass.prototype.on;
+  if (origOn) {
+    WsClass.prototype.on = function patchedOn(event: string, listener: any, ...args: any[]) {
+      if (event === 'message') {
+        const wrappedListener = (data: any, ...rest: any[]) => {
+          writeWsEvent({
+            kind: 'ws',
+            event: 'message',
+            direction: 'in',
+            url: this.url || this._url,
+            data: truncateData(data),
+            timestamp: Date.now(),
+          });
+          return listener(data, ...rest);
+        };
+        return origOn.call(this, event, wrappedListener, ...args);
+      }
+      if (event === 'open') {
+        const wrappedListener = (...rest: any[]) => {
+          writeWsEvent({
+            kind: 'ws',
+            event: 'connect',
+            url: this.url || this._url,
+            timestamp: Date.now(),
+          });
+          return listener(...rest);
+        };
+        return origOn.call(this, event, wrappedListener, ...args);
+      }
+      if (event === 'close') {
+        const wrappedListener = (code: number, reason: string, ...rest: any[]) => {
+          writeWsEvent({
+            kind: 'ws',
+            event: 'close',
+            url: this.url || this._url,
+            data: { code, reason: String(reason || '').substring(0, 100) },
+            timestamp: Date.now(),
+          });
+          return listener(code, reason, ...rest);
+        };
+        return origOn.call(this, event, wrappedListener, ...args);
+      }
+      return origOn.call(this, event, listener, ...args);
+    };
+  }
+
+  (WsClass.prototype as any).__trickle_ws_patched = true;
+  if (debug) console.log('[trickle/ws] WebSocket tracing enabled');
+}
+
+/**
+ * Patch socket.io client to capture emit/on events.
+ */
+export function patchSocketIo(ioModule: any, debug: boolean): void {
+  // socket.io-client: the default export is a function that returns a Socket
+  const Socket = ioModule.Socket || (ioModule.io && ioModule.io.Socket);
+  if (!Socket?.prototype || (Socket.prototype as any).__trickle_sio_patched) return;
+
+  const origEmit = Socket.prototype.emit;
+  if (origEmit) {
+    Socket.prototype.emit = function patchedEmit(event: string, ...args: any[]) {
+      if (event !== 'connect' && event !== 'disconnect' && !event.startsWith('__')) {
+        writeWsEvent({
+          kind: 'ws',
+          event: 'emit',
+          direction: 'out',
+          channel: event,
+          data: truncateData(args[0]),
+          timestamp: Date.now(),
+        });
+      }
+      return origEmit.call(this, event, ...args);
+    };
+  }
+
+  const origOn = Socket.prototype.on;
+  if (origOn) {
+    Socket.prototype.on = function patchedOn(event: string, listener: any, ...rest: any[]) {
+      if (event !== 'connect' && event !== 'disconnect' && !event.startsWith('__')) {
+        const wrappedListener = (...args: any[]) => {
+          writeWsEvent({
+            kind: 'ws',
+            event: 'emit',
+            direction: 'in',
+            channel: event,
+            data: truncateData(args[0]),
+            timestamp: Date.now(),
+          });
+          return listener(...args);
+        };
+        return origOn.call(this, event, wrappedListener, ...rest);
+      }
+      return origOn.call(this, event, listener, ...rest);
+    };
+  }
+
+  (Socket.prototype as any).__trickle_sio_patched = true;
+  if (debug) console.log('[trickle/ws] socket.io tracing enabled');
+}