@libp2p/circuit-relay-v2 0.0.0-05b52d69c

package/src/server/index.ts

@@ -0,0 +1,446 @@
+import { TypedEventEmitter, setMaxListeners } from '@libp2p/interface/events'
+import { peerIdFromBytes } from '@libp2p/peer-id'
+import { RecordEnvelope } from '@libp2p/peer-record'
+import { type Multiaddr, multiaddr } from '@multiformats/multiaddr'
+import { pbStream, type ProtobufStream } from 'it-protobuf-stream'
+import pDefer from 'p-defer'
+import {
+  CIRCUIT_PROTO_CODE,
+  DEFAULT_HOP_TIMEOUT,
+  MAX_CONNECTIONS,
+  RELAY_SOURCE_TAG,
+  RELAY_V2_HOP_CODEC,
+  RELAY_V2_STOP_CODEC
+} from '../constants.js'
+import { HopMessage, type Reservation, Status, StopMessage } from '../pb/index.js'
+import { createLimitedRelay } from '../utils.js'
+import { AdvertService, type AdvertServiceComponents, type AdvertServiceInit } from './advert-service.js'
+import { ReservationStore, type ReservationStoreInit } from './reservation-store.js'
+import { ReservationVoucherRecord } from './reservation-voucher.js'
+import type { CircuitRelayService, RelayReservation } from '../index.js'
+import type { ComponentLogger, Logger } from '@libp2p/interface'
+import type { Connection, Stream } from '@libp2p/interface/connection'
+import type { ConnectionGater } from '@libp2p/interface/connection-gater'
+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 { 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 { PeerMap } from '@libp2p/peer-collections'
+
+const isRelayAddr = (ma: Multiaddr): boolean => ma.protoCodes().includes(CIRCUIT_PROTO_CODE)
+
+export interface CircuitRelayServerInit {
+  /**
+   * Incoming hop requests must complete within this time in ms otherwise
+   * the stream will be reset (default: 30s)
+   */
+  hopTimeout?: number
+
+  /**
+   * If true, advertise this service via libp2p content routing to allow
+   * peers to locate us on the network (default: false)
+   */
+  advertise?: boolean | AdvertServiceInit
+
+  /**
+   * Configuration of reservations
+   */
+  reservations?: ReservationStoreInit
+
+  /**
+   * The maximum number of simultaneous HOP inbound streams that can be open at once
+   */
+  maxInboundHopStreams?: number
+
+  /**
+   * The maximum number of simultaneous HOP outbound streams that can be open at once
+   */
+  maxOutboundHopStreams?: number
+
+  /**
+   * The maximum number of simultaneous STOP outbound streams that can be open at
+   * once. (default: 300)
+   */
+  maxOutboundStopStreams?: number
+}
+
+export interface HopProtocolOptions {
+  connection: Connection
+  request: HopMessage
+  stream: ProtobufStream<Stream>
+}
+
+export interface StopOptions {
+  connection: Connection
+  request: StopMessage
+}
+
+export interface CircuitRelayServerComponents extends AdvertServiceComponents {
+  registrar: Registrar
+  peerStore: PeerStore
+  addressManager: AddressManager
+  peerId: PeerId
+  connectionManager: ConnectionManager
+  connectionGater: ConnectionGater
+  logger: ComponentLogger
+}
+
+export interface RelayServerEvents {
+  'relay:reservation': CustomEvent<RelayReservation>
+  'relay:advert:success': CustomEvent<unknown>
+  'relay:advert:error': CustomEvent<Error>
+}
+
+const defaults = {
+  maxOutboundStopStreams: MAX_CONNECTIONS
+}
+
+class CircuitRelayServer extends TypedEventEmitter<RelayServerEvents> implements Startable, CircuitRelayService {
+  private readonly registrar: Registrar
+  private readonly peerStore: PeerStore
+  private readonly addressManager: AddressManager
+  private readonly peerId: PeerId
+  private readonly connectionManager: ConnectionManager
+  private readonly connectionGater: ConnectionGater
+  private readonly reservationStore: ReservationStore
+  private readonly advertService: AdvertService | undefined
+  private started: boolean
+  private readonly hopTimeout: number
+  private readonly shutdownController: AbortController
+  private readonly maxInboundHopStreams?: number
+  private readonly maxOutboundHopStreams?: number
+  private readonly maxOutboundStopStreams: number
+  private readonly log: Logger
+
+  /**
+   * Creates an instance of Relay
+   */
+  constructor (components: CircuitRelayServerComponents, init: CircuitRelayServerInit = {}) {
+    super()
+
+    this.log = components.logger.forComponent('libp2p:circuit-relay:server')
+    this.registrar = components.registrar
+    this.peerStore = components.peerStore
+    this.addressManager = components.addressManager
+    this.peerId = components.peerId
+    this.connectionManager = components.connectionManager
+    this.connectionGater = components.connectionGater
+    this.started = false
+    this.hopTimeout = init?.hopTimeout ?? DEFAULT_HOP_TIMEOUT
+    this.shutdownController = new AbortController()
+    this.maxInboundHopStreams = init.maxInboundHopStreams
+    this.maxOutboundHopStreams = init.maxOutboundHopStreams
+    this.maxOutboundStopStreams = init.maxOutboundStopStreams ?? defaults.maxOutboundStopStreams
+
+    setMaxListeners(Infinity, this.shutdownController.signal)
+
+    if (init.advertise != null && init.advertise !== false) {
+      this.advertService = new AdvertService(components, init.advertise === true ? undefined : init.advertise)
+      this.advertService.addEventListener('advert:success', () => {
+        this.safeDispatchEvent('relay:advert:success', {})
+      })
+      this.advertService.addEventListener('advert:error', (evt) => {
+        this.safeDispatchEvent('relay:advert:error', { detail: evt.detail })
+      })
+    }
+
+    this.reservationStore = new ReservationStore(init.reservations)
+  }
+
+  isStarted (): boolean {
+    return this.started
+  }
+
+  /**
+   * Start Relay service
+   */
+  async start (): Promise<void> {
+    if (this.started) {
+      return
+    }
+
+    // Advertise service if HOP enabled and advertising enabled
+    this.advertService?.start()
+
+    await this.registrar.handle(RELAY_V2_HOP_CODEC, (data) => {
+      void this.onHop(data).catch(err => {
+        this.log.error(err)
+      })
+    }, {
+      maxInboundStreams: this.maxInboundHopStreams,
+      maxOutboundStreams: this.maxOutboundHopStreams,
+      runOnTransientConnection: true
+    })
+
+    this.reservationStore.start()
+
+    this.started = true
+  }
+
+  /**
+   * Stop Relay service
+   */
+  async stop (): Promise<void> {
+    this.advertService?.stop()
+    this.reservationStore.stop()
+    this.shutdownController.abort()
+    await this.registrar.unhandle(RELAY_V2_HOP_CODEC)
+
+    this.started = false
+  }
+
+  async onHop ({ connection, stream }: IncomingStreamData): Promise<void> {
+    this.log('received circuit v2 hop protocol stream from %p', connection.remotePeer)
+
+    const hopTimeoutPromise = pDefer<HopMessage>()
+    const timeout = setTimeout(() => {
+      hopTimeoutPromise.reject('timed out')
+    }, this.hopTimeout)
+    const pbstr = pbStream(stream)
+
+    try {
+      const request: HopMessage = await Promise.race([
+        pbstr.pb(HopMessage).read(),
+        hopTimeoutPromise.promise
+      ])
+
+      if (request?.type == null) {
+        throw new Error('request was invalid, could not read from stream')
+      }
+
+      this.log('received', request.type)
+
+      await Promise.race([
+        this.handleHopProtocol({
+          connection,
+          stream: pbstr,
+          request
+        }),
+        hopTimeoutPromise.promise
+      ])
+    } catch (err: any) {
+      this.log.error('error while handling hop', err)
+      await pbstr.pb(HopMessage).write({
+        type: HopMessage.Type.STATUS,
+        status: Status.MALFORMED_MESSAGE
+      })
+      stream.abort(err)
+    } finally {
+      clearTimeout(timeout)
+    }
+  }
+
+  async handleHopProtocol ({ stream, request, connection }: HopProtocolOptions): Promise<void> {
+    this.log('received hop message')
+    switch (request.type) {
+      case HopMessage.Type.RESERVE: await this.handleReserve({ stream, request, connection }); break
+      case HopMessage.Type.CONNECT: await this.handleConnect({ stream, request, connection }); break
+      default: {
+        this.log.error('invalid hop request type %s via peer %p', request.type, connection.remotePeer)
+        await stream.pb(HopMessage).write({ type: HopMessage.Type.STATUS, status: Status.UNEXPECTED_MESSAGE })
+      }
+    }
+  }
+
+  async handleReserve ({ stream, request, connection }: HopProtocolOptions): Promise<void> {
+    const hopstr = stream.pb(HopMessage)
+    this.log('hop reserve request from %p', connection.remotePeer)
+
+    if (isRelayAddr(connection.remoteAddr)) {
+      this.log.error('relay reservation over circuit connection denied for peer: %p', connection.remotePeer)
+      await hopstr.write({ type: HopMessage.Type.STATUS, status: Status.PERMISSION_DENIED })
+      return
+    }
+
+    if ((await this.connectionGater.denyInboundRelayReservation?.(connection.remotePeer)) === true) {
+      this.log.error('reservation for %p denied by connection gater', connection.remotePeer)
+      await hopstr.write({ type: HopMessage.Type.STATUS, status: Status.PERMISSION_DENIED })
+      return
+    }
+
+    const result = this.reservationStore.reserve(connection.remotePeer, connection.remoteAddr)
+
+    if (result.status !== Status.OK) {
+      await hopstr.write({ type: HopMessage.Type.STATUS, status: result.status })
+      return
+    }
+
+    try {
+      // tag relay target peer
+      // result.expire is non-null if `ReservationStore.reserve` returns with status == OK
+      if (result.expire != null) {
+        const ttl = (result.expire * 1000) - Date.now()
+        await this.peerStore.merge(connection.remotePeer, {
+          tags: {
+            [RELAY_SOURCE_TAG]: { value: 1, ttl }
+          }
+        })
+      }
+
+      await hopstr.write({
+        type: HopMessage.Type.STATUS,
+        status: Status.OK,
+        reservation: await this.makeReservation(connection.remotePeer, BigInt(result.expire ?? 0)),
+        limit: this.reservationStore.get(connection.remotePeer)?.limit
+      })
+      this.log('sent confirmation response to %s', connection.remotePeer)
+    } catch (err) {
+      this.log.error('failed to send confirmation response to %p', connection.remotePeer, err)
+      this.reservationStore.removeReservation(connection.remotePeer)
+    }
+  }
+
+  async makeReservation (
+    remotePeer: PeerId,
+    expire: bigint
+  ): Promise<Reservation> {
+    const addrs = []
+
+    for (const relayAddr of this.addressManager.getAddresses()) {
+      if (relayAddr.toString().includes('/p2p-circuit')) {
+        continue
+      }
+
+      addrs.push(relayAddr.bytes)
+    }
+
+    const voucher = await RecordEnvelope.seal(new ReservationVoucherRecord({
+      peer: remotePeer,
+      relay: this.peerId,
+      expiration: Number(expire)
+    }), this.peerId)
+
+    return {
+      addrs,
+      expire,
+      voucher: voucher.marshal()
+    }
+  }
+
+  async handleConnect ({ stream, request, connection }: HopProtocolOptions): Promise<void> {
+    const hopstr = stream.pb(HopMessage)
+
+    if (isRelayAddr(connection.remoteAddr)) {
+      this.log.error('relay reservation over circuit connection denied for peer: %p', connection.remotePeer)
+      await hopstr.write({ type: HopMessage.Type.STATUS, status: Status.PERMISSION_DENIED })
+      return
+    }
+
+    this.log('hop connect request from %p', connection.remotePeer)
+
+    let dstPeer: PeerId
+
+    try {
+      if (request.peer == null) {
+        this.log.error('no peer info in hop connect request')
+        throw new Error('no peer info in request')
+      }
+
+      request.peer.addrs.forEach(multiaddr)
+      dstPeer = peerIdFromBytes(request.peer.id)
+    } catch (err) {
+      this.log.error('invalid hop connect request via peer %p %s', connection.remotePeer, err)
+      await hopstr.write({ type: HopMessage.Type.STATUS, status: Status.MALFORMED_MESSAGE })
+      return
+    }
+
+    if (!this.reservationStore.hasReservation(dstPeer)) {
+      this.log.error('hop connect denied for destination peer %p not having a reservation for %p with status %s', dstPeer, connection.remotePeer, Status.NO_RESERVATION)
+      await hopstr.write({ type: HopMessage.Type.STATUS, status: Status.NO_RESERVATION })
+      return
+    }
+
+    if ((await this.connectionGater.denyOutboundRelayedConnection?.(connection.remotePeer, dstPeer)) === true) {
+      this.log.error('hop connect for %p to %p denied by connection gater', connection.remotePeer, dstPeer)
+      await hopstr.write({ type: HopMessage.Type.STATUS, status: Status.PERMISSION_DENIED })
+      return
+    }
+
+    const connections = this.connectionManager.getConnections(dstPeer)
+
+    if (connections.length === 0) {
+      this.log('hop connect denied for destination peer %p not having a connection for %p as there is no destination connection', dstPeer, connection.remotePeer)
+      await hopstr.write({ type: HopMessage.Type.STATUS, status: Status.NO_RESERVATION })
+      return
+    }
+
+    const destinationConnection = connections[0]
+
+    const destinationStream = await this.stopHop({
+      connection: destinationConnection,
+      request: {
+        type: StopMessage.Type.CONNECT,
+        peer: {
+          id: connection.remotePeer.toBytes(),
+          addrs: []
+        }
+      }
+    })
+
+    if (destinationStream == null) {
+      this.log.error('failed to open stream to destination peer %p', destinationConnection?.remotePeer)
+      await hopstr.write({ type: HopMessage.Type.STATUS, status: Status.CONNECTION_FAILED })
+      return
+    }
+
+    await hopstr.write({ type: HopMessage.Type.STATUS, status: Status.OK })
+    const sourceStream = stream.unwrap()
+
+    this.log('connection from %p to %p established - merging streams', connection.remotePeer, dstPeer)
+    const limit = this.reservationStore.get(dstPeer)?.limit
+    // Short circuit the two streams to create the relayed connection
+    createLimitedRelay(sourceStream, destinationStream, this.shutdownController.signal, limit, {
+      log: this.log
+    })
+  }
+
+  /**
+   * Send a STOP request to the target peer that the dialing peer wants to contact
+   */
+  async stopHop ({
+    connection,
+    request
+  }: StopOptions): Promise<Stream | undefined> {
+    this.log('starting circuit relay v2 stop request to %s', connection.remotePeer)
+    const stream = await connection.newStream([RELAY_V2_STOP_CODEC], {
+      maxOutboundStreams: this.maxOutboundStopStreams,
+      runOnTransientConnection: true
+    })
+    const pbstr = pbStream(stream)
+    const stopstr = pbstr.pb(StopMessage)
+    await stopstr.write(request)
+    let response
+
+    try {
+      response = await stopstr.read()
+    } catch (err) {
+      this.log.error('error parsing stop message response from %p', connection.remotePeer)
+    }
+
+    if (response == null) {
+      this.log.error('could not read response from %p', connection.remotePeer)
+      await stream.close()
+      return
+    }
+
+    if (response.status === Status.OK) {
+      this.log('stop request to %p was successful', connection.remotePeer)
+      return pbstr.unwrap()
+    }
+
+    this.log('stop request failed with code %d', response.status)
+    await stream.close()
+  }
+
+  get reservations (): PeerMap<RelayReservation> {
+    return this.reservationStore.reservations
+  }
+}
+
+export function circuitRelayServer (init: CircuitRelayServerInit = {}): (components: CircuitRelayServerComponents) => CircuitRelayService {
+  return (components) => {
+    return new CircuitRelayServer(components, init)
+  }
+}

package/src/server/reservation-store.ts

@@ -0,0 +1,116 @@
+import { PeerMap } from '@libp2p/peer-collections'
+import { DEFAULT_DATA_LIMIT, DEFAULT_DURATION_LIMIT, DEFAULT_MAX_RESERVATION_CLEAR_INTERVAL, DEFAULT_MAX_RESERVATION_STORE_SIZE, DEFAULT_MAX_RESERVATION_TTL } from '../constants.js'
+import { type Limit, Status } from '../pb/index.js'
+import type { RelayReservation } from '../index.js'
+import type { RecursivePartial } from '@libp2p/interface'
+import type { PeerId } from '@libp2p/interface/peer-id'
+import type { Startable } from '@libp2p/interface/startable'
+import type { Multiaddr } from '@multiformats/multiaddr'
+
+export type ReservationStatus = Status.OK | Status.PERMISSION_DENIED | Status.RESERVATION_REFUSED
+
+export interface ReservationStoreInit {
+  /*
+   * maximum number of reservations allowed, default: 15
+   */
+  maxReservations?: number
+  /*
+   * interval after which stale reservations are cleared, default: 300s
+   */
+  reservationClearInterval?: number
+  /*
+   * apply default relay limits to a new reservation, default: true
+   */
+  applyDefaultLimit?: boolean
+  /**
+   * reservation ttl, default: 2 hours
+   */
+  reservationTtl?: number
+  /**
+   * The maximum time a relayed connection can be open for
+   */
+  defaultDurationLimit?: number
+  /**
+   * The maximum amount of data allowed to be transferred over a relayed connection
+   */
+  defaultDataLimit?: bigint
+}
+
+export type ReservationStoreOptions = RecursivePartial<ReservationStoreInit>
+
+export class ReservationStore implements Startable {
+  public readonly reservations = new PeerMap<RelayReservation>()
+  private _started = false
+  private interval: any
+  private readonly maxReservations: number
+  private readonly reservationClearInterval: number
+  private readonly applyDefaultLimit: boolean
+  private readonly reservationTtl: number
+  private readonly defaultDurationLimit: number
+  private readonly defaultDataLimit: bigint
+
+  constructor (options: ReservationStoreOptions = {}) {
+    this.maxReservations = options.maxReservations ?? DEFAULT_MAX_RESERVATION_STORE_SIZE
+    this.reservationClearInterval = options.reservationClearInterval ?? DEFAULT_MAX_RESERVATION_CLEAR_INTERVAL
+    this.applyDefaultLimit = options.applyDefaultLimit !== false
+    this.reservationTtl = options.reservationTtl ?? DEFAULT_MAX_RESERVATION_TTL
+    this.defaultDurationLimit = options.defaultDurationLimit ?? DEFAULT_DURATION_LIMIT
+    this.defaultDataLimit = options.defaultDataLimit ?? DEFAULT_DATA_LIMIT
+  }
+
+  isStarted (): boolean {
+    return this._started
+  }
+
+  start (): void {
+    if (this._started) {
+      return
+    }
+    this._started = true
+    this.interval = setInterval(
+      () => {
+        const now = (new Date()).getTime()
+        this.reservations.forEach((r, k) => {
+          if (r.expire.getTime() < now) {
+            this.reservations.delete(k)
+          }
+        })
+      },
+      this.reservationClearInterval
+    )
+  }
+
+  stop (): void {
+    clearInterval(this.interval)
+  }
+
+  reserve (peer: PeerId, addr: Multiaddr, limit?: Limit): { status: ReservationStatus, expire?: number } {
+    if (this.reservations.size >= this.maxReservations && !this.reservations.has(peer)) {
+      return { status: Status.RESERVATION_REFUSED }
+    }
+
+    const expire = new Date(Date.now() + this.reservationTtl)
+    let checkedLimit: Limit | undefined
+
+    if (this.applyDefaultLimit) {
+      checkedLimit = limit ?? { data: this.defaultDataLimit, duration: this.defaultDurationLimit }
+    }
+
+    this.reservations.set(peer, { addr, expire, limit: checkedLimit })
+
+    // return expiry time in seconds
+    return { status: Status.OK, expire: Math.round(expire.getTime() / 1000) }
+  }
+
+  removeReservation (peer: PeerId): void {
+    this.reservations.delete(peer)
+  }
+
+  hasReservation (dst: PeerId): boolean {
+    return this.reservations.has(dst)
+  }
+
+  get (peer: PeerId): RelayReservation | undefined {
+    return this.reservations.get(peer)
+  }
+}

package/src/server/reservation-voucher.ts

@@ -0,0 +1,51 @@
+import { ReservationVoucher } from '../pb/index.js'
+import type { PeerId } from '@libp2p/interface/peer-id'
+import type { Record } from '@libp2p/interface/record'
+
+export interface ReservationVoucherOptions {
+  relay: PeerId
+  peer: PeerId
+  expiration: number
+}
+
+export class ReservationVoucherRecord implements Record {
+  public readonly domain = 'libp2p-relay-rsvp'
+  public readonly codec = new Uint8Array([0x03, 0x02])
+
+  private readonly relay: PeerId
+  private readonly peer: PeerId
+  private readonly expiration: number
+
+  constructor ({ relay, peer, expiration }: ReservationVoucherOptions) {
+    this.relay = relay
+    this.peer = peer
+    this.expiration = expiration
+  }
+
+  marshal (): Uint8Array {
+    return ReservationVoucher.encode({
+      relay: this.relay.toBytes(),
+      peer: this.peer.toBytes(),
+      expiration: BigInt(this.expiration)
+    })
+  }
+
+  equals (other: Record): boolean {
+    if (!(other instanceof ReservationVoucherRecord)) {
+      return false
+    }
+    if (!this.peer.equals(other.peer)) {
+      return false
+    }
+
+    if (!this.relay.equals(other.relay)) {
+      return false
+    }
+
+    if (this.expiration !== other.expiration) {
+      return false
+    }
+
+    return true
+  }
+}