@libp2p/interface 0.0.1-6fdaa7dc

package/package.json

@@ -0,0 +1,177 @@
+{
+  "name": "@libp2p/interface",
+  "version": "0.0.1-6fdaa7dc",
+  "description": "The interface implemented by a libp2p node",
+  "license": "Apache-2.0 OR MIT",
+  "homepage": "https://github.com/libp2p/js-libp2p/tree/master/packages/interface#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/libp2p/js-libp2p.git"
+  },
+  "bugs": {
+    "url": "https://github.com/libp2p/js-libp2p/issues"
+  },
+  "keywords": [
+    "interface",
+    "libp2p"
+  ],
+  "type": "module",
+  "types": "./dist/src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "*",
+        "dist/*",
+        "dist/src/*",
+        "dist/src/*/index"
+      ],
+      "src/*": [
+        "*",
+        "dist/*",
+        "dist/src/*",
+        "dist/src/*/index"
+      ]
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "!dist/test",
+    "!**/*.tsbuildinfo"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./connection": {
+      "types": "./dist/src/connection/index.d.ts",
+      "import": "./dist/src/connection/index.js"
+    },
+    "./connection-encrypter": {
+      "types": "./dist/src/connection-encrypter/index.d.ts",
+      "import": "./dist/src/connection-encrypter/index.js"
+    },
+    "./connection-gater": {
+      "types": "./dist/src/connection-gater/index.d.ts",
+      "import": "./dist/src/connection-gater/index.js"
+    },
+    "./connection/status": {
+      "types": "./dist/src/connection/status.d.ts",
+      "import": "./dist/src/connection/status.js"
+    },
+    "./content-routing": {
+      "types": "./dist/src/content-routing/index.d.ts",
+      "import": "./dist/src/content-routing/index.js"
+    },
+    "./errors": {
+      "types": "./dist/src/errors.d.ts",
+      "import": "./dist/src/errors.js"
+    },
+    "./events": {
+      "types": "./dist/src/events.d.ts",
+      "import": "./dist/src/events.js"
+    },
+    "./keychain": {
+      "types": "./dist/src/keychain/index.d.ts",
+      "import": "./dist/src/keychain/index.js"
+    },
+    "./keys": {
+      "types": "./dist/src/keys/index.d.ts",
+      "import": "./dist/src/keys/index.js"
+    },
+    "./metrics": {
+      "types": "./dist/src/metrics/index.d.ts",
+      "import": "./dist/src/metrics/index.js"
+    },
+    "./metrics/tracked-map": {
+      "types": "./dist/src/metrics/tracked-map.d.ts",
+      "import": "./dist/src/metrics/tracked-map.js"
+    },
+    "./peer-discovery": {
+      "types": "./dist/src/peer-discovery/index.d.ts",
+      "import": "./dist/src/peer-discovery/index.js"
+    },
+    "./peer-id": {
+      "types": "./dist/src/peer-id/index.d.ts",
+      "import": "./dist/src/peer-id/index.js"
+    },
+    "./peer-info": {
+      "types": "./dist/src/peer-info/index.d.ts",
+      "import": "./dist/src/peer-info/index.js"
+    },
+    "./peer-routing": {
+      "types": "./dist/src/peer-routing/index.d.ts",
+      "import": "./dist/src/peer-routing/index.js"
+    },
+    "./peer-store": {
+      "types": "./dist/src/peer-store/index.d.ts",
+      "import": "./dist/src/peer-store/index.js"
+    },
+    "./peer-store/tags": {
+      "types": "./dist/src/peer-store/tags.d.ts",
+      "import": "./dist/src/peer-store/tags.js"
+    },
+    "./record": {
+      "types": "./dist/src/record/index.d.ts",
+      "import": "./dist/src/record/index.js"
+    },
+    "./startable": {
+      "types": "./dist/src/startable.d.ts",
+      "import": "./dist/src/startable.js"
+    },
+    "./stream-handler": {
+      "types": "./dist/src/stream-handler/index.d.ts",
+      "import": "./dist/src/stream-handler/index.js"
+    },
+    "./stream-muxer": {
+      "types": "./dist/src/stream-muxer/index.d.ts",
+      "import": "./dist/src/stream-muxer/index.js"
+    },
+    "./stream-muxer/stream": {
+      "types": "./dist/src/stream-muxer/stream.d.ts",
+      "import": "./dist/src/stream-muxer/stream.js"
+    },
+    "./transport": {
+      "types": "./dist/src/transport/index.d.ts",
+      "import": "./dist/src/transport/index.js"
+    }
+  },
+  "eslintConfig": {
+    "extends": "ipfs",
+    "parserOptions": {
+      "sourceType": "module"
+    }
+  },
+  "scripts": {
+    "clean": "aegir clean",
+    "lint": "aegir lint",
+    "dep-check": "aegir dep-check",
+    "build": "aegir build",
+    "test": "aegir test",
+    "test:chrome": "aegir test -t browser --cov",
+    "test:chrome-webworker": "aegir test -t webworker",
+    "test:firefox": "aegir test -t browser -- --browser firefox",
+    "test:firefox-webworker": "aegir test -t webworker -- --browser firefox",
+    "test:node": "aegir test -t node --cov",
+    "test:electron-main": "aegir test -t electron-main"
+  },
+  "dependencies": {
+    "@multiformats/multiaddr": "^12.1.3",
+    "abortable-iterator": "^5.0.1",
+    "any-signal": "^4.1.1",
+    "it-pushable": "^3.1.3",
+    "it-stream-types": "^2.0.1",
+    "multiformats": "^12.0.1",
+    "uint8arraylist": "^2.4.3"
+  },
+  "devDependencies": {
+    "@types/sinon": "^10.0.15",
+    "aegir": "^39.0.10",
+    "sinon": "^15.1.2",
+    "sinon-ts": "^1.0.0"
+  },
+  "typedoc": {
+    "entryPoint": "./src/index.ts"
+  }
+}

