@libp2p/kad-dht 9.1.2 → 9.1.4

package/src/dual-kad-dht.ts

@@ -1,34 +1,117 @@
-import { symbol } from '@libp2p/interface-peer-discovery'
+import { type ContentRouting, contentRouting } from '@libp2p/interface-content-routing'
+import { type PeerDiscovery, peerDiscovery, type PeerDiscoveryEvents } from '@libp2p/interface-peer-discovery'
+import { type PeerRouting, peerRouting } from '@libp2p/interface-peer-routing'
 import { CodeError } from '@libp2p/interfaces/errors'
 import { EventEmitter, CustomEvent } from '@libp2p/interfaces/events'
 import { logger } from '@libp2p/logger'
+import drain from 'it-drain'
 import merge from 'it-merge'
+import { DefaultKadDHT } from './kad-dht.js'
 import { queryErrorEvent } from './query/events.js'
-import type { KadDHTComponents } from './index.js'
-import type { KadDHT } from './kad-dht.js'
-import type { DualDHT, QueryEvent, QueryOptions } from '@libp2p/interface-dht'
-import type { PeerDiscoveryEvents } from '@libp2p/interface-peer-discovery'
+import type { DualKadDHT, KadDHT, KadDHTComponents, KadDHTInit, QueryEvent, QueryOptions } from './index.js'
 import type { PeerId } from '@libp2p/interface-peer-id'
+import type { PeerInfo } from '@libp2p/interface-peer-info'
 import type { AbortOptions } from '@libp2p/interfaces'
-import type { CID } from 'multiformats'
+import type { CID } from 'multiformats/cid'
 
 const log = logger('libp2p:kad-dht')
 
+/**
+ * Wrapper class to convert events into returned values
+ */
+class DHTContentRouting implements ContentRouting {
+  private readonly dht: KadDHT
+
+  constructor (dht: KadDHT) {
+    this.dht = dht
+  }
+
+  async provide (cid: CID): Promise<void> {
+    await drain(this.dht.provide(cid))
+  }
+
+  async * findProviders (cid: CID, options: AbortOptions = {}): AsyncGenerator<PeerInfo, void, undefined> {
+    for await (const event of this.dht.findProviders(cid, options)) {
+      if (event.name === 'PROVIDER') {
+        yield * event.providers
+      }
+    }
+  }
+
+  async put (key: Uint8Array, value: Uint8Array, options?: AbortOptions): Promise<void> {
+    await drain(this.dht.put(key, value, options))
+  }
+
+  async get (key: Uint8Array, options?: AbortOptions): Promise<Uint8Array> {
+    for await (const event of this.dht.get(key, options)) {
+      if (event.name === 'VALUE') {
+        return event.value
+      }
+    }
+
+    throw new CodeError('Not found', 'ERR_NOT_FOUND')
+  }
+}
+
+/**
+ * Wrapper class to convert events into returned values
+ */
+class DHTPeerRouting implements PeerRouting {
+  private readonly dht: KadDHT
+
+  constructor (dht: KadDHT) {
+    this.dht = dht
+  }
+
+  async findPeer (peerId: PeerId, options: AbortOptions = {}): Promise<PeerInfo> {
+    for await (const event of this.dht.findPeer(peerId, options)) {
+      if (event.name === 'FINAL_PEER') {
+        return event.peer
+      }
+    }
+
+    throw new CodeError('Not found', 'ERR_NOT_FOUND')
+  }
+
+  async * getClosestPeers (key: Uint8Array, options: AbortOptions = {}): AsyncIterable<PeerInfo> {
+    for await (const event of this.dht.getClosestPeers(key, options)) {
+      if (event.name === 'FINAL_PEER') {
+        yield event.peer
+      }
+    }
+  }
+}
+
 /**
  * A DHT implementation modelled after Kademlia with S/Kademlia modifications.
  * Original implementation in go: https://github.com/libp2p/go-libp2p-kad-dht.
  */
