@libp2p/circuit-relay-v2 0.0.0-97ab31c0c

package/src/transport/discovery.ts

@@ -0,0 +1,138 @@
+import { TypedEventEmitter } from '@libp2p/interface/events'
+import {
+  RELAY_RENDEZVOUS_NS,
+  RELAY_V2_HOP_CODEC
+} from '../constants.js'
+import { namespaceToCid } from '../utils.js'
+import type { ComponentLogger, Logger } from '@libp2p/interface'
+import type { ContentRouting } from '@libp2p/interface/content-routing'
+import type { PeerId } from '@libp2p/interface/peer-id'
+import type { PeerStore } from '@libp2p/interface/peer-store'
+import type { Startable } from '@libp2p/interface/startable'
+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 RelayDiscoveryEvents {
+  'relay:discover': CustomEvent<PeerId>
+}
+
+export interface RelayDiscoveryComponents {
+  peerId: PeerId
+  peerStore: PeerStore
+  connectionManager: ConnectionManager
+  transportManager: TransportManager
+  contentRouting: ContentRouting
+  registrar: Registrar
+  logger: ComponentLogger
+}
+
+/**
+ * ReservationManager automatically makes a circuit v2 reservation on any connected
+ * peers that support the circuit v2 HOP protocol.
+ */
+export class RelayDiscovery extends TypedEventEmitter<RelayDiscoveryEvents> implements Startable {
+  private readonly peerId: PeerId
+  private readonly peerStore: PeerStore
+  private readonly contentRouting: ContentRouting
+  private readonly registrar: Registrar
+  private started: boolean
+  private topologyId?: string
+  private readonly log: Logger
+
+  constructor (components: RelayDiscoveryComponents) {
+    super()
+
+    this.log = components.logger.forComponent('libp2p:circuit-relay:discover-relays')
+    this.started = false
+    this.peerId = components.peerId
+    this.peerStore = components.peerStore
+    this.contentRouting = components.contentRouting
+    this.registrar = components.registrar
+  }
+
+  isStarted (): boolean {
+    return this.started
+  }
+
+  async start (): Promise<void> {
+    // register a topology listener for when new peers are encountered
+    // that support the hop protocol
+    this.topologyId = await this.registrar.register(RELAY_V2_HOP_CODEC, {
+      notifyOnTransient: true,
+      onConnect: (peerId) => {
+        this.safeDispatchEvent('relay:discover', { detail: peerId })
+      }
+    })
+
+    void this.discover()
+      .catch(err => {
+        this.log.error('error listening on relays', err)
+      })
+
+    this.started = true
+  }
+
+  stop (): void {
+    if (this.topologyId != null) {
+      this.registrar.unregister(this.topologyId)
+    }
+
+    this.started = false
+  }
+
+  /**
+   * Try to listen on available hop relay connections.
+   * The following order will happen while we do not have enough relays:
+   *
+   * 1. Check the metadata store for known relays, try to listen on the ones we are already connected
+   * 2. Dial and try to listen on the peers we know that support hop but are not connected
+   * 3. Search the network
+   */
+  async discover (): Promise<void> {
+    this.log('searching peer store for relays')
+    const peers = (await this.peerStore.all({
+      filters: [
+        // filter by a list of peers supporting RELAY_V2_HOP and ones we are not listening on
+        (peer) => {
+          return peer.protocols.includes(RELAY_V2_HOP_CODEC)
+        }
+      ],
+      orders: [
+        () => Math.random() < 0.5 ? 1 : -1
+      ]
+    }))
+
+    for (const peer of peers) {
+      this.log('found relay peer %p in content peer store', peer.id)
+      this.safeDispatchEvent('relay:discover', { detail: peer.id })
+    }
+
+    this.log('found %d relay peers in peer store', peers.length)
+
+    try {
+      this.log('searching content routing for relays')
+      const cid = await namespaceToCid(RELAY_RENDEZVOUS_NS)
+
+      let found = 0
+
+      for await (const provider of this.contentRouting.findProviders(cid)) {
+        if (provider.multiaddrs.length > 0 && !provider.id.equals(this.peerId)) {
+          const peerId = provider.id
+
+          found++
+          await this.peerStore.merge(peerId, {
+            multiaddrs: provider.multiaddrs
+          })
+
+          this.log('found relay peer %p in content routing', peerId)
+          this.safeDispatchEvent('relay:discover', { detail: peerId })
+        }
+      }
+
+      this.log('found %d relay peers in content routing', found)
+    } catch (err: any) {
+      this.log.error('failed when finding relays on the network', err)
+    }
+  }
+}

