libp2p 0.46.4 → 0.46.5

package/src/dcutr/dcutr.ts

@@ -0,0 +1,406 @@
+import { CodeError } from '@libp2p/interface/errors'
+import { logger } from '@libp2p/logger'
+import { type Multiaddr, multiaddr } from '@multiformats/multiaddr'
+import { Circuit, IP, DNS } from '@multiformats/multiaddr-matcher'
+import delay from 'delay'
+import { pbStream } from 'it-protobuf-stream'
+import isPrivate from 'private-ip'
+import { codes } from '../errors.js'
+import { HolePunch } from './pb/message.js'
+import { multicodec } from './index.js'
+import type { DCUtRServiceComponents, DCUtRServiceInit } from './index.js'
+import type { Connection, Stream } from '@libp2p/interface/connection'
+import type { PeerStore } from '@libp2p/interface/peer-store'
+import type { Startable } from '@libp2p/interface/startable'
+import type { AddressManager } from '@libp2p/interface-internal/address-manager'
+import type { ConnectionManager } from '@libp2p/interface-internal/connection-manager'
+import type { Registrar } from '@libp2p/interface-internal/registrar'
+import type { TransportManager } from '@libp2p/interface-internal/src/transport-manager/index.js'
+
+const log = logger('libp2p:dcutr')
+
+// https://github.com/libp2p/specs/blob/master/relay/DCUtR.md#rpc-messages
+const MAX_DCUTR_MESSAGE_SIZE = 1024 * 4
+// ensure the dial has a high priority to jump to the head of the dial queue
+const DCUTR_DIAL_PRIORITY = 100
+
+const defaultValues = {
+  // https://github.com/libp2p/go-libp2p/blob/8d2e54e1637041d5cf4fac1e531287560bd1f4ac/p2p/protocol/holepunch/holepuncher.go#L27
+  timeout: 5000,
+  // https://github.com/libp2p/go-libp2p/blob/8d2e54e1637041d5cf4fac1e531287560bd1f4ac/p2p/protocol/holepunch/holepuncher.go#L28
+  retries: 3,
+  maxInboundStreams: 1,
+  maxOutboundStreams: 1
+}
+
+export class DefaultDCUtRService implements Startable {
+  private started: boolean
+  private readonly timeout: number
+  private readonly retries: number
+  private readonly maxInboundStreams: number
+  private readonly maxOutboundStreams: number
+  private readonly peerStore: PeerStore
+  private readonly registrar: Registrar
+  private readonly connectionManager: ConnectionManager
+  private readonly addressManager: AddressManager
+  private readonly transportManager: TransportManager
+  private topologyId?: string
+
+  constructor (components: DCUtRServiceComponents, init: DCUtRServiceInit) {
+    this.started = false
+    this.peerStore = components.peerStore
+    this.registrar = components.registrar
+    this.addressManager = components.addressManager
+    this.connectionManager = components.connectionManager
+    this.transportManager = components.transportManager
+
+    this.timeout = init.timeout ?? defaultValues.timeout
+    this.retries = init.retries ?? defaultValues.retries
+    this.maxInboundStreams = init.maxInboundStreams ?? defaultValues.maxInboundStreams
+    this.maxOutboundStreams = init.maxOutboundStreams ?? defaultValues.maxOutboundStreams
+  }
+
+  isStarted (): boolean {
+    return this.started
+  }
+
+  async start (): Promise<void> {
+    if (this.started) {
+      return
+    }
+
+    // register for notifications of when peers that support DCUtR connect
+    // nb. requires the identify service to be enabled
+    this.topologyId = await this.registrar.register(multicodec, {
+      onConnect: (peerId, connection) => {
+        if (!connection.transient) {
+          // the connection is already direct, no upgrade is required
+          return
+        }
+
+        // the inbound peer starts the connection upgrade
+        if (connection.direction !== 'inbound') {
+          return
+        }
+
+        this.upgradeInbound(connection)
+          .catch(err => {
+            log.error('error during outgoing DCUtR attempt', err)
+          })
+      }
+    })
+
+    await this.registrar.handle(multicodec, (data) => {
+      void this.handleIncomingUpgrade(data.stream, data.connection).catch(err => {
+        log.error('error during incoming DCUtR attempt', err)
+        data.stream.abort(err)
+      })
+    }, {
+      maxInboundStreams: this.maxInboundStreams,
+      maxOutboundStreams: this.maxOutboundStreams,
+      runOnTransientConnection: true
+    })
+
+    this.started = true
+  }
+
+  async stop (): Promise<void> {
+    await this.registrar.unhandle(multicodec)
+
+    if (this.topologyId != null) {
+      this.registrar.unregister(this.topologyId)
+    }
+
+    this.started = false
+  }
+
+  /**
+   * Perform the inbound connection upgrade as B
+   *
+   * @see https://github.com/libp2p/specs/blob/master/relay/DCUtR.md#the-protocol
+   */
+  async upgradeInbound (relayedConnection: Connection): Promise<void> {
+    // Upon observing the new connection, the inbound peer (here B) checks the
+    // addresses advertised by A via identify.
+    //
+    // If that set includes public addresses, then A may be reachable by a direct
+    // connection, in which case B attempts a unilateral connection upgrade by
+    // initiating a direct connection to A.
+    if (await this.attemptUnilateralConnectionUpgrade(relayedConnection)) {
+      return
+    }
+
+    let stream: Stream | undefined
+
+    for (let i = 0; i < this.retries; i++) {
+      const options = {
+        signal: AbortSignal.timeout(this.timeout)
+      }
+
+      try {
+        // 1. B opens a stream to A using the /libp2p/dcutr protocol.
+        stream = await relayedConnection.newStream([multicodec], {
+          signal: options.signal,
+          runOnTransientConnection: true
+        })
+
+        const pb = pbStream(stream, {
+          maxDataLength: MAX_DCUTR_MESSAGE_SIZE
+        }).pb(HolePunch)
+
+        // 2. B sends to A a Connect message containing its observed (and
+        // possibly predicted) addresses from identify and starts a timer
+        // to measure RTT of the relay connection.
+        log('B sending connect to %p', relayedConnection.remotePeer)
+        const connectTimer = Date.now()
+        await pb.write({
+          type: HolePunch.Type.CONNECT,
+          observedAddresses: this.addressManager.getAddresses().map(ma => ma.bytes)
+        }, options)
+
+        log('B receiving connect from %p', relayedConnection.remotePeer)
+        // 4. Upon receiving the Connect, B sends a Sync message
+        const connect = await pb.read(options)
+
+        if (connect.type !== HolePunch.Type.CONNECT) {
+          log('A sent wrong message type')
+          throw new CodeError('DCUtR message type was incorrect', codes.ERR_INVALID_MESSAGE)
+        }
+
+        const multiaddrs = this.getDialableMultiaddrs(connect.observedAddresses)
+
+        if (multiaddrs.length === 0) {
+          log('A did not have any dialable multiaddrs')
+          throw new CodeError('DCUtR connect message had no multiaddrs', codes.ERR_INVALID_MESSAGE)
+        }
+
+        const rtt = Date.now() - connectTimer
+
+        log('A sending sync, rtt %dms', rtt)
+        await pb.write({
+          type: HolePunch.Type.SYNC,
+          observedAddresses: []
+        }, options)
+
+        log('A waiting for half RTT')
+        // ..and starts a timer for half the RTT measured from the time between
+        // sending the initial Connect and receiving the response
+        await delay(rtt / 2)
+
+        // TODO: when we have a QUIC transport, the dial step is different - for
+        // now we only have tcp support
+        // https://github.com/libp2p/specs/blob/master/relay/DCUtR.md#the-protocol
+
+        log('B dialing', multiaddrs)
+        // Upon expiry of the timer, B dials the address to A.
+        const conn = await this.connectionManager.openConnection(multiaddrs, {
+          signal: options.signal,
+          priority: DCUTR_DIAL_PRIORITY
+        })
+
+        log('DCUtR to %p succeeded to address %a, closing relayed connection', relayedConnection.remotePeer, conn.remoteAddr)
+        await relayedConnection.close(options)
+
+        break
+      } catch (err: any) {
+        log.error('error while attempting DCUtR on attempt %d of %d', i + 1, this.retries, err)
+        stream?.abort(err)
+
+        if (i === this.retries) {
+          throw err
+        }
+      } finally {
+        if (stream != null) {
+          await stream.close(options)
+        }
+      }
+    }
+  }
+
+  /**
+   * This is performed when A has dialed B via a relay but A also has a public
+   * address that B can dial directly
+   */
+  async attemptUnilateralConnectionUpgrade (relayedConnection: Connection): Promise<boolean> {
+    // Upon observing the new connection, the inbound peer (here B) checks the
+    // addresses advertised by A via identify.
+    const peerInfo = await this.peerStore.get(relayedConnection.remotePeer)
+
+    // If that set includes public addresses, then A may be reachable by a direct
+    // connection, in which case B attempts a unilateral connection upgrade by
+    // initiating a direct connection to A.
+    const publicAddresses = peerInfo.addresses
+      .map(address => {
+        const ma = address.multiaddr
+
+        // ensure all multiaddrs have the peer id
+        if (ma.getPeerId() == null) {
+          return ma.encapsulate(`/p2p/${relayedConnection.remotePeer}`)
+        }
+
+        return ma
+      })
+      .filter(ma => {
+        return this.isPublicAndDialable(ma)
+      })
+
+    if (publicAddresses.length > 0) {
+      const signal = AbortSignal.timeout(this.timeout)
+
+      try {
+        log('attempting unilateral connection upgrade to %a', publicAddresses)
+
+        // force-dial the multiaddr(s), otherwise `connectionManager.openConnection`
+        // will return the existing relayed connection
+        const connection = await this.connectionManager.openConnection(publicAddresses, {
+          signal,
+          force: true
+        })
+
+        if (connection.transient) {
+          throw new Error('Could not open a new, non-transient, connection')
+        }
+
+        log('unilateral connection upgrade to %p succeeded via %a, closing relayed connection', relayedConnection.remotePeer, connection.remoteAddr)
+        await relayedConnection.close()
+
+        return true
+      } catch (err) {
+        log.error('unilateral connection upgrade to %p on addresses %a failed', relayedConnection.remotePeer, publicAddresses, err)
+      }
+    } else {
+      log('peer %p has no public addresses, not attempting unilateral connection upgrade', relayedConnection.remotePeer)
+    }
+
+    // no public addresses or failed to dial public addresses
+    return false
+  }
+
+  /**
+   * Perform the connection upgrade as A
+   *
+   * @see https://github.com/libp2p/specs/blob/master/relay/DCUtR.md#the-protocol
+   */
+  async handleIncomingUpgrade (stream: Stream, relayedConnection: Connection): Promise<void> {
+    const options = {
+      signal: AbortSignal.timeout(this.timeout)
+    }
+
+    try {
+      const pb = pbStream(stream, {
+        maxDataLength: MAX_DCUTR_MESSAGE_SIZE
+      }).pb(HolePunch)
+
+      log('A receiving connect')
+      // 3. Upon receiving the Connect, A responds back with a Connect message
+      // containing its observed (and possibly predicted) addresses.
+      const connect = await pb.read(options)
+
+      if (connect.type !== HolePunch.Type.CONNECT) {
+        log('B sent wrong message type')
+        throw new CodeError('DCUtR message type was incorrect', codes.ERR_INVALID_MESSAGE)
+      }
+
+      if (connect.observedAddresses.length === 0) {
+        log('B sent no multiaddrs')
+        throw new CodeError('DCUtR connect message had no multiaddrs', codes.ERR_INVALID_MESSAGE)
+      }
+
+      const multiaddrs = this.getDialableMultiaddrs(connect.observedAddresses)
+
+      if (multiaddrs.length === 0) {
+        log('B had no dialable multiaddrs')
+        throw new CodeError('DCUtR connect message had no dialable multiaddrs', codes.ERR_INVALID_MESSAGE)
+      }
+
+      log('A sending connect')
+      await pb.write({
+        type: HolePunch.Type.CONNECT,
+        observedAddresses: this.addressManager.getAddresses().map(ma => ma.bytes)
+      })
+
+      log('A receiving sync')
+      const sync = await pb.read(options)
+
+      if (sync.type !== HolePunch.Type.SYNC) {
+        throw new CodeError('DCUtR message type was incorrect', codes.ERR_INVALID_MESSAGE)
+      }
+
+      // TODO: when we have a QUIC transport, the dial step is different - for
+      // now we only have tcp support
+      // https://github.com/libp2p/specs/blob/master/relay/DCUtR.md#the-protocol
+
+      // Upon receiving the Sync, A immediately dials the address to B
+      log('A dialing', multiaddrs)
+      const connection = await this.connectionManager.openConnection(multiaddrs, {
+        signal: options.signal,
+        priority: DCUTR_DIAL_PRIORITY,
+        force: true
+      })
+
+      log('DCUtR to %p succeeded via %a, closing relayed connection', relayedConnection.remotePeer, connection.remoteAddr)
+      await relayedConnection.close(options)
+    } catch (err: any) {
+      log.error('incoming DCUtR from %p failed', relayedConnection.remotePeer, err)
+      stream.abort(err)
+    } finally {
+      await stream.close(options)
+    }
+  }
+
+  /**
+   * Takes the `addr` and converts it to a Multiaddr if possible
+   */
+  getDialableMultiaddrs (addrs: Array<Uint8Array | string | null | undefined>): Multiaddr[] {
+    const output = []
+
+    for (const addr of addrs) {
+      if (addr == null || addr.length === 0) {
+        continue
+      }
+
+      try {
+        const ma = multiaddr(addr)
+
+        if (!this.isPublicAndDialable(ma)) {
+          continue
+        }
+
+        output.push(ma)
+      } catch {}
+    }
+
+    return output
+  }
+
+  /**
+   * Returns true if the passed multiaddr is public, not relayed and we have a
+   * transport that can dial it
+   */
+  isPublicAndDialable (ma: Multiaddr): boolean {
+    // ignore circuit relay
+    if (Circuit.matches(ma)) {
+      return false
+    }
+
+    // dns addresses are probably public?
+    if (DNS.matches(ma)) {
+      return true
+    }
+
+    // ensure we have only IPv4/IPv6 addresses
+    if (!IP.matches(ma)) {
+      return false
+    }
+
+    const transport = this.transportManager.transportForMultiaddr(ma)
+
+    if (transport == null) {
+      return false
+    }
+
+    const options = ma.toOptions()
+
+    return isPrivate(options.host) === false
+  }
+}

