@helia/bitswap 0.0.0-329652a

package/src/bitswap.ts

@@ -0,0 +1,152 @@
+/* eslint-disable no-loop-func */
+import { DEFAULT_SESSION_MAX_PROVIDERS, DEFAULT_SESSION_MIN_PROVIDERS, DEFAULT_SESSION_PROVIDER_QUERY_CONCURRENCY } from '@helia/interface'
+import { setMaxListeners } from '@libp2p/interface'
+import { anySignal } from 'any-signal'
+import { Network } from './network.js'
+import { PeerWantLists } from './peer-want-lists/index.js'
+import { createBitswapSession } from './session.js'
+import { Stats } from './stats.js'
+import { WantList } from './want-list.js'
+import type { BitswapOptions, Bitswap as BitswapInterface, BitswapWantProgressEvents, BitswapNotifyProgressEvents, BitswapSession, WantListEntry, BitswapComponents, CreateBitswapSessionOptions } from './index.js'
+import type { ComponentLogger, PeerId } from '@libp2p/interface'
+import type { Logger } from '@libp2p/logger'
+import type { AbortOptions } from '@multiformats/multiaddr'
+import type { Blockstore } from 'interface-blockstore'
+import type { CID } from 'multiformats/cid'
+import type { ProgressOptions } from 'progress-events'
+
+export interface WantOptions extends AbortOptions, ProgressOptions<BitswapWantProgressEvents> {
+  /**
+   * When searching the routing for providers, stop searching after finding this
+   * many providers.
+   *
+   * @default 3
+   */
+  maxProviders?: number
+}
+
+/**
+ * JavaScript implementation of the Bitswap 'data exchange' protocol
+ * used by IPFS.
+ */
+export class Bitswap implements BitswapInterface {
+  private readonly log: Logger
+  private readonly logger: ComponentLogger
+  public readonly stats: Stats
+  public network: Network
+  public blockstore: Blockstore
+  public peerWantLists: PeerWantLists
+  public wantList: WantList
+
+  constructor (components: BitswapComponents, init: BitswapOptions = {}) {
+    this.logger = components.logger
+    this.log = components.logger.forComponent('helia:bitswap')
+    this.blockstore = components.blockstore
+
+    // report stats to libp2p metrics
+    this.stats = new Stats(components)
+
+    // the network delivers messages
+    this.network = new Network(components, init)
+
+    // handle which blocks we send to peers
+    this.peerWantLists = new PeerWantLists({
+      ...components,
+      network: this.network
+    }, init)
+
+    // handle which blocks we ask peers for
+    this.wantList = new WantList({
+      ...components,
+      network: this.network
+    }, init)
+  }
+
+  async createSession (root: CID, options?: CreateBitswapSessionOptions): Promise<BitswapSession> {
+    const minProviders = options?.minProviders ?? DEFAULT_SESSION_MIN_PROVIDERS
+    const maxProviders = options?.maxProviders ?? DEFAULT_SESSION_MAX_PROVIDERS
+
+    return createBitswapSession({
+      wantList: this.wantList,
+      network: this.network,
+      logger: this.logger
+    }, {
+      root,
+      queryConcurrency: options?.providerQueryConcurrency ?? DEFAULT_SESSION_PROVIDER_QUERY_CONCURRENCY,
+      minProviders,
+      maxProviders,
+      connectedPeers: options?.queryConnectedPeers !== false ? [...this.wantList.peers.keys()] : [],
+      signal: options?.signal
+    })
+  }
+
+  async want (cid: CID, options: WantOptions = {}): Promise<Uint8Array> {
+    const controller = new AbortController()
+    setMaxListeners(Infinity, controller.signal)
+    const signal = anySignal([controller.signal, options.signal])
+
+    // find providers and connect to them
+    this.network.findAndConnect(cid, {
+      ...options,
+      signal
+    })
+      .catch(err => {
+        // if the controller was aborted we found the block already so ignore
+        // the error
+        if (!controller.signal.aborted) {
+          this.log.error('error during finding and connect for cid %c', cid, err)
+        }
+      })
+
+    try {
+      const result = await this.wantList.wantBlock(cid, {
+        ...options,
+        signal
+      })
+
+      return result.block
+    } finally {
+      // since we have the block we can now abort any outstanding attempts to
+      // find providers for it
+      controller.abort()
+      signal.clear()
+    }
+  }
+
+  /**
+   * Sends notifications about the arrival of a block
+   */
+  async notify (cid: CID, block: Uint8Array, options: ProgressOptions<BitswapNotifyProgressEvents> & AbortOptions = {}): Promise<void> {
+    await this.peerWantLists.receivedBlock(cid, options)
+  }
+
+  getWantlist (): WantListEntry[] {
+    return [...this.wantList.wants.values()]
+      .filter(entry => !entry.cancel)
+      .map(entry => ({
+        cid: entry.cid,
+        priority: entry.priority,
+        wantType: entry.wantType
+      }))
+  }
+
+  getPeerWantlist (peer: PeerId): WantListEntry[] | undefined {
+    return this.peerWantLists.wantListForPeer(peer)
+  }
+
+  /**
+   * Start the bitswap node
+   */
+  async start (): Promise<void> {
+    this.wantList.start()
+    await this.network.start()
+  }
+
+  /**
+   * Stop the bitswap node
+   */
+  async stop (): Promise<void> {
+    this.wantList.stop()
+    await this.network.stop()
+  }
+}

