@libp2p/interface 0.0.1-6fdaa7dc

package/src/keychain/index.ts

@@ -0,0 +1,167 @@
+/**
+ * @packageDocumentation
+ *
+ * The libp2p keychain provides an API to store keys in a datastore in
+ * an encrypted format.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { createLibp2p } from 'libp2p'
+ * import { FsDatastore } from 'datastore-fs'
+ *
+ * const node = await createLibp2p({
+ *   datastore: new FsDatastore('/path/to/dir')
+ * })
+ *
+ * const info = await node.keychain.createKey('my-new-key', 'Ed25519')
+ *
+ * console.info(info) // { id: '...', name: 'my-new-key' }
+ * ```
+ */
+
+import type { KeyType } from '../keys/index.js'
+import type { PeerId } from '../peer-id/index.js'
+import type { Multibase } from 'multiformats/bases/interface'
+
+export interface KeyInfo {
+  /**
+   * The universally unique key id
+   */
+  id: string
+
+  /**
+   * The local key name
+   */
+  name: string
+}
+
+export interface KeyChain {
+  /**
+   * Export an existing key as a PEM encrypted PKCS #8 string.
+   *
+   * @example
+   *
+   * ```js
+   * await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+   * const pemKey = await libp2p.keychain.exportKey('keyTest', 'password123')
+   * ```
+   */
+  exportKey: (name: string, password: string) => Promise<Multibase<'m'>>
+
+  /**
+   * Import a new key from a PEM encoded PKCS #8 string.
+   *
+   * @example
+   *
+   * ```js
+   * await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+   * const pemKey = await libp2p.keychain.exportKey('keyTest', 'password123')
+   * const keyInfo = await libp2p.keychain.importKey('keyTestImport', pemKey, 'password123')
+   * ```
+   */
+  importKey: (name: string, pem: string, password: string) => Promise<KeyInfo>
+
+  /**
+   * Import a new key from a PeerId with a private key component
+   *
+   * @example
+   *
+   * ```js
+   * const keyInfo = await libp2p.keychain.importPeer('keyTestImport', peerIdFromString('12D3Foo...'))
+   * ```
+   */
+  importPeer: (name: string, peerId: PeerId) => Promise<KeyInfo>
+
+  /**
+   * Export an existing key as a PeerId
+   *
+   * @example
+   *
+   * ```js
+   * const peerId = await libp2p.keychain.exportPeerId('key-name')
+   * ```
+   */
+  exportPeerId: (name: string) => Promise<PeerId>
+
+  /**
+   * Create a key in the keychain.
+   *
+   * @example
+   *
+   * ```js
+   * const keyInfo = await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+   * ```
+   */
+  createKey: (name: string, type: KeyType, size?: number) => Promise<KeyInfo>
+
+  /**
+   * List all the keys.
+   *
+   * @example
+   *
+   * ```js
+   * const keyInfos = await libp2p.keychain.listKeys()
+   * ```
+   */
+  listKeys: () => Promise<KeyInfo[]>
+
+  /**
+   * Removes a key from the keychain.
+   *
+   * @example
+   *
+   * ```js
+   * await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+   * const keyInfo = await libp2p.keychain.removeKey('keyTest')
+   * ```
+   */
+  removeKey: (name: string) => Promise<KeyInfo>
+
+  /**
+   * Rename a key in the keychain.
+   *
+   * @example
+   *
+   * ```js
+   * await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+   * const keyInfo = await libp2p.keychain.renameKey('keyTest', 'keyNewNtest')
+   * ```
+   */
+  renameKey: (oldName: string, newName: string) => Promise<KeyInfo>
+
+  /**
+   * Find a key by it's id.
+   *
+   * @example
+   *
+   * ```js
+   * const keyInfo = await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+   * const keyInfo2 = await libp2p.keychain.findKeyById(keyInfo.id)
+   * ```
+   */
+  findKeyById: (id: string) => Promise<KeyInfo>
+
+  /**
+   * Find a key by it's name.
+   *
+   * @example
+   *
+   * ```js
+   * const keyInfo = await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+   * const keyInfo2 = await libp2p.keychain.findKeyByName('keyTest')
+   * ```
+   */
+  findKeyByName: (name: string) => Promise<KeyInfo>
+
+  /**
+   * Rotate keychain password and re-encrypt all associated keys
+   *
+   * @example
+   *
+   * ```js
+   * await libp2p.keychain.rotateKeychainPass('oldPassword', 'newPassword')
+   * ```
+   */
+  rotateKeychainPass: (oldPass: string, newPass: string) => Promise<void>
+}

