feat: resolve multiaddrs

.travis.yml

@@ -6,7 +6,8 @@ stages:
   - cov
 
 node_js:
-  - '10'
+  - 'lts/*'
+  - 'stable'
 
 os:
   - linux

README.md

@@ -30,6 +30,7 @@ js-multiaddr
       - [Browser: `<script>` Tag](#browser-script-tag)
   - [Usage](#usage)
   - [API](#api)
+  - [Resolvers](#resolvers)
   - [Contribute](#contribute)
   - [License](#license)
 
@@ -117,6 +118,26 @@ $ node
 
 https://multiformats.github.io/js-multiaddr/
 
+## Resolvers
+
+`multiaddr` allows multiaddrs to be resolved when appropriate resolvers are provided. This module already has resolvers available, but you can also create your own.  Resolvers should always be set in the same module that is calling `multiaddr.resolve()` to avoid conflicts if multiple versions of `multiaddr` are in your dependency tree. 
+To provide multiaddr resolvers you can do:
+
+```js
+const multiaddr = require('multiaddr')
+const resolvers = require('multiaddr/src/resolvers')
+
+multiaddr.resolvers.set('dnsaddr', resolvers.dnsaddrResolver)
+```
+
+The available resolvers are:
+
+|     Name    | type | Description |
+|-------------|------|-------------|
+| `dnsaddrResolver` | `dnsaddr` | dnsaddr resolution with TXT Records |
+
+A resolver receives a `Multiaddr` as a parameter and returns a `Promise<Array<string>>`.
+
 ## Contribute
 
 Contributions welcome. Please check out [the issues](https://github.com/multiformats/js-multiaddr/issues).

package.json

@@ -34,6 +34,8 @@
   "dependencies": {
     "cids": "^1.0.0",
     "class-is": "^1.1.0",
+    "dns-over-http-resolver": "^1.0.0",
+    "err-code": "^2.0.3",
     "is-ip": "^3.1.0",
     "multibase": "^3.0.0",
     "uint8arrays": "^1.1.0",
@@ -45,6 +47,7 @@
     "@types/mocha": "^8.0.1",
     "@types/node": "^14.0.11",
     "aegir": "^26.0.0",
+    "sinon": "^9.2.0",
     "typescript": "^3.9.5"
   },
   "contributors": [
@@ -79,4 +82,4 @@
     "Linus Unnebäck <[email protected]>",
     "Alex Potsides <[email protected]>"
   ]
-}
+}

src/index.d.ts

@@ -152,9 +152,16 @@ declare class Multiaddr {
    * `{IPv4, IPv6}/{TCP, UDP}`
    */
   isThinWaistAddress(addr?: Multiaddr): boolean;
+
+  /**
+   * Resolve multiaddr if containing resolvable hostname.
+   */
+  resolve(): Promise<Array<Multiaddr>>
 }
 
 declare namespace Multiaddr {
+  const resolvers: Map < string, (addr: Multiaddr) => Promise < Array < string >>>
+
   /**
    * Creates a Multiaddr from a node-friendly address object
    */

src/index.js

@@ -5,10 +5,13 @@ const protocols = require('./protocols-table')
 const varint = require('varint')
 const CID = require('cids')
 const withIs = require('class-is')
+const errCode = require('err-code')
 const inspect = Symbol.for('nodejs.util.inspect.custom')
 const uint8ArrayToString = require('uint8arrays/to-string')
 const uint8ArrayEquals = require('uint8arrays/equals')
 
+const resolvers = new Map()
+
 /**
  * Creates a [multiaddr](https://github.com/multiformats/multiaddr) from
  * a Uint8Array, String or another Multiaddr instance
@@ -366,6 +369,38 @@ Multiaddr.prototype.equals = function equals (addr) {
   return uint8ArrayEquals(this.bytes, addr.bytes)
 }
 
+/**
+ * Resolve multiaddr if containing resolvable hostname.
+ *
+ * @param {object} options
+ * @returns {Promise<Array<Multiaddr>>}
+ * @example
+ * Multiaddr.resolvers.set('dnsaddr', resolverFunction)
+ * const mh1 = Multiaddr('/dnsaddr/bootstrap.libp2p.io/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb')
+ * const resolvedMultiaddrs = await mh1.resolve()
+ * // [
+ * //   <Multiaddr 04934b5353060fa1a503221220c10f9319dac35c270a6b74cd644cb3acfc1f6efc8c821f8eb282599fd1814f64 - /ip4/147.75.83.83/tcp/4001/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb>,
+ * //   <Multiaddr 04934b53530601bbde03a503221220c10f9319dac35c270a6b74cd644cb3acfc1f6efc8c821f8eb282599fd1814f64 - /ip4/147.75.83.83/tcp/443/wss/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb>,
+ * //   <Multiaddr 04934b535391020fa1cc03a503221220c10f9319dac35c270a6b74cd644cb3acfc1f6efc8c821f8eb282599fd1814f64 - /ip4/147.75.83.83/udp/4001/quic/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb>
+ * // ]
+ */
+Multiaddr.prototype.resolve = async function resolve () {
+  const resolvableProto = this.protos().find((p) => p.resolvable)
+
+  // Multiaddr is not resolvable?
+  if (!resolvableProto) {
+    return [this]
+  }
+
+  const resolver = resolvers.get(resolvableProto.name)
+  if (!resolver) {
+    throw errCode(new Error(`no available resolver for ${resolvableProto.name}`), 'ERR_NO_AVAILABLE_RESOLVER')
+  }
+
+  const addresses = await resolver(this)
+  return addresses.map(a => Multiaddr(a))
+}
+
 /**
  * Gets a Multiaddrs node-friendly address object. Note that protocol information
  * is left out: in Node (and most network systems) the protocol is unknowable
@@ -516,4 +551,5 @@ Multiaddr.resolve = function resolve (addr) {
   return Promise.reject(new Error('not implemented yet'))
 }
 
+Multiaddr.resolvers = resolvers
 exports = module.exports = Multiaddr

src/resolvers/dns.js

@@ -0,0 +1,11 @@
+'use strict'
+
+let dns
+
+try {
+  dns = require('dns').promises
+} catch (err) {
+  dns = require('dns-over-http-resolver')
+}
+
+module.exports = dns

src/resolvers/index.js

@@ -0,0 +1,34 @@
+'use strict'
+
+const Multiaddr = require('..') // eslint-disable-line  no-unused-vars
+const protocols = require('../protocols-table')
+
+const { code: dnsaddrCode } = protocols('dnsaddr')
+
+/**
+ * Resolver for dnsaddr addresses.
+ *
+ * @param {Multiaddr} addr
+ * @returns {Promise<Array<string>>}
+ */
+async function dnsaddrResolver (addr) {
+  const { Resolver } = require('./dns')
+  const resolver = new Resolver()
+
+  const peerId = addr.getPeerId()
+  const [, hostname] = addr.stringTuples().find(([proto]) => proto === dnsaddrCode) || []
+
+  const records = await resolver.resolveTxt(`_dnsaddr.${hostname}`)
+  // @ts-ignore
+  let addresses = records.flat().map((a) => a.split('=')[1])
+
+  if (peerId) {
+    addresses = addresses.filter((entry) => entry.includes(peerId))
+  }
+
+  return addresses
+}
+
+module.exports = {
+  dnsaddrResolver
+}

test/resolvers.spec.js

@@ -0,0 +1,103 @@
+/* eslint-env mocha */
+'use strict'
+
+const { expect } = require('aegir/utils/chai')
+const sinon = require('sinon')
+
+const multiaddr = require('../src')
+const resolvers = require('../src/resolvers')
+const { Resolver } = require('../src/resolvers/dns')
+
+const dnsaddrStub1 = [
+  ['dnsaddr=/dnsaddr/ams-1.bootstrap.libp2p.io/p2p/QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd'],
+  ['dnsaddr=/dnsaddr/ams-2.bootstrap.libp2p.io/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb'],
+  ['dnsaddr=/dnsaddr/lon-1.bootstrap.libp2p.io/p2p/QmSoLMeWqB7YGVLJN3pNLQpmmEk35v6wYtsMGLzSr5QBU3'],
+  ['dnsaddr=/dnsaddr/nrt-1.bootstrap.libp2p.io/p2p/QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt'],
+  ['dnsaddr=/dnsaddr/nyc-1.bootstrap.libp2p.io/p2p/QmSoLueR4xBeUbY9WZ9xGUUxunbKWcrNFTDAadQJmocnWm'],
+  ['dnsaddr=/dnsaddr/sfo-2.bootstrap.libp2p.io/p2p/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z']
+]
+
+const dnsaddrStub2 = [
+  ['dnsaddr=/ip4/147.75.83.83/tcp/4001/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb'],
+  ['dnsaddr=/ip4/147.75.83.83/tcp/443/wss/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb'],
+  ['dnsaddr=/ip4/147.75.83.83/udp/4001/quic/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb'],
+  ['dnsaddr=/ip6/2604:1380:2000:7a00::1/tcp/4001/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb'],
+  ['dnsaddr=/ip6/2604:1380:2000:7a00::1/tcp/443/wss/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb'],
+  ['dnsaddr=/ip6/2604:1380:2000:7a00::1/udp/4001/quic/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb']
+]
+
+describe('multiaddr resolve', () => {
+  it('should throw if no resolver is available', async () => {
+    const ma = multiaddr('/dnsaddr/bootstrap.libp2p.io')
+
+    // Resolve
+    await expect(ma.resolve()).to.eventually.be.rejected()
+      .and.to.have.property('code', 'ERR_NO_AVAILABLE_RESOLVER')
+  })
+
+  describe('dnsaddr', () => {
+    before(() => {
+      // Set resolvers
+      multiaddr.resolvers.set('dnsaddr', resolvers.dnsaddrResolver)
+    })
+
+    afterEach(() => {
+      sinon.restore()
+    })
+
+    it('can resolve dnsaddr without no peerId', async () => {
+      const ma = multiaddr('/dnsaddr/bootstrap.libp2p.io')
+
+      const stub = sinon.stub(Resolver.prototype, 'resolveTxt')
+      stub.onCall(0).returns(Promise.resolve(dnsaddrStub1))
+
+      // Resolve
+      const resolvedMas = await ma.resolve()
+
+      expect(resolvedMas).to.have.length(dnsaddrStub1.length)
+      resolvedMas.forEach((ma, index) => {
+        const stubAddr = dnsaddrStub1[index][0].split('=')[1]
+
+        expect(ma.equals(multiaddr(stubAddr))).to.equal(true)
+      })
+    })
+
+    it('can resolve dnsaddr with peerId', async () => {
+      const ma = multiaddr('/dnsaddr/bootstrap.libp2p.io/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb')
+
+      const stub = sinon.stub(Resolver.prototype, 'resolveTxt')
+      stub.onCall(0).returns(Promise.resolve(dnsaddrStub1))
+      stub.onCall(1).returns(Promise.resolve(dnsaddrStub2))
+
+      // Resolve
+      const resolvedMas = await ma.resolve()
+
+      expect(resolvedMas).to.have.length(1)
+      expect(resolvedMas[0].equals(multiaddr('/dnsaddr/ams-2.bootstrap.libp2p.io/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb'))).to.eql(true)
+    })
+
+    it('can resolve dnsaddr with peerId two levels', async () => {
+      const ma = multiaddr('/dnsaddr/bootstrap.libp2p.io/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb')
+
+      const stub = sinon.stub(Resolver.prototype, 'resolveTxt')
+      stub.onCall(0).returns(Promise.resolve(dnsaddrStub1))
+      stub.onCall(1).returns(Promise.resolve(dnsaddrStub2))
+
+      // Resolve
+      const resolvedInitialMas = await ma.resolve()
+      const resolvedSecondMas = await Promise.all(resolvedInitialMas.map(nm => {
+        //  nm.resolvers.set('dnsaddr', resolvers.dnsaddrResolver)
+        return nm.resolve()
+      }))
+      // @ts-ignore
+      const resolvedMas = resolvedSecondMas.flat()
+
+      expect(resolvedMas).to.have.length(dnsaddrStub2.length)
+      resolvedMas.forEach((ma, index) => {
+        const stubAddr = dnsaddrStub2[index][0].split('=')[1]
+
+        expect(ma.equals(multiaddr(stubAddr))).to.equal(true)
+      })
+    })
+  })
+})