@libp2p/dcutr 0.0.0-97ab31c0c

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@libp2p/dcutr",
+  "version": "0.0.0-97ab31c0c",
+  "description": "Implementation of the DCUtR Protocol",
+  "license": "Apache-2.0 OR MIT",
+  "homepage": "https://github.com/libp2p/js-libp2p/tree/master/packages/protocol-dcutr#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/libp2p/js-libp2p.git"
+  },
+  "bugs": {
+    "url": "https://github.com/libp2p/js-libp2p/issues"
+  },
+  "type": "module",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "src",
+    "dist",
+    "!dist/test",
+    "!**/*.tsbuildinfo"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "eslintConfig": {
+    "extends": "ipfs",
+    "parserOptions": {
+      "project": true,
+      "sourceType": "module"
+    }
+  },
+  "scripts": {
+    "start": "node dist/src/main.js",
+    "build": "aegir build",
+    "test": "aegir test",
+    "clean": "aegir clean",
+    "generate": "protons ./src/pb/index.proto",
+    "lint": "aegir lint",
+    "test:chrome": "aegir test -t browser --cov",
+    "test:chrome-webworker": "aegir test -t webworker",
+    "test:firefox": "aegir test -t browser -- --browser firefox",
+    "test:firefox-webworker": "aegir test -t webworker -- --browser firefox",
+    "test:node": "aegir test -t node --cov",
+    "dep-check": "aegir dep-check"
+  },
+  "dependencies": {
+    "@libp2p/interface": "0.1.6-97ab31c0c",
+    "@libp2p/interface-internal": "0.1.9-97ab31c0c",
+    "@multiformats/multiaddr": "^12.1.10",
+    "@multiformats/multiaddr-matcher": "^1.1.0",
+    "delay": "^6.0.0",
+    "it-protobuf-stream": "^1.0.2",
+    "private-ip": "^3.0.1",
+    "protons-runtime": "^5.0.0",
+    "uint8arraylist": "^2.4.3"
+  },
+  "devDependencies": {
+    "aegir": "^41.0.2",
+    "protons": "^7.3.0",
+    "sinon": "^17.0.0",
+    "sinon-ts": "^2.0.0"
+  }
+}

package/src/dcutr.ts

