@libp2p/utils 6.7.2 → 7.0.0-55b7e5fea

package/src/abstract-stream.ts

@@ -1,515 +1,102 @@
-import { StreamResetError, StreamStateError } from '@libp2p/interface'
-import { pushable } from 'it-pushable'
-import defer from 'p-defer'
-import { raceSignal } from 'race-signal'
-import { Uint8ArrayList } from 'uint8arraylist'
-import { closeSource } from './close-source.js'
-import type { AbortOptions, Direction, ReadStatus, Stream, StreamStatus, StreamTimeline, WriteStatus } from '@libp2p/interface'
-import type { Logger } from '@libp2p/logger'
-import type { Pushable } from 'it-pushable'
-import type { Source } from 'it-stream-types'
-import type { DeferredPromise } from 'p-defer'
+import { pEvent } from 'p-event'
+import { AbstractMessageStream } from './abstract-message-stream.js'
+import type { MessageStreamInit } from './abstract-message-stream.js'
+import type { AbortOptions, Stream } from '@libp2p/interface'
 
-const DEFAULT_SEND_CLOSE_WRITE_TIMEOUT = 5000
-
-export interface AbstractStreamInit {
+export interface AbstractStreamInit extends MessageStreamInit {
   /**
    * 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): 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 stream has been reset by the remote
-   */
-  onReset?(): void
-
-  /**
-   * Invoked when the stream has errored
+   * The protocol name for the stream, if it is known
    */
-  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
+  protocol?: string
 }
 
-function isPromise <T = unknown> (thing: any): thing is Promise<T> {
-  if (thing == null) {
-    return false
-  }
-
-  return typeof thing.then === 'function' &&
-    typeof thing.catch === 'function' &&
-    typeof thing.finally === 'function'
-}
-
-export abstract class AbstractStream implements Stream {
+export abstract class AbstractStream extends AbstractMessageStream 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
-  public readonly log: Logger
-
-  private readonly sinkController: AbortController
-  private readonly sinkEnd: DeferredPromise<void>
-  private readonly closed: DeferredPromise<void>
-  private endErr: Error | undefined
-  private readonly streamSource: Pushable<Uint8ArrayList>
-  private readonly onEnd?: (err?: Error) => void
-  private readonly onCloseRead?: () => void
-  private readonly onCloseWrite?: () => void
-  private readonly onReset?: () => void
-  private readonly onAbort?: (err: Error) => void
-  private readonly sendCloseWriteTimeout: number
-  private sendingData?: DeferredPromise<void>
+  public protocol: string
 
   constructor (init: AbstractStreamInit) {
-    this.sinkController = new AbortController()
-    this.sinkEnd = defer()
-    this.closed = defer()
-    this.log = init.log
-
-    // stream status
-    this.status = 'open'
-    this.readStatus = 'ready'
-    this.writeStatus = 'ready'
+    super(init)
 
     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 StreamStateError(`writable end state is "${this.writeStatus}" not "ready"`)
-    }
-
-    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
-        }
-      }
-
-      const abortListener = (): void => {
-        closeSource(source, this.log)
-      }
-
-      try {
-        this.sinkController.signal.addEventListener('abort', abortListener)
-
-        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)) {
-            this.sendingData = defer()
-            await res
-            this.sendingData.resolve()
-            this.sendingData = undefined
-          }
-        }
-      } finally {
-        this.sinkController.signal.removeEventListener('abort', abortListener)
-      }
-
-      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()
-    }
+    this.protocol = init.protocol ?? ''
   }
 
-  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)
-      }
-
-      this.closed.resolve()
-    } 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)
-      }
-
-      this.closed.resolve()
-    } else {
-      this.log.trace('sink ended, waiting for source to end')
-    }
-  }
-
-  // Close for both Reading and Writing
   async close (options?: AbortOptions): Promise<void> {
-    if (this.status !== 'open') {
-      return
-    }
-
-    this.log.trace('closing gracefully')
-
-    this.status = 'closing'
-
-    // wait for read and write ends to close
-    await raceSignal(Promise.all([
-      this.closeWrite(options),
-      this.closeRead(options),
-      this.closed.promise
-    ]), options?.signal)
-
-    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 with %d queued bytes', this.streamSource.readableLength)
-      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') {
-      // try to let sending outgoing data succeed
-      if (this.sendingData != null) {
-        await raceSignal(this.sendingData.promise, options.signal)
-      }
-
-      // stop reading from the source passed to `.sink`
-      this.log.trace('aborting source passed to .sink')
-      this.sinkController.abort()
-      await raceSignal(this.sinkEnd.promise, options.signal)
-    }
-
-    this.writeStatus = 'closed'
-
-    this.log.trace('closed writable end of stream')
-  }
+    this.writeStatus = 'closing'
 
