@libp2p/kad-dht 11.0.8 → 12.0.0-4e0135c7d

package/src/index.ts

@@ -1,12 +1,94 @@
-import { DefaultDualKadDHT } from './dual-kad-dht.js'
+/**
+ * @packageDocumentation
+ *
+ * This module implements the [libp2p Kademlia spec](https://github.com/libp2p/specs/blob/master/kad-dht/README.md) in TypeScript.
+ *
+ * The Kademlia DHT allow for several operations such as finding peers, searching for providers of DHT records, etc.
+ *
+ * @example Using with libp2p
+ *
+ * ```TypeScript
+ * import { kadDHT } from '@libp2p/kad-dht'
+ * import { createLibp2p } from 'libp2p'
+ * import { peerIdFromString } from '@libp2p/peer-id'
+ *
+ * const node = await createLibp2p({
+ *   services: {
+ *     dht: kadDHT()
+ *   }
+ * })
+ *
+ * const peerId = peerIdFromString('QmFoo')
+ * const peerInfo = await libp2p.peerRouting.findPeer(peerId)
+ *
+ * console.info(peerInfo) // peer id, multiaddrs
+ * ```
+ *
+ * @example Connecting to the IPFS Amino DHT
+ *
+ * The [Amino DHT](https://blog.ipfs.tech/2023-09-amino-refactoring/) is a public-good DHT used by IPFS to fetch content, find peers, etc.
+ *
+ * If you are trying to access content on the public internet, this is the implementation you want.
+ *
+ * ```TypeScript
+ * import { kadDHT, removePrivateAddressesMapper } from '@libp2p/kad-dht'
+ * import { createLibp2p } from 'libp2p'
+ * import { peerIdFromString } from '@libp2p/peer-id'
+ *
+ * const node = await createLibp2p({
+ *   services: {
+ *     aminoDHT: kadDHT({
+ *       protocol: '/ipfs/kad/1.0.0',
+ *       addressFilter: removePrivateAddressesMapper
+ *     })
+ *   }
+ * })
+ *
+ * const peerId = peerIdFromString('QmFoo')
+ * const peerInfo = await libp2p.peerRouting.findPeer(peerId)
+ *
+ * console.info(peerInfo) // peer id, multiaddrs
+ * ```
+ *
+ * @example Connecting to a LAN-only DHT
+ *
+ * This DHT only works with privately dialable peers.
+ *
+ * This is for use when peers are on the local area network.
+ *
+ * ```TypeScript
+ * import { kadDHT, removePublicAddressesMapper } from '@libp2p/kad-dht'
+ * import { createLibp2p } from 'libp2p'
+ * import { peerIdFromString } from '@libp2p/peer-id'
+ *
+ * const node = await createLibp2p({
+ *   services: {
+ *     lanDHT: kadDHT({
+ *       protocol: '/ipfs/lan/kad/1.0.0',
+ *       addressFilter: removePublicAddressesMapper,
+ *       clientMode: false
+ *     })
+ *   }
+ * })
+ *
+ * const peerId = peerIdFromString('QmFoo')
+ * const peerInfo = await libp2p.peerRouting.findPeer(peerId)
+ *
+ * console.info(peerInfo) // peer id, multiaddrs
+ * ```
+ */
+
+import { KadDHT as KadDHTClass } from './kad-dht.js'
+import { removePrivateAddressesMapper, removePublicAddressesMapper, passthroughMapper } from './utils.js'
 import type { ProvidersInit } from './providers.js'
-import type { Libp2pEvents, AbortOptions, ComponentLogger, TypedEventTarget, Metrics, PeerId, PeerInfo, PeerStore } from '@libp2p/interface'
+import type { Libp2pEvents, ComponentLogger, TypedEventTarget, Metrics, PeerId, PeerInfo, PeerStore, RoutingOptions } from '@libp2p/interface'
 import type { AddressManager, ConnectionManager, Registrar } from '@libp2p/interface-internal'
 import type { Datastore } from 'interface-datastore'
 import type { CID } from 'multiformats/cid'
-import type { ProgressOptions, ProgressEvent } from 'progress-events'
+import type { ProgressEvent } from 'progress-events'
 
 export { Libp2pRecord as Record } from './record/index.js'
+export { removePrivateAddressesMapper, removePublicAddressesMapper, passthroughMapper }
 
 /**
  * The types of events emitted during DHT queries
@@ -52,10 +134,6 @@ export type DHTProgressEvents =
   ProgressEvent<'kad-dht:query:add-peer', AddPeerEvent> |
   ProgressEvent<'kad-dht:query:dial-peer', DialPeerEvent>
 
-export interface QueryOptions extends AbortOptions, ProgressOptions {
-  queryFuncTimeout?: number
-}
-
 /**
  * Emitted when sending queries to remote peers
  */
@@ -146,44 +224,49 @@ export interface RoutingTable {
   size: number
 }
 