package/src/dcutr/index.ts

@@ -0,0 +1,102 @@
+/**
+ * @packageDocumentation
+ *
+ * Direct Connection Upgrade through Relay (DCUtR) is a protocol that allows two
+ * nodes to connect to each other who would otherwise be prevented doing so due
+ * to being behind NATed connections or firewalls.
+ *
+ * The protocol involves making a relayed connection between the two peers and
+ * using the relay to synchronise connection timings so that they dial each other
+ * at precisely the same moment.
+ *
+ * @example
+ *
+ * ```ts
+ * import { createLibp2p } from 'libp2p'
+ * import { circuitRelayTransport } from 'libp2p/circuit-relay'
+ * import { tcp } from '@libp2p/tcp'
+ * import { identifyService } from 'libp2p/identify'
+ * import { dCUtRService } from 'libp2p/dcutr'
+ *
+ * const node = await createLibp2p({
+ *   transports: [
+ *     circuitRelayTransport(),
+ *     tcp()
+ *   ],
+ *   services: {
+ *     identify: identifyService(),
+ *     dcutr: dcutrService()
+ *   }
+ * })
+ *
+ * // QmTarget is a peer that is behind a NAT, supports TCP and has a relay
+ * // reservation
+ * await node.dial('/ip4/.../p2p/QmRelay/p2p-circuit/p2p/QmTarget')
+ *
+ * // after a while the connection should automatically get upgraded to a
+ * // direct connection (e.g. non-transient)
+ * while (true) {
+ *   const connections = node.getConnections()
+ *
+ *   if (connections.find(conn => conn.transient === false)) {
+ *     console.info('have direct connection')
+ *     break
+ *   } else {
+ *     console.info('have relayed connection')
+ *
+ *     // wait a few seconds to see if it's succeeded yet
+ *     await new Promise((resolve) => {
+ *       setTimeout(() => resolve(), 5000)
+ *     })
+ *   }
+ * }
+ * ```
+ */
+
+import { DefaultDCUtRService } from './dcutr.js'
+import type { PeerStore } from '@libp2p/interface/peer-store'
+import type { AddressManager } from '@libp2p/interface-internal/address-manager'
+import type { ConnectionManager } from '@libp2p/interface-internal/connection-manager'
+import type { Registrar } from '@libp2p/interface-internal/registrar'
+import type { TransportManager } from '@libp2p/interface-internal/transport-manager'
+
+export interface DCUtRServiceInit {
+  /**
+   * How long we should wait for the connection upgrade to complete (default: 5s)
+   */
+  timeout?: number
+
+  /**
+   * How many times to retry the connection upgrade (default: 3)
+   */
+  retries?: number
+
+  /**
+   * How many simultaneous inbound DCUtR protocol streams to allow on each
+   * connection (default: 1)
+   */
+  maxInboundStreams?: number
+
+  /**
+   * How many simultaneous outbound DCUtR protocol streams to allow on each
+   * connection (default: 1)
+   */
+  maxOutboundStreams?: number
+}
+
+export interface DCUtRServiceComponents {
+  peerStore: PeerStore
+  connectionManager: ConnectionManager
+  registrar: Registrar
+  addressManager: AddressManager
+  transportManager: TransportManager
+}
+
+/**
+ * The DCUtR protocol
+ */
+export const multicodec = '/libp2p/dcutr'
+
+export function dcutrService (init: DCUtRServiceInit = {}): (components: DCUtRServiceComponents) => unknown {
+  return (components) => new DefaultDCUtRService(components, init)
+}

