feat: add core adapter for swarm peers and docs

Author: Alan Shaw

API.md

@@ -85,10 +85,10 @@
 * stats.bwPullStream
 * stats.repo
 * swarm.addrs
-* [swarm.connect](#swarmconnect) TODO: add docs
+* [swarm.connect](#swarmconnect)
 * swarm.disconnect
 * swarm.localAddrs
-* [swarm.peers](#swarmpeers) TODO: add docs
+* [swarm.peers](#swarmpeers)
 * [version](#version) TODO: add docs
 
 Note: All API methods are documented using Promises/async/await but they also accept a callback as their last parameter.
@@ -755,3 +755,102 @@ Unsubscribe all handlers:
 ```js
 await ipfs.pubsub.unsubscribe('my-pubsub-topic')
 ```
+
+## swarm.connect
+
+Open a connection to a given address.
+
+### `swarm.connect(addr, [options]): Promise<String[]>`
+
+#### Parameters
+
+* `addr` - Multiaddr address(es) of IPFS node(s) to connect to.
+    * Type: `String`|`String[]`
+* `options` (optional)
+    * Type: `Object`
+    * Default: `null`
+* `options.signal` (optional) - A signal that can be used to abort the request
+    * Type: [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+    * Default: `null`
+
+#### Returns
+
+List of connection status messages for each peer connection attempted.
+
+* Type: `Promise<String[]>`
+
+#### Examples
+
+```js
+const res = await ipfs.swarm.connect('/ip4/127.0.0.1/tcp/4101/ipfs/Qmeg3LQNGuiwpinKe69YBbADV2PpqGcGtcgLeaNjoxuUdV')
+console.log(res)
+/*
+[
+  'connect Qmeg3LQNGuiwpinKe69YBbADV2PpqGcGtcgLeaNjoxuUdV success'
+]
+*/
+```
+
+## swarm.peers
+
+List peers with open connections.
+
+### `swarm.peers([options]): Promise<Object[]>`
+
+#### Parameters
+
+* `options` (optional)
+    * Type: `Object`
+    * Default: `null`
+* `options.direction` (optional) - Return direction information for each peer (inbound/outbound).
+    * Type: `Boolean`
+    * Default: `false`
+* `options.signal` (optional) - A signal that can be used to abort the request
+    * Type: [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+    * Default: `null`
+* `options.latency` (optional) - Return latency information for each peer.
+    * Type: `Boolean`
+    * Default: `false`
+* `options.streams` (optional) - Return streams information for each peer.
+    * Type: `Boolean`
+    * Default: `false`
+* `options.verbose` (optional) - Return streams, latency, and direction info as well as address and ID for each peer.
+    * Type: `Boolean`
+    * Default: `false`
+
+#### Returns
+
+Peer information for peers with open connections.
+
+* Type: `Promise<Object[]>`
+
+#### Examples
+
+```js
+const peers = await ipfs.swarm.peers({ verbose: true })
+console.log(res)
+/*
+[
+  {
+    addr: '/ip6/2a03:b0c0:3:e1::130:e001/tcp/4001',
+    peer: 'QmYR4jxcGUTQZ7mA5DkfBSxpdJW5Y4CsfgHFfARLAV3goA',
+    latency: '27.965651ms',
+    muxer: '',
+    direction: 2,
+    streams: [ { protocol: '/ipfs/bitswap/1.1.0' } ]
+  },
+  {
+    addr: '/ipfs/QmdGQoGuK3pao6bRDqGSDvux5SFHa4kC1XNFfHFcvcbydY/p2p-circuit',
+    peer: 'QmcqrAQZqcQxrVpw2Png7FrSfNArfEFTu9UhPopmKPZpGP',
+    latency: '772.455375ms',
+    muxer: '',
+    direction: 2,
+    streams: [
+      { protocol: '/ipfs/bitswap/1.1.0' },
+      { protocol: '/ipfs/kad/1.0.0' }
+    ]
+  },
+  // ...
+]
+*/
+```

README.md

@@ -222,10 +222,10 @@ This module is in heavy development, not all API methods are available (or docum
 * stats.bwPullStream
 * stats.repo
 * swarm.addrs
-* [swarm.connect](./API.md#swarmconnect) TODO: add docs
+* [swarm.connect](./API.md#swarmconnect)
 * swarm.disconnect
 * swarm.localAddrs
-* [swarm.peers](./API.md#swarmpeers) TODO: add docs
+* [swarm.peers](./API.md#swarmpeers)
 * [version](./API.md#version) TODO: add docs
 
 Note: All API methods are documented using Promises/async/await but they also accept a callback as their last parameter.

package.json

@@ -46,8 +46,10 @@
     "interface-ipfs-core": "~0.105.1",
     "ipfs-block": "^0.8.1",
     "ipfsd-ctl": "^0.43.0",
+    "multiaddr": "^6.1.0",
     "multiaddr-to-uri": "^4.0.1",
     "multihashes": "^0.4.14",
+    "peer-id": "^0.12.2",
     "pull-stream": "^3.6.12"
   },
   "engines": {

src/swarm/peers.js

@@ -3,6 +3,7 @@
 const { objectToQuery } = require('../lib/querystring')
 const configure = require('../lib/configure')
 const { ok } = require('../lib/fetch')
+const toCamel = require('../lib/to-camel')
 
 module.exports = configure(({ fetch, apiUrl, apiPath, headers }) => {
   return async options => {
@@ -22,21 +23,10 @@ module.exports = configure(({ fetch, apiUrl, apiPath, headers }) => {
     const data = await res.json()
 
     return (data.Peers || []).map(p => {
-      const peerInfo = {
-        addr: p.Addr,
-        peer: p.Peer
-      }
-
-      if (options.verbose || options.streams) {
-        peerInfo.streams = (p.Streams || []).map(s => ({ protocol: s.Protocol }))
-      }
-
-      if (options.verbose || options.latency) {
-        peerInfo.latency = p.Latency
-      }
+      const peerInfo = toCamel(p)
 
-      if (options.verbose) {
-        peerInfo.muxer = p.Muxer
+      if (peerInfo.streams) {
+        peerInfo.streams = peerInfo.streams.map(toCamel)
       }
 
       return peerInfo

test/interface.spec.js

@@ -359,7 +359,6 @@ describe('interface-ipfs-core tests', () => {
 
   tests.swarm(defaultCommon, {
     skip: [
-      { name: 'peers', reason: 'LITE: not implemented yet' },
       { name: 'addrs', reason: 'LITE: not implemented yet' },
       { name: 'localAddrs', reason: 'LITE: not implemented yet' },
       { name: 'disconnect', reason: 'LITE: not implemented yet' }

test/utils/core-adapter/index.js

@@ -25,6 +25,10 @@ module.exports = ipfsLite => {
       publish: ipfsLite.pubsub.publish,
       subscribe: callbackify(require('./pubsub/subscribe')(ipfsLite), { minArgs: 2 }),
       unsubscribe: callbackify(require('./pubsub/unsubscribe')(ipfsLite), { minArgs: 2 })
+    },
+    swarm: {
+      connect: ipfsLite.swarm.connect,
+      peers: callbackify(require('./swarm/peers')(ipfsLite))
     }
   }
 

test/utils/core-adapter/swarm/peers.js

@@ -0,0 +1,28 @@
+'use strict'
+
+const Multiaddr = require('multiaddr')
+const PeerId = require('peer-id')
+
+module.exports = ipfsLite => async (...args) => {
+  const list = await ipfsLite.swarm.peers(...args)
+  return list.map(parsePeer)
+}
+
+function parsePeer (peer) {
+  const res = {}
+  try {
+    res.addr = Multiaddr(peer.addr)
+    res.peer = PeerId.createFromB58String(peer.peer)
+    res.muxer = peer.muxer
+  } catch (error) {
+    res.error = error
+    res.rawPeerInfo = peer
+  }
+  if (peer.latency) {
+    res.latency = peer.latency
+  }
+  if (peer.streams) {
+    res.streams = peer.streams
+  }
+  return res
+}

test/utils/interface-common-factory.js

@@ -24,8 +24,20 @@ function createFactory (options) {
     } else {
       setup = (callback) => {
         callback(null, {
-          spawnNode (cb) {
-            ipfsFactory.spawn(options.spawnOptions, (err, _ipfsd) => {
+          spawnNode (repoPath, config, cb) {
+            if (typeof repoPath === 'function') {
+              cb = repoPath
+              repoPath = null
+            }
+
+            if (typeof config === 'function') {
+              cb = config
+              config = null
+            }
+
+            const spawnOptions = { ...options.spawnOptions, repoPath, config }
+
+            ipfsFactory.spawn(spawnOptions, (err, _ipfsd) => {
               if (err) {
                 return cb(err)
               }