package/src/transport/index.ts

@@ -0,0 +1,399 @@
+import { CodeError } from '@libp2p/interface/errors'
+import { symbol, type Transport, type CreateListenerOptions, type Listener, type Upgrader } from '@libp2p/interface/transport'
+import { peerIdFromBytes, peerIdFromString } from '@libp2p/peer-id'
+import { streamToMaConnection } from '@libp2p/utils/stream-to-ma-conn'
+import * as mafmt from '@multiformats/mafmt'
+import { multiaddr } from '@multiformats/multiaddr'
+import { pbStream } from 'it-protobuf-stream'
+import { CIRCUIT_PROTO_CODE, ERR_HOP_REQUEST_FAILED, ERR_RELAYED_DIAL, MAX_CONNECTIONS, RELAY_V2_HOP_CODEC, RELAY_V2_STOP_CODEC } from '../constants.js'
+import { StopMessage, HopMessage, Status } from '../pb/index.js'
+import { RelayDiscovery, type RelayDiscoveryComponents } from './discovery.js'
+import { createListener } from './listener.js'
+import { type RelayStoreInit, ReservationStore } from './reservation-store.js'
+import type { Libp2pEvents, AbortOptions, ComponentLogger, Logger } from '@libp2p/interface'
+import type { Connection, Stream } from '@libp2p/interface/connection'
+import type { ConnectionGater } from '@libp2p/interface/connection-gater'
+import type { ContentRouting } from '@libp2p/interface/content-routing'
+import type { TypedEventTarget } from '@libp2p/interface/events'
+import type { PeerId } from '@libp2p/interface/peer-id'
+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 { IncomingStreamData, Registrar } from '@libp2p/interface-internal/registrar'
+import type { Multiaddr } from '@multiformats/multiaddr'
+
+const isValidStop = (request: StopMessage): request is Required<StopMessage> => {
+  if (request.peer == null) {
+    return false
+  }
+
+  try {
+    request.peer.addrs.forEach(multiaddr)
+  } catch {
+    return false
+  }
+
+  return true
+}
+
+export interface CircuitRelayTransportComponents extends RelayDiscoveryComponents {
+  peerId: PeerId
+  peerStore: PeerStore
+  registrar: Registrar
+  connectionManager: ConnectionManager
+  upgrader: Upgrader
+  addressManager: AddressManager
+  contentRouting: ContentRouting
+  connectionGater: ConnectionGater
+  events: TypedEventTarget<Libp2pEvents>
+  logger: ComponentLogger
+}
+
+interface ConnectOptions {
+  stream: Stream
+  connection: Connection
+  destinationPeer: PeerId
+  destinationAddr: Multiaddr
+  relayAddr: Multiaddr
+  ma: Multiaddr
+  disconnectOnFailure: boolean
+}
+
+/**
+ * RelayConfig configures the circuit v2 relay transport.
+ */
+export interface CircuitRelayTransportInit extends RelayStoreInit {
+  /**
+   * The number of peers running diable relays to search for and
+   * connect to. (default: 0)
+   */
+  discoverRelays?: number
+
+  /**
+   * The maximum number of simultaneous STOP inbound streams that can be open at
+   * once - each inbound relayed connection uses a STOP stream (default: 300)
+   */
+  maxInboundStopStreams?: number
+
+  /**
+   * The maximum number of simultaneous STOP outbound streams that can be open at
+   * once. If this transport is used along with the relay server these settings
+   * should be set to the same value (default: 300)
+   */
+  maxOutboundStopStreams?: number
+
+  /**
+   * Incoming STOP requests (e.g. when a remote peer wants to dial us via a relay)
+   * must finish the initial protocol negotiation within this timeout in ms
+   * (default: 30000)
+   */
+  stopTimeout?: number
+
+  /**
+   * When creating a reservation it must complete within this number of ms
+   * (default: 10000)
+   */
+  reservationCompletionTimeout?: number
+}
+
+const defaults = {
+  maxInboundStopStreams: MAX_CONNECTIONS,
+  maxOutboundStopStreams: MAX_CONNECTIONS,
+  stopTimeout: 30000
+}
+
+class CircuitRelayTransport implements Transport {
+  private readonly discovery?: RelayDiscovery
+  private readonly registrar: Registrar
+  private readonly peerStore: PeerStore
+  private readonly connectionManager: ConnectionManager
+  private readonly peerId: PeerId
+  private readonly upgrader: Upgrader
+  private readonly addressManager: AddressManager
+  private readonly connectionGater: ConnectionGater
+  private readonly reservationStore: ReservationStore
+  private readonly logger: ComponentLogger
+  private readonly maxInboundStopStreams: number
+  private readonly maxOutboundStopStreams?: number
+  private readonly stopTimeout: number
+  private started: boolean
+  private readonly log: Logger
+
+  constructor (components: CircuitRelayTransportComponents, init: CircuitRelayTransportInit) {
+    this.log = components.logger.forComponent('libp2p:circuit-relay:transport')
+    this.registrar = components.registrar
+    this.peerStore = components.peerStore
+    this.connectionManager = components.connectionManager
+    this.logger = components.logger
+    this.peerId = components.peerId
+    this.upgrader = components.upgrader
+    this.addressManager = components.addressManager
+    this.connectionGater = components.connectionGater
+    this.maxInboundStopStreams = init.maxInboundStopStreams ?? defaults.maxInboundStopStreams
+    this.maxOutboundStopStreams = init.maxOutboundStopStreams ?? defaults.maxOutboundStopStreams
+    this.stopTimeout = init.stopTimeout ?? defaults.stopTimeout
+
+    if (init.discoverRelays != null && init.discoverRelays > 0) {
+      this.discovery = new RelayDiscovery(components)
+      this.discovery.addEventListener('relay:discover', (evt) => {
+        this.reservationStore.addRelay(evt.detail, 'discovered')
+          .catch(err => {
+            this.log.error('could not add discovered relay %p', evt.detail, err)
+          })
+      })
+    }
+
+    this.reservationStore = new ReservationStore(components, init)
+    this.reservationStore.addEventListener('relay:not-enough-relays', () => {
+      this.discovery?.discover()
+        .catch(err => {
+          this.log.error('could not discover relays', err)
+        })
+    })
+
+    this.started = false
+  }
+
+  isStarted (): boolean {
+    return this.started
+  }
+
+  async start (): Promise<void> {
+    await this.reservationStore.start()
+    await this.discovery?.start()
+
+    await this.registrar.handle(RELAY_V2_STOP_CODEC, (data) => {
+      void this.onStop(data).catch(err => {
+        this.log.error('error while handling STOP protocol', err)
+        data.stream.abort(err)
+      })
+    }, {
+      maxInboundStreams: this.maxInboundStopStreams,
+      maxOutboundStreams: this.maxOutboundStopStreams,
+      runOnTransientConnection: true
+    })
+
+    this.started = true
+  }
+
+  async stop (): Promise<void> {
+    this.discovery?.stop()
+    await this.reservationStore.stop()
+    await this.registrar.unhandle(RELAY_V2_STOP_CODEC)
+
+    this.started = false
+  }
+
+  readonly [symbol] = true
+
+  readonly [Symbol.toStringTag] = 'libp2p/circuit-relay-v2'
+
+  /**
+   * Dial a peer over a relay
+   */
+  async dial (ma: Multiaddr, options: AbortOptions = {}): Promise<Connection> {
+    if (ma.protoCodes().filter(code => code === CIRCUIT_PROTO_CODE).length !== 1) {
+      const errMsg = 'Invalid circuit relay address'
+      this.log.error(errMsg, ma)
+      throw new CodeError(errMsg, ERR_RELAYED_DIAL)
+    }
+
+    // Check the multiaddr to see if it contains a relay and a destination peer
+    const addrs = ma.toString().split('/p2p-circuit')
+    const relayAddr = multiaddr(addrs[0])
+    const destinationAddr = multiaddr(addrs[addrs.length - 1])
+    const relayId = relayAddr.getPeerId()
+    const destinationId = destinationAddr.getPeerId()
+
+    if (relayId == null || destinationId == null) {
+      const errMsg = `Circuit relay dial to ${ma.toString()} failed as address did not have peer ids`
+      this.log.error(errMsg)
+      throw new CodeError(errMsg, ERR_RELAYED_DIAL)
+    }
+
+    const relayPeer = peerIdFromString(relayId)
+    const destinationPeer = peerIdFromString(destinationId)
+
+    let disconnectOnFailure = false
+    const relayConnections = this.connectionManager.getConnections(relayPeer)
+    let relayConnection = relayConnections[0]
+
+    if (relayConnection == null) {
+      await this.peerStore.merge(relayPeer, {
+        multiaddrs: [relayAddr]
+      })
+      relayConnection = await this.connectionManager.openConnection(relayPeer, options)
+      disconnectOnFailure = true
+    }
+
+    let stream: Stream | undefined
+
+    try {
+      stream = await relayConnection.newStream([RELAY_V2_HOP_CODEC])
+
+      return await this.connectV2({
+        stream,
+        connection: relayConnection,
+        destinationPeer,
+        destinationAddr,
+        relayAddr,
+        ma,
+        disconnectOnFailure
+      })
+    } catch (err: any) {
+      this.log.error('circuit relay dial to destination %p via relay %p failed', destinationPeer, relayPeer, err)
+
+      if (stream != null) {
+        stream.abort(err)
+      }
+
+      disconnectOnFailure && await relayConnection.close()
+      throw err
+    }
+  }
+
+  async connectV2 (
+    {
+      stream, connection, destinationPeer,
+      destinationAddr, relayAddr, ma,
+      disconnectOnFailure
+    }: ConnectOptions
+  ): Promise<Connection> {
+    try {
+      const pbstr = pbStream(stream)
+      const hopstr = pbstr.pb(HopMessage)
+      await hopstr.write({
+        type: HopMessage.Type.CONNECT,
+        peer: {
+          id: destinationPeer.toBytes(),
+          addrs: [multiaddr(destinationAddr).bytes]
+        }
+      })
+
+      const status = await hopstr.read()
+
+      if (status.status !== Status.OK) {
+        throw new CodeError(`failed to connect via relay with status ${status?.status?.toString() ?? 'undefined'}`, ERR_HOP_REQUEST_FAILED)
+      }
+
+      const maConn = streamToMaConnection({
+        stream: pbstr.unwrap(),
+        remoteAddr: ma,
+        localAddr: relayAddr.encapsulate(`/p2p-circuit/p2p/${this.peerId.toString()}`),
+        logger: this.logger
+      })
+
+      this.log('new outbound transient connection %a', maConn.remoteAddr)
+      return await this.upgrader.upgradeOutbound(maConn, {
+        transient: true
+      })
+    } catch (err) {
+      this.log.error(`Circuit relay dial to destination ${destinationPeer.toString()} via relay ${connection.remotePeer.toString()} failed`, err)
+      disconnectOnFailure && await connection.close()
+      throw err
+    }
+  }
+
+  /**
+   * Create a listener
+   */
+  createListener (options: CreateListenerOptions): Listener {
+    return createListener({
+      connectionManager: this.connectionManager,
+      relayStore: this.reservationStore,
+      logger: this.logger
+    })
+  }
+
+  /**
+   * Filter check for all Multiaddrs that this transport can dial on
+   *
+   * @param {Multiaddr[]} multiaddrs
+   * @returns {Multiaddr[]}
+   */
+  filter (multiaddrs: Multiaddr[]): Multiaddr[] {
+    multiaddrs = Array.isArray(multiaddrs) ? multiaddrs : [multiaddrs]
+
+    return multiaddrs.filter((ma) => {
+      return mafmt.Circuit.matches(ma)
+    })
+  }
+
+  /**
+   * An incoming STOP request means a remote peer wants to dial us via a relay
+   */
+  async onStop ({ connection, stream }: IncomingStreamData): Promise<void> {
+    const signal = AbortSignal.timeout(this.stopTimeout)
+    const pbstr = pbStream(stream).pb(StopMessage)
+    const request = await pbstr.read({
+      signal
+    })
+
+    this.log('new circuit relay v2 stop stream from %p with type %s', connection.remotePeer, request.type)
+
+    if (request?.type === undefined) {
+      this.log.error('type was missing from circuit v2 stop protocol request from %s', connection.remotePeer)
+      await pbstr.write({ type: StopMessage.Type.STATUS, status: Status.MALFORMED_MESSAGE }, {
+        signal
+      })
+      await stream.close()
+      return
+    }
+
+    // Validate the STOP request has the required input
+    if (request.type !== StopMessage.Type.CONNECT) {
+      this.log.error('invalid stop connect request via peer %p', connection.remotePeer)
+      await pbstr.write({ type: StopMessage.Type.STATUS, status: Status.UNEXPECTED_MESSAGE }, {
+        signal
+      })
+      await stream.close()
+      return
+    }
+
+    if (!isValidStop(request)) {
+      this.log.error('invalid stop connect request via peer %p', connection.remotePeer)
+      await pbstr.write({ type: StopMessage.Type.STATUS, status: Status.MALFORMED_MESSAGE }, {
+        signal
+      })
+      await stream.close()
+      return
+    }
+
+    const remotePeerId = peerIdFromBytes(request.peer.id)
+
+    if ((await this.connectionGater.denyInboundRelayedConnection?.(connection.remotePeer, remotePeerId)) === true) {
+      this.log.error('connection gater denied inbound relayed connection from %p', connection.remotePeer)
+      await pbstr.write({ type: StopMessage.Type.STATUS, status: Status.PERMISSION_DENIED }, {
+        signal
+      })
+      await stream.close()
+      return
+    }
+
+    this.log.trace('sending success response to %p', connection.remotePeer)
+    await pbstr.write({ type: StopMessage.Type.STATUS, status: Status.OK }, {
+      signal
+    })
+
+    const remoteAddr = connection.remoteAddr.encapsulate(`/p2p-circuit/p2p/${remotePeerId.toString()}`)
+    const localAddr = this.addressManager.getAddresses()[0]
+    const maConn = streamToMaConnection({
+      stream: pbstr.unwrap().unwrap(),
+      remoteAddr,
+      localAddr,
+      logger: this.logger
+    })
+
+    this.log('new inbound transient connection %a', maConn.remoteAddr)
+    await this.upgrader.upgradeInbound(maConn, {
+      transient: true
+    })
+    this.log('%s connection %a upgraded', 'inbound', maConn.remoteAddr)
+  }
+}
+
+export function circuitRelayTransport (init: CircuitRelayTransportInit = {}): (components: CircuitRelayTransportComponents) => Transport {
+  return (components) => {
+    return new CircuitRelayTransport(components, init)
+  }
+}

