hrpc-inspector 0.1.1 → 0.1.3

package/dist/index.js

@@ -28,9 +28,12 @@ function createWebSocketReporter(url, opts = {}) {
   const maxQueue = opts.maxQueue ?? 1e3;
   const reconnectMs = opts.reconnectMs ?? 3e3;
   const OPEN = 1;
+  const maxReconnectMs = opts.maxReconnectMs ?? 3e4;
   let ws = null;
   let queue = [];
   let closed = false;
+  let retryTimer = null;
+  let backoffMs = reconnectMs;
   function enqueue(ev) {
     queue.push(ev);
     if (queue.length > maxQueue) queue.shift();
@@ -42,12 +45,23 @@ function createWebSocketReporter(url, opts = {}) {
       enqueue(ev);
     }
   }
+  function scheduleRetry() {
+    if (closed || retryTimer) return;
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      ensure();
+    }, backoffMs);
+    backoffMs = Math.min(backoffMs * 2, maxReconnectMs);
+    if (typeof retryTimer?.unref === "function") retryTimer.unref();
+  }
   function ensure() {
     if (closed || !WS) return;
     if (ws && (ws.readyState === 0 || ws.readyState === 1)) return;
+    if (retryTimer) return;
     try {
       ws = new WS(url);
       ws.onopen = () => {
+        backoffMs = reconnectMs;
         if (opts.announce !== void 0) rawSend({ __source: opts.announce });
         const q = queue;
         queue = [];
@@ -55,7 +69,7 @@ function createWebSocketReporter(url, opts = {}) {
       };
       ws.onclose = () => {
         ws = null;
-        if (!closed) setTimeout(ensure, reconnectMs);
+        scheduleRetry();
       };
       ws.onerror = () => {
       };
@@ -67,6 +81,7 @@ function createWebSocketReporter(url, opts = {}) {
       };
     } catch {
       ws = null;
+      scheduleRetry();
     }
   }
   return {
@@ -80,6 +95,10 @@ function createWebSocketReporter(url, opts = {}) {
     },
     close() {
       closed = true;
+      if (retryTimer) {
+        clearTimeout(retryTimer);
+        retryTimer = null;
+      }
       try {
         ws?.close();
       } catch {
@@ -117,16 +136,27 @@ function monitorStream(report, endpoint, corrId, stream, t0, preview, tag) {
     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"));
+    const original = stream.emit;
+    if (typeof original !== "function") return;
+    stream.emit = function patched(name, ...args) {
+      try {
+        if (name === "data") {
+          report({ type: "stream.data", method: endpoint, corrId, seq: ++n, item: preview(args[0]), t: Date.now(), ...tag });
+        } else if (name === "error") {
+          settle("error", { error: String(args[0]) });
+        } else if (name === "end" || name === "close") {
+          settle("closed");
+        }
+      } catch {
+      }
+      return original.apply(this, [name, ...args]);
+    };
   } 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 wrapped = function observed(...args) {
     const corrId = "rpc-" + ++seq;
     let tag = {};
     if (invokeCtx && invokeCtx.method === endpoint) {
@@ -160,6 +190,12 @@ function wrapFn(report, endpoint, fn, self, preview, monitorStreams, onCall) {
     }
     return result;
   };
+  try {
+    Object.defineProperty(wrapped, "name", { value: fn.name, configurable: true });
+    Object.defineProperty(wrapped, "length", { value: fn.length, configurable: true });
+  } catch {
+  }
+  return wrapped;
 }
 function wrapClient(client, report, opts = {}) {
   if (!client || typeof client !== "object") return client;
@@ -257,6 +293,8 @@ function observe(opts = {}) {
   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 redactMethods = new Set(opts.redactMethods ?? []);
+  const methodRedactor = !redactor && redactMethods.size > 0 ? new Redactor() : null;
   const wireSource = redactor ? redactSource(source, redactor) : source;
   const invokeEnabled = opts.allowInvoke === true && !!opts.websocket;
   const replayLogMax = opts.replayLogMax ?? 2e3;
@@ -296,7 +334,9 @@ function observe(opts = {}) {
   const flusher = new BatchFlusher({
     intervalMs: opts.intervalMs ?? 200,
     onFlush: (batch) => {
-      const out = redactor ? redactor.redactBatch(batch) : batch;
+      const out = redactor ? redactor.redactBatch(batch) : methodRedactor ? batch.map(
+        (e) => redactMethods.has(String(e.method)) ? methodRedactor.redact(e) : e
+      ) : batch;
       exporter.export(out.map((e) => ({ ...e, src: wireSource.id })));
     }
   });

package/dist/observe.d.ts

@@ -42,6 +42,15 @@ export interface ObserveOptions {
      * Set false ONLY for a purely-local view that never leaves the machine (F3/F4/F9).
      */
     redact?: boolean;
+    /**
+     * Per-`method` FORCED redaction, for when global `redact` is off (the local viewer default).
+     * A listed method still appears in the GUI — you see it fired, when, how long it took, whether
+     * it errored, and the SHAPE of its payload (`{phrase: 'string'}`) — but its values are replaced
+     * by a content summary. Use it for methods that carry secrets you never want rendered, e.g.
+     * a recovery phrase. This is a denylist: a newly added secret-bearing method must be listed.
+     * Ignored when `redact` is on, because everything is redacted already.
+     */
+    redactMethods?: Iterable<string>;
     /** 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). */

package/dist/observe.js

@@ -28,9 +28,12 @@ function createWebSocketReporter(url, opts = {}) {
   const maxQueue = opts.maxQueue ?? 1e3;
   const reconnectMs = opts.reconnectMs ?? 3e3;
   const OPEN = 1;
+  const maxReconnectMs = opts.maxReconnectMs ?? 3e4;
   let ws = null;
   let queue = [];
   let closed = false;
+  let retryTimer = null;
+  let backoffMs = reconnectMs;
   function enqueue(ev) {
     queue.push(ev);
     if (queue.length > maxQueue) queue.shift();
@@ -42,12 +45,23 @@ function createWebSocketReporter(url, opts = {}) {
       enqueue(ev);
     }
   }
+  function scheduleRetry() {
+    if (closed || retryTimer) return;
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      ensure();
+    }, backoffMs);
+    backoffMs = Math.min(backoffMs * 2, maxReconnectMs);
+    if (typeof retryTimer?.unref === "function") retryTimer.unref();
+  }
   function ensure() {
     if (closed || !WS) return;
     if (ws && (ws.readyState === 0 || ws.readyState === 1)) return;
+    if (retryTimer) return;
     try {
       ws = new WS(url);
       ws.onopen = () => {
+        backoffMs = reconnectMs;
         if (opts.announce !== void 0) rawSend({ __source: opts.announce });
         const q = queue;
         queue = [];
@@ -55,7 +69,7 @@ function createWebSocketReporter(url, opts = {}) {
       };
       ws.onclose = () => {
         ws = null;
-        if (!closed) setTimeout(ensure, reconnectMs);
+        scheduleRetry();
       };
       ws.onerror = () => {
       };
@@ -67,6 +81,7 @@ function createWebSocketReporter(url, opts = {}) {
       };
     } catch {
       ws = null;
+      scheduleRetry();
     }
   }
   return {
@@ -80,6 +95,10 @@ function createWebSocketReporter(url, opts = {}) {
     },
     close() {
       closed = true;
+      if (retryTimer) {
+        clearTimeout(retryTimer);
+        retryTimer = null;
+      }
       try {
         ws?.close();
       } catch {
@@ -117,16 +136,27 @@ function monitorStream(report, endpoint, corrId, stream, t0, preview, tag) {
     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"));
+    const original = stream.emit;
+    if (typeof original !== "function") return;
+    stream.emit = function patched(name, ...args) {
+      try {
+        if (name === "data") {
+          report({ type: "stream.data", method: endpoint, corrId, seq: ++n, item: preview(args[0]), t: Date.now(), ...tag });
+        } else if (name === "error") {
+          settle("error", { error: String(args[0]) });
+        } else if (name === "end" || name === "close") {
+          settle("closed");
+        }
+      } catch {
+      }
+      return original.apply(this, [name, ...args]);
+    };
   } 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 wrapped = function observed(...args) {
     const corrId = "rpc-" + ++seq;
     let tag = {};
     if (invokeCtx && invokeCtx.method === endpoint) {
@@ -160,6 +190,12 @@ function wrapFn(report, endpoint, fn, self, preview, monitorStreams, onCall) {
     }
     return result;
   };
+  try {
+    Object.defineProperty(wrapped, "name", { value: fn.name, configurable: true });
+    Object.defineProperty(wrapped, "length", { value: fn.length, configurable: true });
+  } catch {
+  }
+  return wrapped;
 }
 function wrapClient(client, report, opts = {}) {
   if (!client || typeof client !== "object") return client;
@@ -257,6 +293,8 @@ function observe(opts = {}) {
   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 redactMethods = new Set(opts.redactMethods ?? []);
+  const methodRedactor = !redactor && redactMethods.size > 0 ? new Redactor() : null;
   const wireSource = redactor ? redactSource(source, redactor) : source;
   const invokeEnabled = opts.allowInvoke === true && !!opts.websocket;
   const replayLogMax = opts.replayLogMax ?? 2e3;
@@ -296,7 +334,9 @@ function observe(opts = {}) {
   const flusher = new BatchFlusher({
     intervalMs: opts.intervalMs ?? 200,
     onFlush: (batch) => {
-      const out = redactor ? redactor.redactBatch(batch) : batch;
+      const out = redactor ? redactor.redactBatch(batch) : methodRedactor ? batch.map(
+        (e) => redactMethods.has(String(e.method)) ? methodRedactor.redact(e) : e
+      ) : batch;
       exporter.export(out.map((e) => ({ ...e, src: wireSource.id })));
     }
   });

package/dist/reporters.d.ts

@@ -17,6 +17,8 @@ export interface WebSocketReporterOptions {
      * replay/invoke path); leaving it undefined keeps the reporter strictly send-only, as before.
      */
     onMessage?: (msg: any) => void;
+    /** Ceiling for the reconnect backoff, in ms. Default 30000. */
+    maxReconnectMs?: number;
 }
 /**
  * Send each event as one JSON WebSocket message to `url` (e.g. ws://127.0.0.1:9420/ws).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hrpc-inspector",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "hrpc based debugging and observability for Bare. Tap an RPC client or a raw transport and read endpoint, request, response, latency and live subscription streams in a local GUI, or merge multi-peer timelines over a Hyperswarm hub.",
   "type": "module",
   "main": "./dist/index.js",
@@ -63,6 +63,7 @@
   },
   "devDependencies": {
     "esbuild": "^0.28.2",
+    "streamx": "^2.28.1",
     "typescript": "^7.0.2"
   }
 }

package/src/observe.ts

@@ -128,6 +128,15 @@ export interface ObserveOptions {
    * Set false ONLY for a purely-local view that never leaves the machine (F3/F4/F9).
    */
   redact?: boolean;
+  /**
+   * Per-`method` FORCED redaction, for when global `redact` is off (the local viewer default).
+   * A listed method still appears in the GUI — you see it fired, when, how long it took, whether
+   * it errored, and the SHAPE of its payload (`{phrase: 'string'}`) — but its values are replaced
+   * by a content summary. Use it for methods that carry secrets you never want rendered, e.g.
+   * a recovery phrase. This is a denylist: a newly added secret-bearing method must be listed.
+   * Ignored when `redact` is on, because everything is redacted already.
+   */
+  redactMethods?: Iterable<string>;
   /** 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). */
@@ -249,6 +258,10 @@ export function observe(opts: ObserveOptions = {}): ObserveHandle {
   const redactOn = opts.redact ?? (opts.websocket ? false : true);
   const redactor: Redactor | null =
     opts.redactor ?? (redactOn ? new Redactor({ bodyAllowlist: opts.bodyAllowlist }) : null);
+  // Only meaningful while global redaction is off; when it is on these methods are covered anyway.
+  const redactMethods = new Set(opts.redactMethods ?? []);
+  const methodRedactor: Redactor | null =
+    !redactor && redactMethods.size > 0 ? new Redactor() : null;
   // Identity ON THE WIRE — hashed ids / no human labels when redaction is on. `handle.source`
   // keeps the original for the app's own use.
   const wireSource = redactor ? redactSource(source, redactor) : source;
@@ -306,7 +319,15 @@ export function observe(opts: ObserveOptions = {}): ObserveHandle {
   const flusher = new BatchFlusher<L2Event>({
     intervalMs: opts.intervalMs ?? 200,
     onFlush: (batch) => {
-      const out = redactor ? redactor.redactBatch(batch) : batch;
+      const out = redactor
+        ? redactor.redactBatch(batch)
+        : methodRedactor
+          ? batch.map((e) =>
+              redactMethods.has(String((e as Record<string, unknown>).method))
+                ? (methodRedactor.redact(e as Record<string, unknown>) as L2Event)
+                : e,
+            )
+          : batch;
       // Stamp the (wire) source id so the GUI can group/select by device.
       exporter.export(out.map((e) => ({ ...(e as object), src: wireSource.id })));
     },

package/src/reporters.ts

@@ -25,6 +25,8 @@ export interface WebSocketReporterOptions {
    * replay/invoke path); leaving it undefined keeps the reporter strictly send-only, as before.
    */
   onMessage?: (msg: any) => void;
+  /** Ceiling for the reconnect backoff, in ms. Default 30000. */
+  maxReconnectMs?: number;
 }
 
 /**
@@ -37,9 +39,17 @@ export function createWebSocketReporter(url: string, opts: WebSocketReporterOpti
   const reconnectMs = opts.reconnectMs ?? 3000;
   const OPEN = 1;
 
+  const maxReconnectMs = opts.maxReconnectMs ?? 30000;
+
   let ws: any = null;
   let queue: unknown[] = [];
   let closed = false;
+  // A reconnect already scheduled. Without this, export() — which runs on every flush, i.e. every
+  // ~200ms — would open a fresh socket the moment the previous one failed, defeating the backoff
+  // entirely. A browser logs EVERY refused WebSocket connect to the console itself, before any
+  // onerror handler runs, so that turned "no GUI running" into a console flooded at 5 errors/sec.
+  let retryTimer: any = null;
+  let backoffMs = reconnectMs;
 
   function enqueue(ev: unknown) {
     queue.push(ev);
@@ -48,21 +58,33 @@ export function createWebSocketReporter(url: string, opts: WebSocketReporterOpti
   function rawSend(ev: unknown) {
     try { ws.send(JSON.stringify(ev)); } catch { enqueue(ev); }
   }
+  function scheduleRetry() {
+    if (closed || retryTimer) return;
+    retryTimer = setTimeout(() => { retryTimer = null; ensure(); }, backoffMs);
+    // Widen the gap each time the viewer stays absent, so a dev session with no GUI settles at one
+    // attempt per maxReconnectMs instead of one per flush. Reset to `reconnectMs` on a real open.
+    backoffMs = Math.min(backoffMs * 2, maxReconnectMs);
+    if (typeof retryTimer?.unref === 'function') retryTimer.unref();
+  }
+
   function ensure() {
     if (closed || !WS) return;
     if (ws && (ws.readyState === 0 || ws.readyState === 1)) return;
+    if (retryTimer) return; // a reconnect is already pending — do not stack another socket on top
     try {
       ws = new WS(url);
       ws.onopen = () => {
+        backoffMs = reconnectMs; // the viewer is back; retry promptly if it goes away again
         if (opts.announce !== undefined) rawSend({ __source: opts.announce }); // identify this device first
         const q = queue; queue = []; for (const e of q) rawSend(e);
       };
-      ws.onclose = () => { ws = null; if (!closed) setTimeout(ensure, reconnectMs); };
+      ws.onclose = () => { ws = null; scheduleRetry(); };
       ws.onerror = () => {};
       // Bidirectional only when a handler was supplied (dev/replay path). Never throws inward.
       if (opts.onMessage) ws.onmessage = (m: any) => { try { opts.onMessage!(JSON.parse(m.data)); } catch { /* ignore malformed inbound */ } };
     } catch {
       ws = null;
+      scheduleRetry();
     }
   }
 
@@ -77,6 +99,7 @@ export function createWebSocketReporter(url: string, opts: WebSocketReporterOpti
     },
     close() {
       closed = true;
+      if (retryTimer) { clearTimeout(retryTimer); retryTimer = null; }
       try { ws?.close(); } catch {}
       ws = null;
     },

package/src/wrap-client.ts

@@ -57,10 +57,16 @@ function defaultPreview(v: unknown): unknown {
   }
 }
 
-// Attach PASSIVE listeners to a subscription stream. Non-destructive when the app also uses
-// `.on('data')` (every listener receives each item). If a consumer instead uses `.read()` /
-// async-iteration, adding a data listener flips it to flowing mode — opt out with
-// monitorStreams:false for those.
+// Observe a subscription stream WITHOUT changing its behaviour.
+//
+// This wraps `emit` instead of calling `.on('data', ...)`. Registering a data listener is not
+// passive: it puts the stream into flowing mode immediately, so anything emitted before the app
+// attaches its own listener is delivered to us and LOST to the app. That is a debug-only data
+// loss — the app silently misses items, with no error — and it is real: keet's RPC subscriptions
+// return their stream synchronously, while the consumer attaches a tick later.
+//
+// Wrapping `emit` cannot cause that: we only see events the stream was already delivering. If
+// nothing consumes the stream, nothing is emitted and we report nothing, which is the truth.
 function monitorStream(report: Report, endpoint: string, corrId: string, stream: any, t0: number, preview: (v: unknown) => unknown, tag: Record<string, unknown>): void {
   report({ type: 'stream.open', method: endpoint, corrId, t: Date.now(), ...tag });
   let n = 0;
@@ -71,17 +77,31 @@ function monitorStream(report: Report, endpoint: string, corrId: string, stream:
     report({ type: 'request.end', method: endpoint, corrId, status, count: n, dur: Date.now() - t0, t: Date.now(), ...tag, ...(extra || {}) });
   };
   try {
-    stream.on('data', (item: unknown) => report({ type: 'stream.data', method: endpoint, corrId, seq: ++n, item: preview(item), t: Date.now(), ...tag }));
-    stream.on('error', (err: unknown) => settle('error', { error: String(err) }));
-    stream.on('end', () => settle('closed'));
-    stream.on('close', () => settle('closed'));
+    const original = stream.emit;
+    if (typeof original !== 'function') return;
+    stream.emit = function patched(this: unknown, name: string, ...args: unknown[]): unknown {
+      // Observation must never affect delivery: record, then hand off unchanged. A throw in the
+      // reporting path would surface as a stream error in the app, so it is swallowed.
+      try {
+        if (name === 'data') {
+          report({ type: 'stream.data', method: endpoint, corrId, seq: ++n, item: preview(args[0]), t: Date.now(), ...tag });
+        } else if (name === 'error') {
+          settle('error', { error: String(args[0]) });
+        } else if (name === 'end' || name === 'close') {
+          settle('closed');
+        }
+      } catch {
+        /* never break the stream */
+      }
+      return original.apply(this, [name, ...args] as never);
+    };
   } 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: Report, endpoint: string, fn: any, self: any, preview: (v: unknown) => unknown, monitorStreams: boolean, onCall?: (corrId: string, method: string, args: unknown[]) => void): any {
-  return function observed(this: unknown, ...args: unknown[]) {
+  const wrapped = function observed(this: unknown, ...args: unknown[]) {
     const corrId = 'rpc-' + ++seq;
     // Consume the invoke tag ONCE, and only for the exact method being replayed.
     let tag: Record<string, unknown> = {};
@@ -111,6 +131,18 @@ function wrapFn(report: Report, endpoint: string, fn: any, self: any, preview: (
     }
     return result;
   };
+
+  // Carry the original identity across. An app may read `fn.name` — keet's own System Log does
+  // (`method: apiFn.name`), and every entry showed "observed" instead of the endpoint. `length`
+  // goes too, since arity is the other thing reflection commonly checks. Both are configurable
+  // on a function, so this cannot throw; guarded anyway, because the tap must never break a client.
+  try {
+    Object.defineProperty(wrapped, 'name', { value: fn.name, configurable: true });
+    Object.defineProperty(wrapped, 'length', { value: fn.length, configurable: true });
+  } catch {
+    /* identity is a nicety; never fail the wrap over it */
+  }
+  return wrapped;
 }
 
 /**