@libp2p/interface 2.11.0-6059227cb → 2.11.0-87bc8d4fb

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'
@@ -23,8 +23,7 @@ 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, StreamMiddleware } from './stream-handler.js'
-import type { Stream } from './stream.js'
+import type { StreamHandler, StreamHandlerOptions } from './stream-handler.js'
 import type { Topology } from './topology.js'
 import type { Listener, OutboundConnectionUpgradeEvents } from './transport.js'
 import type { DNS } from '@multiformats/dns'
@@ -781,33 +780,6 @@ 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
@@ -943,25 +915,20 @@ 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'

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/peer-store.ts

@@ -314,4 +314,9 @@ export interface PeerStore {
    * ```
    */
   consumePeerRecord(buf: Uint8Array, options?: ConsumePeerRecordOptions): Promise<boolean>
+
+  /**
+   * @deprecated Pass `expectedPeer` as a property of `options` instead
+   */
+  consumePeerRecord(buf: Uint8Array, expectedPeer?: PeerId, options?: AbortOptions): Promise<boolean>
 }

package/src/pubsub.ts

@@ -0,0 +1,286 @@
+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'
+
+/**
+ * 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 marshaled 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: PublicKey
+}
+
+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 TypedEventTarget<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
+}
+
+export 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>
+}
+
+/**
+ * @deprecated This will be removed from `@libp2p/interface` in a future release, pubsub implementations should declare their own types
+ */
+export interface PubSub<Events extends Record<string, any> = PubSubEvents> extends TypedEventTarget<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
+   *
+   * ```TypeScript
+   * 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.
+   *
+   * ```TypeScript
+   * const topics = libp2p.pubsub.getTopics()
+   * ```
+   */
+  getTopics(): string[]
+
+  /**
+   * Subscribes to a pubsub topic.
+   *
+   * @example
+   *
+   * ```TypeScript
+   * 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
+   *
+   * ```TypeScript
+   * 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
+   *
+   * ```TypeScript
+   * const peerIds = libp2p.pubsub.getSubscribers(topic)
+   * ```
+   */
+  getSubscribers(topic: string): PeerId[]
+
+  /**
+   * Publishes messages to the given topic.
+   *
+   * @example
+   *
+   * ```TypeScript
+   * 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>
+}
+
+/**
+ * All Pubsub implementations must use this symbol as the name of a property
+ * with a boolean `true` value
+ */
+export const pubSubSymbol = Symbol.for('@libp2p/pubsub')
+
+/**
+ * Returns true if the passed argument is a PubSub implementation
+ */
+export function isPubSub (obj?: any): obj is PubSub {
+  return Boolean(obj?.[pubSubSymbol])
+}

package/src/stream-handler.ts

@@ -1,17 +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 StreamHandler {
+export interface IncomingStreamData {
   /**
-   * A callback function that accepts the incoming stream data
+   * The newly opened stream
+   */
+  stream: Stream
+
+  /**
+   * The connection the stream was opened on
    */
-  (stream: Stream, connection: Connection): void | Promise<void>
+  connection: Connection
 }
 
-/**
- * Stream middleware allows accessing stream data outside of the stream handler
- */
-export interface StreamMiddleware {
-  (stream: Stream, connection: Connection, next: (stream: Stream, connection: Connection) => void): void | Promise<void>
+export interface StreamHandler {
+  /**
+   * A callback function that accepts the incoming stream data
+   */
+  (data: IncomingStreamData): void | Promise<void>
 }
 
 export interface StreamHandlerOptions extends AbortOptions {
@@ -40,11 +46,6 @@ export interface StreamHandlerOptions extends AbortOptions {
    * protocol(s), the existing handler will be discarded.
    */
   force?: true
-
-  /**
-   * Middleware allows accessing stream data outside of the stream handler
-   */
-  middleware?: StreamMiddleware[]
 }
 
 export interface StreamHandlerRecord {

package/src/stream-muxer.ts

@@ -1,160 +1,68 @@
-import type { Stream, TypedEventTarget, MessageStream, AbortOptions } from './index.js'
-
-/**
- * User-facing message stream muxer options
- */
-export interface StreamMuxerOptions<MuxedStreamOptions extends StreamOptions = StreamOptions> {
-  /**
-   * Configuration options for each outgoing/incoming stream
-   */
-  streamOptions?: MuxedStreamOptions
-
-  /**
-   * libp2p is notified of incoming streams via the muxer's 'stream' event.
-   *
-   * During connection establishment there may be a small window where a muxer
-   * starts to process incoming stream data before a listener has been added for
-   * the 'stream' event.
-   *
-   * If no handler is registered for this event incoming streams can be missed
-   * so when this is the case muxers queue streams internally as "early
-   * streams", and will defer emitting the 'stream' event until after a listener
-   * has been registered.
-   *
-   * Allowing an unlimited amount of early streams can cause excessive memory
-   * consumption so this setting controls how many early streams to store when
-   * no 'stream' listener has been registered.
-   *
-   * If more streams than this are opened before a listener is added the muxed
-   * connection will be reset.
-   *
-   * @default 10
-   */
-  maxEarlyStreams?: number
-
-  /**
-   * Maximum size of a message in bytes that we'll send on a stream - this
-   * ensures that a single stream doesn't hog a connection
-   *
-   * @default 65_536
-   */
-  maxMessageSize?: number
+import type { Direction, Stream } from './connection.js'
+import type { AbortOptions, Logger } from './index.js'
+import type { Duplex } from 'it-stream-types'
+import type { Uint8ArrayList } from 'uint8arraylist'
 
+export interface StreamMuxerFactory {
   /**
-   * Maximum number of concurrent inbound streams that we accept - if the peer
-   * tries to open more streams, those will be reset immediately
-   *
-   * @default 1_000
+   * The protocol used to select this muxer during connection opening
    */
-  maxInboundStreams?: number
+  protocol: string
 
   /**
-   * Maximum number of concurrent outbound streams that we accept - if the
-   * application tries to open more streams, the call to `newStream` will throw
-   *
-   * @default 1_000
+   * Creates a new stream muxer to be used with a new connection
    */
-  maxOutboundStreams?: number
+  createStreamMuxer(init?: StreamMuxerInit): StreamMuxer
 }
 
 /**
- * User-facing message stream options
+ * A libp2p stream muxer
  */
-export interface StreamOptions {
-  /**
-   * If no data is sent or received in this number of ms the stream will be
-   * reset and an 'error' event emitted.
-   *
-   * @default 120_000
-   */
-  inactivityTimeout?: number
-
-  /**
-   * The maximum number of bytes to store when paused or before a 'message'
-   * event handler is added.
-   *
-   * If the internal buffer overflows this value the stream will be reset.
-   *
-   * @default 4_194_304
-   */
-  maxReadBufferLength?: number
-
-  /**
-   * The maximum number of bytes to store when the remote end of the stream is
-   * applying backpressure, or when it is slow to accept new bytes.
-   *
-   * If the internal buffer overflows this value the stream will be reset.
-   *
-   * @default Infinity
-   */
-  maxWriteBufferLength?: number
-}
-
-export interface StreamMuxerFactory<Muxer extends StreamMuxer = StreamMuxer> {
+export interface StreamMuxer extends Duplex<AsyncGenerator<Uint8Array | Uint8ArrayList>> {
   /**
    * The protocol used to select this muxer during connection opening
    */
   protocol: string
 
   /**
-   * Creates a new stream muxer to be used with a new connection
-   */
-  createStreamMuxer(maConn: MessageStream): Muxer
-}
-
-export interface StreamMuxerEvents<MuxedStream extends Stream = Stream> {
-  /**
-   * An incoming stream was created
+   * A list of streams that are currently open. Closed streams will not be returned.
    */
-  stream: CustomEvent<MuxedStream>
-}
-
-export interface CreateStreamOptions extends AbortOptions, StreamOptions {
+  readonly streams: Stream[]
   /**
-   * If a single protocol was requested and the muxer has support for this,
-   * pre-negotiate the protocol using this value, otherwise multistream-select
-   * will be run over the stream after opening.
+   * Initiate a new stream with the given name. If no name is
+   * provided, the id of the stream will be used.
    */
-  protocol?: string
-}
+  newStream(name?: string): Stream | Promise<Stream>
 
-export type StreamMuxerStatus = 'open' | 'closing' | 'closed'
-
-/**
- * A libp2p stream muxer
- */
-export interface StreamMuxer<MuxedStream extends Stream = Stream> extends TypedEventTarget<StreamMuxerEvents<MuxedStream>> {
   /**
-   * The protocol used to select this muxer during connection opening
+   * Close or abort all tracked streams and stop the muxer
    */
-  protocol: string
+  close(options?: AbortOptions): Promise<void>
 
   /**
-   * A list of streams that are currently open
+   * Close or abort all tracked streams and stop the muxer
    */
-  streams: MuxedStream[]
+  abort(err: Error): void
+}
 
+export interface StreamMuxerInit {
   /**
-   * The status of the muxer
+   * A callback function invoked every time an incoming stream is opened
    */
-  status: StreamMuxerStatus
+  onIncomingStream?(stream: Stream): void
 
   /**
-   * Create a new stream
+   * A callback function invoke every time a stream ends
    */
-  createStream(options?: CreateStreamOptions): Promise<MuxedStream>
+  onStreamEnd?(stream: Stream): void
 
   /**
-   * Immediately close the muxer, abort every open stream and discard any
-   * unsent/unread data.
+   * Outbound stream muxers are opened by the local node, inbound stream muxers are opened by the remote
    */
-  abort (err: Error): void
+  direction?: Direction
 
   /**
-   * Gracefully close the muxer. All open streams will be gracefully closed, and
-   * the returned promise will either resolve when any/all unsent data has been
-   * sent, or it will reject if the passed abort signal fires before this
-   * happens.
+   * The logger used by the connection
    */
-  close (options?: AbortOptions): Promise<void>
+  log?: Logger
 }

package/src/topology.ts

@@ -5,7 +5,7 @@ import type { PeerId } from './peer-id.js'
  * A topology filter - this can be used by topologies to ensure they do not
  * receive duplicate notifications of individual peers
  *
- * @see https://libp2p.github.io/js-libp2p/classes/_libp2p_peer-collections.PeerFilter.html
+ * @see https://libp2p.github.io/js-libp2p/functions/_libp2p_peer_collections.peerFilter-1.html
  */
 export interface TopologyFilter {
   has (peerId: PeerId): boolean
@@ -40,11 +40,11 @@ export interface Topology {
    * Invoked when a new connection is opened to a peer that supports the
    * registered protocol
    */
-  onConnect?(peerId: PeerId, conn: Connection): void | Promise<void>
+  onConnect?(peerId: PeerId, conn: Connection): void
 
   /**
    * Invoked when the last connection to a peer that supports the registered
    * protocol closes
    */
-  onDisconnect?(peerId: PeerId): void | Promise<void>
+  onDisconnect?(peerId: PeerId): void
 }