@@ -0,0 +1,377 @@
+import { CodeError, ERR_INVALID_MESSAGE } from '@libp2p/interface/errors'
+import { type Multiaddr, multiaddr } from '@multiformats/multiaddr'
+import delay from 'delay'
+import { pbStream } from 'it-protobuf-stream'
+import { HolePunch } from './pb/message.js'
+import { isPublicAndDialable } from './utils.js'
+import { multicodec } from './index.js'
+import type { DCUtRServiceComponents, DCUtRServiceInit } from './index.js'
+import type { Logger } from '@libp2p/interface'
+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'
+
+// 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
+  private readonly log: Logger
+
+  constructor (components: DCUtRServiceComponents, init: DCUtRServiceInit) {
+    this.log = components.logger.forComponent('libp2p:dcutr')
+    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, {
+      notifyOnTransient: true,
+      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 => {
+            this.log.error('error during outgoing DCUtR attempt', err)
+          })
+      }
+    })
+
+    await this.registrar.handle(multicodec, (data) => {
+      void this.handleIncomingUpgrade(data.stream, data.connection).catch(err => {
+        this.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.
+        this.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)
+
+        this.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) {
+          this.log('A sent wrong message type')
+          throw new CodeError('DCUtR message type was incorrect', ERR_INVALID_MESSAGE)
+        }
+
+        const multiaddrs = this.getDialableMultiaddrs(connect.observedAddresses)
+
+        if (multiaddrs.length === 0) {
+          this.log('A did not have any dialable multiaddrs')
+          throw new CodeError('DCUtR connect message had no multiaddrs', ERR_INVALID_MESSAGE)
+        }
+
+        const rtt = Date.now() - connectTimer
+
+        this.log('A sending sync, rtt %dms', rtt)
+        await pb.write({
+          type: HolePunch.Type.SYNC,
+          observedAddresses: []
+        }, options)
+
+        this.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
+
+        this.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
+        })
+
+        this.log('DCUtR to %p succeeded to address %a, closing relayed connection', relayedConnection.remotePeer, conn.remoteAddr)
+        await relayedConnection.close(options)
+
+        break
+      } catch (err: any) {
+        this.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 isPublicAndDialable(ma, this.transportManager)
+      })
+
+    if (publicAddresses.length > 0) {
+      const signal = AbortSignal.timeout(this.timeout)
+
+      try {
+        this.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')
+        }
+
+        this.log('unilateral connection upgrade to %p succeeded via %a, closing relayed connection', relayedConnection.remotePeer, connection.remoteAddr)
+
+        await relayedConnection.close({
+          signal
+        })
+
+        return true
+      } catch (err) {
+        this.log.error('unilateral connection upgrade to %p on addresses %a failed', relayedConnection.remotePeer, publicAddresses, err)
+      }
+    } else {
+      this.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)
+
+      this.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) {
+        this.log('B sent wrong message type')
+        throw new CodeError('DCUtR message type was incorrect', ERR_INVALID_MESSAGE)
+      }
+
+      if (connect.observedAddresses.length === 0) {
+        this.log('B sent no multiaddrs')
+        throw new CodeError('DCUtR connect message had no multiaddrs', ERR_INVALID_MESSAGE)
+      }
+
+      const multiaddrs = this.getDialableMultiaddrs(connect.observedAddresses)
+
+      if (multiaddrs.length === 0) {
+        this.log('B had no dialable multiaddrs')
+        throw new CodeError('DCUtR connect message had no dialable multiaddrs', ERR_INVALID_MESSAGE)
+      }
+
+      this.log('A sending connect')
+      await pb.write({
+        type: HolePunch.Type.CONNECT,
+        observedAddresses: this.addressManager.getAddresses().map(ma => ma.bytes)
+      })
+
+      this.log('A receiving sync')
+      const sync = await pb.read(options)
+
+      if (sync.type !== HolePunch.Type.SYNC) {
+        throw new CodeError('DCUtR message type was incorrect', 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
+      this.log('A dialing', multiaddrs)
+      const connection = await this.connectionManager.openConnection(multiaddrs, {
+        signal: options.signal,
+        priority: DCUTR_DIAL_PRIORITY,
+        force: true
+      })
+
+      this.log('DCUtR to %p succeeded via %a, closing relayed connection', relayedConnection.remotePeer, connection.remoteAddr)
+      await relayedConnection.close(options)
+    } catch (err: any) {
+      this.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 (!isPublicAndDialable(ma, this.transportManager)) {
+          continue
+        }
+
+        output.push(ma)
+      } catch {}
+    }
+
+    return output
+  }
+}

package/src/index.ts

@@ -0,0 +1,104 @@
+/**
+ * @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 { identify } from '@libp2p/identify'
+ * import { dcutr } from '@libp2p/dcutr'
+ *
+ * const node = await createLibp2p({
+ *   transports: [
+ *     circuitRelayTransport(),
+ *     tcp()
+ *   ],
+ *   services: {
+ *     identify: identify(),
+ *     dcutr: dcutr()
+ *   }
+ * })
+ *
+ * // 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 { ComponentLogger } from '@libp2p/interface'
+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
+  logger: ComponentLogger
+}
+
+/**
+ * The DCUtR protocol
+ */
+export const multicodec = '/libp2p/dcutr'
+
+export function dcutr (init: DCUtRServiceInit = {}): (components: DCUtRServiceComponents) => unknown {
+  return (components) => new DefaultDCUtRService(components, init)
+}

package/src/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/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/utils.ts

@@ -0,0 +1,33 @@
+import { type Multiaddr } from '@multiformats/multiaddr'
+import { Circuit, IP, DNS } from '@multiformats/multiaddr-matcher'
+import isPrivate from 'private-ip'
+import type { TransportManager } from '@libp2p/interface-internal/src/transport-manager'
+
+/**
+ * Returns true if the passed multiaddr is public, not relayed and we have a
+ * transport that can dial it
+ */
+export function isPublicAndDialable (ma: Multiaddr, transportManager: TransportManager): boolean {
+  // ignore circuit relay
+  if (Circuit.matches(ma)) {
+    return false
+  }
+
+  const transport = transportManager.transportForMultiaddr(ma)
+
+  if (transport == null) {
+    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
+  }
+
+  return isPrivate(ma.toOptions().host) === false
+}