@libp2p/interface 0.1.6 → 1.0.0

package/src/stream-muxer/stream.ts

@@ -1,496 +1,11 @@
-import { abortableSource } from 'abortable-iterator'
-import { type Pushable, pushable } from 'it-pushable'
-import defer, { type DeferredPromise } from 'p-defer'
-import { raceSignal } from 'race-signal'
-import { Uint8ArrayList } from 'uint8arraylist'
-import { CodeError } from '../errors.js'
-import type { Direction, ReadStatus, Stream, StreamStatus, StreamTimeline, WriteStatus } from '../connection/index.js'
-import type { AbortOptions } from '../index.js'
-import type { Source } from 'it-stream-types'
+// TODO: remove this file and the dep-check override in package.json for
+// @libp2p/utils when yamux is updated.
+// This is a hack to defeat TypeScript trying to inspect the types for
+// @libp2p/utils/abstract-stream which depends on this module - making the
+// import path only resolvable at runtime breaks the transpile time circular
+// dependency
+const s = await import('@libp2p/utils' + '/abstract-stream')
 
-// copied from @libp2p/logger to break a circular dependency
-interface Logger {
-  (formatter: any, ...args: any[]): void
-  error(formatter: any, ...args: any[]): void
-  trace(formatter: any, ...args: any[]): void
-  enabled: boolean
-}
+export type AbstractStreamInit = any
 