-export class DualKadDHT extends EventEmitter<PeerDiscoveryEvents> implements DualDHT {
-  public readonly wan: KadDHT
-  public readonly lan: KadDHT
+export class DefaultDualKadDHT extends EventEmitter<PeerDiscoveryEvents> implements DualKadDHT, PeerDiscovery {
+  public readonly wan: DefaultKadDHT
+  public readonly lan: DefaultKadDHT
   public readonly components: KadDHTComponents
+  private readonly contentRouting: ContentRouting
+  private readonly peerRouting: PeerRouting
 
-  constructor (components: KadDHTComponents, wan: KadDHT, lan: KadDHT) {
+  constructor (components: KadDHTComponents, init: KadDHTInit = {}) {
     super()
 
     this.components = components
-    this.wan = wan
-    this.lan = lan
+
+    this.wan = new DefaultKadDHT(components, {
+      protocolPrefix: '/ipfs',
+      ...init,
+      lan: false
+    })
+    this.lan = new DefaultKadDHT(components, {
+      protocolPrefix: '/ipfs',
+      ...init,
+      clientMode: false,
+      lan: true
+    })
+
+    this.contentRouting = new DHTContentRouting(this)
+    this.peerRouting = new DHTPeerRouting(this)
 
     // handle peers being discovered during processing of DHT messages
     this.wan.addEventListener('peer', (evt) => {
@@ -43,10 +126,20 @@ export class DualKadDHT extends EventEmitter<PeerDiscoveryEvents> implements Dua
     })
   }
 
-  readonly [symbol] = true
-
   readonly [Symbol.toStringTag] = '@libp2p/dual-kad-dht'
 
+  get [contentRouting] (): ContentRouting {
+    return this.contentRouting
+  }
+
+  get [peerRouting] (): PeerRouting {
+    return this.peerRouting
+  }
+
+  get [peerDiscovery] (): PeerDiscovery {
+    return this
+  }
+
   /**
    * Is this DHT running.
    */

package/src/index.ts

@@ -1,14 +1,7 @@
-import { type ContentRouting, contentRouting } from '@libp2p/interface-content-routing'
-import { type PeerDiscovery, peerDiscovery } from '@libp2p/interface-peer-discovery'
-import { type PeerRouting, peerRouting } from '@libp2p/interface-peer-routing'
-import { CodeError } from '@libp2p/interfaces/errors'
-import drain from 'it-drain'
-import { DualKadDHT } from './dual-kad-dht.js'
-import { KadDHT as SingleKadDHT } from './kad-dht.js'
+import { DefaultDualKadDHT } from './dual-kad-dht.js'
 import type { ProvidersInit } from './providers.js'
 import type { AddressManager } from '@libp2p/interface-address-manager'
 import type { ConnectionManager } from '@libp2p/interface-connection-manager'
-import type { DHT, DualDHT, Selectors, Validators } from '@libp2p/interface-dht'
 import type { Metrics } from '@libp2p/interface-metrics'
 import type { PeerId } from '@libp2p/interface-peer-id'
 import type { PeerInfo } from '@libp2p/interface-peer-info'
@@ -18,6 +11,212 @@ import type { AbortOptions } from '@libp2p/interfaces'
 import type { Datastore } from 'interface-datastore'
 import type { CID } from 'multiformats/cid'
 
+/**
+ * The types of events emitted during DHT queries
+ */
+export enum EventTypes {
+  SENDING_QUERY = 0,
+  PEER_RESPONSE,
+  FINAL_PEER,
+  QUERY_ERROR,
+  PROVIDER,
+  VALUE,
+  ADDING_PEER,
+  DIALING_PEER
+}
+
+/**
+ * The types of messages sent to peers during DHT queries
+ */
+export enum MessageType {
+  PUT_VALUE = 0,
+  GET_VALUE,
+  ADD_PROVIDER,
+  GET_PROVIDERS,
+  FIND_NODE,
+  PING
+}
+
+export type MessageName = keyof typeof MessageType
+
+export interface DHTRecord {
+  key: Uint8Array
+  value: Uint8Array
+  timeReceived?: Date
+}
+
+export interface QueryOptions extends AbortOptions {
+  queryFuncTimeout?: number
+}
+
+/**
+ * Emitted when sending queries to remote peers
+ */
+export interface SendingQueryEvent {
+  to: PeerId
+  type: EventTypes.SENDING_QUERY
+  name: 'SENDING_QUERY'
+  messageName: keyof typeof MessageType
+  messageType: MessageType
+}
+
+/**
+ * Emitted when query responses are received form remote peers.  Depending on the query
+ * these events may be followed by a `FinalPeerEvent`, a `ValueEvent` or a `ProviderEvent`.
+ */
+export interface PeerResponseEvent {
+  from: PeerId
+  type: EventTypes.PEER_RESPONSE
+  name: 'PEER_RESPONSE'
+  messageName: keyof typeof MessageType
+  messageType: MessageType
+  closer: PeerInfo[]
+  providers: PeerInfo[]
+  record?: DHTRecord
+}
+
+/**
+ * Emitted at the end of a `findPeer` query
+ */
+export interface FinalPeerEvent {
+  from: PeerId
+  peer: PeerInfo
+  type: EventTypes.FINAL_PEER
+  name: 'FINAL_PEER'
+}
+
+/**
+ * Something went wrong with the query
+ */
+export interface QueryErrorEvent {
+  from: PeerId
+  type: EventTypes.QUERY_ERROR
+  name: 'QUERY_ERROR'
+  error: Error
+}
+
+/**
+ * Emitted when providers are found
+ */
+export interface ProviderEvent {
+  from: PeerId
+  type: EventTypes.PROVIDER
+  name: 'PROVIDER'
+  providers: PeerInfo[]
+}
+
+/**
+ * Emitted when values are found
+ */
+export interface ValueEvent {
+  from: PeerId
+  type: EventTypes.VALUE
+  name: 'VALUE'
+  value: Uint8Array
+}
+
+/**
+ * Emitted when peers are added to a query
+ */
+export interface AddingPeerEvent {
+  type: EventTypes.ADDING_PEER
+  name: 'ADDING_PEER'
+  peer: PeerId
+}
+
+/**
+ * Emitted when peers are dialled as part of a query
+ */
+export interface DialingPeerEvent {
+  peer: PeerId
+  type: EventTypes.DIALING_PEER
+  name: 'DIALING_PEER'
+}
+
+export type QueryEvent = SendingQueryEvent | PeerResponseEvent | FinalPeerEvent | QueryErrorEvent | ProviderEvent | ValueEvent | AddingPeerEvent | DialingPeerEvent
+
+export interface RoutingTable {
+  size: number
+}
+
+export interface KadDHT {
+  /**
+   * Get a value from the DHT, the final ValueEvent will be the best value
+   */
+  get: (key: Uint8Array, options?: QueryOptions) => AsyncIterable<QueryEvent>
+
+  /**
+   * Find providers of a given CID
+   */
+  findProviders: (key: CID, options?: QueryOptions) => AsyncIterable<QueryEvent>
+
+  /**
+   * Find a peer on the DHT
+   */
+  findPeer: (id: PeerId, options?: QueryOptions) => AsyncIterable<QueryEvent>
+
+  /**
+   * Find the closest peers to the passed key
+   */
+  getClosestPeers: (key: Uint8Array, options?: QueryOptions) => AsyncIterable<QueryEvent>
+
+  /**
+   * Store provider records for the passed CID on the DHT pointing to us
+   */
+  provide: (key: CID, options?: QueryOptions) => AsyncIterable<QueryEvent>
+
+  /**
+   * Store the passed value under the passed key on the DHT
+   */
+  put: (key: Uint8Array, value: Uint8Array, options?: QueryOptions) => AsyncIterable<QueryEvent>
+
+  /**
+   * Returns the mode this node is in
+   */
+  getMode: () => Promise<'client' | 'server'>
+
+  /**
+   * If 'server' this node will respond to DHT queries, if 'client' this node will not
+   */
+  setMode: (mode: 'client' | 'server') => Promise<void>
+
+  /**
+   * Force a routing table refresh
+   */
+  refreshRoutingTable: () => Promise<void>
+}
+
+export interface SingleKadDHT extends KadDHT {
+  routingTable: RoutingTable
+}
+
+export interface DualKadDHT extends KadDHT {
+  wan: SingleKadDHT
+  lan: SingleKadDHT
+}
+
+/**
+ * A selector function takes a DHT key and a list of records and returns the
+ * index of the best record in the list
+ */
+export interface SelectFn { (key: Uint8Array, records: Uint8Array[]): number }
+
+/**
+ * A validator function takes a DHT key and the value of the record for that key
+ * and throws if the record is invalid
+ */
+export interface ValidateFn { (key: Uint8Array, value: Uint8Array): Promise<void> }
+
+/**
+ * Selectors are a map of key prefixes to selector functions
+ */
+export type Selectors = Record<string, SelectFn>
+
+/**
+ * Validators are a map of key prefixes to validator functions
+ */
+export type Validators = Record<string, ValidateFn>
+
 export interface KadDHTInit {
   /**
    * How many peers to store in each kBucket (default 20)
@@ -103,106 +302,6 @@ export interface KadDHTComponents {
   datastore: Datastore
 }
 
-/**
- * Wrapper class to convert events into returned values
- */
-export class DHTContentRouting implements ContentRouting {
-  private readonly dht: DHT
-
-  constructor (dht: DHT) {
-    this.dht = dht
-  }
-
-  async provide (cid: CID): Promise<void> {
-    await drain(this.dht.provide(cid))
-  }
-
-  async * findProviders (cid: CID, options: AbortOptions = {}): AsyncGenerator<PeerInfo, void, undefined> {
-    for await (const event of this.dht.findProviders(cid, options)) {
-      if (event.name === 'PROVIDER') {
-        yield * event.providers
-      }
-    }
-  }
-
-  async put (key: Uint8Array, value: Uint8Array, options?: AbortOptions): Promise<void> {
-    await drain(this.dht.put(key, value, options))
-  }
-
-  async get (key: Uint8Array, options?: AbortOptions): Promise<Uint8Array> {
-    for await (const event of this.dht.get(key, options)) {
-      if (event.name === 'VALUE') {
-        return event.value
-      }
-    }
-
-    throw new CodeError('Not found', 'ERR_NOT_FOUND')
-  }
-}
-
-/**
- * Wrapper class to convert events into returned values
- */
-export class DHTPeerRouting implements PeerRouting {
-  private readonly dht: DHT
-
-  constructor (dht: DHT) {
-    this.dht = dht
-  }
-
-  async findPeer (peerId: PeerId, options: AbortOptions = {}): Promise<PeerInfo> {
-    for await (const event of this.dht.findPeer(peerId, options)) {
-      if (event.name === 'FINAL_PEER') {
-        return event.peer
-      }
-    }
-
-    throw new CodeError('Not found', 'ERR_NOT_FOUND')
-  }
-
-  async * getClosestPeers (key: Uint8Array, options: AbortOptions = {}): AsyncIterable<PeerInfo> {
-    for await (const event of this.dht.getClosestPeers(key, options)) {
-      if (event.name === 'FINAL_PEER') {
-        yield event.peer
-      }
-    }
-  }
-}
-
-class KadDHT extends DualKadDHT {
-  private readonly contentRouting: ContentRouting
-  private readonly peerRouting: PeerRouting
-
-  constructor (components: KadDHTComponents, init?: KadDHTInit) {
-    super(components, new SingleKadDHT(components, {
-      protocolPrefix: '/ipfs',
-      ...init,
-      lan: false
-    }),
-    new SingleKadDHT(components, {
-      protocolPrefix: '/ipfs',
-      ...init,
-      clientMode: false,
-      lan: true
-    }))
-
-    this.contentRouting = new DHTContentRouting(this)
-    this.peerRouting = new DHTPeerRouting(this)
-  }
-
-  get [contentRouting] (): ContentRouting {
-    return this.contentRouting
-  }
-
-  get [peerRouting] (): PeerRouting {
-    return this.peerRouting
-  }
-
-  get [peerDiscovery] (): PeerDiscovery {
-    return this
-  }
-}
-
-export function kadDHT (init?: KadDHTInit): (components: KadDHTComponents) => DualDHT {
-  return (components: KadDHTComponents) => new KadDHT(components, init)
+export function kadDHT (init?: KadDHTInit): (components: KadDHTComponents) => DualKadDHT {
+  return (components: KadDHTComponents) => new DefaultDualKadDHT(components, init)
 }

package/src/kad-dht.ts

@@ -1,4 +1,3 @@
-import { symbol } from '@libp2p/interface-peer-discovery'
 import { CustomEvent, EventEmitter } from '@libp2p/interfaces/events'
 import { type Logger, logger } from '@libp2p/logger'
 import { selectors as recordSelectors } from '@libp2p/record/selectors'
@@ -20,8 +19,7 @@ import {
   removePrivateAddresses,
   removePublicAddresses
 } from './utils.js'
-import type { KadDHTComponents, KadDHTInit } from './index.js'
-import type { QueryOptions, Validators, Selectors, DHT, QueryEvent } from '@libp2p/interface-dht'
+import type { KadDHTComponents, KadDHTInit, QueryOptions, Validators, Selectors, KadDHT, QueryEvent } from './index.js'
 import type { PeerDiscoveryEvents } from '@libp2p/interface-peer-discovery'
 import type { PeerId } from '@libp2p/interface-peer-id'
 import type { PeerInfo } from '@libp2p/interface-peer-info'
@@ -41,7 +39,7 @@ export interface SingleKadDHTInit extends KadDHTInit {
  * A DHT implementation modelled after Kademlia with S/Kademlia modifications.
  * Original implementation in go: https://github.com/libp2p/go-libp2p-kad-dht.
  */
-export class KadDHT extends EventEmitter<PeerDiscoveryEvents> implements DHT {
+export class DefaultKadDHT extends EventEmitter<PeerDiscoveryEvents> implements KadDHT {
   public protocol: string
   public routingTable: RoutingTable
   public providers: Providers
@@ -219,10 +217,6 @@ export class KadDHT extends EventEmitter<PeerDiscoveryEvents> implements DHT {
     })
   }
 
-  readonly [symbol] = true
-
-  readonly [Symbol.toStringTag] = '@libp2p/kad-dht'
-
   async onPeerConnect (peerData: PeerInfo): Promise<void> {
     this.log('peer %p connected with protocols', peerData.id, peerData.protocols)
 

package/src/network.ts

@@ -13,9 +13,8 @@ import {
   peerResponseEvent,
   queryErrorEvent
 } from './query/events.js'
-import type { KadDHTComponents } from './index.js'
+import type { KadDHTComponents, QueryEvent } from './index.js'
 import type { Stream } from '@libp2p/interface-connection'
-import type { QueryEvent } from '@libp2p/interface-dht'
 import type { PeerId } from '@libp2p/interface-peer-id'
 import type { PeerInfo } from '@libp2p/interface-peer-info'
 import type { AbortOptions } from '@libp2p/interfaces'

package/src/peer-routing/index.ts

@@ -13,12 +13,11 @@ import {
   valueEvent
 } from '../query/events.js'
 import * as utils from '../utils.js'
-import type { KadDHTComponents } from '../index.js'
+import type { KadDHTComponents, DHTRecord, DialingPeerEvent, FinalPeerEvent, QueryEvent, Validators } from '../index.js'
 import type { Network } from '../network.js'
 import type { QueryManager, QueryOptions } from '../query/manager.js'
 import type { QueryFunc } from '../query/types.js'
 import type { RoutingTable } from '../routing-table/index.js'
-import type { DHTRecord, DialingPeerEvent, FinalPeerEvent, QueryEvent, Validators } from '@libp2p/interface-dht'
 import type { PeerId } from '@libp2p/interface-peer-id'
 import type { PeerInfo } from '@libp2p/interface-peer-info'
 import type { AbortOptions } from '@libp2p/interfaces'

package/src/query/events.ts

@@ -1,6 +1,6 @@
 import { MESSAGE_TYPE_LOOKUP } from '../message/index.js'
+import type { SendingQueryEvent, PeerResponseEvent, DialingPeerEvent, AddingPeerEvent, ValueEvent, ProviderEvent, QueryErrorEvent, FinalPeerEvent } from '../index.js'
 import type { Message } from '../message/dht.js'
-import type { SendingQueryEvent, PeerResponseEvent, DialingPeerEvent, AddingPeerEvent, ValueEvent, ProviderEvent, QueryErrorEvent, FinalPeerEvent } from '@libp2p/interface-dht'
 import type { PeerId } from '@libp2p/interface-peer-id'
 import type { PeerInfo } from '@libp2p/interface-peer-info'
 import type { Libp2pRecord } from '@libp2p/record'

package/src/query/manager.ts

@@ -11,7 +11,7 @@ import {
 } from '../constants.js'
 import { queryPath } from './query-path.js'
 import type { QueryFunc } from './types.js'
-import type { QueryEvent } from '@libp2p/interface-dht'
+import type { QueryEvent } from '../index.js'
 import type { Metric, Metrics } from '@libp2p/interface-metrics'
 import type { PeerId } from '@libp2p/interface-peer-id'
 import type { AbortOptions } from '@libp2p/interfaces'

package/src/query/query-path.ts

@@ -7,8 +7,8 @@ import { xor } from 'uint8arrays/xor'
 import { convertPeerId, convertBuffer } from '../utils.js'
 import { queryErrorEvent } from './events.js'
 import type { CleanUpEvents } from './manager.js'
+import type { QueryEvent } from '../index.js'
 import type { QueryFunc } from '../query/types.js'
-import type { QueryEvent } from '@libp2p/interface-dht'
 import type { PeerId } from '@libp2p/interface-peer-id'
 import type { EventEmitter } from '@libp2p/interfaces/events'
 import type { Logger } from '@libp2p/logger'

package/src/query/types.ts

@@ -1,4 +1,4 @@
-import type { QueryEvent } from '@libp2p/interface-dht'
+import type { QueryEvent } from '../index.js'
 import type { PeerId } from '@libp2p/interface-peer-id'
 
 export interface QueryContext {

package/src/rpc/handlers/put-value.ts

@@ -2,9 +2,9 @@ import { CodeError } from '@libp2p/interfaces/errors'
 import { type Logger, logger } from '@libp2p/logger'
 import { verifyRecord } from '@libp2p/record/validators'
 import { bufferToRecordKey } from '../../utils.js'
+import type { Validators } from '../../index.js'
 import type { Message } from '../../message/index.js'
 import type { DHTMessageHandler } from '../index.js'
-import type { Validators } from '@libp2p/interface-dht'
 import type { PeerId } from '@libp2p/interface-peer-id'
 import type { Datastore } from 'interface-datastore'
 

package/src/rpc/index.ts

@@ -8,10 +8,10 @@ import { GetProvidersHandler, type GetProvidersHandlerComponents } from './handl
 import { GetValueHandler, type GetValueHandlerComponents } from './handlers/get-value.js'
 import { PingHandler } from './handlers/ping.js'
 import { PutValueHandler, type PutValueHandlerComponents } from './handlers/put-value.js'
+import type { Validators } from '../index.js'
 import type { PeerRouting } from '../peer-routing'
 import type { Providers } from '../providers'
 import type { RoutingTable } from '../routing-table'
-import type { Validators } from '@libp2p/interface-dht'
 import type { PeerId } from '@libp2p/interface-peer-id'
 import type { IncomingStreamData } from '@libp2p/interface-registrar'