@libp2p/kad-dht 15.0.2 → 15.1.0-aa25d38ab

package/src/content-routing/index.ts

@@ -1,7 +1,6 @@
 import { PeerSet } from '@libp2p/peer-collections'
-import map from 'it-map'
-import parallel from 'it-parallel'
-import { pipe } from 'it-pipe'
+import { Queue } from '@libp2p/utils/queue'
+import { pushable } from 'it-pushable'
 import { ALPHA } from '../constants.js'
 import { MessageType } from '../message/dht.js'
 import { toPbPeerInfo } from '../message/utils.js'
@@ -10,7 +9,7 @@ import {
   peerResponseEvent,
   providerEvent
 } from '../query/events.js'
-import type { KadDHTComponents, PeerResponseEvent, ProviderEvent, QueryEvent } from '../index.js'
+import type { FinalPeerEvent, KadDHTComponents, PeerResponseEvent, ProviderEvent, QueryEvent } from '../index.js'
 import type { Message } from '../message/dht.js'
 import type { Network } from '../network.js'
 import type { PeerRouting } from '../peer-routing/index.js'
@@ -98,51 +97,76 @@ export class ContentRouting {
     }
 
     let sent = 0
+    const self = this
+
+    async function * publishProviderRecord (event: FinalPeerEvent): AsyncGenerator<QueryEvent, void, undefined> {
+      try {
+        self.log('sending provider record for %s to %p', key, event.peer.id)
+
+        for await (const addProviderEvent of self.network.sendMessage(event.peer.id, msg, {
+          ...options,
+          path: event.path
+        })) {
+          if (addProviderEvent.name === 'PEER_RESPONSE') {
+            self.log('sent provider record for %s to %p', key, event.peer.id)
+            sent++
+          }
 
-    const maybeNotifyPeer = (event: QueryEvent) => {
-      return async () => {
-        if (event.name !== 'FINAL_PEER') {
-          return [event]
+          yield addProviderEvent
         }
+      } catch (err: any) {
+        self.log.error('error sending provide record to peer %p', event.peer.id, err)
+        yield queryErrorEvent({
+          from: event.peer.id,
+          error: err,
+          path: event.path
+        }, options)
+      }
+    }
 
-        const events = []
+    const events = pushable<QueryEvent>({
+      objectMode: true
+    })
 
-        this.log('putProvider %s to %p', key, event.peer.id)
+    const queue = new Queue({
+      concurrency: ALPHA
+    })
+    queue.addEventListener('idle', () => {
+      events.end()
+    })
+    queue.addEventListener('error', (err) => {
+      this.log.error('error publishing provider record to peer - %e', err)
+    })
 
-        try {
-          this.log('sending provider record for %s to %p', key, event.peer.id)
+    queue.add(async () => {
+      const finalPeerEvents: FinalPeerEvent[] = []
 
-          for await (const sendEvent of this.network.sendMessage(event.peer.id, msg, options)) {
-            if (sendEvent.name === 'PEER_RESPONSE') {
-              this.log('sent provider record for %s to %p', key, event.peer.id)
-              sent++
-            }
+      for await (const event of this.peerRouting.getClosestPeers(target, options)) {
+        events.push(event)
 
-            events.push(sendEvent)
-          }
-        } catch (err: any) {
-          this.log.error('error sending provide record to peer %p', event.peer.id, err)
-          events.push(queryErrorEvent({ from: event.peer.id, error: err }, options))
+        if (event.name !== 'FINAL_PEER') {
+          continue
         }
 
-        return events
+        finalPeerEvents.push(event)
       }
-    }
 
-    // Notify closest peers
-    yield * pipe(
-      this.peerRouting.getClosestPeers(target, options),
-      (source) => map(source, (event) => maybeNotifyPeer(event)),
-      (source) => parallel(source, {
-        ordered: false,
-        concurrency: ALPHA
-      }),
-      async function * (source) {
-        for await (const events of source) {
-          yield * events
-        }
-      }
-    )
+      finalPeerEvents.forEach(event => {
+        queue.add(async () => {
+          for await (const notifyEvent of publishProviderRecord(event)) {
+            events.push(notifyEvent)
+          }
+        })
+          .catch(err => {
+            this.log.error('error publishing provider record to peer - %e', err)
+          })
+      })
+    })
+      .catch(err => {
+        events.end(err)
+      })
+
+    yield * events
 
     this.log('sent provider records to %d peers', sent)
   }
@@ -154,7 +178,7 @@ export class ContentRouting {
     const toFind = this.routingTable.kBucketSize
     let found = 0
     const target = key.multihash.bytes
-    const self = this // eslint-disable-line @typescript-eslint/no-this-alias
+    const self = this
 
     this.log('findProviders %c', key)
 
@@ -181,8 +205,27 @@ export class ContentRouting {
         }
       }
 
-      yield peerResponseEvent({ from: this.components.peerId, messageType: MessageType.GET_PROVIDERS, providers }, options)
-      yield providerEvent({ from: this.components.peerId, providers }, options)
+      yield peerResponseEvent({
+        from: this.components.peerId,
+        messageType: MessageType.GET_PROVIDERS,
+        providers,
+        path: {
+          index: -1,
+          queued: 0,
+          running: 0,
+          total: 0
+        }
+      }, options)
+      yield providerEvent({
+        from: this.components.peerId,
+        providers,
+        path: {
+          index: -1,
+          queued: 0,
+          running: 0,
+          total: 0
+        }
+      }, options)
 
       found += providers.length
 
@@ -194,15 +237,16 @@ export class ContentRouting {
     /**
      * The query function to use on this particular disjoint path
      */
-    const findProvidersQuery: QueryFunc = async function * ({ peer, signal }) {
+    const findProvidersQuery: QueryFunc = async function * ({ peer, signal, path }) {
       const request = {
         type: MessageType.GET_PROVIDERS,
         key: target
       }
 
-      yield * self.network.sendRequest(peer, request, {
+      yield * self.network.sendRequest(peer.id, request, {
         ...options,
-        signal
+        signal,
+        path
       })
     }
 
@@ -226,7 +270,11 @@ export class ContentRouting {
         }
 
         if (newProviders.length > 0) {
-          yield providerEvent({ from: event.from, providers: newProviders }, options)
+          yield providerEvent({
+            from: event.from,
+            providers: newProviders,
+            path: event.path
+          }, options)
 
           found += newProviders.length
 

package/src/index.ts

@@ -138,7 +138,7 @@ import { removePrivateAddressesMapper, removePublicAddressesMapper, passthroughM
 import type { Libp2pEvents, ComponentLogger, TypedEventTarget, Metrics, PeerId, PeerInfo, PeerStore, RoutingOptions, PrivateKey } from '@libp2p/interface'
 import type { AddressManager, ConnectionManager, Registrar } from '@libp2p/interface-internal'
 import type { Ping } from '@libp2p/ping'
-import type { AdaptiveTimeoutInit } from '@libp2p/utils/src/adaptive-timeout.js'
+import type { AdaptiveTimeoutInit } from '@libp2p/utils/adaptive-timeout'
 import type { Datastore } from 'interface-datastore'
 import type { CID } from 'multiformats/cid'
 import type { ProgressEvent } from 'progress-events'
@@ -157,7 +157,8 @@ export enum EventTypes {
   PROVIDER,
   VALUE,
   ADD_PEER,
-  DIAL_PEER
+  DIAL_PEER,
+  PATH_ENDED
 }
 
 /**
@@ -183,6 +184,13 @@ export type DHTProgressEvents =
   ProgressEvent<'kad-dht:query:add-peer', AddPeerEvent> |
   ProgressEvent<'kad-dht:query:dial-peer', DialPeerEvent>
 
+export interface DisjointPath {
+  index: number
+  queued: number
+  running: number
+  total: number
+}
+
 /**
  * Emitted when sending queries to remote peers
  */
@@ -192,6 +200,7 @@ export interface SendQueryEvent {
   name: 'SEND_QUERY'
   messageName: keyof typeof MessageType
   messageType: MessageType
+  path: DisjointPath
 }
 
 /**
@@ -207,6 +216,7 @@ export interface PeerResponseEvent {
   closer: PeerInfo[]
   providers: PeerInfo[]
   record?: DHTRecord
+  path: DisjointPath
 }
 
 /**
@@ -217,6 +227,7 @@ export interface FinalPeerEvent {
   peer: PeerInfo
   type: EventTypes.FINAL_PEER
   name: 'FINAL_PEER'
+  path: DisjointPath
 }
 
 /**
@@ -227,6 +238,7 @@ export interface QueryErrorEvent {
   type: EventTypes.QUERY_ERROR
   name: 'QUERY_ERROR'
   error: Error
+  path: DisjointPath
 }
 
 /**
@@ -237,6 +249,7 @@ export interface ProviderEvent {
   type: EventTypes.PROVIDER
   name: 'PROVIDER'
   providers: PeerInfo[]
+  path: DisjointPath
 }
 
 /**
@@ -247,6 +260,7 @@ export interface ValueEvent {
   type: EventTypes.VALUE
   name: 'VALUE'
   value: Uint8Array
+  path: DisjointPath
 }
 
 /**
@@ -256,18 +270,29 @@ export interface AddPeerEvent {
   type: EventTypes.ADD_PEER
   name: 'ADD_PEER'
   peer: PeerId
+  path: DisjointPath
 }
 
 /**
- * Emitted when peers are dialled as part of a query
+ * Emitted when peers are dialled and a new stream is opened as part of a query
  */
 export interface DialPeerEvent {
   peer: PeerId
   type: EventTypes.DIAL_PEER
   name: 'DIAL_PEER'
+  path: DisjointPath
+}
+
+/**
+ * Emitted when sending queries to remote peers
+ */
+export interface PathEndedEvent {
+  type: EventTypes.PATH_ENDED
+  name: 'PATH_ENDED'
+  path: DisjointPath
 }
 
-export type QueryEvent = SendQueryEvent | PeerResponseEvent | FinalPeerEvent | QueryErrorEvent | ProviderEvent | ValueEvent | AddPeerEvent | DialPeerEvent
+export type QueryEvent = SendQueryEvent | PeerResponseEvent | FinalPeerEvent | QueryErrorEvent | ProviderEvent | ValueEvent | AddPeerEvent | DialPeerEvent | PathEndedEvent
 
 export interface RoutingTable {
   size: number
@@ -278,6 +303,24 @@ export interface PeerInfoMapper {
 }
 
 export interface KadDHT {
+  /**
+   * This is the maximum size of the k-buckets and how many peers are looked up
+   * when searching for peers close to a key.
+   */
+  readonly k: number
+
+  /**
+   * Query concurrency factor - this controls how many peers we contact in
+   * parallel during a query.
+   */
+  readonly a: number
+
+  /**
+   * From section 4.4 of the S/Kademlia paper - this is how many disjoint paths
+   * are used during a query.
+   */
+  readonly d: number
+
   /**
    * Get a value from the DHT, the final ValueEvent will be the best value
    */
@@ -436,6 +479,22 @@ export interface KadDHTInit {
    */
   kBucketSplitThreshold?: number
 
+  /**
+   * How many peers are queried in parallel during a query.
+   *
+   * @default 3
+   */
+  alpha?: number
+
+  /**
+   * How many disjoint paths are used during a query
+   *
+   * @see https://telematics.tm.kit.edu/publications/Files/267/SKademlia_2007.pdf - section 4.4
+   *
+   * @default alpha
+   */
+  disjointPaths?: number
+
   /**
    * How many bits of the KAD-ID of peers to use when creating the routing
    * table.
@@ -506,8 +565,8 @@ export interface KadDHTInit {
   initialQuerySelfInterval?: number
 
   /**
-   * After startup by default all queries will be paused until the initial
-   * self-query has run and there are some peers in the routing table.
+   * After startup by default all queries will be paused until there is at least
+   * one peer in the routing table.
    *
    * Pass true here to disable this behavior.
    *

package/src/kad-dht.ts

@@ -2,7 +2,7 @@ import { NotFoundError, TypedEventEmitter, contentRoutingSymbol, peerDiscoverySy
 import drain from 'it-drain'
 import createMortice from 'mortice'
 import pDefer from 'p-defer'
-import { PROTOCOL } from './constants.js'
+import { ALPHA, PROTOCOL } from './constants.js'
 import { ContentFetching } from './content-fetching/index.js'
 import { ContentRouting as KADDHTContentRouting } from './content-routing/index.js'
 import { Network } from './network.js'
@@ -13,7 +13,7 @@ import { QuerySelf } from './query-self.js'
 import { selectors as recordSelectors } from './record/selectors.js'
 import { validators as recordValidators } from './record/validators.js'
 import { Reprovider } from './reprovider.js'
-import { RoutingTable } from './routing-table/index.js'
+import { KBUCKET_SIZE, RoutingTable } from './routing-table/index.js'
 import { RoutingTableRefresh } from './routing-table/refresh.js'
 import { RPC } from './rpc/index.js'
 import { TopologyListener } from './topology-listener.js'
@@ -113,6 +113,9 @@ export interface OperationMetrics {
  * Original implementation in go: https://github.com/libp2p/go-libp2p-kad-dht.
  */
 export class KadDHT extends TypedEventEmitter<PeerDiscoveryEvents> implements KadDHTInterface, Startable {
+  public readonly k: number
+  public readonly a: number
+  public readonly d: number
   public protocol: string
   public routingTable: RoutingTable
   public providers: Providers
@@ -122,7 +125,6 @@ export class KadDHT extends TypedEventEmitter<PeerDiscoveryEvents> implements Ka
   public readonly components: KadDHTComponents
   private readonly log: Logger
   private running: boolean
-  private readonly kBucketSize: number
   private clientMode: boolean
   private readonly validators: Validators
   private readonly selectors: Selectors
@@ -161,8 +163,10 @@ export class KadDHT extends TypedEventEmitter<PeerDiscoveryEvents> implements Ka
     this.running = false
     this.components = components
     this.log = components.logger.forComponent(logPrefix)
+    this.k = init.kBucketSize ?? KBUCKET_SIZE
+    this.a = init.alpha ?? ALPHA
+    this.d = init.disjointPaths ?? this.a
     this.protocol = init.protocol ?? PROTOCOL
-    this.kBucketSize = init.kBucketSize ?? 20
     this.clientMode = init.clientMode ?? true
     this.maxInboundStreams = init.maxInboundStreams ?? DEFAULT_MAX_INBOUND_STREAMS
     this.maxOutboundStreams = init.maxOutboundStreams ?? DEFAULT_MAX_OUTBOUND_STREAMS
@@ -192,7 +196,7 @@ export class KadDHT extends TypedEventEmitter<PeerDiscoveryEvents> implements Ka
     })
 
     this.routingTable = new RoutingTable(components, {
-      kBucketSize: init.kBucketSize,
+      kBucketSize: this.k,
       pingOldContactTimeout: init.pingOldContactTimeout,
       pingOldContactConcurrency: init.pingOldContactConcurrency,
       pingOldContactMaxQueueSize: init.pingOldContactMaxQueueSize,
@@ -218,12 +222,13 @@ export class KadDHT extends TypedEventEmitter<PeerDiscoveryEvents> implements Ka
     }
 
     this.queryManager = new QueryManager(components, {
-      // Number of disjoint query paths to use - This is set to `kBucketSize/2` per the S/Kademlia paper
-      disjointPaths: Math.ceil(this.kBucketSize / 2),
+      disjointPaths: this.d,
+      alpha: this.a,
       logPrefix,
       metricsPrefix,
       initialQuerySelfHasRun,
-      routingTable: this.routingTable
+      routingTable: this.routingTable,
+      allowQueryWithZeroPeers: init.allowQueryWithZeroPeers
     })
 
     // DHT components
@@ -276,7 +281,6 @@ export class KadDHT extends TypedEventEmitter<PeerDiscoveryEvents> implements Ka
       initialInterval: init.initialQuerySelfInterval,
       logPrefix,
       initialQuerySelfHasRun,
-      routingTable: this.routingTable,
       operationMetrics
     })
     this.reprovider = new Reprovider(components, {
@@ -317,7 +321,7 @@ export class KadDHT extends TypedEventEmitter<PeerDiscoveryEvents> implements Ka
 
         await this.onPeerConnect(peerData)
       }).catch(err => {
-        this.log.error('could not add %p to routing table - %e', peerId, err)
+        this.log.error('could not add %p to routing table - %e - %e', peerId, err)
       })
     })
 

package/src/message/dht.ts

@@ -1,11 +1,6 @@
-/* eslint-disable import/export */
-/* eslint-disable complexity */
-/* eslint-disable @typescript-eslint/no-namespace */
-/* eslint-disable @typescript-eslint/no-unnecessary-boolean-literal-compare */
-/* eslint-disable @typescript-eslint/no-empty-interface */
-
-import { type Codec, decodeMessage, type DecodeOptions, encodeMessage, enumeration, MaxLengthError, message } from 'protons-runtime'
+import { decodeMessage, encodeMessage, enumeration, MaxLengthError, message } from 'protons-runtime'
 import { alloc as uint8ArrayAlloc } from 'uint8arrays/alloc'
+import type { Codec, DecodeOptions } from 'protons-runtime'
 import type { Uint8ArrayList } from 'uint8arraylist'
 
 export interface Record {

package/src/network.ts

@@ -1,17 +1,18 @@
 import { InvalidParametersError, TypedEventEmitter } from '@libp2p/interface'
 import { Libp2pRecord } from '@libp2p/record'
-import { AdaptiveTimeout, type AdaptiveTimeoutInit } from '@libp2p/utils/adaptive-timeout'
+import { AdaptiveTimeout } from '@libp2p/utils/adaptive-timeout'
 import { pbStream } from 'it-protobuf-stream'
 import { Message } from './message/dht.js'
 import { fromPbPeerInfo } from './message/utils.js'
 import {
-  dialPeerEvent,
   sendQueryEvent,
   peerResponseEvent,
-  queryErrorEvent
+  queryErrorEvent,
+  dialPeerEvent
 } from './query/events.js'
-import type { KadDHTComponents, QueryEvent } from './index.js'
+import type { DisjointPath, KadDHTComponents, QueryEvent } from './index.js'
 import type { AbortOptions, Logger, Stream, PeerId, PeerInfo, Startable, RoutingOptions, CounterGroup } from '@libp2p/interface'
+import type { AdaptiveTimeoutInit } from '@libp2p/utils/adaptive-timeout'
 
 export interface NetworkInit {
   protocol: string
@@ -21,7 +22,16 @@ export interface NetworkInit {
 }
 
 interface NetworkEvents {
-  'peer': CustomEvent<PeerInfo>
+  peer: CustomEvent<PeerInfo>
+}
+
+export interface SendMessageOptions extends RoutingOptions {
+  /**
+   * Queries involve following up to `k` disjoint paths through the network -
+   * this option is which index within `k` this message is for, and it
+   * allows observers to collate events together on a per-path basis
+   */
+  path: DisjointPath
 }
 
 /**
@@ -142,7 +152,7 @@ export class Network extends TypedEventEmitter<NetworkEvents> implements Startab
   /**
    * Send a request and read a response
    */
-  async * sendRequest (to: PeerId, msg: Partial<Message>, options: RoutingOptions = {}): AsyncGenerator<QueryEvent> {
+  async * sendRequest (to: PeerId, msg: Partial<Message>, options: SendMessageOptions): AsyncGenerator<QueryEvent> {
     if (!this.running) {
       return
     }
@@ -153,10 +163,6 @@ export class Network extends TypedEventEmitter<NetworkEvents> implements Startab
       throw new InvalidParametersError('Message type was missing')
     }
 
-    this.log('sending %s to %p', msg.type, to)
-    yield dialPeerEvent({ peer: to }, options)
-    yield sendQueryEvent({ to, type }, options)
-
     let stream: Stream | undefined
     const signal = this.timeout.getTimeoutSignal(options)
 
@@ -168,8 +174,15 @@ export class Network extends TypedEventEmitter<NetworkEvents> implements Startab
     try {
       this.metrics.operations?.increment({ [type]: true })
 
+      this.log('dialling %p', to)
+      yield dialPeerEvent({ peer: to, path: options.path }, options)
+
       const connection = await this.components.connectionManager.openConnection(to, options)
       stream = await connection.newStream(this.protocol, options)
+
+      this.log('sending %s to %p', msg.type, to)
+      yield sendQueryEvent({ to, type, path: options.path }, options)
+
       const response = await this._writeReadMessage(stream, msg, options)
 
       stream.close(options)
@@ -183,7 +196,8 @@ export class Network extends TypedEventEmitter<NetworkEvents> implements Startab
         messageType: response.type,
         closer: response.closer.map(fromPbPeerInfo),
         providers: response.providers.map(fromPbPeerInfo),
-        record: response.record == null ? undefined : Libp2pRecord.deserialize(response.record)
+        record: response.record == null ? undefined : Libp2pRecord.deserialize(response.record),
+        path: options.path
       }, options)
     } catch (err: any) {
       this.metrics.errors?.increment({ [type]: true })
@@ -196,7 +210,7 @@ export class Network extends TypedEventEmitter<NetworkEvents> implements Startab
         this.log.error('could not send %s to %p - %e', msg.type, to, err)
       }
 
-      yield queryErrorEvent({ from: to, error: err }, options)
+      yield queryErrorEvent({ from: to, error: err, path: options.path }, options)
     } finally {
       this.timeout.cleanUp(signal)
     }
@@ -205,7 +219,7 @@ export class Network extends TypedEventEmitter<NetworkEvents> implements Startab
   /**
    * Sends a message without expecting an answer
    */
-  async * sendMessage (to: PeerId, msg: Partial<Message>, options: RoutingOptions = {}): AsyncGenerator<QueryEvent> {
+  async * sendMessage (to: PeerId, msg: Partial<Message>, options: SendMessageOptions): AsyncGenerator<QueryEvent> {
     if (!this.running) {
       return
     }
@@ -216,10 +230,6 @@ export class Network extends TypedEventEmitter<NetworkEvents> implements Startab
       throw new InvalidParametersError('Message type was missing')
     }
 
-    this.log('sending %s to %p', msg.type, to)
-    yield dialPeerEvent({ peer: to }, options)
-    yield sendQueryEvent({ to, type }, options)
-
     let stream: Stream | undefined
     const signal = this.timeout.getTimeoutSignal(options)
 
@@ -231,9 +241,15 @@ export class Network extends TypedEventEmitter<NetworkEvents> implements Startab
     try {
       this.metrics.operations?.increment({ [type]: true })
 
+      this.log('dialling %p', to)
+      yield dialPeerEvent({ peer: to, path: options.path }, options)
+
       const connection = await this.components.connectionManager.openConnection(to, options)
       stream = await connection.newStream(this.protocol, options)
 
+      this.log('sending %s to %p', msg.type, to)
+      yield sendQueryEvent({ to, type, path: options.path }, options)
+
       await this._writeMessage(stream, msg, options)
 
       stream.close(options)
@@ -242,12 +258,12 @@ export class Network extends TypedEventEmitter<NetworkEvents> implements Startab
           stream?.abort(err)
         })
 
-      yield peerResponseEvent({ from: to, messageType: type }, options)
+      yield peerResponseEvent({ from: to, messageType: type, path: options.path }, options)
     } catch (err: any) {
       this.metrics.errors?.increment({ [type]: true })
 
       stream?.abort(err)
-      yield queryErrorEvent({ from: to, error: err }, options)
+      yield queryErrorEvent({ from: to, error: err, path: options.path }, options)
     } finally {
       this.timeout.cleanUp(signal)
     }
@@ -262,9 +278,7 @@ export class Network extends TypedEventEmitter<NetworkEvents> implements Startab
   }
 
   /**
-   * Write a message and read its response.
-   * If no response is received after the specified timeout
-   * this will error out.
+   * Write a message and read a response
    */
   async _writeReadMessage (stream: Stream, msg: Partial<Message>, options: AbortOptions): Promise<Message> {
     const pb = pbStream(stream)

package/src/peer-distance-list.ts

@@ -1,11 +1,13 @@
 import { xor as uint8ArrayXor } from 'uint8arrays/xor'
 import { xorCompare as uint8ArrayXorCompare } from 'uint8arrays/xor-compare'
 import { convertPeerId } from './utils.js'
+import type { DisjointPath } from './index.js'
 import type { PeerId, PeerInfo } from '@libp2p/interface'
 
 interface PeerDistance {
   peer: PeerInfo
   distance: Uint8Array
+  path: DisjointPath
 }
 
 /**
@@ -40,30 +42,40 @@ export class PeerDistanceList {
   /**
    * The peers in the list, in order of distance from the origin key
    */
-  get peers (): PeerInfo[] {
-    return this.peerDistances.map(pd => pd.peer)
+  get peers (): PeerDistance[] {
+    return [...this.peerDistances]
   }
 
   /**
    * Add a peerId to the list.
    */
-  async add (peer: PeerInfo): Promise<void> {
+  async add (peer: PeerInfo, path: DisjointPath = { index: -1, queued: 0, running: 0, total: 0 }): Promise<void> {
     const dhtKey = await convertPeerId(peer.id)
 
-    this.addWithKadId(peer, dhtKey)
+    this.addWithKadId(peer, dhtKey, path)
   }
 
   /**
    * Add a peerId to the list.
    */
-  addWithKadId (peer: PeerInfo, kadId: Uint8Array): void {
+  addWithKadId (peer: PeerInfo, kadId: Uint8Array, path: DisjointPath = { index: -1, queued: 0, running: 0, total: 0 }): void {
     if (this.peerDistances.find(pd => pd.peer.id.equals(peer.id)) != null) {
       return
     }
 
-    const el = {
+    const el: PeerDistance = {
       peer,
-      distance: uint8ArrayXor(this.originDhtKey, kadId)
+      distance: uint8ArrayXor(this.originDhtKey, kadId),
+      path
+    }
+
+    if (this.peerDistances.length === this.capacity) {
+      const lastPeer = this.peerDistances[this.peerDistances.length - 1]
+
+      // only add if it's closer than our furthest peer
+      if (lastPeer != null && uint8ArrayXorCompare(el.distance, lastPeer.distance) !== -1) {
+        return
+      }
     }
 
     let added = false