@libp2p/utils 5.3.2-e1923b0a7 → 5.4.0-1488a7371

package/dist/src/filters/scalable-cuckoo-filter.js

@@ -0,0 +1,87 @@
+import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string';
+import { CuckooFilter, optimize } from './cuckoo-filter.js';
+import { fnv1a } from './hashes.js';
+import { getRandomInt } from './utils.js';
+export class ScalableCuckooFilter {
+    filterSize;
+    bucketSize;
+    fingerprintSize;
+    scale;
+    filterSeries;
+    hash;
+    seed;
+    constructor(init) {
+        this.bucketSize = init.bucketSize ?? 4;
+        this.filterSize = init.filterSize ?? (1 << 18) / this.bucketSize;
+        this.fingerprintSize = init.fingerprintSize ?? 2;
+        this.scale = init.scale ?? 2;
+        this.hash = init.hash ?? fnv1a;
+        this.seed = init.seed ?? getRandomInt(0, Math.pow(2, 10));
+        this.filterSeries = [
+            new CuckooFilter({
+                filterSize: this.filterSize,
+                bucketSize: this.bucketSize,
+                fingerprintSize: this.fingerprintSize,
+                hash: this.hash,
+                seed: this.seed
+            })
+        ];
+    }
+    add(item) {
+        if (typeof item === 'string') {
+            item = uint8ArrayFromString(item);
+        }
+        if (this.has(item)) {
+            return true;
+        }
+        let current = this.filterSeries.find((cuckoo) => {
+            return cuckoo.reliable;
+        });
+        if (current == null) {
+            const curSize = this.filterSize * Math.pow(this.scale, this.filterSeries.length);
+            current = new CuckooFilter({
+                filterSize: curSize,
+                bucketSize: this.bucketSize,
+                fingerprintSize: this.fingerprintSize,
+                hash: this.hash,
+                seed: this.seed
+            });
+            this.filterSeries.push(current);
+        }
+        return current.add(item);
+    }
+    has(item) {
+        if (typeof item === 'string') {
+            item = uint8ArrayFromString(item);
+        }
+        for (let i = 0; i < this.filterSeries.length; i++) {
+            if (this.filterSeries[i].has(item)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    remove(item) {
+        if (typeof item === 'string') {
+            item = uint8ArrayFromString(item);
+        }
+        for (let i = 0; i < this.filterSeries.length; i++) {
+            if (this.filterSeries[i].remove(item)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    get count() {
+        return this.filterSeries.reduce((acc, curr) => {
+            return acc + curr.count;
+        }, 0);
+    }
+}
+export function createScalableCuckooFilter(maxItems, errorRate = 0.001, options) {
+    return new ScalableCuckooFilter({
+        ...optimize(maxItems, errorRate),
+        ...(options ?? {})
+    });
+}
+//# sourceMappingURL=scalable-cuckoo-filter.js.map

package/dist/src/filters/scalable-cuckoo-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalable-cuckoo-filter.js","sourceRoot":"","sources":["../../../src/filters/scalable-cuckoo-filter.ts"],"names":[],"mappings":"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"}

package/dist/src/filters/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function getRandomInt(min: number, max: number): number;
+//# sourceMappingURL=utils.d.ts.map

package/dist/src/filters/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/filters/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,YAAY,CAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/dist/src/filters/utils.js

@@ -0,0 +1,4 @@
+export function getRandomInt(min, max) {
+    return Math.floor(Math.random() * (max - min)) + min;
+}
+//# sourceMappingURL=utils.js.map

package/dist/src/filters/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/filters/utils.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,YAAY,CAAE,GAAW,EAAE,GAAW;IACpD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAA;AACtD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libp2p/utils",
-  "version": "5.3.2-e1923b0a7",
+  "version": "5.4.0-1488a7371",
   "description": "Package to aggregate shared logic and dependencies for the libp2p ecosystem",
   "license": "Apache-2.0 OR MIT",
   "homepage": "https://github.com/libp2p/js-libp2p/tree/main/packages/utils#readme",
@@ -44,6 +44,10 @@
       "types": "./src/index.d.ts",
       "import": "./dist/src/index.js"
     },
+    "./abort-options": {
+      "types": "./dist/src/abort-options.d.ts",
+      "import": "./dist/src/abort-options.js"
+    },
     "./abstract-stream": {
       "types": "./dist/src/abstract-stream.d.ts",
       "import": "./dist/src/abstract-stream.js"
@@ -56,14 +60,18 @@
       "types": "./dist/src/array-equals.d.ts",
       "import": "./dist/src/array-equals.js"
     },
-    "./bloom-filter": {
-      "types": "./dist/src/bloom-filter.d.ts",
-      "import": "./dist/src/bloom-filter.js"
-    },
     "./close-source": {
       "types": "./dist/src/close-source.d.ts",
       "import": "./dist/src/close-source.js"
     },
+    "./close": {
+      "types": "./dist/src/close.d.ts",
+      "import": "./dist/src/close.js"
+    },
+    "./filters": {
+      "types": "./dist/src/filters/index.d.ts",
+      "import": "./dist/src/filters/index.js"
+    },
     "./ip-port-to-multiaddr": {
       "types": "./dist/src/ip-port-to-multiaddr.d.ts",
       "import": "./dist/src/ip-port-to-multiaddr.js"
@@ -132,12 +140,14 @@
   },
   "dependencies": {
     "@chainsafe/is-ip": "^2.0.2",
-    "@libp2p/crypto": "4.1.0-e1923b0a7",
-    "@libp2p/interface": "1.3.0-e1923b0a7",
-    "@libp2p/logger": "4.0.11-e1923b0a7",
+    "@libp2p/crypto": "4.1.1-1488a7371",
+    "@libp2p/interface": "1.3.1-1488a7371",
+    "@libp2p/logger": "4.0.12-1488a7371",
     "@multiformats/multiaddr": "^12.2.1",
     "@multiformats/multiaddr-matcher": "^1.2.0",
+    "@sindresorhus/fnv1a": "^3.1.0",
     "@types/murmurhash3js-revisited": "^3.0.3",
+    "any-signal": "^4.1.1",
     "delay": "^6.0.0",
     "get-iterator": "^2.0.1",
     "is-loopback-addr": "^2.0.2",
@@ -152,7 +162,7 @@
     "uint8arrays": "^5.0.3"
   },
   "devDependencies": {
-    "@libp2p/peer-id-factory": "4.1.0-e1923b0a7",
+    "@libp2p/peer-id-factory": "4.1.1-1488a7371",
     "@types/netmask": "^2.0.5",
     "aegir": "^42.2.5",
     "delay": "^6.0.0",

package/src/abort-options.ts

@@ -0,0 +1,20 @@
+import { setMaxListeners } from '@libp2p/interface'
+import { anySignal } from 'any-signal'
+import type { AbortOptions } from '@libp2p/interface'
+import type { ClearableSignal } from 'any-signal'
+
+export function createTimeoutOptions (timeout: number): AbortOptions
+export function createTimeoutOptions (timeout: number, ...existingSignals: AbortSignal[]): { signal: ClearableSignal }
+export function createTimeoutOptions (timeout: number, ...existingSignals: AbortSignal[]): AbortOptions {
+  let signal = AbortSignal.timeout(timeout)
+  setMaxListeners(Infinity, signal)
+
+  if (existingSignals.length > 0) {
+    signal = anySignal([signal, ...existingSignals])
+    setMaxListeners(Infinity, signal)
+  }
+
+  return {
+    signal
+  }
+}

package/src/close.ts

@@ -0,0 +1,65 @@
+import type { Connection, Stream, AbortOptions } from '@libp2p/interface'
+
+/**
+ * Close the passed stream, falling back to aborting the stream if closing
+ * cleanly fails.
+ */
+export async function safelyCloseStream (stream?: Stream, options?: AbortOptions): Promise<void> {
+  try {
+    await stream?.close(options)
+  } catch (err: any) {
+    stream?.abort(err)
+  }
+}
+
+/**
+ * These are speculative protocols that are run automatically on connection open
+ * so are usually not the reason the connection was opened.
+ *
+ * Consequently when requested it should be safe to close connections that only
+ * have these protocol streams open.
+ */
+const DEFAULT_CLOSABLE_PROTOCOLS = [
+  // identify
+  '/ipfs/id/1.0.0',
+
+  // identify-push
+  '/ipfs/id/push/1.0.0',
+
+  // autonat
+  '/libp2p/autonat/1.0.0',
+
+  // dcutr
+  '/libp2p/dcutr'
+]
+
+export interface SafelyCloseConnectionOptions extends AbortOptions {
+  /**
+   * Only close the stream if it either has no protocol streams open or only
+   * ones in this list.
+   *
+   * @default ['/ipfs/id/1.0.0']
+   */
+  closableProtocols?: string[]
+}
+
+/**
+ * Close the passed connection if it has no streams, or only closable protocol
+ * streams, falling back to aborting the connection if closing it cleanly fails.
+ */
+export async function safelyCloseConnectionIfUnused (connection?: Connection, options?: SafelyCloseConnectionOptions): Promise<void> {
+  const streamProtocols = connection?.streams?.map(stream => stream.protocol) ?? []
+  const closableProtocols = options?.closableProtocols ?? DEFAULT_CLOSABLE_PROTOCOLS
+
+  // if the connection has protocols not in the closable protocols list, do not
+  // close the connection
+  if (streamProtocols.filter(proto => proto != null && !closableProtocols.includes(proto)).length > 0) {
+    return
+  }
+
+  try {
+    await connection?.close(options)
+  } catch (err: any) {
+    connection?.abort(err)
+  }
+}

package/src/{bloom-filter.ts → filters/bloom-filter.ts}

@@ -4,6 +4,7 @@ import mur from 'murmurhash3js-revisited'
 import { Uint8ArrayList } from 'uint8arraylist'
 import { alloc } from 'uint8arrays/alloc'
 import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
+import type { Filter } from './index.js'
 
 const LN2_SQUARED = Math.LN2 * Math.LN2
 
@@ -13,16 +14,7 @@ export interface BloomFilterOptions {
   bits?: number
 }
 
-export class BloomFilter {
-  /**
-   * Create a `BloomFilter` with the smallest `bits` and `hashes` value for the
-   * specified item count and error rate.
-   */
-  static create (itemcount: number, errorRate: number = 0.005): BloomFilter {
-    const opts = optimize(itemcount, errorRate)
-    return new BloomFilter(opts)
-  }
-
+export class BloomFilter implements Filter {
   public readonly seeds: number[]
   public readonly bits: number
   public buffer: Uint8Array
@@ -111,9 +103,18 @@ export class BloomFilter {
   }
 }
 
-function optimize (itemcount: number, errorRate: number = 0.005): { bits: number, hashes: number } {
-  const bits = Math.round(-1 * itemcount * Math.log(errorRate) / LN2_SQUARED)
-  const hashes = Math.round((bits / itemcount) * Math.LN2)
+/**
+ * Create a `BloomFilter` with the smallest `bits` and `hashes` value for the
+ * specified item count and error rate.
+ */
+export function createBloomFilter (itemcount: number, errorRate: number = 0.005): Filter {
+  const opts = optimize(itemcount, errorRate)
+  return new BloomFilter(opts)
+}
+
+function optimize (itemCount: number, errorRate: number = 0.005): { bits: number, hashes: number } {
+  const bits = Math.round(-1 * itemCount * Math.log(errorRate) / LN2_SQUARED)
+  const hashes = Math.round((bits / itemCount) * Math.LN2)
 
   return { bits, hashes }
 }

package/src/filters/bucket.ts

@@ -0,0 +1,64 @@
+import { Fingerprint } from './fingerprint.js'
+import { getRandomInt } from './utils.js'
+
+export class Bucket {
+  private readonly contents: Array<Fingerprint | null>
+
+  constructor (size: number) {
+    this.contents = new Array(size).fill(null)
+  }
+
+  has (fingerprint: Fingerprint): boolean {
+    if (!(fingerprint instanceof Fingerprint)) {
+      throw new TypeError('Invalid Fingerprint')
+    }
+
+    return this.contents.some((fp) => {
+      return fingerprint.equals(fp)
+    })
+  }
+
+  add (fingerprint: Fingerprint): boolean {
+    if (!(fingerprint instanceof Fingerprint)) {
+      throw new TypeError('Invalid Fingerprint')
+    }
+
+    for (let i = 0; i < this.contents.length; i++) {
+      if (this.contents[i] == null) {
+        this.contents[i] = fingerprint
+        return true
+      }
+    }
+
+    return true
+  }
+
+  swap (fingerprint: Fingerprint): Fingerprint | null {
+    if (!(fingerprint instanceof Fingerprint)) {
+      throw new TypeError('Invalid Fingerprint')
+    }
+
+    const i = getRandomInt(0, this.contents.length - 1)
+    const current = this.contents[i]
+    this.contents[i] = fingerprint
+
+    return current
+  }
+
+  remove (fingerprint: Fingerprint): boolean {
+    if (!(fingerprint instanceof Fingerprint)) {
+      throw new TypeError('Invalid Fingerprint')
+    }
+
+    const found = this.contents.findIndex((fp) => {
+      return fingerprint.equals(fp)
+    })
+
+    if (found > -1) {
+      this.contents[found] = null
+      return true
+    } else {
+      return false
+    }
+  }
+}

package/src/filters/cuckoo-filter.ts

@@ -0,0 +1,197 @@
+import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
+import { Bucket } from './bucket.js'
+import { Fingerprint, MAX_FINGERPRINT_SIZE } from './fingerprint.js'
+import { fnv1a, type Hash } from './hashes.js'
+import { getRandomInt } from './utils.js'
+import type { Filter } from './index.js'
+
+const maxCuckooCount = 500
+
+export interface CuckooFilterInit {
+  /**
+   * How many items the filter is expected to contain
+   */
+  filterSize: number
+
+  /**
+   * How many items to put in each bucket
+   */
+  bucketSize?: number
+
+  /**
+   * How many bytes the fingerprint is expected to be
+   */
+  fingerprintSize?: number
+
+  /**
+   * A non-cryptographic hash implementation
+   */
+  hash?: Hash
+
+  /**
+   * A number used to seed the hash
+   */
+  seed?: number
+}
+
+export class CuckooFilter implements Filter {
+  private readonly bucketSize: number
+  private readonly filterSize: number
+  private readonly fingerprintSize: number
+  private readonly buckets: Bucket[]
+  public count: number
+  private readonly hash: Hash
+  private readonly seed: number
+
+  constructor (init: CuckooFilterInit) {
+    this.filterSize = init.filterSize
+    this.bucketSize = init.bucketSize ?? 4
+    this.fingerprintSize = init.fingerprintSize ?? 2
+    this.count = 0
+    this.buckets = []
+    this.hash = init.hash ?? fnv1a
+    this.seed = init.seed ?? getRandomInt(0, Math.pow(2, 10))
+  }
+
+  add (item: Uint8Array | string): boolean {
+    if (typeof item === 'string') {
+      item = uint8ArrayFromString(item)
+    }
+
+    const fingerprint = new Fingerprint(item, this.hash, this.seed, this.fingerprintSize)
+    const j = this.hash.hash(item, this.seed) % this.filterSize
+    const k = (j ^ fingerprint.hash()) % this.filterSize
+
+    if (this.buckets[j] == null) {
+      this.buckets[j] = new Bucket(this.bucketSize)
+    }
+
+    if (this.buckets[k] == null) {
+      this.buckets[k] = new Bucket(this.bucketSize)
+    }
+
+    if (this.buckets[j].add(fingerprint) || this.buckets[k].add(fingerprint)) {
+      this.count++
+      return true
+    }
+
+    const rand = [j, k]
+    let i = rand[getRandomInt(0, rand.length - 1)]
+
+    if (this.buckets[i] == null) {
+      this.buckets[i] = new Bucket(this.bucketSize)
+    }
+
+    for (let n = 0; n < maxCuckooCount; n++) {
+      const swapped = this.buckets[i].swap(fingerprint)
+
+      if (swapped == null) {
+        continue
+      }
+
+      i = (i ^ swapped.hash()) % this.filterSize
+
+      if (this.buckets[i] == null) {
+        this.buckets[i] = new Bucket(this.bucketSize)
+      }
+
+      if (this.buckets[i].add(swapped)) {
+        this.count++
+
+        return true
+      } else {
+        continue
+      }
+    }
+
+    return false
+  }
+
+  has (item: Uint8Array | string): boolean {
+    if (typeof item === 'string') {
+      item = uint8ArrayFromString(item)
+    }
+
+    const fingerprint = new Fingerprint(item, this.hash, this.seed, this.fingerprintSize)
+    const j = this.hash.hash(item, this.seed) % this.filterSize
+    const inJ = this.buckets[j]?.has(fingerprint) ?? false
+
+    if (inJ) {
+      return inJ
+    }
+
+    const k = (j ^ fingerprint.hash()) % this.filterSize
+
+    return this.buckets[k]?.has(fingerprint) ?? false
+  }
+
+  remove (item: Uint8Array | string): boolean {
+    if (typeof item === 'string') {
+      item = uint8ArrayFromString(item)
+    }
+
+    const fingerprint = new Fingerprint(item, this.hash, this.seed, this.fingerprintSize)
+    const j = this.hash.hash(item, this.seed) % this.filterSize
+    const inJ = this.buckets[j]?.remove(fingerprint) ?? false
+
+    if (inJ) {
+      this.count--
+      return inJ
+    }
+
+    const k = (j ^ fingerprint.hash()) % this.filterSize
+    const inK = this.buckets[k]?.remove(fingerprint) ?? false
+
+    if (inK) {
+      this.count--
+    }
+
+    return inK
+  }
+
+  get reliable (): boolean {
+    return Math.floor(100 * (this.count / this.filterSize)) <= 95
+  }
+}
+
+// max load constants, defined in the cuckoo paper
+const MAX_LOAD = {
+  1: 0.5,
+  2: 0.84,
+  4: 0.95,
+  8: 0.98
+}
+
+function calculateBucketSize (errorRate: number = 0.001): 2 | 4 | 8 {
+  if (errorRate > 0.002) {
+    return 2
+  }
+
+  if (errorRate > 0.00001) {
+    return 4
+  }
+
+  return 8
+}
+
+export function optimize (maxItems: number, errorRate: number = 0.001): CuckooFilterInit {
+  // https://www.eecs.harvard.edu/~michaelm/postscripts/cuckoo-conext2014.pdf
+  // Section 5.1 Optimal Bucket Size
+  const bucketSize = calculateBucketSize(errorRate)
+  const load = MAX_LOAD[bucketSize]
+
+  // https://stackoverflow.com/questions/57555236/how-to-size-a-cuckoo-filter/57617208#57617208
+  const filterSize = Math.round(maxItems / load)
+  const fingerprintSize = Math.min(Math.ceil(Math.log(filterSize / bucketSize)) + 2, MAX_FINGERPRINT_SIZE)
+
+  return {
+    filterSize,
+    bucketSize,
+    fingerprintSize
+  }
+}
+
+export function createCuckooFilter (maxItems: number, errorRate: number = 0.005): Filter {
+  const opts = optimize(maxItems, errorRate)
+  return new CuckooFilter(opts)
+}

package/src/filters/fingerprint.ts

@@ -0,0 +1,44 @@
+import { alloc as uint8ArrayAlloc } from 'uint8arrays/alloc'
+import { equals as uint8ArrayEquals } from 'uint8arrays/equals'
+import type { Hash } from './hashes'
+
+export const MAX_FINGERPRINT_SIZE = 64
+
+export class Fingerprint {
+  private readonly fp: Uint8Array
+  private readonly h: Hash
+  private readonly seed: number
+
+  constructor (buf: Uint8Array, hash: Hash, seed: number, fingerprintSize: number = 2) {
+    if (fingerprintSize > MAX_FINGERPRINT_SIZE) {
+      throw new TypeError('Invalid Fingerprint Size')
+    }
+
+    const fnv = hash.hashV(buf, seed)
+    const fp = uint8ArrayAlloc(fingerprintSize)
+
+    for (let i = 0; i < fp.length; i++) {
+      fp[i] = fnv[i]
+    }
+
+    if (fp.length === 0) {
+      fp[0] = 7
+    }
+
+    this.fp = fp
+    this.h = hash
+    this.seed = seed
+  }
+
+  hash (): number {
+    return this.h.hash(this.fp, this.seed)
+  }
+
+  equals (other?: any): boolean {
+    if (!(other?.fp instanceof Uint8Array)) {
+      return false
+    }
+
+    return uint8ArrayEquals(this.fp, other.fp)
+  }
+}

package/src/filters/hashes.ts

@@ -0,0 +1,38 @@
+import fnv1aHash from '@sindresorhus/fnv1a'
+import mur from 'murmurhash3js-revisited'
+import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
+
+export interface Hash {
+  hash(input: Uint8Array, seed: number): number
+  hashV(input: Uint8Array, seed: number): Uint8Array
+}
+
+export const murmur3: Hash = {
+  hash: (input, seed) => {
+    return mur.x86.hash32(input, seed)
+  },
+  hashV: (input, seed) => {
+    return numberToBuffer(murmur3.hash(input, seed))
+  }
+}
+
+export const fnv1a: Hash = {
+  hash: (input) => {
+    return Number(fnv1aHash(input, {
+      size: 32
+    }))
+  },
+  hashV: (input, seed) => {
+    return numberToBuffer(fnv1a.hash(input, seed))
+  }
+}
+
+export function numberToBuffer (num: bigint | number): Uint8Array {
+  let hex = num.toString(16)
+
+  if (hex.length % 2 === 1) {
+    hex = `0${hex}`
+  }
+
+  return uint8ArrayFromString(hex, 'base16')
+}

package/src/filters/index.ts

@@ -0,0 +1,9 @@
+export { BloomFilter, createBloomFilter, type BloomFilterOptions } from './bloom-filter.js'
+export { CuckooFilter, createCuckooFilter, type CuckooFilterInit } from './cuckoo-filter.js'
+export { ScalableCuckooFilter, createScalableCuckooFilter, type ScalableCuckooFilterInit } from './scalable-cuckoo-filter.js'
+
+export interface Filter {
+  add(item: Uint8Array | string): void
+  has(item: Uint8Array | string): boolean
+  remove?(buf: Uint8Array | string): boolean
+}