From 7dcc78ea7a897c3b13f7ab5d5ac3e66d12fe43f4 Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Thu, 9 Apr 2020 12:54:48 +0200 Subject: [PATCH] chore: apply suggestions from code review Co-Authored-By: Jacob Heun --- doc/API.md | 14 +++---- src/peer-store/README.md | 69 +++++++++------------------------- src/peer-store/address-book.js | 14 +++---- src/peer-store/proto-book.js | 12 +++--- 4 files changed, 38 insertions(+), 71 deletions(-) diff --git a/doc/API.md b/doc/API.md index 4a95b2d8..bfaa9f77 100644 --- a/doc/API.md +++ b/doc/API.md @@ -519,7 +519,7 @@ const key = '/key' const { from, val } = await libp2p.contentRouting.get(key) ``` -### peerStore.addressBook.Add +### peerStore.addressBook.add Adds known `multiaddrs` of a given peer. If the peer is not known, it will be set with the provided multiaddrs. @@ -536,7 +536,7 @@ Adds known `multiaddrs` of a given peer. If the peer is not known, it will be se | Type | Description | |------|-------------| -| `Map` | Map of known peers' string identifier with their relevant information [`MultiaddrInfo`](multiaddr-info) | +| `AddressBook` | Returns the Address Book component | #### Example @@ -574,7 +574,7 @@ peerStore.addressBook.delete(peerId) ### peerStore.addressBook.get -Get the known [`MultiaddrInfos`](multiaddr-info) of a provided peer. +Get the known [`MultiaddrInfos`][multiaddr-info] of a provided peer. `peerStore.addressBook.get(peerId)` @@ -588,7 +588,7 @@ Get the known [`MultiaddrInfos`](multiaddr-info) of a provided peer. | Type | Description | |------|-------------| -| `Array` | Array of peer's multiaddr with their relevant information [`MultiaddrInfo`](multiaddr-info) | +| `Array` | Array of peer's multiaddr with their relevant information [`MultiaddrInfo`][multiaddr-info] | #### Example @@ -657,7 +657,7 @@ Set known `multiaddrs` of a given peer. | Type | Description | |------|-------------| -| `Map` | Map of known peers' string identifier with their relevant information [`MultiaddrInfo`](multiaddr-info) | +| `AddressBook` | Returns the Address Book component | #### Example @@ -682,7 +682,7 @@ Add known `protocols` of a given peer. | Type | Description | |------|-------------| -| `Map` | Map of known peers' string identifier with their supported protocols | +| `ProtoBook` | Returns the Proto Book component | #### Example @@ -763,7 +763,7 @@ Set known `protocols` of a given peer. | Type | Description | |------|-------------| -| `Map` | Map of known peers' string identifier with their supported protocols | +| `ProtoBook` | Returns the Proto Book component | #### Example diff --git a/src/peer-store/README.md b/src/peer-store/README.md index a17b26c7..bb309a0d 100644 --- a/src/peer-store/README.md +++ b/src/peer-store/README.md @@ -26,7 +26,7 @@ It is also possible to gather relevant information for peers from other protocol When the PeerStore data is updated, this information might be important for different parties. -Every time a peer needs to dial another peer, it is essential that it knows the multiaddrs used by the peer, in order to perform a successful dial to it. The same is true for pinging a peer. While the `AddressBook` is going to keep its data updated, it will also emit `change:multiaddrs` events so that subsystems/users interested in knowing these changes can be notifyied instead of pooling the `AddressBook`. +Every time a peer needs to dial another peer, it is essential that it knows the multiaddrs used by the peer, in order to perform a successful dial to it. The same is true for pinging a peer. While the `AddressBook` is going to keep its data updated, it will also emit `change:multiaddrs` events so that subsystems/users interested in knowing these changes can be notified instead of polling the `AddressBook`. Everytime a peer starts/stops supporting a protocol, libp2p subsystems or users might need to act accordingly. `js-libp2p` registrar orchestrates known peers, established connections and protocol topologies. This way, once a protocol is supported for a peer, the topology of that protocol should be informed that a new peer may be used and the subsystem can decide if it should open a new stream with that peer or not. For these situations, the `ProtoBook` will emit `change:protocols` events whenever supported protocols of a peer change. @@ -34,36 +34,7 @@ Everytime a peer starts/stops supporting a protocol, libp2p subsystems or users The PeerStore wraps four main components: `addressBook`, `keyBook`, `protocolBook` and `metadataBook`. Moreover, it provides a high level API for those components, as well as data events. -### API - -For the complete API documentation, you should check the [API.md](../../doc/API.md). - -Access to its underlying books: - -- `peerStore.protoBook.*` -- `peerStore.addressBook.*` - -High level operations: - -- [`peerStore.delete(peerId)`](../../doc/API.md#peerstoredelete) - -Deletes the provided peer from every book. - -- [`peerStore.get(peerId)`](../../doc/API.md#peerstoreget) - -Gets the stored information of a given peer. - -- [`peerStore.peers()`](../../doc/API.md#peerstorepeers) - -Gets an array of all the peers, as well as their information. - -### Events - -- `peer` - emitted when a new peer is added. -- `change:multiaadrs` - emitted when a known peer has a different set of multiaddrs. -- `change:protocols` - emitted when a known peer supports a different set of protocols. - -### Components API +### Components #### Address Book @@ -75,23 +46,10 @@ A `peerId.toString()` identifier mapping to a `multiaddrInfo` object, which shou ```js { - multiaddr: , + multiaddr: } ``` -**Note:** except for multiaddr naming, the other properties are placeholders for now and might not be as described in the future milestones. - -- `addressBook.data` -- [`addressBook.add()`](../../doc/API.md#peerstoreaddressbookadd) -- [`addressBook.delete()`](../../doc/API.md#peerstoreaddressbookdelete) -- [`addressBook.get()`](../../doc/API.md#peerstoreaddressbookget) -- [`addressBook.getMultiaddrsForPeer()`](../../doc/API.md#peerstoreaddressbookgetmultiaddrsforpeer) -- [`addressBook.set()`](../../doc/API.md#peerstoreaddressbookset) - -(Future considerations: Further API methods will probably be added in the context of multiaddr validity and multiaddr confidence.) - -**Not Yet Implemented**: Multiaddr Confidence - #### Key Book The `keyBook` tracks the keys of the peers. @@ -106,16 +64,25 @@ The `protoBook` holds the identifiers of the protocols supported by each peer. T A `peerId.toString()` identifier mapping to a `Set` of protocol identifier strings. -- `protoBook.data` -- [`protoBook.add()`](../../doc/API.md#peerstoreprotobookadd) -- [`protoBook.delete()`](../../doc/API.md#peerstoreprotobookdelete) -- [`protoBook.get()`](../../doc/API.md#peerstoreprotobookget) -- [`protoBook.set()`](../../doc/API.md#peerstoreprotobookset) - #### Metadata Book **Not Yet Implemented** +### API + +For the complete API documentation, you should check the [API.md](../../doc/API.md). + +Access to its underlying books: + +- `peerStore.protoBook.*` +- `peerStore.addressBook.*` + +### Events + +- `peer` - emitted when a new peer is added. +- `change:multiaadrs` - emitted when a known peer has a different set of multiaddrs. +- `change:protocols` - emitted when a known peer supports a different set of protocols. + ## Future Considerations - If multiaddr TTLs are added, the PeerStore may schedule jobs to delete all addresses that exceed the TTL to prevent AddressBook bloating diff --git a/src/peer-store/address-book.js b/src/peer-store/address-book.js index 6a08277f..445d731e 100644 --- a/src/peer-store/address-book.js +++ b/src/peer-store/address-book.js @@ -50,7 +50,7 @@ class AddressBook extends Book { * @override * @param {PeerId} peerId * @param {Array} addresses - * @returns {Map>} + * @returns {AddressBook} */ set (peerId, addresses) { if (!PeerId.isPeerId(peerId)) { @@ -64,7 +64,7 @@ class AddressBook extends Book { // Not replace multiaddrs if (!multiaddrInfos.length) { - return this.data + return this } // Already knows the peer @@ -75,7 +75,7 @@ class AddressBook extends Book { // If yes, no changes needed! if (intersection.length === rec.length) { log(`the addresses provided to store are equal to the already stored for ${id}`) - return this.data + return this } } @@ -98,7 +98,7 @@ class AddressBook extends Book { multiaddrs: multiaddrInfos.map((mi) => mi.multiaddr) }) - return this.data + return this } /** @@ -107,7 +107,7 @@ class AddressBook extends Book { * @override * @param {PeerId} peerId * @param {Array} addresses - * @returns {Map>} + * @returns {AddressBook} */ add (peerId, addresses) { if (!PeerId.isPeerId(peerId)) { @@ -130,7 +130,7 @@ class AddressBook extends Book { // The content is the same, no need to update. if (rec && rec.length === multiaddrInfos.length) { log(`the addresses provided to store are already stored for ${id}`) - return this.data + return this } this.data.set(id, multiaddrInfos) @@ -153,7 +153,7 @@ class AddressBook extends Book { this._ps.emit('peer', peerInfo) } - return this.data + return this } /** diff --git a/src/peer-store/proto-book.js b/src/peer-store/proto-book.js index 8a353031..a5c5867e 100644 --- a/src/peer-store/proto-book.js +++ b/src/peer-store/proto-book.js @@ -44,7 +44,7 @@ class ProtoBook extends Book { * @override * @param {PeerId} peerId * @param {Array} protocols - * @returns {Map>} + * @returns {ProtoBook} */ set (peerId, protocols) { if (!PeerId.isPeerId(peerId)) { @@ -67,7 +67,7 @@ class ProtoBook extends Book { // If yes, no changes needed! if (recSet && isSetEqual(recSet, newSet)) { log(`the protocols provided to store are equal to the already stored for ${id}`) - return this.data + return this } this.data.set(id, newSet) @@ -83,7 +83,7 @@ class ProtoBook extends Book { protocols }) - return this.data + return this } /** @@ -92,7 +92,7 @@ class ProtoBook extends Book { * @override * @param {PeerId} peerId * @param {Array} protocols - * @returns {Map>} + * @returns {ProtoBook} */ add (peerId, protocols) { if (!PeerId.isPeerId(peerId)) { @@ -112,7 +112,7 @@ class ProtoBook extends Book { // Any new protocol added? if (recSet.size === newSet.size) { log(`the protocols provided to store are already stored for ${id}`) - return this.data + return this } protocols = [...newSet] @@ -130,7 +130,7 @@ class ProtoBook extends Book { protocols }) - return this.data + return this } }