multiaddr - npm Package Compare versions

Comparing version 8.0.0 to 8.1.0

CHANGELOG.md

@@ -0,1 +1,10 @@
+# [8.1.0](https://github.com/multiformats/js-multiaddr/compare/v8.0.0...v8.1.0) (2020-10-29)
+
+
+### Features
+
+* resolve multiaddrs ([#149](https://github.com/multiformats/js-multiaddr/issues/149)) ([525268b](https://github.com/multiformats/js-multiaddr/commit/525268b3727bb9413e58322059d6ece7ec65e7f7))
+
+
+
 <a name="8.0.0"></a>
@@ -2,0 +11,0 @@ # [8.0.0](https://github.com/multiformats/js-multiaddr/compare/v7.5.0...v8.0.0) (2020-08-07)

package.json

 {
   "name": "multiaddr",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "multiaddr implementation (binary + string representation of network addresses)",
@@ -10,4 +10,4 @@ "leadMaintainer": "Jacob Heun <[e-mail]>",
     "lint": "aegir lint",
-    "test": "aegir test",
-    "test:node": "aegir test -t node",
+    "test": "npm run test:node && npm run test:browser",
+    "test:node": "aegir test --ts -t node",
     "test:browser": "aegir test -t browser",
@@ -38,2 +38,4 @@ "test:types": "npx tsc",
     "class-is": "^1.1.0",
+    "dns-over-http-resolver": "^1.0.0",
+    "err-code": "^2.0.3",
     "is-ip": "^3.1.0",
@@ -49,3 +51,4 @@ "multibase": "^3.0.0",
     "@types/node": "^14.0.11",
-    "aegir": "^22.0.0",
+    "aegir": "^28.1.0",
+    "sinon": "^9.2.0",
     "typescript": "^3.9.5"
@@ -61,16 +64,16 @@ },
     "Friedel Ziegelmayer <[e-mail]>",
+    "Richard Littauer <[e-mail]>",
     "Dmitriy Ryajov <[e-mail]>",
-    "Richard Littauer <[e-mail]>",
+    "Marcin Rataj <[e-mail]>",
     "Robert Kiel <[e-mail]>",
     "Maciej Krüger <[e-mail]>",
-    "Marcin Rataj <[e-mail]>",
     "Oli Evans <[e-mail]>",
     "Alan Shaw <[e-mail]>",
     "Steven Allen <[e-mail]>",
+    "Vasco Santos <[e-mail]>",
     "Tony Jin <[e-mail]>",
-    "Sid Harder <[e-mail]>",
     "Stephen Whitmore <[e-mail]>",
+    "Alex Potsides <[e-mail]>",
+    "Trond Arne Bråthen <[e-mail]>",
     "Alessandro Ricottone <[e-mail]>",
-    "Trond Arne Bråthen <[e-mail]>",
-    "Vasco Santos <[e-mail]>",
     "KuhnChris <[e-mail]>",
@@ -84,4 +87,4 @@ "Diogo Silva <[e-mail]>",
     "Linus Unnebäck <[e-mail]>",
-    "Alex Potsides <[e-mail]>"
+    "Sid Harder <[e-mail]>"
   ]
 }

README.md

