docs(api): first pass

.npmignore

@@ -26,4 +26,5 @@ build/Release
 # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git
 node_modules
 
-test
+test
+docs

CHANGELOG.md

@@ -1,13 +1,3 @@
-<a name="0.13.0"></a>
-# [0.13.0](https://github.com/libp2p/js-libp2p-tcp/compare/v0.12.1...v0.13.0) (2018-09-12)
-
-
-### Features
-
-* add support for dialing over dns ([eba0b48](https://github.com/libp2p/js-libp2p-tcp/commit/eba0b48))
-
-
-
 <a name="0.12.1"></a>
 ## [0.12.1](https://github.com/libp2p/js-libp2p-tcp/compare/v0.12.0...v0.12.1) (2018-07-31)
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2p-tcp",
-  "version": "0.13.0",
+  "version": "0.12.1",
   "description": "Node.js implementation of the TCP module that libp2p uses, which implements the interface-connection and interface-transport interfaces",
   "leadMaintainer": "Jacob Heun <jacobheun@gmail.com>",
   "main": "src/index.js",
@@ -34,19 +34,22 @@
     "npm": ">=3.0.0"
   },
   "devDependencies": {
-    "aegir": "^17.0.1",
-    "chai": "^4.2.0",
+    "aegir": "^15.1.0",
+    "chai": "^4.1.2",
     "dirty-chai": "^2.0.1",
     "interface-transport": "~0.3.6",
-    "pull-stream": "^3.6.9"
+    "lodash.isfunction": "^3.0.9",
+    "pull-stream": "^3.6.7"
   },
   "dependencies": {
     "class-is": "^1.1.0",
-    "debug": "^4.1.0",
+    "debug": "^3.1.0",
     "interface-connection": "~0.3.2",
     "ip-address": "^5.8.9",
-    "mafmt": "^6.0.2",
-    "multiaddr": "^5.0.2",
+    "lodash.includes": "^4.3.0",
+    "lodash.isfunction": "^3.0.9",
+    "mafmt": "^6.0.0",
+    "multiaddr": "^4.0.0",
     "once": "^1.4.0",
     "stream-to-pull-stream": "^1.7.2"
   },

src/index.js

@@ -4,6 +4,8 @@ const net = require('net')
 const toPull = require('stream-to-pull-stream')
 const mafmt = require('mafmt')
 const withIs = require('class-is')
+const includes = require('lodash.includes')
+const isFunction = require('lodash.isfunction')
 const Connection = require('interface-connection').Connection
 const once = require('once')
 const debug = require('debug')
@@ -13,9 +15,20 @@ const createListener = require('./listener')
 
 function noop () {}
 
+/**
+ *
+ */
 class TCP {
+  /**
+   * Dial to another peer.
+   *
+   * @param {Multiaddr} ma - The address of the peer we want to dial to.
+   * @param {Object} [options={}]
+   * @param {function(Error?, Array<Multiaddr>?)} [callback]
+   * @returns {Connection}
+   */
   dial (ma, options, callback) {
-    if (typeof options === 'function') {
+    if (isFunction(options)) {
       callback = options
       options = {}
     }
@@ -50,8 +63,15 @@ class TCP {
     return conn
   }
 
+  /**
+   * Listen for incoming `TCP` connetions.
+   *
+   * @param {Object} [options={}]
+   * @param {function(Connection)} [handler] - Called with newly incomin connections.
+   * @returns {Listener}
+   */
   createListener (options, handler) {
-    if (typeof options === 'function') {
+    if (isFunction(options)) {
       handler = options
       options = {}
     }
@@ -61,17 +81,24 @@ class TCP {
     return createListener(handler)
   }
 
+  /**
+   * Filter a list of multiaddrs for those which contain
+   * valid `TCP` addresses.
+   *
+   * @param {Multiaddr|Array<Multiaddr>} multiaddrs
+   * @returns {Array<Multiaddr>}
+   */
   filter (multiaddrs) {
     if (!Array.isArray(multiaddrs)) {
       multiaddrs = [multiaddrs]
     }
 
     return multiaddrs.filter((ma) => {
-      if (ma.protoNames().includes('p2p-circuit')) {
+      if (includes(ma.protoNames(), 'p2p-circuit')) {
         return false
       }
 
-      if (ma.protoNames().includes('ipfs')) {
+      if (includes(ma.protoNames(), 'ipfs')) {
         ma = ma.decapsulate('ipfs')
       }
 

src/listener.js

@@ -3,6 +3,7 @@
 const multiaddr = require('multiaddr')
 const Connection = require('interface-connection').Connection
 const os = require('os')
+const includes = require('lodash.includes')
 const net = require('net')
 const toPull = require('stream-to-pull-stream')
 const EventEmitter = require('events').EventEmitter
@@ -16,7 +17,49 @@ const CLOSE_TIMEOUT = 2000
 
 function noop () {}
 
+/**
+ * Listening for incoming connections.
+ *
+ * @event listening
+ * @instance
+ * @memberof Listener
+ */
+
+/**
+ * The server closes.
+ *
+ * @event close
+ * @instance
+ * @memberof Listener
+ */
+
+/**
+ * New connection established.
+ *
+ * @event connection
+ * @instance
+ * @type {Connection}
+ * @memberof Listener
+ */
+
+/**
+ * The underlying server encountered an error.
+ *
+ * @event error
+ * @instance
+ * @type {Error}
+ * @memberof Listener
+ */
+
 module.exports = (handler) => {
+  /**
+   * @alias Listener
+   * @type {Eventemitter}
+   * @fires Listener#listening
+   * @fires Listener#close
+   * @fires Listener#connection
+   * @fires Listener#error
+   */
   const listener = new EventEmitter()
 
   const server = net.createServer((socket) => {
@@ -41,6 +84,8 @@ module.exports = (handler) => {
       cb(null, [addr])
     }
 
+    trackSocket(server, socket)
+
     const conn = new Connection(s)
     handler(conn)
     listener.emit('connection', conn)
@@ -49,17 +94,9 @@ module.exports = (handler) => {
   server.on('listening', () => listener.emit('listening'))
   server.on('error', (err) => listener.emit('error', err))
   server.on('close', () => listener.emit('close'))
-  server.on('connection', (conn) => {
-    server.__connections.push(conn)
-    conn.once('close', () => {
-      server.__connections = server.__connections.filter((c) => {
-        return conn !== c
-      })
-    })
-  })
 
   // Keep track of open connections to destroy in case of timeout
-  server.__connections = []
+  server.__connections = {}
 
   listener.close = (options, callback) => {
     if (typeof options === 'function') {
@@ -71,9 +108,9 @@ module.exports = (handler) => {
 
     const timeout = setTimeout(() => {
       log('unable to close graciously, destroying conns')
-      server.__connections.forEach((conn) => {
-        log('destroying %s', `${conn.remoteAddress}:${conn.remotePort}`)
-        conn.destroy()
+      Object.keys(server.__connections).forEach((key) => {
+        log('destroying %s', key)
+        server.__connections[key].destroy()
       })
     }, options.timeout || CLOSE_TIMEOUT)
 
@@ -89,7 +126,7 @@ module.exports = (handler) => {
 
   listener.listen = (ma, callback) => {
     listeningAddr = ma
-    if (ma.protoNames().includes('ipfs')) {
+    if (includes(ma.protoNames(), 'ipfs')) {
       ipfsId = getIpfsId(ma)
       listeningAddr = ma.decapsulate('ipfs')
     }
@@ -150,3 +187,12 @@ function getIpfsId (ma) {
     return tuple[0] === IPFS_CODE
   })[0][1]
 }
+
+function trackSocket (server, socket) {
+  const key = `${socket.remoteAddress}:${socket.remotePort}`
+  server.__connections[key] = socket
+
+  socket.on('close', () => {
+    delete server.__connections[key]
+  })
+}

test/compliance.spec.js

@@ -8,12 +8,11 @@ const TCP = require('../src')
 describe('interface-transport compliance', () => {
   tests({
     setup (cb) {
-      const tcp = new TCP()
+      let tcp = new TCP()
       const addrs = [
         multiaddr('/ip4/127.0.0.1/tcp/9091'),
         multiaddr('/ip4/127.0.0.1/tcp/9092'),
-        multiaddr('/ip4/127.0.0.1/tcp/9093'),
-        multiaddr('/dns4/ipfs.io')
+        multiaddr('/ip4/127.0.0.1/tcp/9093')
       ]
       cb(null, tcp, addrs)
     },

test/filter.spec.js

@@ -25,11 +25,9 @@ describe('filter addrs', () => {
     const ma4 = multiaddr(base + '/tcp/9090/ipfs/Qmb6owHp6eaWArVbcJJbQSyifyJBttMMjYV76N2hMbf5Vw')
     const ma5 = multiaddr(base + '/tcp/9090/http' + ipfs)
     const ma6 = multiaddr('/ip4/127.0.0.1/tcp/9090/p2p-circuit' + ipfs)
-    const ma7 = multiaddr('/dns4/libp2p.io/tcp/9090')
-    const ma8 = multiaddr('/dnsaddr/libp2p.io/tcp/9090')
 
-    const valid = tcp.filter([ma1, ma2, ma3, ma4, ma5, ma6, ma7, ma8])
-    expect(valid.length).to.equal(4)
+    const valid = tcp.filter([ma1, ma2, ma3, ma4, ma5, ma6])
+    expect(valid.length).to.equal(2)
     expect(valid[0]).to.deep.equal(ma1)
     expect(valid[1]).to.deep.equal(ma4)
   })