@serfab/cadre-core 0.6.0 → 0.8.1

package/src/diagnostics/connection-path.ts

@@ -0,0 +1,277 @@
+/**
+ * connection-path.ts — classify each open libp2p connection as relayed
+ * (`/p2p-circuit`) vs direct, tag its transport, and summarise counts plus a
+ * "stuck on relay" condition.
+ *
+ * This is the **canonical** implementation. The web reference app keeps a
+ * deliberate, documented duplicate at
+ * `packages/reference-app-web/src/lib/connection-path.ts` (it does not depend on
+ * `@serfab/cadre-core`). Keep the function signatures and classification table
+ * identical across both copies so a future shared micro-package would be a
+ * drop-in.
+ *
+ * The whole signal is a pure function over `node.getConnections()` + a settle
+ * window + `Date.now()`. A connection's path is derivable from its `remoteAddr`
+ * multiaddr string alone — no I/O, no events, no stateful observer.
+ */
+
+export type ConnectionPathKind = 'relayed' | 'direct';
+
+export type ConnectionTransport =
+  | 'circuit-relay'
+  | 'webrtc'
+  | 'webrtc-turn'   // WebRTC session whose ICE selected a TURN relay candidate
+  | 'webrtc-direct'
+  | 'websocket'
+  | 'tcp'
+  | 'unknown';
+
+export interface ConnectionPath {
+  /** remotePeer.toString() */
+  peerId: string;
+  remoteAddr: string;
+  kind: ConnectionPathKind;
+  transport: ConnectionTransport;
+  direction: 'inbound' | 'outbound';
+  /** connection.timeline.open ?? null */
+  openedAtMs: number | null;
+  /** now - openedAtMs */
+  ageMs: number | null;
+  /** relayed && age > settleWindow && no direct conn to same peer */
+  stuckOnRelay: boolean;
+}
+
+export interface ConnectionPathSummary {
+  total: number;
+  relayed: number;
+  direct: number;
+  stuckOnRelay: number;
+  byTransport: Record<ConnectionTransport, number>;
+  /** best-effort; null when libp2p exposes no byte counter (see classifier docs) */
+  bytesOverRelay: number | null;
+  paths: ConnectionPath[];
+  settleWindowMs: number;
+}
+
+/**
+ * The minimal connection shape the classifier needs. The stock libp2p
+ * `Connection` (from `@libp2p/interface`) satisfies this structurally, and
+ * tests can build small synthetic objects against it.
+ */
+export interface ConnectionLike {
+  remotePeer?: { toString(): string };
+  remoteAddr?: { toString(): string };
+  direction?: 'inbound' | 'outbound';
+  timeline?: { open?: number };
+  /**
+   * Set externally (by {@link CadreNode}, from a {@link TurnRelayTracker}
+   * observation) when ICE selected a TURN relay candidate for this `/webrtc`
+   * session. `undefined` = unknown (the multiaddr alone cannot reveal it). Only
+   * honoured for the `webrtc` transport — see {@link classifyConnectionPath}.
+   */
+  turnRelayed?: boolean;
+}
+
+export const DEFAULT_SETTLE_WINDOW_MS = 10_000;
+
+const ALL_TRANSPORTS: readonly ConnectionTransport[] = [
+  'circuit-relay',
+  'webrtc',
+  'webrtc-turn',
+  'webrtc-direct',
+  'websocket',
+  'tcp',
+  'unknown',
+];
+
+interface TransportClass {
+  kind: ConnectionPathKind;
+  transport: ConnectionTransport;
+}
+
+/**
+ * Classify a remote multiaddr string into a (kind, transport) pair. Order
+ * matters — first match wins:
+ *
+ * | multiaddr contains            | kind    | transport      |
+ * |-------------------------------|---------|----------------|
+ * | `/webrtc-direct`              | direct  | webrtc-direct  |
+ * | `/webrtc`                     | direct  | webrtc         |
+ * | `/p2p-circuit` (no webrtc)    | relayed | circuit-relay  |
+ * | `/ws` (or `/wss`)             | direct  | websocket      |
+ * | `/tcp` (and none of the above)| direct  | tcp            |
+ * | _none_                        | direct  | unknown        |
+ *
+ * Note the ordering: a browser-to-browser WebRTC connection is dialed *over* a
+ * relay for SDP signalling and js-libp2p keeps the circuit prefix in the
+ * connection's remoteAddr — a successful hole-punch reads as
+ * `…/p2p-circuit/webrtc/p2p/…`, i.e. it contains BOTH `/p2p-circuit` and
+ * `/webrtc`. Its data path is nevertheless **direct**, so the WebRTC checks
+ * must come *before* `/p2p-circuit`. Only a connection with no transport after
+ * `/p2p-circuit` (`…/p2p-circuit/p2p/…`) is genuinely relay-carried.
+ */
+export function classifyTransport(remoteAddr: string): TransportClass {
+  const addr = remoteAddr ?? '';
+  if (addr.includes('/webrtc-direct')) return { kind: 'direct', transport: 'webrtc-direct' };
+  if (addr.includes('/webrtc')) return { kind: 'direct', transport: 'webrtc' };
+  if (addr.includes('/p2p-circuit')) return { kind: 'relayed', transport: 'circuit-relay' };
+  if (addr.includes('/ws')) return { kind: 'direct', transport: 'websocket' };
+  if (addr.includes('/tcp')) return { kind: 'direct', transport: 'tcp' };
+  return { kind: 'direct', transport: 'unknown' };
+}
+
+/** Read a connection's remote address as a string, never throwing. */
+function addrString(conn: ConnectionLike): string {
+  try {
+    return conn.remoteAddr?.toString?.() ?? '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Per-connection classifier. Starts from the pure multiaddr classification, then
+ * applies the TURN override: a `/webrtc` session whose ICE selected a TURN relay
+ * candidate (`conn.turnRelayed === true`, set externally — the multiaddr alone
+ * cannot reveal it) is reclassified `relayed`/`webrtc-turn`. The
+ * `transport === 'webrtc'` guard means a `webrtc-direct` connection is never
+ * promoted (it uses no ICE and so can never be TURN-relayed), and `undefined`
+ * (unknown) degrades safely to the multiaddr result — not relayed.
+ */
+export function classifyConnectionPath(conn: ConnectionLike): TransportClass {
+  const { kind, transport } = classifyTransport(addrString(conn));
+  if (transport === 'webrtc' && conn.turnRelayed === true) {
+    return { kind: 'relayed', transport: 'webrtc-turn' };
+  }
+  return { kind, transport };
+}
+
+/**
+ * Best-effort per-connection byte counter. The stock libp2p `Connection`
+ * interface carries no byte counter, so unless a metrics implementation is
+ * wired into the node this returns `null`. Never throws.
+ */
+function readConnectionBytes(conn: ConnectionLike): number | null {
+  try {
+    const metrics = (conn as { metrics?: { bytesReceived?: number; bytesSent?: number } }).metrics;
+    if (!metrics) return null;
+    const received = typeof metrics.bytesReceived === 'number' ? metrics.bytesReceived : 0;
+    const sent = typeof metrics.bytesSent === 'number' ? metrics.bytesSent : 0;
+    const total = received + sent;
+    return Number.isFinite(total) ? total : null;
+  } catch {
+    return null;
+  }
+}
+
+function zeroByTransport(): Record<ConnectionTransport, number> {
+  const out = {} as Record<ConnectionTransport, number>;
+  for (const t of ALL_TRANSPORTS) out[t] = 0;
+  return out;
+}
+
+/** An all-zero summary, used when no node/connections are available. */
+export function emptyConnectionPathSummary(
+  settleWindowMs: number = DEFAULT_SETTLE_WINDOW_MS,
+): ConnectionPathSummary {
+  return {
+    total: 0,
+    relayed: 0,
+    direct: 0,
+    stuckOnRelay: 0,
+    byTransport: zeroByTransport(),
+    bytesOverRelay: null,
+    paths: [],
+    settleWindowMs,
+  };
+}
+
+/**
+ * Build a {@link ConnectionPathSummary} from the node's current connections.
+ *
+ * `stuckOnRelay` per connection is `relayed && ageMs != null && ageMs >
+ * settleWindowMs && no direct connection to the same peer` — the relay-only
+ * silent-failure condition (WebRTC negotiation failed, the connection quietly
+ * stays on the relay). The direct-peer set is the set of `peerId`s that have at
+ * least one `direct` connection, so a peer mid-upgrade (a relayed circuit conn
+ * *and* a direct webrtc conn at once) is correctly not flagged.
+ */
+export function summarizeConnectionPaths(
+  conns: Iterable<ConnectionLike> | null | undefined,
+  settleWindowMs: number = DEFAULT_SETTLE_WINDOW_MS,
+): ConnectionPathSummary {
+  const now = Date.now();
+  const list = conns ? Array.from(conns) : [];
+
+  // First pass: classify each connection and find the set of peers that have at
+  // least one direct connection.
+  const classified = list.map((conn) => {
+    const remoteAddr = addrString(conn);
+    // classifyConnectionPath (not classifyTransport) so the externally-set
+    // turnRelayed hint promotes webrtc → webrtc-turn (relayed).
+    const { kind, transport } = classifyConnectionPath(conn);
+    const openedAtMs = typeof conn.timeline?.open === 'number' ? conn.timeline.open : null;
+    const ageMs = openedAtMs != null ? Math.max(0, now - openedAtMs) : null;
+    const peerId = safePeerId(conn);
+    const direction: 'inbound' | 'outbound' = conn.direction === 'inbound' ? 'inbound' : 'outbound';
+    return { conn, peerId, remoteAddr, kind, transport, openedAtMs, ageMs, direction };
+  });
+
+  const directPeerSet = new Set(
+    classified.filter((c) => c.kind === 'direct').map((c) => c.peerId),
+  );
+
+  const byTransport = zeroByTransport();
+  let relayed = 0;
+  let direct = 0;
+  let stuckCount = 0;
+  let bytesOverRelay: number | null = null;
+
+  const paths: ConnectionPath[] = classified.map((c) => {
+    byTransport[c.transport] += 1;
+    if (c.kind === 'relayed') {
+      relayed += 1;
+      const bytes = readConnectionBytes(c.conn);
+      if (bytes != null) bytesOverRelay = (bytesOverRelay ?? 0) + bytes;
+    } else {
+      direct += 1;
+    }
+
+    const stuckOnRelay =
+      c.kind === 'relayed' &&
+      c.ageMs != null &&
+      c.ageMs > settleWindowMs &&
+      !directPeerSet.has(c.peerId);
+    if (stuckOnRelay) stuckCount += 1;
+
+    return {
+      peerId: c.peerId,
+      remoteAddr: c.remoteAddr,
+      kind: c.kind,
+      transport: c.transport,
+      direction: c.direction,
+      openedAtMs: c.openedAtMs,
+      ageMs: c.ageMs,
+      stuckOnRelay,
+    };
+  });
+
+  return {
+    total: list.length,
+    relayed,
+    direct,
+    stuckOnRelay: stuckCount,
+    byTransport,
+    bytesOverRelay,
+    paths,
+    settleWindowMs,
+  };
+}
+
+function safePeerId(conn: ConnectionLike): string {
+  try {
+    return conn.remotePeer?.toString?.() ?? '';
+  } catch {
+    return '';
+  }
+}

package/src/diagnostics/webrtc-turn-tracker.ts

@@ -0,0 +1,222 @@
+/**
+ * webrtc-turn-tracker.ts — observe whether ICE selected a TURN relay candidate
+ * for each WebRTC session, so a TURN-relayed `/webrtc` connection can be
+ * reclassified `relayed`/`webrtc-turn` instead of silently counted `direct`.
+ *
+ * `@libp2p/webrtc` keeps the underlying `RTCPeerConnection` private and never
+ * surfaces it on the libp2p `Connection`, so the multiaddr classifier
+ * (`connection-path.ts`) cannot see the ICE candidate types. This tracker hooks
+ * `globalThis.RTCPeerConnection` at install time: every connection that reaches
+ * `connectionState === 'connected'` is inspected via `getStats()`, and the
+ * relay/not-relay verdict for the selected candidate pair is pushed onto a FIFO
+ * queue. {@link CadreNode} drains that queue on each `connection:open` to tag the
+ * matching peer (see {@link consume}).
+ *
+ * The correlation between a queued settlement and a `connection:open` is
+ * timing-based and best-effort — it degrades gracefully (unknown → treated as not
+ * relayed, a safe default that never produces a false `relayed`). It is inert on
+ * Node.js / any runtime with no `RTCPeerConnection`.
+ */
+
+import debug from 'debug';
+
+const log = debug('sereus:cadre:turn-tracker');
+
+/** A single observed WebRTC settlement: when it connected and whether ICE relayed. */
+interface SettlementEntry {
+  settledAtMs: number;
+  isRelay: boolean;
+}
+
+/**
+ * Hard cap on the FIFO queue. In steady state every settlement is consumed by a
+ * `connection:open`, so the queue stays tiny; the cap only bounds a pathological
+ * leak (settlements that never get a matching consume).
+ */
+const MAX_QUEUE = 64;
+
+export class TurnRelayTracker {
+  private readonly queue: SettlementEntry[] = [];
+  private OriginalRTCPeerConnection: typeof RTCPeerConnection | undefined;
+  /** One settlement record per connection; guards against repeated `connected` events. */
+  private readonly observed = new WeakSet<RTCPeerConnection>();
+
+  /**
+   * Wrap `globalThis.RTCPeerConnection` with a subclass that records each
+   * connection's TURN-relay verdict when it settles. Idempotent. A NOP when no
+   * `RTCPeerConnection` exists (Node.js / no WebRTC polyfill) — the tracker stays
+   * inert and {@link consume} always returns `null`.
+   */
+  install(): void {
+    if (this.OriginalRTCPeerConnection) {
+      return; // already installed
+    }
+    const Original = globalThis.RTCPeerConnection;
+    if (typeof Original !== 'function') {
+      log('install: no globalThis.RTCPeerConnection — tracker inert (Node.js / no polyfill)');
+      return;
+    }
+    this.OriginalRTCPeerConnection = Original;
+
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const tracker = this;
+    class TrackedRTCPeerConnection extends Original {
+      constructor(...args: ConstructorParameters<typeof RTCPeerConnection>) {
+        super(...args);
+        try {
+          this.addEventListener('connectionstatechange', () => {
+            try {
+              if (this.connectionState === 'connected' && !tracker.observed.has(this)) {
+                tracker.observed.add(this);
+                void tracker.recordSettlement(this);
+              }
+            } catch (error) {
+              log('connectionstatechange handler failed: %o', error);
+            }
+          });
+        } catch (error) {
+          log('install: failed to attach connectionstatechange listener: %o', error);
+        }
+      }
+    }
+
+    globalThis.RTCPeerConnection = TrackedRTCPeerConnection as typeof RTCPeerConnection;
+    log('install: wrapped globalThis.RTCPeerConnection');
+  }
+
+  /**
+   * Pop the most recent settled entry within `windowMs` ms of now, returning its
+   * relay verdict (`true`/`false`); `null` when the queue has no matching entry.
+   * Also prunes entries older than the window (they can never match a later
+   * consume). Synchronous and safe to call from a `connection:open` handler.
+   */
+  consume(windowMs: number): boolean | null {
+    const now = Date.now();
+    let result: boolean | null = null;
+    // Walk newest → oldest; the most recent in-window settlement is the best
+    // correlation for a just-opened connection.
+    for (let i = this.queue.length - 1; i >= 0; i--) {
+      if (now - this.queue[i]!.settledAtMs <= windowMs) {
+        result = this.queue[i]!.isRelay;
+        this.queue.splice(i, 1);
+        break;
+      }
+    }
+    this.pruneOlderThan(now - windowMs);
+    return result;
+  }
+
+  /** Restore the original `RTCPeerConnection` and clear the queue. Idempotent. */
+  dispose(): void {
+    if (this.OriginalRTCPeerConnection) {
+      globalThis.RTCPeerConnection = this.OriginalRTCPeerConnection;
+      this.OriginalRTCPeerConnection = undefined;
+    }
+    this.queue.length = 0;
+  }
+
+  /**
+   * Inspect a settled connection's stats and queue its TURN-relay verdict. Any
+   * failure (stats API absent, rejected promise, malformed report) is caught and
+   * recorded as `isRelay: false` — the safe default (unknown → not relayed) keeps
+   * the connection counted rather than dropping it.
+   */
+  private async recordSettlement(pc: RTCPeerConnection): Promise<void> {
+    // Defaults to not-relayed (the safe "unknown" verdict); only the success path
+    // below overrides it, so a getStats failure leaves it false.
+    let isRelay = false;
+    try {
+      const report = await pc.getStats();
+      isRelay = selectedCandidatePairIsRelay(statsToMap(report));
+    } catch (error) {
+      log('recordSettlement: getStats failed, keeping not-relayed default: %o', error);
+    }
+    this.queue.push({ settledAtMs: Date.now(), isRelay });
+    if (this.queue.length > MAX_QUEUE) {
+      this.queue.shift();
+    }
+  }
+
+  /** Drop queued entries settled before `cutoffMs` (the queue is in push order). */
+  private pruneOlderThan(cutoffMs: number): void {
+    while (this.queue.length > 0 && this.queue[0]!.settledAtMs < cutoffMs) {
+      this.queue.shift();
+    }
+  }
+}
+
+/** Materialise an `RTCStatsReport` into a plain map keyed by stats id. */
+function statsToMap(report: RTCStatsReport): Map<string, RTCStats> {
+  const map = new Map<string, RTCStats>();
+  report.forEach((value: RTCStats, key: string) => {
+    map.set(key, value);
+  });
+  return map;
+}
+
+/**
+ * Whether the selected ICE candidate pair used a TURN relay candidate on either
+ * end. The pair is the transport's `selectedCandidatePairId` when present, else
+ * the nominated succeeded pair, else any succeeded pair.
+ */
+function selectedCandidatePairIsRelay(stats: Map<string, RTCStats>): boolean {
+  const pair = findSelectedPair(stats);
+  if (!pair) {
+    return false;
+  }
+  const local = pair.localCandidateId ? stats.get(pair.localCandidateId) : undefined;
+  const remote = pair.remoteCandidateId ? stats.get(pair.remoteCandidateId) : undefined;
+  return isRelayCandidate(local) || isRelayCandidate(remote);
+}
+
+/**
+ * Minimal shape of a local/remote ICE candidate stats entry. Declared locally
+ * rather than relying on a DOM `RTCIceCandidateStats` lib type (absent in some
+ * TS lib versions); only `candidateType` is read.
+ */
+interface IceCandidateStats extends RTCStats {
+  candidateType?: string;
+}
+
+function isRelayCandidate(stat: RTCStats | undefined): boolean {
+  return stat?.type === 'local-candidate' || stat?.type === 'remote-candidate'
+    ? (stat as IceCandidateStats).candidateType === 'relay'
+    : false;
+}
+
+function findSelectedPair(stats: Map<string, RTCStats>): RTCIceCandidatePairStats | undefined {
+  const selectedId = selectedPairIdFromTransport(stats);
+  if (selectedId) {
+    const stat = stats.get(selectedId);
+    if (stat?.type === 'candidate-pair') {
+      return stat as RTCIceCandidatePairStats;
+    }
+  }
+  let succeeded: RTCIceCandidatePairStats | undefined;
+  for (const stat of stats.values()) {
+    if (stat.type !== 'candidate-pair') {
+      continue;
+    }
+    const pair = stat as RTCIceCandidatePairStats;
+    if (pair.state !== 'succeeded') {
+      continue;
+    }
+    if (pair.nominated) {
+      return pair; // nominated succeeded pair wins outright
+    }
+    succeeded ??= pair;
+  }
+  return succeeded;
+}
+
+function selectedPairIdFromTransport(stats: Map<string, RTCStats>): string | undefined {
+  for (const stat of stats.values()) {
+    if (stat.type === 'transport') {
+      const id = (stat as RTCTransportStats).selectedCandidatePairId;
+      if (typeof id === 'string') {
+        return id;
+      }
+    }
+  }
+  return undefined;
+}