@@ -33,2 +33,3 @@ js-multiaddr
   - [API](#api)
+  - [Resolvers](#resolvers)
   - [Contribute](#contribute)
@@ -81,4 +82,2 @@ - [License](#license)
 <script src="https://unpkg.com/multiaddr/dist/index.min.js"></script>
-<!-- OR -->
-<script src="https://unpkg.com/multiaddr/dist/index.js"></script>
 ```
@@ -124,2 +123,22 @@
 
+## 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
@@ -126,0 +145,0 @@

src/index.d.ts

@@ -155,5 +155,12 @@ declare type NetOptions = {
   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 >>>
+
   /**
@@ -160,0 +167,0 @@ * Creates a Multiaddr from a node-friendly address object

src/index.js

@@ -8,2 +8,3 @@ 'use strict'
 const withIs = require('class-is')
+const errCode = require('err-code')
 const inspect = Symbol.for('nodejs.util.inspect.custom')
@@ -13,2 +14,4 @@ const uint8ArrayToString = require('uint8arrays/to-string')
 
+const resolvers = new Map()
+
 /**
@@ -18,4 +21,5 @@ * Creates a [multiaddr](https://github.com/multiformats/multiaddr) from
  * public key.
+ *
  * @class Multiaddr
- * @param {(String|Uint8Array|Multiaddr)} addr - If String or Uint8Array, needs to adhere
+ * @param {(string | Uint8Array | Multiaddr)} addr - If String or Uint8Array, needs to adhere
  * to the address format of a [multiaddr](https://github.com/multiformats/multiaddr#string-format)
@@ -56,3 +60,3 @@ * @example
  *
- * @returns {String}
+ * @returns {string}
  * @example
@@ -69,3 +73,3 @@ * Multiaddr('/ip4/127.0.0.1/tcp/4001').toString()
  *
- * @returns {String}
+ * @returns {string}
  * @example
@@ -80,3 +84,3 @@ * JSON.stringify(Multiaddr('/ip4/127.0.0.1/tcp/4001'))
  *
- * @returns {{family: String, host: String, transport: String, port: Number}}
+ * @returns {{family: string, host: string, transport: string, port: number}}
  * @example
@@ -101,3 +105,3 @@ * Multiaddr('/ip4/127.0.0.1/tcp/4001').toOptions()
  *
- * @returns {String}
+ * @returns {string}
  * @example
@@ -118,3 +122,3 @@ * console.log(Multiaddr('/ip4/127.0.0.1/tcp/4001'))
  *
- * @returns {String}
+ * @returns {string}
  * @example
@@ -131,2 +135,11 @@ * Multiaddr('/ip4/127.0.0.1/tcp/4001').inspect()
 /**
+ * @typedef {object} protocol
+ * @property {number} code
+ * @property {number} size
+ * @property {string} name
+ * @property {boolean} [resolvable]
+ * @property {boolean} [path]
+ */
+
+/**
  * Returns the protocols the Multiaddr is defined with, as an array of objects, in
@@ -137,6 +150,3 @@ * left-to-right order. Each object contains the protocol code, protocol name,
  *
- * @returns {Array.<Object>} protocols - All the protocols the address is composed of
- * @returns {Number} protocols[].code
- * @returns {Number} protocols[].size
- * @returns {String} protocols[].name
+ * @returns {protocol[]} protocols - All the protocols the address is composed of
  * @example
@@ -155,3 +165,3 @@ * Multiaddr('/ip4/127.0.0.1/tcp/4001').protos()
  *
- * @returns {Array.<Number>} protocol codes
+ * @returns {Array<number>} protocol codes
  * @example
@@ -183,3 +193,3 @@ * Multiaddr('/ip4/127.0.0.1/tcp/4001').protoCodes()
  *
- * @return {Array.<String>} protocol names
+ * @returns {Array.<string>} protocol names
  * @example
@@ -196,5 +206,3 @@ * Multiaddr('/ip4/127.0.0.1/tcp/4001').protoNames()
  *
- * @return {Array.<Array>} tuples
- * @return {Number} tuples[].0 code of protocol
- * @return {Buffer} tuples[].1 contents of address
+ * @returns {[number, Uint8Array][]} tuples
  * @example
@@ -210,6 +218,6 @@ * Multiaddr("/ip4/127.0.0.1/tcp/4001").tuples()
  * Returns a tuple of string/number parts
+ * - tuples[][0] = code of protocol
+ * - tuples[][1] = contents of address
  *
- * @return {Array.<Array>} tuples
- * @return {Number} tuples[].0 code of protocol
- * @return {(String|Number)} tuples[].1 contents of address
+ * @returns {[number, string|number][]} tuples
  * @example
@@ -228,3 +236,3 @@ * Multiaddr("/ip4/127.0.0.1/tcp/4001").stringTuples()
  * @param {Multiaddr} addr - Multiaddr to add into this Multiaddr
- * @return {Multiaddr}
+ * @returns {Multiaddr}
  * @example
@@ -252,3 +260,3 @@ * const mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080')
  * @param {Multiaddr} addr - Multiaddr to remove from this Multiaddr
- * @return {Multiaddr}
+ * @returns {Multiaddr}
  * @example
@@ -283,4 +291,4 @@ * const mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080')
  *
- * @param {Number} code The code of the protocol to decapsulate from this Multiaddr
- * @return {Multiaddr}
+ * @param {number} code - The code of the protocol to decapsulate from this Multiaddr
+ * @returns {Multiaddr}
  * @example
@@ -309,3 +317,3 @@ * const addr = Multiaddr('/ip4/0.0.0.0/tcp/8080/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC')
  *
- * @return {String|null} peerId - The id of the peer or null if invalid or missing from the ma
+ * @returns {string | null} peerId - The id of the peer or null if invalid or missing from the ma
  * @example
@@ -341,3 +349,3 @@ * const mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080/ipfs/QmValidBase58string')
  *
- * @return {String|null} path - The path of the multiaddr, or null if no path protocol is present
+ * @returns {string | null} path - The path of the multiaddr, or null if no path protocol is present
  * @example
@@ -370,3 +378,3 @@ * const mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080/unix/tmp/p2p.sock')
  * @param {Multiaddr} addr
- * @return {Bool}
+ * @returns {Bool}
  * @example
@@ -390,2 +398,33 @@ * const mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080')
 /**
+ * Resolve multiaddr if containing resolvable hostname.
+ *
+ * @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
@@ -397,3 +436,3 @@ * is left out: in Node (and most network systems) the protocol is unknowable
  *
- * @returns {{family: String, address: String, port: Number}}
+ * @returns {{family: string, address: string, port: number}}
  * @throws {Error} Throws error if Multiaddr is not a Thin Waist address
@@ -427,4 +466,4 @@ * @example
  *
- * @param {{family: String, address: String, port: Number}} addr
- * @param {String} transport
+ * @param {{family: string, address: string, port: number}} addr
+ * @param {string} transport
  * @returns {Multiaddr} multiaddr
@@ -463,3 +502,3 @@ * @throws {Error} Throws error if addr is not truthy
  * @param {Multiaddr} [addr] - Defaults to using `this` instance
- * @returns {Boolean} isThinWaistAddress
+ * @returns {boolean} isThinWaistAddress
  * @example
@@ -512,3 +551,3 @@ * const mh1 = Multiaddr('/ip4/127.0.0.1/tcp/4001')
  * @param {Multiaddr} addr
- * @return {Bool} isName
+ * @returns {Bool} isName
  */
@@ -529,3 +568,3 @@ Multiaddr.isName = function isName (addr) {
  * @param {Multiaddr} addr
- * @return {Multiaddr[]}
+ * @returns {Multiaddr[]}
  */
@@ -545,2 +584,3 @@ Multiaddr.resolve = function resolve (addr) {
 
+Multiaddr.resolvers = resolvers
 exports = module.exports = Multiaddr

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Network access

Supply chain risk

This module accesses the network.

Found 2 instances in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Unidentified License

License

(Experimental) Something that seems like a license was found, but its contents could not be matched with a known license.

Found 1 instance in 1 package

Improved metrics

Number of package files

13

increased by8.33%

Number of low license alerts

0

decreased by-100%

License quality

100

increased by25%

Lines of code

1226

increased by6.24%

Number of lines in readme file

152

increased by14.29%

Worsened metrics

Total package byte prevSize

106556

decreased by-15.3%

Dependency count

8

increased by33.33%

Dev dependency count

7

increased by16.67%

Number of medium supply chain risk alerts

3

increased byInfinity%

Dependency changes

• + Addeddns-over-http-resolver@^1.0.0

• + Addederr-code@^2.0.3

• + Addeddata-uri-to-buffer@4.0.1(transitive)

• + Addeddebug@4.3.7(transitive)

• + Addeddns-over-http-resolver@1.2.3(transitive)

• + Addederr-code@2.0.3(transitive)

• + Addedfetch-blob@3.2.0(transitive)

• + Addedformdata-polyfill@4.0.10(transitive)

• + Addedms@2.1.3(transitive)

• + Addednative-fetch@3.0.0(transitive)

• + Addednode-domexception@1.0.0(transitive)

• + Addednode-fetch@3.3.2(transitive)

• + Addedreceptacle@1.3.2(transitive)

• + Addedweb-streams-polyfill@3.3.3(transitive)