Skip to content

Commit 5699779

Browse files
vasco-santosvasco-santos
committed
docs: add events
1 parent 5de2e22 commit 5699779

File tree

2 files changed

+40
-316
lines changed

2 files changed

+40
-316
lines changed

‎README.md

Lines changed: 1 addition & 316 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,6 @@ We've come a long way, but this project is still in Alpha, lots of development i
5050
- [Install](#install)
5151
- [Usage](#usage)
5252
- [API](#api)
53-
- [Events](#events)
5453
- [Development](#development)
5554
- [Tests](#tests)
5655
- [Packages](#packages)
@@ -209,321 +208,7 @@ class Node extends Libp2p {
209208

210209
### API
211210

212-
**IMPORTANT NOTE**: All the methods listed in the API section that take a callback are also now Promisified. Libp2p is migrating away from callbacks to async/await, and in a future release (that will be announced in advance), callback support will be removed entirely. You can follow progress of the async/await endeavor at https://github.com/ipfs/js-ipfs/issues/1670.
213-
214-
#### Create a Node - `Libp2p.create(options)`
215-
216-
> Behaves exactly like `new Libp2p(options)`, but doesn't require a PeerInfo. One will be generated instead
217-
218-
```js
219-
const { create } = require('libp2p')
220-
const libp2p = await create(options)
221-
222-
await libp2p.start()
223-
```
224-
225-
- `options`: Object of libp2p configuration options
226-
227-
#### Create a Node alternative - `new Libp2p(options)`
228-
229-
> Creates an instance of Libp2p with a custom `PeerInfo` provided via `options.peerInfo`.
230-
231-
Required keys in the `options` object:
232-
233-
- `peerInfo`: instance of [PeerInfo][] that contains the [PeerId][], Keys and [multiaddrs][multiaddr] of the libp2p Node.
234-
- `modules.transport`: An array that must include at least 1 transport, such as `libp2p-tcp`.
235-
236-
#### `libp2p.start(callback)`
237-
238-
> Start the libp2p Node.
239-
240-
`callback` following signature `function (err) {}`, where `err` is an Error in case starting the node fails.
241-
242-
#### `libp2p.stop(callback)`
243-
244-
> Stop the libp2p Node.
245-
246-
`callback` following signature `function (err) {}`, where `err` is an Error in case stopping the node fails.
247-
248-
#### `libp2p.dial(peer, callback)`
249-
250-
> Dials to another peer in the network, establishes the connection.
251-
252-
- `peer`: can be an instance of [PeerInfo][], [PeerId][], [multiaddr][], or a multiaddr string
253-
- `callback` following signature `function (err, conn) {}`, where `err` is an Error in of failure to dial the connection and `conn` is a [Connection][] instance in case of a protocol selected, if not it is undefined.
254-
255-
#### `libp2p.dialProtocol(peer, protocol, callback)`
256-
257-
> Dials to another peer in the network and selects a protocol to talk with that peer.
258-
259-
- `peer`: can be an instance of [PeerInfo][], [PeerId][], [multiaddr][], or a multiaddr string
260-
- `protocol`: String that defines the protocol (e.g '/ipfs/bitswap/1.1.0')
261-
- `callback`: Function with signature `function (err, conn) {}`, where `conn` is a [Connection](https://github.com/libp2p/interface-connection) object
262-
263-
`callback` following signature `function (err, conn) {}`, where `err` is an Error in of failure to dial the connection and `conn` is a [Connection][] instance in case of a protocol selected, if not it is undefined.
264-
265-
#### `libp2p.dialFSM(peer, protocol, callback)`
266-
267-
> Behaves like `.dial` and `.dialProtocol` but calls back with a Connection State Machine
268-
269-
- `peer`: can be an instance of [PeerInfo][], [PeerId][], [multiaddr][], or a multiaddr string
270-
- `protocol`: an optional String that defines the protocol (e.g '/ipfs/bitswap/1.1.0')
271-
- `callback`: following signature `function (err, connFSM) {}`, where `connFSM` is a [Connection State Machine](https://github.com/libp2p/js-libp2p-switch#connection-state-machine)
272-
273-
#### `libp2p.hangUp(peer, callback)`
274-
275-
> Closes an open connection with a peer, graciously.
276-
277-
- `peer`: can be an instance of [PeerInfo][], [PeerId][] or [multiaddr][]
278-
279-
`callback` following signature `function (err) {}`, where `err` is an Error in case stopping the node fails.
280-
281-
#### `libp2p.peerRouting.findPeer(id, options, callback)`
282-
283-
> Looks up for multiaddrs of a peer in the DHT
284-
285-
- `id`: instance of [PeerId][]
286-
- `options`: object of options
287-
- `options.maxTimeout`: Number milliseconds
288-
289-
#### `libp2p.contentRouting.findProviders(key, options, callback)`
290-
291-
- `key`: Buffer
292-
- `options`: object of options
293-
- `options.maxTimeout`: Number milliseconds
294-
- `options.maxNumProviders` maximum number of providers to find
295-
296-
#### `libp2p.contentRouting.provide(key, callback)`
297-
298-
- `key`: Buffer
299-
300-
#### `libp2p.handle(protocol, handlerFunc [, matchFunc])`
301-
302-
> Handle new protocol
303-
304-
- `protocol`: String that defines the protocol (e.g '/ipfs/bitswap/1.1.0')
305-
- `handlerFunc`: following signature `function (protocol, conn) {}`, where `conn` is a [Connection](https://github.com/libp2p/interface-connection) object
306-
- `matchFunc`: Function for matching on protocol (exact matching, semver, etc). Default to exact match.
307-
308-
#### `libp2p.unhandle(protocol)`
309-
310-
> Stop handling protocol
311-
312-
- `protocol`: String that defines the protocol (e.g '/ipfs/bitswap/1.1.0')
313-
314-
#### Events
315-
316-
##### `libp2p.on('start', () => {})`
317-
318-
> Libp2p has started, along with all its services.
319-
320-
##### `libp2p.on('stop', () => {})`
321-
322-
> Libp2p has stopped, along with all its services.
323-
324-
##### `libp2p.on('error', (err) => {})`
325-
326-
> An error has occurred
327-
328-
- `err`: instance of `Error`
329-
330-
##### `libp2p.on('peer:discovery', (peer) => {})`
331-
332-
> Peer has been discovered.
333-
334-
If `autoDial` is `true`, applications should **not** attempt to connect to the peer
335-
unless they are performing a specific action. See [peer discovery and auto dial](./doc/PEER_DISCOVERY.md) for more information.
336-
337-
- `peer`: instance of [PeerInfo][]
338-
339-
##### `libp2p.on('peer:connect', (peer) => {})`
340-
341-
> We have a new muxed connection to a peer
342-
343-
- `peer`: instance of [PeerInfo][]
344-
345-
##### `libp2p.on('peer:disconnect', (peer) => {})`
346-
347-
> We have closed a connection to a peer
348-
349-
- `peer`: instance of [PeerInfo][]
350-
351-
##### `libp2p.on('connection:start', (peer) => {})`
352-
353-
> We created a new connection to a peer
354-
355-
- `peer`: instance of [PeerInfo][]
356-
357-
##### `libp2p.on('connection:end', (peer) => {})`
358-
359-
> We closed a connection to a peer
360-
361-
- `peer`: instance of [PeerInfo][]
362-
363-
#### `libp2p.isStarted()`
364-
365-
> Check if libp2p is started
366-
367-
#### `libp2p.ping(peer [, options], callback)`
368-
369-
> Ping a node in the network
370-
371-
#### `libp2p.peerBook`
372-
373-
> PeerBook instance of the node
374-
375-
#### `libp2p.peerInfo`
376-
377-
> PeerInfo instance of the node
378-
379-
#### `libp2p.pubsub`
380-
381-
> Same API as IPFS PubSub, defined in the [CORE API Spec](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/PUBSUB.md). Just replace `ipfs` by `libp2p` and you are golden.
382-
383-
---------------------
384-
385-
`DHT methods also exposed for the time being`
386-
387-
#### `libp2p.dht.put(key, value, callback)`
388-
389-
- `key`: Buffer
390-
- `value`: Buffer
391-
392-
#### `libp2p.dht.get(key, options, callback)`
393-
394-
- `key`: Buffer
395-
- `options`: object of options
396-
- `options.maxTimeout`: Number milliseconds
397-
398-
#### `libp2p.dht.getMany(key, nVals, options, callback)`
399-
400-
- `key`: Buffer
401-
- `nVals`: Number
402-
- `options`: object of options
403-
- `options.maxTimeout`: Number milliseconds
404-
405-
[PeerInfo]: https://github.com/libp2p/js-peer-info
406-
[PeerId]: https://github.com/libp2p/js-peer-id
407-
[PeerBook]: https://github.com/libp2p/js-peer-book
408-
[multiaddr]: https://github.com/multiformats/js-multiaddr
409-
[Connection]: https://github.com/libp2p/interface-connection
410-
411-
-------
412-
413-
### Switch Stats API
414-
415-
##### `libp2p.stats.emit('update')`
416-
417-
Every time any stat value changes, this object emits an `update` event.
418-
419-
#### Global stats
420-
421-
##### `libp2p.stats.global.snapshot`
422-
423-
Should return a stats snapshot, which is an object containing the following keys and respective values:
424-
425-
- dataSent: amount of bytes sent, [Big](https://github.com/MikeMcl/big.js#readme) number
426-
- dataReceived: amount of bytes received, [Big](https://github.com/MikeMcl/big.js#readme) number
427-
428-
##### `libp2p.stats.global.movingAverages`
429-
430-
Returns an object containing the following keys:
431-
432-
- dataSent
433-
- dataReceived
434-
435-
Each one of them contains an object that has a key for each interval (`60000`, `300000` and `900000` milliseconds).
436-
437-
Each one of these values is [an exponential moving-average instance](https://github.com/pgte/moving-average#readme).
438-
439-
#### Per-transport stats
440-
441-
##### `libp2p.stats.transports()`
442-
443-
Returns an array containing the tags (string) for each observed transport.
444-
445-
##### `libp2p.stats.forTransport(transportTag).snapshot`
446-
447-
Should return a stats snapshot, which is an object containing the following keys and respective values:
448-
449-
- dataSent: amount of bytes sent, [Big](https://github.com/MikeMcl/big.js#readme) number
450-
- dataReceived: amount of bytes received, [Big](https://github.com/MikeMcl/big.js#readme) number
451-
452-
##### `libp2p.stats.forTransport(transportTag).movingAverages`
453-
454-
Returns an object containing the following keys:
455-
456-
dataSent
457-
dataReceived
458-
459-
Each one of them contains an object that has a key for each interval (`60000`, `300000` and `900000` milliseconds).
460-
461-
Each one of these values is [an exponential moving-average instance](https://github.com/pgte/moving-average#readme).
462-
463-
#### Per-protocol stats
464-
465-
##### `libp2p.stats.protocols()`
466-
467-
Returns an array containing the tags (string) for each observed protocol.
468-
469-
##### `libp2p.stats.forProtocol(protocolTag).snapshot`
470-
471-
Should return a stats snapshot, which is an object containing the following keys and respective values:
472-
473-
- dataSent: amount of bytes sent, [Big](https://github.com/MikeMcl/big.js#readme) number
474-
- dataReceived: amount of bytes received, [Big](https://github.com/MikeMcl/big.js#readme) number
475-
476-
477-
##### `libp2p.stats.forProtocol(protocolTag).movingAverages`
478-
479-
Returns an object containing the following keys:
480-
481-
- dataSent
482-
- dataReceived
483-
484-
Each one of them contains an object that has a key for each interval (`60000`, `300000` and `900000` milliseconds).
485-
486-
Each one of these values is [an exponential moving-average instance](https://github.com/pgte/moving-average#readme).
487-
488-
#### Per-peer stats
489-
490-
##### `libp2p.stats.peers()`
491-
492-
Returns an array containing the peerIDs (B58-encoded string) for each observed peer.
493-
494-
##### `libp2p.stats.forPeer(peerId:String).snapshot`
495-
496-
Should return a stats snapshot, which is an object containing the following keys and respective values:
497-
498-
- dataSent: amount of bytes sent, [Big](https://github.com/MikeMcl/big.js#readme) number
499-
- dataReceived: amount of bytes received, [Big](https://github.com/MikeMcl/big.js#readme) number
500-
501-
502-
##### `libp2p.stats.forPeer(peerId:String).movingAverages`
503-
504-
Returns an object containing the following keys:
505-
506-
- dataSent
507-
- dataReceived
508-
509-
Each one of them contains an object that has a key for each interval (`60000`, `300000` and `900000` milliseconds).
510-
511-
Each one of these values is [an exponential moving-average instance](https://github.com/pgte/moving-average#readme).
512-
513-
#### Stats update interval
514-
515-
Stats are not updated in real-time. Instead, measurements are buffered and stats are updated at an interval. The maximum interval can be defined through the `Switch` constructor option `stats.computeThrottleTimeout`, defined in milliseconds.
516-
517-
### Private Networks
518-
519-
#### Enforcement
520-
521-
Libp2p provides support for connection protection, such as for private networks. You can enforce network protection by setting the environment variable `LIBP2P_FORCE_PNET=1`. When this variable is on, if no protector is set via `options.connProtector`, Libp2p will throw an error upon creation.
522-
523-
#### Protectors
524-
525-
Some available network protectors:
526-
* [libp2p-pnet](https://github.com/libp2p/js-libp2p/tree/master/src/pnet)
211+
See [API.md](./doc/API.md).
527212

528213
## Development
529214

‎API.md renamed to ‎doc/API.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,12 @@ Creates an instance of Libp2p.
3434
| Name | Type | Description |
3535
|------|------|-------------|
3636
| options | `Object` | libp2p options |
37+
| options.modules | `Array<Object>` | libp2p modules to use |
38+
| [options.config] | `Object` | libp2p modules configuration and core configuration |
39+
| [options.datastore] | `Object` | must implement [ipfs/interface-datastore](https://github.com/ipfs/interface-datastore) (in memory datastore will be used if not provided) |
40+
| [options.peerInfo] | [PeerInfo](https://github.com/libp2p/js-peer-info) | peerInfo instance (it will be created if not provided) |
41+
42+
For Libp2p configurations and modules details read the [Configuration Document](./CONFIGURATION.md).
3743

3844
#### Returns
3945

@@ -77,6 +83,39 @@ Required keys in the `options` object:
7783

7884
</details>
7985

86+
Once you have a libp2p instance, you are able to listen to several events it emmits, so that you can be noticed of relevant network events.
87+
88+
<details><summary>Events</summary>
89+
90+
#### An error has occurred
91+
92+
`libp2p.on('error', (err) => {})`
93+
94+
- `err`: instance of `Error`
95+
96+
#### A peer has been discovered
97+
98+
`libp2p.on('peer:discovery', (peer) => {})`
99+
100+
If `autoDial` option is `true`, applications should **not** attempt to connect to the peer
101+
unless they are performing a specific action. See [peer discovery and auto dial](./PEER_DISCOVERY.md) for more information.
102+
103+
- `peer`: instance of [PeerInfo][https://github.com/libp2p/js-peer-info]
104+
105+
#### We have a new connection to a peer
106+
107+
`libp2p.on('peer:connect', (peer) => {})`
108+
109+
- `peer`: instance of [PeerInfo][https://github.com/libp2p/js-peer-info]
110+
111+
#### We have closed a connection to a peer
112+
113+
`libp2p.on('peer:disconnect', (peer) => {})`
114+
115+
- `peer`: instance of [PeerInfo][https://github.com/libp2p/js-peer-info]
116+
117+
</details>
118+
80119
## Libp2p Instance Methods
81120

82121
### start

0 commit comments

Comments
 (0)