@libp2p/kad-dht 0.28.6

package/src/message/dht.proto

@@ -0,0 +1,75 @@
+syntax = "proto3";
+// can't use, because protocol-buffers doesn't support imports
+// so we have to duplicate for now :(
+// import "record.proto";
+
+message Record {
+  // adjusted for javascript
+  optional bytes key = 1;
+  optional bytes value = 2;
+  optional bytes author = 3;
+  optional bytes signature = 4;
+  optional string timeReceived = 5;
+}
+
+message Message {
+  enum MessageType {
+    PUT_VALUE = 0;
+    GET_VALUE = 1;
+    ADD_PROVIDER = 2;
+    GET_PROVIDERS = 3;
+    FIND_NODE = 4;
+    PING = 5;
+  }
+
+  enum ConnectionType {
+    // sender does not have a connection to peer, and no extra information (default)
+    NOT_CONNECTED = 0;
+
+    // sender has a live connection to peer
+    CONNECTED = 1;
+
+    // sender recently connected to peer
+    CAN_CONNECT = 2;
+
+    // sender recently tried to connect to peer repeatedly but failed to connect
+    // ("try" here is loose, but this should signal "made strong effort, failed")
+    CANNOT_CONNECT = 3;
+  }
+
+  message Peer {
+    // ID of a given peer.
+    optional bytes id = 1;
+
+    // multiaddrs for a given peer
+    repeated bytes addrs = 2;
+
+    // used to signal the sender's connection capabilities to the peer
+    optional ConnectionType connection = 3;
+  }
+
+  // defines what type of message it is.
+  optional MessageType type = 1;
+
+  // defines what coral cluster level this query/response belongs to.
+  // in case we want to implement coral's cluster rings in the future.
+  optional int32 clusterLevelRaw = 10;
+
+  // Used to specify the key associated with this message.
+  // PUT_VALUE, GET_VALUE, ADD_PROVIDER, GET_PROVIDERS
+  // adjusted for javascript
+  optional bytes key = 2;
+
+  // Used to return a value
+  // PUT_VALUE, GET_VALUE
+  // adjusted Record to bytes for js
+  optional bytes record = 3;
+
+  // Used to return peers closer to a key in a query
+  // GET_VALUE, GET_PROVIDERS, FIND_NODE
+  repeated Peer closerPeers = 8;
+
+  // Used to return Providers
+  // GET_VALUE, ADD_PROVIDER, GET_PROVIDERS
+  repeated Peer providerPeers = 9;
+}

package/src/message/index.ts

@@ -0,0 +1,111 @@
+import { peerIdFromBytes } from '@libp2p/peer-id'
+import { Multiaddr } from '@multiformats/multiaddr'
+import { Libp2pRecord } from '@libp2p/record'
+import Proto from './dht.js'
+import type { PeerData } from '@libp2p/interfaces/peer-data'
+
+export const MESSAGE_TYPE = Proto.Message.MessageType
+export const CONNECTION_TYPE = Proto.Message.ConnectionType
+export const MESSAGE_TYPE_LOOKUP = Object.keys(MESSAGE_TYPE)
+
+type ConnectionType = 0|1|2|3|4
+
+interface PBPeer {
+  id: Uint8Array
+  addrs: Uint8Array[]
+  connection: ConnectionType
+}
+
+/**
+ * Represents a single DHT control message.
+ */
+export class Message {
+  public type: Proto.Message.MessageType
+  public key: Uint8Array
+  private clusterLevelRaw: number
+  public closerPeers: PeerData[]
+  public providerPeers: PeerData[]
+  public record?: Libp2pRecord
+
+  constructor (type: Proto.Message.MessageType, key: Uint8Array, level: number) {
+    if (!(key instanceof Uint8Array)) {
+      throw new Error('Key must be a Uint8Array')
+    }
+
+    this.type = type
+    this.key = key
+    this.clusterLevelRaw = level
+    this.closerPeers = []
+    this.providerPeers = []
+    this.record = undefined
+  }
+
+  /**
+   * @type {number}
+   */
+  get clusterLevel () {
+    const level = this.clusterLevelRaw - 1
+    if (level < 0) {
+      return 0
+    }
+
+    return level
+  }
+
+  set clusterLevel (level) {
+    this.clusterLevelRaw = level
+  }
+
+  /**
+   * Encode into protobuf
+   */
+  serialize () {
+    return Proto.Message.encode({
+      key: this.key,
+      type: this.type,
+      clusterLevelRaw: this.clusterLevelRaw,
+      closerPeers: this.closerPeers.map(toPbPeer),
+      providerPeers: this.providerPeers.map(toPbPeer),
+      record: this.record == null ? undefined : this.record.serialize()
+    }).finish()
+  }
+
+  /**
+   * Decode from protobuf
+   */
+  static deserialize (raw: Uint8Array) {
+    const dec = Proto.Message.decode(raw)
+
+    const msg = new Message(dec.type ?? 0, dec.key ?? Uint8Array.from([]), dec.clusterLevelRaw ?? 0)
+    msg.closerPeers = dec.closerPeers.map(fromPbPeer)
+    msg.providerPeers = dec.providerPeers.map(fromPbPeer)
+
+    if (dec.record?.length != null) {
+      msg.record = Libp2pRecord.deserialize(dec.record)
+    }
+
+    return msg
+  }
+}
+
+function toPbPeer (peer: PeerData) {
+  const output: PBPeer = {
+    id: peer.id.toBytes(),
+    addrs: (peer.multiaddrs ?? []).map((m) => m.bytes),
+    connection: CONNECTION_TYPE.CONNECTED
+  }
+
+  return output
+}
+
+function fromPbPeer (peer: Proto.Message.IPeer) {
+  if (peer.id == null) {
+    throw new Error('Invalid peer in message')
+  }
+
+  return {
+    id: peerIdFromBytes(peer.id),
+    multiaddrs: (peer.addrs ?? []).map((a) => new Multiaddr(a)),
+    protocols: []
+  }
+}

