@libp2p/interface 2.11.0 → 3.0.0-049bfa0fa

package/src/message-stream.ts

@@ -0,0 +1,183 @@
+import type { Logger, StreamCloseEvent, StreamMessageEvent, TypedEventTarget, AbortOptions } from './index.js'
+import type { Uint8ArrayList } from 'uint8arraylist'
+
+/**
+ * The direction of the message stream
+ */
+export type MessageStreamDirection = 'inbound' | 'outbound'
+
+/**
+ * The states a message stream can be in
+ */
+export type MessageStreamStatus = 'open' | 'closing' | 'closed' | 'aborted' | 'reset'
+
+/**
+ * The states the readable end of a message stream can be in
+ */
+export type MessageStreamReadStatus = 'readable' | 'paused' | 'closing' | 'closed'
+
+/**
+ * The states the writable end of a message stream can be in
+ */
+export type MessageStreamWriteStatus = 'writable' | 'closing' | 'closed'
+
+/**
+ * An object that records the times of various events
+ */
+export interface MessageStreamTimeline {
+  /**
+   * A timestamp of when the message stream was opened
+   */
+  open: number
+
+  /**
+   * A timestamp of when the message stream was closed for both reading and
+   * writing by both ends of the stream
+   */
+  close?: number
+}
+
+export interface MessageStreamEvents {
+  /**
+   * Data was received from the remote end of the message stream
+   */
+  message: StreamMessageEvent
+
+  /**
+   * The local send buffer has emptied and the stream may be written to once
+   * more, unless it is currently closing.
+   */
+  drain: Event
+
+  /**
+   * The underlying resource is closed - no further events will be emitted and
+   * the stream cannot be used to send or receive any more data.
+   *
+   * When the `.error` field is set, the `local` property of the event will be
+   * `true` value if the `.abort` was invoked, otherwise it means a remote error
+   * occurred and the peer sent a reset signal.
+   */
+  close: StreamCloseEvent
+
+  /**
+   * Where the stream implementation supports half-closing, it may emit this
+   * event when the remote end of the stream closes it's writable end.
+   *
+   * After this event is received no further 'message' events will be emitted
+   * though the stream can still be written to, if it has not been closed at
+   * this end.
+   */
+  remoteCloseWrite: Event
+
+  /**
+   * The outgoing write queue emptied - there are no more bytes queued for
+   * sending to the remote end of the stream.
+   */
+  idle: Event
+}
+
+export interface MessageStream<Timeline extends MessageStreamTimeline = MessageStreamTimeline> extends TypedEventTarget<MessageStreamEvents>, AsyncIterable<Uint8Array | Uint8ArrayList> {
+  /**
+   * The current status of the message stream
+   */
+  status: MessageStreamStatus
+
+  /**
+   * Timestamps of when stream events occurred
+   */
+  timeline: Timeline
+
+  /**
+   * A logging implementation that can be used to log stream-specific messages
+   */
+  log: Logger
+
+  /**
+   * Whether this stream is inbound or outbound
+   */
+  direction: MessageStreamDirection
+
+  /**
+   * The maximum number of bytes to store when paused. If receipt of more bytes
+   * from the remote end of the stream causes the buffer size to exceed this
+   * value the stream will be reset and a 'close' event emitted.
+   *
+   * This value can be changed at runtime.
+   */
+  maxReadBufferLength: number
+
+  /**
+   * When the `.send` method returns false it means that the underlying resource
+   * has signalled that it's write buffer is full. If the user continues to call
+   * `.send`, outgoing bytes are stored in an internal buffer until the
+   * underlying resource signals that it can accept more data.
+   *
+   * If the size of that internal buffer exceed this value the stream will be
+   * reset and a 'close' event emitted.
+   *
+   * This value can be changed at runtime.
+   */
+  maxWriteBufferLength?: number
+
+  /**
+   * If no data is transmitted over the stream in this many ms, the stream will
+   * be aborted with an InactivityTimeoutError
+   */
+  inactivityTimeout: number
+
+  /**
+   * If this property is `true`, the underlying transport has signalled that its
+   * write buffer is full and that `.send` should not be called again.
+   *
+   * A `drain` event will be emitted after which is its safe to call `.send`
+   * again to resume sending.
+   */
+  writableNeedsDrain: boolean
+
+  /**
+   * Write data to the stream. If the method returns false it means the
+   * internal buffer is now full and the caller should wait for the 'drain'
+   * event before sending more data.
+   *
+   * This method may throw if:
+   * - The internal send buffer is full
+   * - The stream has previously been closed for writing locally or remotely
+   */
+  send (data: Uint8Array | Uint8ArrayList): boolean
+
+  /**
+   * Stop accepting new data to send and return a promise that resolves when any
+   * unsent data has been written into the underlying resource.
+   */
+  close (options?: AbortOptions): Promise<void>
+
+  /**
+   * Stop accepting new data to send, discard any unsent/unread data, and emit a
+   * 'close' event with the 'error' property set to the passed error.
+   */
+  abort (err: Error): void
+
+  /**
+   * Stop emitting further 'message' events. Any received data will be stored in
+   * an internal buffer. If the buffer size reaches `maxReadBufferLength`, the
+   * stream will be reset and a StreamAbortEvent emitted.
+   *
+   * If the underlying resource supports it, the remote peer will be instructed
+   * to pause transmission of further data.
+   */
+  pause (): void
+
+  /**
+   * Resume emitting 'message' events.
+   *
+   * If the underlying resource supports it, the remote peer will be informed
+   * that it is ok to start sending data again.
+   */
+  resume (): void
+
+  /**
+   * Queue the passed data to be emitted as a 'message' event either during the
+   * next tick or sooner if data is received from the underlying resource.
+   */
+  push (buf: Uint8Array | Uint8ArrayList): void
+}

