Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: new api #472

Merged
merged 7 commits into from
Dec 10, 2019
Merged

docs: new api #472

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
e244170
docs: new api
vasco-santos Nov 2, 2019
e9158bd
chore: new iteration
vasco-santos Nov 29, 2019
4d9eabd
chore: apply suggestions from code review
vasco-santos Nov 29, 2019
cfa0136
chore: apply suggestions from code review
vasco-santos Dec 1, 2019
5de2e22
chore: address review
vasco-santos Dec 1, 2019
5699779
docs: add events
vasco-santos Dec 3, 2019
40e3e6b
chore: apply suggestions from code review
vasco-santos Dec 6, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
317 changes: 1 addition & 316 deletions README.md
View file
Open in desktop
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).
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will add in the section before the configuration doc, which will also be linked from the API when relevant


## Development

Expand Down
Loading