package/src/connection/index.ts

@@ -0,0 +1,221 @@
+import type * as Status from './status.js'
+import type { AbortOptions } from '../index.js'
+import type { PeerId } from '../peer-id/index.js'
+import type { Multiaddr } from '@multiformats/multiaddr'
+import type { Duplex, Source } from 'it-stream-types'
+import type { Uint8ArrayList } from 'uint8arraylist'
+
+export interface ConnectionTimeline {
+  open: number
+  upgraded?: number
+  close?: number
+}
+
+/**
+ * Outbound conections are opened by the local node, inbound streams are opened by the remote
+ */
+export type Direction = 'inbound' | 'outbound'
+
+export interface ConnectionStat {
+  /**
+   * Outbound conections are opened by the local node, inbound streams are opened by the remote
+   */
+  direction: Direction
+
+  /**
+   * Lifecycle times for the connection
+   */
+  timeline: ConnectionTimeline
+
+  /**
+   * Once a multiplexer has been negotiated for this stream, it will be set on the stat object
+   */
+  multiplexer?: string
+
+  /**
+   * Once a connection encrypter has been negotiated for this stream, it will be set on the stat object
+   */
+  encryption?: string
+
+  /**
+   * The current status of the connection
+   */
+  status: keyof typeof Status
+}
+
+export interface StreamTimeline {
+  /**
+   * A timestamp of when the stream was opened
+   */
+  open: number
+
+  /**
+   * A timestamp of when the stream was closed for both reading and writing
+   */
+  close?: number
+
+  /**
+   * A timestamp of when the stream was closed for reading
+   */
+  closeRead?: number
+
+  /**
+   * A timestamp of when the stream was closed for writing
+   */
+  closeWrite?: number
+
+  /**
+   * A timestamp of when the stream was reset
+   */
+  reset?: number
+}
+
+export interface StreamStat {
+  /**
+   * Outbound streams are opened by the local node, inbound streams are opened by the remote
+   */
+  direction: Direction
+
+  /**
+   * Lifecycle times for the stream
+   */
+  timeline: StreamTimeline
+
+  /**
+   * Once a protocol has been negotiated for this stream, it will be set on the stat object
+   */
+  protocol?: string
+}
+
+/**
+ * A Stream is a data channel between two peers that
+ * can be written to and read from at both ends.
+ *
+ * It may be encrypted and multiplexed depending on the
+ * configuration of the nodes.
+ */
+export interface Stream extends Duplex<AsyncGenerator<Uint8ArrayList>, Source<Uint8ArrayList | Uint8Array>, Promise<void>> {
+  /**
+   * Closes the stream for **reading** *and* **writing**.
+   *
+   * Any buffered data in the source can still be consumed and the stream will end normally.
+   *
+   * This will cause a `CLOSE` message to be sent to the remote, *unless* the sink has already ended.
+   *
+   * The sink and the source will return normally.
+   */
+  close: () => void
+
+  /**
+   * Closes the stream for **reading**. If iterating over the source of this stream in a `for await of` loop, it will return (exit the loop) after any buffered data has been consumed.
+   *
+   * This function is called automatically by the muxer when it receives a `CLOSE` message from the remote.
+   *
+   * The source will return normally, the sink will continue to consume.
+   */
+  closeRead: () => void
+
+  /**
+   * Closes the stream for **writing**. If iterating over the source of this stream in a `for await of` loop, it will return (exit the loop) after any buffered data has been consumed.
+   *
+   * The source will return normally, the sink will continue to consume.
+   */
+  closeWrite: () => void
+
+  /**
+   * Closes the stream for **reading** *and* **writing**. This should be called when a *local error* has occurred.
+   *
+   * Note, if called without an error any buffered data in the source can still be consumed and the stream will end normally.
+   *
+   * This will cause a `RESET` message to be sent to the remote, *unless* the sink has already ended.
+   *
+   * The sink will return and the source will throw if an error is passed or return normally if not.
+   */
+  abort: (err: Error) => void
+
+  /**
+   * Closes the stream *immediately* for **reading** *and* **writing**. This should be called when a *remote error* has occurred.
+   *
+   * This function is called automatically by the muxer when it receives a `RESET` message from the remote.
+   *
+   * The sink will return and the source will throw.
+   */
+  reset: () => void
+
+  /**
+   * Unique identifier for a stream. Identifiers are not unique across muxers.
+   */
+  id: string
+
+  /**
+   * Stats about this stream
+   */
+  stat: StreamStat
+
+  /**
+   * User defined stream metadata
+   */
+  metadata: Record<string, any>
+}
+
+export interface NewStreamOptions extends AbortOptions {
+  /**
+   * If specified, and no handler has been registered with the registrar for the
+   * successfully negotiated protocol, use this as the max outbound stream limit
+   * for the protocol
+   */
+  maxOutboundStreams?: number
+}
+
+/**
+ * A Connection is a high-level representation of a connection
+ * to a remote peer that may have been secured by encryption and
+ * multiplexed, depending on the configuration of the nodes
+ * between which the connection is made.
+ */
+export interface Connection {
+  id: string
+  stat: ConnectionStat
+  remoteAddr: Multiaddr
+  remotePeer: PeerId
+  tags: string[]
+  streams: Stream[]
+
+  newStream: (multicodecs: string | string[], options?: NewStreamOptions) => Promise<Stream>
+  addStream: (stream: Stream) => void
+  removeStream: (id: string) => void
+  close: () => Promise<void>
+}
+
+export const symbol = Symbol.for('@libp2p/connection')
+
+export function isConnection (other: any): other is Connection {
+  return other != null && Boolean(other[symbol])
+}
+
+export interface ConnectionProtector {
+
+  /**
+   * Takes a given Connection and creates a private encryption stream
+   * between its two peers from the PSK the Protector instance was
+   * created with.
+   */
+  protect: (connection: MultiaddrConnection) => Promise<MultiaddrConnection>
+}
+
+export interface MultiaddrConnectionTimeline {
+  open: number
+  upgraded?: number
+  close?: number
+}
+
+/**
+ * A MultiaddrConnection is returned by transports after dialing
+ * a peer. It is a low-level primitive and is the raw connection
+ * without encryption or stream multiplexing.
+ */
+export interface MultiaddrConnection extends Duplex<AsyncGenerator<Uint8Array>, Source<Uint8Array>, Promise<void>> {
+  close: (err?: Error) => Promise<void>
+  remoteAddr: Multiaddr
+  timeline: MultiaddrConnectionTimeline
+}