package/src/keys/index.ts

@@ -0,0 +1,38 @@
+
+export interface PublicKey {
+  readonly bytes: Uint8Array
+  verify: (data: Uint8Array, sig: Uint8Array) => Promise<boolean>
+  marshal: () => Uint8Array
+  equals: (key: PublicKey) => boolean
+  hash: () => Promise<Uint8Array>
+}
+
+/**
+ * Generic private key interface
+ */
+export interface PrivateKey {
+  readonly public: PublicKey
+  readonly bytes: Uint8Array
+  sign: (data: Uint8Array) => Promise<Uint8Array>
+  marshal: () => Uint8Array
+  equals: (key: PrivateKey) => boolean
+  hash: () => Promise<Uint8Array>
+  /**
+   * Gets the ID of the key.
+   *
+   * The key id is the base58 encoding of the SHA-256 multihash of its public key.
+   * The public key is a protobuf encoding containing a type and the DER encoding
+   * of the PKCS SubjectPublicKeyInfo.
+   */
+  id: () => Promise<string>
+  /**
+   * Exports the password protected key in the format specified.
+   */
+  export: (password: string, format?: 'pkcs-8' | string) => Promise<string>
+}
+
+export const Ed25519 = 'Ed25519'
+export const RSA = 'RSA'
+export const secp256k1 = 'secp256k1'
+
+export type KeyType = typeof Ed25519 | typeof RSA | typeof secp256k1

package/src/metrics/index.ts

@@ -0,0 +1,187 @@
+import type { MultiaddrConnection, Stream, Connection } from '../connection/index.js'
+
+/**
+ * Create tracked metrics with these options. Loosely based on the
+ * interfaces exposed by the prom-client module
+ */
+export interface MetricOptions {
+  /**
+   * Optional label for the metric
+   */
+  label?: string
+
+  /**
+   * Optional help for the metric
+   */
+  help?: string
+}
+
+/**
+ * A function that returns a tracked metric which may be expensive
+ * to calculate so it is only invoked when metrics are being scraped
+ */
+export type CalculateMetric<T = number> = (() => T) | (() => Promise<T>)
+
+/**
+ * Create tracked metrics that are expensive to calculate by passing
+ * a function that is only invoked when metrics are being scraped
+ */
+export interface CalculatedMetricOptions<T = number> extends MetricOptions {
+  /**
+   * An optional function invoked to calculate the component metric instead of
+   * using `.update`, `.increment`, and `.decrement`
+   */
+  calculate: CalculateMetric<T>
+}
+
+/**
+ * Call this function to stop the timer returned from the `.timer` method
+ * on the metric
+ */
+export interface StopTimer { (): void }
+
+/**
+ * A tracked metric loosely based on the interfaces exposed by the
+ * prom-client module
+ */
+export interface Metric {
+  /**
+   * Update the stored metric to the passed value
+   */
+  update: (value: number) => void
+
+  /**
+   * Increment the metric by the passed value or 1
+   */
+  increment: (value?: number) => void
+
+  /**
+   * Decrement the metric by the passed value or 1
+   */
+  decrement: (value?: number) => void
+
+  /**
+   * Reset this metric to its default value
+   */
+  reset: () => void
+
+  /**
+   * Start a timed metric, call the returned function to
+   * stop the timer
+   */
+  timer: () => StopTimer
+}
+
+/**
+ * A group of related metrics loosely based on the interfaces exposed by the
+ * prom-client module
+ */
+export interface MetricGroup {
+  /**
+   * Update the stored metric group to the passed value
+   */
+  update: (values: Record<string, number>) => void
+
+  /**
+   * Increment the metric group keys by the passed number or
+   * any non-numeric value to increment by 1
+   */
+  increment: (values: Record<string, number | unknown>) => void
+
+  /**
+   * Decrement the metric group keys by the passed number or
+   * any non-numeric value to decrement by 1
+   */
+  decrement: (values: Record<string, number | unknown>) => void
+
+  /**
+   * Reset the passed key in this metric group to its default value
+   * or all keys if no key is passed
+   */
+  reset: () => void
+
+  /**
+   * Start a timed metric for the named key in the group, call
+   * the returned function to stop the timer
+   */
+  timer: (key: string) => StopTimer
+}
+
+/**
+ * A tracked counter loosely based on the Counter interface exposed
+ * by the prom-client module - counters are metrics that only go up
+ */
+export interface Counter {
+  /**
+   * Increment the metric by the passed value or 1
+   */
+  increment: (value?: number) => void
+
+  /**
+   * Reset this metric to its default value
+   */
+  reset: () => void
+}
+
+/**
+ * A group of tracked counters loosely based on the Counter interface
+ * exposed by the prom-client module - counters are metrics that only
+ * go up
+ */
+export interface CounterGroup {
+  /**
+   * Increment the metric group keys by the passed number or
+   * any non-numeric value to increment by 1
+   */
+  increment: (values: Record<string, number | unknown>) => void
+
+  /**
+   * Reset the passed key in this metric group to its default value
+   * or all keys if no key is passed
+   */
+  reset: () => void
+}
+
+/**
+ * The libp2p metrics tracking object. This interface is only concerned
+ * with the collection of metrics, please see the individual implementations
+ * for how to extract metrics for viewing.
+ */
+export interface Metrics {
+  /**
+   * Track a newly opened multiaddr connection
+   */
+  trackMultiaddrConnection: (maConn: MultiaddrConnection) => void
+
+  /**
+   * Track a newly opened protocol stream
+   */
+  trackProtocolStream: (stream: Stream, connection: Connection) => void
+
+  /**
+   * Register an arbitrary metric. Call this to set help/labels for metrics
+   * and update/increment/decrement/etc them by calling methods on the returned
+   * metric object
+   */
+  registerMetric: ((name: string, options?: MetricOptions) => Metric) & ((name: string, options: CalculatedMetricOptions) => void)
+
+  /**
+   * Register a a group of related metrics. Call this to set help/labels for
+   * groups of related metrics that will be updated with by calling `.update`,
+   * `.increment` and/or `.decrement` methods on the returned metric group object
+   */
+  registerMetricGroup: ((name: string, options?: MetricOptions) => MetricGroup) & ((name: string, options: CalculatedMetricOptions<Record<string, number>>) => void)
+
+  /**
+   * Register an arbitrary counter. Call this to set help/labels for counters
+   * and increment them by calling methods on the returned counter object
+   */
+  registerCounter: ((name: string, options?: MetricOptions) => Counter) & ((name: string, options: CalculatedMetricOptions) => void)
+
+  /**
+   * Register a a group of related counters. Call this to set help/labels for
+   * groups of related counters that will be updated with by calling the `.increment`
+   * method on the returned counter group object
+   */
+  registerCounterGroup: ((name: string, options?: MetricOptions) => CounterGroup) & ((name: string, options: CalculatedMetricOptions<Record<string, number>>) => void)
+}

