@relay-federation/bridge 0.1.0

package/lib/peer-health.js

@@ -0,0 +1,172 @@
+import { EventEmitter } from 'node:events'
+
+const DEFAULT_GRACE_PERIOD_MS = 24 * 60 * 60 * 1000 // 24 hours
+const DEFAULT_INACTIVE_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000 // 7 days
+
+/**
+ * Peer health tracker — monitors peer connectivity and applies
+ * grace period logic + auto-deregistration detection.
+ *
+ * Rules:
+ * - Tracks last-seen timestamp for each peer
+ * - Grace period (24h): short outages don't count against peer score
+ * - Inactive threshold (7d): peers unreachable for 7+ days are flagged inactive
+ * - Inactive peers should be excluded from peer lists locally
+ *
+ * Emits:
+ *   'peer:grace'    — { pubkeyHex, offlineSince } — peer entered grace period
+ *   'peer:inactive' — { pubkeyHex, offlineSince } — peer flagged as inactive (7+ days offline)
+ *   'peer:recovered' — { pubkeyHex } — peer came back online
+ */
+export class PeerHealth extends EventEmitter {
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.gracePeriodMs=86400000] — 24 hours
+   * @param {number} [opts.inactiveThresholdMs=604800000] — 7 days
+   */
+  constructor (opts = {}) {
+    super()
+    this._gracePeriodMs = opts.gracePeriodMs ?? DEFAULT_GRACE_PERIOD_MS
+    this._inactiveThresholdMs = opts.inactiveThresholdMs ?? DEFAULT_INACTIVE_THRESHOLD_MS
+
+    /** @type {Map<string, { lastSeen: number, offlineSince: number|null, status: string }>} */
+    this._peers = new Map()
+  }
+
+  /**
+   * Record that we successfully communicated with a peer.
+   * Resets offline tracking.
+   * @param {string} pubkeyHex
+   */
+  recordSeen (pubkeyHex) {
+    const prev = this._peers.get(pubkeyHex)
+    const wasOffline = prev && prev.offlineSince !== null
+
+    this._peers.set(pubkeyHex, {
+      lastSeen: Date.now(),
+      offlineSince: null,
+      status: 'online'
+    })
+
+    if (wasOffline) {
+      this.emit('peer:recovered', { pubkeyHex })
+    }
+  }
+
+  /**
+   * Record that a peer has disconnected or failed to respond.
+   * Starts the offline timer if not already started.
+   * @param {string} pubkeyHex
+   */
+  recordOffline (pubkeyHex) {
+    const existing = this._peers.get(pubkeyHex)
+
+    if (existing && existing.offlineSince !== null) {
+      // Already tracking offline — don't reset the timer
+      return
+    }
+
+    this._peers.set(pubkeyHex, {
+      lastSeen: existing ? existing.lastSeen : 0,
+      offlineSince: Date.now(),
+      status: 'offline'
+    })
+  }
+
+  /**
+   * Check the health status of a peer.
+   *
+   * @param {string} pubkeyHex
+   * @returns {'online'|'grace'|'inactive'|'unknown'}
+   */
+  getStatus (pubkeyHex) {
+    const peer = this._peers.get(pubkeyHex)
+    if (!peer) return 'unknown'
+    if (peer.offlineSince === null) return 'online'
+
+    const offlineDuration = Date.now() - peer.offlineSince
+
+    if (offlineDuration >= this._inactiveThresholdMs) {
+      return 'inactive'
+    }
+
+    if (offlineDuration >= this._gracePeriodMs) {
+      return 'offline'
+    }
+
+    return 'grace'
+  }
+
+  /**
+   * Check all peers and emit events for status changes.
+   * Call this periodically (e.g. every 10 minutes).
+   *
+   * @returns {{ grace: string[], inactive: string[] }} Lists of pubkeys in each state
+   */
+  checkAll () {
+    const grace = []
+    const inactive = []
+
+    for (const [pubkeyHex, peer] of this._peers) {
+      if (peer.offlineSince === null) continue
+
+      const status = this.getStatus(pubkeyHex)
+      const prevStatus = peer.status
+
+      if (status === 'inactive' && prevStatus !== 'inactive') {
+        peer.status = 'inactive'
+        inactive.push(pubkeyHex)
+        this.emit('peer:inactive', { pubkeyHex, offlineSince: peer.offlineSince })
+      } else if (status === 'grace' && prevStatus !== 'grace') {
+        peer.status = 'grace'
+        grace.push(pubkeyHex)
+        this.emit('peer:grace', { pubkeyHex, offlineSince: peer.offlineSince })
+      }
+    }
+
+    return { grace, inactive }
+  }
+
+  /**
+   * Get the last-seen timestamp for a peer.
+   * @param {string} pubkeyHex
+   * @returns {number|null} Unix timestamp in ms, or null if unknown
+   */
+  getLastSeen (pubkeyHex) {
+    const peer = this._peers.get(pubkeyHex)
+    return peer ? peer.lastSeen : null
+  }
+
+  /**
+   * Get all peers flagged as inactive (7+ days offline).
+   * @returns {string[]} Array of pubkeyHex strings
+   */
+  getInactivePeers () {
+    const result = []
+    for (const [pubkeyHex] of this._peers) {
+      if (this.getStatus(pubkeyHex) === 'inactive') {
+        result.push(pubkeyHex)
+      }
+    }
+    return result
+  }
+
+  /**
+   * Check if scoring impact should be suppressed (grace period active).
+   * During grace period, bad pings should NOT count against the peer.
+   *
+   * @param {string} pubkeyHex
+   * @returns {boolean} true if peer is in grace period (suppress scoring)
+   */
+  isInGracePeriod (pubkeyHex) {
+    return this.getStatus(pubkeyHex) === 'grace'
+  }
+
+  /**
+   * Remove a peer from health tracking.
+   * @param {string} pubkeyHex
+   */
+  removePeer (pubkeyHex) {
+    this._peers.delete(pubkeyHex)
+  }
+}

