@libp2p/kad-dht 9.3.4 → 9.3.6-05abd49f

package/src/query/query-path.ts

@@ -1,4 +1,4 @@
-import { CodeError } from '@libp2p/interfaces/errors'
+import { CodeError } from '@libp2p/interface/errors'
 import { anySignal } from 'any-signal'
 import defer from 'p-defer'
 import Queue from 'p-queue'
@@ -9,8 +9,8 @@ import { queryErrorEvent } from './events.js'
 import type { CleanUpEvents } from './manager.js'
 import type { QueryEvent, QueryOptions } from '../index.js'
 import type { QueryFunc } from '../query/types.js'
-import type { PeerId } from '@libp2p/interface-peer-id'
-import type { EventEmitter } from '@libp2p/interfaces/events'
+import type { EventEmitter } from '@libp2p/interface/events'
+import type { PeerId } from '@libp2p/interface/peer-id'
 import type { Logger } from '@libp2p/logger'
 import type { PeerSet } from '@libp2p/peer-collections'
 

package/src/query/types.ts

@@ -1,5 +1,5 @@
 import type { QueryEvent } from '../index.js'
-import type { PeerId } from '@libp2p/interface-peer-id'
+import type { PeerId } from '@libp2p/interface/peer-id'
 
 export interface QueryContext {
   // the key we are looking up

package/src/query-self.ts

@@ -4,11 +4,13 @@ import { anySignal } from 'any-signal'
 import length from 'it-length'
 import { pipe } from 'it-pipe'
 import take from 'it-take'
+import pDefer from 'p-defer'
+import { pEvent } from 'p-event'
 import { QUERY_SELF_INTERVAL, QUERY_SELF_TIMEOUT, K, QUERY_SELF_INITIAL_INTERVAL } from './constants.js'
-import type { KadDHTComponents } from './index.js'
 import type { PeerRouting } from './peer-routing/index.js'
 import type { RoutingTable } from './routing-table/index.js'
-import type { Startable } from '@libp2p/interfaces/startable'
+import type { PeerId } from '@libp2p/interface/peer-id'
+import type { Startable } from '@libp2p/interface/startable'
 import type { DeferredPromise } from 'p-defer'
 
 export interface QuerySelfInit {
@@ -22,18 +24,8 @@ export interface QuerySelfInit {
   initialQuerySelfHasRun: DeferredPromise<void>
 }
 
-function debounce (func: () => void, wait: number): () => void {
-  let timeout: ReturnType<typeof setTimeout> | undefined
-
-  return function () {
-    const later = function (): void {
-      timeout = undefined
-      func()
-    }
-
-    clearTimeout(timeout)
-    timeout = setTimeout(later, wait)
-  }
+export interface QuerySelfComponents {
+  peerId: PeerId
 }
 
 /**
@@ -41,7 +33,7 @@ function debounce (func: () => void, wait: number): () => void {
  */
 export class QuerySelf implements Startable {
   private readonly log: Logger
-  private readonly components: KadDHTComponents
+  private readonly components: QuerySelfComponents
   private readonly peerRouting: PeerRouting
   private readonly routingTable: RoutingTable
   private readonly count: number
@@ -49,17 +41,16 @@ export class QuerySelf implements Startable {
   private readonly initialInterval: number
   private readonly queryTimeout: number
   private started: boolean
-  private running: boolean
   private timeoutId?: NodeJS.Timer
   private controller?: AbortController
   private initialQuerySelfHasRun?: DeferredPromise<void>
+  private querySelfPromise?: DeferredPromise<void>
 
-  constructor (components: KadDHTComponents, init: QuerySelfInit) {
+  constructor (components: QuerySelfComponents, init: QuerySelfInit) {
     const { peerRouting, lan, count, interval, queryTimeout, routingTable } = init
 
     this.components = components
     this.log = logger(`libp2p:kad-dht:${lan ? 'lan' : 'wan'}:query-self`)
-    this.running = false
     this.started = false
     this.peerRouting = peerRouting
     this.routingTable = routingTable
@@ -68,25 +59,28 @@ export class QuerySelf implements Startable {
     this.initialInterval = init.initialInterval ?? QUERY_SELF_INITIAL_INTERVAL
     this.queryTimeout = queryTimeout ?? QUERY_SELF_TIMEOUT
     this.initialQuerySelfHasRun = init.initialQuerySelfHasRun
-
-    this.querySelf = debounce(this.querySelf.bind(this), 100)
   }
 
   isStarted (): boolean {
     return this.started
   }
 
-  async start (): Promise<void> {
+  start (): void {
     if (this.started) {
       return
     }
 
     this.started = true
     clearTimeout(this.timeoutId)
-    this.timeoutId = setTimeout(this.querySelf.bind(this), this.initialInterval)
+    this.timeoutId = setTimeout(() => {
+      this.querySelf()
+        .catch(err => {
+          this.log.error('error running self-query', err)
+        })
+    }, this.initialInterval)
   }
 
-  async stop (): Promise<void> {
+  stop (): void {
     this.started = false
 
     if (this.timeoutId != null) {
@@ -98,84 +92,72 @@ export class QuerySelf implements Startable {
     }
   }
 
-  querySelf (): void {
+  async querySelf (): Promise<void> {
     if (!this.started) {
       this.log('skip self-query because we are not started')
       return
     }
 
-    if (this.running) {
-      this.log('skip self-query because we are already running, will run again in %dms', this.interval)
-      return
+    if (this.querySelfPromise != null) {
+      this.log('joining existing self query')
+      return this.querySelfPromise.promise
     }
 
-    if (this.routingTable.size === 0) {
-      let nextInterval = this.interval
-
-      if (this.initialQuerySelfHasRun != null) {
-        // if we've not yet run the first self query, shorten the interval until we try again
-        nextInterval = this.initialInterval
-      }
+    this.querySelfPromise = pDefer()
 
-      this.log('skip self-query because routing table is empty, will run again in %dms', nextInterval)
-      clearTimeout(this.timeoutId)
-      this.timeoutId = setTimeout(this.querySelf.bind(this), nextInterval)
-      return
+    if (this.routingTable.size === 0) {
+      // wait to discover at least one DHT peer
+      await pEvent(this.routingTable, 'peer:add')
     }
 
-    this.running = true
+    if (this.started) {
+      this.controller = new AbortController()
+      const signal = anySignal([this.controller.signal, AbortSignal.timeout(this.queryTimeout)])
 
-    Promise.resolve()
-      .then(async () => {
-        if (!this.started) {
-          this.log('not running self-query - node stopped before query started')
-          return
+      // this controller will get used for lots of dial attempts so make sure we don't cause warnings to be logged
+      try {
+        if (setMaxListeners != null) {
+          setMaxListeners(Infinity, signal)
         }
+      } catch {} // fails on node < 15.4
 
-        this.controller = new AbortController()
-        const signal = anySignal([this.controller.signal, AbortSignal.timeout(this.queryTimeout)])
-
-        // this controller will get used for lots of dial attempts so make sure we don't cause warnings to be logged
-        try {
-          if (setMaxListeners != null) {
-            setMaxListeners(Infinity, signal)
-          }
-        } catch {} // fails on node < 15.4
-
-        try {
-          this.log('run self-query, look for %d peers timing out after %dms', this.count, this.queryTimeout)
-
-          const found = await pipe(
-            this.peerRouting.getClosestPeers(this.components.peerId.toBytes(), {
-              signal,
-              isSelfQuery: true
-            }),
-            (source) => take(source, this.count),
-            async (source) => length(source)
-          )
-
-          this.log('self-query ran successfully - found %d peers', found)
-
-          if (this.initialQuerySelfHasRun != null) {
-            this.initialQuerySelfHasRun.resolve()
-            this.initialQuerySelfHasRun = undefined
-          }
-        } catch (err: any) {
-          this.log.error('self-query error', err)
-        } finally {
-          signal.clear()
-        }
-      }).catch(err => {
-        this.log('self-query error', err)
-      }).finally(() => {
-        this.running = false
+      try {
+        this.log('run self-query, look for %d peers timing out after %dms', this.count, this.queryTimeout)
+
+        const found = await pipe(
+          this.peerRouting.getClosestPeers(this.components.peerId.toBytes(), {
+            signal,
+            isSelfQuery: true
+          }),
+          (source) => take(source, this.count),
+          async (source) => length(source)
+        )
 
-        clearTimeout(this.timeoutId)
+        this.log('self-query ran successfully - found %d peers', found)
 
-        if (this.started) {
-          this.log('running self-query again in %dms', this.interval)
-          this.timeoutId = setTimeout(this.querySelf.bind(this), this.interval)
+        if (this.initialQuerySelfHasRun != null) {
+          this.initialQuerySelfHasRun.resolve()
+          this.initialQuerySelfHasRun = undefined
         }
-      })
+      } catch (err: any) {
+        this.log.error('self-query error', err)
+      } finally {
+        signal.clear()
+      }
+    }
+
+    this.querySelfPromise.resolve()
+    this.querySelfPromise = undefined
+
+    if (!this.started) {
+      return
+    }
+
+    this.timeoutId = setTimeout(() => {
+      this.querySelf()
+        .catch(err => {
+          this.log.error('error running self-query', err)
+        })
+    }, this.interval)
   }
 }

package/src/record/index.ts

@@ -0,0 +1,70 @@
+import {
+  Record
+} from './record.js'
+import * as utils from './utils.js'
+import type { Uint8ArrayList } from 'uint8arraylist'
+
+export class Libp2pRecord {
+  public key: Uint8Array
+  public value: Uint8Array
+  public timeReceived: Date
+
+  constructor (key: Uint8Array, value: Uint8Array, timeReceived: Date) {
+    if (!(key instanceof Uint8Array)) {
+      throw new Error('key must be a Uint8Array')
+    }
+
+    if (!(value instanceof Uint8Array)) {
+      throw new Error('value must be a Uint8Array')
+    }
+
+    this.key = key
+    this.value = value
+    this.timeReceived = timeReceived
+  }
+
+  serialize (): Uint8Array {
+    return Record.encode(this.prepareSerialize())
+  }
+
+  /**
+   * Return the object format ready to be given to the protobuf library.
+   */
+  prepareSerialize (): Record {
+    return {
+      key: this.key,
+      value: this.value,
+      timeReceived: utils.toRFC3339(this.timeReceived)
+    }
+  }
+
+  /**
+   * Decode a protobuf encoded record
+   */
+  static deserialize (raw: Uint8Array | Uint8ArrayList): Libp2pRecord {
+    const rec = Record.decode(raw)
+
+    return new Libp2pRecord(rec.key, rec.value, new Date(rec.timeReceived))
+  }
+
+  /**
+   * Create a record from the raw object returned from the protobuf library
+   */
+  static fromDeserialized (obj: Record): Libp2pRecord {
+    const recvtime = utils.parseRFC3339(obj.timeReceived)
+
+    if (obj.key == null) {
+      throw new Error('key missing from deserialized object')
+    }
+
+    if (obj.value == null) {
+      throw new Error('value missing from deserialized object')
+    }
+
+    const rec = new Libp2pRecord(
+      obj.key, obj.value, recvtime
+    )
+
+    return rec
+  }
+}

package/src/record/record.proto

@@ -0,0 +1,20 @@
+syntax = "proto3";
+
+// Record represents a dht record that contains a value
+// for a key value pair
+message Record {
+  // The key that references this record
+  bytes key = 1;
+
+  // The actual value this record is storing
+  bytes value = 2;
+
+  // Note: These fields were removed from the Record message
+  // hash of the authors public key
+  // optional bytes author = 3;
+  // A PKI signature for the key+value+author
+  // optional bytes signature = 4;
+
+  // Time the record was received, set by receiver
+  string timeReceived = 5;
+}

package/src/record/record.ts

@@ -0,0 +1,87 @@
+/* eslint-disable import/export */
+/* eslint-disable complexity */
+/* eslint-disable @typescript-eslint/no-namespace */
+/* eslint-disable @typescript-eslint/no-unnecessary-boolean-literal-compare */
+/* eslint-disable @typescript-eslint/no-empty-interface */
+
+import { encodeMessage, decodeMessage, message } from 'protons-runtime'
+import type { Codec } from 'protons-runtime'
+import type { Uint8ArrayList } from 'uint8arraylist'
+
+export interface Record {
+  key: Uint8Array
+  value: Uint8Array
+  timeReceived: string
+}
+
+export namespace Record {
+  let _codec: Codec<Record>
+
+  export const codec = (): Codec<Record> => {
+    if (_codec == null) {
+      _codec = message<Record>((obj, w, opts = {}) => {
+        if (opts.lengthDelimited !== false) {
+          w.fork()
+        }
+
+        if ((obj.key != null && obj.key.byteLength > 0)) {
+          w.uint32(10)
+          w.bytes(obj.key)
+        }
+
+        if ((obj.value != null && obj.value.byteLength > 0)) {
+          w.uint32(18)
+          w.bytes(obj.value)
+        }
+
+        if ((obj.timeReceived != null && obj.timeReceived !== '')) {
+          w.uint32(42)
+          w.string(obj.timeReceived)
+        }
+
+        if (opts.lengthDelimited !== false) {
+          w.ldelim()
+        }
+      }, (reader, length) => {
+        const obj: any = {
+          key: new Uint8Array(0),
+          value: new Uint8Array(0),
+          timeReceived: ''
+        }
+
+        const end = length == null ? reader.len : reader.pos + length
+
+        while (reader.pos < end) {
+          const tag = reader.uint32()
+
+          switch (tag >>> 3) {
+            case 1:
+              obj.key = reader.bytes()
+              break
+            case 2:
+              obj.value = reader.bytes()
+              break
+            case 5:
+              obj.timeReceived = reader.string()
+              break
+            default:
+              reader.skipType(tag & 7)
+              break
+          }
+        }
+
+        return obj
+      })
+    }
+
+    return _codec
+  }
+
+  export const encode = (obj: Partial<Record>): Uint8Array => {
+    return encodeMessage(obj, Record.codec())
+  }
+
+  export const decode = (buf: Uint8Array | Uint8ArrayList): Record => {
+    return decodeMessage(buf, Record.codec())
+  }
+}

package/src/record/selectors.ts

@@ -0,0 +1,50 @@
+import { CodeError } from '@libp2p/interface/errors'
+import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
+import type { Selectors } from '../index.js'
+
+/**
+ * Select the best record out of the given records
+ */
+export function bestRecord (selectors: Selectors, k: Uint8Array, records: Uint8Array[]): number {
+  if (records.length === 0) {
+    const errMsg = 'No records given'
+
+    throw new CodeError(errMsg, 'ERR_NO_RECORDS_RECEIVED')
+  }
+
+  const kStr = uint8ArrayToString(k)
+  const parts = kStr.split('/')
+
+  if (parts.length < 3) {
+    const errMsg = 'Record key does not have a selector function'
+
+    throw new CodeError(errMsg, 'ERR_NO_SELECTOR_FUNCTION_FOR_RECORD_KEY')
+  }
+
+  const selector = selectors[parts[1].toString()]
+
+  if (selector == null) {
+    const errMsg = `Unrecognized key prefix: ${parts[1]}`
+
+    throw new CodeError(errMsg, 'ERR_UNRECOGNIZED_KEY_PREFIX')
+  }
+
+  if (records.length === 1) {
+    return 0
+  }
+
+  return selector(k, records)
+}
+
+/**
+ * Best record selector, for public key records.
+ * Simply returns the first record, as all valid public key
+ * records are equal
+ */
+function publickKey (k: Uint8Array, records: Uint8Array[]): number {
+  return 0
+}
+
+export const selectors: Selectors = {
+  pk: publickKey
+}

package/src/record/utils.ts

@@ -0,0 +1,46 @@
+/**
+ * Convert a JavaScript date into an `RFC3339Nano` formatted
+ * string
+ */
+export function toRFC3339 (time: Date): string {
+  const year = time.getUTCFullYear()
+  const month = String(time.getUTCMonth() + 1).padStart(2, '0')
+  const day = String(time.getUTCDate()).padStart(2, '0')
+  const hour = String(time.getUTCHours()).padStart(2, '0')
+  const minute = String(time.getUTCMinutes()).padStart(2, '0')
+  const seconds = String(time.getUTCSeconds()).padStart(2, '0')
+  const milliseconds = time.getUTCMilliseconds()
+  const nanoseconds = String(milliseconds * 1000 * 1000).padStart(9, '0')
+
+  return `${year}-${month}-${day}T${hour}:${minute}:${seconds}.${nanoseconds}Z`
+}
+
+/**
+ * Parses a date string formatted as `RFC3339Nano` into a
+ * JavaScript Date object
+ */
+export function parseRFC3339 (time: string): Date {
+  const rfc3339Matcher = new RegExp(
+    // 2006-01-02T
+    '(\\d{4})-(\\d{2})-(\\d{2})T' +
+    // 15:04:05
+    '(\\d{2}):(\\d{2}):(\\d{2})' +
+    // .999999999Z
+    '\\.(\\d+)Z'
+  )
+  const m = String(time).trim().match(rfc3339Matcher)
+
+  if (m == null) {
+    throw new Error('Invalid format')
+  }
+
+  const year = parseInt(m[1], 10)
+  const month = parseInt(m[2], 10) - 1
+  const date = parseInt(m[3], 10)
+  const hour = parseInt(m[4], 10)
+  const minute = parseInt(m[5], 10)
+  const second = parseInt(m[6], 10)
+  const millisecond = parseInt(m[7].slice(0, -6), 10)
+
+  return new Date(Date.UTC(year, month, date, hour, minute, second, millisecond))
+}

package/src/record/validators.ts

@@ -0,0 +1,69 @@
+import { CodeError } from '@libp2p/interface/errors'
+import { sha256 } from 'multiformats/hashes/sha2'
+import { equals as uint8ArrayEquals } from 'uint8arrays/equals'
+import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
+import type { Libp2pRecord } from './index.js'
+import type { Validators } from '../index.js'
+
+/**
+ * Checks a record and ensures it is still valid.
+ * It runs the needed validators.
+ * If verification fails the returned Promise will reject with the error.
+ */
+export async function verifyRecord (validators: Validators, record: Libp2pRecord): Promise<void> {
+  const key = record.key
+  const keyString = uint8ArrayToString(key)
+  const parts = keyString.split('/')
+
+  if (parts.length < 3) {
+    // No validator available
+    return
+  }
+
+  const validator = validators[parts[1].toString()]
+
+  if (validator == null) {
+    const errMsg = 'Invalid record keytype'
+
+    throw new CodeError(errMsg, 'ERR_INVALID_RECORD_KEY_TYPE')
+  }
+
+  await validator(key, record.value)
+}
+
+/**
+ * Validator for public key records.
+ * Verifies that the passed in record value is the PublicKey
+ * that matches the passed in key.
+ * If validation fails the returned Promise will reject with the error.
+ *
+ * @param {Uint8Array} key - A valid key is of the form `'/pk/<keymultihash>'`
+ * @param {Uint8Array} publicKey - The public key to validate against (protobuf encoded).
+ */
+const validatePublicKeyRecord = async (key: Uint8Array, publicKey: Uint8Array): Promise<void> => {
+  if (!(key instanceof Uint8Array)) {
+    throw new CodeError('"key" must be a Uint8Array', 'ERR_INVALID_RECORD_KEY_NOT_BUFFER')
+  }
+
+  if (key.byteLength < 5) {
+    throw new CodeError('invalid public key record', 'ERR_INVALID_RECORD_KEY_TOO_SHORT')
+  }
+
+  const prefix = uint8ArrayToString(key.subarray(0, 4))
+
+  if (prefix !== '/pk/') {
+    throw new CodeError('key was not prefixed with /pk/', 'ERR_INVALID_RECORD_KEY_BAD_PREFIX')
+  }
+
+  const keyhash = key.slice(4)
+
+  const publicKeyHash = await sha256.digest(publicKey)
+
+  if (!uint8ArrayEquals(keyhash, publicKeyHash.bytes)) {
+    throw new CodeError('public key does not match passed in key', 'ERR_INVALID_RECORD_HASH_MISMATCH')
+  }
+}
+
+export const validators: Validators = {
+  pk: validatePublicKeyRecord
+}

package/src/routing-table/index.ts

@@ -1,13 +1,14 @@
+import { EventEmitter } from '@libp2p/interface/events'
 import { logger } from '@libp2p/logger'
 import { PeerSet } from '@libp2p/peer-collections'
 import Queue from 'p-queue'
 import * as utils from '../utils.js'
 import { KBucket, type PingEventDetails } from './k-bucket.js'
-import type { ConnectionManager } from '@libp2p/interface-connection-manager'
-import type { Metric, Metrics } from '@libp2p/interface-metrics'
-import type { PeerId } from '@libp2p/interface-peer-id'
-import type { PeerStore } from '@libp2p/interface-peer-store'
-import type { Startable } from '@libp2p/interfaces/startable'
+import type { Metric, Metrics } from '@libp2p/interface/metrics'
+import type { PeerId } from '@libp2p/interface/peer-id'
+import type { PeerStore } from '@libp2p/interface/peer-store'
+import type { Startable } from '@libp2p/interface/startable'
+import type { ConnectionManager } from '@libp2p/interface-internal/connection-manager'
 import type { Logger } from '@libp2p/logger'
 
 export const KAD_CLOSE_TAG_NAME = 'kad-close'
@@ -33,11 +34,16 @@ export interface RoutingTableComponents {
   metrics?: Metrics
 }
 
+export interface RoutingTableEvents {
+  'peer:add': CustomEvent<PeerId>
+  'peer:remove': CustomEvent<PeerId>
+}
+
 /**
  * A wrapper around `k-bucket`, to provide easy store and
  * retrieval for peers.
  */
-export class RoutingTable implements Startable {
+export class RoutingTable extends EventEmitter<RoutingTableEvents> implements Startable {
   public kBucketSize: number
   public kb?: KBucket
   public pingQueue: Queue
@@ -58,6 +64,8 @@ export class RoutingTable implements Startable {
   }
 
   constructor (components: RoutingTableComponents, init: RoutingTableInit) {
+    super()
+
     const { kBucketSize, pingTimeout, lan, pingConcurrency, protocol, tagName, tagValue } = init
 
     this.components = components
@@ -160,11 +168,15 @@ export class RoutingTable implements Startable {
       kClosest = newClosest
     })
 
-    kBuck.addEventListener('added', () => {
+    kBuck.addEventListener('added', (evt) => {
       updatePeerTags()
+
+      this.safeDispatchEvent('peer:add', { detail: evt.detail.peer })
     })
-    kBuck.addEventListener('removed', () => {
+    kBuck.addEventListener('removed', (evt) => {
       updatePeerTags()
+
+      this.safeDispatchEvent('peer:remove', { detail: evt.detail.peer })
     })
   }
 

package/src/routing-table/k-bucket.ts

@@ -27,8 +27,8 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.
 */
 
-import { EventEmitter } from '@libp2p/interfaces/events'
-import type { PeerId } from '@libp2p/interface-peer-id'
+import { EventEmitter } from '@libp2p/interface/events'
+import type { PeerId } from '@libp2p/interface/peer-id'
 
 function arrayEquals (array1: Uint8Array, array2: Uint8Array): boolean {
   if (array1 === array2) {