diff --git a/doc/API.md b/doc/API.md index 07e5817e..4890264c 100644 --- a/doc/API.md +++ b/doc/API.md @@ -11,9 +11,10 @@ * [`handle`](#handle) * [`unhandle`](#unhandle) * [`ping`](#ping) - * [`addressManager.listen`](#addressManagerlisten) - * [`addressManager.announce`](#addressManagerannounce) - * [`addressManager.noAnnounce`](#addressManagernoannounce) + * [`getAdvertisingMultiaddrs`](#getadvertisingmultiaddrs) + * [`addressManager.getListenMultiaddrs`](#addressmanagergetlistenmultiaddrs) + * [`addressmger.getAnnounceMultiaddrs`](#addressmanagergetannouncemultiaddrs) + * [`addressManager.getNoAnnounceMultiaddrs`](#addressmanagergetnoannouncemultiaddrs) * [`contentRouting.findProviders`](#contentroutingfindproviders) * [`contentRouting.provide`](#contentroutingprovide) * [`contentRouting.put`](#contentroutingput) @@ -66,7 +67,7 @@ Creates an instance of Libp2p. |------|------|-------------| | options | `object` | libp2p options | | options.modules | `Array` | libp2p modules to use | -| [options.addresses] | `{ listen: Array }` | Addresses to use for transport listening and to announce to the network | +| [options.addresses] | `{ listen: Array, announce: Array, noAnnounce: Array }` | Addresses for transport listening and to advertise to the network | | [options.config] | `object` | libp2p modules configuration and core configuration | | [options.connectionManager] | `object` | libp2p Connection Manager configuration | | [options.datastore] | `object` | must implement [ipfs/interface-datastore](https://github.com/ipfs/interface-datastore) (in memory datastore will be used if not provided) | @@ -363,44 +364,108 @@ Pings a given peer and get the operation's latency. const latency = await libp2p.ping(otherPeerId) ``` -### addressManager.listen +## getAdvertisingMultiaddrs -Getter for getting the addresses that the peer is using for listening on libp2p transports. +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.addressManager.listen` +`libp2p.getAdvertisingMultiaddrs()` + +#### Returns + +| Type | Description | +|------|-------------| +| `Array` | Advertising multiaddrs | #### Example ```js // ... -const listenAddresses = libp2p.addressManager.listen +const listenMa = libp2p.getAdvertisingMultiaddrs() // [ ] ``` -### addressManager.announce +### addressManager.getListenMultiaddrs -Getter for getting the addresses that the peer is announcing to other peers in the network. +Get the multiaddrs that were provided for listening on libp2p transports. -`libp2p.addressManager.announce` +`libp2p.addressManager.getListenMultiaddrs()` + +#### Returns + +| Type | Description | +|------|-------------| +| `Array` | Provided listening multiaddrs | + +#### Example ```js // ... -const announceAddresses = libp2p.addressManager.announce +const listenMa = libp2p.addressManager.getListenMultiaddrs() +// [ ] +``` + +### addressManager.getAnnounceMultiaddrs + +Get the multiaddrs that were provided to announce to the network. + +`libp2p.addressManager.getAnnounceMultiaddrs()` + +#### Returns + +| Type | Description | +|------|-------------| +| `Array` | Provided announce multiaddrs | + +#### Example + +```js +// ... +const announceMa = libp2p.addressManager.getAnnounceMultiaddrs() // [ ] ``` -### addressManager.noAnnounce +### addressManager.getNoAnnounceMultiaddrs -Getter for getting the addresses that the peer is not announcing in the network. +Get the multiaddrs that were provided to not announce to the network. -`libp2p.addressManager.noAnnounce` +`libp2p.addressManager.getNoAnnounceMultiaddrs()` + +#### Returns + +| Type | Description | +|------|-------------| +| `Array` | Provided noAnnounce multiaddrs | + +#### Example ```js // ... -const noAnnounceAddresses = libp2p.addressManager.noAnnounce +const noAnnounceMa = libp2p.addressManager.getNoAnnounceMultiaddrs() // [ ] ``` +### transportManager.getAddrs + +Get the multiaddrs that libp2p transports are using to listen on. + +`libp2p.transportManager.getAddrs()` + +#### Returns + +| Type | Description | +|------|-------------| +| `Array` | listening multiaddrs | + +#### Example + +```js +// ... +const listenMa = libp2p.transportManager.getAddrs() +// [ ] + ### contentRouting.findProviders Iterates over all content routers in series to find providers of the given key. diff --git a/doc/CONFIGURATION.md b/doc/CONFIGURATION.md index b70f6933..64abf8af 100644 --- a/doc/CONFIGURATION.md +++ b/doc/CONFIGURATION.md @@ -204,15 +204,19 @@ 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. -- `peerInfo`: a previously created instance of [libp2p/js-peer-info](https://github.com/libp2p/js-peer-info). +- `peerId`: a previously computed 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. - -TODO: Add listen/announce addresses and remove peerInfo!! +- `addresses`: an object containing `listen`, `announce` and `noAnnounce` properties with `Array`: + - `listen` addresses will be provided to the libp2p underlying transports for listening on them. + - `announce` addresses will be used to compute the advertises that the node should advertise to the network. + - `noAnnounce` addresses will be used as a filter to compute the advertises that the node should advertise to the network. ### Examples #### 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 @@ -535,7 +539,6 @@ const node = await Libp2p.create({ As libp2p is designed to be a modular networking library, its usage will vary based on individual project needs. We've included links to some existing project configurations for your reference, in case you wish to replicate their configuration: - - [libp2p-ipfs-nodejs](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/libp2p-nodejs.js) - libp2p configuration used by js-ipfs when running in Node.js - [libp2p-ipfs-browser](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/libp2p-browser.js) - libp2p configuration used by js-ipfs when running in a Browser (that supports WebRTC) diff --git a/doc/GETTING_STARTED.md b/doc/GETTING_STARTED.md index b05cc4f6..9c1ddbc0 100644 --- a/doc/GETTING_STARTED.md +++ b/doc/GETTING_STARTED.md @@ -136,6 +136,8 @@ 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') diff --git a/src/transport-manager.js b/src/transport-manager.js index d0aae705..7bb751f6 100644 --- a/src/transport-manager.js +++ b/src/transport-manager.js @@ -128,7 +128,6 @@ class TransportManager { /** * Starts listeners for each listen Multiaddr. - * Update listen multiaddrs of the Address Manager after the operation. * @async */ async listen () {