package/lib/peer-manager.js

@@ -0,0 +1,214 @@
+import { EventEmitter } from 'node:events'
+import { WebSocketServer } from 'ws'
+import { PeerConnection } from './peer-connection.js'
+
+/**
+ * PeerManager — manages multiple peer connections.
+ *
+ * Handles:
+ * - Outbound connections to discovered peers
+ * - Inbound connections from other bridges (via WSS server)
+ * - Broadcasting messages to all connected peers
+ * - Peer lifecycle (connect, disconnect, reconnect)
+ *
+ * Events:
+ *   'peer:connect'    — { pubkeyHex, endpoint }
+ *   'peer:disconnect' — { pubkeyHex, endpoint }
+ *   'peer:message'    — { pubkeyHex, message }
+ *   'peer:error'      — { pubkeyHex, error }
+ */
+export class PeerManager extends EventEmitter {
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.maxPeers=20] - Maximum number of peer connections
+   */
+  constructor (opts = {}) {
+    super()
+    this.maxPeers = opts.maxPeers || 20
+    /** @type {Map<string, PeerConnection>} pubkeyHex → PeerConnection */
+    this.peers = new Map()
+    this._server = null
+  }
+
+  /**
+   * Connect to a discovered peer (outbound).
+   *
+   * @param {object} peer - Peer from buildPeerList()
+   * @param {string} peer.pubkeyHex
+   * @param {string} peer.endpoint
+   * @returns {PeerConnection|null} The connection, or null if at capacity
+   */
+  connectToPeer (peer) {
+    if (this.peers.has(peer.pubkeyHex)) {
+      return this.peers.get(peer.pubkeyHex)
+    }
+
+    if (this.peers.size >= this.maxPeers) {
+      return null
+    }
+
+    const conn = new PeerConnection({
+      endpoint: peer.endpoint,
+      pubkeyHex: peer.pubkeyHex
+    })
+
+    this._attachPeerEvents(conn)
+    this.peers.set(peer.pubkeyHex, conn)
+    conn.connect()
+
+    return conn
+  }
+
+  /**
+   * Accept an inbound peer connection.
+   *
+   * @param {WebSocket} socket - Incoming WebSocket
+   * @param {string} pubkeyHex - Peer's pubkey (from handshake)
+   * @param {string} endpoint - Peer's advertised endpoint
+   * @returns {PeerConnection|null}
+   */
+  acceptPeer (socket, pubkeyHex, endpoint) {
+    if (this.peers.has(pubkeyHex)) {
+      // Already connected — close the duplicate
+      socket.close()
+      return this.peers.get(pubkeyHex)
+    }
+
+    if (this.peers.size >= this.maxPeers) {
+      socket.close()
+      return null
+    }
+
+    const conn = new PeerConnection({
+      endpoint,
+      pubkeyHex,
+      socket
+    })
+
+    this._attachPeerEvents(conn)
+    this.peers.set(pubkeyHex, conn)
+
+    return conn
+  }
+
+  /**
+   * Disconnect a specific peer.
+   *
+   * @param {string} pubkeyHex
+   */
+  disconnectPeer (pubkeyHex) {
+    const conn = this.peers.get(pubkeyHex)
+    if (conn) {
+      conn.destroy()
+      this.peers.delete(pubkeyHex)
+    }
+  }
+
+  /**
+   * Broadcast a message to all connected peers.
+   *
+   * @param {object} msg - JSON message with `type` field
+   * @param {string} [excludePubkey] - Optional pubkey to exclude (e.g. message source)
+   * @returns {number} Number of peers the message was sent to
+   */
+  broadcast (msg, excludePubkey) {
+    let sent = 0
+    for (const [pubkeyHex, conn] of this.peers) {
+      if (pubkeyHex === excludePubkey) continue
+      if (conn.send(msg)) sent++
+    }
+    return sent
+  }
+
+  /**
+   * Get count of currently connected peers.
+   * @returns {number}
+   */
+  connectedCount () {
+    let count = 0
+    for (const conn of this.peers.values()) {
+      if (conn.connected) count++
+    }
+    return count
+  }
+
+  /**
+   * Start a WebSocket server for inbound connections.
+   *
+   * @param {object} opts
+   * @param {number} opts.port - Port to listen on
+   * @param {string} [opts.host='0.0.0.0'] - Host to bind to
+   * @returns {Promise<void>}
+   */
+  startServer (opts) {
+    return new Promise((resolve, reject) => {
+      this._server = new WebSocketServer({
+        port: opts.port,
+        host: opts.host || '0.0.0.0'
+      })
+
+      this._server.on('listening', () => resolve())
+      this._server.on('error', (err) => reject(err))
+
+      this._server.on('connection', (ws) => {
+        // Inbound connections need to identify themselves via handshake.
+        // For now, we hold the socket and wait for a 'hello' message.
+        const timeout = setTimeout(() => {
+          ws.close() // No hello within 10 seconds
+        }, 10000)
+
+        ws.once('message', (data) => {
+          clearTimeout(timeout)
+          try {
+            const msg = JSON.parse(data.toString())
+            if (msg.type === 'hello' && msg.pubkey && msg.endpoint) {
+              const conn = this.acceptPeer(ws, msg.pubkey, msg.endpoint)
+              if (conn) {
+                this.emit('peer:connect', { pubkeyHex: msg.pubkey, endpoint: msg.endpoint })
+                // Forward the hello as a regular message too
+                conn.emit('message', msg)
+              }
+            } else {
+              ws.close() // Invalid hello
+            }
+          } catch {
+            ws.close() // Invalid JSON
+          }
+        })
+      })
+    })
+  }
+
+  /**
+   * Stop the WebSocket server and disconnect all peers.
+   */
+  async shutdown () {
+    for (const [pubkeyHex, conn] of this.peers) {
+      conn.destroy()
+    }
+    this.peers.clear()
+
+    if (this._server) {
+      await new Promise(resolve => this._server.close(resolve))
+      this._server = null
+    }
+  }
+
+  _attachPeerEvents (conn) {
+    conn.on('open', () => {
+      this.emit('peer:connect', { pubkeyHex: conn.pubkeyHex, endpoint: conn.endpoint })
+    })
+
+    conn.on('message', (msg) => {
+      this.emit('peer:message', { pubkeyHex: conn.pubkeyHex, message: msg })
+    })
+
+    conn.on('close', () => {
+      this.emit('peer:disconnect', { pubkeyHex: conn.pubkeyHex, endpoint: conn.endpoint })
+    })
+
+    conn.on('error', (err) => {
+      this.emit('peer:error', { pubkeyHex: conn.pubkeyHex, error: err })
+    })
+  }
+}

