libp2p 0.41.0 → 0.42.0

package/src/connection-manager/index.ts

@@ -9,7 +9,7 @@ import { codes } from '../errors.js'
 import { isPeerId, PeerId } from '@libp2p/interface-peer-id'
 import { setMaxListeners } from 'events'
 import type { Connection, MultiaddrConnection } from '@libp2p/interface-connection'
-import type { ConnectionManager, Dialer } from '@libp2p/interface-connection-manager'
+import type { ConnectionManager, ConnectionManagerEvents, Dialer } from '@libp2p/interface-connection-manager'
 import * as STATUS from '@libp2p/interface-connection/status'
 import type { AddressSorter, PeerStore } from '@libp2p/interface-peer-store'
 import { isMultiaddr, multiaddr, Multiaddr, Resolver } from '@multiformats/multiaddr'
@@ -23,63 +23,27 @@ import { getPeer } from '../get-peer.js'
 
 const log = logger('libp2p:connection-manager')
 
-const defaultOptions: Partial<ConnectionManagerInit> = {
-  maxConnections: Infinity,
-  minConnections: 0,
-  maxData: Infinity,
-  maxSentData: Infinity,
-  maxReceivedData: Infinity,
-  maxEventLoopDelay: Infinity,
-  pollInterval: 2000,
-  autoDialInterval: 10000,
-  movingAverageInterval: 60000,
-  inboundConnectionThreshold: 5,
-  maxIncomingPendingConnections: 10
-}
-
-const STARTUP_RECONNECT_TIMEOUT = 60000
-
-export interface ConnectionManagerInit {
+export interface ConnectionManagerConfig {
   /**
-   * The maximum number of connections to keep open
+   * The maximum number of connections libp2p is willing to have before it starts disconnecting. Defaults to `Infinity`
    */
   maxConnections: number
 
   /**
-   * The minimum number of connections to keep open
+   * The minimum number of connections below which libp2p not activate preemptive disconnections. Defaults to `0`.
    */
   minConnections: number
 
   /**
-   * The max data (in and out), per average interval to allow
-   */
-  maxData?: number
-
-  /**
-   * The max outgoing data, per average interval to allow
-   */
-  maxSentData?: number
-
-  /**
-   * The max incoming data, per average interval to allow
-   */
-  maxReceivedData?: number
-
-  /**
-   * The upper limit the event loop can take to run
+   * 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
 
   /**
-   * How often, in milliseconds, metrics and latency should be checked
+   * 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
 
-  /**
-   * How often, in milliseconds, to compute averages
-   */
-  movingAverageInterval?: number
-
   /**
    * If true, try to connect to all discovered peers up to the connection manager limit
    */
@@ -159,11 +123,18 @@ export interface ConnectionManagerInit {
   maxIncomingPendingConnections?: number
 }
 
-export interface ConnectionManagerEvents {
-  'peer:connect': CustomEvent<PeerId>
-  'peer:disconnect': CustomEvent<PeerId>
+const defaultOptions: Partial<ConnectionManagerConfig> = {
+  maxConnections: Infinity,
+  minConnections: 0,
+  maxEventLoopDelay: Infinity,
+  pollInterval: 2000,
+  autoDialInterval: 10000,
+  inboundConnectionThreshold: 5,
+  maxIncomingPendingConnections: 10
 }
 
+const STARTUP_RECONNECT_TIMEOUT = 60000
+
 export interface DefaultConnectionManagerComponents {
   peerId: PeerId
   metrics?: Metrics
@@ -172,15 +143,17 @@ export interface DefaultConnectionManagerComponents {
   dialer: Dialer
 }
 
+export type ConnectionManagerInit = ConnectionManagerConfig
+
 /**
  * Responsible for managing known connections.
  */
 export class DefaultConnectionManager extends EventEmitter<ConnectionManagerEvents> implements ConnectionManager, Startable {
   private readonly components: DefaultConnectionManagerComponents
-  private readonly opts: Required<ConnectionManagerInit>
+  private readonly opts: ConnectionManagerInit
   private readonly connections: Map<string, Connection[]>
   private started: boolean
-  private readonly latencyMonitor: LatencyMonitor
+  private readonly latencyMonitor?: LatencyMonitor
   private readonly startupReconnectTimeout: number
   private connectOnStartupController?: TimeoutController
   private readonly dialTimeout: number
@@ -189,7 +162,7 @@ export class DefaultConnectionManager extends EventEmitter<ConnectionManagerEven
   private readonly inboundConnectionRateLimiter: RateLimiterMemory
   private incomingPendingConnections: number
 
-  constructor (components: DefaultConnectionManagerComponents, init: ConnectionManagerInit) {
+  constructor (components: DefaultConnectionManagerComponents, init: ConnectionManagerConfig) {
     super()
 
     this.opts = mergeOptions.call({ ignoreUndefined: true }, defaultOptions, init)
@@ -209,10 +182,12 @@ export class DefaultConnectionManager extends EventEmitter<ConnectionManagerEven
 
     this.started = false
 
-    this.latencyMonitor = new LatencyMonitor({
-      latencyCheckIntervalMs: init.pollInterval,
-      dataEmitIntervalMs: init.pollInterval
-    })
+    if (init.maxEventLoopDelay != null && init.maxEventLoopDelay > 0 && init.maxEventLoopDelay !== Infinity) {
+      this.latencyMonitor = new LatencyMonitor({
+        latencyCheckIntervalMs: init.pollInterval,
+        dataEmitIntervalMs: init.pollInterval
+      })
+    }
 
     try {
       // This emitter gets listened to a lot
@@ -324,9 +299,9 @@ export class DefaultConnectionManager extends EventEmitter<ConnectionManagerEven
     })
 
     // latency monitor
-    this.latencyMonitor.start()
+    this.latencyMonitor?.start()
     this._onLatencyMeasure = this._onLatencyMeasure.bind(this)
-    this.latencyMonitor.addEventListener('data', this._onLatencyMeasure)
+    this.latencyMonitor?.addEventListener('data', this._onLatencyMeasure)
 
     this.started = true
     log('started')
@@ -388,8 +363,8 @@ export class DefaultConnectionManager extends EventEmitter<ConnectionManagerEven
    * Stops the Connection Manager
    */
   async stop () {
-    this.latencyMonitor.removeEventListener('data', this._onLatencyMeasure)
-    this.latencyMonitor.stop()
+    this.latencyMonitor?.removeEventListener('data', this._onLatencyMeasure)
+    this.latencyMonitor?.stop()
 
     this.started = false
     await this._close()
@@ -606,6 +581,12 @@ export class DefaultConnectionManager extends EventEmitter<ConnectionManagerEven
    */
   async _checkMaxLimit (name: keyof ConnectionManagerInit, value: number, toPrune: number = 1) {
     const limit = this.opts[name]
+
+    if (limit == null) {
+      log.trace('limit %s was not set so it cannot be applied', name)
+      return
+    }
+
     log.trace('checking limit of %s. current value: %d of %d', name, value, limit)
     if (value > limit) {
       log('%s: limit exceeded: %p, %d/%d, pruning %d connection(s)', this.components.peerId, name, value, limit, toPrune)
@@ -650,6 +631,18 @@ export class DefaultConnectionManager extends EventEmitter<ConnectionManagerEven
         return -1
       }
 
+      // if the peers have an equal tag value then we want to close short-lived connections first
+      const connectionALifespan = a.stat.timeline.open
+      const connectionBLifespan = b.stat.timeline.open
+
+      if (connectionALifespan < connectionBLifespan) {
+        return 1
+      }
+
+      if (connectionALifespan > connectionBLifespan) {
+        return -1
+      }
+
       return 0
     })
 

package/src/fetch/README.md

@@ -1,8 +1,13 @@
-libp2p-fetch JavaScript Implementation
+libp2p-fetch JavaScript Implementation  <!-- omit in toc -->
 =====================================
 
 > Libp2p fetch protocol JavaScript implementation
 
+## Table of contents <!-- omit in toc -->
+
+- [Overview](#overview)
+- [Usage](#usage)
+
 ## Overview
 
 An implementation of the Fetch protocol as described here: https://github.com/libp2p/specs/tree/master/fetch
@@ -27,7 +32,7 @@ async function my_subsystem_key_lookup(key) {
 }
 
 // Enable this peer to respond to fetch requests for keys that begin with '/my_subsystem_key_prefix/'
-const libp2p = Libp2p.create(...)
+const libp2p = createLibp2p()
 libp2p.fetchService.registerLookupFunction('/my_subsystem_key_prefix/', my_subsystem_key_lookup)
 
 const key = '/my_subsystem_key_prefix/{...}'

package/src/fetch/index.ts

@@ -235,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)) {
@@ -247,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/identify/index.ts

@@ -79,7 +79,7 @@ export class IdentifyService implements Startable {
   private readonly components: IdentifyServiceComponents
   private readonly identifyProtocolStr: string
   private readonly identifyPushProtocolStr: string
-  private readonly host: {
+  public readonly host: {
     protocolVersion: string
     agentVersion: string
   }

package/src/index.ts

@@ -1,213 +1,175 @@
+/**
+ * @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 { FaultTolerance } from './transport-manager.js'
+import type { RecursivePartial } from '@libp2p/interfaces'
+import type { TransportManagerInit } 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 { PeerStoreInit } from '@libp2p/interface-peer-store'
 import type { PeerId } from '@libp2p/interface-peer-id'
-import type { AutoRelayConfig, RelayAdvertiseConfig } from './circuit/index.js'
+import type { RelayConfig } 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 } 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'
+import type { KeyChainInit } from './keychain/index.js'
+import type { NatManagerInit } from './nat-manager.js'
+import type { AddressManagerInit } from './address-manager/index.js'
+import type { PeerRoutingInit } from './peer-routing.js'
+import type { ConnectionManagerInit } from './connection-manager/index.js'
 
-export interface PersistentPeerStoreOptions {
-  threshold?: number
-}
-
-export interface DEKConfig {
-  keyLength: number
-  iterationCount: number
-  salt: string
-  hash: string
-}
-
-export interface KeychainConfig {
-  pass?: string
-  dek?: DEKConfig
-}
-
-export interface MetricsConfig {
-  enabled?: boolean
-}
-
-export interface HopConfig {
-  enabled?: boolean
-  active?: boolean
-  timeout: number
-}
-
-export interface RelayConfig {
-  enabled: boolean
-  advertise: RelayAdvertiseConfig
-  hop: HopConfig
-  autoRelay: AutoRelayConfig
-}
-
-export interface NatManagerConfig {
-  enabled: boolean
-  externalAddress?: string
-  localAddress?: string
-  description?: string
-  ttl?: number
-  keepAlive: boolean
-  gateway?: string
-}
-
-export interface AddressesConfig {
-  listen: string[]
-  announce: string[]
-  noAnnounce: string[]
-  announceFilter: (multiaddrs: Multiaddr[]) => Multiaddr[]
-}
+/**
+ * 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
 
-export interface TransportManagerConfig {
-  faultTolerance?: FaultTolerance
-}
+  /**
+   * Addresses for transport listening and to advertise to the network
+   */
+  addresses: AddressManagerInit
 
-export interface PeerStoreConfig {
-  persistence?: boolean
-  threshold?: number
-}
+  /**
+   * libp2p Connection Manager configuration
+   */
+  connectionManager: ConnectionManagerInit
 
-export interface PeerRoutingConfig {
-  refreshManager: RefreshManagerConfig
-}
+  /**
+   * A connection gater can deny new connections based on user criteria
+   */
+  connectionGater: Partial<ConnectionGater>
 
-export interface RefreshManagerConfig {
-  enabled?: boolean
-  interval: number
-  bootDelay: number
-}
+  /**
+   * libp2p transport manager configuration
+   */
+  transportManager: TransportManagerInit
 
-export interface Libp2pInit {
-  peerId: PeerId
-  addresses: AddressesConfig
-  connectionManager: ConnectionManagerInit
-  connectionGater: Partial<ConnectionGater>
-  transportManager: TransportManagerConfig
+  /**
+   * An optional datastore to persist peer information, DHT records, etc.
+   *
+   * An in-memory datastore will be used if one is not provided.
+   */
   datastore: Datastore
+
+  /**
+   * libp2p PeerStore configuration
+   */
   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
-  metrics?: (components: Components) => Metrics
-  pubsub?: (components: Components) => PubSub
-  connectionProtector?: (components: Components) => ConnectionProtector
-}
+  /**
+   * libp2p Peer routing service configuration
+   */
+  peerRouting: PeerRoutingInit
 
-export interface Libp2pEvents {
-  'peer:discovery': CustomEvent<PeerInfo>
-}
+  /**
+   * keychain configuration
+   */
+  keychain: KeyChainInit
 
-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.
+  /**
+   * The NAT manager controls uPNP hole punching
    */
-  getMultiaddrs: () => Multiaddr[]
+  nat: NatManagerInit
 
   /**
-   * Return a list of all connections this node has open, optionally filtering
-   * by a PeerId
+   * If configured as a relay this node will relay certain
+   * types of traffic for other peers
    */
-  getConnections: (peerId?: PeerId) => Connection[]
+  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) => 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: PeerId | Multiaddr, 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, 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 { Libp2p }
+
 export type Libp2pOptions = RecursivePartial<Libp2pInit> & { start?: boolean }
 
 /**
@@ -215,6 +177,25 @@ export type Libp2pOptions = RecursivePartial<Libp2pInit> & { start?: boolean }
  * 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> {
   const node = await createLibp2pNode(options)

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

@@ -17,7 +17,7 @@ import type { Datastore } from 'interface-datastore'
 
 const log = logger('libp2p:keychain')
 
-export interface DekOptions {
+export interface DEKConfig {
   hash: string
   salt: string
   iterationCount: number
@@ -26,7 +26,7 @@ export interface DekOptions {
 
 export interface KeyChainInit {
   pass?: string
-  dek?: DekOptions
+  dek?: DEKConfig
 }
 
 /**