package/src/connection/status.ts

@@ -0,0 +1,4 @@
+
+export const OPEN = 'OPEN'
+export const CLOSING = 'CLOSING'
+export const CLOSED = 'CLOSED'

package/src/connection-encrypter/index.ts

@@ -0,0 +1,30 @@
+import type { PeerId } from '../peer-id/index.js'
+import type { Duplex, Source } from 'it-stream-types'
+
+/**
+ * A libp2p connection encrypter module must be compliant to this interface
+ * to ensure all exchanged data between two peers is encrypted.
+ */
+export interface ConnectionEncrypter<Extension = unknown> {
+  protocol: string
+
+  /**
+   * Encrypt outgoing data to the remote party. If the remote PeerId is known,
+   * pass it for extra verification, otherwise it will be determined during
+   * the handshake.
+   */
+  secureOutbound: (localPeer: PeerId, connection: Duplex<AsyncGenerator<Uint8Array>, Source<Uint8Array>, Promise<void>>, remotePeer?: PeerId) => Promise<SecuredConnection<Extension>>
+
+  /**
+   * Decrypt incoming data. If the remote PeerId is known,
+   * pass it for extra verification, otherwise it will be determined during
+   * the handshake
+   */
+  secureInbound: (localPeer: PeerId, connection: Duplex<AsyncGenerator<Uint8Array>, Source<Uint8Array>, Promise<void>>, remotePeer?: PeerId) => Promise<SecuredConnection<Extension>>
+}
+
+export interface SecuredConnection<Extension = unknown> {
+  conn: Duplex<AsyncGenerator<Uint8Array>, Source<Uint8Array>, Promise<void>>
+  remoteExtensions?: Extension
+  remotePeer: PeerId
+}

