chore: rename address functions and apply suggestions from code review

Co-Authored-By: Jacob Heun <jacobheun@gmail.com>

Author: vasco-santos

doc/API.md

@@ -11,10 +11,10 @@
   * [`handle`](#handle)
   * [`unhandle`](#unhandle)
   * [`ping`](#ping)
-  * [`getAdvertisingMultiaddrs`](#getadvertisingmultiaddrs)
-  * [`addressManager.getListenMultiaddrs`](#addressmanagergetlistenmultiaddrs)
-  * [`addressmger.getAnnounceMultiaddrs`](#addressmanagergetannouncemultiaddrs)
-  * [`addressManager.getNoAnnounceMultiaddrs`](#addressmanagergetnoannouncemultiaddrs)
+  * [`multiaddrs`](#multiaddrs)
+  * [`addressManager.getListenAddrs`](#addressmanagergetlistenaddrs)
+  * [`addressmger.getAnnounceAddrs`](#addressmanagergetannounceaddrs)
+  * [`addressManager.getNoAnnounceAddrs`](#addressmanagergetnoannounceaddrs)
   * [`contentRouting.findProviders`](#contentroutingfindproviders)
   * [`contentRouting.provide`](#contentroutingprovide)
   * [`contentRouting.put`](#contentroutingput)
@@ -364,14 +364,14 @@ Pings a given peer and get the operation's latency.
 const latency = await libp2p.ping(otherPeerId)
 ```
 
-## getAdvertisingMultiaddrs
+## multiaddrs
 
 Get peer advertising multiaddrs. This computes the advertising multiaddrs of the peer by
 joining the multiaddrs that libp2p transports are listening on with the announce multiaddrs
 provided in hte libp2p config. No announce multiaddrs will be filtered out, even when
 using random ports in the provided multiaddrs.
 
-`libp2p.getAdvertisingMultiaddrs()`
+`libp2p.multiaddrs`
 
 #### Returns
 
@@ -383,15 +383,15 @@ using random ports in the provided multiaddrs.
 
 ```js
 // ...
-const listenMa = libp2p.getAdvertisingMultiaddrs()
+const listenMa = libp2p.multiaddrs
 // [ <Multiaddr 047f00000106f9ba - /ip4/127.0.0.1/tcp/63930> ]
 ```
 
-### addressManager.getListenMultiaddrs
+### addressManager.getListenAddrs
 
 Get the multiaddrs that were provided for listening on libp2p transports.
 
-`libp2p.addressManager.getListenMultiaddrs()`
+`libp2p.addressManager.getListenAddrs()`
 
 #### Returns
 
@@ -403,15 +403,15 @@ Get the multiaddrs that were provided for listening on libp2p transports.
 
 ```js
 // ...
-const listenMa = libp2p.addressManager.getListenMultiaddrs()
+const listenMa = libp2p.addressManager.getListenAddrs()
 // [ <Multiaddr 047f00000106f9ba - /ip4/127.0.0.1/tcp/63930> ]
 ```
 
-### addressManager.getAnnounceMultiaddrs
+### addressManager.getAnnounceAddrs
 
 Get the multiaddrs that were provided to announce to the network.
 
-`libp2p.addressManager.getAnnounceMultiaddrs()`
+`libp2p.addressManager.getAnnounceAddrs()`
 
 #### Returns
 
@@ -423,15 +423,15 @@ Get the multiaddrs that were provided to announce to the network.
 
 ```js
 // ...
-const announceMa = libp2p.addressManager.getAnnounceMultiaddrs()
+const announceMa = libp2p.addressManager.getAnnounceAddrs()
 // [ <Multiaddr 047f00000106f9ba - /dns4/peer.io/...> ]
 ```
 
-### addressManager.getNoAnnounceMultiaddrs
+### addressManager.getNoAnnounceAddrs
 
 Get the multiaddrs that were provided to not announce to the network.
 
-`libp2p.addressManager.getNoAnnounceMultiaddrs()`
+`libp2p.addressManager.getNoAnnounceAddrs()`
 
 #### Returns
 
@@ -443,7 +443,7 @@ Get the multiaddrs that were provided to not announce to the network.
 
 ```js
 // ...
-const noAnnounceMa = libp2p.addressManager.getNoAnnounceMultiaddrs()
+const noAnnounceMa = libp2p.addressManager.getNoAnnounceAddrs()
 // [ <Multiaddr 047f00000106f9ba - /ip4/127.0.0.1/tcp/63930> ]
 ```
 

doc/CONFIGURATION.md

@@ -204,7 +204,7 @@ Moreover, the majority of the modules can be customized via option parameters. T
 Besides the `modules` and `config`, libp2p allows other internal options and configurations:
 - `datastore`: an instance of [ipfs/interface-datastore](https://github.com/ipfs/interface-datastore/) modules.
   - This is used in modules such as the DHT. If it is not provided, `js-libp2p` will use an in memory datastore.
-- `peerId`: a previously computed instance of [libp2p/js-peer-id](https://github.com/libp2p/js-peer-id).
+- `peerId`: the identity of the node, an instance of [libp2p/js-peer-id](https://github.com/libp2p/js-peer-id).
   - This is particularly useful if you want to reuse the same `peer-id`, as well as for modules like `libp2p-delegated-content-routing`, which need a `peer-id` in their instantiation.
 - `addresses`: an object containing `listen`, `announce` and `noAnnounce` properties with `Array<string>`:
   - `listen` addresses will be provided to the libp2p underlying transports for listening on them.
@@ -215,8 +215,6 @@ Besides the `modules` and `config`, libp2p allows other internal options and con
 
 #### Basic setup
 
-TODO: should we add to the basic setup the configuration of listen addresses? we should probably make it a required option?
-
 ```js
 // Creating a libp2p node with:
 //   transport: websockets + tcp

doc/GETTING_STARTED.md

@@ -136,15 +136,16 @@ If you want to know more about libp2p stream multiplexing, you should read the f
 
 Now that you have configured a [**Transport**][transport], [**Crypto**][crypto] and [**Stream Multiplexer**](streamMuxer) module, you can start your libp2p node. We can start and stop libp2p using the [`libp2p.start()`](./API.md#start) and [`libp2p.stop()`](./API.md#stop) methods.
 
-TODO: add listen addresses here?
-
 ```js
 const Libp2p = require('libp2p')
 const WebSockets = require('libp2p-websockets')
 const SECIO = require('libp2p-secio')
 const MPLEX = require('libp2p-mplex')
 
 const node = await Libp2p.create({
+  addresses: {
+    listen: ['/ip4/127.0.0.1/tcp/8000/ws']
+  },
   modules: {
     transport: [WebSockets],
     connEncryption: [SECIO],
@@ -156,6 +157,12 @@ const node = await Libp2p.create({
 await node.start()
 console.log('libp2p has started')
 
+const listenAddrs = node.transportManager.getAddrs()
+console.log('libp2p is listening on the following addresses: ', listenAddrs)
+
+const advertiseAddrs = node.multiaddrs
+console.log('libp2p is advertising the following addresses: ', advertiseAddrs)
+
 // stop libp2p
 await node.stop()
 console.log('libp2p has stopped')

src/address-manager/README.md

@@ -8,9 +8,9 @@ These Addresses should be specified in your libp2p [configuration](../../doc/CON
 
 A libp2p node should have a set of listen addresses, which will be used by libp2p underlying transports to listen for dials from other nodes in the network.
 
-Before a libp2p node starts, a set of listen addresses should be provided to the AddressManager, so that when the node is started, the libp2p transports can use them to listen for connections. Accordingly, listen addresses should be specified through the libp2p configuration, in order to have the `AddressManager` created with them.
+Before a libp2p node starts, its configured listen addresses will be passed to the AddressManager, so that during startup the libp2p transports can use them to listen for connections. Accordingly, listen addresses should be specified through the libp2p configuration, in order to have the `AddressManager` created with them.
 
-It is important pointing out that libp2p accepts to listen on addresses that intend to rely on any available local port. In this context, the provided listen addresses might not be exactly the same as the ones used by the transports. For example tcp may replace `/ip4/0.0.0.0/tcp/0` with something like `/ip4/0.0.0.0/tcp/8989`. As a consequence, libp2p should take into account this when advertising its addresses.
+It is important pointing out that libp2p accepts ephemeral listening addresses. In this context, the provided listen addresses might not be exactly the same as the ones used by the transports. For example TCP may replace `/ip4/0.0.0.0/tcp/0` with something like `/ip4/127.0.0.1/tcp/8989`. As a consequence, libp2p should take into account this when determining its advertised addresses.
 
 ## Announce Addresses
 
@@ -22,13 +22,13 @@ Scenarios for Announce Addresses include:
 
 ## No Announce Addresses
 
-While we need to add Announce Addresses to enable peers' connectivity, we can also not announce addresses that will not be reachable. This way, No Announce Addresses should be specified so that they are not announced by the peer as addresses that other peers can use to dial it.
+While we need to add Announce Addresses to enable peers' connectivity, we should also avoid announcing addresses that will not be reachable. No Announce Addresses should be specified so that they are filtered from the advertised multiaddrs.
 
-As stated into the Listen Addresses section, Listen Addresses might get modified after libp2p transports get in action and use them to listen for new connections. This way, libp2p should also take into account these changes so that they can be matched when No Announce Addresses are being filtered out for advertising addresses.
+As stated in the Listen Addresses section, Listen Addresses might be modified by libp2p transports after the successfully bind to those addresses. Libp2p should also take these changes into account so that they can be matched when No Announce Addresses are being filtered out of the advertised multiaddrs.
 
 ## Implementation
 
-When a libp2p node is created, the Address Manager will be populated from the provided addresses through the libp2p configuration. Once the node is started, the Transport Manager component will gather the listen addresses from the Address Manager, so that the libp2p transports use them to listen on.
+When a libp2p node is created, the Address Manager will be populated from the provided addresses through the libp2p configuration. Once the node is started, the Transport Manager component will gather the listen addresses from the Address Manager, so that the libp2p transports can attempt to bind to them.
 
 Libp2p will use the the Address Manager as the source of truth when advertising the peers addresses. After all transports are ready, other libp2p components/subsystems will kickoff, namely the Identify Service and the DHT. Both of them will announce the node addresses to the other peers in the network. The announce and noAnnounce addresses will have an important role here and will be gathered by libp2p to compute its current addresses to advertise everytime it is needed.
 
@@ -40,7 +40,7 @@ In a future iteration, we can enable these addresses to be modified in runtime.
 
 #### Modify Listen Addresses
 
-While adding new addresses to listen on runtime is a feasible operation, removing one listen address might have bad implications for the node, since all the connections using that listen address will be closed. With this in mind and taking also into consideration the lack of good use cases for removing listen addresses, the Address Manager API only allows libp2p users to add new Listen Addresses on runtime.
+While adding new addresses to listen on runtime should be trivial, removing a listen address might have bad implications for the node, since all the connections using that listen address will be closed. However, libp2p should provide a mechanism for both adding and removing listen addresses in the future.
 
 Every time a new listen address is added, the Address Manager should emit an event with the new multiaddrs to listen. The Transport Manager should listen to this events and act accordingly.
 

src/address-manager/index.js

@@ -7,7 +7,7 @@ log.error = debug('libp2p:addresses:error')
 const multiaddr = require('multiaddr')
 
 /**
- * Responsible for managing the peer addresses.
+ * Responsible for managing this peers addresses.
  * Peers can specify their listen, announce and noAnnounce addresses.
  * The listen addresses will be used by the libp2p transports to listen for new connections,
  * while the announce an noAnnounce addresses will be combined with the listen addresses for
@@ -31,23 +31,23 @@ class AddressManager {
    * Get peer listen multiaddrs.
    * @return {Array<Multiaddr>}
    */
-  getListenMultiaddrs () {
+  getListenAddrs () {
     return Array.from(this.listen).map((a) => multiaddr(a))
   }
 
   /**
    * Get peer announcing multiaddrs.
    * @return {Array<Multiaddr>}
    */
-  getAnnounceMultiaddrs () {
+  getAnnounceAddrs () {
     return Array.from(this.announce).map((a) => multiaddr(a))
   }
 
   /**
    * Get peer noAnnouncing multiaddrs.
    * @return {Array<Multiaddr>}
    */
-  getNoAnnounceMultiaddrs () {
+  getNoAnnounceAddrs () {
     return Array.from(this.noAnnounce).map((a) => multiaddr(a))
   }
 }

src/circuit/index.js

@@ -122,7 +122,7 @@ class Circuit {
           type: CircuitPB.Type.HOP,
           srcPeer: {
             id: this.peerId.toBytes(),
-            addrs: this.addressManager.getListenMultiaddrs().map(addr => addr.buffer)
+            addrs: this.addressManager.getListenAddrs().map(addr => addr.buffer)
           },
           dstPeer: {
             id: destinationPeer.toBytes(),

src/identify/index.js

@@ -49,16 +49,16 @@ class IdentifyService {
    * @param {Libp2p} options.libp2p
    * @param {Map<string, handler>} options.protocols A reference to the protocols we support
    */
-  constructor (options) {
+  constructor ({ libp2p, protocols }) {
     /**
      * @property {PeerStore}
      */
-    this.peerStore = options.libp2p.peerStore
+    this.peerStore = libp2p.peerStore
 
     /**
      * @property {ConnectionManager}
      */
-    this.connectionManager = options.libp2p.connectionManager
+    this.connectionManager = libp2p.connectionManager
 
     this.connectionManager.on('peer:connect', (connection) => {
       const peerId = connection.remotePeer
@@ -69,14 +69,14 @@ class IdentifyService {
     /**
      * @property {PeerId}
      */
-    this.peerId = options.libp2p.peerId
+    this.peerId = libp2p.peerId
 
     /**
      * @property {AddressManager}
      */
-    this._libp2p = options.libp2p
+    this._libp2p = libp2p
 
-    this._protocols = options.protocols
+    this._protocols = protocols
 
     this.handleMessage = this.handleMessage.bind(this)
   }
@@ -93,7 +93,7 @@ class IdentifyService {
 
         await pipe(
           [{
-            listenAddrs: this._libp2p.getAdvertisingMultiaddrs().map((ma) => ma.buffer),
+            listenAddrs: this._libp2p.multiaddrs.map((ma) => ma.buffer),
             protocols: Array.from(this._protocols.keys())
           }],
           pb.encode(Message),
@@ -218,7 +218,7 @@ class IdentifyService {
       protocolVersion: PROTOCOL_VERSION,
       agentVersion: AGENT_VERSION,
       publicKey,
-      listenAddrs: this._libp2p.getAdvertisingMultiaddrs().map((ma) => ma.buffer),
+      listenAddrs: this._libp2p.multiaddrs.map((ma) => ma.buffer),
       observedAddr: connection.remoteAddr.buffer,
       protocols: Array.from(this._protocols.keys())
     })

src/index.js

@@ -300,25 +300,15 @@ class Libp2p extends EventEmitter {
    * Get peer advertising multiaddrs by concating the addresses used
    * by transports to listen with the announce addresses.
    * Duplicated addresses and noAnnounce addresses are filtered out.
-   * This takes into account random ports on matching noAnnounce addresses.
    * @return {Array<Multiaddr>}
    */
-  getAdvertisingMultiaddrs () {
+  get multiaddrs () {
     // Filter noAnnounce multiaddrs
-    const filterMa = this.addressManager.getNoAnnounceMultiaddrs()
-
-    // Special filter for noAnnounce addresses using a random port
-    // eg /ip4/0.0.0.0/tcp/0 => /ip4/192.168.1.0/tcp/58751
-    const filterSpecial = filterMa
-      .map((ma) => ({
-        protos: ma.protos(),
-        ...ma.toOptions()
-      }))
-      .filter((op) => op.port === 0)
+    const filterMa = this.addressManager.getNoAnnounceAddrs()
 
     // Create advertising list
     return this.transportManager.getAddrs()
-      .concat(this.addressManager.getAnnounceMultiaddrs())
+      .concat(this.addressManager.getAnnounceAddrs())
       .filter((ma, index, array) => {
         // Filter out if repeated
         if (array.findIndex((otherMa) => otherMa.equals(ma)) !== index) {
@@ -330,16 +320,6 @@ class Libp2p extends EventEmitter {
           return false
         }
 
-        // Filter out if in the special filter
-        const options = ma.toOptions()
-        if (filterSpecial.find((op) =>
-          op.family === options.family &&
-          op.host === options.host &&
-          op.transport === options.transport &&
-          op.protos.length === ma.protos().length
-        )) {
-          return false
-        }
         return true
       })
   }

src/transport-manager.js

@@ -131,7 +131,7 @@ class TransportManager {
    * @async
    */
   async listen () {
-    const addrs = this.libp2p.addressManager.getListenMultiaddrs()
+    const addrs = this.libp2p.addressManager.getListenAddrs()
 
     if (addrs.length === 0) {
       log('no addresses were provided for listening, this node is dial only')

test/addresses/address-manager.spec.js

@@ -32,7 +32,7 @@ describe('Address Manager', () => {
     expect(am.announce.size).to.equal(0)
     expect(am.noAnnounce.size).to.equal(0)
 
-    const listenMultiaddrs = am.getListenMultiaddrs()
+    const listenMultiaddrs = am.getListenAddrs()
     expect(listenMultiaddrs.length).to.equal(2)
     expect(listenMultiaddrs[0].equals(multiaddr(listenAddresses[0]))).to.equal(true)
     expect(listenMultiaddrs[1].equals(multiaddr(listenAddresses[1]))).to.equal(true)
@@ -48,7 +48,7 @@ describe('Address Manager', () => {
     expect(am.announce.size).to.equal(announceAddreses.length)
     expect(am.noAnnounce.size).to.equal(0)
 
-    const announceMultiaddrs = am.getAnnounceMultiaddrs()
+    const announceMultiaddrs = am.getAnnounceAddrs()
     expect(announceMultiaddrs.length).to.equal(1)
     expect(announceMultiaddrs[0].equals(multiaddr(announceAddreses[0]))).to.equal(true)
   })
@@ -63,7 +63,7 @@ describe('Address Manager', () => {
     expect(am.announce.size).to.equal(0)
     expect(am.noAnnounce.size).to.equal(listenAddresses.length)
 
-    const noAnnounceMultiaddrs = am.getNoAnnounceMultiaddrs()
+    const noAnnounceMultiaddrs = am.getNoAnnounceAddrs()
     expect(noAnnounceMultiaddrs.length).to.equal(2)
     expect(noAnnounceMultiaddrs[0].equals(multiaddr(listenAddresses[0]))).to.equal(true)
     expect(noAnnounceMultiaddrs[1].equals(multiaddr(listenAddresses[1]))).to.equal(true)