chore: release version v0.2.2

* feat: add crypto transmission error

* docs: add error to crypto readme

.gitignore

@@ -6,6 +6,7 @@
 
 build
 dist
+docs
 
 # Dependency directory
 # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git

CHANGELOG.md

@@ -1,3 +1,108 @@
+<a name="0.2.2"></a>
+## [0.2.2](https://github.com/libp2p/js-interfaces/compare/v0.2.1...v0.2.2) (2020-01-17)
+
+
+### Bug Fixes
+
+* **connection:** dont require remoteAddr on creation ([#20](https://github.com/libp2p/js-interfaces/issues/20)) ([5967834](https://github.com/libp2p/js-interfaces/commit/5967834))
+
+
+
+<a name="0.2.1"></a>
+## [0.2.1](https://github.com/libp2p/js-interfaces/compare/v0.2.0...v0.2.1) (2019-12-28)
+
+
+### Features
+
+* add crypto transmission error ([#17](https://github.com/libp2p/js-interfaces/issues/17)) ([d98bb23](https://github.com/libp2p/js-interfaces/commit/d98bb23))
+
+
+
+<a name="0.2.0"></a>
+# [0.2.0](https://github.com/libp2p/js-interfaces/compare/v0.1.7...v0.2.0) (2019-12-20)
+
+
+### Bug Fixes
+
+* transport should not handle connection if upgradeInbound throws ([#16](https://github.com/libp2p/js-interfaces/issues/16)) ([ff03137](https://github.com/libp2p/js-interfaces/commit/ff03137))
+
+
+
+<a name="0.1.7"></a>
+## [0.1.7](https://github.com/libp2p/js-interfaces/compare/v0.1.6...v0.1.7) (2019-12-15)
+
+
+### Features
+
+* export connection status' ([#15](https://github.com/libp2p/js-interfaces/issues/15)) ([bdbd58e](https://github.com/libp2p/js-interfaces/commit/bdbd58e))
+
+
+
+<a name="0.1.6"></a>
+## [0.1.6](https://github.com/libp2p/js-interfaces/compare/v0.1.5...v0.1.6) (2019-12-02)
+
+
+### Bug Fixes
+
+* multicodec topology disconnect with peer param ([#12](https://github.com/libp2p/js-interfaces/issues/12)) ([d5dd256](https://github.com/libp2p/js-interfaces/commit/d5dd256))
+
+
+
+<a name="0.1.5"></a>
+## [0.1.5](https://github.com/libp2p/js-interfaces/compare/v0.1.4...v0.1.5) (2019-11-15)
+
+
+### Bug Fixes
+
+* multicodec topology update peers with multicodec ([#10](https://github.com/libp2p/js-interfaces/issues/10)) ([21d8ae6](https://github.com/libp2p/js-interfaces/commit/21d8ae6))
+
+
+### Features
+
+* add class-is to topology ([#11](https://github.com/libp2p/js-interfaces/issues/11)) ([a67abcc](https://github.com/libp2p/js-interfaces/commit/a67abcc))
+
+
+
+<a name="0.1.4"></a>
+## [0.1.4](https://github.com/libp2p/js-interfaces/compare/v0.1.3...v0.1.4) (2019-11-14)
+
+
+### Features
+
+* add topology interfaces ([#7](https://github.com/libp2p/js-interfaces/issues/7)) ([8bee747](https://github.com/libp2p/js-interfaces/commit/8bee747))
+
+
+
+<a name="0.1.3"></a>
+## [0.1.3](https://github.com/libp2p/js-interfaces/compare/v0.1.2...v0.1.3) (2019-10-30)
+
+
+### Bug Fixes
+
+* localAddr should be optional ([#6](https://github.com/libp2p/js-interfaces/issues/6)) ([749a8d0](https://github.com/libp2p/js-interfaces/commit/749a8d0))
+
+
+
+<a name="0.1.2"></a>
+## [0.1.2](https://github.com/libp2p/js-interfaces/compare/v0.1.1...v0.1.2) (2019-10-29)
+
+
+### Features
+
+* crypto errors ([#4](https://github.com/libp2p/js-interfaces/issues/4)) ([d2fe2d1](https://github.com/libp2p/js-interfaces/commit/d2fe2d1))
+
+
+
+<a name="0.1.1"></a>
+## [0.1.1](https://github.com/libp2p/js-interfaces/compare/v0.1.0...v0.1.1) (2019-10-21)
+
+
+### Features
+
+* crypto interface ([#2](https://github.com/libp2p/js-interfaces/issues/2)) ([5a5c44a](https://github.com/libp2p/js-interfaces/commit/5a5c44a))
+
+
+
 <a name="0.1.0"></a>
 # 0.1.0 (2019-10-20)
 

README.md

@@ -1,4 +1,4 @@
-# JS Libp2p Interfaces
+# JS libp2p Interfaces
 
 [![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://protocol.ai)
 [![](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](http://libp2p.io/)
@@ -15,9 +15,11 @@
 
 - [Connection](./src/connection)
 - [Content Routing](./src/content-routing)
+- [Crypto](./src/crypto)
 - [Peer Discovery](./src/peer-discovery)
 - [Peer Routing](./src/peer-routing)
 - [Stream Muxer](./src/stream-muxer)
+- [Topology](./src/topology)
 - [Transport](./src/transport)
 
 ### Origin Repositories

package.json

@@ -1,7 +1,8 @@
 {
   "name": "libp2p-interfaces",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "Interfaces for JS Libp2p",
+  "leadMaintainer": "Jacob Heun <jacobheun@gmail.com>",
   "main": "src/index.js",
   "files": [
     "src",
@@ -45,12 +46,14 @@
     "libp2p-tcp": "^0.14.1",
     "multiaddr": "^7.1.0",
     "p-limit": "^2.2.1",
+    "p-wait-for": "^3.1.0",
     "peer-id": "^0.13.3",
     "sinon": "^7.5.0",
     "streaming-iterables": "^4.1.0"
   },
   "devDependencies": {
     "aegir": "^20.4.1",
+    "it-handshake": "^1.0.0",
     "it-pair": "^1.0.0",
     "it-pipe": "^1.0.1",
     "peer-info": "^0.17.0"
@@ -63,6 +66,7 @@
     "Friedel Ziegelmayer <dignifiedquire@gmail.com>",
     "Greg Zuro <gregzuro@users.noreply.github.com>",
     "Jacob Heun <jacobheun@gmail.com>",
+    "Jacob Heun <jacobheun@Jacobs-MacBook-Pro.local>",
     "James Ray <16969914+jamesray1@users.noreply.github.com>",
     "Jeffrey Hulten <jhulten@gmail.com>",
     "João Santos <joaosantos15@users.noreply.github.com>",

src/connection/README.md

@@ -109,8 +109,8 @@ const conn = new Connection({
 
 Creates a new Connection instance.
 
-`localAddr` is the [multiaddr](https://github.com/multiformats/multiaddr) address used by the local peer to reach the remote.
-`remoteAddr` is the [multiaddr](https://github.com/multiformats/multiaddr) address used to communicate with the remote peer.
+`localAddr` is the optional [multiaddr](https://github.com/multiformats/multiaddr) address used by the local peer to reach the remote.
+`remoteAddr` is the optional [multiaddr](https://github.com/multiformats/multiaddr) address used to communicate with the remote peer.
 `localPeer` is the [PeerId](https://github.com/libp2p/js-peer-id) of the local peer.
 `remotePeer` is the [PeerId](https://github.com/libp2p/js-peer-id) of the remote peer.
 `newStream` is the `function` responsible for getting a new muxed+multistream-selected stream.
@@ -121,6 +121,7 @@ Creates a new Connection instance.
 - `timeline` is an `object` with the relevant events timestamps of the connection (`open`, `upgraded` and `closed`; the `closed` will be added when the connection is closed).
 - `multiplexer` is a `string` with the connection multiplexing codec (optional).
 - `encryption` is a `string` with the connection encryption method identifier (optional).
+- `status` is a `string` indicating the overall status of the connection. It is one of [`'open'`, `'closing'`, `'closed'`]
 
 #### Create a new stream
 
@@ -220,7 +221,17 @@ This getter returns an `Object` with the metadata of the connection, as follows:
 
 - `status`:
 
-This property contains the status of the connection. It can be either `open`, `closing` or `closed`. Once the connection is created it is in an `open` status. When a `conn.close()` happens, the status will change to `closing` and finally, after all the connection streams are properly closed, the status will be `closed`.
+This property contains the status of the connection. It can be either `open`, `closing` or `closed`. Once the connection is created it is in an `open` status. When a `conn.close()` happens, the status will change to `closing` and finally, after all the connection streams are properly closed, the status will be `closed`. These values can also be directly referenced by importing the `status` file:
+
+```js
+const {
+  OPEN, CLOSING, CLOSED
+} = require('libp2p-interfaces/src/connection/status')
+
+if (connection.stat.status === OPEN) {
+  // ...
+}
+```
 
 - `timeline`:
 

src/connection/connection.js

@@ -7,6 +7,7 @@ const withIs = require('class-is')
 
 const assert = require('assert')
 const errCode = require('err-code')
+const Status = require('./status')
 
 /**
  * An implementation of the js-libp2p connection.
@@ -16,8 +17,8 @@ class Connection {
   /**
    * Creates an instance of Connection.
    * @param {object} properties properties of the connection.
-   * @param {multiaddr} properties.localAddr local multiaddr of the connection.
-   * @param {multiaddr} properties.remoteAddr remote multiaddr of the connection.
+   * @param {multiaddr} [properties.localAddr] local multiaddr of the connection if known.
+   * @param {multiaddr} [properties.remoteAddr] remote multiaddr of the connection.
    * @param {PeerId} properties.localPeer local peer-id.
    * @param {PeerId} properties.remotePeer remote peer-id.
    * @param {function} properties.newStream new stream muxer function.
@@ -32,8 +33,7 @@ class Connection {
    * @param {string} [properties.stat.encryption] connection encryption method identifier.
    */
   constructor ({ localAddr, remoteAddr, localPeer, remotePeer, newStream, close, getStreams, stat }) {
-    assert(multiaddr.isMultiaddr(localAddr), 'localAddr must be an instance of multiaddr')
-    assert(multiaddr.isMultiaddr(remoteAddr), 'remoteAddr must be an instance of multiaddr')
+    localAddr && assert(multiaddr.isMultiaddr(localAddr), 'localAddr must be an instance of multiaddr')
     assert(PeerId.isPeerId(localPeer), 'localPeer must be an instance of peer-id')
     assert(PeerId.isPeerId(remotePeer), 'remotePeer must be an instance of peer-id')
     assert(typeof newStream === 'function', 'new stream must be a function')
@@ -75,7 +75,7 @@ class Connection {
      */
     this._stat = {
       ...stat,
-      status: 'open'
+      status: Status.OPEN
     }
 
     /**
@@ -126,11 +126,11 @@ class Connection {
    * @return {Promise<object>} with muxed+multistream-selected stream and selected protocol
    */
   async newStream (protocols) {
-    if (this.stat.status === 'closing') {
+    if (this.stat.status === Status.CLOSING) {
       throw errCode(new Error('the connection is being closed'), 'ERR_CONNECTION_BEING_CLOSED')
     }
 
-    if (this.stat.status === 'closed') {
+    if (this.stat.status === Status.CLOSED) {
       throw errCode(new Error('the connection is closed'), 'ERR_CONNECTION_CLOSED')
     }
 
@@ -175,7 +175,7 @@ class Connection {
    * @return {Promise}
    */
   async close () {
-    if (this.stat.status === 'closed') {
+    if (this.stat.status === Status.CLOSED) {
       return
     }
 
@@ -183,13 +183,13 @@ class Connection {
       return this._closing
     }
 
-    this.stat.status = 'closing'
+    this.stat.status = Status.CLOSING
 
     // Close raw connection
     this._closing = await this._close()
 
     this._stat.timeline.close = Date.now()
-    this.stat.status = 'closed'
+    this.stat.status = Status.CLOSED
   }
 }
 

src/connection/status.js

@@ -0,0 +1,7 @@
+'use strict'
+
+module.exports = {
+  OPEN: 'open',
+  CLOSING: 'closing',
+  CLOSED: 'closed'
+}

src/connection/tests/connection.js

@@ -6,6 +6,7 @@ const chai = require('chai')
 const expect = chai.expect
 chai.use(require('dirty-chai'))
 const sinon = require('sinon')
+const Status = require('../status')
 
 module.exports = (test) => {
   describe('connection', () => {
@@ -28,7 +29,7 @@ module.exports = (test) => {
         expect(connection.remotePeer).to.exist()
         expect(connection.localAddr).to.exist()
         expect(connection.remoteAddr).to.exist()
-        expect(connection.stat.status).to.equal('open')
+        expect(connection.stat.status).to.equal(Status.OPEN)
         expect(connection.stat.timeline.open).to.exist()
         expect(connection.stat.timeline.upgraded).to.exist()
         expect(connection.stat.timeline.close).to.not.exist()
@@ -40,7 +41,7 @@ module.exports = (test) => {
       it('should get the metadata of an open connection', () => {
         const stat = connection.stat
 
-        expect(stat.status).to.equal('open')
+        expect(stat.status).to.equal(Status.OPEN)
         expect(stat.direction).to.exist()
         expect(stat.timeline.open).to.exist()
         expect(stat.timeline.upgraded).to.exist()
@@ -103,7 +104,7 @@ module.exports = (test) => {
         await connection.close()
 
         expect(connection.stat.timeline.close).to.exist()
-        expect(connection.stat.status).to.equal('closed')
+        expect(connection.stat.status).to.equal(Status.CLOSED)
       })
 
       it('should be able to close the connection after opening a stream', async () => {
@@ -116,7 +117,7 @@ module.exports = (test) => {
         await connection.close()
 
         expect(connection.stat.timeline.close).to.exist()
-        expect(connection.stat.status).to.equal('closed')
+        expect(connection.stat.status).to.equal(Status.CLOSED)
       })
 
       it('should support a proxy on the timeline', async () => {

src/content-routing/README.md

@@ -12,7 +12,7 @@ Publishing a test suite as a module lets multiple modules all ensure compatibili
 # Modules that implement the interface
 
 - [JavaScript libp2p-kad-dht](https://github.com/libp2p/js-libp2p-kad-dht)
-- [JavaScript libp2p-delegated-peer-routing](https://github.com/libp2p/js-libp2p-delegated-peer-routing)
+- [JavaScript libp2p-delegated-content-routing](https://github.com/libp2p/js-libp2p-delegated-content-routing)
 
 # Badge
 

src/crypto/README.md

@@ -0,0 +1,100 @@
+interface-crypto
+==================
+
+> A test suite you can use to implement a libp2p crypto module. A libp2p crypto module is used to ensure all exchanged data between two peers is encrypted.
+
+**Modules that implement the interface**
+
+- [js-libp2p-secio](https://github.com/libp2p/js-libp2p-secio)
+
+## Table of Contents
+- [interface-crypto](#interface-crypto)
+  - [Table of Contents](#table-of-contents)
+  - [Using the Test Suite](#using-the-test-suite)
+  - [API](#api)
+    - [Secure Inbound](#secure-inbound)
+    - [Secure Outbound](#secure-outbound)
+  - [Crypto Errors](#crypto-errors)
+    - [Error Types](#error-types)
+
+## Using the Test Suite
+
+You can also check out the [internal test suite](../../test/crypto/compliance.spec.js) to see the setup in action.
+
+```js
+const tests = require('libp2p-interfaces/src/crypto/tests')
+const yourCrypto = require('./your-crypto')
+
+tests({
+  setup () {
+    // Set up your crypto if needed, then return it
+    return yourCrypto
+  },
+  teardown () {
+    // Clean up your crypto if needed
+  }
+})
+```
+
+## API
+
+- `Crypto`
+  - `protocol<string>`: The protocol id of the crypto module.
+  - `secureInbound<function(PeerId, duplex)>`: Secures inbound connections.
+  - `secureOutbound<function(PeerId, duplex, PeerId)>`: Secures outbound connections.
+
+### Secure Inbound
+
+- `const { conn, remotePeer } = await crypto.secureInbound(localPeer, duplex, [remotePeer])`
+
+Secures an inbound [streaming iterable duplex][iterable-duplex] connection. It returns an encrypted [streaming iterable duplex][iterable-duplex], as well as the [PeerId][peer-id] of the remote peer.
+
+**Parameters**
+- `localPeer` is the [PeerId][peer-id] of the receiving peer.
+- `duplex` is the [streaming iterable duplex][iterable-duplex] that will be encryption.
+- `remotePeer` is the optional [PeerId][peer-id] of the initiating peer, if known. This may only exist during transport upgrades.
+
+**Return Value**
+- `<object>`
+  - `conn<duplex>`: An encrypted [streaming iterable duplex][iterable-duplex].
+  - `remotePeer<PeerId>`: The [PeerId][peer-id] of the remote peer.
+
+### Secure Outbound
+
+- `const { conn, remotePeer } = await crypto.secureOutbound(localPeer, duplex, remotePeer)`
+
+Secures an outbound [streaming iterable duplex][iterable-duplex] connection. It returns an encrypted [streaming iterable duplex][iterable-duplex], as well as the [PeerId][peer-id] of the remote peer.
+
+**Parameters**
+- `localPeer` is the [PeerId][peer-id] of the receiving peer.
+- `duplex` is the [streaming iterable duplex][iterable-duplex] that will be encrypted.
+- `remotePeer` is the [PeerId][peer-id] of the remote peer. If provided, implementations **should** use this to validate the integrity of the remote peer.
+
+**Return Value**
+- `<object>`
+  - `conn<duplex>`: An encrypted [streaming iterable duplex][iterable-duplex].
+  - `remotePeer<PeerId>`: The [PeerId][peer-id] of the remote peer. This **should** match the `remotePeer` parameter, and implementations should enforce this.
+
+[peer-id]: https://github.com/libp2p/js-peer-id
+[iterable-duplex]: https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9#duplex-it
+
+## Crypto Errors
+
+Common crypto errors come with the interface, and can be imported directly. All Errors take an optional message.
+
+```js
+const {
+  InvalidCryptoExchangeError,
+  InvalidCryptoTransmissionError,
+  UnexpectedPeerError
+} = require('libp2p-interfaces/src/crypto/errors')
+
+const error = new UnexpectedPeerError('a custom error message')
+console.log(error.code === UnexpectedPeerError.code) // true
+```
+
+### Error Types
+
+- `InvalidCryptoExchangeError` - Should be thrown when a peer provides data that is insufficient to finish the crypto exchange.
+- `InvalidCryptoTransmissionError` - Should be thrown when an error occurs during encryption/decryption.
+- `UnexpectedPeerError` - Should be thrown when the expected peer id does not match the peer id determined via the crypto exchange.

src/crypto/errors.js

@@ -0,0 +1,40 @@
+'use strict'
+
+class UnexpectedPeerError extends Error {
+  constructor (message = 'Unexpected Peer') {
+    super(message)
+    this.code = UnexpectedPeerError.code
+  }
+
+  static get code () {
+    return 'ERR_UNEXPECTED_PEER'
+  }
+}
+
+class InvalidCryptoExchangeError extends Error {
+  constructor (message = 'Invalid crypto exchange') {
+    super(message)
+    this.code = InvalidCryptoExchangeError.code
+  }
+
+  static get code () {
+    return 'ERR_INVALID_CRYPTO_EXCHANGE'
+  }
+}
+
+class InvalidCryptoTransmissionError extends Error {
+  constructor (message = 'Invalid crypto transmission') {
+    super(message)
+    this.code = InvalidCryptoTransmissionError.code
+  }
+
+  static get code () {
+    return 'ERR_INVALID_CRYPTO_TRANSMISSION'
+  }
+}
+
+module.exports = {
+  UnexpectedPeerError,
+  InvalidCryptoExchangeError,
+  InvalidCryptoTransmissionError
+}

src/crypto/tests/index.js

@@ -0,0 +1,102 @@
+/* eslint-env mocha */
+'use strict'
+
+const duplexPair = require('it-pair/duplex')
+const pipe = require('it-pipe')
+const peers = require('../../utils/peers')
+const { UnexpectedPeerError } = require('../errors')
+const PeerId = require('peer-id')
+const { collect } = require('streaming-iterables')
+const chai = require('chai')
+const expect = chai.expect
+chai.use(require('dirty-chai'))
+
+module.exports = (common) => {
+  describe('interface-crypto', () => {
+    let crypto
+    let localPeer
+    let remotePeer
+    let mitmPeer
+
+    before(async () => {
+      [
+        crypto,
+        localPeer,
+        remotePeer,
+        mitmPeer
+      ] = await Promise.all([
+        common.setup(),
+        PeerId.createFromJSON(peers[0]),
+        PeerId.createFromJSON(peers[1]),
+        PeerId.createFromJSON(peers[2])
+      ])
+    })
+
+    after(() => common.teardown && common.teardown())
+
+    it('has a protocol string', () => {
+      expect(crypto.protocol).to.exist()
+      expect(crypto.protocol).to.be.a('string')
+    })
+
+    it('it wraps the provided duplex connection', async () => {
+      const [localConn, remoteConn] = duplexPair()
+
+      const [
+        inboundResult,
+        outboundResult
+      ] = await Promise.all([
+        crypto.secureInbound(remotePeer, localConn),
+        crypto.secureOutbound(localPeer, remoteConn, remotePeer)
+      ])
+
+      // Echo server
+      pipe(inboundResult.conn, inboundResult.conn)
+
+      // Send some data and collect the result
+      const input = Buffer.from('data to encrypt')
+      const result = await pipe(
+        [input],
+        outboundResult.conn,
+        // Convert BufferList to Buffer via slice
+        (source) => (async function * toBuffer () {
+          for await (const chunk of source) {
+            yield chunk.slice()
+          }
+        })(),
+        collect
+      )
+
+      expect(result).to.eql([input])
+    })
+
+    it('should return the remote peer id', async () => {
+      const [localConn, remoteConn] = duplexPair()
+
+      const [
+        inboundResult,
+        outboundResult
+      ] = await Promise.all([
+        crypto.secureInbound(remotePeer, localConn),
+        crypto.secureOutbound(localPeer, remoteConn, remotePeer)
+      ])
+
+      // Inbound should return the initiator (local) peer
+      expect(inboundResult.remotePeer.id).to.eql(localPeer.id)
+      // Outbound should return the receiver (remote) peer
+      expect(outboundResult.remotePeer.id).to.eql(remotePeer.id)
+    })
+
+    it('inbound connections should verify peer integrity if known', async () => {
+      const [localConn, remoteConn] = duplexPair()
+
+      await Promise.all([
+        crypto.secureInbound(remotePeer, localConn, mitmPeer),
+        crypto.secureOutbound(localPeer, remoteConn, remotePeer)
+      ]).then(expect.fail, (err) => {
+        expect(err).to.exist()
+        expect(err).to.have.property('code', UnexpectedPeerError.code)
+      })
+    })
+  })
+}

src/topology/README.md

@@ -0,0 +1,141 @@
+interface-topology
+========================
+
+> Implementation of the topology interface used by the `js-libp2p` registrar.
+
+Topologies can be used in conjunction with `js-libp2p` to help shape its network and the overlays of its subsystems, such as pubsub and the DHT.
+
+## Table of Contents
+
+- [Implementations](#implementations)
+- [Install](#install)
+- [Modules using the interface](#modulesUsingTheInterface)
+- [Usage](#usage)
+- [Api](#api)
+
+## Implementations
+
+### Topology
+
+A libp2p topology with a group of common peers.
+
+### Multicodec Topology
+
+A libp2p topology with a group of peers that support the same protocol.
+
+## Install
+
+```sh
+$ npm install libp2p-interfaces
+```
+
+## Modules using the interface
+
+TBA
+
+## Usage
+
+###  Topology
+
+```js
+const Topology = require('libp2p-interfaces/src/topology')
+
+const toplogy = new Topology({
+  min: 0,
+  max: 50
+})
+```
+
+### Multicodec Topology
+
+```js
+const MulticodecTopology = require('libp2p-interfaces/src/topology/multicodec-topology')
+
+const toplogy = new MulticodecTopology({
+  min: 0,
+  max: 50,
+  multicodecs: ['/echo/1.0.0'],
+  handlers: {
+    onConnect: (peerInfo, conn) => {},
+    onDisconnect: (peerInfo) => {}
+  }
+})
+```
+
+## API
+
+The `MulticodecTopology` extends the `Topology`, which makes the `Topology` API a subset of the `MulticodecTopology` API.
+
+###  Topology
+
+- `Topology`
+  - `peers<Map<string, PeerInfo>>`: A Map of peers belonging to the topology.
+  - `disconnect<function(PeerInfo)>`: Called when a peer has been disconnected
+
+#### Constructor
+
+```js
+const toplogy = new Topology({
+  min: 0,
+  max: 50,
+  handlers: {
+    onConnect: (peerInfo, conn) => {},
+    onDisconnect: (peerInfo) => {}
+  }
+})
+```
+
+**Parameters**
+- `properties` is an `Object` containing the properties of the topology.
+  - `min` is a `number` with the minimum needed connections (default: 0)
+  - `max` is a `number` with the maximum needed connections (default: Infinity)
+  - `handlers` is an optional `Object` containing the handler called when a peer is connected or disconnected.
+    - `onConnect` is a `function` called everytime a peer is connected in the topology context.
+    - `onDisconnect` is a `function` called everytime a peer is disconnected in the topology context.
+
+#### Set a peer
+
+- `topology.peers.set(id, peerInfo)`
+
+Add a peer to the topology.
+
+**Parameters**
+- `id` is the `string` that identifies the peer to add.
+- `peerInfo` is the [PeerInfo][peer-info] of the peer to add.
+
+#### Notify about a peer disconnected event
+
+- `topology.disconnect(peerInfo)`
+
+**Parameters**
+- `peerInfo` is the [PeerInfo][peer-info] of the peer disconnected.
+
+###  Multicodec Topology
+
+- `MulticodecTopology`
+  - `registrar<Registrar>`: The `Registrar` of the topology. This is set by the `Registrar` during registration.
+  - `peers<Map<string, PeerInfo>>`: The Map of peers that belong to the topology
+  - `disconnect<function(PeerInfo)>`: Disconnects a peer from the topology.
+
+#### Constructor
+
+```js
+const toplogy = new MulticodecTopology({
+  min: 0,
+  max: 50,
+  multicodecs: ['/echo/1.0.0'],
+  handlers: {
+    onConnect: (peerInfo, conn) => {},
+    onDisconnect: (peerInfo) => {}
+  }
+})
+```
+
+**Parameters**
+- `properties` is an `Object` containing the properties of the topology.
+  - `min` is a `number` with the minimum needed connections (default: 0)
+  - `max` is a `number` with the maximum needed connections (default: Infinity)
+  - `multicodecs` is a `Array<String>` with the multicodecs associated with the topology.
+  - `handlers` is an optional `Object` containing the handler called when a peer is connected or disconnected.
+    - `onConnect` is a `function` called everytime a peer is connected in the topology context.
+    - `onDisconnect` is a `function` called everytime a peer is disconnected in the topology context.

src/topology/index.js

@@ -0,0 +1,46 @@
+'use strict'
+
+const withIs = require('class-is')
+
+const noop = () => {}
+
+class Topology {
+  /**
+   * @param {Object} props
+   * @param {number} props.min minimum needed connections (default: 0)
+   * @param {number} props.max maximum needed connections (default: Infinity)
+   * @param {Object} [props.handlers]
+   * @param {function} [props.handlers.onConnect] protocol "onConnect" handler
+   * @param {function} [props.handlers.onDisconnect] protocol "onDisconnect" handler
+   * @constructor
+   */
+  constructor ({
+    min = 0,
+    max = Infinity,
+    handlers = {}
+  }) {
+    this.min = min
+    this.max = max
+
+    // Handlers
+    this._onConnect = handlers.onConnect || noop
+    this._onDisconnect = handlers.onDisconnect || noop
+
+    this.peers = new Map()
+  }
+
+  set registrar (registrar) {
+    this._registrar = registrar
+  }
+
+  /**
+   * Notify about peer disconnected event.
+   * @param {PeerInfo} peerInfo
+   * @returns {void}
+   */
+  disconnect (peerInfo) {
+    this._onDisconnect(peerInfo)
+  }
+}
+
+module.exports = withIs(Topology, { className: 'Topology', symbolName: '@libp2p/js-interfaces/topology' })

src/topology/multicodec-topology.js

@@ -0,0 +1,93 @@
+'use strict'
+
+const assert = require('assert')
+const withIs = require('class-is')
+
+const Topology = require('./index')
+
+class MulticodecTopology extends Topology {
+  /**
+   * @param {Object} props
+   * @param {number} props.min minimum needed connections (default: 0)
+   * @param {number} props.max maximum needed connections (default: Infinity)
+   * @param {Array<string>} props.multicodecs protocol multicodecs
+   * @param {Object} props.handlers
+   * @param {function} props.handlers.onConnect protocol "onConnect" handler
+   * @param {function} props.handlers.onDisconnect protocol "onDisconnect" handler
+   * @constructor
+   */
+  constructor ({
+    min,
+    max,
+    multicodecs,
+    handlers
+  }) {
+    super({ min, max, handlers })
+
+    assert(multicodecs, 'one or more multicodec should be provided')
+    assert(handlers, 'the handlers should be provided')
+    assert(handlers.onConnect && typeof handlers.onConnect === 'function',
+      'the \'onConnect\' handler must be provided')
+    assert(handlers.onDisconnect && typeof handlers.onDisconnect === 'function',
+      'the \'onDisconnect\' handler must be provided')
+
+    this.multicodecs = Array.isArray(multicodecs) ? multicodecs : [multicodecs]
+    this._registrar = undefined
+
+    this._onProtocolChange = this._onProtocolChange.bind(this)
+  }
+
+  set registrar (registrar) {
+    this._registrar = registrar
+    this._registrar.peerStore.on('change:protocols', this._onProtocolChange)
+
+    // Update topology peers
+    this._updatePeers(this._registrar.peerStore.peers.values())
+  }
+
+  /**
+   * Update topology.
+   * @param {Array<PeerInfo>} peerInfoIterable
+   * @returns {void}
+   */
+  _updatePeers (peerInfoIterable) {
+    for (const peerInfo of peerInfoIterable) {
+      if (this.multicodecs.filter(multicodec => peerInfo.protocols.has(multicodec)).length) {
+        // Add the peer regardless of whether or not there is currently a connection
+        this.peers.set(peerInfo.id.toB58String(), peerInfo)
+        // If there is a connection, call _onConnect
+        const connection = this._registrar.getConnection(peerInfo)
+        connection && this._onConnect(peerInfo, connection)
+      } else {
+        // Remove any peers we might be tracking that are no longer of value to us
+        this.peers.delete(peerInfo.id.toB58String())
+      }
+    }
+  }
+
+  /**
+   * Check if a new peer support the multicodecs for this topology.
+   * @param {Object} props
+   * @param {PeerInfo} props.peerInfo
+   * @param {Array<string>} props.protocols
+   */
+  _onProtocolChange ({ peerInfo, protocols }) {
+    const existingPeer = this.peers.get(peerInfo.id.toB58String())
+    const hasProtocol = protocols.filter(protocol => this.multicodecs.includes(protocol))
+
+    // Not supporting the protocol anymore?
+    if (existingPeer && hasProtocol.length === 0) {
+      this._onDisconnect(peerInfo)
+    }
+
+    // New to protocol support
+    for (const protocol of protocols) {
+      if (this.multicodecs.includes(protocol)) {
+        this._updatePeers([peerInfo])
+        return
+      }
+    }
+  }
+}
+
+module.exports = withIs(MulticodecTopology, { className: 'MulticodecTopology', symbolName: '@libp2p/js-interfaces/topology/multicodec-topology' })

src/topology/tests/multicodec-topology.js

@@ -0,0 +1,92 @@
+/* eslint-env mocha */
+
+'use strict'
+
+const chai = require('chai')
+const expect = chai.expect
+chai.use(require('dirty-chai'))
+const sinon = require('sinon')
+
+const PeerId = require('peer-id')
+const PeerInfo = require('peer-info')
+const peers = require('../../utils/peers')
+
+module.exports = (test) => {
+  describe('multicodec topology', () => {
+    let topology, peer
+
+    beforeEach(async () => {
+      topology = await test.setup()
+      if (!topology) throw new Error('missing multicodec topology')
+
+      const id = await PeerId.createFromJSON(peers[0])
+      peer = await PeerInfo.create(id)
+    })
+
+    afterEach(async () => {
+      sinon.restore()
+      await test.teardown()
+    })
+
+    it('should have properties set', () => {
+      expect(topology.multicodecs).to.exist()
+      expect(topology._onConnect).to.exist()
+      expect(topology._onDisconnect).to.exist()
+      expect(topology.peers).to.exist()
+      expect(topology._registrar).to.exist()
+    })
+
+    it('should trigger "onDisconnect" on peer disconnected', () => {
+      sinon.spy(topology, '_onDisconnect')
+      topology.disconnect(peer)
+
+      expect(topology._onDisconnect.callCount).to.equal(1)
+    })
+
+    it('should update peers on protocol change', async () => {
+      sinon.spy(topology, '_updatePeers')
+      expect(topology.peers.size).to.eql(0)
+
+      const id2 = await PeerId.createFromJSON(peers[1])
+      const peer2 = await PeerInfo.create(id2)
+      topology.multicodecs.forEach((m) => peer2.protocols.add(m))
+
+      const peerStore = topology._registrar.peerStore
+      peerStore.emit('change:protocols', {
+        peerInfo: peer2,
+        protocols: Array.from(topology.multicodecs)
+      })
+
+      expect(topology._updatePeers.callCount).to.equal(1)
+      expect(topology.peers.size).to.eql(1)
+    })
+
+    it('should disconnect if peer no longer supports a protocol', async () => {
+      sinon.spy(topology, '_onDisconnect')
+      expect(topology.peers.size).to.eql(0)
+
+      const id2 = await PeerId.createFromJSON(peers[1])
+      const peer2 = await PeerInfo.create(id2)
+      topology.multicodecs.forEach((m) => peer2.protocols.add(m))
+
+      const peerStore = topology._registrar.peerStore
+      peerStore.emit('change:protocols', {
+        peerInfo: peer2,
+        protocols: Array.from(topology.multicodecs)
+      })
+
+      expect(topology.peers.size).to.eql(1)
+
+      topology.multicodecs.forEach((m) => peer2.protocols.delete(m))
+      // Peer does not support the protocol anymore
+      peerStore.emit('change:protocols', {
+        peerInfo: peer2,
+        protocols: []
+      })
+
+      expect(topology.peers.size).to.eql(1)
+      expect(topology._onDisconnect.callCount).to.equal(1)
+      expect(topology._onDisconnect.calledWith(peer2)).to.equal(true)
+    })
+  })
+}

src/topology/tests/topology.js

@@ -0,0 +1,46 @@
+/* eslint-env mocha */
+
+'use strict'
+
+const chai = require('chai')
+const expect = chai.expect
+chai.use(require('dirty-chai'))
+const sinon = require('sinon')
+
+const PeerId = require('peer-id')
+const PeerInfo = require('peer-info')
+const peers = require('../../utils/peers')
+
+module.exports = (test) => {
+  describe('topology', () => {
+    let topology, peer
+
+    beforeEach(async () => {
+      topology = await test.setup()
+      if (!topology) throw new Error('missing multicodec topology')
+
+      const id = await PeerId.createFromJSON(peers[0])
+      peer = await PeerInfo.create(id)
+    })
+
+    afterEach(async () => {
+      sinon.restore()
+      await test.teardown()
+    })
+
+    it('should have properties set', () => {
+      expect(topology.min).to.exist()
+      expect(topology.max).to.exist()
+      expect(topology._onConnect).to.exist()
+      expect(topology._onDisconnect).to.exist()
+      expect(topology.peers).to.exist()
+    })
+
+    it('should trigger "onDisconnect" on peer disconnected', () => {
+      sinon.spy(topology, '_onDisconnect')
+      topology.disconnect(peer)
+
+      expect(topology._onDisconnect.callCount).to.equal(1)
+    })
+  })
+}

src/transport/tests/listen-test.js

@@ -8,6 +8,7 @@ const expect = chai.expect
 chai.use(dirtyChai)
 const sinon = require('sinon')
 
+const pWaitFor = require('p-wait-for')
 const pipe = require('it-pipe')
 const { isValidTick } = require('./utils')
 
@@ -92,6 +93,23 @@ module.exports = (common) => {
       expect(upgradeSpy.callCount).to.equal(2)
     })
 
+    it('should not handle connection if upgradeInbound throws', async () => {
+      sinon.stub(upgrader, 'upgradeInbound').throws()
+
+      const listener = transport.createListener(() => {
+        throw new Error('should not handle the connection if upgradeInbound throws')
+      })
+
+      // Listen
+      await listener.listen(addrs[0])
+
+      // Create a connection to the listener
+      const socket = await transport.dial(addrs[0])
+
+      await pWaitFor(() => typeof socket.timeline.close === 'number')
+      await listener.close()
+    })
+
     describe('events', () => {
       it('connection', (done) => {
         const upgradeSpy = sinon.spy(upgrader, 'upgradeInbound')

test/connection/compliance.spec.js

@@ -3,7 +3,7 @@
 
 const tests = require('../../src/connection/tests')
 const { Connection } = require('../../src/connection')
-const peers = require('../utils/peers')
+const peers = require('../../src/utils/peers')
 const PeerId = require('peer-id')
 const multiaddr = require('multiaddr')
 const pair = require('it-pair')

test/connection/index.spec.js

@@ -0,0 +1,48 @@
+/* eslint-env mocha */
+'use strict'
+
+const { Connection } = require('../../src/connection')
+const peers = require('../../src/utils/peers')
+const PeerId = require('peer-id')
+const pair = require('it-pair')
+
+describe('connection tests', () => {
+  it('should not require local or remote addrs', async () => {
+    const [localPeer, remotePeer] = await Promise.all([
+      PeerId.createFromJSON(peers[0]),
+      PeerId.createFromJSON(peers[1])
+    ])
+    const openStreams = []
+    let streamId = 0
+
+    return new Connection({
+      localPeer,
+      remotePeer,
+      stat: {
+        timeline: {
+          open: Date.now() - 10,
+          upgraded: Date.now()
+        },
+        direction: 'outbound',
+        encryption: '/secio/1.0.0',
+        multiplexer: '/mplex/6.7.0'
+      },
+      newStream: (protocols) => {
+        const id = streamId++
+        const stream = pair()
+
+        stream.close = () => stream.sink([])
+        stream.id = id
+
+        openStreams.push(stream)
+
+        return {
+          stream,
+          protocol: protocols[0]
+        }
+      },
+      close: () => {},
+      getStreams: () => openStreams
+    })
+  })
+})

test/crypto/compliance.spec.js

@@ -0,0 +1,13 @@
+/* eslint-env mocha */
+'use strict'
+
+const tests = require('../../src/crypto/tests')
+const mockCrypto = require('./mock-crypto')
+
+describe('compliance tests', () => {
+  tests({
+    setup () {
+      return mockCrypto
+    }
+  })
+})

test/crypto/mock-crypto.js

@@ -0,0 +1,75 @@
+'use strict'
+
+const PeerId = require('peer-id')
+const handshake = require('it-handshake')
+const duplexPair = require('it-pair/duplex')
+const pipe = require('it-pipe')
+const { UnexpectedPeerError } = require('../../src/crypto/errors')
+
+// A basic transform that does nothing to the data
+const transform = () => {
+  return (source) => (async function * () {
+    for await (const chunk of source) {
+      yield chunk
+    }
+  })()
+}
+
+module.exports = {
+  protocol: 'insecure',
+  secureInbound: async (localPeer, duplex, expectedPeer) => {
+    // 1. Perform a basic handshake.
+    const shake = handshake(duplex)
+    shake.write(localPeer.id)
+    const remoteId = await shake.read()
+    const remotePeer = new PeerId(remoteId.slice())
+    shake.rest()
+
+    if (expectedPeer && expectedPeer.id !== remotePeer.id) {
+      throw new UnexpectedPeerError()
+    }
+
+    // 2. Create your encryption box/unbox wrapper
+    const wrapper = duplexPair()
+    const encrypt = transform() // Use transform iterables to modify data
+    const decrypt = transform()
+
+    pipe(
+      wrapper[0], // We write to wrapper
+      encrypt, // The data is encrypted
+      shake.stream, // It goes to the remote peer
+      decrypt, // Decrypt the incoming data
+      wrapper[0] // Pipe to the wrapper
+    )
+
+    return {
+      conn: wrapper[1],
+      remotePeer
+    }
+  },
+  secureOutbound: async (localPeer, duplex, remotePeer) => {
+    // 1. Perform a basic handshake.
+    const shake = handshake(duplex)
+    shake.write(localPeer.id)
+    const remoteId = await shake.read()
+    shake.rest()
+
+    // 2. Create your encryption box/unbox wrapper
+    const wrapper = duplexPair()
+    const encrypt = transform()
+    const decrypt = transform()
+
+    pipe(
+      wrapper[0], // We write to wrapper
+      encrypt, // The data is encrypted
+      shake.stream, // It goes to the remote peer
+      decrypt, // Decrypt the incoming data
+      wrapper[0] // Pipe to the wrapper
+    )
+
+    return {
+      conn: wrapper[1],
+      remotePeer: new PeerId(remoteId.slice())
+    }
+  }
+}

test/topology/mock-peer-store.js

@@ -0,0 +1,12 @@
+'use strict'
+
+const { EventEmitter } = require('events')
+
+class MockPeerStore extends EventEmitter {
+  constructor (peers) {
+    super()
+    this.peers = peers
+  }
+}
+
+module.exports = MockPeerStore

test/topology/multicodec-topology.spec.js

@@ -0,0 +1,40 @@
+/* eslint-env mocha */
+'use strict'
+
+const tests = require('../../src/topology/tests/multicodec-topology')
+const MulticodecTopology = require('../../src/topology/multicodec-topology')
+const MockPeerStore = require('./mock-peer-store')
+
+describe('multicodec topology compliance tests', () => {
+  tests({
+    setup (properties, registrar) {
+      const multicodecs = ['/echo/1.0.0']
+      const handlers = {
+        onConnect: () => { },
+        onDisconnect: () => { }
+      }
+
+      const topology = new MulticodecTopology({
+        multicodecs,
+        handlers,
+        ...properties
+      })
+
+      if (!registrar) {
+        const peerStore = new MockPeerStore([])
+
+        registrar = {
+          peerStore,
+          getConnection: () => { }
+        }
+      }
+
+      topology.registrar = registrar
+
+      return topology
+    },
+    teardown () {
+      // cleanup resources created by setup()
+    }
+  })
+})

test/topology/topology.spec.js

@@ -0,0 +1,26 @@
+/* eslint-env mocha */
+'use strict'
+
+const tests = require('../../src/topology/tests/topology')
+const Topology = require('../../src/topology')
+
+describe('topology compliance tests', () => {
+  tests({
+    setup (properties) {
+      const handlers = {
+        onConnect: () => { },
+        onDisconnect: () => { }
+      }
+
+      const topology = new Topology({
+        handlers,
+        ...properties
+      })
+
+      return topology
+    },
+    teardown () {
+      // cleanup resources created by setup()
+    }
+  })
+})