From 698c1df1b4d96729ba1228b8aa37a79bfd75ceef Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Mon, 25 May 2020 16:49:04 +0200 Subject: [PATCH] feat: support dial only on transport manager to tolerate errors (#643) * feat: support dial only on transport manager to tolerate errors * chore: address review * chore: add jsdoc to transport manager tolerance errors --- doc/API.md | 1 + doc/CONFIGURATION.md | 25 +++++++++++ src/config.js | 5 +++ src/index.js | 3 +- src/transport-manager.js | 24 +++++++++- test/transports/transport-manager.spec.js | 54 +++++++++++++++++++++++ 6 files changed, 109 insertions(+), 3 deletions(-) diff --git a/doc/API.md b/doc/API.md index cde9161d..ee4af9c7 100644 --- a/doc/API.md +++ b/doc/API.md @@ -89,6 +89,7 @@ Creates an instance of Libp2p. | [options.addresses] | `{ listen: Array, announce: Array, noAnnounce: Array }` | Addresses for transport listening and to advertise to the network | | [options.config] | `object` | libp2p modules configuration and core configuration | | [options.connectionManager] | [`object`](./CONFIGURATION.md#configuring-connection-manager) | libp2p Connection Manager configuration | +| [options.transportManager] | [`object`](./CONFIGURATION.md#configuring-transport-manager) | libp2p transport manager configuration | | [options.datastore] | `object` | must implement [ipfs/interface-datastore](https://github.com/ipfs/interface-datastore) (in memory datastore will be used if not provided) | | [options.dialer] | [`object`](./CONFIGURATION.md#configuring-dialing) | libp2p Dialer configuration | [options.keychain] | [`object`](./CONFIGURATION.md#setup-with-keychain) | keychain configuration | diff --git a/doc/CONFIGURATION.md b/doc/CONFIGURATION.md index 2e3a4ffa..490f3890 100644 --- a/doc/CONFIGURATION.md +++ b/doc/CONFIGURATION.md @@ -23,6 +23,7 @@ - [Setup with Keychain](#setup-with-keychain) - [Configuring Dialing](#configuring-dialing) - [Configuring Connection Manager](#configuring-connection-manager) + - [Configuring Transport Manager](#configuring-transport-manager) - [Configuring Metrics](#configuring-metrics) - [Configuring PeerStore](#configuring-peerstore) - [Customizing Transports](#customizing-transports) @@ -517,6 +518,30 @@ const node = await Libp2p.create({ }) ``` +#### Configuring Transport Manager + +The Transport Manager is responsible for managing the libp2p transports life cycle. This includes starting listeners for the provided listen addresses, closing these listeners and dialing using the provided transports. By default, if a libp2p node has a list of multiaddrs for listenning on and there are no valid transports for those multiaddrs, libp2p will throw an error on startup and shutdown. However, for some applications it is perfectly acceptable for libp2p nodes to start in dial only mode if all the listen multiaddrs failed. This error tolerance can be enabled as follows: + +```js +const Libp2p = require('libp2p') +const TCP = require('libp2p-tcp') +const MPLEX = require('libp2p-mplex') +const SECIO = require('libp2p-secio') + +const { FaultTolerance } = require('libp2p/src/transport-manager')} + +const node = await Libp2p.create({ + modules: { + transport: [TCP], + streamMuxer: [MPLEX], + connEncryption: [SECIO] + }, + transportManager: { + faultTolerance: FaultTolerance.NO_FATAL + } +}) +``` + #### Configuring Metrics Metrics are disabled in libp2p by default. You can enable and configure them as follows: diff --git a/src/config.js b/src/config.js index 53c9c4c2..f586c6dc 100644 --- a/src/config.js +++ b/src/config.js @@ -3,6 +3,8 @@ const mergeOptions = require('merge-options') const Constants = require('./constants') +const { FaultTolerance } = require('./transport-manager') + const DefaultConfig = { addresses: { listen: [], @@ -12,6 +14,9 @@ const DefaultConfig = { connectionManager: { minPeers: 25 }, + transportManager: { + faultTolerance: FaultTolerance.FATAL_ALL + }, dialer: { maxParallelDials: Constants.MAX_PARALLEL_DIALS, maxDialsPerPeer: Constants.MAX_PER_PEER_DIALS, diff --git a/src/index.js b/src/index.js index b4ceafc9..ad7a7828 100644 --- a/src/index.js +++ b/src/index.js @@ -101,7 +101,8 @@ class Libp2p extends EventEmitter { // Setup the transport manager this.transportManager = new TransportManager({ libp2p: this, - upgrader: this.upgrader + upgrader: this.upgrader, + faultTolerance: this._options.transportManager.faultTolerance }) // Create the Registrar diff --git a/src/transport-manager.js b/src/transport-manager.js index b1994938..beeb6bb6 100644 --- a/src/transport-manager.js +++ b/src/transport-manager.js @@ -13,12 +13,14 @@ class TransportManager { * @param {object} options * @param {Libp2p} options.libp2p The Libp2p instance. It will be passed to the transports. * @param {Upgrader} options.upgrader The upgrader to provide to the transports + * @param {boolean} [options.faultTolerance = FAULT_TOLERANCE.FATAL_ALL] Address listen error tolerance. */ - constructor ({ libp2p, upgrader }) { + constructor ({ libp2p, upgrader, faultTolerance = FAULT_TOLERANCE.FATAL_ALL }) { this.libp2p = libp2p this.upgrader = upgrader this._transports = new Map() this._listeners = new Map() + this.faultTolerance = faultTolerance } /** @@ -173,7 +175,11 @@ class TransportManager { // If no transports were able to listen, throw an error. This likely // means we were given addresses we do not have transports for if (couldNotListen.length === this._transports.size) { - throw errCode(new Error(`no valid addresses were provided for transports [${couldNotListen}]`), codes.ERR_NO_VALID_ADDRESSES) + const message = `no valid addresses were provided for transports [${couldNotListen}]` + if (this.faultTolerance === FAULT_TOLERANCE.FATAL_ALL) { + throw errCode(new Error(message), codes.ERR_NO_VALID_ADDRESSES) + } + log(`libp2p in dial mode only: ${message}`) } } @@ -212,4 +218,18 @@ class TransportManager { } } +/** + * Enum Transport Manager Fault Tolerance values. + * FATAL_ALL should be used for failing in any listen circumstance. + * NO_FATAL should be used for not failing when not listening. + * @readonly + * @enum {number} + */ +const FAULT_TOLERANCE = { + FATAL_ALL: 0, + NO_FATAL: 1 +} + +TransportManager.FaultTolerance = FAULT_TOLERANCE + module.exports = TransportManager diff --git a/test/transports/transport-manager.spec.js b/test/transports/transport-manager.spec.js index 4211bd06..0acc4b86 100644 --- a/test/transports/transport-manager.spec.js +++ b/test/transports/transport-manager.spec.js @@ -15,6 +15,8 @@ const mockUpgrader = require('../utils/mockUpgrader') const { MULTIADDRS_WEBSOCKETS } = require('../fixtures/browser') const { codes: ErrorCodes } = require('../../src/errors') const Libp2p = require('../../src') +const { FaultTolerance } = require('../../src/transport-manager') + const Peers = require('../fixtures/peers') const PeerId = require('peer-id') @@ -165,3 +167,55 @@ describe('libp2p.transportManager', () => { expect(libp2p.transportManager.close.callCount).to.equal(1) }) }) + +describe('libp2p.transportManager (dial only)', () => { + let peerId + let libp2p + + before(async () => { + peerId = await PeerId.createFromJSON(Peers[0]) + }) + + afterEach(async () => { + sinon.restore() + libp2p && await libp2p.stop() + }) + + it('fails to start if multiaddr fails to listen', async () => { + libp2p = new Libp2p({ + peerId, + addresses: { + listen: [multiaddr('/ip4/127.0.0.1/tcp/0')] + }, + modules: { + transport: [Transport] + } + }) + + try { + await libp2p.start() + } catch (err) { + expect(err).to.exist() + expect(err.code).to.equal(ErrorCodes.ERR_NO_VALID_ADDRESSES) + return + } + throw new Error('it should fail to start if multiaddr fails to listen') + }) + + it('does not fail to start if multiaddr fails to listen when supporting dial only mode', async () => { + libp2p = new Libp2p({ + peerId, + addresses: { + listen: [multiaddr('/ip4/127.0.0.1/tcp/0')] + }, + transportManager: { + faultTolerance: FaultTolerance.NO_FATAL + }, + modules: { + transport: [Transport] + } + }) + + await libp2p.start() + }) +})