package/src/network.ts

@@ -0,0 +1,185 @@
+import errcode from 'err-code'
+import { pipe } from 'it-pipe'
+import * as lp from 'it-length-prefixed'
+import drain from 'it-drain'
+import first from 'it-first'
+import { Message, MESSAGE_TYPE_LOOKUP } from './message/index.js'
+import { EventEmitter, CustomEvent } from '@libp2p/interfaces'
+import {
+  dialingPeerEvent,
+  sendingQueryEvent,
+  peerResponseEvent,
+  queryErrorEvent
+} from './query/events.js'
+import { logger } from '@libp2p/logger'
+import type { PeerId } from '@libp2p/interfaces/peer-id'
+import type { AbortOptions, Dialer, Startable } from '@libp2p/interfaces'
+import type { Logger } from '@libp2p/logger'
+import type { Duplex } from 'it-stream-types'
+import type { PeerData } from '@libp2p/interfaces/peer-data'
+
+export interface NetworkOptions {
+  dialer: Dialer
+  protocol: string
+  lan: boolean
+  peerId: PeerId
+}
+
+interface NetworkEvents {
+  'peer': CustomEvent<PeerData>
+}
+
+/**
+ * Handle network operations for the dht
+ */
+export class Network extends EventEmitter<NetworkEvents> implements Startable {
+  private readonly log: Logger
+  public dialer: Dialer
+  private readonly protocol: string
+  private running: boolean
+
+  /**
+   * Create a new network
+   */
+  constructor (options: NetworkOptions) {
+    super()
+
+    const { dialer, protocol, lan, peerId } = options
+    this.log = logger(`libp2p:kad-dht:${lan ? 'lan' : 'wan'}:network:${peerId.toString()}`)
+    this.running = false
+    this.dialer = dialer
+    this.protocol = protocol
+  }
+
+  /**
+   * Start the network
+   */
+  async start () {
+    if (this.running) {
+      return
+    }
+
+    this.running = true
+  }
+
+  /**
+   * Stop all network activity
+   */
+  async stop () {
+    this.running = false
+  }
+
+  /**
+   * Is the network online?
+   */
+  isStarted () {
+    return this.running
+  }
+
+  /**
+   * Send a request and record RTT for latency measurements
+   */
+  async * sendRequest (to: PeerId, msg: Message, options: AbortOptions = {}) {
+    if (!this.running) {
+      return
+    }
+
+    this.log('sending %s to %p', MESSAGE_TYPE_LOOKUP[msg.type], to)
+
+    try {
+      yield dialingPeerEvent({ peer: to })
+
+      const { stream } = await this.dialer.dialProtocol(to, this.protocol, options)
+
+      yield sendingQueryEvent({ to, type: msg.type })
+
+      const response = await this._writeReadMessage(stream, msg.serialize())
+
+      yield peerResponseEvent({
+        from: to,
+        messageType: response.type,
+        closer: response.closerPeers,
+        providers: response.providerPeers,
+        record: response.record
+      })
+    } catch (err: any) {
+      yield queryErrorEvent({ from: to, error: err })
+    }
+  }
+
+  /**
+   * Sends a message without expecting an answer
+   */
+  async * sendMessage (to: PeerId, msg: Message, options: AbortOptions = {}) {
+    if (!this.running) {
+      return
+    }
+
+    this.log('sending %s to %p', MESSAGE_TYPE_LOOKUP[msg.type], to)
+
+    yield dialingPeerEvent({ peer: to })
+
+    const { stream } = await this.dialer.dialProtocol(to, this.protocol, options)
+
+    yield sendingQueryEvent({ to, type: msg.type })
+
+    try {
+      await this._writeMessage(stream, msg.serialize())
+
+      yield peerResponseEvent({ from: to, messageType: msg.type })
+    } catch (err: any) {
+      yield queryErrorEvent({ from: to, error: err })
+    }
+  }
+
+  /**
+   * Write a message to the given stream
+   */
+  async _writeMessage (stream: Duplex<Uint8Array>, msg: Uint8Array) {
+    await pipe(
+      [msg],
+      lp.encode(),
+      stream,
+      drain
+    )
+  }
+
+  /**
+   * Write a message and read its response.
+   * If no response is received after the specified timeout
+   * this will error out.
+   */
+  async _writeReadMessage (stream: Duplex<Uint8Array>, msg: Uint8Array) {
+    const res = await pipe(
+      [msg],
+      lp.encode(),
+      stream,
+      lp.decode(),
+      async source => {
+        const buf = await first(source)
+
+        if (buf != null) {
+          return buf
+        }
+
+        throw errcode(new Error('No message received'), 'ERR_NO_MESSAGE_RECEIVED')
+      }
+    )
+
+    const message = Message.deserialize(res)
+
+    // tell any listeners about new peers we've seen
+    message.closerPeers.forEach(peerData => {
+      this.dispatchEvent(new CustomEvent('peer', {
+        detail: peerData
+      }))
+    })
+    message.providerPeers.forEach(peerData => {
+      this.dispatchEvent(new CustomEvent('peer', {
+        detail: peerData
+      }))
+    })
+
+    return message
+  }
+}

