@libp2p/interface 0.0.1-e9cafd3d → 0.0.1-eabf6f36

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,8 +5,20 @@ 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
 }
 
@@ -41,8 +52,38 @@ export interface StreamTimeline {
    * 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.
@@ -60,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.
@@ -69,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.
@@ -89,15 +130,6 @@ 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.
-   */
-  reset: () => void
-
   /**
    * Unique identifier for a stream. Identifiers are not unique across muxers.
    */
@@ -122,6 +154,21 @@ export interface Stream extends Duplex<AsyncGenerator<Uint8ArrayList>, Source<Ui
    * 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 {
@@ -131,8 +178,16 @@ export interface NewStreamOptions extends AbortOptions {
    * for the protocol
    */
   maxOutboundStreams?: number
+
+  /**
+   * Opt-in to running over a transient connection - one that has time/data limits
+   * placed on it.
+   */
+  runOnTransientConnection?: boolean
 }
 
+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
@@ -188,12 +243,41 @@ export interface Connection {
   /**
    * The current status of the connection
    */
-  status: keyof typeof Status
+  status: ConnectionStatus
 
-  newStream: (multicodecs: string | string[], options?: NewStreamOptions) => Promise<Stream>
+  /**
+   * A transient connection is one that is not expected to be open for very long
+   * or one that cannot transfer very much data, such as one being used as a
+   * circuit relay connection. Protocols need to explicitly opt-in to being run
+   * over transient connections.
+   */
+  transient: boolean
+
+  /**
+   * 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')
@@ -203,7 +287,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
@@ -213,8 +296,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
 }
 
@@ -224,7 +319,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/errors.ts

@@ -1,4 +1,3 @@
-
 /**
  * When this error is thrown it means an operation was aborted,
  * usually in response to the `abort` event being emitted by an

package/src/index.ts

@@ -14,7 +14,7 @@
  * ```
  */
 
-import type { Connection, Stream } from './connection/index.js'
+import type { Connection, NewStreamOptions, Stream } from './connection/index.js'
 import type { ContentRouting } from './content-routing/index.js'
 import type { EventEmitter } from './events.js'
 import type { KeyChain } from './keychain/index.js'
@@ -503,10 +503,14 @@ export interface Libp2p<T extends ServiceMap = ServiceMap> extends Startable, Ev
    * pipe([1, 2, 3], stream, consume)
    * ```
    */
-  dialProtocol: (peer: PeerId | Multiaddr | Multiaddr[], protocols: string | string[], options?: AbortOptions) => Promise<Stream>
+  dialProtocol: (peer: PeerId | Multiaddr | Multiaddr[], protocols: string | string[], options?: NewStreamOptions) => 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/keys/index.ts

@@ -1,4 +1,3 @@
-
 export interface PublicKey {
   readonly bytes: Uint8Array
   verify: (data: Uint8Array, sig: Uint8Array) => Promise<boolean>

package/src/peer-store/tags.ts

@@ -1,2 +1 @@
-
 export const KEEP_ALIVE = 'keep-alive'

package/src/startable.ts

@@ -1,4 +1,3 @@
-
 /**
  * Implemented by components that have a lifecycle
  */

package/src/stream-handler/index.ts

@@ -19,6 +19,12 @@ export interface StreamHandlerOptions {
    * How many outgoing streams can be open for this protocol at the same time on each connection (default: 64)
    */
   maxOutboundStreams?: number
+
+  /**
+   * Opt-in to running over a transient connection - one that has time/data limits
+   * placed on it.
+   */
+  runOnTransientConnection?: boolean
 }
 
 export interface StreamHandlerRecord {

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
    */