@libp2p/interface 0.0.1 → 0.1.0

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.
    */
-  reset: () => void
+  id: string
 
   /**
-   * Unique identifier for a stream. Identifiers are not unique across muxers.
+   * Outbound streams are opened by the local node, inbound streams are opened by the remote
    */
-  id: string
+  direction: Direction
+
+  /**
+   * Lifecycle times for the stream
+   */
+  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 {
@@ -165,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
@@ -174,17 +195,89 @@ 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
+
+  /**
+   * 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')
@@ -194,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
@@ -204,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
 }
 
@@ -215,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/pubsub/index.ts

@@ -0,0 +1,269 @@
+import type { Stream } from '../connection/index.js'
+import type { EventEmitter } from '../events.js'
+import type { PeerId } from '../peer-id/index.js'
+import type { Pushable } from 'it-pushable'
+import type { Uint8ArrayList } from 'uint8arraylist'
+
+/**
+ * On the producing side:
+ * * Build messages with the signature, key (from may be enough for certain inlineable public key types), from and seqno fields.
+ *
+ * On the consuming side:
+ * * Enforce the fields to be present, reject otherwise.
+ * * Propagate only if the fields are valid and signature can be verified, reject otherwise.
+ */
+export const StrictSign = 'StrictSign'
+
+/**
+ * On the producing side:
+ * * Build messages without the signature, key, from and seqno fields.
+ * * The corresponding protobuf key-value pairs are absent from the marshalled message, not just empty.
+ *
+ * On the consuming side:
+ * * Enforce the fields to be absent, reject otherwise.
+ * * Propagate only if the fields are absent, reject otherwise.
+ * * A message_id function will not be able to use the above fields, and should instead rely on the data field. A commonplace strategy is to calculate a hash.
+ */
+export const StrictNoSign = 'StrictNoSign'
+
+export type SignaturePolicy = typeof StrictSign | typeof StrictNoSign
+
+export interface SignedMessage {
+  type: 'signed'
+  from: PeerId
+  topic: string
+  data: Uint8Array
+  sequenceNumber: bigint
+  signature: Uint8Array
+  key: Uint8Array
+}
+
+export interface UnsignedMessage {
+  type: 'unsigned'
+  topic: string
+  data: Uint8Array
+}
+
+export type Message = SignedMessage | UnsignedMessage
+
+export interface PubSubRPCMessage {
+  from?: Uint8Array
+  topic?: string
+  data?: Uint8Array
+  sequenceNumber?: Uint8Array
+  signature?: Uint8Array
+  key?: Uint8Array
+}
+
+export interface PubSubRPCSubscription {
+  subscribe?: boolean
+  topic?: string
+}
+
+export interface PubSubRPC {
+  subscriptions: PubSubRPCSubscription[]
+  messages: PubSubRPCMessage[]
+}
+
+export interface PeerStreams extends EventEmitter<PeerStreamEvents> {
+  id: PeerId
+  protocol: string
+  outboundStream?: Pushable<Uint8ArrayList>
+  inboundStream?: AsyncIterable<Uint8ArrayList>
+  isWritable: boolean
+
+  close: () => void
+  write: (buf: Uint8Array | Uint8ArrayList) => void
+  attachInboundStream: (stream: Stream) => AsyncIterable<Uint8ArrayList>
+  attachOutboundStream: (stream: Stream) => Promise<Pushable<Uint8ArrayList>>
+}
+
+export interface PubSubInit {
+  enabled?: boolean
+
+  multicodecs?: string[]
+
+  /**
+   * defines how signatures should be handled
+   */
+  globalSignaturePolicy?: SignaturePolicy
+
+  /**
+   * if can relay messages not subscribed
+   */
+  canRelayMessage?: boolean
+
+  /**
+   * if publish should emit to self, if subscribed
+   */
+  emitSelf?: boolean
+
+  /**
+   * handle this many incoming pubsub messages concurrently
+   */
+  messageProcessingConcurrency?: number
+
+  /**
+   * How many parallel incoming streams to allow on the pubsub protocol per-connection
+   */
+  maxInboundStreams?: number
+
+  /**
+   * How many parallel outgoing streams to allow on the pubsub protocol per-connection
+   */
+  maxOutboundStreams?: number
+}
+
+interface Subscription {
+  topic: string
+  subscribe: boolean
+}
+
+export interface SubscriptionChangeData {
+  peerId: PeerId
+  subscriptions: Subscription[]
+}
+
+export interface PubSubEvents {
+  'subscription-change': CustomEvent<SubscriptionChangeData>
+  'message': CustomEvent<Message>
+}
+
+export interface PublishResult {
+  recipients: PeerId[]
+}
+
+export enum TopicValidatorResult {
+  /**
+   * The message is considered valid, and it should be delivered and forwarded to the network
+   */
+  Accept = 'accept',
+  /**
+   * The message is neither delivered nor forwarded to the network
+   */
+  Ignore = 'ignore',
+  /**
+   * The message is considered invalid, and it should be rejected
+   */
+  Reject = 'reject'
+}
+
+export interface TopicValidatorFn {
+  (peer: PeerId, message: Message): TopicValidatorResult | Promise<TopicValidatorResult>
+}
+
+export interface PubSub<Events extends Record<string, any> = PubSubEvents> extends EventEmitter<Events> {
+  /**
+   * The global signature policy controls whether or not we sill send and receive
+   * signed or unsigned messages.
+   *
+   * Signed messages prevent spoofing message senders and should be preferred to
+   * using unsigned messages.
+   */
+  globalSignaturePolicy: typeof StrictSign | typeof StrictNoSign
+
+  /**
+   * A list of multicodecs that contain the pubsub protocol name.
+   */
+  multicodecs: string[]
+
+  /**
+   * Pubsub routers support message validators per topic, which will validate the message
+   * before its propagations. They are stored in a map where keys are the topic name and
+   * values are the validators.
+   *
+   * @example
+   *
+   * ```js
+   * const topic = 'topic'
+   * const validateMessage = (msgTopic, msg) => {
+   *   const input = uint8ArrayToString(msg.data)
+   *   const validInputs = ['a', 'b', 'c']
+   *
+   *   if (!validInputs.includes(input)) {
+   *     throw new Error('no valid input received')
+   *   }
+   * }
+   * libp2p.pubsub.topicValidators.set(topic, validateMessage)
+   * ```
+   */
+  topicValidators: Map<string, TopicValidatorFn>
+
+  getPeers: () => PeerId[]
+
+  /**
+   * Gets a list of topics the node is subscribed to.
+   *
+   * ```js
+   * const topics = libp2p.pubsub.getTopics()
+   * ```
+   */
+  getTopics: () => string[]
+
+  /**
+   * Subscribes to a pubsub topic.
+   *
+   * @example
+   *
+   * ```js
+   * const topic = 'topic'
+   * const handler = (msg) => {
+   *   if (msg.topic === topic) {
+   *     // msg.data - pubsub data received
+   *   }
+   * }
+   *
+   * libp2p.pubsub.addEventListener('message', handler)
+   * libp2p.pubsub.subscribe(topic)
+   * ```
+   */
+  subscribe: (topic: string) => void
+
+  /**
+   * Unsubscribes from a pubsub topic.
+   *
+   * @example
+   *
+   * ```js
+   * const topic = 'topic'
+   * const handler = (msg) => {
+   *   // msg.data - pubsub data received
+   * }
+   *
+   * libp2p.pubsub.removeEventListener(topic handler)
+   * libp2p.pubsub.unsubscribe(topic)
+   * ```
+   */
+  unsubscribe: (topic: string) => void
+
+  /**
+   * Gets a list of the PeerIds that are subscribed to one topic.
+   *
+   * @example
+   *
+   * ```js
+   * const peerIds = libp2p.pubsub.getSubscribers(topic)
+   * ```
+   */
+  getSubscribers: (topic: string) => PeerId[]
+
+  /**
+   * Publishes messages to the given topic.
+   *
+   * @example
+   *
+   * ```js
+   * const topic = 'topic'
+   * const data = uint8ArrayFromString('data')
+   *
+   * await libp2p.pubsub.publish(topic, data)
+   * ```
+   */
+  publish: (topic: string, data: Uint8Array) => Promise<PublishResult>
+}
+
+export interface PeerStreamEvents {
+  'stream:inbound': CustomEvent<never>
+  'stream:outbound': CustomEvent<never>
+  'close': CustomEvent<never>
+}

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 {