libp2p 0.36.2 → 0.37.0

package/src/circuit/circuit/{utils.js → utils.ts}

@@ -1,20 +1,11 @@
-'use strict'
-
-const { Multiaddr } = require('multiaddr')
-const { CircuitRelay } = require('../protocol')
-
-/**
- * @typedef {import('./stream-handler')} StreamHandler
- * @typedef {import('../protocol').ICircuitRelay} ICircuitRelay
- */
+import { Multiaddr } from '@multiformats/multiaddr'
+import { CircuitRelay } from '../pb/index.js'
+import type { StreamHandler } from './stream-handler.js'
 
 /**
  * Write a response
- *
- * @param {StreamHandler} streamHandler
- * @param {import('../protocol').CircuitRelay.Status} status
  */
-function writeResponse (streamHandler, status) {
+function writeResponse (streamHandler: StreamHandler, status: CircuitRelay.Status) {
   streamHandler.write({
     type: CircuitRelay.Type.STATUS,
     code: status
@@ -23,18 +14,15 @@ function writeResponse (streamHandler, status) {
 
 /**
  * Validate incomming HOP/STOP message
- *
- * @param {ICircuitRelay} msg - A CircuitRelay unencoded protobuf message
- * @param {StreamHandler} streamHandler
  */
-function validateAddrs (msg, streamHandler) {
+export function validateAddrs (msg: CircuitRelay, streamHandler: StreamHandler) {
   try {
-    if (msg.dstPeer && msg.dstPeer.addrs) {
+    if (msg.dstPeer?.addrs != null) {
       msg.dstPeer.addrs.forEach((addr) => {
         return new Multiaddr(addr)
       })
     }
-  } catch (/** @type {any} */ err) {
+  } catch (err: any) {
     writeResponse(streamHandler, msg.type === CircuitRelay.Type.HOP
       ? CircuitRelay.Status.HOP_DST_MULTIADDR_INVALID
       : CircuitRelay.Status.STOP_DST_MULTIADDR_INVALID)
@@ -42,19 +30,15 @@ function validateAddrs (msg, streamHandler) {
   }
 
   try {
-    if (msg.srcPeer && msg.srcPeer.addrs) {
+    if (msg.srcPeer?.addrs != null) {
       msg.srcPeer.addrs.forEach((addr) => {
         return new Multiaddr(addr)
       })
     }
-  } catch (/** @type {any} */ err) {
+  } catch (err: any) {
     writeResponse(streamHandler, msg.type === CircuitRelay.Type.HOP
       ? CircuitRelay.Status.HOP_SRC_MULTIADDR_INVALID
       : CircuitRelay.Status.STOP_SRC_MULTIADDR_INVALID)
     throw err
   }
 }
-
-module.exports = {
-  validateAddrs
-}

package/src/circuit/constants.ts

@@ -0,0 +1,31 @@
+const minute = 60 * 1000
+
+/**
+ * Delay before HOP relay service is advertised on the network
+ */
+export const ADVERTISE_BOOT_DELAY = 15 * minute
+
+/**
+ * Delay Between HOP relay service advertisements on the network
+ */
+export const ADVERTISE_TTL = 30 * minute
+
+/**
+ * Multicodec code
+ */
+export const CIRCUIT_PROTO_CODE = 290
+
+/**
+ * PeerStore metadaBook key for HOP relay service
+ */
+export const HOP_METADATA_KEY = 'hop_relay'
+
+/**
+ * PeerStore metadaBook value for HOP relay service
+ */
+export const HOP_METADATA_VALUE = 'true'
+
+/**
+ * Relay HOP relay service namespace for discovery
+ */
+export const RELAY_RENDEZVOUS_NS = '/libp2p/relay'

package/src/circuit/index.ts

@@ -0,0 +1,120 @@
+import { logger } from '@libp2p/logger'
+import { codes } from '../errors.js'
+import {
+  setDelayedInterval,
+  clearDelayedInterval
+// @ts-expect-error set-delayed-interval does not export types
+} from 'set-delayed-interval'
+import { AutoRelay } from './auto-relay.js'
+import { namespaceToCid } from './utils.js'
+import {
+  RELAY_RENDEZVOUS_NS
+} from './constants.js'
+import type { AddressSorter } from '@libp2p/interfaces/peer-store'
+import type { Startable } from '@libp2p/interfaces/startable'
+import type { Components } from '@libp2p/interfaces/components'
+
+const log = logger('libp2p:relay')
+
+export interface RelayAdvertiseConfig {
+  bootDelay?: number
+  enabled?: boolean
+  ttl?: number
+}
+
+export interface HopConfig {
+  enabled?: boolean
+  active?: boolean
+}
+
+export interface AutoRelayConfig {
+  enabled?: boolean
+
+  /**
+   * maximum number of relays to listen
+   */
+  maxListeners: number
+}
+
+export interface RelayInit {
+  addressSorter?: AddressSorter
+  maxListeners?: number
+  onError?: (error: Error, msg?: string) => void
+  hop: HopConfig
+  advertise: RelayAdvertiseConfig
+  autoRelay: AutoRelayConfig
+}
+
+export class Relay implements Startable {
+  private readonly components: Components
+  private readonly init: RelayInit
+  // @ts-expect-error this field isn't used anywhere?
+  private readonly autoRelay?: AutoRelay
+  private timeout?: any
+  private started: boolean
+
+  /**
+   * Creates an instance of Relay
+   */
+  constructor (components: Components, init: RelayInit) {
+    this.components = components
+    // Create autoRelay if enabled
+    this.autoRelay = init.autoRelay?.enabled !== false
+      ? new AutoRelay(components, {
+        addressSorter: init.addressSorter,
+        ...init.autoRelay
+      })
+      : undefined
+
+    this.started = false
+    this.init = init
+    this._advertiseService = this._advertiseService.bind(this)
+  }
+
+  isStarted () {
+    return this.started
+  }
+
+  /**
+   * Start Relay service
+   */
+  async start () {
+    // Advertise service if HOP enabled
+    if (this.init.hop.enabled !== false && this.init.advertise.enabled !== false) {
+      this.timeout = setDelayedInterval(
+        this._advertiseService, this.init.advertise.ttl, this.init.advertise.bootDelay
+      )
+    }
+
+    this.started = true
+  }
+
+  /**
+   * Stop Relay service
+   */
+  async stop () {
+    if (this.timeout != null) {
+      clearDelayedInterval(this.timeout)
+    }
+
+    this.started = false
+  }
+
+  /**
+   * Advertise hop relay service in the network.
+   */
+  async _advertiseService () {
+    try {
+      const cid = await namespaceToCid(RELAY_RENDEZVOUS_NS)
+      await this.components.getContentRouting().provide(cid)
+    } catch (err: any) {
+      if (err.code === codes.ERR_NO_ROUTERS_AVAILABLE) {
+        log.error('a content router, such as a DHT, must be provided in order to advertise the relay service', err)
+        // Stop the advertise
+        await this.stop()
+      } else {
+        log.error(err)
+      }
+    }
+  }
+}

package/src/circuit/listener.ts

@@ -0,0 +1,82 @@
+import { CustomEvent, EventEmitter } from '@libp2p/interfaces/events'
+import type { ConnectionManager } from '@libp2p/interfaces/connection-manager'
+import type { PeerStore } from '@libp2p/interfaces/peer-store'
+import type { Listener } from '@libp2p/interfaces/transport'
+import { peerIdFromString } from '@libp2p/peer-id'
+import { Multiaddr } from '@multiformats/multiaddr'
+
+export interface ListenerOptions {
+  peerStore: PeerStore
+  connectionManager: ConnectionManager
+}
+
+export function createListener (options: ListenerOptions): Listener {
+  const listeningAddrs = new Map()
+
+  /**
+   * Add swarm handler and listen for incoming connections
+   */
+  async function listen (addr: Multiaddr): Promise<void> {
+    const addrString = addr.toString().split('/p2p-circuit').find(a => a !== '')
+    const ma = new Multiaddr(addrString)
+
+    const relayPeerStr = ma.getPeerId()
+
+    if (relayPeerStr == null) {
+      throw new Error('Could not determine relay peer from multiaddr')
+    }
+
+    const relayPeerId = peerIdFromString(relayPeerStr)
+
+    await options.peerStore.addressBook.add(relayPeerId, [ma])
+
+    const relayConn = await options.connectionManager.openConnection(relayPeerId)
+    const relayedAddr = relayConn.remoteAddr.encapsulate('/p2p-circuit')
+
+    listeningAddrs.set(relayConn.remotePeer.toString(), relayedAddr)
+    listener.dispatchEvent(new CustomEvent('listening'))
+  }
+
+  /**
+   * Get fixed up multiaddrs
+   *
+   * NOTE: This method will grab the peers multiaddrs and expand them such that:
+   *
+   * a) If it's an existing /p2p-circuit address for a specific relay i.e.
+   * `/ip4/0.0.0.0/tcp/0/ipfs/QmRelay/p2p-circuit` this method will expand the
+   * address to `/ip4/0.0.0.0/tcp/0/ipfs/QmRelay/p2p-circuit/ipfs/QmPeer` where
+   * `QmPeer` is this peers id
+   * b) If it's not a /p2p-circuit address, it will encapsulate the address as a /p2p-circuit
+   * addr, such when dialing over a relay with this address, it will create the circuit using
+   * the encapsulated transport address. This is useful when for example, a peer should only
+   * be dialed over TCP rather than any other transport
+   *
+   * @returns {Multiaddr[]}
+   */
+  function getAddrs () {
+    const addrs = []
+    for (const addr of listeningAddrs.values()) {
+      addrs.push(addr)
+    }
+    return addrs
+  }
+
+  const listener: Listener = Object.assign(new EventEmitter(), {
+    close: async () => await Promise.resolve(),
+    listen,
+    getAddrs
+  })
+
+  // Remove listeningAddrs when a peer disconnects
+  options.connectionManager.addEventListener('peer:disconnect', (evt) => {
+    const { detail: connection } = evt
+    const deleted = listeningAddrs.delete(connection.remotePeer.toString())
+
+    if (deleted) {
+      // Announce listen addresses change
+      listener.dispatchEvent(new CustomEvent('close'))
+    }
+  })
+
+  return listener
+}

package/src/circuit/multicodec.ts

@@ -0,0 +1,2 @@
+
+export const RELAY_CODEC = '/libp2p/circuit/relay/0.1.0'

package/src/circuit/{protocol → pb}/index.proto

@@ -1,4 +1,4 @@
-syntax = "proto2";
+syntax = "proto3";
 
 message CircuitRelay {
 

package/src/circuit/pb/index.ts

@@ -0,0 +1,117 @@
+/* eslint-disable import/export */
+/* eslint-disable @typescript-eslint/no-namespace */
+
+import { enumeration, encodeMessage, decodeMessage, message, bytes } from 'protons-runtime'
+import type { Codec } from 'protons-runtime'
+
+export interface CircuitRelay {
+  type?: CircuitRelay.Type
+  srcPeer?: CircuitRelay.Peer
+  dstPeer?: CircuitRelay.Peer
+  code?: CircuitRelay.Status
+}
+
+export namespace CircuitRelay {
+  export enum Status {
+    SUCCESS = 'SUCCESS',
+    HOP_SRC_ADDR_TOO_LONG = 'HOP_SRC_ADDR_TOO_LONG',
+    HOP_DST_ADDR_TOO_LONG = 'HOP_DST_ADDR_TOO_LONG',
+    HOP_SRC_MULTIADDR_INVALID = 'HOP_SRC_MULTIADDR_INVALID',
+    HOP_DST_MULTIADDR_INVALID = 'HOP_DST_MULTIADDR_INVALID',
+    HOP_NO_CONN_TO_DST = 'HOP_NO_CONN_TO_DST',
+    HOP_CANT_DIAL_DST = 'HOP_CANT_DIAL_DST',
+    HOP_CANT_OPEN_DST_STREAM = 'HOP_CANT_OPEN_DST_STREAM',
+    HOP_CANT_SPEAK_RELAY = 'HOP_CANT_SPEAK_RELAY',
+    HOP_CANT_RELAY_TO_SELF = 'HOP_CANT_RELAY_TO_SELF',
+    STOP_SRC_ADDR_TOO_LONG = 'STOP_SRC_ADDR_TOO_LONG',
+    STOP_DST_ADDR_TOO_LONG = 'STOP_DST_ADDR_TOO_LONG',
+    STOP_SRC_MULTIADDR_INVALID = 'STOP_SRC_MULTIADDR_INVALID',
+    STOP_DST_MULTIADDR_INVALID = 'STOP_DST_MULTIADDR_INVALID',
+    STOP_RELAY_REFUSED = 'STOP_RELAY_REFUSED',
+    MALFORMED_MESSAGE = 'MALFORMED_MESSAGE'
+  }
+
+  enum __StatusValues {
+    SUCCESS = 100,
+    HOP_SRC_ADDR_TOO_LONG = 220,
+    HOP_DST_ADDR_TOO_LONG = 221,
+    HOP_SRC_MULTIADDR_INVALID = 250,
+    HOP_DST_MULTIADDR_INVALID = 251,
+    HOP_NO_CONN_TO_DST = 260,
+    HOP_CANT_DIAL_DST = 261,
+    HOP_CANT_OPEN_DST_STREAM = 262,
+    HOP_CANT_SPEAK_RELAY = 270,
+    HOP_CANT_RELAY_TO_SELF = 280,
+    STOP_SRC_ADDR_TOO_LONG = 320,
+    STOP_DST_ADDR_TOO_LONG = 321,
+    STOP_SRC_MULTIADDR_INVALID = 350,
+    STOP_DST_MULTIADDR_INVALID = 351,
+    STOP_RELAY_REFUSED = 390,
+    MALFORMED_MESSAGE = 400
+  }
+
+  export namespace Status {
+    export const codec = () => {
+      return enumeration<typeof Status>(__StatusValues)
+    }
+  }
+
+  export enum Type {
+    HOP = 'HOP',
+    STOP = 'STOP',
+    STATUS = 'STATUS',
+    CAN_HOP = 'CAN_HOP'
+  }
+
+  enum __TypeValues {
+    HOP = 1,
+    STOP = 2,
+    STATUS = 3,
+    CAN_HOP = 4
+  }
+
+  export namespace Type {
+    export const codec = () => {
+      return enumeration<typeof Type>(__TypeValues)
+    }
+  }
+
+  export interface Peer {
+    id: Uint8Array
+    addrs: Uint8Array[]
+  }
+
+  export namespace Peer {
+    export const codec = (): Codec<Peer> => {
+      return message<Peer>({
+        1: { name: 'id', codec: bytes },
+        2: { name: 'addrs', codec: bytes, repeats: true }
+      })
+    }
+
+    export const encode = (obj: Peer): Uint8Array => {
+      return encodeMessage(obj, Peer.codec())
+    }
+
+    export const decode = (buf: Uint8Array): Peer => {
+      return decodeMessage(buf, Peer.codec())
+    }
+  }
+
+  export const codec = (): Codec<CircuitRelay> => {
+    return message<CircuitRelay>({
+      1: { name: 'type', codec: CircuitRelay.Type.codec(), optional: true },
+      2: { name: 'srcPeer', codec: CircuitRelay.Peer.codec(), optional: true },
+      3: { name: 'dstPeer', codec: CircuitRelay.Peer.codec(), optional: true },
+      4: { name: 'code', codec: CircuitRelay.Status.codec(), optional: true }
+    })
+  }
+
+  export const encode = (obj: CircuitRelay): Uint8Array => {
+    return encodeMessage(obj, CircuitRelay.codec())
+  }
+
+  export const decode = (buf: Uint8Array): CircuitRelay => {
+    return decodeMessage(buf, CircuitRelay.codec())
+  }
+}

package/src/circuit/transport.ts

@@ -0,0 +1,219 @@
+import { logger } from '@libp2p/logger'
+import errCode from 'err-code'
+import * as mafmt from '@multiformats/mafmt'
+import { Multiaddr } from '@multiformats/multiaddr'
+import { CircuitRelay as CircuitPB } from './pb/index.js'
+import { codes } from '../errors.js'
+import { streamToMaConnection } from '@libp2p/utils/stream-to-ma-conn'
+import { RELAY_CODEC } from './multicodec.js'
+import { createListener } from './listener.js'
+import { handleCanHop, handleHop, hop } from './circuit/hop.js'
+import { handleStop } from './circuit/stop.js'
+import { StreamHandler } from './circuit/stream-handler.js'
+import { symbol } from '@libp2p/interfaces/transport'
+import { peerIdFromString } from '@libp2p/peer-id'
+import { Components, Initializable } from '@libp2p/interfaces/components'
+import type { AbortOptions } from '@libp2p/interfaces'
+import type { IncomingStreamData } from '@libp2p/interfaces/registrar'
+import type { Listener, Transport, CreateListenerOptions, ConnectionHandler } from '@libp2p/interfaces/transport'
+import type { Connection } from '@libp2p/interfaces/connection'
+
+const log = logger('libp2p:circuit')
+
+export class Circuit implements Transport, Initializable {
+  private handler?: ConnectionHandler
+  private components: Components = new Components()
+
+  init (components: Components): void {
+    this.components = components
+    void this.components.getRegistrar().handle(RELAY_CODEC, (data) => {
+      void this._onProtocol(data).catch(err => {
+        log.error(err)
+      })
+    })
+      .catch(err => {
+        log.error(err)
+      })
+  }
+
+  hopEnabled () {
+    return true
+  }
+
+  hopActive () {
+    return true
+  }
+
+  get [symbol] (): true {
+    return true
+  }
+
+  get [Symbol.toStringTag] () {
+    return 'libp2p/circuit-relay-v1'
+  }
+
+  async _onProtocol (data: IncomingStreamData) {
+    const { connection, stream } = data
+    const streamHandler = new StreamHandler({ stream })
+    const request = await streamHandler.read()
+
+    if (request == null) {
+      log('request was invalid, could not read from stream')
+      streamHandler.write({
+        type: CircuitPB.Type.STATUS,
+        code: CircuitPB.Status.MALFORMED_MESSAGE
+      })
+      streamHandler.close()
+      return
+    }
+
+    let virtualConnection
+
+    switch (request.type) {
+      case CircuitPB.Type.CAN_HOP: {
+        log('received CAN_HOP request from %p', connection.remotePeer)
+        await handleCanHop({ circuit: this, connection, streamHandler })
+        break
+      }
+      case CircuitPB.Type.HOP: {
+        log('received HOP request from %p', connection.remotePeer)
+        virtualConnection = await handleHop({
+          connection,
+          request,
+          streamHandler,
+          circuit: this,
+          connectionManager: this.components.getConnectionManager()
+        })
+        break
+      }
+      case CircuitPB.Type.STOP: {
+        log('received STOP request from %p', connection.remotePeer)
+        virtualConnection = await handleStop({
+          connection,
+          request,
+          streamHandler
+        })
+        break
+      }
+      default: {
+        log('Request of type %s not supported', request.type)
+        streamHandler.write({
+          type: CircuitPB.Type.STATUS,
+          code: CircuitPB.Status.MALFORMED_MESSAGE
+        })
+        streamHandler.close()
+        return
+      }
+    }
+
+    if (virtualConnection != null) {
+      // @ts-expect-error dst peer will not be undefined
+      const remoteAddr = new Multiaddr(request.dstPeer.addrs[0])
+      // @ts-expect-error dst peer will not be undefined
+      const localAddr = new Multiaddr(request.srcPeer.addrs[0])
+      const maConn = streamToMaConnection({
+        stream: virtualConnection,
+        remoteAddr,
+        localAddr
+      })
+      const type = request.type === CircuitPB.Type.HOP ? 'relay' : 'inbound'
+      log('new %s connection %s', type, maConn.remoteAddr)
+
+      const conn = await this.components.getUpgrader().upgradeInbound(maConn)
+      log('%s connection %s upgraded', type, maConn.remoteAddr)
+
+      if (this.handler != null) {
+        this.handler(conn)
+      }
+    }
+  }
+
+  /**
+   * Dial a peer over a relay
+   */
+  async dial (ma: Multiaddr, options: AbortOptions = {}): Promise<Connection> {
+    // Check the multiaddr to see if it contains a relay and a destination peer
+    const addrs = ma.toString().split('/p2p-circuit')
+    const relayAddr = new Multiaddr(addrs[0])
+    const destinationAddr = new Multiaddr(addrs[addrs.length - 1])
+    const relayId = relayAddr.getPeerId()
+    const destinationId = destinationAddr.getPeerId()
+
+    if (relayId == null || destinationId == null) {
+      const errMsg = 'Circuit relay dial failed as addresses did not have peer id'
+      log.error(errMsg)
+      throw errCode(new Error(errMsg), codes.ERR_RELAYED_DIAL)
+    }
+
+    const relayPeer = peerIdFromString(relayId)
+    const destinationPeer = peerIdFromString(destinationId)
+
+    let disconnectOnFailure = false
+    const relayConnections = this.components.getConnectionManager().getConnections(relayPeer)
+    let relayConnection = relayConnections[0]
+
+    if (relayConnection == null) {
+      await this.components.getPeerStore().addressBook.add(relayPeer, [relayAddr])
+      relayConnection = await this.components.getConnectionManager().openConnection(relayPeer, options)
+      disconnectOnFailure = true
+    }
+
+    try {
+      const virtualConnection = await hop({
+        connection: relayConnection,
+        request: {
+          type: CircuitPB.Type.HOP,
+          srcPeer: {
+            id: this.components.getPeerId().toBytes(),
+            addrs: this.components.getAddressManager().getAddresses().map(addr => addr.bytes)
+          },
+          dstPeer: {
+            id: destinationPeer.toBytes(),
+            addrs: [new Multiaddr(destinationAddr).bytes]
+          }
+        }
+      })
+
+      const localAddr = relayAddr.encapsulate(`/p2p-circuit/p2p/${this.components.getPeerId().toString()}`)
+      const maConn = streamToMaConnection({
+        stream: virtualConnection,
+        remoteAddr: ma,
+        localAddr
+      })
+      log('new outbound connection %s', maConn.remoteAddr)
+
+      return await this.components.getUpgrader().upgradeOutbound(maConn)
+    } catch (err: any) {
+      log.error('Circuit relay dial failed', err)
+      disconnectOnFailure && await relayConnection.close()
+      throw err
+    }
+  }
+
+  /**
+   * Create a listener
+   */
+  createListener (options: CreateListenerOptions): Listener {
+    // Called on successful HOP and STOP requests
+    this.handler = options.handler
+
+    return createListener({
+      connectionManager: this.components.getConnectionManager(),
+      peerStore: this.components.getPeerStore()
+    })
+  }
+
+  /**
+   * 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)
+    })
+  }
+}

package/src/circuit/utils.ts

@@ -0,0 +1,12 @@
+import { CID } from 'multiformats/cid'
+import { sha256 } from 'multiformats/hashes/sha2'
+
+/**
+ * Convert a namespace string into a cid
+ */
+export async function namespaceToCid (namespace: string): Promise<CID> {
+  const bytes = new TextEncoder().encode(namespace)
+  const hash = await sha256.digest(bytes)
+
+  return CID.createV0(hash)
+}