feat: add peer filter (#2508)

To make filtering peers in a memory-efficient way possible, add a
peer filter based on a bloom filter using the binary representation
of the peer id.

---------

Co-authored-by: Russell Dempsey <[email protected]>

packages/peer-collections/README.md

@@ -108,6 +108,20 @@ const set = trackedPeerSet({ name: 'my_metric_name', metrics: libp2p.metrics })
 set.add(peerId)
 ```
 
+## Example - Peer filters
+
+```TypeScript
+import { peerFilter } from '@libp2p/peer-collections'
+import { createEd25519PeerId } from '@libp2p/peer-id-factory'
+
+const peerId = await createEd25519PeerId()
+
+const filter = peerFilter(1024)
+filter.has(peerId) // false
+filter.add(peerId)
+filter.has(peerId) // true
+```
+
 # Install
 
 ```console

packages/peer-collections/package.json

@@ -55,7 +55,8 @@
   },
   "dependencies": {
     "@libp2p/interface": "^1.3.0",
-    "@libp2p/peer-id": "^4.1.0"
+    "@libp2p/peer-id": "^4.1.0",
+    "@libp2p/utils": "^5.3.2"
   },
   "devDependencies": {
     "@libp2p/peer-id-factory": "^4.1.0",

packages/peer-collections/src/filter.ts

@@ -0,0 +1,26 @@
+import { BloomFilter } from '@libp2p/utils/bloom-filter'
+import type { PeerId } from '@libp2p/interface'
+
+/**
+ * Uses a Bloom filter to implement a mechansim for deduplicating PeerIds in a
+ * way that uses a fixed amount of memory.
+ */
+export class PeerFilter {
+  private readonly filter: BloomFilter
+
+  constructor (size: number, errorRate?: number) {
+    this.filter = BloomFilter.create(size, errorRate)
+  }
+
+  has (peerId: PeerId): boolean {
+    return this.filter.has(peerId.toBytes())
+  }
+
+  add (peerId: PeerId): void {
+    this.filter.add(peerId.toBytes())
+  }
+}
+
+export function peerFilter (size: number): PeerFilter {
+  return new PeerFilter(size)
+}

packages/peer-collections/src/index.ts

@@ -84,11 +84,26 @@
  * const set = trackedPeerSet({ name: 'my_metric_name', metrics: libp2p.metrics })
  * set.add(peerId)
  * ```
+ *
+ * @example Peer filters
+ *
+ * ```TypeScript
+ * import { peerFilter } from '@libp2p/peer-collections'
+ * import { createEd25519PeerId } from '@libp2p/peer-id-factory'
+ *
+ * const peerId = await createEd25519PeerId()
+ *
+ * const filter = peerFilter(1024)
+ * filter.has(peerId) // false
+ * filter.add(peerId)
+ * filter.has(peerId) // true
+ * ```
  */
 
 export { PeerMap, peerMap } from './map.js'
 export { PeerSet, peerSet } from './set.js'
 export { PeerList, peerList } from './list.js'
+export { PeerFilter, peerFilter } from './filter.js'
 
 export { trackedPeerMap } from './tracked-map.js'
 export { trackedPeerSet } from './tracked-set.js'

packages/peer-collections/test/filter.spec.ts

@@ -0,0 +1,16 @@
+import { createEd25519PeerId } from '@libp2p/peer-id-factory'
+import { expect } from 'aegir/chai'
+import { PeerFilter } from '../src/index.js'
+
+describe('peer-filter', () => {
+  it('should filter a peer', async () => {
+    const filter = new PeerFilter(1024)
+    const peer = await createEd25519PeerId()
+
+    expect(filter.has(peer)).to.be.false()
+
+    filter.add(peer)
+
+    expect(filter.has(peer)).to.be.true()
+  })
+})