diff --git a/doc/API.md b/doc/API.md index cde9161d71..ee4af9c7d3 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 2e3a4ffaa9..490f389034 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 53c9c4c2b5..f586c6dc87 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 b4ceafc977..ad7a78281c 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 b1994938fb..beeb6bb6e2 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 4211bd06d3..0acc4b8660 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() + }) +})