package/src/dcutr/pb/message.proto

@@ -0,0 +1,12 @@
+syntax = "proto3";
+
+message HolePunch {
+  enum Type {
+    UNUSED = 0;
+    CONNECT = 100;
+    SYNC = 300;
+  }
+
+  optional Type type = 1;
+  repeated bytes observed_addresses = 2;
+}

package/src/dcutr/pb/message.ts

@@ -0,0 +1,96 @@
+/* eslint-disable import/export */
+/* eslint-disable complexity */
+/* eslint-disable @typescript-eslint/no-namespace */
+/* eslint-disable @typescript-eslint/no-unnecessary-boolean-literal-compare */
+/* eslint-disable @typescript-eslint/no-empty-interface */
+
+import { enumeration, encodeMessage, decodeMessage, message } from 'protons-runtime'
+import type { Codec } from 'protons-runtime'
+import type { Uint8ArrayList } from 'uint8arraylist'
+
+export interface HolePunch {
+  type?: HolePunch.Type
+  observedAddresses: Uint8Array[]
+}
+
+export namespace HolePunch {
+  export enum Type {
+    UNUSED = 'UNUSED',
+    CONNECT = 'CONNECT',
+    SYNC = 'SYNC'
+  }
+
+  enum __TypeValues {
+    UNUSED = 0,
+    CONNECT = 100,
+    SYNC = 300
+  }
+
+  export namespace Type {
+    export const codec = (): Codec<Type> => {
+      return enumeration<Type>(__TypeValues)
+    }
+  }
+
+  let _codec: Codec<HolePunch>
+
+  export const codec = (): Codec<HolePunch> => {
+    if (_codec == null) {
+      _codec = message<HolePunch>((obj, w, opts = {}) => {
+        if (opts.lengthDelimited !== false) {
+          w.fork()
+        }
+
+        if (obj.type != null) {
+          w.uint32(8)
+          HolePunch.Type.codec().encode(obj.type, w)
+        }
+
+        if (obj.observedAddresses != null) {
+          for (const value of obj.observedAddresses) {
+            w.uint32(18)
+            w.bytes(value)
+          }
+        }
+
+        if (opts.lengthDelimited !== false) {
+          w.ldelim()
+        }
+      }, (reader, length) => {
+        const obj: any = {
+          observedAddresses: []
+        }
+
+        const end = length == null ? reader.len : reader.pos + length
+
+        while (reader.pos < end) {
+          const tag = reader.uint32()
+
+          switch (tag >>> 3) {
+            case 1:
+              obj.type = HolePunch.Type.codec().decode(reader)
+              break
+            case 2:
+              obj.observedAddresses.push(reader.bytes())
+              break
+            default:
+              reader.skipType(tag & 7)
+              break
+          }
+        }
+
+        return obj
+      })
+    }
+
+    return _codec
+  }
+
+  export const encode = (obj: Partial<HolePunch>): Uint8Array => {
+    return encodeMessage(obj, HolePunch.codec())
+  }
+
+  export const decode = (buf: Uint8Array | Uint8ArrayList): HolePunch => {
+    return decodeMessage(buf, HolePunch.codec())
+  }
+}

package/src/version.ts

@@ -1,2 +1,2 @@
-export const version = '0.46.4'
+export const version = '0.46.5'
 export const name = 'libp2p'