+export interface PeerInfoMapper {
+  (peer: PeerInfo): PeerInfo
+}
+
 export interface KadDHT {
   /**
    * Get a value from the DHT, the final ValueEvent will be the best value
    */
-  get(key: Uint8Array, options?: QueryOptions): AsyncIterable<QueryEvent>
+  get(key: Uint8Array, options?: RoutingOptions): AsyncIterable<QueryEvent>
 
   /**
    * Find providers of a given CID
    */
-  findProviders(key: CID, options?: QueryOptions): AsyncIterable<QueryEvent>
+  findProviders(key: CID, options?: RoutingOptions): AsyncIterable<QueryEvent>
 
   /**
    * Find a peer on the DHT
    */
-  findPeer(id: PeerId, options?: QueryOptions): AsyncIterable<QueryEvent>
+  findPeer(id: PeerId, options?: RoutingOptions): AsyncIterable<QueryEvent>
 
   /**
    * Find the closest peers to the passed key
    */
-  getClosestPeers(key: Uint8Array, options?: QueryOptions): AsyncIterable<QueryEvent>
+  getClosestPeers(key: Uint8Array, options?: RoutingOptions): AsyncIterable<QueryEvent>
 
   /**
    * Store provider records for the passed CID on the DHT pointing to us
    */
-  provide(key: CID, options?: QueryOptions): AsyncIterable<QueryEvent>
+  provide(key: CID, options?: RoutingOptions): AsyncIterable<QueryEvent>
 
   /**
    * Store the passed value under the passed key on the DHT
    */
-  put(key: Uint8Array, value: Uint8Array, options?: QueryOptions): AsyncIterable<QueryEvent>
+  put(key: Uint8Array, value: Uint8Array, options?: RoutingOptions): AsyncIterable<QueryEvent>
 
   /**
    * Returns the mode this node is in
    */
-  getMode(): Promise<'client' | 'server'>
+  getMode(): 'client' | 'server'
 
   /**
-   * If 'server' this node will respond to DHT queries, if 'client' this node will not
+   * If 'server' this node will respond to DHT queries, if 'client' this node
+   * will not.
    */
   setMode(mode: 'client' | 'server'): Promise<void>
 
@@ -197,11 +280,6 @@ 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
@@ -226,12 +304,17 @@ export type Validators = Record<string, ValidateFn>
 
 export interface KadDHTInit {
   /**
-   * How many peers to store in each kBucket (default 20)
+   * How many peers to store in each kBucket
+   *
+   * @default 20
    */
   kBucketSize?: number
 
   /**
-   * Whether to start up as a DHT client or server
+   * If true, only ever be a DHT client. If false, be a DHT client until told
+   * to be a DHT server via `setMode`.
+   *
+   * @default false
    */
   clientMode?: boolean
 
@@ -254,7 +337,9 @@ export interface KadDHTInit {
   /**
    * During startup we run the self-query at a shorter interval to ensure
    * the containing node can respond to queries quickly. Set this interval
-   * here in ms (default: 1000)
+   * here in ms.
+   *
+   * @default 1000
    */
   initialQuerySelfInterval?: number
 
@@ -262,34 +347,55 @@ export interface KadDHTInit {
    * 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.
    *
-   * Pass true here to disable this behaviour. (default: false)
+   * Pass true here to disable this behaviour.
+   *
+   * @default false
    */
   allowQueryWithZeroPeers?: boolean
 
   /**
-   * A custom protocol prefix to use (default: '/ipfs')
+   * The network protocol to use
+   *
+   * @default "/ipfs/kad/1.0.0"
    */
-  protocolPrefix?: string
+  protocol?: string
+
+  /**
+   * The logging prefix to use
+   *
+   * @default "libp2p:kad-dht"
+   */
+  logPrefix?: string
 
   /**
    * How long to wait in ms when pinging DHT peers to decide if they
-   * should be evicted from the routing table or not (default 10000)
+   * should be evicted from the routing table or not.
+   *
+   * @default 10000
    */
   pingTimeout?: number
 
   /**
    * How many peers to ping in parallel when deciding if they should
-   * be evicted from the routing table or not (default 10)
+   * be evicted from the routing table or not
+   *
+   * @default 10
    */
   pingConcurrency?: number
 
   /**
-   * How many parallel incoming streams to allow on the DHT protocol per-connection
+   * How many parallel incoming streams to allow on the DHT protocol per
+   * connection
+   *
+   * @default 32
    */
   maxInboundStreams?: number
 
   /**
-   * How many parallel outgoing streams to allow on the DHT protocol per-connection
+   * How many parallel outgoing streams to allow on the DHT protocol per
+   * connection
+   *
+   * @default 64
    */
   maxOutboundStreams?: number
 
@@ -297,6 +403,12 @@ export interface KadDHTInit {
    * Initialization options for the Providers component
    */
   providers?: ProvidersInit
+
+  /**
+   * For every incoming and outgoing PeerInfo, override address configuration
+   * with this filter.
+   */
+  peerInfoMapper?(peer: PeerInfo): PeerInfo
 }
 
 export interface KadDHTComponents {
@@ -311,6 +423,10 @@ export interface KadDHTComponents {
   logger: ComponentLogger
 }
 
-export function kadDHT (init?: KadDHTInit): (components: KadDHTComponents) => DualKadDHT {
-  return (components: KadDHTComponents) => new DefaultDualKadDHT(components, init)
+/**
+ * Creates a custom DHT implementation, please ensure you pass a `protocol`
+ * string as an option.
+ */
+export function kadDHT (init: KadDHTInit): (components: KadDHTComponents) => KadDHT {
+  return (components: KadDHTComponents) => new KadDHTClass(components, init)
 }