hrpc-inspector 0.0.0 → 0.1.0

package/dist/index.js

@@ -0,0 +1,441 @@
+// src/observe.ts
+import { BatchFlusher } from "hrpc-inspector-probe/flush";
+import { createHyperswarmExporter } from "hrpc-inspector-probe/exporters/hyperswarm";
+import { Redactor } from "hrpc-inspector-probe/redactor";
+
+// src/detect.ts
+function detectRuntime(env = globalThis) {
+  const has = (v) => typeof v !== "undefined" && v !== null;
+  if (has(env.Pear)) return { runtime: "pear", isBareRuntime: true, isBridgeOnly: false };
+  if (has(env.Bare)) return { runtime: "bare", isBareRuntime: true, isBridgeOnly: false };
+  const rn = env.navigator?.product === "ReactNative" || has(env.__fbBatchedBridge) || has(env.HermesInternal);
+  if (rn) return { runtime: "react-native", isBareRuntime: false, isBridgeOnly: true };
+  if (has(env.process?.versions?.electron)) {
+    return { runtime: "electron", isBareRuntime: false, isBridgeOnly: false };
+  }
+  if (has(env.process?.versions?.node)) {
+    return { runtime: "node", isBareRuntime: false, isBridgeOnly: false };
+  }
+  if (has(env.window) && has(env.document)) {
+    return { runtime: "browser", isBareRuntime: false, isBridgeOnly: true };
+  }
+  return { runtime: "unknown", isBareRuntime: false, isBridgeOnly: false };
+}
+
+// src/reporters.ts
+function createWebSocketReporter(url, opts = {}) {
+  const WS = opts.WebSocketImpl ?? globalThis.WebSocket;
+  const maxQueue = opts.maxQueue ?? 1e3;
+  const reconnectMs = opts.reconnectMs ?? 3e3;
+  const OPEN = 1;
+  let ws = null;
+  let queue = [];
+  let closed = false;
+  function enqueue(ev) {
+    queue.push(ev);
+    if (queue.length > maxQueue) queue.shift();
+  }
+  function rawSend(ev) {
+    try {
+      ws.send(JSON.stringify(ev));
+    } catch {
+      enqueue(ev);
+    }
+  }
+  function ensure() {
+    if (closed || !WS) return;
+    if (ws && (ws.readyState === 0 || ws.readyState === 1)) return;
+    try {
+      ws = new WS(url);
+      ws.onopen = () => {
+        if (opts.announce !== void 0) rawSend({ __source: opts.announce });
+        const q = queue;
+        queue = [];
+        for (const e of q) rawSend(e);
+      };
+      ws.onclose = () => {
+        ws = null;
+        if (!closed) setTimeout(ensure, reconnectMs);
+      };
+      ws.onerror = () => {
+      };
+      if (opts.onMessage) ws.onmessage = (m) => {
+        try {
+          opts.onMessage(JSON.parse(m.data));
+        } catch {
+        }
+      };
+    } catch {
+      ws = null;
+    }
+  }
+  return {
+    export(batch) {
+      if (closed) return;
+      ensure();
+      for (const ev of batch) {
+        if (ws && ws.readyState === OPEN) rawSend(ev);
+        else enqueue(ev);
+      }
+    },
+    close() {
+      closed = true;
+      try {
+        ws?.close();
+      } catch {
+      }
+      ws = null;
+    }
+  };
+}
+
+// src/wrap-client.ts
+var seq = 0;
+var invokeCtx = null;
+function setInvokeContext(ctx) {
+  invokeCtx = ctx;
+}
+var PREVIEW_MAX_BYTES = 64e3;
+function defaultPreview(v) {
+  try {
+    const s = JSON.stringify(v);
+    if (s === void 0) return String(v);
+    if (s.length <= PREVIEW_MAX_BYTES) return v;
+    if (typeof v === "string") return v.slice(0, PREVIEW_MAX_BYTES) + `\u2026[truncated ${s.length}B]`;
+    return { __truncated: true, bytes: s.length, preview: s.slice(0, 2e3) + "\u2026" };
+  } catch {
+    return { __unserializable: true };
+  }
+}
+function monitorStream(report, endpoint, corrId, stream, t0, preview, tag) {
+  report({ type: "stream.open", method: endpoint, corrId, t: Date.now(), ...tag });
+  let n = 0;
+  let ended = false;
+  const settle = (status, extra) => {
+    if (ended) return;
+    ended = true;
+    report({ type: "request.end", method: endpoint, corrId, status, count: n, dur: Date.now() - t0, t: Date.now(), ...tag, ...extra || {} });
+  };
+  try {
+    stream.on("data", (item) => report({ type: "stream.data", method: endpoint, corrId, seq: ++n, item: preview(item), t: Date.now(), ...tag }));
+    stream.on("error", (err) => settle("error", { error: String(err) }));
+    stream.on("end", () => settle("closed"));
+    stream.on("close", () => settle("closed"));
+  } catch (e) {
+    report({ type: "request.end", method: endpoint, corrId, status: "error", error: "monitor-failed: " + String(e), dur: 0, t: Date.now(), ...tag });
+  }
+}
+function wrapFn(report, endpoint, fn, self, preview, monitorStreams, onCall) {
+  return function observed(...args) {
+    const corrId = "rpc-" + ++seq;
+    let tag = {};
+    if (invokeCtx && invokeCtx.method === endpoint) {
+      tag = { origin: "gui", invokeId: invokeCtx.invokeId, replayOf: invokeCtx.replayOf };
+      invokeCtx = null;
+    }
+    if (onCall) {
+      try {
+        onCall(corrId, endpoint, args);
+      } catch {
+      }
+    }
+    const t = Date.now();
+    report({ type: "request.start", method: endpoint, corrId, args: preview(args), t, ...tag });
+    let result;
+    try {
+      result = fn.apply(self, args);
+    } catch (err) {
+      report({ type: "request.end", method: endpoint, corrId, status: "error", error: String(err), dur: Date.now() - t, t: Date.now(), ...tag });
+      throw err;
+    }
+    if (result && typeof result.then === "function") {
+      result.then(
+        (res) => report({ type: "request.end", method: endpoint, corrId, status: "ok", response: preview(res), dur: Date.now() - t, t: Date.now(), ...tag }),
+        (err) => report({ type: "request.end", method: endpoint, corrId, status: "error", error: String(err), dur: Date.now() - t, t: Date.now(), ...tag })
+      );
+    } else if (monitorStreams && result && typeof result.on === "function") {
+      monitorStream(report, endpoint, corrId, result, t, preview, tag);
+    } else {
+      report({ type: "request.end", method: endpoint, corrId, status: "ok", response: preview(result), dur: Date.now() - t, t: Date.now(), ...tag });
+    }
+    return result;
+  };
+}
+function wrapClient(client, report, opts = {}) {
+  if (!client || typeof client !== "object") return client;
+  const preview = opts.preview ?? defaultPreview;
+  const monitorStreams = opts.monitorStreams !== false;
+  try {
+    for (const ns of Object.keys(client)) {
+      const group = client[ns];
+      if (group && typeof group === "object") {
+        for (const m of Object.keys(group)) {
+          if (typeof group[m] === "function") group[m] = wrapFn(report, `${ns}.${m}`, group[m], group, preview, monitorStreams, opts.onCall);
+        }
+      } else if (typeof group === "function") {
+        client[ns] = wrapFn(report, ns, group, client, preview, monitorStreams, opts.onCall);
+      }
+    }
+  } catch {
+  }
+  return client;
+}
+
+// src/observe.ts
+var DEFAULT_TOPIC = "p2p-observability-hub:v0";
+function persistentId(runtime) {
+  try {
+    const ls = globalThis.localStorage;
+    if (runtime === "browser" && ls) {
+      const KEY = "hrpc-inspector:deviceId";
+      let v = ls.getItem(KEY);
+      if (!v) {
+        v = Math.random().toString(36).slice(2, 10);
+        ls.setItem(KEY, v);
+      }
+      return v;
+    }
+  } catch {
+  }
+  return Math.random().toString(36).slice(2, 8);
+}
+function resolveSource(s, runtime) {
+  if (typeof s === "string" && s) return { id: s, label: s, runtime };
+  const p = s ?? {};
+  const deviceId = p.deviceId || void 0;
+  const appId = (p.appId ?? p.app) || void 0;
+  const enc = (v) => encodeURIComponent(v);
+  const explicitId = typeof p.id === "string" && p.id ? p.id : void 0;
+  const id = explicitId ?? (deviceId && appId ? `d=${enc(deviceId)};a=${enc(appId)}` : deviceId ? `d=${enc(deviceId)}` : appId ? `a=${enc(appId)}` : `r=${runtime}-${persistentId(runtime)}`);
+  const parts = [appId, p.device ?? deviceId, p.variant].filter(Boolean);
+  const label = (typeof p.label === "string" && p.label ? p.label : void 0) ?? (parts.length ? parts.join(" \xB7 ") : id);
+  return { ...p, id, label, runtime, deviceId, appId };
+}
+function redactSource(src, redactor) {
+  const id = redactor.hashPeer(src.id);
+  return {
+    id,
+    label: id,
+    // no human name on the wire
+    runtime: src.runtime,
+    ...src.deviceId ? { deviceId: redactor.hashPeer(src.deviceId) } : {},
+    ...src.appId ? { appId: src.appId } : {},
+    // a bundle id is not personal
+    ...src.variant ? { variant: src.variant } : {}
+    // e.g. "nightly"
+  };
+}
+function createDeferredExporter() {
+  let live = null;
+  const buffered = [];
+  return {
+    export(batch) {
+      if (live) live.export(batch);
+      else buffered.push(batch);
+    },
+    attach(stream) {
+      live = createHyperswarmExporter(stream);
+      for (const b of buffered) live.export(b);
+      buffered.length = 0;
+    },
+    get pendingBatches() {
+      return buffered.length;
+    }
+  };
+}
+async function autoSwarm(topic, onConnection) {
+  const Hyperswarm = (await import("hyperswarm")).default;
+  const crypto = (await import("hypercore-crypto")).default;
+  const swarm = new Hyperswarm();
+  const topicKey = crypto.hash(Buffer.from(topic));
+  swarm.on("connection", (conn) => onConnection(conn));
+  await swarm.join(topicKey, { client: true, server: false }).flushed();
+}
+function observe(opts = {}) {
+  const info = detectRuntime();
+  const source = resolveSource(opts.source, info.runtime);
+  const redactOn = opts.redact ?? (opts.websocket ? false : true);
+  const redactor = opts.redactor ?? (redactOn ? new Redactor({ bodyAllowlist: opts.bodyAllowlist }) : null);
+  const wireSource = redactor ? redactSource(source, redactor) : source;
+  const invokeEnabled = opts.allowInvoke === true && !!opts.websocket;
+  const replayLogMax = opts.replayLogMax ?? 2e3;
+  const recentCalls = /* @__PURE__ */ new Map();
+  const recordCall = invokeEnabled ? (corrId, method, args) => {
+    recentCalls.set(corrId, { method, args });
+    if (recentCalls.size > replayLogMax) {
+      const oldest = recentCalls.keys().next().value;
+      if (oldest !== void 0) recentCalls.delete(oldest);
+    }
+  } : void 0;
+  let wrapped = null;
+  let exporter;
+  let reporter = null;
+  let deferred = null;
+  let mode;
+  if (opts.exporter) {
+    exporter = opts.exporter;
+    mode = "custom";
+  } else if (opts.websocket) {
+    reporter = createWebSocketReporter(opts.websocket, {
+      // Advertise the replay capability so the GUI shows Replay only for opted-in sources.
+      announce: invokeEnabled ? { ...wireSource, caps: { invoke: true } } : wireSource,
+      // Inbound handler ONLY when replay is enabled — otherwise the reporter stays send-only.
+      onMessage: invokeEnabled ? handleInvoke : void 0
+    });
+    exporter = reporter;
+    mode = "websocket";
+  } else if (opts.stream) {
+    exporter = createHyperswarmExporter(opts.stream);
+    mode = "stream";
+  } else {
+    deferred = createDeferredExporter();
+    exporter = deferred;
+    mode = "buffering";
+  }
+  const flusher = new BatchFlusher({
+    intervalMs: opts.intervalMs ?? 200,
+    onFlush: (batch) => {
+      const out = redactor ? redactor.redactBatch(batch) : batch;
+      exporter.export(out.map((e) => ({ ...e, src: wireSource.id })));
+    }
+  });
+  flusher.start();
+  const sink = {
+    emit(event) {
+      try {
+        flusher.add(event);
+      } catch {
+      }
+    }
+  };
+  const INFLIGHT_MAX = 1e3;
+  const inflightCalls = /* @__PURE__ */ new Map();
+  const report = (event) => {
+    const e = event;
+    const corrId = e && typeof e.corrId === "string" ? e.corrId : null;
+    if (corrId) {
+      if (e.type === "request.start") {
+        inflightCalls.set(corrId, { method: String(e.method ?? ""), corrId, t: typeof e.t === "number" ? e.t : Date.now() });
+        if (inflightCalls.size > INFLIGHT_MAX) {
+          const oldest = inflightCalls.keys().next().value;
+          if (oldest !== void 0) inflightCalls.delete(oldest);
+        }
+      } else if (e.type === "stream.open" || e.type === "request.end") {
+        inflightCalls.delete(corrId);
+      }
+    }
+    sink.emit(event);
+  };
+  function emitInvokeError(invokeId, corrId, error) {
+    report({ type: "invoke.error", invokeId, replayOf: corrId, origin: "gui", error, t: Date.now() });
+  }
+  function handleInvoke(msg) {
+    if (!invokeEnabled || !msg || !msg.__invoke) return;
+    const corrId = String(msg.__invoke.corrId ?? "");
+    const invokeId = String(msg.__invoke.invokeId ?? "");
+    if (!wrapped) return emitInvokeError(invokeId, corrId, "client-not-wrapped");
+    const rec = recentCalls.get(corrId);
+    if (!rec) return emitInvokeError(invokeId, corrId, "unknown-corrId");
+    const edited = msg.__invoke.args;
+    if (edited !== void 0 && !Array.isArray(edited)) return emitInvokeError(invokeId, corrId, "bad-args");
+    const args = edited !== void 0 ? edited : rec.args;
+    if (opts.canReplay && !opts.canReplay(rec.method, args)) return emitInvokeError(invokeId, corrId, "blocked-by-canReplay");
+    const [ns, m] = rec.method.split(".", 2);
+    const fn = m ? wrapped?.[ns]?.[m] : wrapped?.[ns];
+    if (typeof fn !== "function") return emitInvokeError(invokeId, corrId, "method-unavailable");
+    try {
+      setInvokeContext({ invokeId, replayOf: corrId, method: rec.method });
+      (m ? wrapped[ns][m] : wrapped[ns])(...args);
+    } catch (e) {
+      emitInvokeError(invokeId, corrId, "threw: " + String(e));
+    } finally {
+      setInvokeContext(null);
+    }
+  }
+  const attach = (stream) => {
+    if (deferred) deferred.attach(stream);
+  };
+  if (mode === "buffering" && info.isBareRuntime && opts.autoSwarm !== false) {
+    autoSwarm(opts.topic ?? DEFAULT_TOPIC, attach).catch(() => {
+    });
+  }
+  return {
+    sink,
+    flusher,
+    runtime: info.runtime,
+    mode,
+    redactor,
+    source,
+    report,
+    inflight: () => [...inflightCalls.values()],
+    wrapClient: (client, o) => {
+      wrapped = wrapClient(client, report, { ...o || {}, onCall: recordCall });
+      return wrapped;
+    },
+    bridgeTraces: (setTraceFunction) => {
+      let on = true;
+      try {
+        setTraceFunction((trace) => {
+          if (!on) return;
+          try {
+            const obj = trace && trace.object || {};
+            const caller = trace && trace.caller || {};
+            const data = caller.props;
+            const event = data && data.event || caller.functionName || "trace";
+            report({
+              type: "trace",
+              plane: "trace",
+              className: obj.className,
+              objId: obj.id,
+              objProps: obj.props,
+              method: (obj.className ? obj.className + "." : "") + event,
+              // GUI groups/labels by this
+              event,
+              data,
+              caller: caller.functionName ? caller.functionName + ":" + caller.line : void 0,
+              t: Date.now()
+            });
+          } catch {
+          }
+        });
+      } catch {
+      }
+      return () => {
+        on = false;
+      };
+    },
+    attach,
+    stop: () => {
+      flusher.stop();
+      reporter?.close();
+    }
+  };
+}
+
+// src/index.ts
+import {
+  instrumentDataChannel,
+  instrumentPeerConnection
+} from "hrpc-inspector-probe/adapters/webrtc";
+import { instrumentWebSocket } from "hrpc-inspector-probe/adapters/websocket";
+import { instrumentHyperswarmStream } from "hrpc-inspector-probe/adapters/hyperswarm";
+import { CollectorSink } from "hrpc-inspector-probe/core/sink";
+import { BatchFlusher as BatchFlusher2 } from "hrpc-inspector-probe/flush";
+import { createHyperswarmExporter as createHyperswarmExporter2 } from "hrpc-inspector-probe/exporters/hyperswarm";
+import { StreamFramer, encodeFrame } from "hrpc-inspector-probe/transport/framing";
+export {
+  BatchFlusher2 as BatchFlusher,
+  CollectorSink,
+  DEFAULT_TOPIC,
+  StreamFramer,
+  createHyperswarmExporter2 as createHyperswarmExporter,
+  createWebSocketReporter,
+  detectRuntime,
+  encodeFrame,
+  instrumentDataChannel,
+  instrumentHyperswarmStream,
+  instrumentPeerConnection,
+  instrumentWebSocket,
+  observe,
+  wrapClient
+};