Skip to content

Commit

Permalink
docs: new api (#472)
Browse files Browse the repository at this point in the history 
* docs: new api

* chore: new iteration

* chore: apply suggestions from code review

Co-Authored-By: Alan Shaw <alan.shaw@protocol.ai>

* chore: apply suggestions from code review

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

* chore: address review

* docs: add events

* chore: apply suggestions from code review

Co-Authored-By: Jacob Heun <jacobheun@gmail.com>
  • Loading branch information
@vasco-santos @jacobheun
vasco-santos and jacobheun committed Dec 10, 2019
1 parent ec68c8b commit ca474fd
Show file tree
Hide file tree
Showing 2 changed files with 612 additions and 316 deletions.
317 changes: 1 addition & 316 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,6 @@ We've come a long way, but this project is still in Alpha, lots of development i
- [Install](#install)
- [Usage](#usage)
- [API](#api)
- [Events](#events)
- [Development](#development)
- [Tests](#tests)
- [Packages](#packages)
Expand Down Expand Up @@ -209,321 +208,7 @@ class Node extends Libp2p {

### API

**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.

#### Create a Node - `Libp2p.create(options)`

> Behaves exactly like `new Libp2p(options)`, but doesn't require a PeerInfo. One will be generated instead
```js
const { create } = require('libp2p')
const libp2p = await create(options)

await libp2p.start()
```

- `options`: Object of libp2p configuration options

#### Create a Node alternative - `new Libp2p(options)`

> Creates an instance of Libp2p with a custom `PeerInfo` provided via `options.peerInfo`.
Required keys in the `options` object:

- `peerInfo`: instance of [PeerInfo][] that contains the [PeerId][], Keys and [multiaddrs][multiaddr] of the libp2p Node.
- `modules.transport`: An array that must include at least 1 transport, such as `libp2p-tcp`.

#### `libp2p.start(callback)`

> Start the libp2p Node.
`callback` following signature `function (err) {}`, where `err` is an Error in case starting the node fails.

#### `libp2p.stop(callback)`

> Stop the libp2p Node.
`callback` following signature `function (err) {}`, where `err` is an Error in case stopping the node fails.

#### `libp2p.dial(peer, callback)`

> Dials to another peer in the network, establishes the connection.
- `peer`: can be an instance of [PeerInfo][], [PeerId][], [multiaddr][], or a multiaddr string
- `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.

#### `libp2p.dialProtocol(peer, protocol, callback)`

> Dials to another peer in the network and selects a protocol to talk with that peer.
- `peer`: can be an instance of [PeerInfo][], [PeerId][], [multiaddr][], or a multiaddr string
- `protocol`: String that defines the protocol (e.g '/ipfs/bitswap/1.1.0')
- `callback`: Function with signature `function (err, conn) {}`, where `conn` is a [Connection](https://github.com/libp2p/interface-connection) object

`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.

#### `libp2p.dialFSM(peer, protocol, callback)`

> Behaves like `.dial` and `.dialProtocol` but calls back with a Connection State Machine
- `peer`: can be an instance of [PeerInfo][], [PeerId][], [multiaddr][], or a multiaddr string
- `protocol`: an optional String that defines the protocol (e.g '/ipfs/bitswap/1.1.0')
- `callback`: following signature `function (err, connFSM) {}`, where `connFSM` is a [Connection State Machine](https://github.com/libp2p/js-libp2p-switch#connection-state-machine)

#### `libp2p.hangUp(peer, callback)`

> Closes an open connection with a peer, graciously.
- `peer`: can be an instance of [PeerInfo][], [PeerId][] or [multiaddr][]

`callback` following signature `function (err) {}`, where `err` is an Error in case stopping the node fails.

#### `libp2p.peerRouting.findPeer(id, options, callback)`

> Looks up for multiaddrs of a peer in the DHT
- `id`: instance of [PeerId][]
- `options`: object of options
- `options.maxTimeout`: Number milliseconds

#### `libp2p.contentRouting.findProviders(key, options, callback)`

- `key`: Buffer
- `options`: object of options
- `options.maxTimeout`: Number milliseconds
- `options.maxNumProviders` maximum number of providers to find

#### `libp2p.contentRouting.provide(key, callback)`

- `key`: Buffer

#### `libp2p.handle(protocol, handlerFunc [, matchFunc])`

> Handle new protocol
- `protocol`: String that defines the protocol (e.g '/ipfs/bitswap/1.1.0')
- `handlerFunc`: following signature `function (protocol, conn) {}`, where `conn` is a [Connection](https://github.com/libp2p/interface-connection) object
- `matchFunc`: Function for matching on protocol (exact matching, semver, etc). Default to exact match.

#### `libp2p.unhandle(protocol)`

> Stop handling protocol
- `protocol`: String that defines the protocol (e.g '/ipfs/bitswap/1.1.0')

#### Events

##### `libp2p.on('start', () => {})`

> Libp2p has started, along with all its services.
##### `libp2p.on('stop', () => {})`

> Libp2p has stopped, along with all its services.
##### `libp2p.on('error', (err) => {})`

> An error has occurred
- `err`: instance of `Error`

##### `libp2p.on('peer:discovery', (peer) => {})`

> Peer has been discovered.
If `autoDial` is `true`, applications should **not** attempt to connect to the peer
unless they are performing a specific action. See [peer discovery and auto dial](./doc/PEER_DISCOVERY.md) for more information.

- `peer`: instance of [PeerInfo][]

##### `libp2p.on('peer:connect', (peer) => {})`

> We have a new muxed connection to a peer
- `peer`: instance of [PeerInfo][]

##### `libp2p.on('peer:disconnect', (peer) => {})`

> We have closed a connection to a peer
- `peer`: instance of [PeerInfo][]

##### `libp2p.on('connection:start', (peer) => {})`

> We created a new connection to a peer
- `peer`: instance of [PeerInfo][]

##### `libp2p.on('connection:end', (peer) => {})`

> We closed a connection to a peer
- `peer`: instance of [PeerInfo][]

#### `libp2p.isStarted()`

> Check if libp2p is started
#### `libp2p.ping(peer [, options], callback)`

> Ping a node in the network
#### `libp2p.peerBook`

> PeerBook instance of the node
#### `libp2p.peerInfo`

> PeerInfo instance of the node
#### `libp2p.pubsub`

> 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.
---------------------

`DHT methods also exposed for the time being`

#### `libp2p.dht.put(key, value, callback)`

- `key`: Buffer
- `value`: Buffer

#### `libp2p.dht.get(key, options, callback)`

- `key`: Buffer
- `options`: object of options
- `options.maxTimeout`: Number milliseconds

#### `libp2p.dht.getMany(key, nVals, options, callback)`

- `key`: Buffer
- `nVals`: Number
- `options`: object of options
- `options.maxTimeout`: Number milliseconds

[PeerInfo]: https://github.com/libp2p/js-peer-info
[PeerId]: https://github.com/libp2p/js-peer-id
[PeerBook]: https://github.com/libp2p/js-peer-book
[multiaddr]: https://github.com/multiformats/js-multiaddr
[Connection]: https://github.com/libp2p/interface-connection

-------

### Switch Stats API

##### `libp2p.stats.emit('update')`

Every time any stat value changes, this object emits an `update` event.

#### Global stats

##### `libp2p.stats.global.snapshot`

Should return a stats snapshot, which is an object containing the following keys and respective values:

- dataSent: amount of bytes sent, [Big](https://github.com/MikeMcl/big.js#readme) number
- dataReceived: amount of bytes received, [Big](https://github.com/MikeMcl/big.js#readme) number

##### `libp2p.stats.global.movingAverages`

Returns an object containing the following keys:

- dataSent
- dataReceived

Each one of them contains an object that has a key for each interval (`60000`, `300000` and `900000` milliseconds).

Each one of these values is [an exponential moving-average instance](https://github.com/pgte/moving-average#readme).

#### Per-transport stats

##### `libp2p.stats.transports()`

Returns an array containing the tags (string) for each observed transport.

##### `libp2p.stats.forTransport(transportTag).snapshot`

Should return a stats snapshot, which is an object containing the following keys and respective values:

- dataSent: amount of bytes sent, [Big](https://github.com/MikeMcl/big.js#readme) number
- dataReceived: amount of bytes received, [Big](https://github.com/MikeMcl/big.js#readme) number

##### `libp2p.stats.forTransport(transportTag).movingAverages`

Returns an object containing the following keys:

dataSent
dataReceived

Each one of them contains an object that has a key for each interval (`60000`, `300000` and `900000` milliseconds).

Each one of these values is [an exponential moving-average instance](https://github.com/pgte/moving-average#readme).

#### Per-protocol stats

##### `libp2p.stats.protocols()`

Returns an array containing the tags (string) for each observed protocol.

##### `libp2p.stats.forProtocol(protocolTag).snapshot`

Should return a stats snapshot, which is an object containing the following keys and respective values:

- dataSent: amount of bytes sent, [Big](https://github.com/MikeMcl/big.js#readme) number
- dataReceived: amount of bytes received, [Big](https://github.com/MikeMcl/big.js#readme) number


##### `libp2p.stats.forProtocol(protocolTag).movingAverages`

Returns an object containing the following keys:

- dataSent
- dataReceived

Each one of them contains an object that has a key for each interval (`60000`, `300000` and `900000` milliseconds).

Each one of these values is [an exponential moving-average instance](https://github.com/pgte/moving-average#readme).

#### Per-peer stats

##### `libp2p.stats.peers()`

Returns an array containing the peerIDs (B58-encoded string) for each observed peer.

##### `libp2p.stats.forPeer(peerId:String).snapshot`

Should return a stats snapshot, which is an object containing the following keys and respective values:

- dataSent: amount of bytes sent, [Big](https://github.com/MikeMcl/big.js#readme) number
- dataReceived: amount of bytes received, [Big](https://github.com/MikeMcl/big.js#readme) number


##### `libp2p.stats.forPeer(peerId:String).movingAverages`

Returns an object containing the following keys:

- dataSent
- dataReceived

Each one of them contains an object that has a key for each interval (`60000`, `300000` and `900000` milliseconds).

Each one of these values is [an exponential moving-average instance](https://github.com/pgte/moving-average#readme).

#### Stats update interval

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.

### Private Networks

#### Enforcement

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.

#### Protectors

Some available network protectors:
* [libp2p-pnet](https://github.com/libp2p/js-libp2p/tree/master/src/pnet)
See [API.md](./doc/API.md).

## Development

Expand Down
Loading

0 comments on commit ca474fd

Please sign in to comment.