-const ERR_STREAM_RESET = 'ERR_STREAM_RESET'
-const ERR_SINK_INVALID_STATE = 'ERR_SINK_INVALID_STATE'
-const DEFAULT_SEND_CLOSE_WRITE_TIMEOUT = 5000
-
-export interface AbstractStreamInit {
-  /**
-   * A unique identifier for this stream
-   */
-  id: string
-
-  /**
-   * The stream direction
-   */
-  direction: Direction
-
-  /**
-   * A Logger implementation used to log stream-specific information
-   */
-  log: Logger
-
-  /**
-   * User specific stream metadata
-   */
-  metadata?: Record<string, unknown>
-
-  /**
-   * Invoked when the stream ends
-   */
-  onEnd?(err?: Error | undefined): void
-
-  /**
-   * Invoked when the readable end of the stream is closed
-   */
-  onCloseRead?(): void
-
-  /**
-   * Invoked when the writable end of the stream is closed
-   */
-  onCloseWrite?(): void
-
-  /**
-   * Invoked when the the stream has been reset by the remote
-   */
-  onReset?(): void
-
-  /**
-   * Invoked when the the stream has errored
-   */
-  onAbort?(err: Error): void
-
-  /**
-   * How long to wait in ms for stream data to be written to the underlying
-   * connection when closing the writable end of the stream. (default: 500)
-   */
-  closeTimeout?: number
-
-  /**
-   * After the stream sink has closed, a limit on how long it takes to send
-   * a close-write message to the remote peer.
-   */
-  sendCloseWriteTimeout?: number
-}
-
-function isPromise (res?: any): res is Promise<void> {
-  return res != null && typeof res.then === 'function'
-}
-
-export abstract class AbstractStream implements Stream {
-  public id: string
-  public direction: Direction
-  public timeline: StreamTimeline
-  public protocol?: string
-  public metadata: Record<string, unknown>
-  public source: AsyncGenerator<Uint8ArrayList, void, unknown>
-  public status: StreamStatus
-  public readStatus: ReadStatus
-  public writeStatus: WriteStatus
-
-  private readonly sinkController: AbortController
-  private readonly sinkEnd: DeferredPromise<void>
-  private endErr: Error | undefined
-  private readonly streamSource: Pushable<Uint8ArrayList>
-  private readonly onEnd?: (err?: Error | undefined) => void
-  private readonly onCloseRead?: () => void
-  private readonly onCloseWrite?: () => void
-  private readonly onReset?: () => void
-  private readonly onAbort?: (err: Error) => void
-  private readonly sendCloseWriteTimeout: number
-
-  protected readonly log: Logger
-
-  constructor (init: AbstractStreamInit) {
-    this.sinkController = new AbortController()
-    this.sinkEnd = defer()
-    this.log = init.log
-
-    // stream status
-    this.status = 'open'
-    this.readStatus = 'ready'
-    this.writeStatus = 'ready'
-
-    this.id = init.id
-    this.metadata = init.metadata ?? {}
-    this.direction = init.direction
-    this.timeline = {
-      open: Date.now()
-    }
-    this.sendCloseWriteTimeout = init.sendCloseWriteTimeout ?? DEFAULT_SEND_CLOSE_WRITE_TIMEOUT
-
-    this.onEnd = init.onEnd
-    this.onCloseRead = init?.onCloseRead
-    this.onCloseWrite = init?.onCloseWrite
-    this.onReset = init?.onReset
-    this.onAbort = init?.onAbort
-
-    this.source = this.streamSource = pushable<Uint8ArrayList>({
-      onEnd: (err) => {
-        if (err != null) {
-          this.log.trace('source ended with error', err)
-        } else {
-          this.log.trace('source ended')
-        }
-
-        this.onSourceEnd(err)
-      }
-    })
-
-    // necessary because the libp2p upgrader wraps the sink function
-    this.sink = this.sink.bind(this)
-  }
-
-  async sink (source: Source<Uint8ArrayList | Uint8Array>): Promise<void> {
-    if (this.writeStatus !== 'ready') {
-      throw new CodeError(`writable end state is "${this.writeStatus}" not "ready"`, ERR_SINK_INVALID_STATE)
-    }
-
-    try {
-      this.writeStatus = 'writing'
-
-      const options: AbortOptions = {
-        signal: this.sinkController.signal
-      }
-
-      if (this.direction === 'outbound') { // If initiator, open a new stream
-        const res = this.sendNewStream(options)
-
-        if (isPromise(res)) {
-          await res
-        }
-      }
-
-      source = abortableSource(source, this.sinkController.signal, {
-        returnOnAbort: true
-      })
-
-      this.log.trace('sink reading from source')
-
-      for await (let data of source) {
-        data = data instanceof Uint8Array ? new Uint8ArrayList(data) : data
-
-        const res = this.sendData(data, options)
-
-        if (isPromise(res)) { // eslint-disable-line max-depth
-          await res
-        }
-      }
-
-      this.log.trace('sink finished reading from source, write status is "%s"', this.writeStatus)
-
-      if (this.writeStatus === 'writing') {
-        this.writeStatus = 'closing'
-
-        this.log.trace('send close write to remote')
-        await this.sendCloseWrite({
-          signal: AbortSignal.timeout(this.sendCloseWriteTimeout)
-        })
-
-        this.writeStatus = 'closed'
-      }
-
-      this.onSinkEnd()
-    } catch (err: any) {
-      this.log.trace('sink ended with error, calling abort with error', err)
-      this.abort(err)
-
-      throw err
-    } finally {
-      this.log.trace('resolve sink end')
-      this.sinkEnd.resolve()
-    }
-  }
-
-  protected onSourceEnd (err?: Error): void {
-    if (this.timeline.closeRead != null) {
-      return
-    }
-
-    this.timeline.closeRead = Date.now()
-    this.readStatus = 'closed'
-
-    if (err != null && this.endErr == null) {
-      this.endErr = err
-    }
-
-    this.onCloseRead?.()
-
-    if (this.timeline.closeWrite != null) {
-      this.log.trace('source and sink ended')
-      this.timeline.close = Date.now()
-
-      if (this.status !== 'aborted' && this.status !== 'reset') {
-        this.status = 'closed'
-      }
-
-      if (this.onEnd != null) {
-        this.onEnd(this.endErr)
-      }
-    } else {
-      this.log.trace('source ended, waiting for sink to end')
-    }
-  }
-
-  protected onSinkEnd (err?: Error): void {
-    if (this.timeline.closeWrite != null) {
-      return
-    }
-
-    this.timeline.closeWrite = Date.now()
-    this.writeStatus = 'closed'
-
-    if (err != null && this.endErr == null) {
-      this.endErr = err
-    }
-
-    this.onCloseWrite?.()
-
-    if (this.timeline.closeRead != null) {
-      this.log.trace('sink and source ended')
-      this.timeline.close = Date.now()
-
-      if (this.status !== 'aborted' && this.status !== 'reset') {
-        this.status = 'closed'
-      }
-
-      if (this.onEnd != null) {
-        this.onEnd(this.endErr)
-      }
-    } else {
-      this.log.trace('sink ended, waiting for source to end')
-    }
-  }
-
-  // Close for both Reading and Writing
-  async close (options?: AbortOptions): Promise<void> {
-    this.log.trace('closing gracefully')
-
-    this.status = 'closing'
-
-    await Promise.all([
-      this.closeRead(options),
-      this.closeWrite(options)
-    ])
-
-    this.status = 'closed'
-
-    this.log.trace('closed gracefully')
-  }
-
-  async closeRead (options: AbortOptions = {}): Promise<void> {
-    if (this.readStatus === 'closing' || this.readStatus === 'closed') {
-      return
-    }
-
-    this.log.trace('closing readable end of stream with starting read status "%s"', this.readStatus)
-
-    const readStatus = this.readStatus
-    this.readStatus = 'closing'
-
-    if (this.status !== 'reset' && this.status !== 'aborted' && this.timeline.closeRead == null) {
-      this.log.trace('send close read to remote')
-      await this.sendCloseRead(options)
-    }
-
-    if (readStatus === 'ready') {
-      this.log.trace('ending internal source queue')
-      this.streamSource.end()
-    }
-
-    this.log.trace('closed readable end of stream')
-  }
-
-  async closeWrite (options: AbortOptions = {}): Promise<void> {
-    if (this.writeStatus === 'closing' || this.writeStatus === 'closed') {
-      return
-    }
-
-    this.log.trace('closing writable end of stream with starting write status "%s"', this.writeStatus)
-
-    if (this.writeStatus === 'ready') {
-      this.log.trace('sink was never sunk, sink an empty array')
-
-      await raceSignal(this.sink([]), options.signal)
-    }
-
-    if (this.writeStatus === 'writing') {
-      // stop reading from the source passed to `.sink` in the microtask queue
-      // - this lets any data queued by the user in the current tick get read
-      // before we exit
-      await new Promise((resolve, reject) => {
-        queueMicrotask(() => {
-          this.log.trace('aborting source passed to .sink')
-          this.sinkController.abort()
-          raceSignal(this.sinkEnd.promise, options.signal)
-            .then(resolve, reject)
-        })
-      })
-    }
-
-    this.writeStatus = 'closed'
-
-    this.log.trace('closed writable end of stream')
-  }
-
-  /**
-   * Close immediately for reading and writing and send a reset message (local
-   * error)
-   */
-  abort (err: Error): void {
-    if (this.status === 'closed' || this.status === 'aborted' || this.status === 'reset') {
-      return
-    }
-
-    this.log('abort with error', err)
-
-    // try to send a reset message
-    this.log('try to send reset to remote')
-    const res = this.sendReset()
-
-    if (isPromise(res)) {
-      res.catch((err) => {
-        this.log.error('error sending reset message', err)
-      })
-    }
-
-    this.status = 'aborted'
-    this.timeline.abort = Date.now()
-    this._closeSinkAndSource(err)
-    this.onAbort?.(err)
-  }
-
-  /**
-   * Receive a reset message - close immediately for reading and writing (remote
-   * error)
-   */
-  reset (): void {
-    if (this.status === 'closed' || this.status === 'aborted' || this.status === 'reset') {
-      return
-    }
-
-    const err = new CodeError('stream reset', ERR_STREAM_RESET)
-
-    this.status = 'reset'
-    this.timeline.reset = Date.now()
-    this._closeSinkAndSource(err)
-    this.onReset?.()
-  }
-
-  _closeSinkAndSource (err?: Error): void {
-    this._closeSink(err)
-    this._closeSource(err)
-  }
-
-  _closeSink (err?: Error): void {
-    // if the sink function is running, cause it to end
-    if (this.writeStatus === 'writing') {
-      this.log.trace('end sink source')
-      this.sinkController.abort()
-    }
-
-    this.onSinkEnd(err)
-  }
-
-  _closeSource (err?: Error): void {
-    // if the source is not ending, end it
-    if (this.readStatus !== 'closing' && this.readStatus !== 'closed') {
-      this.log.trace('ending source with %d bytes to be read by consumer', this.streamSource.readableLength)
-      this.readStatus = 'closing'
-      this.streamSource.end(err)
-    }
-  }
-
-  /**
-   * The remote closed for writing so we should expect to receive no more
-   * messages
-   */
-  remoteCloseWrite (): void {
-    if (this.readStatus === 'closing' || this.readStatus === 'closed') {
-      this.log('received remote close write but local source is already closed')
-      return
-    }
-
-    this.log.trace('remote close write')
-    this._closeSource()
-  }
-
-  /**
-   * The remote closed for reading so we should not send any more
-   * messages
-   */
-  remoteCloseRead (): void {
-    if (this.writeStatus === 'closing' || this.writeStatus === 'closed') {
-      this.log('received remote close read but local sink is already closed')
-      return
-    }
-
-    this.log.trace('remote close read')
-    this._closeSink()
-  }
-
-  /**
-   * The underlying muxer has closed, no more messages can be sent or will
-   * be received, close immediately to free up resources
-   */
-  destroy (): void {
-    if (this.status === 'closed' || this.status === 'aborted' || this.status === 'reset') {
-      this.log('received destroy but we are already closed')
-      return
-    }
-
-    this.log.trace('stream destroyed')
-
-    this._closeSinkAndSource()
-  }
-
-  /**
-   * When an extending class reads data from it's implementation-specific source,
-   * call this method to allow the stream consumer to read the data.
-   */
-  sourcePush (data: Uint8ArrayList): void {
-    this.streamSource.push(data)
-  }
-
-  /**
-   * Returns the amount of unread data - can be used to prevent large amounts of
-   * data building up when the stream consumer is too slow.
-   */
-  sourceReadableLength (): number {
-    return this.streamSource.readableLength
-  }
-
-  /**
-   * Send a message to the remote muxer informing them a new stream is being
-   * opened
-   */
-  abstract sendNewStream (options?: AbortOptions): void | Promise<void>
-
-  /**
-   * Send a data message to the remote muxer
-   */
-  abstract sendData (buf: Uint8ArrayList, options?: AbortOptions): void | Promise<void>
-
-  /**
-   * Send a reset message to the remote muxer
-   */
-  abstract sendReset (options?: AbortOptions): void | Promise<void>
-
-  /**
-   * Send a message to the remote muxer, informing them no more data messages
-   * will be sent by this end of the stream
-   */
-  abstract sendCloseWrite (options?: AbortOptions): void | Promise<void>
-
-  /**
-   * Send a message to the remote muxer, informing them no more data messages
-   * will be read by this end of the stream
-   */
-  abstract sendCloseRead (options?: AbortOptions): void | Promise<void>
-}
+export const AbstractStream = s.AbstractStream

