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

package/src/transport/reservation-store.ts

@@ -0,0 +1,312 @@
+import { TypedEventEmitter, type TypedEventTarget } from '@libp2p/interface/events'
+import { PeerMap } from '@libp2p/peer-collections'
+import { PeerJobQueue } from '@libp2p/utils/peer-job-queue'
+import { multiaddr } from '@multiformats/multiaddr'
+import { pbStream } from 'it-protobuf-stream'
+import { DEFAULT_RESERVATION_CONCURRENCY, RELAY_TAG, RELAY_V2_HOP_CODEC } from '../constants.js'
+import { HopMessage, Status } from '../pb/index.js'
+import { getExpirationMilliseconds } from '../utils.js'
+import type { Reservation } from '../pb/index.js'
+import type { Libp2pEvents, AbortOptions, ComponentLogger, Logger } from '@libp2p/interface'
+import type { Connection } from '@libp2p/interface/connection'
+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 { TransportManager } from '@libp2p/interface-internal/transport-manager'
+
+// allow refreshing a relay reservation if it will expire in the next 10 minutes
+const REFRESH_WINDOW = (60 * 1000) * 10
+
+// try to refresh relay reservations 5 minutes before expiry
+const REFRESH_TIMEOUT = (60 * 1000) * 5
+
+// minimum duration before which a reservation must not be refreshed
+const REFRESH_TIMEOUT_MIN = 30 * 1000
+
+export interface RelayStoreComponents {
+  peerId: PeerId
+  connectionManager: ConnectionManager
+  transportManager: TransportManager
+  peerStore: PeerStore
+  events: TypedEventTarget<Libp2pEvents>
+  logger: ComponentLogger
+}
+
+export interface RelayStoreInit {
+  /**
+   * Multiple relays may be discovered simultaneously - to prevent listening
+   * on too many relays, this value controls how many to attempt to reserve a
+   * slot on at once. If set to more than one, we may end up listening on
+   * more relays than the `maxReservations` value, but on networks with poor
+   * connectivity the user may wish to attempt to reserve on multiple relays
+   * simultaneously. (default: 1)
+   */
+  reservationConcurrency?: number
+
+  /**
+   * How many discovered relays to allow in the reservation store
+   */
+  discoverRelays?: number
+
+  /**
+   * Limit the number of potential relays we will dial (default: 100)
+   */
+  maxReservationQueueLength?: number
+
+  /**
+   * When creating a reservation it must complete within this number of ms
+   * (default: 5000)
+   */
+  reservationCompletionTimeout?: number
+}
+
+export type RelayType = 'discovered' | 'configured'
+
+interface RelayEntry {
+  timeout: ReturnType<typeof setTimeout>
+  type: RelayType
+  reservation: Reservation
+}
+
+export interface ReservationStoreEvents {
+  'relay:not-enough-relays': CustomEvent
+  'relay:removed': CustomEvent<PeerId>
+}
+
+export class ReservationStore extends TypedEventEmitter<ReservationStoreEvents> implements Startable {
+  private readonly peerId: PeerId
+  private readonly connectionManager: ConnectionManager
+  private readonly transportManager: TransportManager
+  private readonly peerStore: PeerStore
+  private readonly events: TypedEventTarget<Libp2pEvents>
+  private readonly reserveQueue: PeerJobQueue
+  private readonly reservations: PeerMap<RelayEntry>
+  private readonly maxDiscoveredRelays: number
+  private readonly maxReservationQueueLength: number
+  private readonly reservationCompletionTimeout: number
+  private started: boolean
+  private readonly log: Logger
+
+  constructor (components: RelayStoreComponents, init?: RelayStoreInit) {
+    super()
+
+    this.log = components.logger.forComponent('libp2p:circuit-relay:transport:reservation-store')
+    this.peerId = components.peerId
+    this.connectionManager = components.connectionManager
+    this.transportManager = components.transportManager
+    this.peerStore = components.peerStore
+    this.events = components.events
+    this.reservations = new PeerMap()
+    this.maxDiscoveredRelays = init?.discoverRelays ?? 0
+    this.maxReservationQueueLength = init?.maxReservationQueueLength ?? 100
+    this.reservationCompletionTimeout = init?.reservationCompletionTimeout ?? 10000
+    this.started = false
+
+    // ensure we don't listen on multiple relays simultaneously
+    this.reserveQueue = new PeerJobQueue({
+      concurrency: init?.reservationConcurrency ?? DEFAULT_RESERVATION_CONCURRENCY
+    })
+
+    // When a peer disconnects, if we had a reservation on that peer
+    // remove the reservation and multiaddr and maybe trigger search
+    // for new relays
+    this.events.addEventListener('peer:disconnect', (evt) => {
+      this.#removeRelay(evt.detail)
+    })
+  }
+
+  isStarted (): boolean {
+    return this.started
+  }
+
+  async start (): Promise<void> {
+    this.started = true
+  }
+
+  async stop (): Promise<void> {
+    this.reserveQueue.clear()
+    this.reservations.forEach(({ timeout }) => {
+      clearTimeout(timeout)
+    })
+    this.reservations.clear()
+    this.started = false
+  }
+
+  /**
+   * If the number of current relays is beneath the configured `maxReservations`
+   * value, and the passed peer id is not our own, and we have a non-relayed connection
+   * to the remote, and the remote peer speaks the hop protocol, try to reserve a slot
+   * on the remote peer
+   */
+  async addRelay (peerId: PeerId, type: RelayType): Promise<void> {
+    if (this.peerId.equals(peerId)) {
+      this.log('not trying to use self as relay')
+      return
+    }
+
+    if (this.reserveQueue.size > this.maxReservationQueueLength) {
+      this.log('not adding relay as the queue is full')
+      return
+    }
+
+    if (this.reserveQueue.hasJob(peerId)) {
+      this.log('relay peer is already in the reservation queue')
+      return
+    }
+
+    this.log('add relay %p', peerId)
+
+    await this.reserveQueue.add(async () => {
+      try {
+        // allow refresh of an existing reservation if it is about to expire
+        const existingReservation = this.reservations.get(peerId)
+
+        if (existingReservation != null) {
+          if (getExpirationMilliseconds(existingReservation.reservation.expire) > REFRESH_WINDOW) {
+            this.log('already have reservation on relay peer %p and it expires in more than 10 minutes', peerId)
+            return
+          }
+
+          clearTimeout(existingReservation.timeout)
+          this.reservations.delete(peerId)
+        }
+
+        if (type === 'discovered' && [...this.reservations.values()].reduce((acc, curr) => {
+          if (curr.type === 'discovered') {
+            acc++
+          }
+
+          return acc
+        }, 0) >= this.maxDiscoveredRelays) {
+          this.log('already have enough discovered relays')
+          return
+        }
+
+        const signal = AbortSignal.timeout(this.reservationCompletionTimeout)
+
+        const connection = await this.connectionManager.openConnection(peerId, {
+          signal
+        })
+
+        if (connection.remoteAddr.protoNames().includes('p2p-circuit')) {
+          this.log('not creating reservation over relayed connection')
+          return
+        }
+
+        const reservation = await this.#createReservation(connection, {
+          signal
+        })
+
+        this.log('created reservation on relay peer %p', peerId)
+
+        const expiration = getExpirationMilliseconds(reservation.expire)
+
+        // sets a lower bound on the timeout, and also don't let it go over
+        // 2^31 - 1 (setTimeout will only accept signed 32 bit integers)
+        const timeoutDuration = Math.min(Math.max(expiration - REFRESH_TIMEOUT, REFRESH_TIMEOUT_MIN), Math.pow(2, 31) - 1)
+
+        const timeout = setTimeout(() => {
+          this.addRelay(peerId, type).catch(err => {
+            this.log.error('could not refresh reservation to relay %p', peerId, err)
+          })
+        }, timeoutDuration)
+
+        // we've managed to create a reservation successfully
+        this.reservations.set(peerId, {
+          timeout,
+          reservation,
+          type
+        })
+
+        // ensure we don't close the connection to the relay
+        await this.peerStore.merge(peerId, {
+          tags: {
+            [RELAY_TAG]: {
+              value: 1,
+              ttl: expiration
+            }
+          }
+        })
+
+        // listen on multiaddr that only the circuit transport is listening for
+        await this.transportManager.listen([multiaddr(`/p2p/${peerId.toString()}/p2p-circuit`)])
+      } catch (err) {
+        this.log.error('could not reserve slot on %p', peerId, err)
+
+        // cancel the renewal timeout if it's been set
+        const reservation = this.reservations.get(peerId)
+
+        if (reservation != null) {
+          clearTimeout(reservation.timeout)
+        }
+
+        // if listening failed, remove the reservation
+        this.reservations.delete(peerId)
+      }
+    }, {
+      peerId
+    })
+  }
+
+  hasReservation (peerId: PeerId): boolean {
+    return this.reservations.has(peerId)
+  }
+
+  getReservation (peerId: PeerId): Reservation | undefined {
+    return this.reservations.get(peerId)?.reservation
+  }
+
+  async #createReservation (connection: Connection, options: AbortOptions): Promise<Reservation> {
+    options.signal?.throwIfAborted()
+
+    this.log('requesting reservation from %p', connection.remotePeer)
+    const stream = await connection.newStream(RELAY_V2_HOP_CODEC, options)
+    const pbstr = pbStream(stream)
+    const hopstr = pbstr.pb(HopMessage)
+    await hopstr.write({ type: HopMessage.Type.RESERVE }, options)
+
+    let response: HopMessage
+
+    try {
+      response = await hopstr.read(options)
+    } catch (err: any) {
+      this.log.error('error parsing reserve message response from %p because', connection.remotePeer, err)
+      throw err
+    } finally {
+      await stream.close()
+    }
+
+    if (response.status === Status.OK && (response.reservation != null)) {
+      return response.reservation
+    }
+
+    const errMsg = `reservation failed with status ${response.status ?? 'undefined'}`
+    this.log.error(errMsg)
+
+    throw new Error(errMsg)
+  }
+
+  /**
+   * Remove listen relay
+   */
+  #removeRelay (peerId: PeerId): void {
+    const existingReservation = this.reservations.get(peerId)
+
+    if (existingReservation == null) {
+      return
+    }
+
+    this.log('connection to relay %p closed, removing reservation from local store', peerId)
+
+    clearTimeout(existingReservation.timeout)
+    this.reservations.delete(peerId)
+
+    this.safeDispatchEvent('relay:removed', { detail: peerId })
+
+    if (this.reservations.size < this.maxDiscoveredRelays) {
+      this.log('not enough relays %d/%d', this.reservations.size, this.maxDiscoveredRelays)
+      this.safeDispatchEvent('relay:not-enough-relays', {})
+    }
+  }
+}

