@libp2p/interface 2.11.0 → 3.0.0-334f91bdc

package/src/connection.ts

@@ -1,179 +1,29 @@
-import type { AbortOptions, Logger } from './index.js'
-import type { PeerId } from './peer-id.js'
+import type { AbortOptions, Logger, TypedEventTarget, Stream, MessageStreamEvents, PeerId, MultiaddrConnectionTimeline, MessageStreamStatus, MessageStreamDirection } from './index.js'
 import type { Multiaddr } from '@multiformats/multiaddr'
-import type { Duplex, Source } from 'it-stream-types'
-import type { Uint8ArrayList } from 'uint8arraylist'
 
-export interface ConnectionTimeline {
-  /**
-   * When the connection was opened
-   */
-  open: number
-
-  /**
-   * When the MultiaddrConnection was upgraded to a Connection - e.g. the type
-   * of connection encryption and multiplexing was negotiated.
-   */
-  upgraded?: number
-
-  /**
-   * When the connection was closed.
-   */
-  close?: number
-}
+export type ConnectionStatus = MessageStreamStatus
 
 /**
- * Outbound connections are opened by the local node, inbound streams are opened by the remote
- */
-export type Direction = 'inbound' | 'outbound'
-
-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
-
-  /**
-   * A timestamp of when the stream was aborted
-   */
-  abort?: number
-}
-
-/**
- * The states a stream can be in
- */
-export type StreamStatus = 'open' | 'closing' | 'closed' | 'aborted' | 'reset'
-
-/**
- * The states the readable end of a stream can be in
- *
- * ready - the readable end is ready for reading
- * closing - the readable end is closing
- * closed - the readable end has closed
- */
-export type ReadStatus = 'ready' | 'closing' | 'closed'
-
-/**
- * The states the writable end of a stream can be in
- *
- * ready - the writable end is ready for writing
- * writing - the writable end is in the process of being written to
- * done - the source passed to the `.sink` function yielded all values without error
- * closing - the writable end is closing
- * closed - the writable end has closed
- */
-export type WriteStatus = 'ready' | 'writing' | 'done' | 'closing' | 'closed'
-
-/**
- * A Stream is a data channel between two peers that
- * can be written to and read from at both ends.
+ * Connection limits are present on connections that are only allowed to
+ * transfer a certain amount of bytes or be open for a certain number
+ * of seconds.
  *
- * It may be encrypted and multiplexed depending on the
- * configuration of the nodes.
+ * These limits are applied by Circuit Relay v2 servers, for example and
+ * the connection will normally be closed abruptly if the limits are
+ * exceeded.
  */