-  /**
-   * 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)
+    // if we are currently sending data, wait for all the data to be written
+    // into the underlying transport
+    if (this.sendingData || this.writeBuffer.byteLength > 0) {
+      this.log('waiting for write queue to become idle before closing writable end of stream, %d unsent bytes', this.writeBuffer.byteLength)
+      await pEvent(this, 'idle', {
+        ...options,
+        rejectionEvents: [
+          'close'
+        ]
       })
     }
 
-    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
+    // now that the underlying transport has all the data, if the buffer is full
+    // wait for it to be emptied
+    if (this.writableNeedsDrain) {
+      this.log('waiting for write queue to drain before closing writable end of stream, %d unsent bytes, sending %s', this.writeBuffer.byteLength, this.sendingData)
+      await pEvent(this, 'drain', {
+        ...options,
+        rejectionEvents: [
+          'close'
+        ]
+      })
+      this.log('write queue drained, closing writable end of stream, %d unsent bytes, sending %s', this.writeBuffer.byteLength, this.sendingData)
     }
 
-    const err = new StreamResetError('stream reset')
+    await this.sendCloseWrite(options)
 
-    this.status = 'reset'
-    this.timeline.reset = Date.now()
-    this._closeSinkAndSource(err)
-    this.onReset?.()
-  }
-
-  _closeSinkAndSource (err?: Error): void {
-    this._closeSink(err)
-    this._closeSource(err)
-  }
+    this.writeStatus = 'closed'
 
-  _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.log('closed writable end gracefully')
 
-    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)
+    if (this.remoteWriteStatus === 'closed') {
+      this.onTransportClosed()
     }
   }
 
-  /**
-   * The remote closed for writing so we should expect to receive no more
-   * messages
-   */
-  remoteCloseWrite (): void {
+  async closeRead (options?: AbortOptions): Promise<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
+    // throw away any unread data
+    if (this.readBuffer.byteLength > 0) {
+      this.readBuffer.consume(this.readBuffer.byteLength)
     }
 
-    this.log.trace('stream destroyed')
+    this.readStatus = 'closing'
 
-    this._closeSinkAndSource()
-  }
+    await this.sendCloseRead(options)
 
-  /**
-   * 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)
-  }
+    this.readStatus = 'closed'
 
-  /**
-   * 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
+    this.log('closed readable end gracefully')
   }
 
   /**
-   * 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
+   * Send a message to the remote end of the stream, informing them that we will
+   * send no more data messages.
    */
-  abstract sendCloseWrite (options?: AbortOptions): void | Promise<void>
+  abstract sendCloseWrite (options?: AbortOptions): Promise<void>
 
   /**
-   * Send a message to the remote muxer, informing them no more data messages
-   * will be read by this end of the stream
+   * If supported, send a message to the remote end of the stream, informing
+   * them that we will read no more data messages.
    */
-  abstract sendCloseRead (options?: AbortOptions): void | Promise<void>
+  abstract sendCloseRead (options?: AbortOptions): Promise<void>
 }

package/src/errors.ts

@@ -27,3 +27,13 @@ export class QueueFullError extends Error {
     this.name = 'QueueFullError'
   }
 }
+
+export class UnexpectedEOFError extends Error {
+  static name = 'UnexpectedEOFError'
+  name = 'UnexpectedEOFError'
+}
+
+export class MaxEarlyStreamsError extends Error {
+  static name = 'MaxEarlyStreamsError'
+  name = 'MaxEarlyStreamsError'
+}

package/src/get-thin-waist-addresses.browser.ts

