@libp2p/interface 2.11.0-8484de8a2 → 2.11.0-87bc8d4fb

package/src/connection-encrypter.ts

@@ -1,4 +1,8 @@
-import type { AbortOptions, StreamMuxerFactory, PeerId, MessageStream } from './index.js'
+import type { MultiaddrConnection } from './connection.js'
+import type { AbortOptions, Logger, StreamMuxerFactory } from './index.js'
+import type { PeerId } from './peer-id.js'
+import type { Duplex } from 'it-stream-types'
+import type { Uint8ArrayList } from 'uint8arraylist'
 
 /**
  * If the remote PeerId is known and passed as an option, the securing operation
@@ -6,9 +10,6 @@ import type { AbortOptions, StreamMuxerFactory, PeerId, MessageStream } from './
  * corresponds to the public key the remote PeerId is derived from.
  */
 export interface SecureConnectionOptions extends AbortOptions {
-  /**
-   * This will be set if the remote peer is known in advance
-   */
   remotePeer?: PeerId
 
   /**
@@ -20,6 +21,13 @@ export interface SecureConnectionOptions extends AbortOptions {
   skipStreamMuxerNegotiation?: boolean
 }
 
+/**
+ * A stream with an optional logger
+ */
+export interface SecurableStream extends Duplex<AsyncGenerator<Uint8Array | Uint8ArrayList>> {
+  log?: Logger
+}
+
 /**
  * A libp2p connection encrypter module must be compliant to this interface
  * to ensure all exchanged data between two peers is encrypted.
@@ -32,30 +40,19 @@ export interface ConnectionEncrypter<Extension = unknown> {
    * pass it for extra verification, otherwise it will be determined during
    * the handshake.
    */
-  secureOutbound (connection: MessageStream, options?: SecureConnectionOptions): Promise<SecuredConnection<Extension>>
+  secureOutbound <Stream extends SecurableStream = MultiaddrConnection> (connection: Stream, options?: SecureConnectionOptions): 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 (connection: MessageStream, options?: SecureConnectionOptions): Promise<SecuredConnection<Extension>>
+  secureInbound <Stream extends SecurableStream = MultiaddrConnection> (connection: Stream, options?: SecureConnectionOptions): Promise<SecuredConnection<Stream, Extension>>
 }
 
