fluencelabs/js-libp2p-interfaces
1
0
Fork 0
mirror of https://github.com/fluencelabs/js-libp2p-interfaces synced 2025-04-24 17:52:21 +00:00
Code Issues Projects Releases Wiki Activity

feat: add types per jsdoc and types for testing interfaces

Browse Source
This commit is contained in:
Vasco Santos 2020-11-30 16:43:51 +01:00
parent 83d7d52d7e
commit e82385d4b9
31 changed files with 852 additions and 571 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
package.json
View File

@ -12,15 +12,15 @@
"scripts": { "scripts": {
"lint": "aegir lint", "lint": "aegir lint",
"build": "aegir build", "build": "aegir build",
"pregenerate:types": "rimraf './src/**/*.d.ts'",
"generate:types": "tsc",
"test": "aegir test", "test": "aegir test",
"test:node": "aegir test --target node", "test:node": "aegir test --target node",
"test:browser": "aegir test --target browser", "test:browser": "aegir test --target browser",
"test:types": "aegir ts -p check",
"prepublishOnly": "npm run generate:types", "prepublishOnly": "npm run generate:types",
"release": "aegir release -t node -t browser", "release": "aegir release -t node -t browser",
"release-minor": "aegir release --type minor -t node -t browser", "release-minor": "aegir release --type minor -t node -t browser",
"release-major": "aegir release --type major -t node -t browser" "release-major": "aegir release --type major -t node -t browser",
"remove:types": "rimraf './src/**/*.d.ts'"
}, },
"repository": { "repository": {
"type": "git", "type": "git",
@ -67,10 +67,12 @@
"uint8arrays": "^1.1.0" "uint8arrays": "^1.1.0"
}, },
"devDependencies": { "devDependencies": {
"aegir": "^25.0.0", "aegir": "^29.2.0",
"it-handshake": "^1.0.1", "it-handshake": "^1.0.1",
"rimraf": "^3.0.2", "rimraf": "^3.0.2"
"typescript": "3.7.5" },
"eslintConfig": {
"extends": "ipfs"
}, },
"contributors": [ "contributors": [
"Alan Shaw <alan.shaw@protocol.ai>", "Alan Shaw <alan.shaw@protocol.ai>",

149
src/connection/connection.d.ts vendored
View File

@ -1,149 +0,0 @@
declare const _exports: typeof Connection;
export = _exports;
/**
* An implementation of the js-libp2p connection.
* Any libp2p transport should use an upgrader to return this connection.
*/
declare class Connection {
/**
* Creates an instance of Connection.
* @param {object} properties properties of the connection.
* @param {multiaddr} [properties.localAddr] local multiaddr of the connection if known.
* @param {multiaddr} [properties.remoteAddr] remote multiaddr of the connection.
* @param {PeerId} properties.localPeer local peer-id.
* @param {PeerId} properties.remotePeer remote peer-id.
* @param {function} properties.newStream new stream muxer function.
* @param {function} properties.close close raw connection function.
* @param {function(): Stream[]} properties.getStreams get streams from muxer function.
* @param {object} properties.stat metadata of the connection.
* @param {string} properties.stat.direction connection establishment direction ("inbound" or "outbound").
* @param {object} properties.stat.timeline connection relevant events timestamp.
* @param {string} properties.stat.timeline.open connection opening timestamp.
* @param {string} properties.stat.timeline.upgraded connection upgraded timestamp.
* @param {string} [properties.stat.multiplexer] connection multiplexing identifier.
* @param {string} [properties.stat.encryption] connection encryption method identifier.
*/
constructor({ localAddr, remoteAddr, localPeer, remotePeer, newStream, close, getStreams, stat }: {
localAddr?: import("multiaddr");
remoteAddr?: import("multiaddr");
localPeer: import("peer-id");
remotePeer: import("peer-id");
newStream: Function;
close: Function;
getStreams: () => any[];
stat: {
direction: string;
timeline: {
open: string;
upgraded: string;
};
multiplexer?: string;
encryption?: string;
};
});
/**
* Connection identifier.
*/
id: any;
/**
* Observed multiaddr of the local peer
*/
localAddr: import("multiaddr");
/**
* Observed multiaddr of the remote peer
*/
remoteAddr: import("multiaddr");
/**
* Local peer id.
*/
localPeer: import("peer-id");
/**
* Remote peer id.
*/
remotePeer: import("peer-id");
/**
* Connection metadata.
*/
_stat: {
status: string;
direction: string;
timeline: {
open: string;
upgraded: string;
};
multiplexer?: string;
encryption?: string;
};
/**
* Reference to the new stream function of the multiplexer
*/
_newStream: Function;
/**
* Reference to the close function of the raw connection
*/
_close: Function;
/**
* Reference to the getStreams function of the muxer
*/
_getStreams: () => any[];
/**
* Connection streams registry
*/
registry: Map<any, any>;
/**
* User provided tags
* @type {string[]}
*/
tags: string[];
/**
* Get connection metadata
* @this {Connection}
*/
get stat(): {
status: string;
direction: string;
timeline: {
open: string;
upgraded: string;
};
multiplexer?: string;
encryption?: string;
};
/**
* Get all the streams of the muxer.
* @this {Connection}
*/
get streams(): any[];
/**
* Create a new stream from this connection
* @param {string[]} protocols intended protocol for the stream
* @return {Promise<{stream: Stream, protocol: string}>} with muxed+multistream-selected stream and selected protocol
*/
newStream(protocols: string[]): Promise<{
stream: any;
protocol: string;
}>;
/**
* Add a stream when it is opened to the registry.
* @param {*} muxedStream a muxed stream
* @param {object} properties the stream properties to be registered
* @param {string} properties.protocol the protocol used by the stream
* @param {object} properties.metadata metadata of the stream
* @return {void}
*/
addStream(muxedStream: any, { protocol, metadata }: {
protocol: string;
metadata: any;
}): void;
/**
* Remove stream registry after it is closed.
* @param {string} id identifier of the stream
*/
removeStream(id: string): void;
/**
* Close the connection.
* @return {Promise<void>}
*/
close(): Promise<void>;
_closing: any;
}

234
src/connection/connection.js
View File

@ -1,234 +0,0 @@
'use strict'
const PeerId = require('peer-id')
const multiaddr = require('multiaddr')
const withIs = require('class-is')
const errCode = require('err-code')
const Status = require('./status')
function validateArgs (localAddr, localPeer, remotePeer, newStream, close, getStreams, stat) {
if (localAddr && !multiaddr.isMultiaddr(localAddr)) {
throw errCode(new Error('localAddr must be an instance of multiaddr'), 'ERR_INVALID_PARAMETERS')
}
if (!PeerId.isPeerId(localPeer)) {
throw errCode(new Error('localPeer must be an instance of peer-id'), 'ERR_INVALID_PARAMETERS')
}
if (!PeerId.isPeerId(remotePeer)) {
throw errCode(new Error('remotePeer must be an instance of peer-id'), 'ERR_INVALID_PARAMETERS')
}
if (typeof newStream !== 'function') {
throw errCode(new Error('new stream must be a function'), 'ERR_INVALID_PARAMETERS')
}
if (typeof close !== 'function') {
throw errCode(new Error('close must be a function'), 'ERR_INVALID_PARAMETERS')
}
if (typeof getStreams !== 'function') {
throw errCode(new Error('getStreams must be a function'), 'ERR_INVALID_PARAMETERS')
}
if (!stat) {
throw errCode(new Error('connection metadata object must be provided'), 'ERR_INVALID_PARAMETERS')
}
if (stat.direction !== 'inbound' && stat.direction !== 'outbound') {
throw errCode(new Error('direction must be "inbound" or "outbound"'), 'ERR_INVALID_PARAMETERS')
}
if (!stat.timeline) {
throw errCode(new Error('connection timeline object must be provided in the stat object'), 'ERR_INVALID_PARAMETERS')
}
if (!stat.timeline.open) {
throw errCode(new Error('connection open timestamp must be provided'), 'ERR_INVALID_PARAMETERS')
}
if (!stat.timeline.upgraded) {
throw errCode(new Error('connection upgraded timestamp must be provided'), 'ERR_INVALID_PARAMETERS')
}
}
/**
* An implementation of the js-libp2p connection.
* Any libp2p transport should use an upgrader to return this connection.
*/
class Connection {
/**
* Creates an instance of Connection.
* @param {object} properties properties of the connection.
* @param {multiaddr} [properties.localAddr] local multiaddr of the connection if known.
* @param {multiaddr} [properties.remoteAddr] remote multiaddr of the connection.
* @param {PeerId} properties.localPeer local peer-id.
* @param {PeerId} properties.remotePeer remote peer-id.
* @param {function} properties.newStream new stream muxer function.
* @param {function} properties.close close raw connection function.
* @param {function(): Stream[]} properties.getStreams get streams from muxer function.
* @param {object} properties.stat metadata of the connection.
* @param {string} properties.stat.direction connection establishment direction ("inbound" or "outbound").
* @param {object} properties.stat.timeline connection relevant events timestamp.
* @param {string} properties.stat.timeline.open connection opening timestamp.
* @param {string} properties.stat.timeline.upgraded connection upgraded timestamp.
* @param {string} [properties.stat.multiplexer] connection multiplexing identifier.
* @param {string} [properties.stat.encryption] connection encryption method identifier.
*/
constructor ({ localAddr, remoteAddr, localPeer, remotePeer, newStream, close, getStreams, stat }) {
validateArgs(localAddr, localPeer, remotePeer, newStream, close, getStreams, stat)
/**
* Connection identifier.
*/
this.id = (parseInt(Math.random() * 1e9)).toString(36) + Date.now()
/**
* Observed multiaddr of the local peer
*/
this.localAddr = localAddr
/**
* Observed multiaddr of the remote peer
*/
this.remoteAddr = remoteAddr
/**
* Local peer id.
*/
this.localPeer = localPeer
/**
* Remote peer id.
*/
this.remotePeer = remotePeer
/**
* Connection metadata.
*/
this._stat = {
...stat,
status: Status.OPEN
}
/**
* Reference to the new stream function of the multiplexer
*/
this._newStream = newStream
/**
* Reference to the close function of the raw connection
*/
this._close = close
/**
* Reference to the getStreams function of the muxer
*/
this._getStreams = getStreams
/**
* Connection streams registry
*/
this.registry = new Map()
/**
* User provided tags
* @type {string[]}
*/
this.tags = []
}
/**
* Get connection metadata
* @this {Connection}
*/
get stat () {
return this._stat
}
/**
* Get all the streams of the muxer.
* @this {Connection}
*/
get streams () {
return this._getStreams()
}
/**
* Create a new stream from this connection
* @param {string[]} protocols intended protocol for the stream
* @return {Promise<{stream: Stream, protocol: string}>} with muxed+multistream-selected stream and selected protocol
*/
async newStream (protocols) {
if (this.stat.status === Status.CLOSING) {
throw errCode(new Error('the connection is being closed'), 'ERR_CONNECTION_BEING_CLOSED')
}
if (this.stat.status === Status.CLOSED) {
throw errCode(new Error('the connection is closed'), 'ERR_CONNECTION_CLOSED')
}
if (!Array.isArray(protocols)) protocols = [protocols]
const { stream, protocol } = await this._newStream(protocols)
this.addStream(stream, { protocol })
return {
stream,
protocol
}
}
/**
* Add a stream when it is opened to the registry.
* @param {*} muxedStream a muxed stream
* @param {object} properties the stream properties to be registered
* @param {string} properties.protocol the protocol used by the stream
* @param {object} properties.metadata metadata of the stream
* @return {void}
*/
addStream (muxedStream, { protocol, metadata = {} }) {
// Add metadata for the stream
this.registry.set(muxedStream.id, {
protocol,
...metadata
})
}
/**
* Remove stream registry after it is closed.
* @param {string} id identifier of the stream
*/
removeStream (id) {
this.registry.delete(id)
}
/**
* Close the connection.
* @return {Promise<void>}
*/
async close () {
if (this.stat.status === Status.CLOSED) {
return
}
if (this._closing) {
return this._closing
}
this.stat.status = Status.CLOSING
// Close raw connection
this._closing = await this._close()
this._stat.timeline.close = Date.now()
this.stat.status = Status.CLOSED
}
}
/**
* @module
* @type {typeof Connection}
*/
module.exports = withIs(Connection, { className: 'Connection', symbolName: '@libp2p/interface-connection/connection' })

231
src/connection/index.d.ts vendored
View File

@ -1 +1,230 @@
export var Connection: typeof import('./connection'); export = Connection;
/**
* @typedef {Object} ConectionStat
* @property {string} direction - connection establishment direction ("inbound" or "outbound").
* @property {object} timeline - connection relevant events timestamp.
* @property {string} timeline.open - connection opening timestamp.
* @property {string} timeline.upgraded - connection upgraded timestamp.
* @property {string} [multiplexer] - connection multiplexing identifier.
* @property {string} [encryption] - connection encryption method identifier.
*
* @typedef {Object} ConnectionOptions
* @property {multiaddr} [localAddr] - local multiaddr of the connection if known.
* @property {multiaddr} [remoteAddr] - remote multiaddr of the connection.
* @property {PeerId} localPeer - local peer-id.
* @property {PeerId} remotePeer - remote peer-id.
* @property {(protocols: string[]) => Promise<{stream: Stream, protocol: string}>} newStream - new stream muxer function.
* @property {() => Promise<void>} close - close raw connection function.
* @property {() => Stream[]} getStreams - get streams from muxer function.
* @property {ConectionStat} stat - metadata of the connection.
*/
declare class Connection {
/**
* An implementation of the js-libp2p connection.
* Any libp2p transport should use an upgrader to return this connection.
*
* @class
* @param {ConnectionOptions} options
*/
constructor({ localAddr, remoteAddr, localPeer, remotePeer, newStream, close, getStreams, stat }: ConnectionOptions);
/**
* Connection identifier.
*/
id: string;
/**
* Observed multiaddr of the local peer
*/
localAddr: import("multiaddr");
/**
* Observed multiaddr of the remote peer
*/
remoteAddr: import("multiaddr");
/**
* Local peer id.
*/
localPeer: import("peer-id");
/**
* Remote peer id.
*/
remotePeer: import("peer-id");
/**
* Connection metadata.
*/
_stat: {
status: string;
/**
* - connection establishment direction ("inbound" or "outbound").
*/
direction: string;
/**
* - connection relevant events timestamp.
*/
timeline: {
open: string;
upgraded: string;
};
/**
* - connection multiplexing identifier.
*/
multiplexer?: string;
/**
* - connection encryption method identifier.
*/
encryption?: string;
};
/**
* Reference to the new stream function of the multiplexer
*/
_newStream: (protocols: string[]) => Promise<{
stream: any;
protocol: string;
}>;
/**
* Reference to the close function of the raw connection
*/
_close: () => Promise<void>;
/**
* Reference to the getStreams function of the muxer
*/
_getStreams: () => any[];
/**
* Connection streams registry
*/
registry: Map<any, any>;
/**
* User provided tags
*
* @type {string[]}
*/
tags: string[];
/**
* Get connection metadata
*
* @this {Connection}
*/
get stat(): {
status: string;
/**
* - connection establishment direction ("inbound" or "outbound").
*/
direction: string;
/**
* - connection relevant events timestamp.
*/
timeline: {
open: string;
upgraded: string;
};
/**
* - connection multiplexing identifier.
*/
multiplexer?: string;
/**
* - connection encryption method identifier.
*/
encryption?: string;
};
/**
* Get all the streams of the muxer.
*
* @this {Connection}
*/
get streams(): any[];
/**
* Create a new stream from this connection
*
* @param {string[]|string} protocols - intended protocol for the stream
* @returns {Promise<{stream: Stream, protocol: string}>} with muxed+multistream-selected stream and selected protocol
*/
newStream(protocols: string[] | string): Promise<{
stream: any;
protocol: string;
}>;
/**
* Add a stream when it is opened to the registry.
*
* @param {*} muxedStream - a muxed stream
* @param {object} properties - the stream properties to be registered
* @param {string} properties.protocol - the protocol used by the stream
* @param {object} properties.metadata - metadata of the stream
* @returns {void}
*/
addStream(muxedStream: any, { protocol, metadata }: {
protocol: string;
metadata: object;
}): void;
/**
* Remove stream registry after it is closed.
*
* @param {string} id - identifier of the stream
*/
removeStream(id: string): void;
/**
* Close the connection.
*
* @returns {Promise<void>}
*/
close(): Promise<void>;
_closing: void;
}
declare namespace Connection {
export { ConectionStat, ConnectionOptions };
}
type ConnectionOptions = {
/**
* - local multiaddr of the connection if known.
*/
localAddr?: import("multiaddr");
/**
* - remote multiaddr of the connection.
*/
remoteAddr?: import("multiaddr");
/**
* - local peer-id.
*/
localPeer: import("peer-id");
/**
* - remote peer-id.
*/
remotePeer: import("peer-id");
/**
* - new stream muxer function.
*/
newStream: (protocols: string[]) => Promise<{
stream: any;
protocol: string;
}>;
/**
* - close raw connection function.
*/
close: () => Promise<void>;
/**
* - get streams from muxer function.
*/
getStreams: () => any[];
/**
* - metadata of the connection.
*/
stat: ConectionStat;
};
type ConectionStat = {
/**
* - connection establishment direction ("inbound" or "outbound").
*/
direction: string;
/**
* - connection relevant events timestamp.
*/
timeline: {
open: string;
upgraded: string;
};
/**
* - connection multiplexing identifier.
*/
multiplexer?: string;
/**
* - connection encryption method identifier.
*/
encryption?: string;
};

241
src/connection/index.js
View File

@ -1,7 +1,242 @@
'use strict' 'use strict'
const PeerId = require('peer-id')
const multiaddr = require('multiaddr')
const withIs = require('class-is')
const errCode = require('err-code')
const Status = require('./status')
/** /**
* @module connection/index * @typedef {Object} ConectionStat
* @type {typeof import('./connection')} * @property {string} direction - connection establishment direction ("inbound" or "outbound").
* @property {object} timeline - connection relevant events timestamp.
* @property {string} timeline.open - connection opening timestamp.
* @property {string} timeline.upgraded - connection upgraded timestamp.
* @property {string} [multiplexer] - connection multiplexing identifier.
* @property {string} [encryption] - connection encryption method identifier.
*
* @typedef {Object} ConnectionOptions
* @property {multiaddr} [localAddr] - local multiaddr of the connection if known.
* @property {multiaddr} [remoteAddr] - remote multiaddr of the connection.
* @property {PeerId} localPeer - local peer-id.
* @property {PeerId} remotePeer - remote peer-id.
* @property {(protocols: string[]) => Promise<{stream: Stream, protocol: string}>} newStream - new stream muxer function.
* @property {() => Promise<void>} close - close raw connection function.
* @property {() => Stream[]} getStreams - get streams from muxer function.
* @property {ConectionStat} stat - metadata of the connection.
*/ */
exports.Connection = require('./connection')
class Connection {
/**
* An implementation of the js-libp2p connection.
* Any libp2p transport should use an upgrader to return this connection.
*
* @class
* @param {ConnectionOptions} options
*/
constructor ({ localAddr, remoteAddr, localPeer, remotePeer, newStream, close, getStreams, stat }) {
validateArgs(localAddr, localPeer, remotePeer, newStream, close, getStreams, stat)
/**
* Connection identifier.
*/
this.id = (parseInt(Math.random() * 1e9)).toString(36) + Date.now()
/**
* Observed multiaddr of the local peer
*/
this.localAddr = localAddr
/**
* Observed multiaddr of the remote peer
*/
this.remoteAddr = remoteAddr
/**
* Local peer id.
*/
this.localPeer = localPeer
/**
* Remote peer id.
*/
this.remotePeer = remotePeer
/**
* Connection metadata.
*/
this._stat = {
...stat,
status: Status.OPEN
}
/**
* Reference to the new stream function of the multiplexer
*/
this._newStream = newStream
/**
* Reference to the close function of the raw connection
*/
this._close = close
/**
* Reference to the getStreams function of the muxer
*/
this._getStreams = getStreams
/**
* Connection streams registry
*/
this.registry = new Map()
/**
* User provided tags
*
* @type {string[]}
*/
this.tags = []
}
/**
* Get connection metadata
*
* @this {Connection}
*/
get stat () {
return this._stat
}
/**
* Get all the streams of the muxer.
*
* @this {Connection}
*/
get streams () {
return this._getStreams()
}
/**
* Create a new stream from this connection
*
* @param {string[]|string} protocols - intended protocol for the stream
* @returns {Promise<{stream: Stream, protocol: string}>} with muxed+multistream-selected stream and selected protocol
*/
async newStream (protocols) {
if (this.stat.status === Status.CLOSING) {
throw errCode(new Error('the connection is being closed'), 'ERR_CONNECTION_BEING_CLOSED')
}
if (this.stat.status === Status.CLOSED) {
throw errCode(new Error('the connection is closed'), 'ERR_CONNECTION_CLOSED')
}
if (!Array.isArray(protocols)) protocols = [protocols]
const { stream, protocol } = await this._newStream(protocols)
this.addStream(stream, { protocol })
return {
stream,
protocol
}
}
/**
* Add a stream when it is opened to the registry.
*
* @param {*} muxedStream - a muxed stream
* @param {object} properties - the stream properties to be registered
* @param {string} properties.protocol - the protocol used by the stream
* @param {object} properties.metadata - metadata of the stream
* @returns {void}
*/
addStream (muxedStream, { protocol, metadata = {} }) {
// Add metadata for the stream
this.registry.set(muxedStream.id, {
protocol,
...metadata
})
}
/**
* Remove stream registry after it is closed.
*
* @param {string} id - identifier of the stream
*/
removeStream (id) {
this.registry.delete(id)
}
/**
* Close the connection.
*
* @returns {Promise<void>}
*/
async close () {
if (this.stat.status === Status.CLOSED) {
return
}
if (this._closing) {
return this._closing
}
this.stat.status = Status.CLOSING
// Close raw connection
this._closing = await this._close()
this._stat.timeline.close = Date.now()
this.stat.status = Status.CLOSED
}
}
module.exports = Connection
function validateArgs (localAddr, localPeer, remotePeer, newStream, close, getStreams, stat) {
if (localAddr && !multiaddr.isMultiaddr(localAddr)) {
throw errCode(new Error('localAddr must be an instance of multiaddr'), 'ERR_INVALID_PARAMETERS')
}
if (!PeerId.isPeerId(localPeer)) {
throw errCode(new Error('localPeer must be an instance of peer-id'), 'ERR_INVALID_PARAMETERS')
}
if (!PeerId.isPeerId(remotePeer)) {
throw errCode(new Error('remotePeer must be an instance of peer-id'), 'ERR_INVALID_PARAMETERS')
}
if (typeof newStream !== 'function') {
throw errCode(new Error('new stream must be a function'), 'ERR_INVALID_PARAMETERS')
}
if (typeof close !== 'function') {
throw errCode(new Error('close must be a function'), 'ERR_INVALID_PARAMETERS')
}
if (typeof getStreams !== 'function') {
throw errCode(new Error('getStreams must be a function'), 'ERR_INVALID_PARAMETERS')
}
if (!stat) {
throw errCode(new Error('connection metadata object must be provided'), 'ERR_INVALID_PARAMETERS')
}
if (stat.direction !== 'inbound' && stat.direction !== 'outbound') {
throw errCode(new Error('direction must be "inbound" or "outbound"'), 'ERR_INVALID_PARAMETERS')
}
if (!stat.timeline) {
throw errCode(new Error('connection timeline object must be provided in the stat object'), 'ERR_INVALID_PARAMETERS')
}
if (!stat.timeline.open) {
throw errCode(new Error('connection open timestamp must be provided'), 'ERR_INVALID_PARAMETERS')
}
if (!stat.timeline.upgraded) {
throw errCode(new Error('connection upgraded timestamp must be provided'), 'ERR_INVALID_PARAMETERS')
}
}

6
src/connection/status.d.ts vendored
View File

@ -1,3 +1,3 @@
export declare const OPEN: string; export const OPEN: string;
export declare const CLOSING: string; export const CLOSING: string;
export declare const CLOSED: string; export const CLOSED: string;

6
src/content-routing/types.ts Normal file
View File

@ -0,0 +1,6 @@
export = ContentRouting;
declare class ContentRouting {
findProviders(cid);
provide(cid);
}

0
src/crypto/types.ts Normal file
View File

0
src/peer-discovery/types.ts Normal file
View File

0
src/peer-routing/types.ts Normal file
View File

18
src/pubsub/errors.d.ts vendored
View File

@ -1,11 +1,11 @@
export namespace codes { export namespace codes {
export const ERR_INVALID_SIGNATURE_POLICY: string; const ERR_INVALID_SIGNATURE_POLICY: string;
export const ERR_UNHANDLED_SIGNATURE_POLICY: string; const ERR_UNHANDLED_SIGNATURE_POLICY: string;
export const ERR_MISSING_SIGNATURE: string; const ERR_MISSING_SIGNATURE: string;
export const ERR_MISSING_SEQNO: string; const ERR_MISSING_SEQNO: string;
export const ERR_INVALID_SIGNATURE: string; const ERR_INVALID_SIGNATURE: string;
export const ERR_UNEXPECTED_FROM: string; const ERR_UNEXPECTED_FROM: string;
export const ERR_UNEXPECTED_SIGNATURE: string; const ERR_UNEXPECTED_SIGNATURE: string;
export const ERR_UNEXPECTED_KEY: string; const ERR_UNEXPECTED_KEY: string;
export const ERR_UNEXPECTED_SEQNO: string; const ERR_UNEXPECTED_SEQNO: string;
} }

109
src/pubsub/index.d.ts vendored
View File

@ -13,27 +13,27 @@ export = PubsubBaseProtocol;
* @type import('peer-id') * @type import('peer-id')
*/ */
/** /**
* PubsubBaseProtocol handles the peers and connections logic for pubsub routers * PubsubBaseProtocol handles the peers and connections logic for pubsub routers
* and specifies the API that pubsub routers should have. * and specifies the API that pubsub routers should have.
*/ */
declare class PubsubBaseProtocol { declare class PubsubBaseProtocol {
/** /**
* @param {Object} props * @param {Object} props
* @param {String} props.debugName log namespace * @param {string} props.debugName - log namespace
* @param {Array<string>|string} props.multicodecs protocol identificers to connect * @param {Array<string>|string} props.multicodecs - protocol identificers to connect
* @param {Libp2p} props.libp2p * @param {Libp2p} props.libp2p
* @param {SignaturePolicy} [props.globalSignaturePolicy = SignaturePolicy.StrictSign] defines how signatures should be handled * @param {SignaturePolicy} [props.globalSignaturePolicy = SignaturePolicy.StrictSign] - defines how signatures should be handled
* @param {boolean} [props.canRelayMessage = false] if can relay messages not subscribed * @param {boolean} [props.canRelayMessage = false] - if can relay messages not subscribed
* @param {boolean} [props.emitSelf = false] if publish should emit to self, if subscribed * @param {boolean} [props.emitSelf = false] - if publish should emit to self, if subscribed
* @abstract * @abstract
*/ */
constructor({ debugName, multicodecs, libp2p, globalSignaturePolicy, canRelayMessage, emitSelf }: { constructor({ debugName, multicodecs, libp2p, globalSignaturePolicy, canRelayMessage, emitSelf }: {
debugName: string; debugName: string;
multicodecs: string | string[]; multicodecs: Array<string> | string;
libp2p: any; libp2p: any;
globalSignaturePolicy?: any; globalSignaturePolicy: any;
canRelayMessage?: boolean; canRelayMessage: boolean;
emitSelf?: boolean; emitSelf: boolean;
}); });
log: any; log: any;
/** /**
@ -55,6 +55,7 @@ declare class PubsubBaseProtocol {
topics: Map<string, Set<string>>; topics: Map<string, Set<string>>;
/** /**
* List of our subscriptions * List of our subscriptions
*
* @type {Set<string>} * @type {Set<string>}
*/ */
subscriptions: Set<string>; subscriptions: Set<string>;
@ -72,16 +73,19 @@ declare class PubsubBaseProtocol {
globalSignaturePolicy: string; globalSignaturePolicy: string;
/** /**
* If router can relay received messages, even if not subscribed * If router can relay received messages, even if not subscribed
*
* @type {boolean} * @type {boolean}
*/ */
canRelayMessage: boolean; canRelayMessage: boolean;
/** /**
* if publish should emit to self, if subscribed * if publish should emit to self, if subscribed
*
* @type {boolean} * @type {boolean}
*/ */
emitSelf: boolean; emitSelf: boolean;
/** /**
* Topic validator function * Topic validator function
*
* @typedef {function(string, InMessage): Promise<void>} validator * @typedef {function(string, InMessage): Promise<void>} validator
*/ */
/** /**
@ -89,73 +93,79 @@ declare class PubsubBaseProtocol {
* *
* Keyed by topic * Keyed by topic
* Topic validators are functions with the following input: * Topic validators are functions with the following input:
*
* @type {Map<string, validator>} * @type {Map<string, validator>}
*/ */
topicValidators: Map<string, validator>; topicValidators: Map<string, (arg0: string, arg1: InMessage) => Promise<void>>;
_registrarId: any; _registrarId: any;
/** /**
* On an inbound stream opened. * On an inbound stream opened.
*
* @private * @private
* @param {Object} props * @param {Object} props
* @param {string} props.protocol * @param {string} props.protocol
* @param {DuplexIterableStream} props.stream * @param {DuplexIterableStream} props.stream
* @param {Connection} props.connection connection * @param {Connection} props.connection - connection
*/ */
_onIncomingStream({ protocol, stream, connection }: { private _onIncomingStream;
protocol: string;
stream: any;
connection: any;
}): void;
/** /**
* Registrar notifies an established connection with pubsub protocol. * Registrar notifies an established connection with pubsub protocol.
*
* @private * @private
* @param {PeerId} peerId remote peer-id * @param {PeerId} peerId - remote peer-id
* @param {Connection} conn connection to the peer * @param {Connection} conn - connection to the peer
*/ */
_onPeerConnected(peerId: import("peer-id"), conn: any): Promise<void>; private _onPeerConnected;
/** /**
* Registrar notifies a closing connection with pubsub protocol. * Registrar notifies a closing connection with pubsub protocol.
*
* @private * @private
* @param {PeerId} peerId peerId * @param {PeerId} peerId - peerId
* @param {Error} err error for connection end * @param {Error} err - error for connection end
*/ */
_onPeerDisconnected(peerId: import("peer-id"), err: Error): void; private _onPeerDisconnected;
/** /**
* Register the pubsub protocol onto the libp2p node. * Register the pubsub protocol onto the libp2p node.
*
* @returns {void} * @returns {void}
*/ */
start(): void; start(): void;
/** /**
* Unregister the pubsub protocol and the streams with other peers will be closed. * Unregister the pubsub protocol and the streams with other peers will be closed.
*
* @returns {void} * @returns {void}
*/ */
stop(): void; stop(): void;
/** /**
* Notifies the router that a peer has been connected * Notifies the router that a peer has been connected
*
* @private * @private
* @param {PeerId} peerId * @param {PeerId} peerId
* @param {string} protocol * @param {string} protocol
* @returns {PeerStreams} * @returns {PeerStreams}
*/ */
_addPeer(peerId: import("peer-id"), protocol: string): import("./peer-streams"); private _addPeer;
/** /**
* Notifies the router that a peer has been disconnected. * Notifies the router that a peer has been disconnected.
*
* @private * @private
* @param {PeerId} peerId * @param {PeerId} peerId
* @returns {PeerStreams | undefined} * @returns {PeerStreams | undefined}
*/ */
_removePeer(peerId: import("peer-id")): import("./peer-streams"); private _removePeer;
/** /**
* Responsible for processing each RPC message received by other peers. * Responsible for processing each RPC message received by other peers.
* @param {string} idB58Str peer id string in base58 *
* @param {DuplexIterableStream} stream inbound stream * @param {string} idB58Str - peer id string in base58
* @param {PeerStreams} peerStreams PubSub peer * @param {DuplexIterableStream} stream - inbound stream
* @param {PeerStreams} peerStreams - PubSub peer
* @returns {Promise<void>} * @returns {Promise<void>}
*/ */
_processMessages(idB58Str: string, stream: any, peerStreams: import("./peer-streams")): Promise<void>; _processMessages(idB58Str: string, stream: any, peerStreams: import("./peer-streams")): Promise<void>;
/** /**
* Handles an rpc request from a peer * Handles an rpc request from a peer
* @param {String} idB58Str *
* @param {string} idB58Str
* @param {PeerStreams} peerStreams * @param {PeerStreams} peerStreams
* @param {RPC} rpc * @param {RPC} rpc
* @returns {boolean} * @returns {boolean}
@ -163,31 +173,36 @@ declare class PubsubBaseProtocol {
_processRpc(idB58Str: string, peerStreams: import("./peer-streams"), rpc: any): boolean; _processRpc(idB58Str: string, peerStreams: import("./peer-streams"), rpc: any): boolean;
/** /**
* Handles a subscription change from a peer * Handles a subscription change from a peer
*
* @param {string} id * @param {string} id
* @param {RPC.SubOpt} subOpt * @param {RPC.SubOpt} subOpt
*/ */
_processRpcSubOpt(id: string, subOpt: any): void; _processRpcSubOpt(id: string, subOpt: any): void;
/** /**
* Handles an message from a peer * Handles an message from a peer
*
* @param {InMessage} msg * @param {InMessage} msg
* @returns {Promise<void>} * @returns {Promise<void>}
*/ */
_processRpcMessage(msg: InMessage): Promise<void>; _processRpcMessage(msg: InMessage): Promise<void>;
/** /**
* Emit a message from a peer * Emit a message from a peer
*
* @param {InMessage} message * @param {InMessage} message
*/ */
_emitMessage(message: InMessage): void; _emitMessage(message: InMessage): void;
/** /**
* The default msgID implementation * The default msgID implementation
* Child class can override this. * Child class can override this.
* @param {RPC.Message} msg the message object *
* @param {RPC.Message} msg - the message object
* @returns {Uint8Array} message id as bytes * @returns {Uint8Array} message id as bytes
*/ */
getMsgId(msg: any): Uint8Array; getMsgId(msg: any): Uint8Array;
/** /**
* Whether to accept a message from a peer * Whether to accept a message from a peer
* Override to create a graylist * Override to create a graylist
*
* @override * @override
* @param {string} id * @param {string} id
* @returns {boolean} * @returns {boolean}
@ -196,6 +211,7 @@ declare class PubsubBaseProtocol {
/** /**
* Decode Uint8Array into an RPC object. * Decode Uint8Array into an RPC object.
* This can be override to use a custom router protobuf. * This can be override to use a custom router protobuf.
*
* @param {Uint8Array} bytes * @param {Uint8Array} bytes
* @returns {RPC} * @returns {RPC}
*/ */
@ -203,28 +219,32 @@ declare class PubsubBaseProtocol {
/** /**
* Encode RPC object into a Uint8Array. * Encode RPC object into a Uint8Array.
* This can be override to use a custom router protobuf. * This can be override to use a custom router protobuf.
*
* @param {RPC} rpc * @param {RPC} rpc
* @returns {Uint8Array} * @returns {Uint8Array}
*/ */
_encodeRpc(rpc: any): Uint8Array; _encodeRpc(rpc: any): Uint8Array;
/** /**
* Send an rpc object to a peer * Send an rpc object to a peer
* @param {string} id peer id *
* @param {string} id - peer id
* @param {RPC} rpc * @param {RPC} rpc
* @returns {void} * @returns {void}
*/ */
_sendRpc(id: string, rpc: any): void; _sendRpc(id: string, rpc: any): void;
/** /**
* Send subscroptions to a peer * Send subscroptions to a peer
* @param {string} id peer id *
* @param {string} id - peer id
* @param {string[]} topics * @param {string[]} topics
* @param {boolean} subscribe set to false for unsubscriptions * @param {boolean} subscribe - set to false for unsubscriptions
* @returns {void} * @returns {void}
*/ */
_sendSubscriptions(id: string, topics: string[], subscribe: boolean): void; _sendSubscriptions(id: string, topics: string[], subscribe: boolean): void;
/** /**
* Validates the given message. The signature will be checked for authenticity. * Validates the given message. The signature will be checked for authenticity.
* Throws an error on invalid messages * Throws an error on invalid messages
*
* @param {InMessage} message * @param {InMessage} message
* @returns {Promise<void>} * @returns {Promise<void>}
*/ */
@ -232,19 +252,22 @@ declare class PubsubBaseProtocol {
/** /**
* Normalizes the message and signs it, if signing is enabled. * Normalizes the message and signs it, if signing is enabled.
* Should be used by the routers to create the message to send. * Should be used by the routers to create the message to send.
*
* @private * @private
* @param {Message} message * @param {Message} message
* @returns {Promise<Message>} * @returns {Promise<Message>}
*/ */
_buildMessage(message: any): Promise<any>; private _buildMessage;
/** /**
* Get a list of the peer-ids that are subscribed to one topic. * Get a list of the peer-ids that are subscribed to one topic.
*
* @param {string} topic * @param {string} topic
* @returns {Array<string>} * @returns {Array<string>}
*/ */
getSubscribers(topic: string): string[]; getSubscribers(topic: string): Array<string>;
/** /**
* Publishes messages to all subscribed peers * Publishes messages to all subscribed peers
*
* @override * @override
* @param {string} topic * @param {string} topic
* @param {Buffer} message * @param {Buffer} message
@ -254,6 +277,7 @@ declare class PubsubBaseProtocol {
/** /**
* Overriding the implementation of publish should handle the appropriate algorithms for the publish/subscriber implementation. * 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 * For example, a Floodsub implementation might simply publish each message to each topic for every peer
*
* @abstract * @abstract
* @param {InMessage} message * @param {InMessage} message
* @returns {Promise<void>} * @returns {Promise<void>}
@ -262,6 +286,7 @@ declare class PubsubBaseProtocol {
_publish(message: InMessage): Promise<void>; _publish(message: InMessage): Promise<void>;
/** /**
* Subscribes to a given topic. * Subscribes to a given topic.
*
* @abstract * @abstract
* @param {string} topic * @param {string} topic
* @returns {void} * @returns {void}
@ -269,6 +294,7 @@ declare class PubsubBaseProtocol {
subscribe(topic: string): void; subscribe(topic: string): void;
/** /**
* Unsubscribe from the given topic. * Unsubscribe from the given topic.
*
* @override * @override
* @param {string} topic * @param {string} topic
* @returns {void} * @returns {void}
@ -276,19 +302,16 @@ declare class PubsubBaseProtocol {
unsubscribe(topic: string): void; unsubscribe(topic: string): void;
/** /**
* Get the list of topics which the peer is subscribed to. * Get the list of topics which the peer is subscribed to.
*
* @override * @override
* @returns {Array<String>} * @returns {Array<string>}
*/ */
getTopics(): string[]; getTopics(): Array<string>;
} }
declare namespace PubsubBaseProtocol { declare namespace PubsubBaseProtocol {
export { message, utils, SignaturePolicy, InMessage, PeerId }; export { message, utils, SignaturePolicy, InMessage, PeerId };
} }
type PeerId = import("peer-id"); type PeerId = import("peer-id");
/**
* Topic validator function
*/
type validator = (arg0: string, arg1: InMessage) => Promise<void>;
type InMessage = { type InMessage = {
from?: string; from?: string;
receivedFrom: string; receivedFrom: string;

75
src/pubsub/index.js
View File

@ -36,18 +36,18 @@ const {
*/ */
/** /**
* PubsubBaseProtocol handles the peers and connections logic for pubsub routers * PubsubBaseProtocol handles the peers and connections logic for pubsub routers
* and specifies the API that pubsub routers should have. * and specifies the API that pubsub routers should have.
*/ */
class PubsubBaseProtocol extends EventEmitter { class PubsubBaseProtocol extends EventEmitter {
/** /**
* @param {Object} props * @param {Object} props
* @param {String} props.debugName log namespace * @param {string} props.debugName - log namespace
* @param {Array<string>|string} props.multicodecs protocol identificers to connect * @param {Array<string>|string} props.multicodecs - protocol identificers to connect
* @param {Libp2p} props.libp2p * @param {Libp2p} props.libp2p
* @param {SignaturePolicy} [props.globalSignaturePolicy = SignaturePolicy.StrictSign] defines how signatures should be handled * @param {SignaturePolicy} [props.globalSignaturePolicy = SignaturePolicy.StrictSign] - defines how signatures should be handled
* @param {boolean} [props.canRelayMessage = false] if can relay messages not subscribed * @param {boolean} [props.canRelayMessage = false] - if can relay messages not subscribed
* @param {boolean} [props.emitSelf = false] if publish should emit to self, if subscribed * @param {boolean} [props.emitSelf = false] - if publish should emit to self, if subscribed
* @abstract * @abstract
*/ */
constructor ({ constructor ({
@ -97,6 +97,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* List of our subscriptions * List of our subscriptions
*
* @type {Set<string>} * @type {Set<string>}
*/ */
this.subscriptions = new Set() this.subscriptions = new Set()
@ -122,18 +123,21 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* If router can relay received messages, even if not subscribed * If router can relay received messages, even if not subscribed
*
* @type {boolean} * @type {boolean}
*/ */
this.canRelayMessage = canRelayMessage this.canRelayMessage = canRelayMessage
/** /**
* if publish should emit to self, if subscribed * if publish should emit to self, if subscribed
*
* @type {boolean} * @type {boolean}
*/ */
this.emitSelf = emitSelf this.emitSelf = emitSelf
/** /**
* Topic validator function * Topic validator function
*
* @typedef {function(string, InMessage): Promise<void>} validator * @typedef {function(string, InMessage): Promise<void>} validator
*/ */
/** /**
@ -141,6 +145,7 @@ class PubsubBaseProtocol extends EventEmitter {
* *
* Keyed by topic * Keyed by topic
* Topic validators are functions with the following input: * Topic validators are functions with the following input:
*
* @type {Map<string, validator>} * @type {Map<string, validator>}
*/ */
this.topicValidators = new Map() this.topicValidators = new Map()
@ -155,6 +160,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Register the pubsub protocol onto the libp2p node. * Register the pubsub protocol onto the libp2p node.
*
* @returns {void} * @returns {void}
*/ */
start () { start () {
@ -184,6 +190,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Unregister the pubsub protocol and the streams with other peers will be closed. * Unregister the pubsub protocol and the streams with other peers will be closed.
*
* @returns {void} * @returns {void}
*/ */
stop () { stop () {
@ -205,11 +212,12 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* On an inbound stream opened. * On an inbound stream opened.
*
* @private * @private
* @param {Object} props * @param {Object} props
* @param {string} props.protocol * @param {string} props.protocol
* @param {DuplexIterableStream} props.stream * @param {DuplexIterableStream} props.stream
* @param {Connection} props.connection connection * @param {Connection} props.connection - connection
*/ */
_onIncomingStream ({ protocol, stream, connection }) { _onIncomingStream ({ protocol, stream, connection }) {
const peerId = connection.remotePeer const peerId = connection.remotePeer
@ -222,9 +230,10 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Registrar notifies an established connection with pubsub protocol. * Registrar notifies an established connection with pubsub protocol.
*
* @private * @private
* @param {PeerId} peerId remote peer-id * @param {PeerId} peerId - remote peer-id
* @param {Connection} conn connection to the peer * @param {Connection} conn - connection to the peer
*/ */
async _onPeerConnected (peerId, conn) { async _onPeerConnected (peerId, conn) {
const idB58Str = peerId.toB58String() const idB58Str = peerId.toB58String()
@ -244,9 +253,10 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Registrar notifies a closing connection with pubsub protocol. * Registrar notifies a closing connection with pubsub protocol.
*
* @private * @private
* @param {PeerId} peerId peerId * @param {PeerId} peerId - peerId
* @param {Error} err error for connection end * @param {Error} err - error for connection end
*/ */
_onPeerDisconnected (peerId, err) { _onPeerDisconnected (peerId, err) {
const idB58Str = peerId.toB58String() const idB58Str = peerId.toB58String()
@ -257,6 +267,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Notifies the router that a peer has been connected * Notifies the router that a peer has been connected
*
* @private * @private
* @param {PeerId} peerId * @param {PeerId} peerId
* @param {string} protocol * @param {string} protocol
@ -287,6 +298,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Notifies the router that a peer has been disconnected. * Notifies the router that a peer has been disconnected.
*
* @private * @private
* @param {PeerId} peerId * @param {PeerId} peerId
* @returns {PeerStreams | undefined} * @returns {PeerStreams | undefined}
@ -317,9 +329,10 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Responsible for processing each RPC message received by other peers. * Responsible for processing each RPC message received by other peers.
* @param {string} idB58Str peer id string in base58 *
* @param {DuplexIterableStream} stream inbound stream * @param {string} idB58Str - peer id string in base58
* @param {PeerStreams} peerStreams PubSub peer * @param {DuplexIterableStream} stream - inbound stream
* @param {PeerStreams} peerStreams - PubSub peer
* @returns {Promise<void>} * @returns {Promise<void>}
*/ */
async _processMessages (idB58Str, stream, peerStreams) { async _processMessages (idB58Str, stream, peerStreams) {
@ -342,7 +355,8 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Handles an rpc request from a peer * Handles an rpc request from a peer
* @param {String} idB58Str *
* @param {string} idB58Str
* @param {PeerStreams} peerStreams * @param {PeerStreams} peerStreams
* @param {RPC} rpc * @param {RPC} rpc
* @returns {boolean} * @returns {boolean}
@ -378,6 +392,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Handles a subscription change from a peer * Handles a subscription change from a peer
*
* @param {string} id * @param {string} id
* @param {RPC.SubOpt} subOpt * @param {RPC.SubOpt} subOpt
*/ */
@ -401,6 +416,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Handles an message from a peer * Handles an message from a peer
*
* @param {InMessage} msg * @param {InMessage} msg
* @returns {Promise<void>} * @returns {Promise<void>}
*/ */
@ -425,6 +441,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Emit a message from a peer * Emit a message from a peer
*
* @param {InMessage} message * @param {InMessage} message
*/ */
_emitMessage (message) { _emitMessage (message) {
@ -438,7 +455,8 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* The default msgID implementation * The default msgID implementation
* Child class can override this. * Child class can override this.
* @param {RPC.Message} msg the message object *
* @param {RPC.Message} msg - the message object
* @returns {Uint8Array} message id as bytes * @returns {Uint8Array} message id as bytes
*/ */
getMsgId (msg) { getMsgId (msg) {
@ -456,6 +474,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Whether to accept a message from a peer * Whether to accept a message from a peer
* Override to create a graylist * Override to create a graylist
*
* @override * @override
* @param {string} id * @param {string} id
* @returns {boolean} * @returns {boolean}
@ -467,6 +486,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Decode Uint8Array into an RPC object. * Decode Uint8Array into an RPC object.
* This can be override to use a custom router protobuf. * This can be override to use a custom router protobuf.
*
* @param {Uint8Array} bytes * @param {Uint8Array} bytes
* @returns {RPC} * @returns {RPC}
*/ */
@ -477,6 +497,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Encode RPC object into a Uint8Array. * Encode RPC object into a Uint8Array.
* This can be override to use a custom router protobuf. * This can be override to use a custom router protobuf.
*
* @param {RPC} rpc * @param {RPC} rpc
* @returns {Uint8Array} * @returns {Uint8Array}
*/ */
@ -486,7 +507,8 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Send an rpc object to a peer * Send an rpc object to a peer
* @param {string} id peer id *
* @param {string} id - peer id
* @param {RPC} rpc * @param {RPC} rpc
* @returns {void} * @returns {void}
*/ */
@ -503,9 +525,10 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Send subscroptions to a peer * Send subscroptions to a peer
* @param {string} id peer id *
* @param {string} id - peer id
* @param {string[]} topics * @param {string[]} topics
* @param {boolean} subscribe set to false for unsubscriptions * @param {boolean} subscribe - set to false for unsubscriptions
* @returns {void} * @returns {void}
*/ */
_sendSubscriptions (id, topics, subscribe) { _sendSubscriptions (id, topics, subscribe) {
@ -517,6 +540,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Validates the given message. The signature will be checked for authenticity. * Validates the given message. The signature will be checked for authenticity.
* Throws an error on invalid messages * Throws an error on invalid messages
*
* @param {InMessage} message * @param {InMessage} message
* @returns {Promise<void>} * @returns {Promise<void>}
*/ */
@ -563,6 +587,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Normalizes the message and signs it, if signing is enabled. * Normalizes the message and signs it, if signing is enabled.
* Should be used by the routers to create the message to send. * Should be used by the routers to create the message to send.
*
* @private * @private
* @param {Message} message * @param {Message} message
* @returns {Promise<Message>} * @returns {Promise<Message>}
@ -585,6 +610,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Get a list of the peer-ids that are subscribed to one topic. * Get a list of the peer-ids that are subscribed to one topic.
*
* @param {string} topic * @param {string} topic
* @returns {Array<string>} * @returns {Array<string>}
*/ */
@ -606,6 +632,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Publishes messages to all subscribed peers * Publishes messages to all subscribed peers
*
* @override * @override
* @param {string} topic * @param {string} topic
* @param {Buffer} message * @param {Buffer} message
@ -639,6 +666,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Overriding the implementation of publish should handle the appropriate algorithms for the publish/subscriber implementation. * 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 * For example, a Floodsub implementation might simply publish each message to each topic for every peer
*
* @abstract * @abstract
* @param {InMessage} message * @param {InMessage} message
* @returns {Promise<void>} * @returns {Promise<void>}
@ -650,6 +678,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Subscribes to a given topic. * Subscribes to a given topic.
*
* @abstract * @abstract
* @param {string} topic * @param {string} topic
* @returns {void} * @returns {void}
@ -667,6 +696,7 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Unsubscribe from the given topic. * Unsubscribe from the given topic.
*
* @override * @override
* @param {string} topic * @param {string} topic
* @returns {void} * @returns {void}
@ -684,8 +714,9 @@ class PubsubBaseProtocol extends EventEmitter {
/** /**
* Get the list of topics which the peer is subscribed to. * Get the list of topics which the peer is subscribed to.
*
* @override * @override
* @returns {Array<String>} * @returns {Array<string>}
*/ */
getTopics () { getTopics () {
if (!this.started) { if (!this.started) {

3
src/pubsub/message/sign.d.ts vendored
View File

@ -17,7 +17,8 @@ export function signMessage(peerId: import("peer-id"), message: any): Promise<an
export const SignPrefix: any; export const SignPrefix: any;
/** /**
* Verifies the signature of the given message * Verifies the signature of the given message
*
* @param {InMessage} message * @param {InMessage} message
* @returns {Promise<Boolean>} * @returns {Promise<boolean>}
*/ */
export function verifySignature(message: any): Promise<boolean>; export function verifySignature(message: any): Promise<boolean>;

3
src/pubsub/message/sign.js
View File

@ -31,8 +31,9 @@ async function signMessage (peerId, message) {
/** /**
* Verifies the signature of the given message * Verifies the signature of the given message
*
* @param {InMessage} message * @param {InMessage} message
* @returns {Promise<Boolean>} * @returns {Promise<boolean>}
*/ */
async function verifySignature (message) { async function verifySignature (message) {
// Get message sans the signature // Get message sans the signature

22
src/pubsub/peer-streams.d.ts vendored
View File

@ -16,12 +16,12 @@ export = PeerStreams;
*/ */
declare class PeerStreams { declare class PeerStreams {
/** /**
* @param {object} properties properties of the PeerStreams. * @param {object} properties - properties of the PeerStreams.
* @param {PeerId} properties.id * @param {PeerId} properties.id
* @param {string} properties.protocol * @param {string} properties.protocol
*/ */
constructor({ id, protocol }: { constructor({ id, protocol }: {
id: import("peer-id"); id: PeerId;
protocol: string; protocol: string;
}); });
/** /**
@ -30,34 +30,40 @@ declare class PeerStreams {
id: import('peer-id'); id: import('peer-id');
/** /**
* Established protocol * Established protocol
*
* @type {string} * @type {string}
*/ */
protocol: string; protocol: string;
/** /**
* The raw outbound stream, as retrieved from conn.newStream * The raw outbound stream, as retrieved from conn.newStream
*
* @private * @private
* @type {DuplexIterableStream} * @type {DuplexIterableStream}
*/ */
_rawOutboundStream: DuplexIterableStream; private _rawOutboundStream;
/** /**
* The raw inbound stream, as retrieved from the callback from libp2p.handle * The raw inbound stream, as retrieved from the callback from libp2p.handle
*
* @private * @private
* @type {DuplexIterableStream} * @type {DuplexIterableStream}
*/ */
_rawInboundStream: DuplexIterableStream; private _rawInboundStream;
/** /**
* An AbortController for controlled shutdown of the inbound stream * An AbortController for controlled shutdown of the inbound stream
*
* @private * @private
* @type {typeof AbortController} * @type {typeof AbortController}
*/ */
_inboundAbortController: typeof AbortController; private _inboundAbortController;
/** /**
* Write stream -- its preferable to use the write method * Write stream -- its preferable to use the write method
*
* @type {import('it-pushable').Pushable<Uint8Array>>} * @type {import('it-pushable').Pushable<Uint8Array>>}
*/ */
outboundStream: import('it-pushable').Pushable<Uint8Array>; outboundStream: import('it-pushable').Pushable<Uint8Array>;
/** /**
* Read stream * Read stream
*
* @type {DuplexIterableStream} * @type {DuplexIterableStream}
*/ */
inboundStream: DuplexIterableStream; inboundStream: DuplexIterableStream;
@ -97,6 +103,7 @@ declare class PeerStreams {
attachOutboundStream(stream: any): Promise<void>; attachOutboundStream(stream: any): Promise<void>;
/** /**
* Closes the open connection to peer * Closes the open connection to peer
*
* @returns {void} * @returns {void}
*/ */
close(): void; close(): void;
@ -106,8 +113,7 @@ declare namespace PeerStreams {
} }
type DuplexIterableStream = { type DuplexIterableStream = {
sink: Sink; sink: Sink;
source: () => AsyncIterator<Uint8Array, any, undefined>; source: () => AsyncIterator<Uint8Array>;
}; };
declare const AbortController: typeof import("abort-controller");
type Sink = (source: Uint8Array) => Promise<Uint8Array>;
type PeerId = import("peer-id"); type PeerId = import("peer-id");
type Sink = (source: Uint8Array) => Promise<Uint8Array>;

9
src/pubsub/peer-streams.js
View File

@ -30,7 +30,7 @@ log.error = debug('libp2p-pubsub:peer-streams:error')
*/ */
class PeerStreams extends EventEmitter { class PeerStreams extends EventEmitter {
/** /**
* @param {object} properties properties of the PeerStreams. * @param {object} properties - properties of the PeerStreams.
* @param {PeerId} properties.id * @param {PeerId} properties.id
* @param {string} properties.protocol * @param {string} properties.protocol
*/ */
@ -43,34 +43,40 @@ class PeerStreams extends EventEmitter {
this.id = id this.id = id
/** /**
* Established protocol * Established protocol
*
* @type {string} * @type {string}
*/ */
this.protocol = protocol this.protocol = protocol
/** /**
* The raw outbound stream, as retrieved from conn.newStream * The raw outbound stream, as retrieved from conn.newStream
*
* @private * @private
* @type {DuplexIterableStream} * @type {DuplexIterableStream}
*/ */
this._rawOutboundStream = null this._rawOutboundStream = null
/** /**
* The raw inbound stream, as retrieved from the callback from libp2p.handle * The raw inbound stream, as retrieved from the callback from libp2p.handle
*
* @private * @private
* @type {DuplexIterableStream} * @type {DuplexIterableStream}
*/ */
this._rawInboundStream = null this._rawInboundStream = null
/** /**
* An AbortController for controlled shutdown of the inbound stream * An AbortController for controlled shutdown of the inbound stream
*
* @private * @private
* @type {typeof AbortController} * @type {typeof AbortController}
*/ */
this._inboundAbortController = null this._inboundAbortController = null
/** /**
* Write stream -- its preferable to use the write method * Write stream -- its preferable to use the write method
*
* @type {import('it-pushable').Pushable<Uint8Array>>} * @type {import('it-pushable').Pushable<Uint8Array>>}
*/ */
this.outboundStream = null this.outboundStream = null
/** /**
* Read stream * Read stream
*
* @type {DuplexIterableStream} * @type {DuplexIterableStream}
*/ */
this.inboundStream = null this.inboundStream = null
@ -179,6 +185,7 @@ class PeerStreams extends EventEmitter {
/** /**
* Closes the open connection to peer * Closes the open connection to peer
*
* @returns {void} * @returns {void}
*/ */
close () { close () {

4
src/pubsub/signature-policy.d.ts vendored
View File

@ -1,4 +1,4 @@
export namespace SignaturePolicy { export namespace SignaturePolicy {
export const StrictSign: string; const StrictSign: string;
export const StrictNoSign: string; const StrictNoSign: string;
} }

6
src/pubsub/utils.d.ts vendored
View File

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

7
src/pubsub/utils.js
View File

@ -85,9 +85,10 @@ exports.ensureArray = (maybeArray) => {
/** /**
* Ensures `message.from` is base58 encoded * Ensures `message.from` is base58 encoded
*
* @param {object} message * @param {object} message
* @param {String} peerId * @param {string} peerId
* @return {object} * @returns {object}
*/ */
exports.normalizeInRpcMessage = (message, peerId) => { exports.normalizeInRpcMessage = (message, peerId) => {
const m = Object.assign({}, message) const m = Object.assign({}, message)
@ -102,7 +103,7 @@ exports.normalizeInRpcMessage = (message, peerId) => {
/** /**
* @param {object} message * @param {object} message
* @return {object} * @returns {object}
*/ */
exports.normalizeOutRpcMessage = (message) => { exports.normalizeOutRpcMessage = (message) => {
const m = Object.assign({}, message) const m = Object.assign({}, message)

7
src/record/index.d.ts vendored
View File

@ -4,9 +4,9 @@ export = Record;
*/ */
declare class Record { declare class Record {
/** /**
* @constructor * @class
* @param {String} domain signature domain * @param {string} domain - signature domain
* @param {Uint8Array} codec identifier of the type of record * @param {Uint8Array} codec - identifier of the type of record
*/ */
constructor(domain: string, codec: Uint8Array); constructor(domain: string, codec: Uint8Array);
domain: string; domain: string;
@ -17,6 +17,7 @@ declare class Record {
marshal(): void; marshal(): void;
/** /**
* Verifies if the other provided Record is identical to this one. * Verifies if the other provided Record is identical to this one.
*
* @param {Record} other * @param {Record} other
*/ */
equals(other: Record): void; equals(other: Record): void;

7
src/record/index.js
View File

@ -7,9 +7,9 @@ const errcode = require('err-code')
*/ */
class Record { class Record {
/** /**
* @constructor * @class
* @param {String} domain signature domain * @param {string} domain - signature domain
* @param {Uint8Array} codec identifier of the type of record * @param {Uint8Array} codec - identifier of the type of record
*/ */
constructor (domain, codec) { constructor (domain, codec) {
this.domain = domain this.domain = domain
@ -25,6 +25,7 @@ class Record {
/** /**
* Verifies if the other provided Record is identical to this one. * Verifies if the other provided Record is identical to this one.
*
* @param {Record} other * @param {Record} other
*/ */
equals (other) { equals (other) {

5
src/stream-muxer/tests/base-test.js
View File

@ -20,8 +20,9 @@ async function closeAndWait (stream) {
/** /**
* A tick is considered valid if it happened between now * A tick is considered valid if it happened between now
* and `ms` milliseconds ago * and `ms` milliseconds ago
* @param {number} date Time in ticks *
* @param {number} ms max milliseconds that should have expired * @param {number} date - Time in ticks
* @param {number} ms - max milliseconds that should have expired
* @returns {boolean} * @returns {boolean}
*/ */
function isValidTick (date, ms = 5000) { function isValidTick (date, ms = 5000) {

0
src/stream-muxer/types.ts Normal file
View File

69
src/topology/index.d.ts vendored
View File

@ -1,42 +1,63 @@
declare const _exports: Topology; declare const _exports: Topology;
export = _exports; export = _exports;
export type PeerId = import("peer-id");
export type TopologyHandlers = {
/**
* - protocol "onConnect" handler
*/
onConnect?: (peerId: PeerId, conn: import('../connection')) => void;
/**
* - protocol "onDisconnect" handler
*/
onDisconnect?: (peerId: PeerId) => void;
};
export type TopologyOptions = {
/**
* - minimum needed connections
*/
min?: number;
/**
* - maximum needed connections
*/
max?: number;
handlers?: TopologyHandlers;
};
/**
* @typedef {import('peer-id')} PeerId
*/
/**
* @typedef {Object} TopologyHandlers
* @property {(peerId: PeerId, conn: import('../connection')) => void} [handlers.onConnect] - protocol "onConnect" handler
* @property {(peerId: PeerId) => void} [handlers.onDisconnect] - protocol "onDisconnect" handler
*
* @typedef {Object} TopologyOptions
* @property {number} [props.min = 0] - minimum needed connections
* @property {number} [props.max = Infinity] - maximum needed connections
* @property {TopologyHandlers} [props.handlers]
*/
declare class Topology { declare class Topology {
/** /**
* @param {Object} props * @class
* @param {number} props.min minimum needed connections (default: 0) * @param {TopologyHandlers} options
* @param {number} props.max maximum needed connections (default: Infinity)
* @param {Object} [props.handlers]
* @param {function} [props.handlers.onConnect] protocol "onConnect" handler
* @param {function} [props.handlers.onDisconnect] protocol "onDisconnect" handler
* @constructor
*/ */
constructor({ min, max, handlers }: { constructor({ min, max, handlers }: TopologyHandlers);
min: number; min: any;
max: number; max: any;
handlers?: { _onConnect: any;
onConnect?: Function; _onDisconnect: any;
onDisconnect?: Function;
};
});
min: number;
max: number;
_onConnect: Function;
_onDisconnect: Function;
/** /**
* Set of peers that support the protocol. * Set of peers that support the protocol.
*
* @type {Set<string>} * @type {Set<string>}
*/ */
peers: Set<string>; peers: Set<string>;
set registrar(arg: any); set registrar(arg: any);
_registrar: any; _registrar: any;
/**
* @typedef PeerId
* @type {import('peer-id')}
*/
/** /**
* Notify about peer disconnected event. * Notify about peer disconnected event.
*
* @param {PeerId} peerId * @param {PeerId} peerId
* @returns {void} * @returns {void}
*/ */
disconnect(peerId: import("peer-id")): void; disconnect(peerId: PeerId): void;
} }

33
src/topology/index.js
View File

@ -3,15 +3,25 @@
const withIs = require('class-is') const withIs = require('class-is')
const noop = () => {} const noop = () => {}
/**
* @typedef {import('peer-id')} PeerId
*/
/**
* @typedef {Object} TopologyHandlers
* @property {(peerId: PeerId, conn: import('../connection')) => void} [handlers.onConnect] - protocol "onConnect" handler
* @property {(peerId: PeerId) => void} [handlers.onDisconnect] - protocol "onDisconnect" handler
*
* @typedef {Object} TopologyOptions
* @property {number} [props.min = 0] - minimum needed connections
* @property {number} [props.max = Infinity] - maximum needed connections
* @property {TopologyHandlers} [props.handlers]
*/
class Topology { class Topology {
/** /**
* @param {Object} props * @class
* @param {number} props.min minimum needed connections (default: 0) * @param {TopologyHandlers} options
* @param {number} props.max maximum needed connections (default: Infinity)
* @param {Object} [props.handlers]
* @param {function} [props.handlers.onConnect] protocol "onConnect" handler
* @param {function} [props.handlers.onDisconnect] protocol "onDisconnect" handler
* @constructor
*/ */
constructor ({ constructor ({
min = 0, min = 0,
@ -27,22 +37,19 @@ class Topology {
/** /**
* Set of peers that support the protocol. * Set of peers that support the protocol.
*
* @type {Set<string>} * @type {Set<string>}
*/ */
this.peers = new Set() this.peers = new Set()
} }
set registrar (registrar) { set registrar (registrar) { // eslint-disable-line
this._registrar = registrar this._registrar = registrar
} }
/**
* @typedef PeerId
* @type {import('peer-id')}
*/
/** /**
* Notify about peer disconnected event. * Notify about peer disconnected event.
*
* @param {PeerId} peerId * @param {PeerId} peerId
* @returns {void} * @returns {void}
*/ */

35
src/topology/multicodec-topology.d.ts vendored
View File

@ -2,38 +2,26 @@ declare const _exports: MulticodecTopology;
export = _exports; export = _exports;
declare class MulticodecTopology { declare class MulticodecTopology {
/** /**
* @param {Object} props * @class
* @param {number} props.min minimum needed connections (default: 0) * @param {import('./').TopologyOptions} options
* @param {number} props.max maximum needed connections (default: Infinity)
* @param {Array<string>} props.multicodecs protocol multicodecs
* @param {Object} props.handlers
* @param {function} props.handlers.onConnect protocol "onConnect" handler
* @param {function} props.handlers.onDisconnect protocol "onDisconnect" handler
* @constructor
*/ */
constructor({ min, max, multicodecs, handlers }: { constructor({ min, max, handlers, multicodecs, }: import('./').TopologyOptions);
min: number; multicodecs: any[];
max: number;
multicodecs: string[];
handlers: {
onConnect: Function;
onDisconnect: Function;
};
});
multicodecs: string[];
_registrar: any; _registrar: any;
/** /**
* Check if a new peer support the multicodecs for this topology. * Check if a new peer support the multicodecs for this topology.
*
* @param {Object} props * @param {Object} props
* @param {PeerId} props.peerId * @param {PeerId} props.peerId
* @param {Array<string>} props.protocols * @param {Array<string>} props.protocols
*/ */
_onProtocolChange({ peerId, protocols }: { _onProtocolChange({ peerId, protocols }: {
peerId: any; peerId: any;
protocols: string[]; protocols: Array<string>;
}): void; }): void;
/** /**
* Verify if a new connected peer has a topology multicodec and call _onConnect. * Verify if a new connected peer has a topology multicodec and call _onConnect.
*
* @param {Connection} connection * @param {Connection} connection
* @returns {void} * @returns {void}
*/ */
@ -41,12 +29,13 @@ declare class MulticodecTopology {
set registrar(arg: any); set registrar(arg: any);
/** /**
* Update topology. * Update topology.
*
* @param {Array<{id: PeerId, multiaddrs: Array<Multiaddr>, protocols: Array<string>}>} peerDataIterable * @param {Array<{id: PeerId, multiaddrs: Array<Multiaddr>, protocols: Array<string>}>} peerDataIterable
* @returns {void} * @returns {void}
*/ */
_updatePeers(peerDataIterable: { _updatePeers(peerDataIterable: Array<{
id: any; id: any;
multiaddrs: any[]; multiaddrs: Array<any>;
protocols: string[]; protocols: Array<string>;
}[]): void; }>): void;
} }

21
src/topology/multicodec-topology.js
View File

@ -6,20 +6,14 @@ const Topology = require('./index')
class MulticodecTopology extends Topology { class MulticodecTopology extends Topology {
/** /**
* @param {Object} props * @class
* @param {number} props.min minimum needed connections (default: 0) * @param {import('./').TopologyOptions} options
* @param {number} props.max maximum needed connections (default: Infinity)
* @param {Array<string>} props.multicodecs protocol multicodecs
* @param {Object} props.handlers
* @param {function} props.handlers.onConnect protocol "onConnect" handler
* @param {function} props.handlers.onDisconnect protocol "onDisconnect" handler
* @constructor
*/ */
constructor ({ constructor ({
min, min = 0,
max, max = Infinity,
handlers = {},
multicodecs, multicodecs,
handlers
}) { }) {
super({ min, max, handlers }) super({ min, max, handlers })
@ -46,7 +40,7 @@ class MulticodecTopology extends Topology {
this._onPeerConnect = this._onPeerConnect.bind(this) this._onPeerConnect = this._onPeerConnect.bind(this)
} }
set registrar (registrar) { set registrar (registrar) { // eslint-disable-line
this._registrar = registrar this._registrar = registrar
this._registrar.peerStore.on('change:protocols', this._onProtocolChange) this._registrar.peerStore.on('change:protocols', this._onProtocolChange)
this._registrar.connectionManager.on('peer:connect', this._onPeerConnect) this._registrar.connectionManager.on('peer:connect', this._onPeerConnect)
@ -57,6 +51,7 @@ class MulticodecTopology extends Topology {
/** /**
* Update topology. * Update topology.
*
* @param {Array<{id: PeerId, multiaddrs: Array<Multiaddr>, protocols: Array<string>}>} peerDataIterable * @param {Array<{id: PeerId, multiaddrs: Array<Multiaddr>, protocols: Array<string>}>} peerDataIterable
* @returns {void} * @returns {void}
*/ */
@ -77,6 +72,7 @@ class MulticodecTopology extends Topology {
/** /**
* Check if a new peer support the multicodecs for this topology. * Check if a new peer support the multicodecs for this topology.
*
* @param {Object} props * @param {Object} props
* @param {PeerId} props.peerId * @param {PeerId} props.peerId
* @param {Array<string>} props.protocols * @param {Array<string>} props.protocols
@ -102,6 +98,7 @@ class MulticodecTopology extends Topology {
/** /**
* Verify if a new connected peer has a topology multicodec and call _onConnect. * Verify if a new connected peer has a topology multicodec and call _onConnect.
*
* @param {Connection} connection * @param {Connection} connection
* @returns {void} * @returns {void}
*/ */

5
src/transport/tests/utils/index.js
View File

@ -4,8 +4,9 @@ module.exports = {
/** /**
* A tick is considered valid if it happened between now * A tick is considered valid if it happened between now
* and `ms` milliseconds ago * and `ms` milliseconds ago
* @param {number} date Time in ticks *
* @param {number} ms max milliseconds that should have expired * @param {number} date - Time in ticks
* @param {number} ms - max milliseconds that should have expired
* @returns {boolean} * @returns {boolean}
*/ */
isValidTick: function isValidTick (date, ms = 5000) { isValidTick: function isValidTick (date, ms = 5000) {

103
src/transport/types.ts Normal file
View File

@ -0,0 +1,103 @@
export default Transport;
declare class Transport implements TransportInterface {
constructor({ upgrader, ...others }: {
upgrader: Upgrader;
others: any;
});
/**
* Dial a given multiaddr.
* @param {Multiaddr} ma
* @param {Object} [options]
* @returns {Promise<Connection>}
*/
dial(ma: Multiaddr, options?: Object): Promise<Connection>;
/**
* Create transport listeners.
* @param {Object} options
* @param {(Connection) => void} handler
*/
createListener(options: Object, handler: Function): Listener;
/**
* Takes a list of `Multiaddr`s and returns only valid addresses for the transport
* @param {Multiaddr[]} multiaddrs
* @returns {Multiaddr[]}
*/
filter(multiaddrs: Multiaddr[]): Multiaddr[];
}
/**
* A libp2p transport is understood as something that offers a dial and listen interface to establish connections.
*/
interface TransportInterface {
/**
* Dial a given multiaddr.
* @param {Multiaddr} ma
* @param {Object} [options]
* @returns {Promise<Connection>}
*/
dial(ma: Multiaddr, options?: Object): Promise<Connection>;
/**
* Create transport listeners.
* @param {Object} options
* @param {(Connection) => void} handler
*/
createListener(options: Object, handler: Function): Listener;
/**
* Takes a list of `Multiaddr`s and returns only valid addresses for the transport
* @param {Multiaddr[]} multiaddrs
* @returns {Multiaddr[]}
*/
filter(multiaddrs: Multiaddr[]): Multiaddr[];
}
interface Listener {
/**
* Start a listener
* @param {Multiaddr} multiaddr
* @returns {Promise<void>}
*/
listen(multiaddr: Multiaddr): Promise<void>;
/**
* Get listen addresses
* @returns {Multiaddr[]}
*/
getAddrs(): Multiaddr[];
/**
* Close listener
* @returns {Promise<void>}
*/
close(): Promise<void>;
}
interface Upgrader {
/**
* Upgrades an outbound connection on `transport.dial`.
* @param {MultiaddrConnection} maConn
* @returns {Promise<Connection>}
*/
upgradeOutbound(maConn: MultiaddrConnection): Promise<Connection>;
/**
* Upgrades an inbound connection on transport listener.
* @param {MultiaddrConnection} maConn
* @returns {Promise<Connection>}
*/
upgradeInbound(maConn: MultiaddrConnection): Promise<Connection>;
}
type MultiaddrConnection = {
connection: any;
remoteAddr: Multiaddr;
sink: Sink;
source: () => AsyncIterator<Uint8Array, any, undefined>;
}
type Sink = (source: Uint8Array) => Promise<Uint8Array>;
type Connection = typeof import('../connection')
type Multiaddr = import('multiaddr');
declare namespace Transport {
export { Upgrader, Listener, MultiaddrConnection };
}

1
test/connection/compliance.spec.js
View File

@ -13,6 +13,7 @@ describe('compliance tests', () => {
/** /**
* Test setup. `properties` allows the compliance test to override * Test setup. `properties` allows the compliance test to override
* certain values for testing. * certain values for testing.
*
* @param {*} properties * @param {*} properties
*/ */
async setup (properties) { async setup (properties) {