@serfab/cadre-core 1.9.0 → 1.11.0

package/dist/diagnostics/webrtc-turn-tracker.d.ts

@@ -1,50 +0,0 @@
-/**
- * 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`.
- */
-export declare class TurnRelayTracker {
-    private readonly queue;
-    private OriginalRTCPeerConnection;
-    /** One settlement record per connection; guards against repeated `connected` events. */
-    private readonly observed;
-    /**
-     * 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;
-    /**
-     * 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;
-    /** Restore the original `RTCPeerConnection` and clear the queue. Idempotent. */
-    dispose(): void;
-    /**
-     * 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 recordSettlement;
-    /** Drop queued entries settled before `cutoffMs` (the queue is in push order). */
-    private pruneOlderThan;
-}

package/dist/diagnostics/webrtc-turn-tracker.js

@@ -1,196 +0,0 @@
-/**
- * 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');
-/**
- * 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 {
-    constructor() {
-        this.queue = [];
-        /** One settlement record per connection; guards against repeated `connected` events. */
-        this.observed = new WeakSet();
-    }
-    /**
-     * 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() {
-        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) {
-                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;
-        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) {
-        const now = Date.now();
-        let result = 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() {
-        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.
-     */
-    async recordSettlement(pc) {
-        // 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). */
-    pruneOlderThan(cutoffMs) {
-        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) {
-    const map = new Map();
-    report.forEach((value, key) => {
-        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) {
-    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);
-}
-function isRelayCandidate(stat) {
-    return stat?.type === 'local-candidate' || stat?.type === 'remote-candidate'
-        ? stat.candidateType === 'relay'
-        : false;
-}
-function findSelectedPair(stats) {
-    const selectedId = selectedPairIdFromTransport(stats);
-    if (selectedId) {
-        const stat = stats.get(selectedId);
-        if (stat?.type === 'candidate-pair') {
-            return stat;
-        }
-    }
-    let succeeded;
-    for (const stat of stats.values()) {
-        if (stat.type !== 'candidate-pair') {
-            continue;
-        }
-        const pair = stat;
-        if (pair.state !== 'succeeded') {
-            continue;
-        }
-        if (pair.nominated) {
-            return pair; // nominated succeeded pair wins outright
-        }
-        succeeded ?? (succeeded = pair);
-    }
-    return succeeded;
-}
-function selectedPairIdFromTransport(stats) {
-    for (const stat of stats.values()) {
-        if (stat.type === 'transport') {
-            const id = stat.selectedCandidatePairId;
-            if (typeof id === 'string') {
-                return id;
-            }
-        }
-    }
-    return undefined;
-}
-//# sourceMappingURL=webrtc-turn-tracker.js.map

package/dist/diagnostics/webrtc-turn-tracker.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"webrtc-turn-tracker.js","sourceRoot":"","sources":["../../src/diagnostics/webrtc-turn-tracker.ts"],"names":[],"mappings":"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"}

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

@@ -1,222 +0,0 @@
-/**
- * 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;
-}