@libp2p/floodsub 10.1.46 → 11.0.0-049bfa0fa

package/src/index.ts

@@ -32,138 +32,266 @@
  * ```
  */
 
-import { pubSubSymbol, serviceCapabilities, serviceDependencies } from '@libp2p/interface'
-import { PubSubBaseProtocol } from '@libp2p/pubsub'
-import { toString } from 'uint8arrays/to-string'
-import { SimpleTimeCache } from './cache.js'
-import { multicodec } from './config.js'
-import { RPC } from './message/rpc.js'
-import type { PeerId, PubSubInit, Message, PubSubRPC, PubSubRPCMessage, PublishResult, PubSub } from '@libp2p/interface'
-import type { PubSubComponents } from '@libp2p/pubsub'
-import type { Uint8ArrayList } from 'uint8arraylist'
-
-export { multicodec }
-
-export interface FloodSubInit extends PubSubInit {
-  seenTTL?: number
-}
+import { pubSubSymbol } from './constants.ts'
+import { FloodSub as FloodSubClass } from './floodsub.js'
+import type { ComponentLogger, PeerId, PrivateKey, PublicKey, TypedEventTarget } from '@libp2p/interface'
+import type { Registrar } from '@libp2p/interface-internal'
 
-export interface FloodSubComponents extends PubSubComponents {
+export const protocol = '/floodsub/1.0.0'
 
-}
+/**
+ * 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'
 
 /**
- * FloodSub (aka dumbsub is an implementation of pubsub focused on
- * delivering an API for Publish/Subscribe, but with no CastTree Forming
- * (it just floods the network).
+ * 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.
  */
-class FloodSub extends PubSubBaseProtocol {
-  public seenCache: SimpleTimeCache<boolean>
+export const StrictNoSign = 'StrictNoSign'
 
-  constructor (components: FloodSubComponents, init?: FloodSubInit) {
-    super(components, {
-      ...init,
-      canRelayMessage: true,
-      multicodecs: [multicodec]
-    })
+export type SignaturePolicy = typeof StrictSign | typeof StrictNoSign
 
-    this.log = components.logger.forComponent('libp2p:floodsub')
+export interface SignedMessage {
+  type: 'signed'
+  from: PeerId
+  topic: string
+  data: Uint8Array
+  sequenceNumber: bigint
+  signature: Uint8Array
+  key: PublicKey
+}
 
-    /**
-     * Cache of seen messages
-     *
-     * @type {TimeCache}
-     */
-    this.seenCache = new SimpleTimeCache<boolean>({
-      validityMs: init?.seenTTL ?? 30000
-    })
-  }
+export interface UnsignedMessage {
+  type: 'unsigned'
+  topic: string
+  data: Uint8Array
+}
 
-  readonly [pubSubSymbol] = true
+export type Message = SignedMessage | UnsignedMessage
 
-  readonly [Symbol.toStringTag] = '@libp2p/floodsub'
+export interface Subscription {
+  topic: string
+  subscribe: boolean
+}
 
-  readonly [serviceCapabilities]: string[] = [
-    '@libp2p/pubsub'
-  ]
+export interface SubscriptionChangeData {
+  peerId: PeerId
+  subscriptions: Subscription[]
+}
 
-  readonly [serviceDependencies]: string[] = [
-    '@libp2p/identify'
-  ]
+export interface FloodSubEvents {
+  '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',
   /**
-   * Decode a Uint8Array into an RPC object
+   * The message is considered invalid, and it should be rejected
    */
-  decodeRpc (bytes: Uint8Array | Uint8ArrayList): PubSubRPC {
-    return RPC.decode(bytes)
-  }
+  Reject = 'reject'
+}
+
+export interface TopicValidatorFn {
+  (peer: PeerId, message: Message): TopicValidatorResult | Promise<TopicValidatorResult>
+}
+
+export interface PeerStreamEvents {
+  'stream:inbound': CustomEvent<never>
+  'stream:outbound': CustomEvent<never>
+  close: CustomEvent<never>
+}
 
+export { pubSubSymbol }
+
+/**
+ * Returns true if the passed argument is a PubSub implementation
+ */
+export function isPubSub (obj?: any): obj is FloodSub {
+  return Boolean(obj?.[pubSubSymbol])
+}
+
+export interface FloodSub extends TypedEventTarget<FloodSubEvents> {
   /**
-   * Encode an RPC object into a Uint8Array
+   * 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.
    */
-  encodeRpc (rpc: PubSubRPC): Uint8Array {
-    return RPC.encode(rpc)
-  }
+  globalSignaturePolicy: typeof StrictSign | typeof StrictNoSign
 
-  decodeMessage (bytes: Uint8Array | Uint8ArrayList): PubSubRPCMessage {
-    return RPC.Message.decode(bytes)
-  }
+  /**
+   * A list of multicodecs that contain the pubsub protocol name.
+   */
+  protocols: string[]
 
-  encodeMessage (rpc: PubSubRPCMessage): Uint8Array {
-    return RPC.Message.encode(rpc)
-  }
+  /**
+   * 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[]
 
   /**
-   * Process incoming message
-   * Extends base implementation to check router cache.
+   * Gets a list of topics the node is subscribed to.
+   *
+   * ```TypeScript
+   * const topics = libp2p.pubsub.getTopics()
+   * ```
    */
-  async processMessage (from: PeerId, message: Message): Promise<void> {
-    // Check if I've seen the message, if yes, ignore
-    const seqno = await super.getMsgId(message)
-    const msgIdStr = toString(seqno, 'base64')
+  getTopics(): string[]
 
-    if (this.seenCache.has(msgIdStr)) {
-      return
-    }
+  /**
+   * 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
 
-    this.seenCache.put(msgIdStr, true)
+  /**
+   * 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
 
-    await super.processMessage(from, message)
-  }
+  /**
+   * Gets a list of the PeerIds that are subscribed to one topic.
+   *
+   * @example
+   *
+   * ```TypeScript
+   * const peerIds = libp2p.pubsub.getSubscribers(topic)
+   * ```
+   */
+  getSubscribers(topic: string): PeerId[]
 
   /**
-   * Publish message created. Forward it to the peers.
+   * Publishes messages to the given topic.
+   *
+   * @example
+   *
+   * ```TypeScript
+   * const topic = 'topic'
+   * const data = uint8ArrayFromString('data')
+   *
+   * await libp2p.pubsub.publish(topic, data)
+   * ```
    */
-  async publishMessage (from: PeerId, message: Message): Promise<PublishResult> {
-    const peers = this.getSubscribers(message.topic)
-    const recipients: PeerId[] = []
+  publish(topic: string, data?: Uint8Array): Promise<PublishResult>
+}
 
-    if (peers == null || peers.length === 0) {
-      this.log('no peers are subscribed to topic %s', message.topic)
-      return { recipients }
-    }
+export interface FloodSubComponents {
+  peerId: PeerId
+  privateKey: PrivateKey
+  registrar: Registrar
+  logger: ComponentLogger
+}
 
-    peers.forEach(id => {
-      if (this.components.peerId.equals(id)) {
-        this.log('not sending message on topic %s to myself', message.topic)
-        return
-      }
+export interface FloodSubInit {
+  seenTTL?: number
 
-      if (id.equals(from)) {
-        this.log('not sending message on topic %s to sender %p', message.topic, id)
-        return
-      }
+  /**
+   * Override the protocol registered with the registrar
+   *
+   * @default ['/floodsub/1.0.0']
+   */
+  protocols?: string[]
 
-      this.log('publish msgs on topics %s %p', message.topic, id)
+  /**
+   * 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
 
-      recipients.push(id)
-      this.send(id, { messages: [message] })
-    })
+  /**
+   * handle this many incoming pubsub messages concurrently
+   */
+  messageProcessingConcurrency?: number
 
-    return { recipients }
-  }
+  /**
+   * 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 function floodsub (init: FloodSubInit = {}): (components: FloodSubComponents) => PubSub {
-  return (components: FloodSubComponents) => new FloodSub(components, init)
+export function floodsub (init: FloodSubInit = {}): (components: FloodSubComponents) => FloodSub {
+  return (components: FloodSubComponents) => new FloodSubClass(components, init)
 }

package/src/peer-streams.ts

@@ -0,0 +1,200 @@
+import { AbortError } from '@libp2p/interface'
+import { pipe } from '@libp2p/utils'
+import * as lp from 'it-length-prefixed'
+import { pushable } from 'it-pushable'
+import { TypedEventEmitter } from 'main-event'
+import { pEvent } from 'p-event'
+import { Uint8ArrayList } from 'uint8arraylist'
+import type { PeerStreamEvents } from './index.ts'
+import type { ComponentLogger, Logger, Stream, PeerId } from '@libp2p/interface'
+import type { DecoderOptions as LpDecoderOptions } from 'it-length-prefixed'
+import type { Pushable } from 'it-pushable'
+
+export interface PeerStreamsInit {
+  id: PeerId
+  protocol: string
+}
+
+export interface PeerStreamsComponents {
+  logger: ComponentLogger
+}
+
+export interface DecoderOptions extends LpDecoderOptions {
+  // other custom options we might want for `attachInboundStream`
+}
+
+/**
+ * Thin wrapper around a peer's inbound / outbound pubsub streams
+ */
+export class PeerStreams extends TypedEventEmitter<PeerStreamEvents> {
+  public readonly id: PeerId
+  public readonly protocol: string
+  /**
+   * Write stream - it's preferable to use the write method
+   */
+  public outboundStream?: Pushable<Uint8ArrayList>
+  /**
+   * Read stream
+   */
+  public inboundStream?: AsyncIterable<Uint8ArrayList>
+  /**
+   * The raw outbound stream, as retrieved from conn.newStream
+   */
+  private _rawOutboundStream?: Stream
+  /**
+   * The raw inbound stream, as retrieved from the callback from libp2p.handle
+   */
+  private _rawInboundStream?: Stream
+  /**
+   * An AbortController for controlled shutdown of the inbound stream
+   */
+  private readonly _inboundAbortController: AbortController
+  private closed: boolean
+  private readonly log: Logger
+
+  constructor (components: PeerStreamsComponents, init: PeerStreamsInit) {
+    super()
+
+    this.log = components.logger.forComponent('libp2p-pubsub:peer-streams')
+    this.id = init.id
+    this.protocol = init.protocol
+
+    this._inboundAbortController = new AbortController()
+    this.closed = false
+  }
+
+  /**
+   * Do we have a connection to read from?
+   */
+  get isReadable (): boolean {
+    return Boolean(this.inboundStream)
+  }
+
+  /**
+   * Do we have a connection to write on?
+   */
+  get isWritable (): boolean {
+    return Boolean(this.outboundStream)
+  }
+
+  /**
+   * Send a message to this peer.
+   * Throws if there is no `stream` to write to available.
+   */
+  write (data: Uint8Array | Uint8ArrayList): void {
+    if (this.outboundStream == null) {
+      const id = this.id.toString()
+      throw new Error('No writable connection to ' + id)
+    }
+
+    this.outboundStream.push(data instanceof Uint8Array ? new Uint8ArrayList(data) : data)
+  }
+
+  /**
+   * Attach a raw inbound stream and setup a read stream
+   */
+  attachInboundStream (stream: Stream, decoderOptions?: DecoderOptions): AsyncIterable<Uint8ArrayList> {
+    const abortListener = (): void => {
+      stream.abort(new AbortError())
+    }
+
+    this._inboundAbortController.signal.addEventListener('abort', abortListener, {
+      once: true
+    })
+
+    // Create and attach a new inbound stream
+    // The inbound stream is:
+    // - abortable, set to only return on abort, rather than throw
+    // - transformed with length-prefix transform
+    this._rawInboundStream = stream
+    this.inboundStream = pipe(
+      this._rawInboundStream,
+      (source) => lp.decode(source, decoderOptions)
+    )
+
+    this.dispatchEvent(new CustomEvent('stream:inbound'))
+    return this.inboundStream
+  }
+
+  /**
+   * Attach a raw outbound stream and setup a write stream
+   */
+  async attachOutboundStream (stream: Stream): Promise<Pushable<Uint8ArrayList>> {
+    // If an outbound stream already exists, gently close it
+    const _prevStream = this.outboundStream
+    if (this.outboundStream != null) {
+      // End the stream without emitting a close event
+      this.outboundStream.end()
+    }
+
+    this._rawOutboundStream = stream
+    this.outboundStream = pushable<Uint8ArrayList>({
+      onEnd: (shouldEmit) => {
+        // close writable side of the stream if it exists
+        this._rawOutboundStream?.close()
+          .catch(err => {
+            this.log('error closing outbound stream', err)
+          })
+
+        this._rawOutboundStream = undefined
+        this.outboundStream = undefined
+        if (shouldEmit != null) {
+          this.dispatchEvent(new CustomEvent('close'))
+        }
+      }
+    })
+
+    pipe(
+      this.outboundStream,
+      (source) => lp.encode(source),
+      async (source) => {
+        for await (const buf of source) {
+          const sendMore = stream.send(buf)
+
+          if (sendMore === false) {
+            await pEvent(stream, 'drain', {
+              rejectionEvents: [
+                'close'
+              ]
+            })
+          }
+        }
+      }
+    ).catch((err: Error) => {
+      this.log.error(err)
+    })
+
+    // Only emit if the connection is new
+    if (_prevStream == null) {
+      this.dispatchEvent(new CustomEvent('stream:outbound'))
+    }
+
+    return this.outboundStream
+  }
+
+  /**
+   * Closes the open connection to peer
+   */
+  close (): void {
+    if (this.closed) {
+      return
+    }
+
+    this.closed = true
+
+    // End the outbound stream
+    if (this.outboundStream != null) {
+      this.outboundStream.end()
+    }
+    // End the inbound stream
+    if (this.inboundStream != null) {
+      this._inboundAbortController.abort()
+    }
+
+    this._rawOutboundStream = undefined
+    this.outboundStream = undefined
+    this._rawInboundStream = undefined
+    this.inboundStream = undefined
+    this.dispatchEvent(new CustomEvent('close'))
+  }
+}

package/src/sign.ts

@@ -0,0 +1,93 @@
+import { peerIdFromPrivateKey } from '@libp2p/peer-id'
+import { concat as uint8ArrayConcat } from 'uint8arrays/concat'
+import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
+import { toRpcMessage } from './utils.js'
+import type { PubSubRPCMessage } from './floodsub.ts'
+import type { SignedMessage } from './index.ts'
+import type { PeerId, PrivateKey, PublicKey } from '@libp2p/interface'
+
+export const SignPrefix = uint8ArrayFromString('libp2p-pubsub:')
+
+/**
+ * Signs the provided message with the given `peerId`
+ */
+export async function signMessage (privateKey: PrivateKey, message: { from: PeerId, topic: string, data: Uint8Array, sequenceNumber: bigint }, encode: (rpc: PubSubRPCMessage) => Uint8Array): Promise<SignedMessage> {
+  // @ts-expect-error signature field is missing, added below
+  const outputMessage: SignedMessage = {
+    type: 'signed',
+    topic: message.topic,
+    data: message.data,
+    sequenceNumber: message.sequenceNumber,
+    from: peerIdFromPrivateKey(privateKey)
+  }
+
+  // Get the message in bytes, and prepend with the pubsub prefix
+  const bytes = uint8ArrayConcat([
+    SignPrefix,
+    encode(toRpcMessage(outputMessage)).subarray()
+  ])
+
+  outputMessage.signature = await privateKey.sign(bytes)
+  outputMessage.key = privateKey.publicKey
+
+  return outputMessage
+}
+
+/**
+ * Verifies the signature of the given message
+ */
+export async function verifySignature (message: SignedMessage, encode: (rpc: PubSubRPCMessage) => Uint8Array): Promise<boolean> {
+  if (message.type !== 'signed') {
+    throw new Error('Message type must be "signed" to be verified')
+  }
+
+  if (message.signature == null) {
+    throw new Error('Message must contain a signature to be verified')
+  }
+
+  if (message.from == null) {
+    throw new Error('Message must contain a from property to be verified')
+  }
+
+  // Get message sans the signature
+  const bytes = uint8ArrayConcat([
+    SignPrefix,
+    encode({
+      ...toRpcMessage(message),
+      signature: undefined,
+      key: undefined
+    }).subarray()
+  ])
+
+  // Get the public key
+  const pubKey = messagePublicKey(message)
+
+  // verify the base message
+  return pubKey.verify(bytes, message.signature)
+}
+
+/**
+ * Returns the PublicKey associated with the given message.
+ * If no valid PublicKey can be retrieved an error will be returned.
+ */
+export function messagePublicKey (message: SignedMessage): PublicKey {
+  if (message.type !== 'signed') {
+    throw new Error('Message type must be "signed" to have a public key')
+  }
+
+  // should be available in the from property of the message (peer id)
+  if (message.from == null) {
+    throw new Error('Could not get the public key from the originator id')
+  }
+
+  if (message.key != null) {
+    return message.key
+  }
+
+  if (message.from.publicKey != null) {
+    return message.from.publicKey
+  }
+
+  // We couldn't validate pubkey is from the originator, error
+  throw new Error('Could not get the public key from the originator id')
+}