@helia/delegated-routing-v1-http-api-client 0.0.0

package/src/client.ts

@@ -0,0 +1,266 @@
+import { CodeError } from '@libp2p/interface/errors'
+import { logger } from '@libp2p/logger'
+import { peerIdFromString } from '@libp2p/peer-id'
+import { multiaddr } from '@multiformats/multiaddr'
+import { anySignal } from 'any-signal'
+import toIt from 'browser-readablestream-to-it'
+import { unmarshal, type IPNSRecord, marshal, peerIdToRoutingKey } from 'ipns'
+import { ipnsValidator } from 'ipns/validator'
+// @ts-expect-error no types
+import ndjson from 'iterable-ndjson'
+import defer from 'p-defer'
+import PQueue from 'p-queue'
+import type { DelegatedRoutingV1HttpApiClient, DelegatedRoutingV1HttpApiClientInit, PeerRecord } from './index.js'
+import type { AbortOptions } from '@libp2p/interface'
+import type { PeerId } from '@libp2p/interface/peer-id'
+import type { CID } from 'multiformats'
+
+const log = logger('routing-v1-http-api-client')
+
+const defaultValues = {
+  concurrentRequests: 4,
+  timeout: 30e3
+}
+
+export class DefaultDelegatedRoutingV1HttpApiClient implements DelegatedRoutingV1HttpApiClient {
+  private started: boolean
+  private readonly httpQueue: PQueue
+  private readonly shutDownController: AbortController
+  private readonly clientUrl: URL
+  private readonly timeout: number
+
+  /**
+   * Create a new DelegatedContentRouting instance
+   */
+  constructor (url: string | URL, init: DelegatedRoutingV1HttpApiClientInit = {}) {
+    this.started = false
+    this.shutDownController = new AbortController()
+    this.httpQueue = new PQueue({
+      concurrency: init.concurrentRequests ?? defaultValues.concurrentRequests
+    })
+    this.clientUrl = url instanceof URL ? url : new URL(url)
+    this.timeout = init.timeout ?? defaultValues.timeout
+  }
+
+  isStarted (): boolean {
+    return this.started
+  }
+
+  start (): void {
+    this.started = true
+  }
+
+  stop (): void {
+    this.httpQueue.clear()
+    this.shutDownController.abort()
+    this.started = false
+  }
+
+  async * getProviders (cid: CID, options: AbortOptions = {}): AsyncGenerator<PeerRecord, any, unknown> {
+    log('getProviders starts: %c', cid)
+
+    const signal = anySignal([this.shutDownController.signal, options.signal, AbortSignal.timeout(this.timeout)])
+    const onStart = defer()
+    const onFinish = defer()
+
+    void this.httpQueue.add(async () => {
+      onStart.resolve()
+      return onFinish.promise
+    })
+
+    try {
+      await onStart.promise
+
+      // https://specs.ipfs.tech/routing/http-routing-v1/
+      const resource = `${this.clientUrl}routing/v1/providers/${cid.toString()}`
+      const getOptions = { headers: { Accept: 'application/x-ndjson' }, signal }
+      const res = await fetch(resource, getOptions)
+
+      if (res.body == null) {
+        throw new CodeError('Routing response had no body', 'ERR_BAD_RESPONSE')
+      }
+
+      const contentType = res.headers.get('Content-Type')
+      if (contentType === 'application/json') {
+        const body = await res.json()
+
+        for (const provider of body.Providers) {
+          const record = this.#handleProviderRecords(provider)
+          if (record != null) {
+            yield record
+          }
+        }
+      } else {
+        for await (const provider of ndjson(toIt(res.body))) {
+          const record = this.#handleProviderRecords(provider)
+          if (record != null) {
+            yield record
+          }
+        }
+      }
+    } catch (err) {
+      log.error('getProviders errored:', err)
+    } finally {
+      signal.clear()
+      onFinish.resolve()
+      log('getProviders finished: %c', cid)
+    }
+  }
+
+  async * getPeerInfo (peerId: PeerId, options: AbortOptions | undefined = {}): AsyncGenerator<PeerRecord, any, unknown> {
+    log('getPeers starts: %c', peerId)
+
+    const signal = anySignal([this.shutDownController.signal, options.signal, AbortSignal.timeout(this.timeout)])
+    const onStart = defer()
+    const onFinish = defer()
+
+    void this.httpQueue.add(async () => {
+      onStart.resolve()
+      return onFinish.promise
+    })
+
+    try {
+      await onStart.promise
+
+      // https://specs.ipfs.tech/routing/http-routing-v1/
+      const resource = `${this.clientUrl}routing/v1/peers/${peerId.toCID().toString()}`
+      const getOptions = { headers: { Accept: 'application/x-ndjson' }, signal }
+      const res = await fetch(resource, getOptions)
+
+      if (res.body == null) {
+        throw new CodeError('Routing response had no body', 'ERR_BAD_RESPONSE')
+      }
+
+      const contentType = res.headers.get('Content-Type')
+      if (contentType === 'application/json') {
+        const body = await res.json()
+
+        for (const peer of body.Peers) {
+          const record = this.#handlePeerRecords(peerId, peer)
+          if (record != null) {
+            yield record
+          }
+        }
+      } else {
+        for await (const peer of ndjson(toIt(res.body))) {
+          const record = this.#handlePeerRecords(peerId, peer)
+          if (record != null) {
+            yield record
+          }
+        }
+      }
+    } catch (err) {
+      log.error('getPeers errored:', err)
+    } finally {
+      signal.clear()
+      onFinish.resolve()
+      log('getPeers finished: %c', peerId)
+    }
+  }
+
+  async getIPNS (peerId: PeerId, options: AbortOptions = {}): Promise<IPNSRecord> {
+    log('getIPNS starts: %c', peerId)
+
+    const signal = anySignal([this.shutDownController.signal, options.signal, AbortSignal.timeout(this.timeout)])
+    const onStart = defer()
+    const onFinish = defer()
+
+    void this.httpQueue.add(async () => {
+      onStart.resolve()
+      return onFinish.promise
+    })
+
+    try {
+      await onStart.promise
+
+      // https://specs.ipfs.tech/routing/http-routing-v1/
+      const resource = `${this.clientUrl}routing/v1/ipns/${peerId.toCID().toString()}`
+      const getOptions = { headers: { Accept: 'application/vnd.ipfs.ipns-record' }, signal }
+      const res = await fetch(resource, getOptions)
+
+      if (res.body == null) {
+        throw new CodeError('GET ipns response had no body', 'ERR_BAD_RESPONSE')
+      }
+
+      const body = new Uint8Array(await res.arrayBuffer())
+      await ipnsValidator(peerIdToRoutingKey(peerId), body)
+      return unmarshal(body)
+    } finally {
+      signal.clear()
+      onFinish.resolve()
+      log('getIPNS finished: %c', peerId)
+    }
+  }
+
+  async putIPNS (peerId: PeerId, record: IPNSRecord, options: AbortOptions = {}): Promise<void> {
+    log('getIPNS starts: %c', peerId)
+
+    const signal = anySignal([this.shutDownController.signal, options.signal, AbortSignal.timeout(this.timeout)])
+    const onStart = defer()
+    const onFinish = defer()
+
+    void this.httpQueue.add(async () => {
+      onStart.resolve()
+      return onFinish.promise
+    })
+
+    try {
+      await onStart.promise
+
+      const body = marshal(record)
+
+      // https://specs.ipfs.tech/routing/http-routing-v1/
+      const resource = `${this.clientUrl}routing/v1/ipns/${peerId.toCID().toString()}`
+      const getOptions = { method: 'PUT', headers: { 'Content-Type': 'application/vnd.ipfs.ipns-record' }, body, signal }
+      const res = await fetch(resource, getOptions)
+      if (res.status !== 200) {
+        throw new CodeError('PUT ipns response had status other than 200', 'ERR_BAD_RESPONSE')
+      }
+    } finally {
+      signal.clear()
+      onFinish.resolve()
+      log('getIPNS finished: %c', peerId)
+    }
+  }
+
+  #handleProviderRecords (record: any): PeerRecord | undefined {
+    if (record.Schema === 'peer') {
+      // Peer schema can have additional, user-defined, fields.
+      record.ID = peerIdFromString(record.ID)
+      record.Addrs = record.Addrs.map(multiaddr)
+      return record
+    }
+
+    if (record.Schema === 'bitswap') {
+      // Bitswap schema is deprecated, was incorrectly used when server had no
+      // information about actual protocols, so we convert it to peer result
+      // without protocol information
+      return {
+        Schema: 'peer',
+        ID: peerIdFromString(record.ID),
+        Addrs: record.Addrs.map(multiaddr),
+        Protocols: record.Protocol != null ? [record.Protocol] : []
+      }
+    }
+
+    if (record.ID != null && Array.isArray(record.Addrs)) {
+      return {
+        Schema: 'peer',
+        ID: peerIdFromString(record.ID),
+        Addrs: record.Addrs.map(multiaddr),
+        Protocols: Array.isArray(record.Protocols) ? record.Protocols : []
+      }
+    }
+  }
+
+  #handlePeerRecords (peerId: PeerId, record: any): PeerRecord | undefined {
+    if (record.Schema === 'peer') {
+      // Peer schema can have additional, user-defined, fields.
+      record.ID = peerIdFromString(record.ID)
+      record.Addrs = record.Addrs.map(multiaddr)
+      if (peerId.equals(record.ID)) {
+        return record
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+/**
+ * @packageDocumentation
+ *
+ * Create a client to use with a Routing V1 HTTP API server.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { createRoutingV1HttpApiClient } from '@helia/routing-v1-http-api-client'
+ * import { CID } from 'multiformats/cid'
+ *
+ * const client = createRoutingV1HttpApiClient(new URL('https://example.org'))
+ *
+ * for await (const prov of getProviders(CID.parse('QmFoo'))) {
+ *   // ...
+ * }
+ * ```
+ */
+
+import { DefaultDelegatedRoutingV1HttpApiClient } from './client.js'
+import type { AbortOptions } from '@libp2p/interface'
+import type { PeerId } from '@libp2p/interface/peer-id'
+import type { Multiaddr } from '@multiformats/multiaddr'
+import type { IPNSRecord } from 'ipns'
+import type { CID } from 'multiformats/cid'
+
+export interface PeerRecord {
+  Schema: 'peer'
+  ID: PeerId
+  Addrs?: Multiaddr[]
+  Protocols?: string[]
+}
+
+export interface DelegatedRoutingV1HttpApiClientInit {
+  /**
+   * A concurrency limit to avoid request flood in web browser (default: 4)
+   *
+   * @see https://github.com/libp2p/js-libp2p-delegated-content-routing/issues/12
+   */
+  concurrentRequests?: number
+
+  /**
+   * How long a request is allowed to take in ms (default: 30 seconds)
+   */
+  timeout?: number
+}
+
+export interface DelegatedRoutingV1HttpApiClient {
+  /**
+   * Returns an async generator of PeerInfos that can provide the content
+   * for the passed CID
+   */
+  getProviders(cid: CID, options?: AbortOptions): AsyncGenerator<PeerRecord>
+
+  /**
+   * Returns an async generator of PeerInfos for the provided PeerId
+   */
+  getPeerInfo(peerId: PeerId, options?: AbortOptions): AsyncGenerator<PeerRecord>
+
+  /**
+   * Returns a promise of a IPNSRecord for the given PeerId
+   */
+  getIPNS(peerId: PeerId, options?: AbortOptions): Promise<IPNSRecord>
+
+  /**
+   * Publishes the given IPNSRecorded for the provided PeerId
+   */
+  putIPNS(peerId: PeerId, record: IPNSRecord, options?: AbortOptions): Promise<void>
+
+  /**
+   * Shut down any currently running HTTP requests and clear up any resources
+   * that are in use
+   */
+  stop(): void
+}
+
+/**
+ * Create and return a client to use with a Routing V1 HTTP API server
+ */
+export function createDelegatedRoutingV1HttpApiClient (url: URL, init: DelegatedRoutingV1HttpApiClientInit = {}): DelegatedRoutingV1HttpApiClient {
+  return new DefaultDelegatedRoutingV1HttpApiClient(url, init)
+}