chore: add type generation from jsdoc (#64)

src/pubsub/errors.d.ts

@@ -0,0 +1,4 @@
+export namespace codes {
+    export const ERR_MISSING_SIGNATURE: string;
+    export const ERR_INVALID_SIGNATURE: string;
+}

src/pubsub/index.d.ts

@@ -0,0 +1,307 @@
+export = PubsubBaseProtocol;
+/**
+ * @typedef {Object} InMessage
+ * @property {string} [from]
+ * @property {string} receivedFrom
+ * @property {string[]} topicIDs
+ * @property {Uint8Array} [seqno]
+ * @property {Uint8Array} data
+ * @property {Uint8Array} [signature]
+ * @property {Uint8Array} [key]
+ *
+ * @typedef PeerId
+ * @type import('peer-id')
+ */
+/**
+* PubsubBaseProtocol handles the peers and connections logic for pubsub routers
+* and specifies the API that pubsub routers should have.
+*/
+declare class PubsubBaseProtocol {
+    /**
+     * @param {Object} props
+     * @param {String} props.debugName log namespace
+     * @param {Array<string>|string} props.multicodecs protocol identificers to connect
+     * @param {Libp2p} props.libp2p
+     * @param {boolean} [props.signMessages = true] if messages should be signed
+     * @param {boolean} [props.strictSigning = true] if message signing should be required
+     * @param {boolean} [props.canRelayMessage = false] if can relay messages not subscribed
+     * @param {boolean} [props.emitSelf = false] if publish should emit to self, if subscribed
+     * @abstract
+     */
+    constructor({ debugName, multicodecs, libp2p, signMessages, strictSigning, canRelayMessage, emitSelf }: {
+        debugName: string;
+        multicodecs: string | string[];
+        libp2p: any;
+        signMessages?: boolean;
+        strictSigning?: boolean;
+        canRelayMessage?: boolean;
+        emitSelf?: boolean;
+    });
+    log: any;
+    /**
+     * @type {Array<string>}
+     */
+    multicodecs: Array<string>;
+    _libp2p: any;
+    registrar: any;
+    /**
+     * @type {PeerId}
+     */
+    peerId: PeerId;
+    started: boolean;
+    /**
+     * Map of topics to which peers are subscribed to
+     *
+     * @type {Map<string, Set<string>>}
+     */
+    topics: Map<string, Set<string>>;
+    /**
+     * List of our subscriptions
+     * @type {Set<string>}
+     */
+    subscriptions: Set<string>;
+    /**
+     * Map of peer streams
+     *
+     * @type {Map<string, import('./peer-streams')>}
+     */
+    peers: Map<string, import('./peer-streams')>;
+    signMessages: boolean;
+    /**
+     * If message signing should be required for incoming messages
+     * @type {boolean}
+     */
+    strictSigning: boolean;
+    /**
+     * If router can relay received messages, even if not subscribed
+     * @type {boolean}
+     */
+    canRelayMessage: boolean;
+    /**
+     * if publish should emit to self, if subscribed
+     * @type {boolean}
+     */
+    emitSelf: boolean;
+    /**
+     * Topic validator function
+     * @typedef {function(string, InMessage): Promise<void>} validator
+     */
+    /**
+     * Topic validator map
+     *
+     * Keyed by topic
+     * Topic validators are functions with the following input:
+     * @type {Map<string, validator>}
+     */
+    topicValidators: Map<string, validator>;
+    _registrarId: any;
+    /**
+     * On an inbound stream opened.
+     * @private
+     * @param {Object} props
+     * @param {string} props.protocol
+     * @param {DuplexIterableStream} props.stream
+     * @param {Connection} props.connection connection
+     */
+    _onIncomingStream({ protocol, stream, connection }: {
+        protocol: string;
+        stream: any;
+        connection: any;
+    }): void;
+    /**
+     * Registrar notifies an established connection with pubsub protocol.
+     * @private
+     * @param {PeerId} peerId remote peer-id
+     * @param {Connection} conn connection to the peer
+     */
+    _onPeerConnected(peerId: import("peer-id"), conn: any): Promise<void>;
+    /**
+     * Registrar notifies a closing connection with pubsub protocol.
+     * @private
+     * @param {PeerId} peerId peerId
+     * @param {Error} err error for connection end
+     */
+    _onPeerDisconnected(peerId: import("peer-id"), err: Error): void;
+    /**
+     * Register the pubsub protocol onto the libp2p node.
+     * @returns {void}
+     */
+    start(): void;
+    /**
+     * Unregister the pubsub protocol and the streams with other peers will be closed.
+     * @returns {void}
+     */
+    stop(): void;
+    /**
+     * Notifies the router that a peer has been connected
+     * @private
+     * @param {PeerId} peerId
+     * @param {string} protocol
+     * @returns {PeerStreams}
+     */
+    _addPeer(peerId: import("peer-id"), protocol: string): import("./peer-streams");
+    /**
+     * Notifies the router that a peer has been disconnected.
+     * @private
+     * @param {PeerId} peerId
+     * @returns {PeerStreams | undefined}
+     */
+    _removePeer(peerId: import("peer-id")): import("./peer-streams");
+    /**
+     * Responsible for processing each RPC message received by other peers.
+     * @param {string} idB58Str peer id string in base58
+     * @param {DuplexIterableStream} stream inbound stream
+     * @param {PeerStreams} peerStreams PubSub peer
+     * @returns {Promise<void>}
+     */
+    _processMessages(idB58Str: string, stream: any, peerStreams: import("./peer-streams")): Promise<void>;
+    /**
+     * Handles an rpc request from a peer
+     * @param {String} idB58Str
+     * @param {PeerStreams} peerStreams
+     * @param {RPC} rpc
+     * @returns {boolean}
+     */
+    _processRpc(idB58Str: string, peerStreams: import("./peer-streams"), rpc: any): boolean;
+    /**
+     * Handles a subscription change from a peer
+     * @param {string} id
+     * @param {RPC.SubOpt} subOpt
+     */
+    _processRpcSubOpt(id: string, subOpt: any): void;
+    /**
+     * Handles an message from a peer
+     * @param {InMessage} msg
+     * @returns {Promise<void>}
+     */
+    _processRpcMessage(msg: InMessage): Promise<void>;
+    /**
+     * Emit a message from a peer
+     * @param {InMessage} message
+     */
+    _emitMessage(message: InMessage): void;
+    /**
+     * The default msgID implementation
+     * Child class can override this.
+     * @param {RPC.Message} msg the message object
+     * @returns {string} message id as string
+     */
+    getMsgId(msg: any): string;
+    /**
+     * Whether to accept a message from a peer
+     * Override to create a graylist
+     * @override
+     * @param {string} id
+     * @returns {boolean}
+     */
+    _acceptFrom(id: string): boolean;
+    /**
+     * Decode Uint8Array into an RPC object.
+     * This can be override to use a custom router protobuf.
+     * @param {Uint8Array} bytes
+     * @returns {RPC}
+     */
+    _decodeRpc(bytes: Uint8Array): any;
+    /**
+     * Encode RPC object into a Uint8Array.
+     * This can be override to use a custom router protobuf.
+     * @param {RPC} rpc
+     * @returns {Uint8Array}
+     */
+    _encodeRpc(rpc: any): Uint8Array;
+    /**
+     * Send an rpc object to a peer
+     * @param {string} id peer id
+     * @param {RPC} rpc
+     * @returns {void}
+     */
+    _sendRpc(id: string, rpc: any): void;
+    /**
+     * Send subscroptions to a peer
+     * @param {string} id peer id
+     * @param {string[]} topics
+     * @param {boolean} subscribe set to false for unsubscriptions
+     * @returns {void}
+     */
+    _sendSubscriptions(id: string, topics: string[], subscribe: boolean): void;
+    /**
+     * Validates the given message. The signature will be checked for authenticity.
+     * Throws an error on invalid messages
+     * @param {InMessage} message
+     * @returns {Promise<void>}
+     */
+    validate(message: InMessage): Promise<void>;
+    /**
+     * Normalizes the message and signs it, if signing is enabled.
+     * Should be used by the routers to create the message to send.
+     * @private
+     * @param {Message} message
+     * @returns {Promise<Message>}
+     */
+    _buildMessage(message: any): Promise<any>;
+    /**
+     * Get a list of the peer-ids that are subscribed to one topic.
+     * @param {string} topic
+     * @returns {Array<string>}
+     */
+    getSubscribers(topic: string): string[];
+    /**
+     * Publishes messages to all subscribed peers
+     * @override
+     * @param {string} topic
+     * @param {Buffer} message
+     * @returns {Promise<void>}
+     */
+    publish(topic: string, message: Buffer): Promise<void>;
+    /**
+     * 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
+     * @abstract
+     * @param {InMessage} message
+     * @returns {Promise<void>}
+     *
+     */
+    _publish(message: InMessage): Promise<void>;
+    /**
+     * Subscribes to a given topic.
+     * @abstract
+     * @param {string} topic
+     * @returns {void}
+     */
+    subscribe(topic: string): void;
+    /**
+     * Unsubscribe from the given topic.
+     * @override
+     * @param {string} topic
+     * @returns {void}
+     */
+    unsubscribe(topic: string): void;
+    /**
+     * Get the list of topics which the peer is subscribed to.
+     * @override
+     * @returns {Array<String>}
+     */
+    getTopics(): string[];
+}
+declare namespace PubsubBaseProtocol {
+    export { message, utils, InMessage, PeerId };
+}
+type PeerId = import("peer-id");
+/**
+ * Topic validator function
+ */
+type validator = (arg0: string, arg1: InMessage) => Promise<void>;
+type InMessage = {
+    from?: string;
+    receivedFrom: string;
+    topicIDs: string[];
+    seqno?: Uint8Array;
+    data: Uint8Array;
+    signature?: Uint8Array;
+    key?: Uint8Array;
+};
+/**
+ * @type {typeof import('./message')}
+ */
+declare const message: typeof import('./message');
+declare const utils: typeof import("./utils");

src/pubsub/index.js

@@ -8,9 +8,13 @@ const pipe = require('it-pipe')
 
 const MulticodecTopology = require('../topology/multicodec-topology')
 const { codes } = require('./errors')
+/**
+ * @type {typeof import('./message')}
+ */
 const message = require('./message')
 const PeerStreams = require('./peer-streams')
 const utils = require('./utils')
+
 const {
   signMessage,
   verifySignature
@@ -18,12 +22,16 @@ const {
 
 /**
  * @typedef {Object} InMessage
- * @property {string} from
+ * @property {string} [from]
  * @property {string} receivedFrom
  * @property {string[]} topicIDs
+ * @property {Uint8Array} [seqno]
  * @property {Uint8Array} data
  * @property {Uint8Array} [signature]
  * @property {Uint8Array} [key]
+ *
+ * @typedef PeerId
+ * @type import('peer-id')
  */
 
 /**
@@ -68,9 +76,15 @@ class PubsubBaseProtocol extends EventEmitter {
     this.log = debug(debugName)
     this.log.err = debug(`${debugName}:error`)
 
+    /**
+     * @type {Array<string>}
+     */
     this.multicodecs = utils.ensureArray(multicodecs)
     this._libp2p = libp2p
     this.registrar = libp2p.registrar
+    /**
+     * @type {PeerId}
+     */
     this.peerId = libp2p.peerId
 
     this.started = false
@@ -91,7 +105,7 @@ class PubsubBaseProtocol extends EventEmitter {
     /**
      * Map of peer streams
      *
-     * @type {Map<string, PeerStreams>}
+     * @type {Map<string, import('./peer-streams')>}
      */
     this.peers = new Map()
 
@@ -118,7 +132,7 @@ class PubsubBaseProtocol extends EventEmitter {
 
     /**
      * Topic validator function
-     * @typedef {function(string, RPC): boolean} validator
+     * @typedef {function(string, InMessage): Promise<void>} validator
      */
     /**
      * Topic validator map

src/pubsub/message/index.d.ts

@@ -0,0 +1,5 @@
+export var rpc: any;
+export var td: any;
+export var RPC: any;
+export var Message: any;
+export var SubOpts: any;

src/pubsub/message/index.js

@@ -6,6 +6,9 @@ const rpcProto = protons(require('./rpc.proto.js'))
 const RPC = rpcProto.RPC
 const topicDescriptorProto = protons(require('./topic-descriptor.proto.js'))
 
+/**
+ * @module pubsub/message/index
+ */
 exports = module.exports
 exports.rpc = rpcProto
 exports.td = topicDescriptorProto

src/pubsub/message/rpc.proto.d.ts

@@ -0,0 +1,2 @@
+declare const _exports: string;
+export = _exports;

src/pubsub/message/sign.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns the PublicKey associated with the given message.
+ * If no, valid PublicKey can be retrieved an error will be returned.
+ *
+ * @param {InMessage} message
+ * @returns {Promise<PublicKey>}
+ */
+export function messagePublicKey(message: any): Promise<any>;
+/**
+ * Signs the provided message with the given `peerId`
+ *
+ * @param {PeerId} peerId
+ * @param {Message} message
+ * @returns {Promise<Message>}
+ */
+export function signMessage(peerId: import("peer-id"), message: any): Promise<any>;
+export const SignPrefix: any;
+/**
+ * Verifies the signature of the given message
+ * @param {InMessage} message
+ * @returns {Promise<Boolean>}
+ */
+export function verifySignature(message: any): Promise<boolean>;

src/pubsub/message/topic-descriptor.proto.d.ts

@@ -0,0 +1,2 @@
+declare const _exports: string;
+export = _exports;

src/pubsub/peer-streams.d.ts

@@ -0,0 +1,113 @@
+export = PeerStreams;
+/**
+ * @callback Sink
+ * @param {Uint8Array} source
+ * @returns {Promise<Uint8Array>}
+ *
+ * @typedef {object} DuplexIterableStream
+ * @property {Sink} sink
+ * @property {() AsyncIterator<Uint8Array>} source
+ *
+ * @typedef PeerId
+ * @type import('peer-id')
+ */
+/**
+ * Thin wrapper around a peer's inbound / outbound pubsub streams
+ */
+declare class PeerStreams {
+    /**
+     * @param {object} properties properties of the PeerStreams.
+     * @param {PeerId} properties.id
+     * @param {string} properties.protocol
+     */
+    constructor({ id, protocol }: {
+        id: import("peer-id");
+        protocol: string;
+    });
+    /**
+     * @type {import('peer-id')}
+     */
+    id: import('peer-id');
+    /**
+     * Established protocol
+     * @type {string}
+     */
+    protocol: string;
+    /**
+     * The raw outbound stream, as retrieved from conn.newStream
+     * @private
+     * @type {DuplexIterableStream}
+     */
+    _rawOutboundStream: DuplexIterableStream;
+    /**
+     * The raw inbound stream, as retrieved from the callback from libp2p.handle
+     * @private
+     * @type {DuplexIterableStream}
+     */
+    _rawInboundStream: DuplexIterableStream;
+    /**
+     * An AbortController for controlled shutdown of the inbound stream
+     * @private
+     * @type {typeof AbortController}
+     */
+    _inboundAbortController: typeof AbortController;
+    /**
+     * Write stream -- its preferable to use the write method
+     * @type {import('it-pushable').Pushable<Uint8Array>>}
+     */
+    outboundStream: import('it-pushable').Pushable<Uint8Array>;
+    /**
+     * Read stream
+     * @type {DuplexIterableStream}
+     */
+    inboundStream: DuplexIterableStream;
+    /**
+     * Do we have a connection to read from?
+     *
+     * @type {boolean}
+     */
+    get isReadable(): boolean;
+    /**
+     * Do we have a connection to write on?
+     *
+     * @type {boolean}
+     */
+    get isWritable(): boolean;
+    /**
+     * Send a message to this peer.
+     * Throws if there is no `stream` to write to available.
+     *
+     * @param {Uint8Array} data
+     * @returns {void}
+     */
+    write(data: Uint8Array): void;
+    /**
+     * Attach a raw inbound stream and setup a read stream
+     *
+     * @param {DuplexIterableStream} stream
+     * @returns {void}
+     */
+    attachInboundStream(stream: DuplexIterableStream): void;
+    /**
+     * Attach a raw outbound stream and setup a write stream
+     *
+     * @param {Stream} stream
+     * @returns {Promise<void>}
+     */
+    attachOutboundStream(stream: any): Promise<void>;
+    /**
+     * Closes the open connection to peer
+     * @returns {void}
+     */
+    close(): void;
+}
+declare namespace PeerStreams {
+    export { Sink, DuplexIterableStream, PeerId };
+}
+type DuplexIterableStream = {
+    sink: Sink;
+    source: () => AsyncIterator<Uint8Array, any, undefined>;
+};
+declare const AbortController: typeof import("abort-controller");
+type Sink = (source: Uint8Array) => Promise<Uint8Array>;
+type PeerId = import("peer-id");

src/pubsub/peer-streams.js

@@ -12,19 +12,33 @@ const debug = require('debug')
 const log = debug('libp2p-pubsub:peer-streams')
 log.error = debug('libp2p-pubsub:peer-streams:error')
 
+/**
+ * @callback Sink
+ * @param {Uint8Array} source
+ * @returns {Promise<Uint8Array>}
+ *
+ * @typedef {object} DuplexIterableStream
+ * @property {Sink} sink
+ * @property {() AsyncIterator<Uint8Array>} source
+ *
+ * @typedef PeerId
+ * @type import('peer-id')
+ */
+
 /**
  * Thin wrapper around a peer's inbound / outbound pubsub streams
  */
 class PeerStreams extends EventEmitter {
   /**
-   * @param {PeerId} id
-   * @param {string} protocol
+   * @param {object} properties properties of the PeerStreams.
+   * @param {PeerId} properties.id
+   * @param {string} properties.protocol
    */
   constructor ({ id, protocol }) {
     super()
 
     /**
-     * @type {PeerId}
+     * @type {import('peer-id')}
      */
     this.id = id
     /**
@@ -47,12 +61,12 @@ class PeerStreams extends EventEmitter {
     /**
      * An AbortController for controlled shutdown of the inbound stream
      * @private
-     * @type {AbortController}
+     * @type {typeof AbortController}
      */
     this._inboundAbortController = null
     /**
      * Write stream -- its preferable to use the write method
-     * @type {Pushable}
+     * @type {import('it-pushable').Pushable<Uint8Array>>}
      */
     this.outboundStream = null
     /**
@@ -85,7 +99,7 @@ class PeerStreams extends EventEmitter {
    * Throws if there is no `stream` to write to available.
    *
    * @param {Uint8Array} data
-   * @returns {undefined}
+   * @returns {void}
    */
   write (data) {
     if (!this.isWritable) {

src/pubsub/utils.d.ts

@@ -0,0 +1,6 @@
+export function randomSeqno(): Uint8Array;
+export function msgId(from: string, seqno: Uint8Array): string;
+export function anyMatch(a: any[] | Set<any>, b: any[] | Set<any>): boolean;
+export function ensureArray(maybeArray: any): any[];
+export function normalizeInRpcMessage(message: any, peerId: string): any;
+export function normalizeOutRpcMessage(message: any): any;

src/pubsub/utils.js

@@ -3,7 +3,6 @@
 const randomBytes = require('libp2p-crypto/src/random-bytes')
 const uint8ArrayToString = require('uint8arrays/to-string')
 const uint8ArrayFromString = require('uint8arrays/from-string')
-
 exports = module.exports
 
 /**
@@ -71,10 +70,9 @@ exports.ensureArray = (maybeArray) => {
 
 /**
  * Ensures `message.from` is base58 encoded
- * @param {Object} message
- * @param {Uint8Array|String} message.from
+ * @param {object} message
  * @param {String} peerId
- * @return {Object}
+ * @return {object}
  */
 exports.normalizeInRpcMessage = (message, peerId) => {
   const m = Object.assign({}, message)
@@ -87,6 +85,10 @@ exports.normalizeInRpcMessage = (message, peerId) => {
   return m
 }
 
+/**
+ * @param {object} message
+ * @return {object}
+ */
 exports.normalizeOutRpcMessage = (message) => {
   const m = Object.assign({}, message)
   if (typeof message.from === 'string' || message.from instanceof String) {