@libp2p/pubsub
Version:
libp2p pubsub base class
217 lines • 7.45 kB
TypeScript
/**
* @packageDocumentation
*
* A set of components to be extended in order to create a pubsub implementation.
*
* @example
*
* ```TypeScript
* import { PubSubBaseProtocol } from '@libp2p/pubsub'
* import type { PubSubRPC, PublishResult, PubSubRPCMessage, PeerId, Message } from '@libp2p/interface'
* import type { Uint8ArrayList } from 'uint8arraylist'
*
* class MyPubsubImplementation extends PubSubBaseProtocol {
* decodeRpc (bytes: Uint8Array | Uint8ArrayList): PubSubRPC {
* throw new Error('Not implemented')
* }
*
* encodeRpc (rpc: PubSubRPC): Uint8Array {
* throw new Error('Not implemented')
* }
*
* encodeMessage (rpc: PubSubRPCMessage): Uint8Array {
* throw new Error('Not implemented')
* }
*
* async publishMessage (sender: PeerId, message: Message): Promise<PublishResult> {
* throw new Error('Not implemented')
* }
* }
* ```
*/
import { PeerMap, PeerSet } from '@libp2p/peer-collections';
import { TypedEventEmitter } from 'main-event';
import Queue from 'p-queue';
import type { PubSub, Message, StrictNoSign, StrictSign, PubSubInit, PubSubEvents, PeerStreams, PubSubRPCMessage, PubSubRPC, PubSubRPCSubscription, PublishResult, TopicValidatorFn, ComponentLogger, Logger, Connection, PeerId, PrivateKey, IncomingStreamData } from '@libp2p/interface';
import type { Registrar } from '@libp2p/interface-internal';
import type { Uint8ArrayList } from 'uint8arraylist';
export interface PubSubComponents {
peerId: PeerId;
privateKey: PrivateKey;
registrar: Registrar;
logger: ComponentLogger;
}
/**
* PubSubBaseProtocol handles the peers and connections logic for pubsub routers
* and specifies the API that pubsub routers should have.
*/
export declare abstract class PubSubBaseProtocol<Events extends Record<string, any> = PubSubEvents> extends TypedEventEmitter<Events> implements PubSub<Events> {
protected log: Logger;
started: boolean;
/**
* Map of topics to which peers are subscribed to
*/
topics: Map<string, PeerSet>;
/**
* List of our subscriptions
*/
subscriptions: Set<string>;
/**
* Map of peer streams
*/
peers: PeerMap<PeerStreams>;
/**
* The signature policy to follow by default
*/
globalSignaturePolicy: typeof StrictNoSign | typeof StrictSign;
/**
* If router can relay received messages, even if not subscribed
*/
canRelayMessage: boolean;
/**
* if publish should emit to self, if subscribed
*/
emitSelf: boolean;
/**
* Topic validator map
*
* Keyed by topic
* Topic validators are functions with the following input:
*/
topicValidators: Map<string, TopicValidatorFn>;
queue: Queue;
multicodecs: string[];
components: PubSubComponents;
private _registrarTopologyIds;
protected enabled: boolean;
private readonly maxInboundStreams;
private readonly maxOutboundStreams;
constructor(components: PubSubComponents, props: PubSubInit);
/**
* Register the pubsub protocol onto the libp2p node.
*/
start(): Promise<void>;
/**
* Unregister the pubsub protocol and the streams with other peers will be closed.
*/
stop(): Promise<void>;
isStarted(): boolean;
/**
* On an inbound stream opened
*/
protected _onIncomingStream(data: IncomingStreamData): void;
/**
* Registrar notifies an established connection with pubsub protocol
*/
protected _onPeerConnected(peerId: PeerId, conn: Connection): void;
/**
* Registrar notifies a closing connection with pubsub protocol
*/
protected _onPeerDisconnected(peerId: PeerId, conn?: Connection): void;
/**
* Notifies the router that a peer has been connected
*/
addPeer(peerId: PeerId, protocol: string): PeerStreams;
/**
* Notifies the router that a peer has been disconnected
*/
protected _removePeer(peerId: PeerId): PeerStreams | undefined;
/**
* Responsible for processing each RPC message received by other peers.
*/
processMessages(peerId: PeerId, stream: AsyncIterable<Uint8ArrayList>, peerStreams: PeerStreams): Promise<void>;
/**
* Handles an rpc request from a peer
*/
processRpc(from: PeerId, peerStreams: PeerStreams, rpc: PubSubRPC): Promise<boolean>;
/**
* Handles a subscription change from a peer
*/
processRpcSubOpt(id: PeerId, subOpt: PubSubRPCSubscription): void;
/**
* Handles a message from a peer
*/
processMessage(from: PeerId, msg: Message): Promise<void>;
/**
* The default msgID implementation
* Child class can override this.
*/
getMsgId(msg: Message): Promise<Uint8Array> | Uint8Array;
/**
* Whether to accept a message from a peer
* Override to create a gray list
*/
acceptFrom(id: PeerId): boolean;
/**
* Decode Uint8Array into an RPC object.
* This can be override to use a custom router protobuf.
*/
abstract decodeRpc(bytes: Uint8Array | Uint8ArrayList): PubSubRPC;
/**
* Encode RPC object into a Uint8Array.
* This can be override to use a custom router protobuf.
*/
abstract encodeRpc(rpc: PubSubRPC): Uint8Array;
/**
* Encode RPC object into a Uint8Array.
* This can be override to use a custom router protobuf.
*/
abstract encodeMessage(rpc: PubSubRPCMessage): Uint8Array;
/**
* Send an rpc object to a peer
*/
send(peer: PeerId, data: {
messages?: Message[];
subscriptions?: string[];
subscribe?: boolean;
}): void;
/**
* Send an rpc object to a peer
*/
sendRpc(peer: PeerId, rpc: PubSubRPC): void;
/**
* Validates the given message. The signature will be checked for authenticity.
* Throws an error on invalid messages
*/
validate(from: PeerId, message: Message): Promise<void>;
/**
* Normalizes the message and signs it, if signing is enabled.
* Should be used by the routers to create the message to send.
*/
buildMessage(message: {
from: PeerId;
topic: string;
data: Uint8Array;
sequenceNumber: bigint;
}): Promise<Message>;
/**
* Get a list of the peer-ids that are subscribed to one topic.
*/
getSubscribers(topic: string): PeerId[];
/**
* Publishes messages to all subscribed peers
*/
publish(topic: string, data?: Uint8Array): Promise<PublishResult>;
/**
* Overriding the implementation of publish should handle the appropriate algorithms for the publish/subscriber implementation.
* For example, a Floodsub implementation might simply publish each message to each topic for every peer.
*
* `sender` might be this peer, or we might be forwarding a message on behalf of another peer, in which case sender
* is the peer we received the message from, which may not be the peer the message was created by.
*/
abstract publishMessage(sender: PeerId, message: Message): Promise<PublishResult>;
/**
* Subscribes to a given topic.
*/
subscribe(topic: string): void;
/**
* Unsubscribe from the given topic
*/
unsubscribe(topic: string): void;
/**
* Get the list of topics which the peer is subscribed to.
*/
getTopics(): string[];
getPeers(): PeerId[];
}
//# sourceMappingURL=index.d.ts.map