docs: update addressBook get and getMultiaddrsForPeer return values

* fix: retimer reschedule does not work as interval

* chore: apply suggestions from code review

Co-authored-by: Jacob Heun <jacobheun@gmail.com>

Co-authored-by: Jacob Heun <jacobheun@gmail.com>

CHANGELOG.md

@@ -1,3 +1,13 @@
+<a name="0.28.7"></a>
+## [0.28.7](https://github.com/libp2p/js-libp2p/compare/v0.28.6...v0.28.7) (2020-07-14)
+
+
+### Bug Fixes
+
+* retimer reschedule does not work as interval ([#710](https://github.com/libp2p/js-libp2p/issues/710)) ([999c1b7](https://github.com/libp2p/js-libp2p/commit/999c1b7))
+
+
+
 <a name="0.28.6"></a>
 ## [0.28.6](https://github.com/libp2p/js-libp2p/compare/v0.28.5...v0.28.6) (2020-07-14)
 

MIGRATION_TEMPLATE.md

@@ -0,0 +1,45 @@
+<!--Specify versions for migration below-->
+# Migrating to libp2p@__
+
+A migration guide for refactoring your application code from libp2p v__ to v__.
+
+## Table of Contents
+
+- [API](#api)
+- [Module Updates](#module-updates)
+
+## API
+
+<!--Describe breaking APIs with examples for Before and After
+Example:
+
+### Peer Discovery
+
+__Describe__
+
+**Before**
+
+```js
+
+```
+
+**After**
+
+```js
+
+```
+
+-->
+
+## Module Updates
+
+With this release you should update the following libp2p modules if you are relying on them:
+
+<!--Specify module versions in JSON for migration below.
+It's recommended to check package.json changes for this: 
+`git diff <release> <prev> -- package.json`
+-->
+
+```json
+
+```

doc/API.md

@@ -760,7 +760,7 @@ Get the known [`Addresses`][address] of a provided peer.
 
 | Type | Description |
 |------|-------------|
-| `Array<Address>` | Array of peer's [`Addresses`][address] containing the multiaddr and its metadata |
+| `Array<Address>|undefined` | Array of peer's [`Addresses`][address] containing the multiaddr and its metadata if available, otherwise undefined |
 
 #### Example
 
@@ -797,7 +797,7 @@ Get the known `Multiaddr` of a provided peer. All returned multiaddrs will inclu
 
 | Type | Description |
 |------|-------------|
-| `Array<Multiaddr>` | Array of peer's multiaddr |
+| `Array<Multiaddr>|undefined` | Array of peer's multiaddr if available, otherwise undefined |
 
 #### Example
 

doc/CONFIGURATION.md

@@ -304,7 +304,7 @@ const node = await Libp2p.create({
   },
   config: {
     peerDiscovery: {
-      webRTCStar: {
+      [WebRTCStar.tag]: {
         enabled: true
       }
     }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2p",
-  "version": "0.28.6",
+  "version": "0.28.7",
   "description": "JavaScript implementation of libp2p, a modular peer to peer network stack",
   "leadMaintainer": "Jacob Heun <jacobheun@gmail.com>",
   "main": "src/index.js",

src/connection-manager/index.js

@@ -178,7 +178,7 @@ class ConnectionManager extends EventEmitter {
     const total = received + sent
     this._checkMaxLimit('maxData', total)
     log('metrics update', total)
-    this._timer.reschedule(this._options.pollInterval)
+    this._timer = retimer(this._checkMetrics, this._options.pollInterval)
   }
 
   /**
@@ -291,17 +291,9 @@ class ConnectionManager extends EventEmitter {
   async _autoDial () {
     const minConnections = this._options.minConnections
 
-    const recursiveTimeoutTrigger = () => {
-      if (this._autoDialTimeout) {
-        this._autoDialTimeout.reschedule(this._options.autoDialInterval)
-      } else {
-        this._autoDialTimeout = retimer(this._autoDial, this._options.autoDialInterval)
-      }
-    }
-
     // Already has enough connections
     if (this.size >= minConnections) {
-      recursiveTimeoutTrigger()
+      this._autoDialTimeout = retimer(this._autoDial, this._options.autoDialInterval)
       return
     }
 
@@ -332,7 +324,7 @@ class ConnectionManager extends EventEmitter {
       }
     }
 
-    recursiveTimeoutTrigger()
+    this._autoDialTimeout = retimer(this._autoDial, this._options.autoDialInterval)
   }
 
   /**

src/dialer/index.js

@@ -112,7 +112,7 @@ class Dialer {
       this.peerStore.addressBook.add(id, multiaddrs)
     }
 
-    let addrs = this.peerStore.addressBook.getMultiaddrsForPeer(id)
+    let addrs = this.peerStore.addressBook.getMultiaddrsForPeer(id) || []
 
     // If received a multiaddr to dial, it should be the first to use
     // But, if we know other multiaddrs for the peer, we should try them too.

src/metrics/stats.js

@@ -128,11 +128,7 @@ class Stats extends EventEmitter {
    * @returns {void}
    */
   _resetComputeTimeout () {
-    if (this._timeout) {
-      this._timeout.reschedule(this._nextTimeout())
-    } else {
-      this._timeout = retimer(this._update, this._nextTimeout())
-    }
+    this._timeout = retimer(this._update, this._nextTimeout())
   }
 
   /**

src/peer-store/address-book.js

@@ -168,8 +168,9 @@ class AddressBook extends Book {
   /**
    * Get the known multiaddrs for a given peer. All returned multiaddrs
    * will include the encapsulated `PeerId` of the peer.
+   * Returns `undefined` if there are no known multiaddrs for the given peer.
    * @param {PeerId} peerId
-   * @returns {Array<Multiaddr>}
+   * @returns {Array<Multiaddr>|undefined}
    */
   getMultiaddrsForPeer (peerId) {
     if (!PeerId.isPeerId(peerId)) {

src/peer-store/book.js

@@ -77,8 +77,9 @@ class Book {
 
   /**
    * Get the known data of a provided peer.
+   * Returns `undefined` if there is no available data for the given peer.
    * @param {PeerId} peerId
-   * @returns {Array<Data>}
+   * @returns {Array<Data>|undefined}
    */
   get (peerId) {
     if (!PeerId.isPeerId(peerId)) {

test/dialing/direct.node.js

@@ -96,6 +96,15 @@ describe('Dialing (direct, TCP)', () => {
       .and.to.have.nested.property('._errors[0].code', ErrorCodes.ERR_TRANSPORT_UNAVAILABLE)
   })
 
+  it('should fail to connect if peer has no known addresses', async () => {
+    const dialer = new Dialer({ transportManager: localTM, peerStore })
+    const peerId = await PeerId.createFromJSON(Peers[1])
+
+    await expect(dialer.connectToPeer(peerId))
+      .to.eventually.be.rejectedWith(Error)
+      .and.to.have.nested.property('.code', ErrorCodes.ERR_NO_VALID_ADDRESSES)
+  })
+
   it('should be able to connect to a given peer id', async () => {
     const peerStore = new PeerStore()
     const dialer = new Dialer({