package/src/metrics/tracked-map.ts

@@ -0,0 +1,65 @@
+import type { Metric, Metrics } from './index.js'
+
+export interface TrackedMapInit {
+  name: string
+  metrics: Metrics
+}
+
+class TrackedMap<K, V> extends Map<K, V> {
+  private readonly metric: Metric
+
+  constructor (init: TrackedMapInit) {
+    super()
+
+    const { name, metrics } = init
+
+    this.metric = metrics.registerMetric(name)
+    this.updateComponentMetric()
+  }
+
+  set (key: K, value: V): this {
+    super.set(key, value)
+    this.updateComponentMetric()
+    return this
+  }
+
+  delete (key: K): boolean {
+    const deleted = super.delete(key)
+    this.updateComponentMetric()
+    return deleted
+  }
+
+  clear (): void {
+    super.clear()
+    this.updateComponentMetric()
+  }
+
+  private updateComponentMetric (): void {
+    this.metric.update(this.size)
+  }
+}
+
+export interface CreateTrackedMapInit {
+  /**
+   * The metric name to use
+   */
+  name: string
+
+  /**
+   * A metrics implementation
+   */
+  metrics?: Metrics
+}
+
+export function trackedMap <K, V> (config: CreateTrackedMapInit): Map<K, V> {
+  const { name, metrics } = config
+  let map: Map<K, V>
+
+  if (metrics != null) {
+    map = new TrackedMap<K, V>({ name, metrics })
+  } else {
+    map = new Map<K, V>()
+  }
+
+  return map
+}

package/src/peer-discovery/index.ts

