@gettrace/cli 2.0.6 → 2.0.8

package/instrument/trace-instrument.cjs

@@ -0,0 +1,474 @@
+'use strict';
+/* ==========================================================================
+ * Trace Backend Instrumentation  (in-process, zero-dependency)
+ *
+ * Loaded into the USER'S backend process by Trace's dev_server via:
+ *     node --require <abs path to this file> <their server entry>
+ *
+ * It passively captures the execution flow of each incoming HTTP request —
+ * the route, any outbound HTTP/fetch calls, and (best-effort) database
+ * queries — as a tree of spans, and streams them to the Trace bridge for the
+ * Backend Flow Visualizer.
+ *
+ * ── DESIGN PRINCIPLES (non-negotiable) ───────────────────────────────────
+ *  1. NEVER throw into user code. Every hook is wrapped; on any internal
+ *     error we fall back to the original, un-instrumented behavior.
+ *  2. INERT BY DEFAULT. If TRACE_INGEST_URL is not set, this module does
+ *     nothing at all (returns immediately). So it is safe to --require even
+ *     for frontend dev servers; it only activates for backends Trace targets.
+ *  3. NO new dependencies. Uses only Node built-ins so it can run inside any
+ *     user project without installing anything.
+ *  4. NEVER instrument our own span-export requests (infinite-loop guard).
+ *  5. BOUNDED memory + network. Spans are batched, capped, and dropped under
+ *     backpressure rather than growing without limit.
+ * ========================================================================== */
+
+// ── Activation gate ────────────────────────────────────────────────────────
+// The bridge ingest endpoint, e.g. "http://127.0.0.1:8767/__trace/ingest".
+const INGEST_URL = process.env.TRACE_INGEST_URL || '';
+if (!INGEST_URL) {
+  // Not targeted by Trace — stay completely inert.
+  module.exports = { active: false };
+  return;
+}
+
+// Guard against double-injection (e.g. --require listed twice, or re-require).
+if (globalThis.__TRACE_INSTRUMENT_ACTIVE__) {
+  module.exports = globalThis.__TRACE_INSTRUMENT_ACTIVE__;
+  return;
+}
+
+let ingestTarget;
+try {
+  ingestTarget = new URL(INGEST_URL);
+} catch {
+  // Malformed ingest URL — refuse to activate rather than risk misbehaving.
+  module.exports = { active: false };
+  return;
+}
+
+const http = require('http');
+const https = require('https');
+
+let AsyncLocalStorage;
+try {
+  ({ AsyncLocalStorage } = require('async_hooks'));
+} catch {
+  AsyncLocalStorage = null;
+}
+// Without AsyncLocalStorage we cannot correlate child operations to a request.
+// Server spans still work; child spans simply won't be attached. Never fatal.
+const als = AsyncLocalStorage ? new AsyncLocalStorage() : null;
+
+// ── Config / limits ──────────────────────────────────────────────────────
+const SERVICE_NAME = process.env.TRACE_SERVICE_NAME || 'backend';
+const MAX_BUFFER = 2000;          // max spans queued for export before dropping
+const FLUSH_INTERVAL_MS = 250;    // batch export cadence
+const MAX_BATCH = 200;            // spans per export request
+const MAX_ATTR_STRING = 2048;     // truncate long attribute strings (e.g. SQL)
+const MAX_URL_LEN = 1024;
+
+// ── Safety helpers ─────────────────────────────────────────────────────────
+function safe(fn, fallback) {
+  try { return fn(); } catch { return fallback; }
+}
+function truncate(str, max) {
+  if (typeof str !== 'string') return str;
+  return str.length > max ? str.slice(0, max - 1) + '\u2026' : str;
+}
+function hrNowMs() {
+  // Wall-clock ms with sub-ms precision; aligned to Date.now for the UI.
+  return Date.now();
+}
+let _seq = 0;
+function genId() {
+  // 16 hex chars; collision-safe enough for a dev session.
+  _seq = (_seq + 1) >>> 0;
+  return (
+    Date.now().toString(16) +
+    Math.floor(Math.random() * 0xffffff).toString(16).padStart(6, '0') +
+    _seq.toString(16).padStart(4, '0')
+  ).slice(0, 16);
+}
+
+// ── Span buffer + exporter ──────────────────────────────────────────────────
+const buffer = [];
+let dropped = 0;
+let exporting = false;       // true while our own export request is in flight
+let flushTimer = null;
+
+function enqueue(span) {
+  if (buffer.length >= MAX_BUFFER) { dropped++; return; }
+  buffer.push(span);
+  scheduleFlush();
+}
+
+function scheduleFlush() {
+  if (flushTimer) return;
+  flushTimer = setTimeout(() => {
+    flushTimer = null;
+    flush();
+  }, FLUSH_INTERVAL_MS);
+  // Do not keep the event loop alive solely for flushing.
+  if (flushTimer.unref) flushTimer.unref();
+}
+
+function flush() {
+  if (buffer.length === 0) return;
+  const batch = buffer.splice(0, MAX_BATCH);
+  const payload = safe(() => JSON.stringify({
+    service: SERVICE_NAME,
+    pid: process.pid,
+    dropped,
+    spans: batch,
+  }), null);
+  if (payload == null) return; // unserializable — drop silently
+  dropped = 0;
+
+  const isHttps = ingestTarget.protocol === 'https:';
+  const lib = isHttps ? https : http;
+  const opts = {
+    hostname: ingestTarget.hostname,
+    port: ingestTarget.port || (isHttps ? 443 : 80),
+    path: ingestTarget.pathname + (ingestTarget.search || ''),
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(payload),
+      // Marker so our OWN outbound hook ignores this request (loop guard).
+      'x-trace-ingest': '1',
+    },
+    // Never hold up the host process on a slow/absent bridge.
+    timeout: 2000,
+  };
+
+  exporting = true;
+  let req;
+  try {
+    req = lib.request(opts, (res) => {
+      // Drain and discard.
+      res.on('data', () => {});
+      res.on('end', () => {});
+      res.resume();
+    });
+  } catch {
+    exporting = false;
+    return;
+  }
+  req.on('error', () => { /* bridge down — drop this batch */ });
+  req.on('timeout', () => { safe(() => req.destroy()); });
+  req.on('close', () => { exporting = false; if (buffer.length) scheduleFlush(); });
+  safe(() => { req.end(payload); });
+}
+
+// Best-effort flush on exit so the last requests aren't lost.
+safe(() => {
+  process.once('beforeExit', () => { flush(); });
+});
+
+// ── Span emission ───────────────────────────────────────────────────────────
+function emitSpan(s) {
+  // Normalize + clamp before queueing.
+  if (s.endTime == null) s.endTime = hrNowMs();
+  if (s.duration == null) s.duration = Math.max(0, s.endTime - s.startTime);
+  enqueue(s);
+}
+
+function currentContext() {
+  return als ? als.getStore() : undefined;
+}
+
+// ── HTTP server instrumentation (incoming requests) ─────────────────────────
+// Patch http.Server.prototype.emit so we wrap the 'request' event. This covers
+// http AND https servers (https.Server delegates to the same emit), and every
+// framework built on Node's http server (Express, Fastify, Koa, Nest, raw http).
+function instrumentHttpServer() {
+  const proto = http.Server && http.Server.prototype;
+  if (!proto || proto.__tracePatched) return;
+  const origEmit = proto.emit;
+  if (typeof origEmit !== 'function') return;
+
+  proto.emit = function patchedEmit(event, ...args) {
+    if (event !== 'request') {
+      return origEmit.apply(this, [event, ...args]);
+    }
+    const req = args[0];
+    const res = args[1];
+    // Bail out cleanly if shapes are unexpected.
+    if (!req || !res) return origEmit.apply(this, [event, ...args]);
+
+    // Skip our own ingest traffic (defensive; ingest is outbound, but guard anyway).
+    if (safe(() => req.headers && req.headers['x-trace-ingest'] === '1', false)) {
+      return origEmit.apply(this, [event, ...args]);
+    }
+
+    const startTime = hrNowMs();
+    const traceId = genId();
+    const spanId = genId();
+    const method = safe(() => (req.method || 'GET').toUpperCase(), 'GET');
+    const rawUrl = safe(() => truncate(req.url || '/', MAX_URL_LEN), '/');
+
+    const ctx = {
+      traceId,
+      rootSpanId: spanId,
+      // Stack of currently-open span ids so children attach to the nearest parent.
+      // For the MVP we attach children directly to the root request span.
+      children: 0,
+    };
+
+    let finished = false;
+    const finalize = () => {
+      if (finished) return;
+      finished = true;
+      const statusCode = safe(() => res.statusCode, 0);
+      const route = safe(() => req.route && req.route.path, undefined) ||
+                    safe(() => req.baseUrl, undefined) ||
+                    undefined;
+      emitSpan({
+        traceId,
+        spanId,
+        parentSpanId: null,
+        kind: 'server',
+        stage: 'route',
+        name: method + ' ' + (route || pathOf(rawUrl)),
+        startTime,
+        endTime: hrNowMs(),
+        attributes: clean({
+          'http.method': method,
+          'http.target': rawUrl,
+          'http.route': route,
+          'http.status_code': statusCode,
+          'http.status_class': statusClass(statusCode),
+        }),
+        error: statusCode >= 500
+          ? { message: 'HTTP ' + statusCode }
+          : null,
+      });
+    };
+
+    safe(() => {
+      res.once('finish', finalize);
+      res.once('close', finalize);
+    });
+
+    if (!als) {
+      return origEmit.apply(this, [event, ...args]);
+    }
+    // Run the rest of request handling inside the ALS context so outbound
+    // calls / db queries can find their parent request.
+    return als.run(ctx, () => origEmit.apply(this, [event, ...args]));
+  };
+
+  proto.__tracePatched = true;
+}
+
+function pathOf(u) {
+  return safe(() => {
+    const q = u.indexOf('?');
+    return q === -1 ? u : u.slice(0, q);
+  }, u);
+}
+function statusClass(code) {
+  if (!code) return 'unknown';
+  if (code >= 500) return '5xx';
+  if (code >= 400) return '4xx';
+  if (code >= 300) return '3xx';
+  if (code >= 200) return '2xx';
+  return '1xx';
+}
+function clean(obj) {
+  const out = {};
+  for (const k in obj) {
+    const v = obj[k];
+    if (v === undefined || v === null) continue;
+    out[k] = typeof v === 'string' ? truncate(v, MAX_ATTR_STRING) : v;
+  }
+  return out;
+}
+
+// ── Outbound HTTP/HTTPS instrumentation (external API calls) ─────────────────
+function instrumentOutbound(lib, scheme) {
+  if (!lib || lib.__traceOutboundPatched) return;
+  const origRequest = lib.request;
+  const origGet = lib.get;
+  if (typeof origRequest !== 'function') return;
+
+  function wrap(orig) {
+    return function patched(...args) {
+      // Determine if this call originates inside a tracked request AND is not
+      // our own ingest export. If either fails, call through untouched.
+      const ctx = currentContext();
+      let isIngest = false;
+      safe(() => {
+        for (const a of args) {
+          if (a && typeof a === 'object' && a.headers && a.headers['x-trace-ingest'] === '1') {
+            isIngest = true; break;
+          }
+        }
+      });
+      if (exporting || isIngest || !ctx) {
+        return orig.apply(this, args);
+      }
+
+      const startTime = hrNowMs();
+      const spanId = genId();
+      const meta = safe(() => describeOutbound(scheme, args), {});
+      let clientReq;
+      try {
+        clientReq = orig.apply(this, args);
+      } catch (e) {
+        // Record the synchronous failure, then rethrow to preserve behavior.
+        emitSpan({
+          traceId: ctx.traceId, spanId, parentSpanId: ctx.rootSpanId,
+          kind: 'client', stage: 'external',
+          name: (meta.method || 'GET') + ' ' + (meta.host || 'external'),
+          startTime, endTime: hrNowMs(),
+          attributes: clean(meta.attributes), error: { message: String(e && e.message || e) },
+        });
+        throw e;
+      }
+
+      safe(() => {
+        let done = false;
+        const finishClient = (statusCode, errMsg) => {
+          if (done) return; done = true;
+          emitSpan({
+            traceId: ctx.traceId, spanId, parentSpanId: ctx.rootSpanId,
+            kind: 'client', stage: 'external',
+            name: (meta.method || 'GET') + ' ' + (meta.host || 'external'),
+            startTime, endTime: hrNowMs(),
+            attributes: clean(Object.assign({}, meta.attributes, {
+              'http.status_code': statusCode,
+              'http.status_class': statusClass(statusCode),
+            })),
+            error: errMsg ? { message: errMsg } : (statusCode >= 500 ? { message: 'HTTP ' + statusCode } : null),
+          });
+        };
+        clientReq.once('response', (res) => {
+          const code = safe(() => res.statusCode, 0);
+          res.once('end', () => finishClient(code));
+          // Some responses never emit 'end' if not consumed; also finish on close.
+          res.once('close', () => finishClient(code));
+        });
+        clientReq.once('error', (e) => finishClient(0, String(e && e.message || e)));
+        clientReq.once('close', () => finishClient(safe(() => clientReq.res && clientReq.res.statusCode, 0)));
+      });
+
+      return clientReq;
+    };
+  }
+
+  safe(() => { lib.request = wrap(origRequest); });
+  if (typeof origGet === 'function') {
+    // http.get calls http.request internally in most Node versions, but patch
+    // it explicitly to be safe across versions.
+    safe(() => { lib.get = wrap(origGet); });
+  }
+  lib.__traceOutboundPatched = true;
+}
+
+function describeOutbound(scheme, args) {
+  let method = 'GET';
+  let host = 'external';
+  let pathName = '';
+  let url;
+  const a0 = args[0];
+  if (typeof a0 === 'string') {
+    url = safe(() => new URL(a0), null);
+  } else if (a0 instanceof URL) {
+    url = a0;
+  } else if (a0 && typeof a0 === 'object') {
+    method = (a0.method || 'GET').toUpperCase();
+    host = a0.hostname || a0.host || 'external';
+    pathName = a0.path || '';
+  }
+  // Options object can also be the 2nd arg when 1st is a URL/string.
+  const optsArg = (a0 instanceof URL || typeof a0 === 'string') && args[1] && typeof args[1] === 'object' ? args[1] : null;
+  if (optsArg && optsArg.method) method = String(optsArg.method).toUpperCase();
+  if (url) {
+    host = url.host;
+    pathName = url.pathname + (url.search || '');
+  }
+  return {
+    method, host,
+    attributes: {
+      'http.method': method,
+      'http.url': truncate((scheme ? scheme + '://' : '') + host + pathName, MAX_URL_LEN),
+      'net.peer.name': host,
+    },
+  };
+}
+
+// ── fetch() / undici instrumentation (external API calls) ────────────────────
+function instrumentFetch() {
+  if (typeof globalThis.fetch !== 'function' || globalThis.fetch.__tracePatched) return;
+  const origFetch = globalThis.fetch;
+  const patched = function tracedFetch(input, init) {
+    const ctx = currentContext();
+    if (!ctx || exporting) return origFetch.call(this, input, init);
+
+    const startTime = hrNowMs();
+    const spanId = genId();
+    const method = safe(() => ((init && init.method) || (input && input.method) || 'GET').toUpperCase(), 'GET');
+    const urlStr = safe(() => {
+      if (typeof input === 'string') return input;
+      if (input instanceof URL) return input.href;
+      if (input && input.url) return input.url;
+      return 'external';
+    }, 'external');
+    // Skip our own ingest export if it ever routed through fetch.
+    if (urlStr.indexOf(ingestTarget.host) !== -1 && urlStr.indexOf('__trace') !== -1) {
+      return origFetch.call(this, input, init);
+    }
+    const host = safe(() => new URL(urlStr).host, 'external');
+
+    let p;
+    try {
+      p = origFetch.call(this, input, init);
+    } catch (e) {
+      emitSpan({
+        traceId: ctx.traceId, spanId, parentSpanId: ctx.rootSpanId,
+        kind: 'client', stage: 'external', name: method + ' ' + host,
+        startTime, endTime: hrNowMs(),
+        attributes: clean({ 'http.method': method, 'http.url': truncate(urlStr, MAX_URL_LEN) }),
+        error: { message: String(e && e.message || e) },
+      });
+      throw e;
+    }
+    return p.then(
+      (resp) => {
+        const code = safe(() => resp.status, 0);
+        emitSpan({
+          traceId: ctx.traceId, spanId, parentSpanId: ctx.rootSpanId,
+          kind: 'client', stage: 'external', name: method + ' ' + host,
+          startTime, endTime: hrNowMs(),
+          attributes: clean({ 'http.method': method, 'http.url': truncate(urlStr, MAX_URL_LEN), 'http.status_code': code, 'http.status_class': statusClass(code) }),
+          error: code >= 500 ? { message: 'HTTP ' + code } : null,
+        });
+        return resp;
+      },
+      (err) => {
+        emitSpan({
+          traceId: ctx.traceId, spanId, parentSpanId: ctx.rootSpanId,
+          kind: 'client', stage: 'external', name: method + ' ' + host,
+          startTime, endTime: hrNowMs(),
+          attributes: clean({ 'http.method': method, 'http.url': truncate(urlStr, MAX_URL_LEN) }),
+          error: { message: String(err && err.message || err) },
+        });
+        throw err;
+      }
+    );
+  };
+  patched.__tracePatched = true;
+  safe(() => { globalThis.fetch = patched; });
+}
+
+// ── Activate (each step independently guarded) ───────────────────────────────
+safe(instrumentHttpServer);
+safe(() => instrumentOutbound(http, 'http'));
+safe(() => instrumentOutbound(https, 'https'));
+safe(instrumentFetch);
+
+const api = { active: true, version: 1, service: SERVICE_NAME };
+globalThis.__TRACE_INSTRUMENT_ACTIVE__ = api;
+module.exports = api;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gettrace/cli",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "description": "Trace IDE Bridge for connecting local filesystem to Trace browser extensions.",
   "main": "dist/index.js",
   "type": "module",
@@ -9,7 +9,8 @@
     "trace-connect": "./dist/index.js"
   },
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/index.js",
+    "build": "rm -rf dist && esbuild src/index.ts --bundle --platform=node --format=esm --packages=external --minify --legal-comments=none --outfile=dist/index.js",
+    "build:dev": "rm -rf dist && esbuild src/index.ts --bundle --platform=node --format=esm --packages=external --sourcemap --outfile=dist/index.js",
     "dev": "esbuild src/index.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/index.js --watch",
     "start": "node dist/index.js",
     "prepublishOnly": "npm run build",
@@ -41,7 +42,7 @@
     "@babel/traverse": "^7.24.0",
     "@babel/generator": "^7.24.0",
     "@babel/types": "^7.24.0",
-    "@gettrace/agent": "^2.0.5"
+    "@gettrace/agent": "^2.0.6"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -52,9 +53,12 @@
     "typescript": "^5.3.0"
   },
   "files": [
-    "dist",
-    "native-host",
+    "dist/index.js",
+    "native-host/host.cjs",
+    "native-host/host-entry",
+    "native-host/package.json",
     "scripts",
+    "instrument",
     "README.md"
   ]
 }