@@ -1,4 +1,5 @@
-import { multiaddr } from '@multiformats/multiaddr'
+import { getNetConfig } from './multiaddr/get-net-config.ts'
+import { netConfigToMultiaddr } from './multiaddr/utils.ts'
 import type { Multiaddr } from '@multiformats/multiaddr'
 
 /**
@@ -7,14 +8,14 @@ import type { Multiaddr } from '@multiformats/multiaddr'
  *
  * Wildcard IP4/6 addresses will be expanded into all available interfaces.
  */
-export function getThinWaistAddresses (ma?: Multiaddr, port?: number): Multiaddr[] {
+export function getThinWaistAddresses (ma?: Multiaddr, port?: number | string): Multiaddr[] {
   if (ma == null) {
     return []
   }
 
-  const options = ma.toOptions()
+  const config = getNetConfig(ma)
 
   return [
-    multiaddr(`/ip${options.family}/${options.host}/${options.transport}/${port ?? options.port}`)
+    netConfigToMultiaddr(config, port)
   ]
 }

package/src/get-thin-waist-addresses.ts

@@ -1,6 +1,7 @@
 import os from 'node:os'
-import { multiaddr } from '@multiformats/multiaddr'
 import { isLinkLocalIp } from './link-local-ip.js'
+import { getNetConfig } from './multiaddr/get-net-config.ts'
+import { netConfigToMultiaddr } from './multiaddr/utils.ts'
 import type { Multiaddr } from '@multiformats/multiaddr'
 
 const FAMILIES = { 4: 'IPv4', 6: 'IPv6' }
@@ -36,24 +37,19 @@ function getNetworkAddrs (family: 4 | 6): string[] {
  *
  * Wildcard IP4/6 addresses will be expanded into all available interfaces.
  */
-export function getThinWaistAddresses (ma?: Multiaddr, port?: number): Multiaddr[] {
+export function getThinWaistAddresses (ma?: Multiaddr, port?: number | string): Multiaddr[] {
   if (ma == null) {
     return []
   }
 
-  const options = ma.toOptions()
+  const config = getNetConfig(ma)
 
-  if (isWildcard(options.host)) {
-    const addrs = []
-
-    for (const host of getNetworkAddrs(options.family)) {
-      addrs.push(multiaddr(`/ip${options.family}/${host}/${options.transport}/${port ?? options.port}`))
-    }
-
-    return addrs
+  if ((config.type === 'ip4' || config.type === 'ip6') && isWildcard(config.host)) {
+    return getNetworkAddrs(config.type === 'ip4' ? 4 : 6)
+      .map(host => netConfigToMultiaddr(config, port, host))
   }
 
   return [
-    multiaddr(`/ip${options.family}/${options.host}/${options.transport}/${port ?? options.port}`)
+    netConfigToMultiaddr(config, port)
   ]
 }

package/src/index.ts

@@ -4,4 +4,34 @@
  * This module contains utility functions used by libp2p modules.
  */
 
-export {}
+export * from './filters/index.js'
+export * from './multiaddr/index.js'
+export * from './queue/index.js'
+export * from './abstract-message-stream.js'
+export * from './abstract-multiaddr-connection.js'
+export * from './abstract-stream-muxer.js'
+export * from './abstract-stream.js'
+export * from './adaptive-timeout.js'
+export * from './debounce.js'
+export * from './errors.js'
+export * from './get-thin-waist-addresses.js'
+export * from './global-unicast-ip.js'
+export * from './ip-port-to-multiaddr.js'
+export * from './is-async-generator.js'
+export * from './is-generator.js'
+export * from './is-promise.js'
+export * from './length-prefixed-decoder.js'
+export * from './link-local-ip.js'
+export * from './mock-muxer.js'
+export * from './mock-stream.js'
+export * from './moving-average.js'
+export * from './multiaddr-connection-pair.js'
+export * from './peer-queue.js'
+export * from './priority-queue.js'
+export * from './private-ip.js'
+export * from './rate-limiter.js'
+export * from './repeating-task.js'
+export * from './stream-pair.js'
+export * from './stream-utils.js'
+export * from './tracked-list.js'
+export * from './tracked-map.js'