@libp2p/interface 0.0.1-5315f7bc → 0.0.1-562f9b08

package/src/connection/index.ts

@@ -1,4 +1,3 @@
-import type * as Status from './status.js'
 import type { AbortOptions } from '../index.js'
 import type { PeerId } from '../peer-id/index.js'
 import type { Multiaddr } from '@multiformats/multiaddr'
@@ -6,43 +5,28 @@ import type { Duplex, Source } from 'it-stream-types'
 import type { Uint8ArrayList } from 'uint8arraylist'
 
 export interface ConnectionTimeline {
-  open: number
-  upgraded?: number
-  close?: number
-}
-
-/**
- * Outbound conections are opened by the local node, inbound streams are opened by the remote
- */
-export type Direction = 'inbound' | 'outbound'
-
-export interface ConnectionStat {
-  /**
-   * Outbound conections are opened by the local node, inbound streams are opened by the remote
-   */
-  direction: Direction
-
-  /**
-   * Lifecycle times for the connection
-   */
-  timeline: ConnectionTimeline
-
   /**
-   * Once a multiplexer has been negotiated for this stream, it will be set on the stat object
+   * When the connection was opened
    */
-  multiplexer?: string
+  open: number
 
   /**
-   * Once a connection encrypter has been negotiated for this stream, it will be set on the stat object
+   * When the MultiaddrConnection was upgraded to a Connection - e.g. the type
+   * of connection encryption and multiplexing was negotiated.
    */
-  encryption?: string
+  upgraded?: number
 
   /**
-   * The current status of the connection
+   * When the connection was closed.
    */
-  status: keyof typeof Status
+  close?: number
 }
 
+/**
+ * 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
@@ -68,24 +52,37 @@ export interface StreamTimeline {
    * A timestamp of when the stream was reset
    */
   reset?: number
-}
 
-export interface StreamStat {
   /**
-   * Outbound streams are opened by the local node, inbound streams are opened by the remote
+   * A timestamp of when the stream was aborted
    */
-  direction: Direction
+  abort?: number
+}
 
-  /**
-   * Lifecycle times for the stream
-   */
-  timeline: StreamTimeline
+/**
+ * The states a stream can be in
+ */
+export type StreamStatus = 'open' | 'closing' | 'closed' | 'aborted' | 'reset'
 
-  /**
-   * Once a protocol has been negotiated for this stream, it will be set on the stat object
-   */
-  protocol?: string
-}
+/**
+ * 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
@@ -104,7 +101,7 @@ export interface Stream extends Duplex<AsyncGenerator<Uint8ArrayList>, Source<Ui
    *
    * The sink and the source will return normally.
    */
-  close: () => void
+  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.
@@ -113,14 +110,14 @@ export interface Stream extends Duplex<AsyncGenerator<Uint8ArrayList>, Source<Ui
    *
    * The source will return normally, the sink will continue to consume.
    */
-  closeRead: () => void
+  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: () => void
+  closeWrite: (options?: AbortOptions) => Promise<void>
 
   /**
    * Closes the stream for **reading** *and* **writing**. This should be called when a *local error* has occurred.
@@ -134,28 +131,44 @@ export interface Stream extends Duplex<AsyncGenerator<Uint8ArrayList>, Source<Ui
   abort: (err: Error) => void
 
   /**
-   * Closes the stream *immediately* for **reading** *and* **writing**. This should be called when a *remote error* has occurred.
-   *
-   * This function is called automatically by the muxer when it receives a `RESET` message from the remote.
-   *
-   * The sink will return and the source will throw.
+   * 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
    */
-  reset: () => void
+  direction: Direction
 
   /**
-   * Unique identifier for a stream. Identifiers are not unique across muxers.
+   * Lifecycle times for the stream
    */
-  id: string
+  timeline: StreamTimeline
 
   /**
-   * Stats about this stream
+   * Once a protocol has been negotiated for this stream, it will be set on the stat object
    */
