@libp2p/identify 1.0.21 → 2.0.0-4ad63bb79

package/src/index.ts

@@ -3,7 +3,16 @@
  *
  * Use the `identify` function to add support for the [Identify protocol](https://github.com/libp2p/specs/blob/master/identify/README.md) to libp2p.
  *
- * @example
+ * This protocol allows network peers to discover the multiaddrs the current node listens on, and the protocols it supports.
+ *
+ * A second function, `identifyPush` is also exported to add support for [identify/push](https://github.com/libp2p/specs/blob/master/identify/README.md#identifypush).
+ *
+ * This protocol will send updates to all connected peers when the multiaddrs or protocols of the current node change.
+ *
+ * > [!TIP]
+ * > For maximum network compatibility you should configure both protocols
+ *
+ * @example Enabling identify
  *
  * ```typescript
  * import { createLibp2p } from 'libp2p'
@@ -16,19 +25,32 @@
  *   }
  * })
  * ```
+ *
+ * @example Enabling identify push
+ *
+ * ```typescript
+ * import { createLibp2p } from 'libp2p'
+ * import { identifyPush } from '@libp2p/identify'
+ *
+ * const node = await createLibp2p({
+ *   // ...other options
+ *   services: {
+ *     identifyPush: identifyPush()
+ *   }
+ * })
+ * ```
  */
 
-import {
-  MULTICODEC_IDENTIFY,
-  MULTICODEC_IDENTIFY_PUSH
-} from './consts.js'
+import { IdentifyPush as IdentifyPushClass } from './identify-push.js'
 import { Identify as IdentifyClass } from './identify.js'
 import type { AbortOptions, IdentifyResult, Libp2pEvents, ComponentLogger, NodeInfo, TypedEventTarget, PeerId, PeerStore, Connection } from '@libp2p/interface'
 import type { AddressManager, ConnectionManager, Registrar } from '@libp2p/interface-internal'
 
 export interface IdentifyInit {
   /**
-   * The prefix to use for the protocol (default: 'ipfs')
+   * The prefix to use for the protocol
+   *
+   * @default 'ipfs'
    */
   protocolPrefix?: string
 
@@ -39,36 +61,73 @@ export interface IdentifyInit {
 
   /**
    * How long we should wait for a remote peer to send their identify response
+   *
+   * @default 5000
    */
   timeout?: number
 
   /**
-   * Identify responses larger than this in bytes will be rejected (default: 8192)
+   * Identify responses larger than this in bytes will be rejected
+   *
+   * @default 8192
    */
-  maxIdentifyMessageSize?: number
+  maxMessageSize?: number
 
+  /**
+   * The maximum number of inbound streams that may be open on a single
+   * connection for this protocol
+   *
+   * @default 1
+   */
   maxInboundStreams?: number
+
+  /**
+   * The maximum number of outbound streams that may be open on a single
+   * connection for this protocol
+   *
+   * @default 1
+   */
   maxOutboundStreams?: number
 
-  maxPushIncomingStreams?: number
-  maxPushOutgoingStreams?: number
+  /**
+   * The maximum number of observed addresses to send in an Identify message
+   */
   maxObservedAddresses?: number
 
   /**
-   * Whether to automatically dial identify on newly opened connections (default: true)
+   * Whether to run on connections with data or duration limits
+   *
+   * @default true
+   */
+  runOnTransientConnection?: boolean
+
+  /**
+   * Whether to automatically run identify on newly opened connections
+   *
+   * @default true
    */
   runOnConnectionOpen?: boolean
+}
 
+export interface IdentifyPushInit extends Omit<IdentifyInit, 'runOnConnectionOpen'> {
   /**
-   * Whether to run on connections with data or duration limits (default: true)
+   * Whether to automatically dial identify-push on self updates
+   *
+   * @default true
    */
-  runOnTransientConnection?: boolean
+  runOnSelfUpdate?: boolean
+
+  /**
+   * Push to this many connections in parallel
+   *
+   * @default 32
+   */
+  concurrency?: number
 }
 
 export interface IdentifyComponents {
   peerId: PeerId
   peerStore: PeerStore
-  connectionManager: ConnectionManager
   registrar: Registrar
   addressManager: AddressManager
   events: TypedEventTarget<Libp2pEvents>
@@ -76,12 +135,8 @@ export interface IdentifyComponents {
   nodeInfo: NodeInfo
 }
 
-/**
- * The protocols the Identify service supports
- */
-export const multicodecs = {
-  IDENTIFY: MULTICODEC_IDENTIFY,
-  IDENTIFY_PUSH: MULTICODEC_IDENTIFY_PUSH
+export interface IdentifyPushComponents extends IdentifyComponents {
+  connectionManager: ConnectionManager
 }
 
 export interface Identify {
@@ -93,10 +148,16 @@ export interface Identify {
    * you may be better off configuring a topology to be notified instead.
    */
   identify(connection: Connection, options?: AbortOptions): Promise<IdentifyResult>
+}
 
+export interface IdentifyPush {
   push(): Promise<void>
 }
 
 export function identify (init: IdentifyInit = {}): (components: IdentifyComponents) => Identify {
   return (components) => new IdentifyClass(components, init)
 }
+
+export function identifyPush (init: IdentifyPushInit = {}): (components: IdentifyPushComponents) => IdentifyPush {
+  return (components) => new IdentifyPushClass(components, init)
+}

package/src/utils.ts

@@ -0,0 +1,273 @@
+import { CodeError } from '@libp2p/interface'
+import { peerIdFromKeys } from '@libp2p/peer-id'
+import { RecordEnvelope, PeerRecord } from '@libp2p/peer-record'
+import { type Multiaddr, multiaddr } from '@multiformats/multiaddr'
+import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
+import { isNode, isBrowser, isWebWorker, isElectronMain, isElectronRenderer, isReactNative } from 'wherearewe'
+import { IDENTIFY_PROTOCOL_VERSION, MAX_IDENTIFY_MESSAGE_SIZE, MAX_PUSH_CONCURRENCY } from './consts.js'
+import type { IdentifyComponents, IdentifyInit } from './index.js'
+import type { Identify as IdentifyMessage } from './pb/message.js'
+import type { Libp2pEvents, IdentifyResult, SignedPeerRecord, Logger, Connection, TypedEventTarget, Peer, PeerData, PeerStore, NodeInfo, Startable, PeerId, IncomingStreamData } from '@libp2p/interface'
+import type { AddressManager, Registrar } from '@libp2p/interface-internal'
+
+export const defaultValues = {
+  protocolPrefix: 'ipfs',
+  timeout: 5000,
+  maxInboundStreams: 1,
+  maxOutboundStreams: 1,
+  maxObservedAddresses: 10,
+  maxMessageSize: MAX_IDENTIFY_MESSAGE_SIZE,
+  runOnConnectionOpen: true,
+  runOnSelfUpdate: true,
+  runOnTransientConnection: true,
+  concurrency: MAX_PUSH_CONCURRENCY
+}
+
+/**
+ * Takes the `addr` and converts it to a Multiaddr if possible
+ */
+export function getCleanMultiaddr (addr: Uint8Array | string | null | undefined): Multiaddr | undefined {
+  if (addr != null && addr.length > 0) {
+    try {
+      return multiaddr(addr)
+    } catch {
+
+    }
+  }
+}
+
+export function getAgentVersion (nodeInfo: NodeInfo, agentVersion?: string): string {
+  if (agentVersion != null) {
+    return agentVersion
+  }
+
+  agentVersion = `${nodeInfo.name}/${nodeInfo.version}`
+  // Append user agent version to default AGENT_VERSION depending on the environment
+  if (isNode || isElectronMain) {
+    agentVersion += ` UserAgent=${globalThis.process.version}`
+  } else if (isBrowser || isWebWorker || isElectronRenderer || isReactNative) {
+    agentVersion += ` UserAgent=${globalThis.navigator.userAgent}`
+  }
+
+  return agentVersion
+}
+
+export async function consumeIdentifyMessage (peerStore: PeerStore, events: TypedEventTarget<Libp2pEvents>, log: Logger, connection: Connection, message: IdentifyMessage): Promise<IdentifyResult> {
+  log('received identify from %p', connection.remotePeer)
+
+  if (message == null) {
+    throw new CodeError('message was null or undefined', 'ERR_INVALID_MESSAGE')
+  }
+
+  const peer: PeerData = {}
+
+  if (message.listenAddrs.length > 0) {
+    peer.addresses = message.listenAddrs.map(buf => ({
+      isCertified: false,
+      multiaddr: multiaddr(buf)
+    }))
+  }
+
+  if (message.protocols.length > 0) {
+    peer.protocols = message.protocols
+  }
+
+  if (message.publicKey != null) {
+    peer.publicKey = message.publicKey
+
+    const peerId = await peerIdFromKeys(message.publicKey)
+
+    if (!peerId.equals(connection.remotePeer)) {
+      throw new CodeError('public key did not match remote PeerId', 'ERR_INVALID_PUBLIC_KEY')
+    }
+  }
+
+  let output: SignedPeerRecord | undefined
+
+  // if the peer record has been sent, prefer the addresses in the record as they are signed by the remote peer
+  if (message.signedPeerRecord != null) {
+    log('received signedPeerRecord from %p', connection.remotePeer)
+
+    let peerRecordEnvelope = message.signedPeerRecord
+    const envelope = await RecordEnvelope.openAndCertify(peerRecordEnvelope, PeerRecord.DOMAIN)
+    let peerRecord = PeerRecord.createFromProtobuf(envelope.payload)
+
+    // Verify peerId
+    if (!peerRecord.peerId.equals(envelope.peerId)) {
+      throw new CodeError('signing key does not match PeerId in the PeerRecord', 'ERR_INVALID_SIGNING_KEY')
+    }
+
+    // Make sure remote peer is the one sending the record
+    if (!connection.remotePeer.equals(peerRecord.peerId)) {
+      throw new CodeError('signing key does not match remote PeerId', 'ERR_INVALID_PEER_RECORD_KEY')
+    }
+
+    let existingPeer: Peer | undefined
+
+    try {
+      existingPeer = await peerStore.get(peerRecord.peerId)
+    } catch (err: any) {
+      if (err.code !== 'ERR_NOT_FOUND') {
+        throw err
+      }
+    }
+
+    if (existingPeer != null) {
+      // don't lose any existing metadata
+      peer.metadata = existingPeer.metadata
+
+      // if we have previously received a signed record for this peer, compare it to the incoming one
+      if (existingPeer.peerRecordEnvelope != null) {
+        const storedEnvelope = await RecordEnvelope.createFromProtobuf(existingPeer.peerRecordEnvelope)
+        const storedRecord = PeerRecord.createFromProtobuf(storedEnvelope.payload)
+
+        // ensure seq is greater than, or equal to, the last received
+        if (storedRecord.seqNumber >= peerRecord.seqNumber) {
+          log('sequence number was lower or equal to existing sequence number - stored: %d received: %d', storedRecord.seqNumber, peerRecord.seqNumber)
+          peerRecord = storedRecord
+          peerRecordEnvelope = existingPeer.peerRecordEnvelope
+        }
+      }
+    }
+
+    // store the signed record for next time
+    peer.peerRecordEnvelope = peerRecordEnvelope
+
+    // override the stored addresses with the signed multiaddrs
+    peer.addresses = peerRecord.multiaddrs.map(multiaddr => ({
+      isCertified: true,
+      multiaddr
+    }))
+
+    output = {
+      seq: peerRecord.seqNumber,
+      addresses: peerRecord.multiaddrs
+    }
+  } else {
+    log('%p did not send a signed peer record', connection.remotePeer)
+  }
+
+  log('patching %p with', connection.remotePeer, peer)
+  await peerStore.patch(connection.remotePeer, peer)
+
+  if (message.agentVersion != null || message.protocolVersion != null) {
+    const metadata: Record<string, Uint8Array> = {}
+
+    if (message.agentVersion != null) {
+      metadata.AgentVersion = uint8ArrayFromString(message.agentVersion)
+    }
+
+    if (message.protocolVersion != null) {
+      metadata.ProtocolVersion = uint8ArrayFromString(message.protocolVersion)
+    }
+
+    log('merging %p metadata', connection.remotePeer, metadata)
+    await peerStore.merge(connection.remotePeer, {
+      metadata
+    })
+  }
+
+  const result: IdentifyResult = {
+    peerId: connection.remotePeer,
+    protocolVersion: message.protocolVersion,
+    agentVersion: message.agentVersion,
+    publicKey: message.publicKey,
+    listenAddrs: message.listenAddrs.map(buf => multiaddr(buf)),
+    observedAddr: message.observedAddr == null ? undefined : multiaddr(message.observedAddr),
+    protocols: message.protocols,
+    signedPeerRecord: output,
+    connection
+  }
+
+  events.safeDispatchEvent('peer:identify', { detail: result })
+
+  return result
+}
+
+export interface AbstractIdentifyInit extends IdentifyInit {
+  protocol: string
+  log: Logger
+}
+
+export abstract class AbstractIdentify implements Startable {
+  public readonly host: {
+    protocolVersion: string
+    agentVersion: string
+  }
+
+  protected protocol: string
+  protected started: boolean
+  protected readonly timeout: number
+  protected readonly peerId: PeerId
+  protected readonly peerStore: PeerStore
+  protected readonly registrar: Registrar
+  protected readonly addressManager: AddressManager
+  private readonly maxInboundStreams: number
+  private readonly maxOutboundStreams: number
+  protected readonly maxMessageSize: number
+  protected readonly maxObservedAddresses: number
+  protected readonly events: TypedEventTarget<Libp2pEvents>
+  protected readonly runOnTransientConnection: boolean
+  protected readonly log: Logger
+
+  constructor (components: IdentifyComponents, init: AbstractIdentifyInit) {
+    this.protocol = init.protocol
+    this.started = false
+    this.peerId = components.peerId
+    this.peerStore = components.peerStore
+    this.registrar = components.registrar
+    this.addressManager = components.addressManager
+    this.events = components.events
+    this.log = init.log
+
+    this.timeout = init.timeout ?? defaultValues.timeout
+    this.maxInboundStreams = init.maxInboundStreams ?? defaultValues.maxInboundStreams
+    this.maxOutboundStreams = init.maxOutboundStreams ?? defaultValues.maxOutboundStreams
+    this.maxMessageSize = init.maxMessageSize ?? defaultValues.maxMessageSize
+    this.maxObservedAddresses = init.maxObservedAddresses ?? defaultValues.maxObservedAddresses
+    this.runOnTransientConnection = init.runOnTransientConnection ?? defaultValues.runOnTransientConnection
+
+    // Store self host metadata
+    this.host = {
+      protocolVersion: `${init.protocolPrefix ?? defaultValues.protocolPrefix}/${IDENTIFY_PROTOCOL_VERSION}`,
+      agentVersion: getAgentVersion(components.nodeInfo, init.agentVersion)
+    }
+  }
+
+  isStarted (): boolean {
+    return this.started
+  }
+
+  async start (): Promise<void> {
+    if (this.started) {
+      return
+    }
+
+    await this.peerStore.merge(this.peerId, {
+      metadata: {
+        AgentVersion: uint8ArrayFromString(this.host.agentVersion),
+        ProtocolVersion: uint8ArrayFromString(this.host.protocolVersion)
+      }
+    })
+
+    await this.registrar.handle(this.protocol, (data) => {
+      void this.handleProtocol(data).catch(err => {
+        this.log.error(err)
+      })
+    }, {
+      maxInboundStreams: this.maxInboundStreams,
+      maxOutboundStreams: this.maxOutboundStreams,
+      runOnTransientConnection: this.runOnTransientConnection
+    })
+
+    this.started = true
+  }
+
+  async stop (): Promise<void> {
+    await this.registrar.unhandle(this.protocol)
+
+    this.started = false
+  }
+
+  protected abstract handleProtocol (data: IncomingStreamData): Promise<void>
+}

package/dist/typedoc-urls.json

@@ -1,12 +0,0 @@
-{
-  "Identify": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_identify.Identify.html",
-  ".:Identify": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_identify.Identify.html",
-  "IdentifyComponents": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_identify.IdentifyComponents.html",
-  ".:IdentifyComponents": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_identify.IdentifyComponents.html",
-  "IdentifyInit": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_identify.IdentifyInit.html",
-  ".:IdentifyInit": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_identify.IdentifyInit.html",
-  "multicodecs": "https://libp2p.github.io/js-libp2p/variables/_libp2p_identify.multicodecs.html",
-  ".:multicodecs": "https://libp2p.github.io/js-libp2p/variables/_libp2p_identify.multicodecs.html",
-  "identify": "https://libp2p.github.io/js-libp2p/functions/_libp2p_identify.identify-1.html",
-  ".:identify": "https://libp2p.github.io/js-libp2p/functions/_libp2p_identify.identify-1.html"
-}