@libp2p/interface 0.1.6 → 1.0.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@libp2p/interface",
-  "version": "0.1.6",
+  "version": "1.0.0",
   "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",
+  "homepage": "https://github.com/libp2p/js-libp2p/tree/main/packages/interface#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/libp2p/js-libp2p.git"
@@ -11,6 +11,10 @@
   "bugs": {
     "url": "https://github.com/libp2p/js-libp2p/issues"
   },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "keywords": [
     "interface",
     "libp2p"
@@ -39,9 +43,6 @@
     "!dist/test",
     "!**/*.tsbuildinfo"
   ],
-  "browser": {
-    "events": "./dist/src/events.browser.js"
-  },
   "exports": {
     ".": {
       "types": "./dist/src/index.d.ts",
@@ -150,33 +151,20 @@
   "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"
+    "dep-check": "aegir dep-check -i @libp2p/utils",
+    "build": "aegir build"
   },
   "dependencies": {
-    "@multiformats/multiaddr": "^12.1.5",
-    "abortable-iterator": "^5.0.1",
-    "it-pushable": "^3.2.0",
+    "@multiformats/multiaddr": "^12.1.10",
+    "it-pushable": "^3.2.1",
     "it-stream-types": "^2.0.1",
-    "multiformats": "^12.0.1",
-    "p-defer": "^4.0.0",
-    "race-signal": "^1.0.0",
+    "multiformats": "^12.1.3",
     "uint8arraylist": "^2.4.3"
   },
   "devDependencies": {
-    "@types/sinon": "^17.0.0",
-    "aegir": "^41.0.2",
-    "delay": "^6.0.0",
-    "it-all": "^3.0.3",
-    "it-drain": "^3.0.3",
-    "sinon": "^17.0.0",
-    "sinon-ts": "^2.0.0"
+    "aegir": "^41.0.2"
+  },
+  "browser": {
+    "events": "./dist/src/events.browser.js"
   }
 }

package/src/connection/index.ts

@@ -1,4 +1,4 @@
-import type { AbortOptions } from '../index.js'
+import type { AbortOptions, Logger } 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'
@@ -169,6 +169,11 @@ export interface Stream extends Duplex<AsyncGenerator<Uint8ArrayList>, Source<Ui
    * The current status of the writable end of the stream
    */
   writeStatus: WriteStatus