package/src/constants.ts

@@ -0,0 +1,11 @@
+export const BITSWAP_120 = '/ipfs/bitswap/1.2.0'
+export const DEFAULT_MAX_SIZE_REPLACE_HAS_WITH_BLOCK = 1024
+export const DEFAULT_MAX_INBOUND_STREAMS = 1024
+export const DEFAULT_MAX_OUTBOUND_STREAMS = 1024
+export const DEFAULT_MESSAGE_RECEIVE_TIMEOUT = 5000
+export const DEFAULT_MESSAGE_SEND_DELAY = 10
+export const DEFAULT_MESSAGE_SEND_TIMEOUT = 5000
+export const DEFAULT_MESSAGE_SEND_CONCURRENCY = 50
+export const DEFAULT_RUN_ON_TRANSIENT_CONNECTIONS = false
+export const DEFAULT_SESSION_ROOT_PRIORITY = 1
+export const DEFAULT_MAX_PROVIDERS_PER_REQUEST = 3

package/src/index.ts

@@ -0,0 +1,215 @@
+/**
+ * @packageDocumentation
+ *
+ * This module implements the [Bitswap protocol](https://docs.ipfs.tech/concepts/bitswap/) in TypeScript.
+ *
+ * It supersedes the older [ipfs-bitswap](https://www.npmjs.com/package/ipfs-bitswap) module with the aim of being smaller, faster, better integrated with libp2p/helia, having fewer dependencies and using standard JavaScript instead of Node.js APIs.
+ */
+
+import { Bitswap as BitswapClass } from './bitswap.js'
+import type { BitswapNetworkNotifyProgressEvents, BitswapNetworkWantProgressEvents } from './network.js'
+import type { WantType } from './pb/message.js'
+import type { CreateSessionOptions } from '@helia/interface'
+import type { Routing } from '@helia/interface/routing'
+import type { Libp2p, AbortOptions, Startable, ComponentLogger, Metrics, PeerId } from '@libp2p/interface'
+import type { PeerSet } from '@libp2p/peer-collections'
+import type { Blockstore } from 'interface-blockstore'
+import type { CID } from 'multiformats/cid'
+import type { MultihashHasher } from 'multiformats/hashes/interface'
+import type { ProgressEvent, ProgressOptions } from 'progress-events'
+
+export type BitswapWantProgressEvents =
+  BitswapWantBlockProgressEvents
+
+export type BitswapNotifyProgressEvents =
+  BitswapNetworkNotifyProgressEvents
+
+export type BitswapWantBlockProgressEvents =
+  ProgressEvent<'bitswap:want-block:unwant', CID> |
+  ProgressEvent<'bitswap:want-block:block', CID> |
+  BitswapNetworkWantProgressEvents
+
+/**
+ * A bitswap session is a network overlay consisting of peers that all have the
+ * first block in a file. Subsequent requests will only go to these peers.
+ */
+export interface BitswapSession {
+  /**
+   * The peers in this session
+   */
+  peers: PeerSet
+
+  /**
+   * Fetch an additional CID from this DAG
+   */
+  want(cid: CID, options?: AbortOptions & ProgressOptions<BitswapWantProgressEvents>): Promise<Uint8Array>
+}
+
+export interface WantListEntry {
+  cid: CID
+  priority: number
+  wantType: WantType
+}
+
+export interface CreateBitswapSessionOptions extends CreateSessionOptions<BitswapWantProgressEvents> {
+  /**
+   * If true, query connected peers before searching for providers via
+   * Helia routers
+   *
+   * @default true
+   */
+  queryConnectedPeers?: boolean
+
+  /**
+   * If true, search for providers via Helia routers to query for the root CID
+   *
+   * @default true
+   */
+  queryRoutingPeers?: boolean
+
+  /**
+   * The priority to use when querying availability of the root CID
+   *
+   * @default 1
+   */
+  priority?: number
+}
+
+export interface Bitswap extends Startable {
+  /**
+   * Returns the current state of the wantlist
+   */
+  getWantlist(): WantListEntry[]
+
+  /**
+   * Returns the current state of the wantlist for a peer, if it is being
+   * tracked
+   */
+  getPeerWantlist(peerId: PeerId): WantListEntry[] | undefined
+
+  /**
+   * Notify bitswap that a new block is available
+   */
+  notify(cid: CID, block: Uint8Array, options?: ProgressOptions<BitswapNotifyProgressEvents>): Promise<void>
+
+  /**
+   * Start a session to retrieve a file from the network
+   */
+  want(cid: CID, options?: AbortOptions & ProgressOptions<BitswapWantProgressEvents>): Promise<Uint8Array>
+
+  /**
+   * Start a session to retrieve a file from the network
+   */
+  createSession(root: CID, options?: AbortOptions & ProgressOptions<BitswapWantProgressEvents>): Promise<BitswapSession>
+}
+
+export interface MultihashHasherLoader {
+  getHasher(codeOrName: number | string): Promise<MultihashHasher>
+}
+
+export interface BitswapComponents {
+  routing: Routing
+  blockstore: Blockstore
+  logger: ComponentLogger
+  libp2p: Libp2p
+  metrics?: Metrics
+}
+
+export interface BitswapOptions {
+  /**
+   * This is the maximum number of concurrent inbound bitswap streams that are
+   * allowed
+   *
+   * @default 32
+   */
+  maxInboundStreams?: number
+
+  /**
+   * This is the maximum number of concurrent outbound bitswap streams that are
+   * allowed
+   *
+   * @default 128
+   */
+  maxOutboundStreams?: number
+
+  /**
+   * An incoming stream must resolve within this number of seconds
+   *
+   * @default 30000
+   */
+  incomingStreamTimeout?: number
+
+  /**
+   * Whether to run on transient (e.g. time/data limited) connections
+   *
+   * @default false
+   */
+  runOnTransientConnections?: boolean
+
+  /**
+   * Enables loading esoteric hash functions
+   */
+  hashLoader?: MultihashHasherLoader
+
+  /**
+   * The protocol that we speak
+   *
+   * @default '/ipfs/bitswap/1.2.0'
+   */
+  protocol?: string
+
+  /**
+   * When a new peer connects, sending our WantList should complete within this
+   * many ms
+   *
+   * @default 5000
+   */
+  messageSendTimeout?: number
+
+  /**
+   * When sending want list updates to peers, how many messages to send at once
+   *
+   * @default 50
+   */
+  messageSendConcurrency?: number
+
+  /**
+   * When sending blocks to peers, how many messages to send at once
+   *
+   * @default 50
+   */
+  sendBlocksConcurrency?: number
+
+  /**
+   * When sending blocks to peers, timeout after this many milliseconds.
+   * This is useful for preventing slow/large peer-connections from consuming
+   * your bandwidth/streams.
+   *
+   * @default 10000
+   */
+  sendBlocksTimeout?: number
+
+  /**
+   * When a block is added to the blockstore and we are about to send that block
+   * to peers who have it in their wantlist, wait this many milliseconds before
+   * queueing the send job in case more blocks are added that they want
+   *
+   * @default 10
+   */
+  sendBlocksDebounce?: number
+
+  /**
+   * If the client sends a want-have, and we have the corresponding block, we
+   * check the size of the block and if it's small enough we send the block
+   * itself, rather than sending a HAVE.
+   *
+   * This defines the maximum size up to which we replace a HAVE with a block.
+   *
+   * @default 1024
+   */
+  maxSizeReplaceHasWithBlock?: number
+}
+
+export const createBitswap = (components: BitswapComponents, options: BitswapOptions = {}): Bitswap => {
+  return new BitswapClass(components, options)
+}