package/src/metrics.ts

@@ -1,4 +1,4 @@
-import type { MultiaddrConnection, Stream, Connection } from './connection.js'
+import type { MultiaddrConnection, Stream } from './index.js'
 
 /**
  * Create tracked metrics with these options. Loosely based on the
@@ -434,7 +434,7 @@ export interface Metrics {
   /**
    * Track a newly opened protocol stream
    */
-  trackProtocolStream(stream: Stream, connection: Connection): void
+  trackProtocolStream(stream: Stream): void
 
   /**
    * Register an arbitrary metric. Call this to set help/labels for metrics

package/src/multiaddr-connection.ts

@@ -0,0 +1,27 @@
+import type { MessageStream, MessageStreamTimeline } from './message-stream.ts'
+import type { Multiaddr } from '@multiformats/multiaddr'
+
+export interface MultiaddrConnectionTimeline extends MessageStreamTimeline {
+  /**
+   * When the MultiaddrConnection was upgraded to a Connection - the type of
+   * connection encryption and multiplexing was negotiated.
+   */
+  upgraded?: number
+}
+
+/**
+ * A MultiaddrConnection is returned by a transport after dialing a peer. It is
+ * a low-level primitive and is the raw connection, typically without encryption
+ * or stream multiplexing.
+ */
+export interface MultiaddrConnection extends MessageStream<MultiaddrConnectionTimeline> {
+  /**
+   * The address of the remote end of the connection
+   */
+  remoteAddr: Multiaddr
+
+  /**
+   * When stream life cycle events occurred
+   */
+  timeline: MultiaddrConnectionTimeline
+}

package/src/peer-store.ts