+
+  /**
+   * The stream logger
+   */
+  log: Logger
 }
 
 export interface NewStreamOptions extends AbortOptions {
@@ -268,12 +273,17 @@ export interface Connection {
    * Immediately close the connection, any queued data will be discarded
    */
   abort(err: Error): void
+
+  /**
+   * The connection logger
+   */
+  log: Logger
 }
 
-export const symbol = Symbol.for('@libp2p/connection')
+export const connectionSymbol = Symbol.for('@libp2p/connection')
 
 export function isConnection (other: any): other is Connection {
-  return other != null && Boolean(other[symbol])
+  return other != null && Boolean(other[connectionSymbol])
 }
 
 export interface ConnectionProtector {
@@ -308,7 +318,7 @@ export interface MultiaddrConnectionTimeline {
  * 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>> {
+export interface MultiaddrConnection extends Duplex<AsyncGenerator<Uint8Array | Uint8ArrayList>> {
   /**
    * Gracefully close the connection. All queued data will be written to the
    * underlying transport.
@@ -329,4 +339,9 @@ export interface MultiaddrConnection extends Duplex<AsyncGenerator<Uint8Array>,
    * When connection lifecycle events occurred
    */
   timeline: MultiaddrConnectionTimeline
+
+  /**
+   * The multiaddr connection logger
+   */
+  log: Logger
 }

package/src/connection-encrypter/index.ts

@@ -1,5 +1,7 @@
+import type { MultiaddrConnection } from '../connection/index.js'
 import type { PeerId } from '../peer-id/index.js'
-import type { Duplex, Source } from 'it-stream-types'
+import type { Duplex } from 'it-stream-types'
+import type { Uint8ArrayList } from 'uint8arraylist'
 
 /**
  * A libp2p connection encrypter module must be compliant to this interface
@@ -13,18 +15,18 @@ export interface ConnectionEncrypter<Extension = unknown> {
    * 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>>
+  secureOutbound <Stream extends Duplex<AsyncGenerator<Uint8Array | Uint8ArrayList>> = MultiaddrConnection> (localPeer: PeerId, connection: Stream, remotePeer?: PeerId): Promise<SecuredConnection<Stream, 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>>
+  secureInbound <Stream extends Duplex<AsyncGenerator<Uint8Array | Uint8ArrayList>> = MultiaddrConnection> (localPeer: PeerId, connection: Stream, remotePeer?: PeerId): Promise<SecuredConnection<Stream, Extension>>
 }
 
-export interface SecuredConnection<Extension = unknown> {
-  conn: Duplex<AsyncGenerator<Uint8Array>, Source<Uint8Array>, Promise<void>>
+export interface SecuredConnection<Stream = any, Extension = unknown> {
+  conn: Stream
   remoteExtensions?: Extension
   remotePeer: PeerId
 }

package/src/content-routing/index.ts

@@ -21,7 +21,7 @@ import type { CID } from 'multiformats/cid'
  * }
  * ```
  */
-export const contentRouting = Symbol.for('@libp2p/content-routing')
+export const contentRoutingSymbol = Symbol.for('@libp2p/content-routing')
 
 export interface ContentRouting {
   /**

package/src/errors.ts

@@ -18,6 +18,10 @@ export class AbortError extends Error {
   static readonly type = 'aborted'
 }
 
+/**
+ * An {@see Error } subclass that defines a `.code` property that calling code
+ * can use to detect what type of error has been thrown and act accordingly.
+ */
 export class CodeError<T extends Record<string, any> = Record<string, never>> extends Error {
   public readonly props: T
 
@@ -55,13 +59,22 @@ export class InvalidCryptoExchangeError extends Error {
   static readonly code = 'ERR_INVALID_CRYPTO_EXCHANGE'
 }
 
-export class InvalidCryptoTransmissionError extends Error {
-  public code: string
+/**
+ * A generic error code indicating that a timeout occurred
+ */
+export const ERR_TIMEOUT = 'ERR_TIMEOUT'
 
-  constructor (message = 'Invalid crypto transmission') {
-    super(message)
-    this.code = InvalidCryptoTransmissionError.code
-  }
+/**
+ * A generic error code indicating that invalid paramters were passed
+ */
+export const ERR_INVALID_PARAMETERS = 'ERR_INVALID_PARAMETERS'
 
-  static readonly code = 'ERR_INVALID_CRYPTO_TRANSMISSION'
-}
+/**
+ * A generic error code indicating that something was not found
+ */
+export const ERR_NOT_FOUND = 'ERR_NOT_FOUND'
+
+/**
+ * A generic error code indicating that the message was invalid
+ */
+export const ERR_INVALID_MESSAGE = 'ERR_INVALID_MESSAGE'

package/src/events.ts

@@ -117,9 +117,6 @@ class CustomEventPolyfill<T = any> extends Event {
 
 export const CustomEvent = globalThis.CustomEvent ?? CustomEventPolyfill
 
-// TODO: remove this in v1
-export { TypedEventEmitter as EventEmitter }
-
 // create a setMaxListeners that doesn't break browser usage
 export const setMaxListeners: typeof nodeSetMaxListeners = (n, ...eventTargets) => {
   try {

package/src/index.ts

@@ -17,7 +17,6 @@
 import type { Connection, NewStreamOptions, Stream } from './connection/index.js'
 import type { ContentRouting } from './content-routing/index.js'
 import type { TypedEventTarget } from './events.js'
-import type { KeyChain } from './keychain/index.js'
 import type { Metrics } from './metrics/index.js'
 import type { PeerId } from './peer-id/index.js'
 import type { PeerInfo } from './peer-info/index.js'
@@ -394,20 +393,6 @@ export interface Libp2p<T extends ServiceMap = ServiceMap> extends Startable, Ty
    */
   contentRouting: ContentRouting
 
-  /**
-   * The keychain contains the keys used by the current node, and can create new
-   * keys, export them, import them, etc.
-   *
-   * @example
-   *
-   * ```js
-   * const keyInfo = await libp2p.keychain.createKey('new key')
-   * console.info(keyInfo)
-   * // { id: '...', name: 'new key' }
-   * ```
-   */
-  keychain: KeyChain
-
   /**
    * The metrics subsystem allows recording values to assess the health/performance
    * of the running node.
@@ -624,6 +609,21 @@ export interface Libp2p<T extends ServiceMap = ServiceMap> extends Startable, Ty
   services: T
 }
 
+/**
+ * Metadata about the current node
+ */
+export interface NodeInfo {
+  /**
+   * The implementation name
+   */
+  name: string
+
+  /**
+   * The implementation version
+   */
+  version: string
+}
+
 /**
  * An object that contains an AbortSignal as
  * the optional `signal` property.
@@ -660,3 +660,25 @@ export interface LoggerOptions {
 export type RecursivePartial<T> = {
   [P in keyof T]?: T[P] extends Array<infer I> ? Array<RecursivePartial<I>> : T[P] extends (...args: any[]) => any ? T[P] : RecursivePartial<T[P]>
 }
+
+export * from './connection/index.js'
+export * from './connection-encrypter/index.js'
+export * from './connection-gater/index.js'
+export * from './content-routing/index.js'
+export * from './keys/index.js'
+export * from './metrics/index.js'
+export * from './peer-discovery/index.js'
+export * from './peer-id/index.js'
+export * from './peer-info/index.js'
+export * from './peer-routing/index.js'
+export * from './peer-store/index.js'
+export * from './peer-store/tags.js'
+export * from './pubsub/index.js'
+export * from './record/index.js'
+export * from './stream-handler/index.js'
+export * from './stream-muxer/index.js'
+export * from './topology/index.js'
+export * from './transport/index.js'
+export * from './errors.js'
+export * from './events.js'
+export * from './startable.js'

package/src/keys/index.ts

@@ -1,9 +1,11 @@
+import type { Uint8ArrayList } from 'uint8arraylist'
+
 export interface PublicKey {
   readonly bytes: Uint8Array
-  verify(data: Uint8Array, sig: Uint8Array): Promise<boolean>
+  verify(data: Uint8Array | Uint8ArrayList, sig: Uint8Array): boolean | Promise<boolean>
   marshal(): Uint8Array
   equals(key: PublicKey): boolean
-  hash(): Promise<Uint8Array>
+  hash(): Uint8Array | Promise<Uint8Array>
 }
 
 /**
@@ -12,10 +14,10 @@ export interface PublicKey {
 export interface PrivateKey {
   readonly public: PublicKey
   readonly bytes: Uint8Array
-  sign(data: Uint8Array): Promise<Uint8Array>
+  sign(data: Uint8Array | Uint8ArrayList): Uint8Array | Promise<Uint8Array>
   marshal(): Uint8Array
   equals(key: PrivateKey): boolean
-  hash(): Promise<Uint8Array>
+  hash(): Uint8Array | Promise<Uint8Array>
   /**
    * Gets the ID of the key.
    *

package/src/peer-discovery/index.ts

@@ -20,7 +20,7 @@ import type { PeerInfo } from '../peer-info/index.js'
  * }
  * ```
  */
-export const peerDiscovery = Symbol.for('@libp2p/peer-discovery')
+export const peerDiscoverySymbol = Symbol.for('@libp2p/peer-discovery')
 
 export interface PeerDiscoveryEvents {
   'peer': CustomEvent<PeerInfo>

package/src/peer-id/index.ts

@@ -32,8 +32,8 @@ export interface Secp256k1PeerId extends BasePeerId {
 
 export type PeerId = RSAPeerId | Ed25519PeerId | Secp256k1PeerId
 
-export const symbol = Symbol.for('@libp2p/peer-id')
+export const peerIdSymbol = Symbol.for('@libp2p/peer-id')
 
 export function isPeerId (other: any): other is PeerId {
-  return other != null && Boolean(other[symbol])
+  return other != null && Boolean(other[peerIdSymbol])
 }

package/src/peer-info/index.ts

@@ -1,8 +1,20 @@
 import type { PeerId } from '../peer-id/index.js'
 import type { Multiaddr } from '@multiformats/multiaddr'
 
+/**
+ * A `PeerInfo` is a lightweight object that represents a remote peer, it can be
+ * obtained from peer discovery mechanisms, HTTP RPC endpoints, etc.
+ *
+ * @see https://docs.libp2p.io/concepts/fundamentals/peers/#peer-info
+ */
 export interface PeerInfo {
+  /**
+   * The identifier of the remote peer
+   */
   id: PeerId
+
+  /**
+   * The multiaddrs a peer is listening on
+   */
   multiaddrs: Multiaddr[]
-  protocols: string[]
 }

package/src/peer-routing/index.ts

@@ -21,7 +21,7 @@ import type { PeerInfo } from '../peer-info/index.js'
  * }
  * ```
  */
-export const peerRouting = Symbol.for('@libp2p/peer-routing')
+export const peerRoutingSymbol = Symbol.for('@libp2p/peer-routing')
 
 export interface PeerRouting {
   /**

package/src/startable.ts

@@ -2,8 +2,6 @@
  * Implemented by components that have a lifecycle
  */
 export interface Startable {
-  isStarted(): boolean
-
   /**
    * If implemented, this method will be invoked before the start method.
    *
@@ -51,6 +49,10 @@ export function isStartable (obj: any): obj is Startable {
   return obj != null && typeof obj.start === 'function' && typeof obj.stop === 'function'
 }
 
+/**
+ * Start one or more {@link Startable}s, calling the `beforeStart` and
+ * `afterStart` lifecycle methods if defined.
+ */
 export async function start (...objs: any[]): Promise<void> {
   const startables: Startable[] = []
 
@@ -83,6 +85,10 @@ export async function start (...objs: any[]): Promise<void> {
   )
 }
 
+/**
+ * Stop one or more {@link Startable}s, calling the `beforeStop` and
+ * `afterStop` lifecycle methods if defined.
+ */
 export async function stop (...objs: any[]): Promise<void> {
   const startables: Startable[] = []
 

package/src/stream-muxer/index.ts

@@ -1,6 +1,6 @@
 import type { Direction, Stream } from '../connection/index.js'
 import type { AbortOptions } from '../index.js'
-import type { Duplex, Source } from 'it-stream-types'
+import type { Duplex } from 'it-stream-types'
 import type { Uint8ArrayList } from 'uint8arraylist'
 
 export interface StreamMuxerFactory {
@@ -18,7 +18,7 @@ export interface StreamMuxerFactory {
 /**
  * A libp2p stream muxer
  */
-export interface StreamMuxer extends Duplex<AsyncGenerator<Uint8Array>, Source<Uint8ArrayList | Uint8Array>, Promise<void>> {
+export interface StreamMuxer extends Duplex<AsyncGenerator<Uint8Array | Uint8ArrayList>> {
   /**
    * The protocol used to select this muxer during connection opening
    */