@helia/bitswap 3.1.2 → 3.1.3

package/src/bitswap.ts

@@ -6,7 +6,7 @@ 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, WantListEntry, BitswapComponents } from './index.js'
+import type { BitswapOptions, Bitswap as BitswapInterface, BitswapWantProgressEvents, BitswapNotifyProgressEvents, WantListEntry, BitswapComponents, PeerWantListEntry } from './index.js'
 import type { CreateSessionOptions, ProviderOptions, SessionBlockBroker } from '@helia/interface'
 import type { ComponentLogger, Libp2p, PeerId, AbortOptions } from '@libp2p/interface'
 import type { Logger } from '@libp2p/logger'
@@ -127,7 +127,7 @@ export class Bitswap implements BitswapInterface {
       }))
   }
 
-  getPeerWantlist (peer: PeerId): WantListEntry[] | undefined {
+  getPeerWantlist (peer: PeerId): PeerWantListEntry[] | undefined {
     return this.peerWantLists.wantListForPeer(peer)
   }
 

package/src/constants.ts

@@ -11,3 +11,5 @@ export const DEFAULT_SESSION_ROOT_PRIORITY = 1
 export const DEFAULT_MAX_PROVIDERS_PER_REQUEST = 3
 export const DEFAULT_MAX_OUTGOING_MESSAGE_SIZE = 1024 * 1024 * 4
 export const DEFAULT_MAX_INCOMING_MESSAGE_SIZE = DEFAULT_MAX_OUTGOING_MESSAGE_SIZE
+export const DEFAULT_DO_NOT_RESEND_BLOCK_WINDOW = 1_000 * 5
+export const DEFAULT_MAX_WANTLIST_SIZE = 1024

package/src/index.ts

@@ -35,12 +35,18 @@ export type { BitswapNetworkProgressEvents }
 export type { WantType }
 export type { BitswapProvider } from './network.ts'
 
+export type WantStatus = 'want' | 'sending' | 'sent'
+
 export interface WantListEntry {
   cid: CID
   priority: number
   wantType: WantType
 }
 
+export interface PeerWantListEntry extends WantListEntry {
+  status: WantStatus
+}
+
 export interface Bitswap extends Startable {
   /**
    * Returns the current state of the wantlist
@@ -51,7 +57,7 @@ export interface Bitswap extends Startable {
    * Returns the current state of the wantlist for a peer, if it is being
    * tracked
    */
-  getPeerWantlist(peerId: PeerId): WantListEntry[] | undefined
+  getPeerWantlist(peerId: PeerId): PeerWantListEntry[] | undefined
 
   /**
    * Notify bitswap that a new block is available
@@ -188,6 +194,21 @@ export interface BitswapOptions {
    * @default 2097152
    */
   maxIncomingMessageSize?: number
+
+  /**
+   * If a block has been sent to a peer and it is requested again by the same
+   * peer, do not send it again until this many ms have elapsed
+   *
+   * @default 5000
+   */
+  doNotResendBlockWindow?: number
+
+  /**
+   * Restrict the local copy of each peer wantlist to this many entries
+   *
+   * @default 1024
+   */
+  maxWantlistSize?: number
 }
 
 export const createBitswap = (components: BitswapComponents, options: BitswapOptions = {}): Bitswap => {

package/src/peer-want-lists/index.ts

@@ -1,9 +1,7 @@
 import { trackedPeerMap } from '@libp2p/peer-collections'
 import { CID } from 'multiformats/cid'
-import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
-import { WantType } from '../pb/message.js'
 import { Ledger } from './ledger.js'
-import type { BitswapNotifyProgressEvents, WantListEntry } from '../index.js'
+import type { BitswapNotifyProgressEvents, PeerWantListEntry } from '../index.js'
 import type { Network } from '../network.js'
 import type { BitswapMessage } from '../pb/message.js'
 import type { AbortOptions, ComponentLogger, Libp2p, Logger, Metrics, PeerId } from '@libp2p/interface'
@@ -13,6 +11,8 @@ import type { ProgressOptions } from 'progress-events'
 
 export interface PeerWantListsInit {
   maxSizeReplaceHasWithBlock?: number
+  doNotResendBlockWindow?: number
+  maxWantListSize?: number
 }
 
 export interface PeerWantListsComponents {
@@ -36,6 +36,8 @@ export class PeerWantLists {
   public network: Network
   public readonly ledgerMap: PeerMap<Ledger>
   private readonly maxSizeReplaceHasWithBlock?: number
+  private readonly doNotResendBlockWindow?: number
+  private readonly maxWantListSize?: number
   private readonly log: Logger
   private readonly logger: ComponentLogger
 
@@ -43,6 +45,8 @@ export class PeerWantLists {
     this.blockstore = components.blockstore
     this.network = components.network
     this.maxSizeReplaceHasWithBlock = init.maxSizeReplaceHasWithBlock
+    this.doNotResendBlockWindow = init.doNotResendBlockWindow
+    this.maxWantListSize = init.maxWantListSize
     this.log = components.logger.forComponent('helia:bitswap:peer-want-lists')
     this.logger = components.logger
 
@@ -78,14 +82,17 @@ export class PeerWantLists {
     }
   }
 
-  wantListForPeer (peerId: PeerId): WantListEntry[] | undefined {
+  wantListForPeer (peerId: PeerId): PeerWantListEntry[] | undefined {
     const ledger = this.ledgerMap.get(peerId)
 
     if (ledger == null) {
       return undefined
     }
 
-    return [...ledger.wants.values()]
+    // remove any expired wants
+    ledger.removeExpiredWants()
+
+    return ledger.getWants()
   }
 
   peers (): PeerId[] {
@@ -105,7 +112,9 @@ export class PeerWantLists {
         network: this.network,
         logger: this.logger
       }, {
-        maxSizeReplaceHasWithBlock: this.maxSizeReplaceHasWithBlock
+        maxSizeReplaceHasWithBlock: this.maxSizeReplaceHasWithBlock,
+        doNotResendBlockWindow: this.doNotResendBlockWindow,
+        maxWantListSize: this.maxWantListSize
       })
       this.ledgerMap.set(peerId, ledger)
     }
@@ -113,47 +122,21 @@ export class PeerWantLists {
     // record the amount of block data received
     ledger.receivedBytes(message.blocks?.reduce((acc, curr) => acc + curr.data.byteLength, 0) ?? 0)
 
-    if (message.wantlist != null) {
-      // if the message has a full wantlist, clear the current wantlist
-      if (message.wantlist.full === true) {
-        ledger.wants.clear()
-      }
+    // remove any expired wants
+    ledger.removeExpiredWants()
 
-      // clear cancelled wants and add new wants to the ledger
-      for (const entry of message.wantlist.entries) {
-        const cid = CID.decode(entry.cid)
-        const cidStr = uint8ArrayToString(cid.multihash.bytes, 'base64')
-
-        if (entry.cancel === true) {
-          this.log('peer %p cancelled want of block for %c', peerId, cid)
-          ledger.wants.delete(cidStr)
-        } else {
-          if (entry.wantType === WantType.WantHave) {
-            this.log('peer %p wanted block presence for %c', peerId, cid)
-          } else {
-            this.log('peer %p wanted block for %c', peerId, cid)
-          }
-
-          ledger.wants.set(cidStr, {
-            cid,
-            priority: entry.priority,
-            wantType: entry.wantType ?? WantType.WantBlock,
-            sendDontHave: entry.sendDontHave ?? false
-          })
-        }
-      }
-    }
+    // add new wants
+    ledger.addWants(message.wantlist)
 
     this.log('send blocks to peer')
     await ledger.sendBlocksToPeer()
   }
 
   async receivedBlock (cid: CID, options: ProgressOptions<BitswapNotifyProgressEvents> & AbortOptions): Promise<void> {
-    const cidStr = uint8ArrayToString(cid.multihash.bytes, 'base64')
     const ledgers: Ledger[] = []
 
     for (const ledger of this.ledgerMap.values()) {
-      if (ledger.wants.has(cidStr)) {
+      if (ledger.hasWant(cid)) {
         ledgers.push(ledger)
       }
     }

package/src/peer-want-lists/ledger.ts

@@ -1,12 +1,14 @@
 import toBuffer from 'it-to-buffer'
-import { DEFAULT_MAX_SIZE_REPLACE_HAS_WITH_BLOCK } from '../constants.js'
+import { CID } from 'multiformats/cid'
+import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
+import { DEFAULT_MAX_SIZE_REPLACE_HAS_WITH_BLOCK, DEFAULT_DO_NOT_RESEND_BLOCK_WINDOW, DEFAULT_MAX_WANTLIST_SIZE } from '../constants.js'
 import { BlockPresenceType, WantType } from '../pb/message.js'
 import { QueuedBitswapMessage } from '../utils/bitswap-message.js'
 import { cidToPrefix } from '../utils/cid-prefix.js'
 import type { Network } from '../network.js'
+import type { Wantlist } from '../pb/message.js'
 import type { AbortOptions, ComponentLogger, Logger, PeerId } from '@libp2p/interface'
 import type { Blockstore } from 'interface-blockstore'
-import type { CID } from 'multiformats/cid'
 
 export interface LedgerComponents {
   peerId: PeerId
@@ -17,6 +19,8 @@ export interface LedgerComponents {
 
 export interface LedgerInit {
   maxSizeReplaceHasWithBlock?: number
+  doNotResendBlockWindow?: number
+  maxWantListSize?: number
 }
 
 export interface PeerWantListEntry {
@@ -45,19 +49,50 @@ export interface PeerWantListEntry {
    * If we don't have the block and we've told them we don't have the block
    */
   sentDoNotHave?: boolean
+
+  /**
+   * If the status is `sending` or `sent`, the block for this CID is or has been
+   * sent to the peer so we should not attempt to send it again
+   */
+  status: 'want' | 'sending' | 'sent'
+
+  /**
+   * A timestamp for when this want should be removed from the list, typically
+   * this is set with the `sent` status to prevent sending duplicate blocks to a
+   * peer. Once it has expired the peer can request the block a subsequent time.
+   */
+  expires?: number
+
+  /**
+   * A timestamp of when this entry was created
+   */
+  created: number
+
+  /**
+   * If this field is false, we have attempted to send this WantList entry but
+   * found there is no block for the CID in the blockstore and we are
+   * optimistically waiting to see if we come across it later.
+   *
+   * We only perform the check when we are about to send the block, by which
+   * point the entry status is 'sending' so this value with either be false or
+   * not set
+   */
+  haveBlock?: false
 }
 
 export class Ledger {
   public peerId: PeerId
   private readonly blockstore: Blockstore
   private readonly network: Network
-  public wants: Map<string, PeerWantListEntry>
+  private wants: Map<string, PeerWantListEntry>
   public exchangeCount: number
   public bytesSent: number
   public bytesReceived: number
   public lastExchange?: number
   private readonly maxSizeReplaceHasWithBlock: number
   private readonly log: Logger
+  private readonly doNotResendBlockWindow: number
+  private readonly maxWantListSize: number
 
   constructor (components: LedgerComponents, init: LedgerInit) {
     this.peerId = components.peerId
@@ -70,6 +105,8 @@ export class Ledger {
     this.bytesSent = 0
     this.bytesReceived = 0
     this.maxSizeReplaceHasWithBlock = init.maxSizeReplaceHasWithBlock ?? DEFAULT_MAX_SIZE_REPLACE_HAS_WITH_BLOCK
+    this.doNotResendBlockWindow = init.doNotResendBlockWindow ?? DEFAULT_DO_NOT_RESEND_BLOCK_WINDOW
+    this.maxWantListSize = init.maxWantListSize ?? DEFAULT_MAX_WANTLIST_SIZE
   }
 
   sentBytes (n: number): void {
@@ -88,18 +125,174 @@ export class Ledger {
     return (this.bytesSent / (this.bytesReceived + 1)) // +1 is to prevent division by zero
   }
 
+  removeExpiredWants (): void {
+    // remove any expired wants
+    this.wants.forEach((value, key) => {
+      if (value.expires != null && value.expires < Date.now()) {
+        this.wants.delete(key)
+      }
+    })
+  }
+
+  public addWants (wantlist?: Wantlist): void {
+    if (wantlist == null) {
+      return
+    }
+
+    // if the message has a full wantlist, remove all entries not currently
+    // being sent to the peer
+    if (wantlist.full === true) {
+      this.wants.forEach((value, key) => {
+        if (value.status === 'want') {
+          this.wants.delete(key)
+        }
+      })
+    }
+
+    // clear cancelled wants and add new wants to the ledger
+    for (const entry of wantlist.entries) {
+      const cid = CID.decode(entry.cid)
+      const cidStr = uint8ArrayToString(cid.multihash.bytes, 'base64')
+
+      if (entry.cancel === true) {
+        this.log('peer %p cancelled want of block for %c', this.peerId, cid)
+        this.wants.delete(cidStr)
+      } else {
+        if (entry.wantType === WantType.WantHave) {
+          this.log('peer %p wanted block presence for %c', this.peerId, cid)
+        } else {
+          this.log('peer %p wanted block for %c', this.peerId, cid)
+        }
+
+        const existingWant = this.wants.get(cidStr)
+
+        // we are already tracking a want for this CID, just update the fields
+        if (existingWant != null) {
+          const sentOrSending = existingWant.status === 'sent' || existingWant.status === 'sending'
+          const wantTypeUpgrade = existingWant.wantType === WantType.WantHave && (entry.wantType == null || entry.wantType === WantType.WantBlock)
+
+          // allow upgrade from WantHave to WantBlock if we've previously
+          // sent or are sending a WantHave
+          if (sentOrSending && wantTypeUpgrade) {
+            existingWant.status = 'want'
+          }
+
+          existingWant.priority = entry.priority
+          existingWant.wantType = entry.wantType ?? WantType.WantBlock
+          existingWant.sendDontHave = entry.sendDontHave ?? false
+          continue
+        }
+
+        // add a new want
+        this.wants.set(cidStr, {
+          cid,
+          priority: entry.priority,
+          wantType: entry.wantType ?? WantType.WantBlock,
+          sendDontHave: entry.sendDontHave ?? false,
+          status: 'want',
+          created: Date.now()
+        })
+      }
+    }
+
+    // if we have exceeded maxWantListSize, truncate the list - first select
+    // wants that are not currently being sent to the user
+    const wants = [...this.wants.entries()]
+      .filter(([key, entry]) => entry.status === 'want')
+
+    if (wants.length > this.maxWantListSize) {
+      this.truncateWants(wants)
+    }
+  }
+
+  private truncateWants (wants: Array<[string, PeerWantListEntry]>): void {
+    // sort wants by priority, lack of block presence, then age so the wants
+    // to be evicted are a older, low priority wants that we don't have the
+    // block for
+    wants = wants
+      .sort((a, b) => {
+        if (a[1].created < b[1].created) {
+          return -1
+        }
+
+        if (b[1].created < a[1].created) {
+          return 1
+        }
+
+        return 0
+      })
+      .sort((a, b) => {
+        if (a[1].haveBlock === false) {
+          return -1
+        }
+
+        if (b[1].haveBlock === false) {
+          return 1
+        }
+
+        return 0
+      })
+      .sort((a, b) => {
+        if (a[1].priority < b[1].priority) {
+          return -1
+        }
+
+        if (b[1].priority < a[1].priority) {
+          return 1
+        }
+
+        return 0
+      })
+
+    const toRemove = wants.length - this.maxWantListSize
+
+    for (let i = 0; i < toRemove; i++) {
+      this.wants.delete(wants[i][0])
+    }
+  }
+
+  public getWants (): PeerWantListEntry[] {
+    return [...this.wants.values()]
+  }
+
+  public hasWant (cid: CID): boolean {
+    const cidStr = uint8ArrayToString(cid.multihash.bytes, 'base64')
+
+    return this.wants.has(cidStr)
+  }
+
   public async sendBlocksToPeer (options?: AbortOptions): Promise<void> {
     const message = new QueuedBitswapMessage()
     const sentBlocks = new Set<string>()
 
-    for (const [key, entry] of this.wants.entries()) {
+    // remove any expired wants
+    this.removeExpiredWants()
+
+    // pick unsent wants
+    const unsent = [...this.wants.entries()]
+      .filter(([key, value]) => value.status === 'want')
+
+    // update status, ensure we don't send the same blocks repeatedly
+    unsent.forEach(([key, value]) => {
+      value.status = 'sending'
+    })
+
+    for (const [key, entry] of unsent) {
       try {
         const block = await toBuffer(this.blockstore.get(entry.cid, options))
 
+        // ensure we still need to send the block/status, status may have
+        // changed due to incoming message while we were waiting for async block
+        // load
+        if (entry.status !== 'sending') {
+          continue
+        }
+
         // do they want the block or just us to tell them we have the block
         if (entry.wantType === WantType.WantHave) {
           if (block.byteLength < this.maxSizeReplaceHasWithBlock) {
             this.log('sending have and block for %c', entry.cid)
+
             // if the block is small we just send it to them
             sentBlocks.add(key)
             message.addBlock(entry.cid, {
@@ -123,11 +316,20 @@ export class Ledger {
             prefix: cidToPrefix(entry.cid)
           })
         }
+
+        entry.status = 'sent'
+        entry.expires = Date.now() + this.doNotResendBlockWindow
       } catch (err: any) {
         if (err.name !== 'NotFoundError') {
           throw err
         }
 
+        // reset status to try again later
+        entry.status = 'want'
+
+        // used to maybe delete this want later if the want list grows too large
+        entry.haveBlock = false
+
         this.log('do not have block for %c', entry.cid)
 
         // we don't have the requested block and the remote is not interested
@@ -157,12 +359,6 @@ export class Ledger {
 
       // update accounting
       this.sentBytes([...message.blocks.values()].reduce((acc, curr) => acc + curr.data.byteLength, 0))
-
-      // remove sent blocks from local copy of their want list - they can still
-      // re-request if required
-      for (const key of sentBlocks) {
-        this.wants.delete(key)
-      }
     }
   }
 }