@antseed/node 0.1.0

package/src/discovery/dht-health.ts

@@ -0,0 +1,136 @@
+export interface DHTHealthSnapshot {
+  nodeCount: number;
+  totalLookups: number;
+  successfulLookups: number;
+  failedLookups: number;
+  totalAnnounces: number;
+  successfulAnnounces: number;
+  failedAnnounces: number;
+  averageLookupLatencyMs: number;
+  isHealthy: boolean;
+}
+
+export interface HealthThresholds {
+  minNodeCount: number;
+  minLookupSuccessRate: number;
+  maxAvgLookupLatencyMs: number;
+}
+
+export const DEFAULT_HEALTH_THRESHOLDS: HealthThresholds = {
+  minNodeCount: 5,
+  minLookupSuccessRate: 0.3,
+  maxAvgLookupLatencyMs: 15000,
+};
+
+export class DHTHealthMonitor {
+  private readonly thresholds: HealthThresholds;
+  private readonly getNodeCount: () => number;
+  private _totalLookups = 0;
+  private _successfulLookups = 0;
+  private _failedLookups = 0;
+  private _totalAnnounces = 0;
+  private _successfulAnnounces = 0;
+  private _failedAnnounces = 0;
+  private readonly latencySamples: number[] = [];
+  private static readonly MAX_LATENCY_SAMPLES = 100;
+
+  constructor(
+    getNodeCount: () => number,
+    thresholds: HealthThresholds = DEFAULT_HEALTH_THRESHOLDS
+  ) {
+    this.getNodeCount = getNodeCount;
+    this.thresholds = thresholds;
+  }
+
+  recordLookup(success: boolean, latencyMs: number): void {
+    this._totalLookups++;
+    if (success) {
+      this._successfulLookups++;
+    } else {
+      this._failedLookups++;
+    }
+
+    this.latencySamples.push(latencyMs);
+    if (this.latencySamples.length > DHTHealthMonitor.MAX_LATENCY_SAMPLES) {
+      this.latencySamples.shift();
+    }
+  }
+
+  recordAnnounce(success: boolean): void {
+    this._totalAnnounces++;
+    if (success) {
+      this._successfulAnnounces++;
+    } else {
+      this._failedAnnounces++;
+    }
+  }
+
+  getSnapshot(): DHTHealthSnapshot {
+    const nodeCount = this.getNodeCount();
+    const averageLookupLatencyMs = this.computeAverageLatency();
+    const healthy = this.evaluateHealth(nodeCount, averageLookupLatencyMs);
+
+    return {
+      nodeCount,
+      totalLookups: this._totalLookups,
+      successfulLookups: this._successfulLookups,
+      failedLookups: this._failedLookups,
+      totalAnnounces: this._totalAnnounces,
+      successfulAnnounces: this._successfulAnnounces,
+      failedAnnounces: this._failedAnnounces,
+      averageLookupLatencyMs,
+      isHealthy: healthy,
+    };
+  }
+
+  isHealthy(): boolean {
+    const nodeCount = this.getNodeCount();
+    const averageLookupLatencyMs = this.computeAverageLatency();
+    return this.evaluateHealth(nodeCount, averageLookupLatencyMs);
+  }
+
+  reset(): void {
+    this._totalLookups = 0;
+    this._successfulLookups = 0;
+    this._failedLookups = 0;
+    this._totalAnnounces = 0;
+    this._successfulAnnounces = 0;
+    this._failedAnnounces = 0;
+    this.latencySamples.length = 0;
+  }
+
+  private computeAverageLatency(): number {
+    if (this.latencySamples.length === 0) {
+      return 0;
+    }
+    const sum = this.latencySamples.reduce((a, b) => a + b, 0);
+    return sum / this.latencySamples.length;
+  }
+
+  private evaluateHealth(
+    nodeCount: number,
+    averageLookupLatencyMs: number
+  ): boolean {
+    // Must have minimum node count
+    if (nodeCount < this.thresholds.minNodeCount) {
+      return false;
+    }
+
+    // Check lookup success rate (only if we have 5+ lookups)
+    if (this._totalLookups >= 5) {
+      const successRate = this._successfulLookups / this._totalLookups;
+      if (successRate < this.thresholds.minLookupSuccessRate) {
+        return false;
+      }
+    }
+
+    // Check average latency (only if we have 5+ samples)
+    if (this.latencySamples.length >= 5) {
+      if (averageLookupLatencyMs > this.thresholds.maxAvgLookupLatencyMs) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+}

package/src/discovery/dht-node.ts

@@ -0,0 +1,191 @@
+import DHT from "bittorrent-dht";
+import { createHash } from "node:crypto";
+import { EventEmitter } from "node:events";
+import type { PeerId } from "../types/peer.js";
+import { OFFICIAL_BOOTSTRAP_NODES, toBootstrapConfig } from "./bootstrap.js";
+
+export interface DHTNodeConfig {
+  peerId: PeerId;
+  port: number;
+  bootstrapNodes: Array<{ host: string; port: number }>;
+  reannounceIntervalMs: number;
+  operationTimeoutMs: number;
+  /** Allow private/loopback IPs in lookup results. Default: false. Set true for local testing. */
+  allowPrivateIPs?: boolean;
+}
+
+export const DEFAULT_DHT_CONFIG: Omit<DHTNodeConfig, "peerId"> = {
+  port: 6881,
+  bootstrapNodes: toBootstrapConfig(OFFICIAL_BOOTSTRAP_NODES),
+  reannounceIntervalMs: 15 * 60 * 1000,
+  operationTimeoutMs: 10_000,
+};
+
+function isPublicIP(host: string): boolean {
+  if (host === "localhost" || host === "::1") return false;
+  const parts = host.split(".");
+  if (parts.length !== 4) return false;
+  const [a, b] = parts.map(Number);
+  if (a === 127) return false; // loopback
+  if (a === 10) return false; // 10.0.0.0/8
+  if (a === 172 && b !== undefined && b >= 16 && b <= 31) return false; // 172.16.0.0/12
+  if (a === 192 && b === 168) return false; // 192.168.0.0/16
+  if (a === 169 && b === 254) return false; // link-local
+  if (a === 0) return false;
+  return true;
+}
+
+export function topicToInfoHash(topic: string): Buffer {
+  return createHash("sha1").update(topic).digest();
+}
+
+export function providerTopic(providerName: string): string {
+  return "antseed:" + providerName.toLowerCase();
+}
+
+export function capabilityTopic(capability: string, name?: string): string {
+  const base = "antseed:" + capability.toLowerCase();
+  return name ? base + ":" + name.toLowerCase() : base;
+}
+
+export class DHTNode {
+  private readonly config: DHTNodeConfig;
+  private dht: DHT | null = null;
+  public readonly events: EventEmitter = new EventEmitter();
+
+  constructor(config: DHTNodeConfig) {
+    this.config = config;
+  }
+
+  async start(): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      this.dht = new DHT({
+        bootstrap: this.config.bootstrapNodes.map(
+          (n) => `${n.host}:${n.port}`
+        ),
+      });
+
+      const timeout = setTimeout(() => {
+        // Resolve even on timeout — the DHT may still work with partial bootstrap.
+        // This prevents hanging when public bootstrap nodes are unreachable.
+        cleanup();
+        this.events.emit("ready");
+        resolve();
+      }, this.config.operationTimeoutMs);
+
+      let settled = false;
+      const cleanup = (): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeout);
+      };
+
+      this.dht.listen(this.config.port, () => {
+        // Socket is bound; now wait for DHT bootstrap to complete.
+        // The 'ready' event fires when the routing table has been populated.
+        this.dht!.on("ready", () => {
+          cleanup();
+          this.events.emit("ready");
+          resolve();
+        });
+      });
+
+      this.dht.on("error", (err: Error) => {
+        cleanup();
+        reject(err);
+      });
+    });
+  }
+
+  async stop(): Promise<void> {
+    return new Promise<void>((resolve) => {
+      if (!this.dht) {
+        resolve();
+        return;
+      }
+      this.dht.destroy(() => {
+        this.dht = null;
+        resolve();
+      });
+    });
+  }
+
+  async announce(infoHash: Buffer, port: number): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      if (!this.dht) {
+        reject(new Error("DHT not started"));
+        return;
+      }
+
+      const timeout = setTimeout(() => {
+        reject(new Error("Announce timeout"));
+      }, this.config.operationTimeoutMs);
+
+      this.dht.announce(infoHash, port, (err?: Error) => {
+        clearTimeout(timeout);
+        if (err) {
+          reject(err);
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
+  async lookup(infoHash: Buffer): Promise<Array<{ host: string; port: number }>> {
+    return new Promise<Array<{ host: string; port: number }>>((resolve) => {
+      if (!this.dht) {
+        resolve([]);
+        return;
+      }
+
+      const peers: Array<{ host: string; port: number }> = [];
+      let done = false;
+
+      const onPeer = (peer: { host: string; port: number }, hash: Buffer): void => {
+        if (hash.equals(infoHash)) {
+          if (peer.port < 1 || peer.port > 65535) return;
+          if (!this.config.allowPrivateIPs && !isPublicIP(peer.host)) return;
+          peers.push({ host: peer.host, port: peer.port });
+        }
+      };
+
+      const finish = (): void => {
+        if (done) return;
+        done = true;
+        clearTimeout(timeout);
+        this.dht?.off("peer", onPeer);
+        resolve(peers);
+      };
+
+      this.dht.on("peer", onPeer);
+
+      const timeout = setTimeout(() => {
+        finish();
+      }, this.config.operationTimeoutMs);
+
+      this.dht.lookup(infoHash, () => {
+        finish();
+      });
+    });
+  }
+
+  getNodeCount(): number {
+    if (!this.dht) {
+      return 0;
+    }
+    return this.dht.nodes.toArray().length;
+  }
+
+  getPort(): number {
+    if (!this.dht) {
+      return this.config.port;
+    }
+    try {
+      const addr = this.dht.address();
+      return addr?.port ?? this.config.port;
+    } catch {
+      return this.config.port;
+    }
+  }
+}

package/src/discovery/http-metadata-resolver.ts

@@ -0,0 +1,47 @@
+import type { PeerEndpoint, MetadataResolver } from './metadata-resolver.js';
+import type { PeerMetadata } from './peer-metadata.js';
+import { debugWarn } from '../utils/debug.js';
+
+export interface HttpMetadataResolverConfig {
+  /** Timeout in ms for each metadata fetch. Default: 5000 */
+  timeoutMs?: number;
+  /** Port offset from the signaling port to the metadata HTTP port. Default: 0 (same port) */
+  metadataPortOffset?: number;
+}
+
+export class HttpMetadataResolver implements MetadataResolver {
+  private readonly timeoutMs: number;
+  private readonly metadataPortOffset: number;
+
+  constructor(config?: HttpMetadataResolverConfig) {
+    this.timeoutMs = config?.timeoutMs ?? 5000;
+    this.metadataPortOffset = config?.metadataPortOffset ?? 0;
+  }
+
+  async resolve(peer: PeerEndpoint): Promise<PeerMetadata | null> {
+    const metadataPort = peer.port + this.metadataPortOffset;
+    const url = `http://${peer.host}:${metadataPort}/metadata`;
+
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+      const response = await fetch(url, { signal: controller.signal });
+      clearTimeout(timeout);
+
+      if (!response.ok) {
+        return null;
+      }
+
+      return (await response.json()) as PeerMetadata;
+    } catch (err) {
+      const reason = err instanceof DOMException && err.name === 'AbortError'
+        ? 'timeout'
+        : err instanceof SyntaxError
+          ? 'invalid JSON'
+          : 'network error';
+      debugWarn(`[MetadataResolver] Failed to resolve ${url}: ${reason}`);
+      return null;
+    }
+  }
+}

package/src/discovery/index.ts

@@ -0,0 +1,15 @@
+export { DHTNode, DEFAULT_DHT_CONFIG, topicToInfoHash, providerTopic, type DHTNodeConfig } from './dht-node.js';
+export { PeerAnnouncer, type AnnouncerConfig } from './announcer.js';
+export { PeerLookup, DEFAULT_LOOKUP_CONFIG, type LookupConfig, type LookupResult } from './peer-lookup.js';
+export { scorePeer, rankPeers, selectBestPeer, selectDiversePeers, DEFAULT_SCORING_WEIGHTS, type ScoringWeights, type PeerCandidate, type ScoredPeer } from './peer-selector.js';
+export { OFFICIAL_BOOTSTRAP_NODES, parseBootstrapList, mergeBootstrapNodes, toBootstrapConfig, type BootstrapNode } from './bootstrap.js';
+export { encodeMetadata, encodeMetadataForSigning, decodeMetadata } from './metadata-codec.js';
+export { validateMetadata, MAX_METADATA_SIZE, MAX_PROVIDERS, type ValidationError } from './metadata-validator.js';
+export { METADATA_VERSION, type PeerMetadata, type ProviderAnnouncement } from './peer-metadata.js';
+export { type MetadataResolver, type PeerEndpoint } from './metadata-resolver.js';
+export { DefaultMetadataResolver } from './default-metadata-resolver.js';
+export { HttpMetadataResolver, type HttpMetadataResolverConfig } from './http-metadata-resolver.js';
+export { DHTHealthMonitor, DEFAULT_HEALTH_THRESHOLDS, type DHTHealthSnapshot, type HealthThresholds } from './dht-health.js';
+export { ProfileManager, type ProfileManagerConfig } from './profile-manager.js';
+export { ProfileSearchIndex, type ProfileSearchQuery, type ProfileSearchResult } from './profile-search.js';
+export { verifyReputation, type ReputationVerification } from './reputation-verifier.js';