hrpc-inspector 0.0.0 → 0.1.1

package/dist/index.js

@@ -0,0 +1,442 @@
+// 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 enc = new TextEncoder();
+  const topicKey = crypto.hash(enc.encode(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
+};

package/dist/observe.d.ts

@@ -0,0 +1,119 @@
+import { BatchFlusher } from 'hrpc-inspector-probe/flush';
+import type { WritableStreamLike, HyperswarmExporter } from 'hrpc-inspector-probe/exporters/hyperswarm';
+import { Redactor } from 'hrpc-inspector-probe/redactor';
+import type { EventSink, L2Event } from 'hrpc-inspector-probe/sink';
+import type { Runtime } from './detect.js';
+import type { Report, WrapClientOptions } from './wrap-client.js';
+export declare const DEFAULT_TOPIC = "p2p-observability-hub:v0";
+export interface SourceInfo {
+    /** Stable id used to group/select this source in the GUI. */
+    id: string;
+    /** Human label shown in the selector. */
+    label: string;
+    /** Detected runtime (react-native | pear | bare | electron | node | browser). */
+    runtime: string;
+    /** Physical device id (client-supplied; e.g. an app's own options.deviceId). Lets the GUI select by device. */
+    deviceId?: string;
+    /** App / install instance id — distinguishes MULTIPLE apps sharing one package. */
+    appId?: string;
+    [extra: string]: unknown;
+}
+export interface ObserveOptions {
+    /** Flush cadence; must be in the collector's verified 100-250ms window. Default 200. */
+    intervalMs?: number;
+    /** Explicit hub connection (a NoiseSecretStream / socket). Skips auto-swarm. */
+    stream?: WritableStreamLike;
+    /** Fully custom exporter (e.g. Rozenite bridge, OTLP). Skips everything else. */
+    exporter?: HyperswarmExporter;
+    /** Hub topic string; must match the hub's. Default DEFAULT_TOPIC. */
+    topic?: string;
+    /** Set false to disable Bare/Pear auto-dial (then attach() a stream yourself). */
+    autoSwarm?: boolean;
+    /**
+     * Send events to a local GUI over WebSocket instead of the Hyperswarm hub — the reliable
+     * dev-viewer path for EVERY runtime (RN / Pear / desktop / browser),
+     * e.g. 'ws://127.0.0.1:9420/ws'. When set, redaction defaults OFF (local viewing);
+     * pass redact:true to force it. Takes precedence over stream/auto-swarm.
+     */
+    websocket?: string;
+    /**
+     * Redact every event on the way OUT (peer ids hashed, URLs host-only, bodies off)
+     * — ON by default, because the export path (hub / .p2plog) leaves the device.
+     * Set false ONLY for a purely-local view that never leaves the machine (F3/F4/F9).
+     */
+    redact?: boolean;
+    /** Supply a shared Redactor (e.g. to reuse its local peer reverse-map). Default: a fresh one. */
+    redactor?: Redactor;
+    /** Per-`method` opt-in allowlist for full payload bodies (default: none — bodies summarised). */
+    bodyAllowlist?: Iterable<string>;
+    /**
+     * Identity of THIS device/app, for the GUI's device & app selectors. A string label, or an
+     * object `{ id?, label?, deviceId?, appId?, app?, device?, variant? }`.
+     *   • deviceId — physical device (client-supplied; e.g. the app's own options.deviceId) → select by device
+     *   • appId    — app/install instance → distinguishes MULTIPLE apps sharing one package
+     * Omit → auto: browser reuses localStorage for a stable id (clears on delete-data); other
+     * runtimes get a session id (pass deviceId/appId for stability). Only the client knows its
+     * app name / device / variant, so it supplies those.
+     */
+    source?: string | Record<string, unknown>;
+    /**
+     * Allow the GUI to REPLAY a logged call back into this client (re-run a call the app already
+     * made). Boundary: the GUI references a call by corrId and the METHOD is resolved from this
+     * client's own call log — it never crosses the wire, so a replay cannot be redirected to a
+     * method the app never called. The ARGS may be supplied by the GUI (edit-and-replay) and are
+     * NOT validated here beyond "must be a JSON array"; use `canReplay` to check them.
+     *
+     * Fails CLOSED: must be set to `true` EXPLICITLY. There is no dev-detection default — omit it
+     * and replay is off, so a shipped build never installs the inbound handler. Only meaningful
+     * together with `websocket`.
+     */
+    allowInvoke?: boolean;
+    /**
+     * Optional gate consulted before a replay runs — return false to block (e.g. to refuse
+     * re-running a mutating method like a send). Default: allow. Receives the logged method and the
+     * args that will actually be used — which may be UNVALIDATED, GUI-supplied args. This is the
+     * only argument check in the system, so an app whose methods mutate state should implement it.
+     */
+    canReplay?: (method: string, args: unknown[]) => boolean;
+    /** Max logged calls retained for replay (corrId→method+args). Default 500. */
+    replayLogMax?: number;
+}
+export interface ObserveHandle {
+    /** Wire your L1 adapters into this: `instrumentDataChannel(dc, peerId, obs.sink)`. */
+    sink: EventSink;
+    flusher: BatchFlusher<L2Event>;
+    runtime: Runtime;
+    mode: 'websocket' | 'stream' | 'custom' | 'buffering';
+    /** The redactor applied on export (null if redact:false). Use `.resolvePeer()` for a local names view. */
+    redactor: Redactor | null;
+    /** This device/app's resolved identity — stamped on every event as `src` and announced to the GUI. */
+    source: SourceInfo;
+    /** Report one event directly to the sink (this is what wrapClient uses). */
+    report: Report;
+    /** Wrap an RPC/service client so its calls + subscription streams are observed. */
+    wrapClient<T extends Record<string, any>>(client: T, opts?: WrapClientOptions): T;
+    /**
+     * Snapshot of request/response calls currently in flight — started (request.start) but not yet
+     * settled (request.end). Each `{ method, corrId, t }`. Subscription streams are not included (see
+     * observe.ts). Wire this to a thread-occupancy probe's `getInflight` so a stall names the call
+     * that was running (e.g. hrpc-inspector-threads).
+     */
+    inflight(): Array<{
+        method: string;
+        corrId: string;
+        t: number;
+    }>;
+    /**
+     * Bridge a hypertrace tracer into the SAME event stream: pass hypertrace's `setTraceFunction`
+     * and every `trace()` from instrumented classes (e.g. a WebRTC/call layer) becomes a
+     * `type:'trace'` event on a distinct "trace" plane in the GUI. Install this BEFORE the traced
+     * objects are constructed (hypertrace only traces objects created after the function is set).
+     * Dependency-free: the app supplies `setTraceFunction`, so the package never imports hypertrace.
+     * Returns a disposer that stops forwarding.
+     */
+    bridgeTraces(setTraceFunction: (fn: (trace: any) => void) => void): () => void;
+    /** Attach a hub connection later (auto-swarm calls this on 'connection'). */
+    attach(stream: WritableStreamLike): void;
+    stop(): void;
+}
+export declare function observe(opts?: ObserveOptions): ObserveHandle;