@libp2p/interface 2.11.0-6059227cb → 2.11.0-8484de8a2

package/dist/src/topology.d.ts

@@ -4,7 +4,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libp2p/interface",
-  "version": "2.11.0-6059227cb",
+  "version": "2.11.0-8484de8a2",
   "description": "The interface implemented by a libp2p node",
   "license": "Apache-2.0 OR MIT",
   "homepage": "https://github.com/libp2p/js-libp2p/tree/main/packages/interface#readme",
@@ -43,13 +43,14 @@
   "dependencies": {
     "@multiformats/dns": "^1.0.6",
     "@multiformats/multiaddr": "^13.0.1",
+    "it-pushable": "^3.2.3",
     "main-event": "^1.0.1",
     "multiformats": "^13.4.0",
     "progress-events": "^1.0.1",
     "uint8arraylist": "^2.4.8"
   },
   "devDependencies": {
-    "aegir": "^47.0.22"
+    "aegir": "^47.0.21"
   },
   "sideEffects": false
 }

package/src/errors.ts

@@ -132,6 +132,34 @@ 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
  */

package/src/index.ts

@@ -23,7 +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 { 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'
@@ -781,33 +781,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
@@ -956,6 +929,7 @@ 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'

package/src/message-stream.ts

@@ -100,25 +100,10 @@ export interface MessageStream<Timeline extends MessageStreamTimeline = MessageS
   /**
    * The maximum number of bytes to store when paused. If receipt of more bytes
    * from the remote end of the stream causes the buffer size to exceed this
-   * value the stream will be reset and a 'close' event emitted.
-   *
-   * This value can be changed at runtime.
+   * value the stream will be reset and an 'error' event emitted.
    */
   maxReadBufferLength: number
 
-  /**
-   * When the `.send` method returns false it means that the underlying resource
-   * has signalled that it's write buffer is full. If the user continues to call
-   * `.send`, outgoing bytes are stored in an internal buffer until the
-   * underlying resource signals that it can accept more data.
-   *
-   * If the size of that internal buffer exceed this value the stream will be
-   * reset and a 'close' event emitted.
-   *
-   * This value can be changed at runtime.
-   */
-  maxWriteBufferLength?: number
-
   /**
    * If no data is transmitted over the stream in this many ms, the stream will
    * be aborted with an InactivityTimeoutError

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,284 @@
+import type { Stream, PublicKey, PeerId } from './index.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

@@ -7,13 +7,6 @@ export interface StreamHandler {
   (stream: Stream, connection: Connection): void | Promise<void>
 }
 
-/**
- * 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 StreamHandlerOptions extends AbortOptions {
   /**
    * How many incoming streams can be open for this protocol at the same time on each connection
@@ -40,11 +33,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

@@ -142,7 +142,7 @@ export interface StreamMuxer<MuxedStream extends Stream = Stream> extends TypedE
   /**
    * Create a new stream
    */
-  createStream(options?: CreateStreamOptions): Promise<MuxedStream>
+  createStream(options?: CreateStreamOptions): MuxedStream | Promise<MuxedStream>
 
   /**
    * Immediately close the muxer, abort every open stream and discard any

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