libp2p 0.40.0 → 0.41.0-19e96cc

package/src/fetch/index.ts

@@ -14,6 +14,8 @@ import { pipe } from 'it-pipe'
 import first from 'it-first'
 import { TimeoutController } from 'timeout-abort-controller'
 import { setMaxListeners } from 'events'
+import { fromString as uint8arrayFromString } from 'uint8arrays/from-string'
+import { toString as uint8arrayToString } from 'uint8arrays/to-string'
 import type { ConnectionManager } from '@libp2p/interface-connection-manager'
 
 const log = logger('libp2p:fetch')
@@ -103,6 +105,7 @@ export class FetchService implements Startable {
 
     // create a timeout if no abort signal passed
     if (signal == null) {
+      log('using default timeout of %d ms', this.init.timeout)
       timeoutController = new TimeoutController(this.init.timeout)
       signal = timeoutController.signal
 
@@ -113,13 +116,15 @@ export class FetchService implements Startable {
     }
 
     try {
-      stream = await connection.newStream([this.protocol], {
+      stream = await connection.newStream(this.protocol, {
         signal
       })
 
       // make stream abortable
       const source = abortableDuplex(stream, signal)
 
+      log('fetch %s', key)
+
       const result = await pipe(
         [FetchRequest.encode({ identifier: key })],
         lp.encode(),
@@ -136,16 +141,20 @@ export class FetchService implements Startable {
 
           switch (response.status) {
             case (FetchResponse.StatusCode.OK): {
+              log('received status for %s ok', key)
               return response.data
             }
             case (FetchResponse.StatusCode.NOT_FOUND): {
+              log('received status for %s not found', key)
               return null
             }
             case (FetchResponse.StatusCode.ERROR): {
-              const errmsg = (new TextDecoder()).decode(response.data)
+              log('received status for %s error', key)
+              const errmsg = uint8arrayToString(response.data)
               throw errCode(new Error('Error in fetch protocol response: ' + errmsg), codes.ERR_INVALID_PARAMETERS)
             }
             default: {
+              log('received status for %s unknown', key)
               throw errCode(new Error('Unknown response status'), codes.ERR_INVALID_MESSAGE)
             }
           }
@@ -189,14 +198,18 @@ export class FetchService implements Startable {
         let response: FetchResponse
         const lookup = self._getLookupFunction(request.identifier)
         if (lookup != null) {
+          log('look up data with identifier %s', request.identifier)
           const data = await lookup(request.identifier)
           if (data != null) {
+            log('sending status for %s ok', request.identifier)
             response = { status: FetchResponse.StatusCode.OK, data }
           } else {
+            log('sending status for %s not found', request.identifier)
             response = { status: FetchResponse.StatusCode.NOT_FOUND, data: new Uint8Array(0) }
           }
         } else {
-          const errmsg = (new TextEncoder()).encode('No lookup function registered for key: ' + request.identifier)
+          log('sending status for %s error', request.identifier)
+          const errmsg = uint8arrayFromString(`No lookup function registered for key: ${request.identifier}`)
           response = { status: FetchResponse.StatusCode.ERROR, data: errmsg }
         }
 
@@ -222,6 +235,13 @@ export class FetchService implements Startable {
   /**
    * Registers a new lookup callback that can map keys to values, for a given set of keys that
    * share the same prefix
+   *
+   * @example
+   *
+   * ```js
+   * // ...
+   * libp2p.fetchService.registerLookupFunction('/prefix', (key) => { ... })
+   * ```
    */
   registerLookupFunction (prefix: string, lookup: LookupFunction) {
     if (this.lookupFunctions.has(prefix)) {
@@ -234,6 +254,13 @@ export class FetchService implements Startable {
   /**
    * Registers a new lookup callback that can map keys to values, for a given set of keys that
    * share the same prefix.
+   *
+   * @example
+   *
+   * ```js
+   * // ...
+   * libp2p.fetchService.unregisterLookupFunction('/prefix')
+   * ```
    */
   unregisterLookupFunction (prefix: string, lookup?: LookupFunction) {
     if (lookup != null) {

package/src/get-peer.ts

@@ -1,6 +1,6 @@
 import { peerIdFromString } from '@libp2p/peer-id'
 import type { Multiaddr } from '@multiformats/multiaddr'
-import { multiaddr, isMultiaddr } from '@multiformats/multiaddr'
+import { isMultiaddr } from '@multiformats/multiaddr'
 import errCode from 'err-code'
 import { codes } from './errors.js'
 import { isPeerId } from '@libp2p/interface-peer-id'
@@ -28,9 +28,9 @@ function peerIdFromMultiaddr (ma: Multiaddr) {
 }
 
 /**
- * Converts the given `peer` to a `Peer` object.
+ * Converts the given `peer` to a `PeerInfo` object.
  */
-export function getPeer (peer: PeerId | Multiaddr | string): PeerInfo {
+export function getPeer (peer: PeerId | Multiaddr): PeerInfo {
   if (isPeerId(peer)) {
     return {
       id: peer,
@@ -39,10 +39,6 @@ export function getPeer (peer: PeerId | Multiaddr | string): PeerInfo {
     }
   }
 
-  if (typeof peer === 'string') {
-    peer = multiaddr(peer)
-  }
-
   let addr
 
   if (isMultiaddr(peer)) {

package/src/index.ts

@@ -1,32 +1,43 @@
+/**
+ * @packageDocumentation
+ *
+ * Use the `createLibp2p` function to create a libp2p node.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { createLibp2p } from 'libp2p'
+ *
+ * const node = await createLibp2p({
+ *   // ...other options
+ * })
+ * ```
+ */
+
 import { createLibp2pNode } from './libp2p.js'
-import type { AbortOptions, RecursivePartial } from '@libp2p/interfaces'
-import type { EventEmitter } from '@libp2p/interfaces/events'
-import type { Startable } from '@libp2p/interfaces/startable'
-import type { Multiaddr } from '@multiformats/multiaddr'
+import type { RecursivePartial } from '@libp2p/interfaces'
+import type { Multiaddr, Resolver } from '@multiformats/multiaddr'
 import type { FaultTolerance } from './transport-manager.js'
 import type { IdentifyServiceInit } from './identify/index.js'
 import type { DualDHT } from '@libp2p/interface-dht'
 import type { Datastore } from 'interface-datastore'
-import type { PeerStore, PeerStoreInit } from '@libp2p/interface-peer-store'
+import type { AddressSorter, PeerStoreInit } from '@libp2p/interface-peer-store'
 import type { PeerId } from '@libp2p/interface-peer-id'
 import type { AutoRelayConfig, RelayAdvertiseConfig } from './circuit/index.js'
 import type { PeerDiscovery } from '@libp2p/interface-peer-discovery'
-import type { Connection, ConnectionGater, ConnectionProtector, Stream } from '@libp2p/interface-connection'
+import type { ConnectionGater, ConnectionProtector } from '@libp2p/interface-connection'
 import type { Transport } from '@libp2p/interface-transport'
 import type { StreamMuxerFactory } from '@libp2p/interface-stream-muxer'
 import type { ConnectionEncrypter } from '@libp2p/interface-connection-encrypter'
 import type { PeerRouting } from '@libp2p/interface-peer-routing'
 import type { ContentRouting } from '@libp2p/interface-content-routing'
 import type { PubSub } from '@libp2p/interface-pubsub'
-import type { Registrar, StreamHandler, StreamHandlerOptions } from '@libp2p/interface-registrar'
-import type { ConnectionManager } from '@libp2p/interface-connection-manager'
-import type { Metrics, MetricsInit } from '@libp2p/interface-metrics'
+import type { Metrics } from '@libp2p/interface-metrics'
 import type { PeerInfo } from '@libp2p/interface-peer-info'
-import type { KeyChain } from './keychain/index.js'
-import type { ConnectionManagerInit } from './connection-manager/index.js'
 import type { PingServiceInit } from './ping/index.js'
 import type { FetchServiceInit } from './fetch/index.js'
 import type { Components } from './components.js'
+import type { Libp2p } from '@libp2p/interface-libp2p'
 
 export interface PersistentPeerStoreOptions {
   threshold?: number
@@ -97,123 +108,253 @@ export interface RefreshManagerConfig {
   bootDelay: number
 }
 
+export interface ConnectionManagerConfig {
+  /**
+   * The maximum number of connections libp2p is willing to have before it starts disconnecting. Defaults to `Infinity`
+   */
+  maxConnections: number
+
+  /**
+   * The minimum number of connections below which libp2p not activate preemptive disconnections. Defaults to `0`.
+   */
+  minConnections: number
+
+  /**
+   * Sets the maximum event loop delay (measured in milliseconds) this node is willing to endure before it starts disconnecting peers. Defaults to `Infinity`.
+   */
+  maxEventLoopDelay?: number
+
+  /**
+   * Sets the poll interval (in milliseconds) for assessing the current state and determining if this peer needs to force a disconnect. Defaults to `2000` (2 seconds).
+   */
+  pollInterval?: number
+
+  /**
+   * If true, try to connect to all discovered peers up to the connection manager limit
+   */
+  autoDial?: boolean
+
+  /**
+   * How long to wait between attempting to keep our number of concurrent connections
+   * above minConnections
+   */
+  autoDialInterval: number
+
+  /**
+   * Sort the known addresses of a peer before trying to dial
+   */
+  addressSorter?: AddressSorter
+
+  /**
+   * Number of max concurrent dials
+   */
+  maxParallelDials?: number
+
+  /**
+   * Number of max addresses to dial for a given peer
+   */
+  maxAddrsToDial?: number
+
+  /**
+   * How long a dial attempt is allowed to take, including DNS resolution
+   * of the multiaddr, opening a socket and upgrading it to a Connection.
+   */
+  dialTimeout?: number
+
+  /**
+   * When a new inbound connection is opened, the upgrade process (e.g. protect,
+   * encrypt, multiplex etc) must complete within this number of ms.
+   */
+  inboundUpgradeTimeout: number
+
+  /**
+   * Number of max concurrent dials per peer
+   */
+  maxDialsPerPeer?: number
+
+  /**
+   * Multiaddr resolvers to use when dialing
+   */
+  resolvers?: Record<string, Resolver>
+
+  /**
+   * On startup we try to dial any peer that has previously been
+   * tagged with KEEP_ALIVE up to this timeout in ms. (default: 60000)
+   */
+  startupReconnectTimeout?: number
+
+  /**
+   * A list of multiaddrs that will always be allowed (except if they are in the
+   * deny list) to open connections to this node even if we've reached maxConnections
+   */
+  allow?: string[]
+
+  /**
+   * A list of multiaddrs that will never be allowed to open connections to
+   * this node under any circumstances
+   */
+  deny?: string[]
+
+  /**
+   * If more than this many connections are opened per second by a single
+   * host, reject subsequent connections
+   */
+  inboundConnectionThreshold?: number
+
+  /**
+   * The maximum number of parallel incoming connections allowed that have yet to
+   * complete the connection upgrade - e.g. choosing connection encryption, muxer, etc
+   */
+  maxIncomingPendingConnections?: number
+}
+
+/**
+ * For Libp2p configurations and modules details read the [Configuration Document](./CONFIGURATION.md).
+ */
 export interface Libp2pInit {
+  /**
+   * peerId instance (it will be created if not provided)
+   */
   peerId: PeerId
+
+  /**
+   * Addresses for transport listening and to advertise to the network
+   */
   addresses: AddressesConfig
-  connectionManager: ConnectionManagerInit
+
+  /**
+   * libp2p Connection Manager configuration
+   */
+  connectionManager: ConnectionManagerConfig
   connectionGater: Partial<ConnectionGater>
+
+  /**
+   * libp2p transport manager configuration
+   */
   transportManager: TransportManagerConfig
-  datastore: Datastore
-  metrics: MetricsInit
-  peerStore: PeerStoreInit
-  peerRouting: PeerRoutingConfig
-  keychain: KeychainConfig
-  nat: NatManagerConfig
-  relay: RelayConfig
-  identify: IdentifyServiceInit
-  ping: PingServiceInit
-  fetch: FetchServiceInit
 
-  transports: Array<(components: Components) => Transport>
-  streamMuxers?: Array<(components: Components) => StreamMuxerFactory>
-  connectionEncryption?: Array<(components: Components) => ConnectionEncrypter>
-  peerDiscovery?: Array<(components: Components) => PeerDiscovery>
-  peerRouters?: Array<(components: Components) => PeerRouting>
-  contentRouters?: Array<(components: Components) => ContentRouting>
-  dht?: (components: Components) => DualDHT
-  pubsub?: (components: Components) => PubSub
-  connectionProtector?: (components: Components) => ConnectionProtector
-}
+  /**
+   * An optional datastore to persist peer information, DHT records, etc.
+   *
+   * An in-memory datastore will be used if one is not provided.
+   */
+  datastore: Datastore
 
-export interface Libp2pEvents {
-  'peer:discovery': CustomEvent<PeerInfo>
-}
+  /**
+   * libp2p PeerStore configuration
+   */
+  peerStore: PeerStoreInit
 
-export interface Libp2p extends Startable, EventEmitter<Libp2pEvents> {
-  peerId: PeerId
-  peerStore: PeerStore
-  peerRouting: PeerRouting
-  contentRouting: ContentRouting
-  keychain: KeyChain
-  connectionManager: ConnectionManager
-  registrar: Registrar
-  metrics?: Metrics
-  pubsub: PubSub
-  dht: DualDHT
-
-  /**
-   * Get a deduplicated list of peer advertising multiaddrs by concatenating
-   * the listen addresses used by transports with any configured
-   * announce addresses as well as observed addresses reported by peers.
-   *
-   * If Announce addrs are specified, configured listen addresses will be
-   * ignored though observed addresses will still be included.
+  /**
+   * libp2p Peer routing service configuration
    */
-  getMultiaddrs: () => Multiaddr[]
+  peerRouting: PeerRoutingConfig
 
   /**
-   * Return a list of all connections this node has open, optionally filtering
-   * by a PeerId
+   * keychain configuration
    */
-  getConnections: (peerId?: PeerId) => Connection[]
+  keychain: KeychainConfig
+  nat: NatManagerConfig
+  relay: RelayConfig
 
   /**
-   * Return a list of all peers we currently have a connection open to
+   * libp2p identify protocol options
    */
-  getPeers: () => PeerId[]
+  identify: IdentifyServiceInit
 
   /**
-   * Dials to the provided peer. If successful, the known metadata of the
-   * peer will be added to the nodes `peerStore`
+   * libp2p ping protocol options
    */
-  dial: (peer: PeerId | Multiaddr, options?: AbortOptions) => Promise<Connection>
+  ping: PingServiceInit
 
   /**
-   * Dials to the provided peer and tries to handshake with the given protocols in order.
-   * If successful, the known metadata of the peer will be added to the nodes `peerStore`,
-   * and the `MuxedStream` will be returned together with the successful negotiated protocol.
+   * libp2p fetch protocol options
    */
-  dialProtocol: (peer: PeerId | Multiaddr, protocols: string | string[], options?: AbortOptions) => Promise<Stream>
+  fetch: FetchServiceInit
 
   /**
-   * Disconnects all connections to the given `peer`
+   * An array that must include at least 1 compliant transport
    */
-  hangUp: (peer: PeerId | Multiaddr | string) => Promise<void>
+  transports: Array<(components: Components) => Transport>
+  streamMuxers?: Array<(components: Components) => StreamMuxerFactory>
+  connectionEncryption?: Array<(components: Components) => ConnectionEncrypter>
+  peerDiscovery?: Array<(components: Components) => PeerDiscovery>
+  peerRouters?: Array<(components: Components) => PeerRouting>
+  contentRouters?: Array<(components: Components) => ContentRouting>
 
   /**
-   * Registers the `handler` for each protocol
+   * Pass a DHT implementation to enable DHT operations
    */
-  handle: (protocol: string | string[], handler: StreamHandler, options?: StreamHandlerOptions) => Promise<void>
+  dht?: (components: Components) => DualDHT
 
   /**
-   * Removes the handler for each protocol. The protocol
-   * will no longer be supported on streams.
+   * A Metrics implementation can be supplied to collect metrics on this node
    */
-  unhandle: (protocols: string[] | string) => Promise<void>
+  metrics?: (components: Components) => Metrics
 
   /**
-   * Pings the given peer in order to obtain the operation latency
+   * If a PubSub implmentation is supplied, PubSub operations will become available
    */
-  ping: (peer: Multiaddr | PeerId, options?: AbortOptions) => Promise<number>
+  pubsub?: (components: Components) => PubSub
 
   /**
-   * Sends a request to fetch the value associated with the given key from the given peer.
+   * A ConnectionProtector can be used to create a secure overlay on top of the network using pre-shared keys
    */
-  fetch: (peer: PeerId | Multiaddr | string, key: string, options?: AbortOptions) => Promise<Uint8Array | null>
+  connectionProtector?: (components: Components) => ConnectionProtector
+}
 
+/**
+ * Once you have a libp2p instance, you can listen to several events it emits, so that you can be notified of relevant network events.
+ */
+export interface Libp2pEvents {
   /**
-   * Returns the public key for the passed PeerId. If the PeerId is of the 'RSA' type
-   * this may mean searching the DHT if the key is not present in the KeyStore.
+   * @example
+   *
+   * ```js
+   * libp2p.addEventListener('peer:discovery', (event) => {
+   *    const peerInfo = event.detail
+   *    // ...
+   * })
+   * ```
    */
-  getPublicKey: (peer: PeerId, options?: AbortOptions) => Promise<Uint8Array>
+  'peer:discovery': CustomEvent<PeerInfo>
 }
 
-export type Libp2pOptions = RecursivePartial<Libp2pInit>
+export type { Libp2p }
+
+export type Libp2pOptions = RecursivePartial<Libp2pInit> & { start?: boolean }
 
 /**
  * Returns a new instance of the Libp2p interface, generating a new PeerId
  * if one is not passed as part of the options.
+ *
+ * The node will be started unless `start: false` is passed as an option.
+ *
+ * @example
+ *
+ * ```js
+ * import { createLibp2p } from 'libp2p'
+ * import { tcp } from '@libp2p/tcp'
+ * import { mplex } from '@libp2p/mplex'
+ * import { noise } from '@chainsafe/libp2p-noise'
+ *
+ * // specify options
+ * const options = {
+ *   transports: [tcp()],
+ *   streamMuxers: [mplex()],
+ *   connectionEncryption: [noise()]
+ * }
+ *
+ * // create libp2p
+ * const libp2p = await createLibp2p(options)
+ * ```
  */
 export async function createLibp2p (options: Libp2pOptions): Promise<Libp2p> {
-  return await createLibp2pNode(options)
+  const node = await createLibp2pNode(options)
+
+  if (options.start !== false) {
+    await node.start()
+  }
+
+  return node
 }

package/src/insecure/index.ts

@@ -1,3 +1,27 @@
+/**
+ * @packageDocumentation
+ *
+ * A connection encrypter that does no connection encryption.
+ *
+ * This should not be used in production should be used for research purposes only.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { createLibp2p } from 'libp2p'
+ * import { plaintext } from 'libp2p/insecure'
+ *
+ * // Create a Uint8Array and write the swarm key to it
+ * const swarmKey = new Uint8Array(95)
+ * generateKey(swarmKey)
+ *
+ * const node = await createLibp2p({
+ *   // ...other options
+ *   connectionEncryption: [plaintext()]
+ * })
+ * ```
+ */
+
 import { logger } from '@libp2p/logger'
 import { handshake } from 'it-handshake'
 import * as lp from 'it-length-prefixed'

package/src/keychain/index.ts

@@ -118,7 +118,7 @@ export interface KeyChainComponents {
  */
 export class KeyChain implements Startable {
   private readonly components: KeyChainComponents
-  private init: KeyChainInit
+  private readonly init: KeyChainInit
   private started: boolean
 
   /**

package/src/libp2p.ts

@@ -14,7 +14,6 @@ import { AutoDialler } from './connection-manager/auto-dialler.js'
 import { Circuit } from './circuit/transport.js'
 import { Relay } from './circuit/index.js'
 import { KeyChain } from './keychain/index.js'
-import { DefaultMetrics } from './metrics/index.js'
 import { DefaultTransportManager } from './transport-manager.js'
 import { DefaultUpgrader } from './upgrader.js'
 import { DefaultRegistrar } from './registrar.js'
@@ -103,8 +102,8 @@ export class Libp2pNode extends EventEmitter<Libp2pEvents> implements Libp2p {
     ]
 
     // Create Metrics
-    if (init.metrics.enabled) {
-      this.metrics = this.components.metrics = new DefaultMetrics(init.metrics)
+    if (init.metrics != null) {
+      this.metrics = this.components.metrics = this.configureComponent(init.metrics(this.components))
     }
 
     this.peerStore = this.components.peerStore
@@ -374,7 +373,7 @@ export class Libp2pNode extends EventEmitter<Libp2pEvents> implements Libp2p {
     return this.components.addressManager.getAddresses()
   }
 
-  async hangUp (peer: PeerId | Multiaddr | string): Promise<void> {
+  async hangUp (peer: PeerId | Multiaddr): Promise<void> {
     const { id } = getPeer(peer)
 
     await this.components.connectionManager.closeConnections(id)
@@ -419,7 +418,7 @@ export class Libp2pNode extends EventEmitter<Libp2pEvents> implements Libp2p {
     throw errCode(new Error(`Node not responding with its public key: ${peer.toString()}`), codes.ERR_INVALID_RECORD)
   }
 
-  async fetch (peer: PeerId | Multiaddr | string, key: string, options: AbortOptions = {}): Promise<Uint8Array | null> {
+  async fetch (peer: PeerId | Multiaddr, key: string, options: AbortOptions = {}): Promise<Uint8Array | null> {
     const { id, multiaddrs } = getPeer(peer)
 
     if (multiaddrs != null) {
@@ -429,7 +428,7 @@ export class Libp2pNode extends EventEmitter<Libp2pEvents> implements Libp2p {
     return await this.fetchService.fetch(id, key, options)
   }
 
-  async ping (peer: PeerId | Multiaddr | string, options: AbortOptions = {}): Promise<number> {
+  async ping (peer: PeerId | Multiaddr, options: AbortOptions = {}): Promise<number> {
     const { id, multiaddrs } = getPeer(peer)
 
     if (multiaddrs.length > 0) {

package/src/nat-manager.ts

@@ -149,11 +149,16 @@ export class NatManager implements Startable {
 
       const client = await this._getClient()
       const publicIp = this.externalAddress ?? await client.externalIp()
+      const isPrivate = isPrivateIp(publicIp)
 
-      if (isPrivateIp(publicIp)) {
+      if (isPrivate === true) {
         throw new Error(`${publicIp} is private - please set config.nat.externalIp to an externally routable IP or ensure you are not behind a double NAT`)
       }
 
+      if (isPrivate == null) {
+        throw new Error(`${publicIp} is not an IP address`)
+      }
+
       const publicPort = highPort()
 
       log(`opening uPnP connection from ${publicIp}:${publicPort} to ${host}:${port}`)