package/src/utils.ts

@@ -0,0 +1,134 @@
+import { CodeError } from '@libp2p/interface/errors'
+import { anySignal } from 'any-signal'
+import { CID } from 'multiformats/cid'
+import { sha256 } from 'multiformats/hashes/sha2'
+import { ERR_TRANSFER_LIMIT_EXCEEDED } from './constants.js'
+import type { Limit } from './pb/index.js'
+import type { LoggerOptions } from '@libp2p/interface'
+import type { Stream } from '@libp2p/interface/connection'
+import type { Source } from 'it-stream-types'
+import type { Uint8ArrayList } from 'uint8arraylist'
+
+async function * countStreamBytes (source: Source<Uint8Array | Uint8ArrayList>, limit: { remaining: bigint }, options: LoggerOptions): AsyncGenerator<Uint8Array | Uint8ArrayList, void, unknown> {
+  const limitBytes = limit.remaining
+
+  for await (const buf of source) {
+    const len = BigInt(buf.byteLength)
+
+    if ((limit.remaining - len) < 0) {
+      // this is a safe downcast since len is guarantee to be in the range for a number
+      const remaining = Number(limit.remaining)
+      limit.remaining = 0n
+
+      try {
+        if (remaining !== 0) {
+          yield buf.subarray(0, remaining)
+        }
+      } catch (err: any) {
+        options.log.error(err)
+      }
+
+      throw new CodeError(`data limit of ${limitBytes} bytes exceeded`, ERR_TRANSFER_LIMIT_EXCEEDED)
+    }
+
+    limit.remaining -= len
+    yield buf
+  }
+}
+
+export function createLimitedRelay (src: Stream, dst: Stream, abortSignal: AbortSignal, limit: Limit | undefined, options: LoggerOptions): void {
+  function abortStreams (err: Error): void {
+    src.abort(err)
+    dst.abort(err)
+    clearTimeout(timeout)
+  }
+
+  const abortController = new AbortController()
+  const signal = anySignal([abortSignal, abortController.signal])
+
+  let timeout: ReturnType<typeof setTimeout> | undefined
+
+  if (limit?.duration != null) {
+    timeout = setTimeout(() => {
+      abortController.abort()
+    }, limit.duration)
+  }
+
+  let srcDstFinished = false
+  let dstSrcFinished = false
+
+  let dataLimit: { remaining: bigint } | undefined
+
+  if (limit?.data != null) {
+    dataLimit = {
+      remaining: limit.data
+    }
+  }
+
+  queueMicrotask(() => {
+    const onAbort = (): void => {
+      dst.abort(new CodeError(`duration limit of ${limit?.duration} ms exceeded`, ERR_TRANSFER_LIMIT_EXCEEDED))
+    }
+
+    signal.addEventListener('abort', onAbort, { once: true })
+
+    void dst.sink(dataLimit == null ? src.source : countStreamBytes(src.source, dataLimit, options))
+      .catch(err => {
+        options.log.error('error while relaying streams src -> dst', err)
+        abortStreams(err)
+      })
+      .finally(() => {
+        srcDstFinished = true
+
+        if (dstSrcFinished) {
+          signal.removeEventListener('abort', onAbort)
+          signal.clear()
+          clearTimeout(timeout)
+        }
+      })
+  })
+
+  queueMicrotask(() => {
+    const onAbort = (): void => {
+      src.abort(new CodeError(`duration limit of ${limit?.duration} ms exceeded`, ERR_TRANSFER_LIMIT_EXCEEDED))
+    }
+
+    signal.addEventListener('abort', onAbort, { once: true })
+
+    void src.sink(dataLimit == null ? dst.source : countStreamBytes(dst.source, dataLimit, options))
+      .catch(err => {
+        options.log.error('error while relaying streams dst -> src', err)
+        abortStreams(err)
+      })
+      .finally(() => {
+        dstSrcFinished = true
+
+        if (srcDstFinished) {
+          signal.removeEventListener('abort', onAbort)
+          signal.clear()
+          clearTimeout(timeout)
+        }
+      })
+  })
+}
+
+/**
+ * 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)
+}
+
+/**
+ * returns number of ms between now and expiration time
+ */
+export function getExpirationMilliseconds (expireTimeSeconds: bigint): number {
+  const expireTimeMillis = expireTimeSeconds * BigInt(1000)
+  const currentTime = new Date().getTime()
+
+  // downcast to number to use with setTimeout
+  return Number(expireTimeMillis - BigInt(currentTime))
+}