package/src/topology/index.ts

@@ -2,9 +2,6 @@ import type { Connection } from '../connection/index.js'
 import type { PeerId } from '../peer-id/index.js'
 
 export interface Topology {
-  min?: number
-  max?: number
-
   /**
    * If true, invoke `onConnect` for this topology on transient (e.g. short-lived
    * and/or data-limited) connections. (default: false)

package/src/transport/index.ts

@@ -28,7 +28,7 @@ export interface Listener extends TypedEventTarget<ListenerEvents> {
   close(): Promise<void>
 }
 
-export const symbol = Symbol.for('@libp2p/transport')
+export const transportSymbol = Symbol.for('@libp2p/transport')
 
 export interface ConnectionHandler { (connection: Connection): void }
 
@@ -55,7 +55,7 @@ export interface Transport {
   /**
    * Used by the isTransport function
    */
-  [symbol]: true
+  [transportSymbol]: true
 
   /**
    * Dial a given multiaddr.
@@ -74,7 +74,7 @@ export interface Transport {
 }
 
 export function isTransport (other: any): other is Transport {
-  return other != null && Boolean(other[symbol])
+  return other != null && Boolean(other[transportSymbol])
 }
 
 /**

package/dist/src/keychain/index.d.ts

@@ -1,154 +0,0 @@
-/**
- * @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>;
-}
-//# sourceMappingURL=index.d.ts.map

package/dist/src/keychain/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/keychain/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AAE7D,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,EAAE,EAAE,MAAM,CAAA;IAEV;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,QAAQ;IACvB;;;;;;;;;OASG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAA;IAElE;;;;;;;;;;OAUG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAExE;;;;;;;;OAQG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE1D;;;;;;;;OAQG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE3C;;;;;;;;OAQG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEvE;;;;;;;;OAQG;IACH,QAAQ,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;IAE9B;;;;;;;;;OASG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEzC;;;;;;;;;OASG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE7D;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEzC;;;;;;;;;OASG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE7C;;;;;;;;OAQG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpE"}