@@ -314,9 +314,4 @@ export interface PeerStore {
    * ```
    */
   consumePeerRecord(buf: Uint8Array, options?: ConsumePeerRecordOptions): Promise<boolean>
-
-  /**
-   * @deprecated Pass `expectedPeer` as a property of `options` instead
-   */
-  consumePeerRecord(buf: Uint8Array, expectedPeer?: PeerId, options?: AbortOptions): Promise<boolean>
 }

package/src/stream-handler.ts

@@ -1,23 +1,17 @@
-import type { Connection, Stream } from './connection.js'
-import type { AbortOptions } from './index.ts'
-
-export interface IncomingStreamData {
-  /**
-   * The newly opened stream
-   */
-  stream: Stream
-
-  /**
-   * The connection the stream was opened on
-   */
-  connection: Connection
-}
+import type { AbortOptions, Connection, Stream } from './index.ts'
 
 export interface StreamHandler {
   /**
    * A callback function that accepts the incoming stream data
    */
-  (data: IncomingStreamData): void | Promise<void>
+  (stream: Stream, connection: Connection): void | Promise<void>
+}
+
+/**
+ * Stream middleware allows accessing stream data outside of the stream handler
+ */
+export interface StreamMiddleware {
+  (stream: Stream, connection: Connection, next: (stream: Stream, connection: Connection) => void): void | Promise<void>
 }
 
 export interface StreamHandlerOptions extends AbortOptions {
@@ -46,6 +40,11 @@ export interface StreamHandlerOptions extends AbortOptions {
    * protocol(s), the existing handler will be discarded.
    */
   force?: true
+
+  /**
+   * Middleware allows accessing stream data outside of the stream handler
+   */
+  middleware?: StreamMiddleware[]
 }
 
 export interface StreamHandlerRecord {

package/src/stream-muxer.ts

@@ -1,68 +1,160 @@
-import type { Direction, Stream } from './connection.js'
-import type { AbortOptions, Logger } from './index.js'
-import type { Duplex } from 'it-stream-types'
-import type { Uint8ArrayList } from 'uint8arraylist'
+import type { Stream, TypedEventTarget, MessageStream, AbortOptions } from './index.js'
 
-export interface StreamMuxerFactory {
+/**
+ * User-facing message stream muxer options
+ */
+export interface StreamMuxerOptions<MuxedStreamOptions extends StreamOptions = StreamOptions> {
   /**
-   * The protocol used to select this muxer during connection opening
+   * Configuration options for each outgoing/incoming stream
    */
-  protocol: string
+  streamOptions?: MuxedStreamOptions
 
   /**
-   * Creates a new stream muxer to be used with a new connection
+   * libp2p is notified of incoming streams via the muxer's 'stream' event.
+   *
+   * During connection establishment there may be a small window where a muxer
+   * starts to process incoming stream data before a listener has been added for
+   * the 'stream' event.
+   *
+   * If no handler is registered for this event incoming streams can be missed
+   * so when this is the case muxers queue streams internally as "early
+   * streams", and will defer emitting the 'stream' event until after a listener
+   * has been registered.
+   *
+   * Allowing an unlimited amount of early streams can cause excessive memory
+   * consumption so this setting controls how many early streams to store when
+   * no 'stream' listener has been registered.
+   *
+   * If more streams than this are opened before a listener is added the muxed
+   * connection will be reset.
+   *
+   * @default 10
+   */
+  maxEarlyStreams?: number
+
+  /**
+   * Maximum size of a message in bytes that we'll send on a stream - this
+   * ensures that a single stream doesn't hog a connection
+   *
+   * @default 65_536
+   */
+  maxMessageSize?: number
+
+  /**
+   * Maximum number of concurrent inbound streams that we accept - if the peer
+   * tries to open more streams, those will be reset immediately
+   *
+   * @default 1_000
    */
-  createStreamMuxer(init?: StreamMuxerInit): StreamMuxer
+  maxInboundStreams?: number
+
+  /**
+   * Maximum number of concurrent outbound streams that we accept - if the
+   * application tries to open more streams, the call to `newStream` will throw
+   *
+   * @default 1_000
+   */
+  maxOutboundStreams?: number
 }
 
 /**
- * A libp2p stream muxer
+ * User-facing message stream options
  */
-export interface StreamMuxer extends Duplex<AsyncGenerator<Uint8Array | Uint8ArrayList>> {
+export interface StreamOptions {
+  /**
+   * If no data is sent or received in this number of ms the stream will be
+   * reset and an 'error' event emitted.
+   *
+   * @default 120_000
+   */
+  inactivityTimeout?: number
+
+  /**
+   * The maximum number of bytes to store when paused or before a 'message'
+   * event handler is added.
+   *
+   * If the internal buffer overflows this value the stream will be reset.
+   *
+   * @default 4_194_304
+   */
+  maxReadBufferLength?: number
+
+  /**
+   * The maximum number of bytes to store when the remote end of the stream is
+   * applying backpressure, or when it is slow to accept new bytes.
+   *
+   * If the internal buffer overflows this value the stream will be reset.
+   *
+   * @default Infinity
+   */
+  maxWriteBufferLength?: number
+}
+
+export interface StreamMuxerFactory<Muxer extends StreamMuxer = StreamMuxer> {
   /**
    * The protocol used to select this muxer during connection opening
    */
   protocol: string
 
   /**
-   * A list of streams that are currently open. Closed streams will not be returned.
+   * Creates a new stream muxer to be used with a new connection
+   */
+  createStreamMuxer(maConn: MessageStream): Muxer
+}
+
+export interface StreamMuxerEvents<MuxedStream extends Stream = Stream> {
+  /**
+   * An incoming stream was created
    */
-  readonly streams: Stream[]
+  stream: CustomEvent<MuxedStream>
+}
+
+export interface CreateStreamOptions extends AbortOptions, StreamOptions {
   /**
-   * Initiate a new stream with the given name. If no name is
-   * provided, the id of the stream will be used.
+   * If a single protocol was requested and the muxer has support for this,
+   * pre-negotiate the protocol using this value, otherwise multistream-select
+   * will be run over the stream after opening.
    */
-  newStream(name?: string): Stream | Promise<Stream>
+  protocol?: string
+}
 
+export type StreamMuxerStatus = 'open' | 'closing' | 'closed'
+
+/**
+ * A libp2p stream muxer
+ */
+export interface StreamMuxer<MuxedStream extends Stream = Stream> extends TypedEventTarget<StreamMuxerEvents<MuxedStream>> {
   /**
-   * Close or abort all tracked streams and stop the muxer
+   * The protocol used to select this muxer during connection opening
    */
-  close(options?: AbortOptions): Promise<void>
+  protocol: string
 
   /**
-   * Close or abort all tracked streams and stop the muxer
+   * A list of streams that are currently open
    */
-  abort(err: Error): void
-}
+  streams: MuxedStream[]
 
-export interface StreamMuxerInit {
   /**
-   * A callback function invoked every time an incoming stream is opened
+   * The status of the muxer
    */
-  onIncomingStream?(stream: Stream): void
+  status: StreamMuxerStatus
 
   /**
-   * A callback function invoke every time a stream ends
+   * Create a new stream
    */
-  onStreamEnd?(stream: Stream): void
+  createStream(options?: CreateStreamOptions): Promise<MuxedStream>
 
   /**
-   * Outbound stream muxers are opened by the local node, inbound stream muxers are opened by the remote
+   * Immediately close the muxer, abort every open stream and discard any
+   * unsent/unread data.
    */
-  direction?: Direction
+  abort (err: Error): void
 
   /**
-   * The logger used by the connection
+   * Gracefully close the muxer. All open streams will be gracefully closed, and
+   * the returned promise will either resolve when any/all unsent data has been
+   * sent, or it will reject if the passed abort signal fires before this
+   * happens.
    */
-  log?: Logger
+  close (options?: AbortOptions): Promise<void>
 }

package/src/stream.ts

@@ -0,0 +1,70 @@
+import type { AbortOptions } from './index.ts'
+import type { MessageStream, MessageStreamReadStatus, MessageStreamWriteStatus } from './message-stream.js'
+
+/**
+ * A Stream is a lightweight data channel between two peers that can be written
+ * to and read from at both ends.
+ *
+ * It is half-closable - that is in order for it to be closed fully and any
+ * associated memory reclaimed, both ends must close their writeable end of the
+ * stream.
+ *
+ * It's also possible to close the readable end of the stream, but this depends
+ * on the underlying stream muxer supporting this operation which not all do.
+ */
+export interface Stream extends MessageStream {
+  /**
+   * Unique identifier for a stream. Identifiers are not unique across muxers.
+   */
+  id: string
+
+  /**
+   * The protocol negotiated for this stream
+   */
+  protocol: string
+
+  /**
+   * The status of the readable end of the stream
+   */
+  readStatus: MessageStreamReadStatus
+
+  /**
+   * The status of the writable end of the stream
+   */
+  writeStatus: MessageStreamWriteStatus
+
+  /**
+   * The status of the readable end of the remote end of the stream - n.b. this
+   * requires the underlying stream transport to support sending STOP_SENDING
+   * messages or similar.
+   */
+  remoteReadStatus: MessageStreamReadStatus
+
+  /**
+   * The status of the writable end of the remote end of the stream
+   */
+  remoteWriteStatus: MessageStreamWriteStatus
+
+  /**
+   * Close stream for writing and return a promise that resolves once any
+   * pending data has been passed to the underlying transport.
+   *
+   * Note that the stream itself will remain readable until the remote end also
+   * closes it's writable end.
+   *
+   * To close without waiting for the remote, call `.abort` instead. If you want
+   * to wait for data to be sent first, ensure if the `.writableStatus` property
+   * is not 'paused', if it is, wait for a `drain` event before aborting.
+   */
+  close (options?: AbortOptions): Promise<void>
+
+  /**
+   * Send a message to the remote end of the stream informing them that any
+   * incoming data will be discarded so they should stop sending.
+   *
+   * This requires the underlying resource to support this operation - for
+   * example the QUIC, WebTransport, WebRTC transports do but anything
+   * multiplexed using Yamux or Mplex do not.
+   */
+  closeRead(options?: AbortOptions): Promise<void>
+}

package/src/topology.ts

@@ -5,7 +5,7 @@ import type { PeerId } from './peer-id.js'
  * A topology filter - this can be used by topologies to ensure they do not
  * receive duplicate notifications of individual peers
  *
- * @see https://libp2p.github.io/js-libp2p/functions/_libp2p_peer_collections.peerFilter-1.html
+ * @see https://libp2p.github.io/js-libp2p/classes/_libp2p_peer-collections.PeerFilter.html
  */
 export interface TopologyFilter {
   has (peerId: PeerId): boolean
@@ -40,11 +40,11 @@ export interface Topology {
    * Invoked when a new connection is opened to a peer that supports the
    * registered protocol
    */
-  onConnect?(peerId: PeerId, conn: Connection): void
+  onConnect?(peerId: PeerId, conn: Connection): void | Promise<void>
 
   /**
    * Invoked when the last connection to a peer that supports the registered
    * protocol closes
    */
-  onDisconnect?(peerId: PeerId): void
+  onDisconnect?(peerId: PeerId): void | Promise<void>
 }

package/src/transport.ts

@@ -1,6 +1,4 @@
-import type { Connection, ConnectionLimits, MultiaddrConnection } from './connection.js'
-import type { AbortOptions, ClearableSignal, ConnectionEncrypter } from './index.js'
-import type { StreamMuxerFactory } from './stream-muxer.js'
+import type { AbortOptions, ClearableSignal, ConnectionEncrypter, MultiaddrConnection, Connection, ConnectionLimits, StreamMuxerFactory, PeerId } from './index.js'
 import type { Multiaddr } from '@multiformats/multiaddr'
 import type { TypedEventTarget } from 'main-event'
 import type { ProgressOptions, ProgressEvent } from 'progress-events'
@@ -29,16 +27,19 @@ export interface Listener extends TypedEventTarget<ListenerEvents> {
    * Start a listener
    */
   listen(multiaddr: Multiaddr): Promise<void>
+
   /**
    * Get listen addresses
    */
   getAddrs(): Multiaddr[]
+
   /**
    * Close listener
    *
    * @returns {Promise<void>}
    */
   close(): Promise<void>
+
   /**
    * Allows transports to amend announce addresses - to add certificate hashes
    * or other metadata that cannot be known before runtime
@@ -134,15 +135,6 @@ export enum FaultTolerance {
  * Options accepted by the upgrader during connection establishment
  */
 export interface UpgraderOptions<ConnectionUpgradeEvents extends ProgressEvent = ProgressEvent> extends ProgressOptions<ConnectionUpgradeEvents>, Required<AbortOptions> {
-  /**
-   * If true the invoking transport is expected to implement it's own encryption
-   * and an encryption protocol will not attempted to be negotiated via
-   * multi-stream select
-   *
-   * @default false
-   */
-  skipEncryption?: boolean
-
   /**
    * If true no connection protection will be performed on the connection.
    */
@@ -172,6 +164,23 @@ export interface UpgraderOptions<ConnectionUpgradeEvents extends ProgressEvent =
   initiator?: boolean
 }
 
+/**
+ * Options accepted by the upgrader during connection establishment
+ */
+export interface UpgraderWithoutEncryptionOptions extends UpgraderOptions {
+  /**
+   * If true the invoking transport is expected to implement it's own encryption
+   * and an encryption protocol will not attempted to be negotiated via
+   * multi-stream select
+   */
+  skipEncryption: true
+
+  /**
+   * If `skipEncryption` is true, a remote PeerId must be supplied
+   */
+  remotePeer: PeerId
+}
+
 export type InboundConnectionUpgradeEvents =
 ProgressEvent<'upgrader:encrypt-inbound-connection'> |
 ProgressEvent<'upgrader:multiplex-inbound-connection'>
@@ -184,13 +193,15 @@ export interface Upgrader {
   /**
    * Upgrades an outbound connection created by the `dial` method of a transport
    */
-  upgradeOutbound(maConn: MultiaddrConnection, opts?: UpgraderOptions<OutboundConnectionUpgradeEvents>): Promise<Connection>
+  upgradeOutbound(maConn: MultiaddrConnection, opts: UpgraderOptions<OutboundConnectionUpgradeEvents>): Promise<Connection>
+  upgradeOutbound(maConn: MultiaddrConnection, opts: UpgraderWithoutEncryptionOptions): Promise<Connection>
 
   /**
    * Upgrades an inbound connection received by a transport listener and
    * notifies other libp2p components about the new connection
    */
-  upgradeInbound(maConn: MultiaddrConnection, opts?: UpgraderOptions<InboundConnectionUpgradeEvents>): Promise<void>
+  upgradeInbound(maConn: MultiaddrConnection, opts: UpgraderOptions<InboundConnectionUpgradeEvents>): Promise<void>
+  upgradeInbound(maConn: MultiaddrConnection, opts: UpgraderWithoutEncryptionOptions): Promise<void>
 
   /**
    * Used by transports that perform part of the upgrade process themselves and