@@ -0,0 +1,29 @@
+import type { EventEmitter } from '../events.js'
+import type { PeerInfo } from '../peer-info/index.js'
+
+/**
+ * Any object that implements this Symbol as a property should return a
+ * PeerDiscovery instance as the property value, similar to how
+ * `Symbol.Iterable` can be used to return an `Iterable` from an `Iterator`.
+ *
+ * @example
+ *
+ * ```js
+ * import { peerDiscovery, PeerDiscovery } from '@libp2p/peer-discovery'
+ *
+ * class MyPeerDiscoverer implements PeerDiscovery {
+ *   get [peerDiscovery] () {
+ *     return this
+ *   }
+ *
+ *   // ...other methods
+ * }
+ * ```
+ */
+export const peerDiscovery = Symbol.for('@libp2p/peer-discovery')
+
+export interface PeerDiscoveryEvents {
+  'peer': CustomEvent<PeerInfo>
+}
+
+export interface PeerDiscovery extends EventEmitter<PeerDiscoveryEvents> {}

package/src/peer-id/index.ts

@@ -0,0 +1,39 @@
+import type { CID } from 'multiformats/cid'
+import type { MultihashDigest } from 'multiformats/hashes/interface'
+
+export type PeerIdType = 'RSA' | 'Ed25519' | 'secp256k1'
+
+interface BasePeerId {
+  readonly type: PeerIdType
+  readonly multihash: MultihashDigest
+  readonly privateKey?: Uint8Array
+  readonly publicKey?: Uint8Array
+
+  toString: () => string
+  toCID: () => CID
+  toBytes: () => Uint8Array
+  equals: (other: PeerId | Uint8Array | string) => boolean
+}
+
+export interface RSAPeerId extends BasePeerId {
+  readonly type: 'RSA'
+  readonly publicKey?: Uint8Array
+}
+
+export interface Ed25519PeerId extends BasePeerId {
+  readonly type: 'Ed25519'
+  readonly publicKey: Uint8Array
+}
+
+export interface Secp256k1PeerId extends BasePeerId {
+  readonly type: 'secp256k1'
+  readonly publicKey: Uint8Array
+}
+
+export type PeerId = RSAPeerId | Ed25519PeerId | Secp256k1PeerId
+
+export const symbol = Symbol.for('@libp2p/peer-id')
+
+export function isPeerId (other: any): other is PeerId {
+  return other != null && Boolean(other[symbol])
+}

package/src/peer-info/index.ts

@@ -0,0 +1,8 @@
+import type { PeerId } from '../peer-id/index.js'
+import type { Multiaddr } from '@multiformats/multiaddr'
+
+export interface PeerInfo {
+  id: PeerId
+  multiaddrs: Multiaddr[]
+  protocols: string[]
+}

package/src/peer-routing/index.ts

@@ -0,0 +1,53 @@
+import type { AbortOptions } from '../index.js'
+import type { PeerId } from '../peer-id/index.js'
+import type { PeerInfo } from '../peer-info/index.js'
+
+/**
+ * Any object that implements this Symbol as a property should return a
+ * PeerRouting instance as the property value, similar to how
+ * `Symbol.Iterable` can be used to return an `Iterable` from an `Iterator`.
+ *
+ * @example
+ *
+ * ```js
+ * import { peerRouting, PeerRouting } from '@libp2p/peer-routing'
+ *
+ * class MyPeerRouter implements PeerRouting {
+ *   get [peerRouting] () {
+ *     return this
+ *   }
+ *
+ *   // ...other methods
+ * }
+ * ```
+ */
+export const peerRouting = Symbol.for('@libp2p/peer-routing')
+
+export interface PeerRouting {
+  /**
+   * Searches the network for peer info corresponding to the passed peer id.
+   *
+   * @example
+   *
+   * ```js
+   * // ...
+   * const peer = await peerRouting.findPeer(peerId, options)
+   * ```
+   */
+  findPeer: (peerId: PeerId, options?: AbortOptions) => Promise<PeerInfo>
+
+  /**
+   * Search the network for peers that are closer to the passed key. Peer
+   * info should be yielded in ever-increasing closeness to the key.
+   *
+   * @example
+   *
+   * ```js
+   * // Iterate over the closest peers found for the given key
+   * for await (const peer of peerRouting.getClosestPeers(key)) {
+   *   console.log(peer.id, peer.multiaddrs)
+   * }
+   * ```
+   */
+  getClosestPeers: (key: Uint8Array, options?: AbortOptions) => AsyncIterable<PeerInfo>
+}