-  stat: StreamStat
+  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
 }
 
 export interface NewStreamOptions extends AbortOptions {
@@ -167,6 +180,8 @@ export interface NewStreamOptions extends AbortOptions {
   maxOutboundStreams?: number
 }
 
+export type ConnectionStatus = 'open' | 'closing' | 'closed'
+
 /**
  * A Connection is a high-level representation of a connection
  * to a remote peer that may have been secured by encryption and
@@ -174,17 +189,81 @@ export interface NewStreamOptions extends AbortOptions {
  * between which the connection is made.
  */
 export interface Connection {
+  /**
+   * The unique identifier for this connection
+   */
   id: string
-  stat: ConnectionStat
+
+  /**
+   * The address of the remote end of the connection
+   */
   remoteAddr: Multiaddr
+
+  /**
+   * The id of the peer at the remote end of the connection
+   */
   remotePeer: PeerId
+
+  /**
+   * A list of tags applied to this connection
+   */
   tags: string[]
+
+  /**
+   * A list of open streams on this connection
+   */
   streams: Stream[]
 
-  newStream: (multicodecs: string | string[], options?: NewStreamOptions) => Promise<Stream>
+  /**
+   * Outbound conections are opened by the local node, inbound streams are opened by the remote
+   */
+  direction: Direction
+
+  /**
+   * Lifecycle times for the connection
+   */
+  timeline: ConnectionTimeline
+
+  /**
+   * Once a multiplexer has been negotiated for this stream, it will be set on the stat object
+   */
+  multiplexer?: string
+
+  /**
+   * Once a connection encrypter has been negotiated for this stream, it will be set on the stat object
+   */
+  encryption?: string
+
+  /**
+   * The current status of the connection
+   */
+  status: ConnectionStatus
+
+  /**
+   * Create a new stream on this connection and negotiate one of the passed protocols
+   */
+  newStream: (protocols: string | string[], options?: NewStreamOptions) => Promise<Stream>
+
+  /**
+   * Add a stream to this connection
+   */
   addStream: (stream: Stream) => void
+
+  /**
+   * Remove a stream from this connection
+   */
   removeStream: (id: string) => void
-  close: () => Promise<void>
+
+  /**
+   * 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
 }
 
 export const symbol = Symbol.for('@libp2p/connection')
@@ -194,7 +273,6 @@ export function isConnection (other: any): other is Connection {
 }
 
 export interface ConnectionProtector {
-
   /**
    * Takes a given Connection and creates a private encryption stream
    * between its two peers from the PSK the Protector instance was
@@ -204,8 +282,20 @@ export interface ConnectionProtector {
 }
 
 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
 }
 
@@ -215,7 +305,24 @@ export interface MultiaddrConnectionTimeline {
  * without encryption or stream multiplexing.
  */
 export interface MultiaddrConnection extends Duplex<AsyncGenerator<Uint8Array>, Source<Uint8Array>, Promise<void>> {
-  close: (err?: Error) => Promise<void>
+  /**
+   * 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 lifecycle events occurred
+   */
   timeline: MultiaddrConnectionTimeline
 }

package/src/index.ts

@@ -506,7 +506,11 @@ export interface Libp2p<T extends ServiceMap = ServiceMap> extends Startable, Ev
   dialProtocol: (peer: PeerId | Multiaddr | Multiaddr[], protocols: string | string[], options?: AbortOptions) => Promise<Stream>
 
   /**
-   * Attempts to gracefully close an open connection to the given peer. If the connection is not closed in the grace period, it will be forcefully closed.
+   * Attempts to gracefully close an open connection to the given peer. If the
+   * connection is not closed in the grace period, it will be forcefully closed.
+   *
+   * An AbortSignal can optionally be passed to control when the connection is
+   * forcefully closed.
    *
    * @example
    *
@@ -514,7 +518,7 @@ export interface Libp2p<T extends ServiceMap = ServiceMap> extends Startable, Ev
    * await libp2p.hangUp(remotePeerId)
    * ```
    */
-  hangUp: (peer: PeerId | Multiaddr) => Promise<void>
+  hangUp: (peer: PeerId | Multiaddr, options?: AbortOptions) => Promise<void>
 
   /**
    * Sets up [multistream-select routing](https://github.com/multiformats/multistream-select) of protocols to their application handlers. Whenever a stream is opened on one of the provided protocols, the handler will be called. `handle` must be called in order to register a handler and support for a given protocol. This also informs other peers of the protocols you support.

package/src/stream-muxer/index.ts

@@ -37,10 +37,15 @@ export interface StreamMuxer extends Duplex<AsyncGenerator<Uint8Array>, Source<U
   /**
    * Close or abort all tracked streams and stop the muxer
    */
-  close: (err?: Error) => void
+  close: (options?: AbortOptions) => Promise<void>
+
+  /**
+   * Close or abort all tracked streams and stop the muxer
+   */
+  abort: (err: Error) => void
 }
 
-export interface StreamMuxerInit extends AbortOptions {
+export interface StreamMuxerInit {
   /**
    * A callback function invoked every time an incoming stream is opened
    */