package/lib/peer-scorer.js

@@ -0,0 +1,285 @@
+import { EventEmitter } from 'node:events'
+
+const WEIGHTS = {
+  uptime: 0.3,
+  responseTime: 0.2,
+  dataAccuracy: 0.4,
+  stakeAge: 0.1
+}
+
+// Response time normalization: 1.0 = <100ms, 0.0 = >5000ms
+const RT_FLOOR = 100
+const RT_CEIL = 5000
+
+// Stake age normalization: log2(days) / 10, capped at 1.0
+const STAKE_AGE_DIVISOR = 10
+
+// Rolling windows
+const DEFAULT_ACCURACY_WINDOW = 1000
+const DEFAULT_UPTIME_WINDOW = 1000 // ~7 days at 10-min ping intervals
+
+/**
+ * Per-peer metrics bucket.
+ */
+function createMetrics () {
+  return {
+    // Uptime tracking
+    pings: 0,
+    pongs: 0,
+
+    // Response time — rolling average
+    latencies: [],
+
+    // Data accuracy — rolling window of booleans (true = good)
+    accuracyLog: [],
+
+    // Stake age in days
+    stakeAgeDays: 0
+  }
+}
+
+/**
+ * Peer scoring engine.
+ *
+ * Computes local reputation scores for each connected peer.
+ * Formula: 0.3 * uptime + 0.2 * response_time + 0.4 * data_accuracy + 0.1 * stake_age
+ *
+ * Emits:
+ *   'score:update' — { pubkeyHex, score, metrics }
+ */
+export class PeerScorer extends EventEmitter {
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.accuracyWindow=1000] — rolling window size for data accuracy
+   * @param {number} [opts.uptimeWindow=1000] — rolling window size for uptime pings
+   * @param {number} [opts.latencyWindow=100] — rolling window size for latency samples
+   */
+  constructor (opts = {}) {
+    super()
+    this._peers = new Map() // pubkeyHex → metrics
+    this._accuracyWindow = opts.accuracyWindow || DEFAULT_ACCURACY_WINDOW
+    this._uptimeWindow = opts.uptimeWindow || DEFAULT_UPTIME_WINDOW
+    this._latencyWindow = opts.latencyWindow || 100
+  }
+
+  /**
+   * Get or create metrics for a peer.
+   * @param {string} pubkeyHex
+   * @returns {object}
+   */
+  _getMetrics (pubkeyHex) {
+    if (!this._peers.has(pubkeyHex)) {
+      this._peers.set(pubkeyHex, createMetrics())
+    }
+    return this._peers.get(pubkeyHex)
+  }
+
+  /**
+   * Record a successful ping response.
+   * @param {string} pubkeyHex
+   * @param {number} latencyMs — round-trip time in milliseconds
+   */
+  recordPing (pubkeyHex, latencyMs) {
+    const m = this._getMetrics(pubkeyHex)
+    m.pings++
+    m.pongs++
+
+    // Trim uptime window
+    if (m.pings > this._uptimeWindow) {
+      // Approximate: scale down proportionally
+      const ratio = m.pongs / m.pings
+      m.pings = this._uptimeWindow
+      m.pongs = Math.round(ratio * this._uptimeWindow)
+    }
+
+    // Record latency
+    m.latencies.push(latencyMs)
+    if (m.latencies.length > this._latencyWindow) {
+      m.latencies.shift()
+    }
+
+    this._emitUpdate(pubkeyHex)
+  }
+
+  /**
+   * Record a ping timeout (no response).
+   * @param {string} pubkeyHex
+   */
+  recordPingTimeout (pubkeyHex) {
+    const m = this._getMetrics(pubkeyHex)
+    m.pings++
+
+    // Trim uptime window
+    if (m.pings > this._uptimeWindow) {
+      const ratio = m.pongs / m.pings
+      m.pings = this._uptimeWindow
+      m.pongs = Math.round(ratio * this._uptimeWindow)
+    }
+
+    this._emitUpdate(pubkeyHex)
+  }
+
+  /**
+   * Record a valid data relay (good header or tx).
+   * @param {string} pubkeyHex
+   */
+  recordGoodData (pubkeyHex) {
+    const m = this._getMetrics(pubkeyHex)
+    m.accuracyLog.push(true)
+    if (m.accuracyLog.length > this._accuracyWindow) {
+      m.accuracyLog.shift()
+    }
+    this._emitUpdate(pubkeyHex)
+  }
+
+  /**
+   * Record an invalid data relay (bad header or tx).
+   * @param {string} pubkeyHex
+   */
+  recordBadData (pubkeyHex) {
+    const m = this._getMetrics(pubkeyHex)
+    m.accuracyLog.push(false)
+    if (m.accuracyLog.length > this._accuracyWindow) {
+      m.accuracyLog.shift()
+    }
+    this._emitUpdate(pubkeyHex)
+  }
+
+  /**
+   * Set the stake bond age for a peer.
+   * @param {string} pubkeyHex
+   * @param {number} days — age of stake bond in days
+   */
+  setStakeAge (pubkeyHex, days) {
+    const m = this._getMetrics(pubkeyHex)
+    m.stakeAgeDays = days
+    this._emitUpdate(pubkeyHex)
+  }
+
+  /**
+   * Compute the uptime sub-score (0-1).
+   * @param {object} m — metrics
+   * @returns {number}
+   */
+  _computeUptime (m) {
+    if (m.pings === 0) return 0.5 // neutral when no data
+    return m.pongs / m.pings
+  }
+
+  /**
+   * Compute the response time sub-score (0-1).
+   * 1.0 = <= 100ms, 0.0 = >= 5000ms, linear between.
+   * @param {object} m — metrics
+   * @returns {number}
+   */
+  _computeResponseTime (m) {
+    if (m.latencies.length === 0) return 0.5 // neutral when no data
+    const avg = m.latencies.reduce((a, b) => a + b, 0) / m.latencies.length
+    if (avg <= RT_FLOOR) return 1.0
+    if (avg >= RT_CEIL) return 0.0
+    return 1.0 - (avg - RT_FLOOR) / (RT_CEIL - RT_FLOOR)
+  }
+
+  /**
+   * Compute the data accuracy sub-score (0-1).
+   * @param {object} m — metrics
+   * @returns {number}
+   */
+  _computeDataAccuracy (m) {
+    if (m.accuracyLog.length === 0) return 0.5 // neutral when no data
+    const good = m.accuracyLog.filter(Boolean).length
+    return good / m.accuracyLog.length
+  }
+
+  /**
+   * Compute the stake age sub-score (0-1).
+   * Formula: log2(days) / 10, capped at 1.0.
+   * @param {object} m — metrics
+   * @returns {number}
+   */
+  _computeStakeAge (m) {
+    if (m.stakeAgeDays <= 0) return 0
+    return Math.min(1.0, Math.log2(m.stakeAgeDays) / STAKE_AGE_DIVISOR)
+  }
+
+  /**
+   * Get the composite score for a peer.
+   * @param {string} pubkeyHex
+   * @returns {number} 0-1
+   */
+  getScore (pubkeyHex) {
+    if (!this._peers.has(pubkeyHex)) return 0.5 // unknown peer = neutral
+
+    const m = this._peers.get(pubkeyHex)
+    const uptime = this._computeUptime(m)
+    const responseTime = this._computeResponseTime(m)
+    const dataAccuracy = this._computeDataAccuracy(m)
+    const stakeAge = this._computeStakeAge(m)
+
+    return (
+      WEIGHTS.uptime * uptime +
+      WEIGHTS.responseTime * responseTime +
+      WEIGHTS.dataAccuracy * dataAccuracy +
+      WEIGHTS.stakeAge * stakeAge
+    )
+  }
+
+  /**
+   * Get all sub-scores and raw metrics for a peer.
+   * @param {string} pubkeyHex
+   * @returns {object|null}
+   */
+  getMetrics (pubkeyHex) {
+    if (!this._peers.has(pubkeyHex)) return null
+
+    const m = this._peers.get(pubkeyHex)
+    return {
+      uptime: this._computeUptime(m),
+      responseTime: this._computeResponseTime(m),
+      dataAccuracy: this._computeDataAccuracy(m),
+      stakeAge: this._computeStakeAge(m),
+      score: this.getScore(pubkeyHex),
+      raw: {
+        pings: m.pings,
+        pongs: m.pongs,
+        latencySamples: m.latencies.length,
+        avgLatencyMs: m.latencies.length > 0
+          ? Math.round(m.latencies.reduce((a, b) => a + b, 0) / m.latencies.length)
+          : null,
+        accuracySamples: m.accuracyLog.length,
+        stakeAgeDays: m.stakeAgeDays
+      }
+    }
+  }
+
+  /**
+   * Get scores for all tracked peers.
+   * @returns {Map<string, number>}
+   */
+  getAllScores () {
+    const scores = new Map()
+    for (const pubkeyHex of this._peers.keys()) {
+      scores.set(pubkeyHex, this.getScore(pubkeyHex))
+    }
+    return scores
+  }
+
+  /**
+   * Remove a peer from tracking.
+   * @param {string} pubkeyHex
+   */
+  removePeer (pubkeyHex) {
+    this._peers.delete(pubkeyHex)
+  }
+
+  /**
+   * Emit a score update event.
+   * @param {string} pubkeyHex
+   */
+  _emitUpdate (pubkeyHex) {
+    this.emit('score:update', {
+      pubkeyHex,
+      score: this.getScore(pubkeyHex)
+    })
+  }
+}