feat: add libp2p factory config option with example (#1470)

Resolves #1463 and libp2p/js-libp2p#222

This adds the ability to pass a libp2p generator function to the ipfs configuration. This makes it easier for users to add custom modules to libp2p that require some startup time properties, like peerInfo (libp2p/js-libp2p#222). 

I have also included an example of how to do this. I think this makes complex libp2p configuration much cleaner and easier to do.

Tests have been added for the old configuration options and the new generator option. I isolated them to avoid spinning up a full ipfs node.

Author: jacobheun

README.md

@@ -320,8 +320,11 @@ Modify the default IPFS node config. This object will be *merged* with the defau
 | Type | Default |
 |------|---------|
 | object | [`libp2p-nodejs.js`](https://github.com/ipfs/js-ipfs/blob/master/src/core/runtime/libp2p-nodejs.js) in Node.js, [`libp2p-browser.js`](https://github.com/ipfs/js-ipfs/blob/master/src/core/runtime/libp2p-browser.js) in browsers |
+| function | [`libp2p bundle`](examples/custom-libp2p) |
 
-Add custom modules to the libp2p stack of your node.
+The libp2p option allows you to build your libp2p node by configuration, or via a bundle function. If you are looking to just modify the below options, using the object format is the quickest way to get the default features of libp2p. If you need to create a more customized libp2p node, such as with custom transports or peer/content routers that need some of the ipfs data on startup, a custom bundle is a great way to achieve this.
+
+You can see the bundle in action in the [custom libp2p example](examples/custom-libp2p).
 
 - `modules` (object):
     - `transport` (Array<[libp2p.Transport](https://github.com/libp2p/interface-transport)>): An array of Libp2p transport classes/instances to use _instead_ of the defaults. See [libp2p/interface-transport](https://github.com/libp2p/interface-transport) for details.

examples/README.md

@@ -23,6 +23,7 @@ Let us know if you find any issue or if you want to contribute and add a new tut
 - [js-ipfs in electron](./run-in-electron)
 - [Using streams to add a directory of files to ipfs](./browser-add-readable-stream)
 - [Customizing the ipfs repository](./custom-ipfs-repo)
+- [Customizing your libp2p bundle](./custom-libp2p)
 - [Streaming video from ipfs to the browser using `ReadableStream`s](./browser-readablestream)
 - [The Mutable File System in the browser](./browser-mfs)
 

examples/custom-libp2p/README.md

@@ -0,0 +1,18 @@
+# Customizing your libp2p bundle
+
+This example shows you how to make full use of the ipfs configuration to create a libp2p bundle function. As IPFS applications become more complex, their needs for a custom libp2p bundle also grow. Instead of fighting with configuration options, you can use your own libp2p bundle function to get exactly what you need.
+
+## Run this example
+
+Running this example should result in metrics being logged out to the console every few seconds.
+
+```
+> npm install
+> npm start
+```
+
+## Play with the configuration!
+
+With the metrics for peers and bandwidth stats being logged out, try playing around with the nodes configuration to see what kind of metrics you can get. How many peers are you getting? What does your bandwidth look like?
+
+This is also a good opportunity to explore the various stats that ipfs offers! Not seeing a statistic you think would be useful? We'd love to have you [contribute](https://github.com/ipfs/js-ipfs/blob/master/CONTRIBUTING.md)!

examples/custom-libp2p/index.js

@@ -0,0 +1,129 @@
+'use strict'
+
+const Libp2p = require('libp2p')
+const IPFS = require('ipfs')
+const TCP = require('libp2p-tcp')
+const MulticastDNS = require('libp2p-mdns')
+const WebSocketStar = require('libp2p-websocket-star')
+const Bootstrap = require('libp2p-railing')
+const SPDY = require('libp2p-spdy')
+const KadDHT = require('libp2p-kad-dht')
+const MPLEX = require('libp2p-mplex')
+const SECIO = require('libp2p-secio')
+const assert = require('assert')
+
+/**
+ * Options for the libp2p bundle
+ * @typedef {Object} libp2pBundle~options
+ * @property {PeerInfo} peerInfo - The PeerInfo of the IPFS node
+ * @property {PeerBook} peerBook - The PeerBook of the IPFS node
+ * @property {Object} config - The config of the IPFS node
+ * @property {Object} options - The options given to the IPFS node
+ */
+
+/**
+ * This is the bundle we will use to create our fully customized libp2p bundle.
+ *
+ * @param {libp2pBundle~options} opts The options to use when generating the libp2p node
+ * @returns {Libp2p} Our new libp2p node
+ */
+const libp2pBundle = (opts) => {
+  // Set convenience variables to clearly showcase some of the useful things that are available
+  const peerInfo = opts.peerInfo
+  const peerBook = opts.peerBook
+  const bootstrapList = opts.config.Bootstrap
+
+  // Create our WebSocketStar transport and give it our PeerId, straight from the ipfs node
+  const wsstar = new WebSocketStar({
+    id: peerInfo.id
+  })
+
+  // Build and return our libp2p node
+  return new Libp2p({
+    peerInfo,
+    peerBook,
+    // Lets limit the connection managers peers and have it check peer health less frequently
+    connectionManager: {
+      maxPeers: 25,
+      pollInterval: 5000
+    },
+    modules: {
+      transport: [
+        TCP,
+        wsstar
+      ],
+      streamMuxer: [
+        MPLEX,
+        SPDY
+      ],
+      connEncryption: [
+        SECIO
+      ],
+      peerDiscovery: [
+        MulticastDNS,
+        Bootstrap,
+        wsstar.discovery
+      ],
+      dht: KadDHT
+    },
+    config: {
+      peerDiscovery: {
+        mdns: {
+          interval: 10000,
+          enabled: true
+        },
+        bootstrap: {
+          interval: 10000,
+          enabled: true,
+          list: bootstrapList
+        }
+      },
+      // Turn on relay with hop active so we can connect to more peers
+      relay: {
+        enabled: true,
+        hop: {
+          enabled: true,
+          active: true
+        }
+      },
+      dht: {
+        kBucketSize: 20
+      },
+      EXPERIMENTAL: {
+        dht: true,
+        pubsub: true
+      }
+    }
+  })
+}
+
+// Now that we have our custom libp2p bundle, let's start up the ipfs node!
+const node = new IPFS({
+  libp2p: libp2pBundle
+})
+
+// Listen for the node to start, so we can log out some metrics
+node.once('start', (err) => {
+  assert.ifError(err, 'Should startup without issue')
+
+  // Lets log out the number of peers we have every 2 seconds
+  setInterval(() => {
+    node.swarm.peers((err, peers) => {
+      if (err) {
+        console.log('An error occurred trying to check our peers:', err)
+        process.exit(1)
+      }
+      console.log(`The node now has ${peers.length} peers.`)
+    })
+  }, 2000)
+
+  // Log out the bandwidth stats every 4 seconds so we can see how our configuration is doing
+  setInterval(() => {
+    node.stats.bw((err, stats) => {
+      if (err) {
+        console.log('An error occurred trying to check our stats:', err)
+      }
+      console.log(`\nBandwidth Stats: ${JSON.stringify(stats, null, 2)}\n`)
+    })
+  }, 4000)
+})

examples/custom-libp2p/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "custom-libp2p",
+  "version": "0.1.0",
+  "description": "Customizing your libp2p node",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node index.js"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "ipfs": "file:../../",
+    "libp2p": "~0.22.0",
+    "libp2p-kad-dht": "~0.10.1",
+    "libp2p-mdns": "~0.12.0",
+    "libp2p-mplex": "~0.8.0",
+    "libp2p-railing": "~0.9.2",
+    "libp2p-secio": "~0.10.0",
+    "libp2p-spdy": "~0.12.1",
+    "libp2p-tcp": "~0.12.0",
+    "libp2p-websocket-star": "~0.8.1"
+  }
+}

src/core/components/libp2p.js

@@ -16,49 +16,64 @@ module.exports = function libp2p (self) {
           return callback(err)
         }
 
-        const libp2pDefaults = {
-          peerInfo: self._peerInfo,
-          peerBook: self._peerInfoBook,
-          config: {
-            peerDiscovery: {
-              mdns: {
-                enabled: get(self._options, 'config.Discovery.MDNS.Enabled',
-                  get(config, 'Discovery.MDNS.Enabled', true))
+        const defaultBundle = (opts) => {
+          const libp2pDefaults = {
+            peerInfo: opts.peerInfo,
+            peerBook: opts.peerBook,
+            config: {
+              peerDiscovery: {
+                mdns: {
+                  enabled: get(opts.options, 'config.Discovery.MDNS.Enabled',
+                    get(opts.config, 'Discovery.MDNS.Enabled', true))
+                },
+                webRTCStar: {
+                  enabled: get(opts.options, 'config.Discovery.webRTCStar.Enabled',
+                    get(opts.config, 'Discovery.webRTCStar.Enabled', true))
+                },
+                bootstrap: {
+                  list: get(opts.options, 'config.Bootstrap',
+                    get(opts.config, 'Bootstrap', []))
+                }
               },
-              webRTCStar: {
-                enabled: get(self._options, 'config.Discovery.webRTCStar.Enabled',
-                  get(config, 'Discovery.webRTCStar.Enabled', true))
+              relay: {
+                enabled: get(opts.options, 'relay.enabled',
+                  get(opts.config, 'relay.enabled', false)),
+                hop: {
+                  enabled: get(opts.options, 'relay.hop.enabled',
+                    get(opts.config, 'relay.hop.enabled', false)),
+                  active: get(opts.options, 'relay.hop.active',
+                    get(opts.config, 'relay.hop.active', false))
+                }
               },
-              bootstrap: {
-                list: get(self._options, 'config.Bootstrap',
-                  get(config, 'Bootstrap', []))
-              }
-            },
-            relay: {
-              enabled: get(self._options, 'relay.enabled',
-                get(config, 'relay.enabled', false)),
-              hop: {
-                enabled: get(self._options, 'relay.hop.enabled',
-                  get(config, 'relay.hop.enabled', false)),
-                active: get(self._options, 'relay.hop.active',
-                  get(config, 'relay.hop.active', false))
+              EXPERIMENTAL: {
+                dht: get(opts.options, 'EXPERIMENTAL.dht', false),
+                pubsub: get(opts.options, 'EXPERIMENTAL.pubsub', false)
               }
             },
-            EXPERIMENTAL: {
-              dht: get(self._options, 'EXPERIMENTAL.dht', false),
-              pubsub: get(self._options, 'EXPERIMENTAL.pubsub', false)
-            }
-          },
-          connectionManager: get(self._options, 'connectionManager',
-            get(config, 'connectionManager', {}))
+            connectionManager: get(opts.options, 'connectionManager',
+              get(opts.config, 'connectionManager', {}))
+          }
+
+          const libp2pOptions = defaultsDeep(
+            get(self._options, 'libp2p', {}),
+            libp2pDefaults
+          )
+
+          return new Node(libp2pOptions)
         }
 
-        const libp2pOptions = defaultsDeep(
-          get(self._options, 'libp2p', {}),
-          libp2pDefaults
-        )
+        // Always create libp2p via a bundle function
+        let libp2pBundle = get(self._options, 'libp2p', null)
+        if (typeof libp2pBundle !== 'function') {
+          libp2pBundle = defaultBundle
+        }
 
-        self._libp2pNode = new Node(libp2pOptions)
+        self._libp2pNode = libp2pBundle({
+          options: self._options,
+          config: config,
+          peerInfo: self._peerInfo,
+          peerBook: self._peerInfoBook
+        })
 
         self._libp2pNode.on('peer:discovery', (peerInfo) => {
           const dial = () => {

src/core/config.js

@@ -49,9 +49,12 @@ const schema = Joi.object().keys({
     }).allow(null),
     Bootstrap: Joi.array().items(Joi.multiaddr().IPFS().options({ convert: false }))
   }).allow(null),
-  libp2p: Joi.object().keys({
-    modules: Joi.object().allow(null) // TODO: schemas for libp2p modules?
-  }).allow(null)
+  libp2p: Joi.alternatives().try(
+    Joi.func(),
+    Joi.object().keys({
+      modules: Joi.object().allow(null) // TODO: schemas for libp2p modules?
+    })
+  ).allow(null)
 }).options({ allowUnknown: true })
 
 module.exports.validate = (config) => Joi.attempt(config, schema)

test/core/config.spec.js

@@ -226,6 +226,7 @@ describe('config', () => {
       { libp2p: { modules: null } },
       { libp2p: { modules: undefined } },
       { libp2p: { unknown: 'value' } },
+      { libp2p: () => {} },
       { libp2p: null },
       { libp2p: undefined }
     ]