package/src/transport/listener.ts

@@ -0,0 +1,98 @@
+import { CodeError } from '@libp2p/interface/errors'
+import { TypedEventEmitter } from '@libp2p/interface/events'
+import { PeerMap } from '@libp2p/peer-collections'
+import { multiaddr } from '@multiformats/multiaddr'
+import type { ReservationStore } from './reservation-store.js'
+import type { ComponentLogger, Logger } from '@libp2p/interface'
+import type { PeerId } from '@libp2p/interface/peer-id'
+import type { Listener, ListenerEvents } from '@libp2p/interface/transport'
+import type { ConnectionManager } from '@libp2p/interface-internal/connection-manager'
+import type { Multiaddr } from '@multiformats/multiaddr'
+
+export interface CircuitRelayTransportListenerComponents {
+  connectionManager: ConnectionManager
+  relayStore: ReservationStore
+  logger: ComponentLogger
+}
+
+class CircuitRelayTransportListener extends TypedEventEmitter<ListenerEvents> implements Listener {
+  private readonly connectionManager: ConnectionManager
+  private readonly relayStore: ReservationStore
+  private readonly listeningAddrs: PeerMap<Multiaddr[]>
+  private readonly log: Logger
+
+  constructor (components: CircuitRelayTransportListenerComponents) {
+    super()
+
+    this.log = components.logger.forComponent('libp2p:circuit-relay:transport:listener')
+    this.connectionManager = components.connectionManager
+    this.relayStore = components.relayStore
+    this.listeningAddrs = new PeerMap()
+
+    // remove listening addrs when a relay is removed
+    this.relayStore.addEventListener('relay:removed', this._onRemoveRelayPeer)
+  }
+
+  _onRemoveRelayPeer = (evt: CustomEvent<PeerId>): void => {
+    this.#removeRelayPeer(evt.detail)
+  }
+
+  async listen (addr: Multiaddr): Promise<void> {
+    this.log('listen on %a', addr)
+
+    // remove the circuit part to get the peer id of the relay
+    const relayAddr = addr.decapsulate('/p2p-circuit')
+    const relayConn = await this.connectionManager.openConnection(relayAddr)
+
+    if (!this.relayStore.hasReservation(relayConn.remotePeer)) {
+      // addRelay calls transportManager.listen which calls this listen method
+      await this.relayStore.addRelay(relayConn.remotePeer, 'configured')
+      return
+    }
+
+    const reservation = this.relayStore.getReservation(relayConn.remotePeer)
+
+    if (reservation == null) {
+      throw new CodeError('Did not have reservation after making reservation', 'ERR_NO_RESERVATION')
+    }
+
+    if (this.listeningAddrs.has(relayConn.remotePeer)) {
+      this.log('already listening on relay %p', relayConn.remotePeer)
+      return
+    }
+
+    // add all addresses from the relay reservation
+    this.listeningAddrs.set(relayConn.remotePeer, reservation.addrs.map(buf => {
+      return multiaddr(buf).encapsulate('/p2p-circuit')
+    }))
+
+    this.safeDispatchEvent('listening', {})
+  }
+
+  getAddrs (): Multiaddr[] {
+    return [...this.listeningAddrs.values()].flat()
+  }
+
+  async close (): Promise<void> {
+
+  }
+
+  #removeRelayPeer (peerId: PeerId): void {
+    const had = this.listeningAddrs.has(peerId)
+
+    this.log('relay peer removed %p - had reservation', peerId, had)
+
+    this.listeningAddrs.delete(peerId)
+
+    if (had) {
+      this.log.trace('removing relay event listener for peer %p', peerId)
+      this.relayStore.removeEventListener('relay:removed', this._onRemoveRelayPeer)
+      // Announce listen addresses change
+      this.safeDispatchEvent('close', {})
+    }
+  }
+}
+
+export function createListener (options: CircuitRelayTransportListenerComponents): Listener {
+  return new CircuitRelayTransportListener(options)
+}