-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(options?: AbortOptions): Promise<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(options?: AbortOptions): Promise<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(options?: AbortOptions): Promise<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.
-   */
-  abort(err: Error): void
-
-  /**
-   * Unique identifier for a stream. Identifiers are not unique across muxers.
-   */
-  id: string
-
-  /**
-   * Outbound streams are opened by the local node, inbound streams are opened by the remote
-   */
-  direction: Direction
-
-  /**
-   * Lifecycle times for the stream
-   */
-  timeline: StreamTimeline
-
-  /**
-   * The protocol negotiated for this stream
-   */
-  protocol?: string
-
-  /**
-   * User defined stream metadata
-   */
-  metadata: Record<string, any>
-
-  /**
-   * The current status of the stream
-   */
-  status: StreamStatus
-
-  /**
-   * The current status of the readable end of the stream
-   */
-  readStatus: ReadStatus
-
+export interface ConnectionLimits {
   /**
-   * The current status of the writable end of the stream
+   * If present this is the number of bytes remaining that may be
+   * transferred over this connection
    */
-  writeStatus: WriteStatus
+  bytes?: bigint
 
   /**
-   * The stream logger
+   * If present this is the number of seconds that this connection will
+   * remain open for
    */
-  log: Logger
+  seconds?: number
 }
 
 export interface NewStreamOptions extends AbortOptions {
@@ -186,10 +36,11 @@ export interface NewStreamOptions extends AbortOptions {
 
   /**
    * Opt-in to running over a limited connection - one that has restrictions
-   * on the amount of data that may be transferred or how long it may be open for.
+   * on the amount of data that may be transferred or how long it may be open
+   * for.
    *
-   * These limits are typically enforced by a relay server, if the protocol
-   * will be transferring a lot of data or the stream will be open for a long time
+   * These limits are typically enforced by a relay server, if the protocol will
+   * be transferring a lot of data or the stream will be open for a long time
    * consider upgrading to a direct connection before opening the stream.
    *
    * @default false
@@ -224,38 +75,13 @@ export interface NewStreamOptions extends AbortOptions {
   negotiateFully?: boolean
 }
 
-export type ConnectionStatus = 'open' | 'closing' | 'closed'
-
-/**
- * Connection limits are present on connections that are only allowed to
- * transfer a certain amount of bytes or be open for a certain number
- * of seconds.
- *
- * These limits are applied by Circuit Relay v2 servers, for example and
- * the connection will normally be closed abruptly if the limits are
- * exceeded.
- */
-export interface ConnectionLimits {
-  /**
-   * If present this is the number of bytes remaining that may be
-   * transferred over this connection
-   */
-  bytes?: bigint
-
-  /**
-   * If present this is the number of seconds that this connection will
-   * remain open for
-   */
-  seconds?: 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 {
+export interface Connection extends TypedEventTarget<Omit<MessageStreamEvents, 'drain' | 'message'>> {
   /**
    * The unique identifier for this connection
    */
@@ -271,11 +97,6 @@ export interface Connection {
    */
   remotePeer: PeerId
 
-  /**
-   * A list of tags applied to this connection
-   */
-  tags: string[]
-
   /**
    * A list of open streams on this connection
    */
@@ -284,12 +105,12 @@ export interface Connection {
   /**
    * Outbound connections are opened by the local node, inbound streams are opened by the remote
    */
-  direction: Direction
+  direction: MessageStreamDirection
 
   /**
-   * Lifecycle times for the connection
+   * When stream life cycle events occurred
    */
-  timeline: ConnectionTimeline
+  timeline: MultiaddrConnectionTimeline
 
   /**
    * The multiplexer negotiated for this connection
@@ -306,6 +127,11 @@ export interface Connection {
    */
   status: ConnectionStatus
 
+  /**
+   * Whether this connection is direct or, for example, is via a relay
+   */
+  direct: boolean
+
   /**
    * If present, this connection has limits applied to it, perhaps by an
    * intermediate relay. Once the limits have been reached the connection will
@@ -320,26 +146,28 @@ export interface Connection {
    */
   rtt?: number
 
+  /**
+   * The connection logger, used to log connection-specific information
+   */
+  log: Logger
+
   /**
    * Create a new stream on this connection and negotiate one of the passed protocols
    */
   newStream(protocols: string | string[], options?: NewStreamOptions): Promise<Stream>
 
   /**
-   * Gracefully close the connection. All queued data will be written to the
-   * underlying transport.
+   * Gracefully close the connection. The returned promise will resolve when all
+   * queued data has been written to the underlying transport. Any unread data
+   * will still be emitted as a 'message' event.
    */
   close(options?: AbortOptions): Promise<void>
 
   /**
-   * Immediately close the connection, any queued data will be discarded
+   * Immediately close the connection. Any data queued to be sent or read will
+   * be discarded.
    */
   abort(err: Error): void
-
-  /**
-   * The connection logger
-   */
-  log: Logger
 }
 
 export const connectionSymbol = Symbol.for('@libp2p/connection')
@@ -347,63 +175,3 @@ export const connectionSymbol = Symbol.for('@libp2p/connection')
 export function isConnection (other: any): other is Connection {
   return other != null && Boolean(other[connectionSymbol])
 }
-
-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, options?: AbortOptions): Promise<MultiaddrConnection>
-}
-
-export interface MultiaddrConnectionTimeline {
-  /**
-   * When the connection was opened
-   */
-  open: number
-
-  /**
-   * When the MultiaddrConnection was upgraded to a Connection - the type of
-   * connection encryption and multiplexing was negotiated.
-   */
-  upgraded?: number
-
-  /**
-   * When the connection was closed.
-   */
-  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 | Uint8ArrayList>> {
-  /**
-   * Gracefully close the connection. All queued data will be written to the
-   * underlying transport.
-   */
-  close(options?: AbortOptions): Promise<void>
-
-  /**
-   * Immediately close the connection, any queued data will be discarded
-   */
-  abort(err: Error): void
-
-  /**
-   * The address of the remote end of the connection
-   */
-  remoteAddr: Multiaddr
-
-  /**
-   * When connection life cycle events occurred
-   */
-  timeline: MultiaddrConnectionTimeline
-
-  /**
-   * The multiaddr connection logger
-   */
-  log: Logger
-}

package/src/errors.ts

@@ -144,6 +144,18 @@ export class StreamResetError extends Error {
   }
 }
 
+/**
+ * Thrown when a protocol stream is aborted locally
+ */
+export class StreamAbortedError extends Error {
+  static name = 'StreamAbortedError'
+
+  constructor (message = 'The stream has been aborted') {
+    super(message)
+    this.name = 'StreamAbortedError'
+  }
+}
+
 /**
  * Thrown when a stream is in an invalid state
  */
@@ -156,6 +168,18 @@ export class StreamStateError extends Error {
   }
 }
 
+/**
+ * Thrown when a stream buffer is full
+ */
+export class StreamBufferError extends Error {
+  static name = 'StreamBufferError'
+
+  constructor (message = 'The stream buffer was full') {
+    super(message)
+    this.name = 'StreamBufferError'
+  }
+}
+
 /**
  * Thrown when a value could not be found
  */

package/src/events.ts

@@ -0,0 +1,44 @@
+import type { Uint8ArrayList } from 'uint8arraylist'
+
+/**
+ * A custom implementation of MessageEvent as the Undici version does too much
+ * validation in it's constructor so is very slow.
+ */
+export class StreamMessageEvent extends Event {
+  public data: Uint8Array | Uint8ArrayList
+
+  constructor (data: Uint8Array | Uint8ArrayList, eventInitDict?: EventInit) {
+    super('message', eventInitDict)
+
+    this.data = data
+  }
+}
+
+/**
+ * An event dispatched when the stream is closed. The `error` property can be
+ * inspected to discover if the closing was graceful or not, and the `remote`
+ * property shows which end of the stream initiated the closure
+ */
+export class StreamCloseEvent extends Event {
+  public error?: Error
+  public local?: boolean
+
+  constructor (local?: boolean, error?: Error, eventInitDict?: EventInit) {
+    super('close', eventInitDict)
+
+    this.error = error
+    this.local = local
+  }
+}
+
+export class StreamAbortEvent extends StreamCloseEvent {
+  constructor (error: Error, eventInitDict?: EventInit) {
+    super(true, error, eventInitDict)
+  }
+}
+
+export class StreamResetEvent extends StreamCloseEvent {
+  constructor (error: Error, eventInitDict?: EventInit) {
+    super(false, error, eventInitDict)
+  }
+}

package/src/index.ts

@@ -14,7 +14,7 @@
  * ```
  */
 
-import type { Connection, NewStreamOptions, Stream } from './connection.js'
+import type { Connection, NewStreamOptions } from './connection.js'
 import type { ContentRouting } from './content-routing.js'
 import type { Ed25519PublicKey, PublicKey, RSAPublicKey, Secp256k1PublicKey } from './keys.js'
 import type { Metrics } from './metrics.js'
@@ -23,7 +23,8 @@ import type { PeerInfo } from './peer-info.js'
 import type { PeerRouting } from './peer-routing.js'
 import type { Address, Peer, PeerStore } from './peer-store.js'
 import type { Startable } from './startable.js'
-import type { StreamHandler, StreamHandlerOptions } from './stream-handler.js'
+import type { StreamHandler, StreamHandlerOptions, StreamMiddleware } from './stream-handler.js'
+import type { Stream } from './stream.js'
 import type { Topology } from './topology.js'
 import type { Listener, OutboundConnectionUpgradeEvents } from './transport.js'
 import type { DNS } from '@multiformats/dns'
@@ -780,6 +781,33 @@ export interface Libp2p<T extends ServiceMap = ServiceMap> extends Startable, Ty
    */
   unregister(id: string): void
 
+  /**
+   * Registers one or more middleware implementations that will be invoked for
+   * incoming and outgoing protocol streams that match the passed protocol.
+   *
+   * @example
+   *
+   * ```TypeScript
+   * libp2p.use('/my/protocol/1.0.0', (stream, connection, next) => {
+   *   // do something with stream and/or connection
+   *   next(stream, connection)
+   * })
+   * ```
+   */
+  use (protocol: string, middleware: StreamMiddleware | StreamMiddleware[]): void
+
+  /**
+   * Deregisters all middleware for the passed protocol.
+   *
+   * @example
+   *
+   * ```TypeScript
+   * libp2p.unuse('/my/protocol/1.0.0')
+   * // any previously registered middleware will no longer be invoked
+   * ```
+   */
+  unuse (protocol: string): void
+
   /**
    * Returns the public key for the passed PeerId. If the PeerId is of the 'RSA'
    * type this may mean searching the routing if the peer's key is not present
@@ -915,20 +943,25 @@ export const serviceDependencies = Symbol.for('@libp2p/service-dependencies')
 export * from './connection.js'
 export * from './connection-encrypter.js'
 export * from './connection-gater.js'
+export * from './connection-protector.js'
 export * from './content-routing.js'
+export * from './errors.js'
+export * from './events.js'
 export * from './keys.js'
+export * from './message-stream.js'
 export * from './metrics.js'
+export * from './multiaddr-connection.js'
 export * from './peer-discovery.js'
 export * from './peer-id.js'
 export * from './peer-info.js'
 export * from './peer-routing.js'
 export * from './peer-store.js'
-export * from './pubsub.js'
 export * from './record.js'
+export * from './startable.js'
 export * from './stream-handler.js'
 export * from './stream-muxer.js'
+export * from './stream.js'
 export * from './topology.js'
 export * from './transport.js'
-export * from './errors.js'
+
 export * from 'main-event'
-export * from './startable.js'