package/src/connection-gater/index.ts

@@ -0,0 +1,128 @@
+import type { MultiaddrConnection } from '../connection/index.js'
+import type { PeerId } from '../peer-id/index.js'
+import type { Multiaddr } from '@multiformats/multiaddr'
+
+export interface ConnectionGater {
+  /**
+   * denyDialPeer tests whether we're permitted to Dial the
+   * specified peer.
+   *
+   * This is called by the dialer.connectToPeer implementation before
+   * dialling a peer.
+   *
+   * Return true to prevent dialing the passed peer.
+   */
+  denyDialPeer?: (peerId: PeerId) => Promise<boolean>
+
+  /**
+   * denyDialMultiaddr tests whether we're permitted to dial the specified
+   * multiaddr.
+   *
+   * This is called by the connection manager - if the peer id of the remote
+   * node is known it will be present in the multiaddr.
+   *
+   * Return true to prevent dialing the passed peer on the passed multiaddr.
+   */
+  denyDialMultiaddr?: (multiaddr: Multiaddr) => Promise<boolean>
+
+  /**
+   * denyInboundConnection tests whether an incipient inbound connection is allowed.
+   *
+   * This is called by the upgrader, or by the transport directly (e.g. QUIC,
+   * Bluetooth), straight after it has accepted a connection from its socket.
+   *
+   * Return true to deny the incoming passed connection.
+   */
+  denyInboundConnection?: (maConn: MultiaddrConnection) => Promise<boolean>
+
+  /**
+   * denyOutboundConnection tests whether an incipient outbound connection is allowed.
+   *
+   * This is called by the upgrader, or by the transport directly (e.g. QUIC,
+   * Bluetooth), straight after it has created a connection with its socket.
+   *
+   * Return true to deny the incoming passed connection.
+   */
+  denyOutboundConnection?: (peerId: PeerId, maConn: MultiaddrConnection) => Promise<boolean>
+
+  /**
+   * denyInboundEncryptedConnection tests whether a given connection, now encrypted,
+   * is allowed.
+   *
+   * This is called by the upgrader, after it has performed the security
+   * handshake, and before it negotiates the muxer, or by the directly by the
+   * transport, at the exact same checkpoint.
+   *
+   * Return true to deny the passed secured connection.
+   */
+  denyInboundEncryptedConnection?: (peerId: PeerId, maConn: MultiaddrConnection) => Promise<boolean>
+
+  /**
+   * denyOutboundEncryptedConnection tests whether a given connection, now encrypted,
+   * is allowed.
+   *
+   * This is called by the upgrader, after it has performed the security
+   * handshake, and before it negotiates the muxer, or by the directly by the
+   * transport, at the exact same checkpoint.
+   *
+   * Return true to deny the passed secured connection.
+   */
+  denyOutboundEncryptedConnection?: (peerId: PeerId, maConn: MultiaddrConnection) => Promise<boolean>
+
+  /**
+   * denyInboundUpgradedConnection tests whether a fully capable connection is allowed.
+   *
+   * This is called after encryption has been negotiated and the connection has been
+   * multiplexed, if a multiplexer is configured.
+   *
+   * Return true to deny the passed upgraded connection.
+   */
+  denyInboundUpgradedConnection?: (peerId: PeerId, maConn: MultiaddrConnection) => Promise<boolean>
+
+  /**
+   * denyOutboundUpgradedConnection tests whether a fully capable connection is allowed.
+   *
+   * This is called after encryption has been negotiated and the connection has been
+   * multiplexed, if a multiplexer is configured.
+   *
+   * Return true to deny the passed upgraded connection.
+   */
+  denyOutboundUpgradedConnection?: (peerId: PeerId, maConn: MultiaddrConnection) => Promise<boolean>
+
+  /**
+   * denyInboundRelayReservation tests whether a remote peer is allowed make a
+   * relay reservation on this node.
+   *
+   * Return true to deny the relay reservation.
+   */
+  denyInboundRelayReservation?: (source: PeerId) => Promise<boolean>
+
+  /**
+   * denyOutboundRelayedConnection tests whether a remote peer is allowed to open a relayed
+   * connection to the destination node.
+   *
+   * This is invoked on the relay server when a source client with a reservation instructs
+   * the server to relay a connection to a destination peer.
+   *
+   * Return true to deny the relayed connection.
+   */
+  denyOutboundRelayedConnection?: (source: PeerId, destination: PeerId) => Promise<boolean>
+
+  /**
+   * denyInboundRelayedConnection tests whether a remote peer is allowed to open a relayed
+   * connection to this node.
+   *
+   * This is invoked on the relay client when a remote relay has received an instruction to
+   * relay a connection to the client.
+   *
+   * Return true to deny the relayed connection.
+   */
+  denyInboundRelayedConnection?: (relay: PeerId, remotePeer: PeerId) => Promise<boolean>
+
+  /**
+   * Used by the address book to filter passed addresses.
+   *
+   * Return true to allow storing the passed multiaddr for the passed peer.
+   */
+  filterMultiaddrForPeer?: (peer: PeerId, multiaddr: Multiaddr) => Promise<boolean>
+}