package/src/peer-list/index.ts

@@ -0,0 +1,54 @@
+import type { PeerId } from '@libp2p/interfaces/peer-id'
+
+/**
+ * A list of unique peers.
+ */
+export class PeerList {
+  private readonly list: PeerId[]
+
+  constructor () {
+    this.list = []
+  }
+
+  /**
+   * Add a new peer. Returns `true` if it was a new one
+   */
+  push (peerId: PeerId) {
+    if (!this.has(peerId)) {
+      this.list.push(peerId)
+
+      return true
+    }
+
+    return false
+  }
+
+  /**
+   * Check if this PeerData is already in here
+   */
+  has (peerId: PeerId) {
+    const match = this.list.find((i) => i.equals(peerId))
+    return Boolean(match)
+  }
+
+  /**
+   * Get the list as an array
+   */
+  toArray () {
+    return this.list.slice()
+  }
+
+  /**
+   * Remove the last element
+   */
+  pop () {
+    return this.list.pop()
+  }
+
+  /**
+   * The length of the list
+   */
+  get length () {
+    return this.list.length
+  }
+}

package/src/peer-list/peer-distance-list.ts

@@ -0,0 +1,93 @@
+import * as utils from '../utils.js'
+import pMap from 'p-map'
+import { compare as uint8ArrayCompare } from 'uint8arrays/compare'
+import { xor as uint8ArrayXor } from 'uint8arrays/xor'
+import type { PeerId } from '@libp2p/interfaces/peer-id'
+
+interface PeerDistance {
+  peerId: PeerId
+  distance: Uint8Array
+}
+
+/**
+ * Maintains a list of peerIds sorted by distance from a DHT key.
+ */
+export class PeerDistanceList {
+  /**
+   * The DHT key from which distance is calculated
+   */
+  private readonly originDhtKey: Uint8Array
+
+  /**
+   * The maximum size of the list
+   */
+  private readonly capacity: number
+
+  private peerDistances: PeerDistance[]
+
+  constructor (originDhtKey: Uint8Array, capacity: number) {
+    this.originDhtKey = originDhtKey
+    this.capacity = capacity
+    this.peerDistances = []
+  }
+
+  /**
+   * The length of the list
+   */
+  get length () {
+    return this.peerDistances.length
+  }
+
+  /**
+   * The peerIds in the list, in order of distance from the origin key
+   */
+  get peers () {
+    return this.peerDistances.map(pd => pd.peerId)
+  }
+
+  /**
+   * Add a peerId to the list.
+   */
+  async add (peerId: PeerId) {
+    if (this.peerDistances.find(pd => pd.peerId.equals(peerId)) != null) {
+      return
+    }
+
+    const dhtKey = await utils.convertPeerId(peerId)
+    const el = {
+      peerId,
+      distance: uint8ArrayXor(this.originDhtKey, dhtKey)
+    }
+
+    this.peerDistances.push(el)
+    this.peerDistances.sort((a, b) => uint8ArrayCompare(a.distance, b.distance))
+    this.peerDistances = this.peerDistances.slice(0, this.capacity)
+  }
+
+  /**
+   * Indicates whether any of the peerIds passed as a parameter are closer
+   * to the origin key than the furthest peerId in the PeerDistanceList.
+   */
+  async anyCloser (peerIds: PeerId[]) {
+    if (peerIds.length === 0) {
+      return false
+    }
+
+    if (this.length === 0) {
+      return true
+    }
+
+    const dhtKeys = await pMap(peerIds, async (peerId) => await utils.convertPeerId(peerId))
+    const furthestDistance = this.peerDistances[this.peerDistances.length - 1].distance
+
+    for (const dhtKey of dhtKeys) {
+      const keyDistance = uint8ArrayXor(this.originDhtKey, dhtKey)
+
+      if (uint8ArrayCompare(keyDistance, furthestDistance) < 0) {
+        return true
+      }
+    }
+
+    return false
+  }
+}