-export interface SecuredConnection<Extension = unknown> {
-  /**
-   * The decrypted data stream
-   */
-  connection: MessageStream
-
-  /**
-   * Any extension data transferred as part of the encryption handshake
-   */
+export interface SecuredConnection<Stream = any, Extension = unknown> {
+  conn: Stream
   remoteExtensions?: Extension
-
-  /**
-   * The identifier of the remote peer
-   */
   remotePeer: PeerId
 
   /**

package/src/connection-gater.ts

@@ -1,4 +1,5 @@
-import type { MultiaddrConnection, PeerId } from './index.js'
+import type { MultiaddrConnection } from './connection.js'
+import type { PeerId } from './peer-id.js'
 import type { Multiaddr } from '@multiformats/multiaddr'
 
 export interface ConnectionGater {

package/src/connection.ts

@@ -1,29 +1,179 @@
-import type { AbortOptions, Logger, TypedEventTarget, Stream, MessageStreamEvents, PeerId, MultiaddrConnectionTimeline, MessageStreamStatus, MessageStreamDirection } from './index.js'
+import type { AbortOptions, Logger } from './index.js'
+import type { PeerId } from './peer-id.js'
 import type { Multiaddr } from '@multiformats/multiaddr'
+import type { Duplex, Source } from 'it-stream-types'
+import type { Uint8ArrayList } from 'uint8arraylist'
 
-export type ConnectionStatus = MessageStreamStatus
+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
+}
 
 /**
- * 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.
+ * 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
  *
- * These limits are applied by Circuit Relay v2 servers, for example and
- * the connection will normally be closed abruptly if the limits are
- * exceeded.
+ * ready - the readable end is ready for reading
+ * closing - the readable end is closing
+ * closed - the readable end has closed
  */
-export interface ConnectionLimits {
+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.
+ *
+ * It may be encrypted and multiplexed depending on the
+ * configuration of the nodes.
+ */
+export interface Stream extends Duplex<AsyncGenerator<Uint8ArrayList>, Source<Uint8ArrayList | Uint8Array>, Promise<void>> {
   /**
-   * If present this is the number of bytes remaining that may be
-   * transferred over this connection
+   * 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.
    */
-  bytes?: bigint
+  close(options?: AbortOptions): Promise<void>
 
   /**
-   * If present this is the number of seconds that this connection will
-   * remain open for
+   * 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.
    */
-  seconds?: number
+  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
+
+  /**
+   * The current status of the writable end of the stream
+   */
+  writeStatus: WriteStatus
+
+  /**
+   * The stream logger
+   */
+  log: Logger
 }
 
 export interface NewStreamOptions extends AbortOptions {
@@ -36,11 +186,10 @@ 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
@@ -75,13 +224,38 @@ 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 extends TypedEventTarget<Omit<MessageStreamEvents, 'drain' | 'message'>> {
+export interface Connection {
   /**
    * The unique identifier for this connection
    */
@@ -97,6 +271,11 @@ export interface Connection extends TypedEventTarget<Omit<MessageStreamEvents, '
    */
   remotePeer: PeerId
 
+  /**
+   * A list of tags applied to this connection
+   */
+  tags: string[]
+
   /**
    * A list of open streams on this connection
    */
@@ -105,12 +284,12 @@ export interface Connection extends TypedEventTarget<Omit<MessageStreamEvents, '
   /**
    * Outbound connections are opened by the local node, inbound streams are opened by the remote
    */
-  direction: MessageStreamDirection
+  direction: Direction
 
   /**
-   * When stream life cycle events occurred
+   * Lifecycle times for the connection
    */
-  timeline: MultiaddrConnectionTimeline
+  timeline: ConnectionTimeline
 
   /**
    * The multiplexer negotiated for this connection
@@ -127,11 +306,6 @@ export interface Connection extends TypedEventTarget<Omit<MessageStreamEvents, '
    */
   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
@@ -146,28 +320,26 @@ export interface Connection extends TypedEventTarget<Omit<MessageStreamEvents, '
    */
   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. 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.
+   * Gracefully close the connection. All queued data will be written to the
+   * underlying transport.
    */
   close(options?: AbortOptions): Promise<void>
 
   /**
-   * Immediately close the connection. Any data queued to be sent or read will
-   * be discarded.
+   * Immediately close the connection, any queued data will be discarded
    */
   abort(err: Error): void
+
+  /**
+   * The connection logger
+   */
+  log: Logger
 }
 
 export const connectionSymbol = Symbol.for('@libp2p/connection')
@@ -175,3 +347,63 @@ 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

@@ -132,34 +132,6 @@ export class MuxerClosedError extends Error {
   }
 }
 
-/**
- * Thrown when a protocol stream is closed during an operation
- *
- * @deprecated delete if unused
- */
-export class StreamClosedError extends Error {
-  static name = 'StreamClosedError'
-
-  constructor (message = 'The stream has been closed') {
-    super(message)
-    this.name = 'StreamClosedError'
-  }
-}
-
-/**
- * Thrown when a protocol stream is closing during an operation
- *
- * @deprecated delete if unused
- */
-export class StreamClosingError extends Error {
-  static name = 'StreamClosingError'
-
-  constructor (message = 'The stream is closing') {
-    super(message)
-    this.name = 'StreamClosingError'
-  }
-}
-
 /**
  * Thrown when a protocol stream is reset by the remote muxer
  */
@@ -172,18 +144,6 @@ 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
  */
@@ -196,18 +156,6 @@ 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/index.ts

@@ -14,7 +14,7 @@
  * ```
  */
 
-import type { Connection, NewStreamOptions } from './connection.js'
+import type { Connection, NewStreamOptions, Stream } 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'
@@ -24,7 +24,6 @@ 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 { Stream } from './stream.js'
 import type { Topology } from './topology.js'
 import type { Listener, OutboundConnectionUpgradeEvents } from './transport.js'
 import type { DNS } from '@multiformats/dns'
@@ -916,14 +915,9 @@ 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'
@@ -931,11 +925,10 @@ 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'

package/src/metrics.ts

@@ -1,4 +1,4 @@
-import type { MultiaddrConnection, Stream } from './index.js'
+import type { MultiaddrConnection, Stream, Connection } from './connection.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): void
+  trackProtocolStream(stream: Stream, connection: Connection): void
 
   /**
    * Register an arbitrary metric. Call this to set help/labels for metrics

package/src/pubsub.ts

@@ -1,4 +1,6 @@
-import type { Stream, PublicKey, PeerId } from './index.js'
+import type { Stream } from './connection.js'
+import type { PublicKey } from './keys.js'
+import type { PeerId } from './peer-id.js'
 import type { Pushable } from 'it-pushable'
 import type { TypedEventTarget } from 'main-event'
 import type { Uint8ArrayList } from 'uint8arraylist'

package/src/stream-handler.ts

@@ -1,10 +1,23 @@
-import type { AbortOptions, Connection, Stream } from './index.ts'
+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
+}
 
 export interface StreamHandler {
   /**
    * A callback function that accepts the incoming stream data
    */
-  (stream: Stream, connection: Connection): void | Promise<void>
+  (data: IncomingStreamData): void | Promise<void>
 }
 
 export interface StreamHandlerOptions extends AbortOptions {