package/src/content-routing/index.ts

@@ -0,0 +1,83 @@
+import type { AbortOptions } from '../index.js'
+import type { PeerInfo } from '../peer-info/index.js'
+import type { CID } from 'multiformats/cid'
+
+/**
+ * Any object that implements this Symbol as a property should return a
+ * ContentRouting instance as the property value, similar to how
+ * `Symbol.Iterable` can be used to return an `Iterable` from an `Iterator`.
+ *
+ * @example
+ *
+ * ```js
+ * import { contentRouting, ContentRouting } from '@libp2p/content-routing'
+ *
+ * class MyContentRouter implements ContentRouting {
+ *   get [contentRouting] () {
+ *     return this
+ *   }
+ *
+ *   // ...other methods
+ * }
+ * ```
+ */
+export const contentRouting = Symbol.for('@libp2p/content-routing')
+
+export interface ContentRouting {
+  /**
+   * The implementation of this method should ensure that network peers know the
+   * caller can provide content that corresponds to the passed CID.
+   *
+   * @example
+   *
+   * ```js
+   * // ...
+   * await contentRouting.provide(cid)
+   * ```
+   */
+  provide: (cid: CID, options?: AbortOptions) => Promise<void>
+
+  /**
+   * Find the providers of the passed CID.
+   *
+   * @example
+   *
+   * ```js
+   * // Iterate over the providers found for the given cid
+   * for await (const provider of contentRouting.findProviders(cid)) {
+   *  console.log(provider.id, provider.multiaddrs)
+   * }
+   * ```
+   */
+  findProviders: (cid: CID, options?: AbortOptions) => AsyncIterable<PeerInfo>
+
+  /**
+   * Puts a value corresponding to the passed key in a way that can later be
+   * retrieved by another network peer using the get method.
+   *
+   * @example
+   *
+   * ```js
+   * // ...
+   * const key = '/key'
+   * const value = uint8ArrayFromString('oh hello there')
+   *
+   * await contentRouting.put(key, value)
+   * ```
+   */
+  put: (key: Uint8Array, value: Uint8Array, options?: AbortOptions) => Promise<void>
+
+  /**
+   * Retrieves a value from the network corresponding to the passed key.
+   *
+   * @example
+   *
+   * ```js
+   * // ...
+   *
+   * const key = '/key'
+   * const value = await contentRouting.get(key)
+   * ```
+   */
+  get: (key: Uint8Array, options?: AbortOptions) => Promise<Uint8Array>
+}