docs: add migration guide from 0.26 to 0.27 (#543)

* docs: add migration guide from 0.26 to 0.27

* docs(fix): relative links

* chore(docs): apply suggestions from code review

* chore: apply review suggestions

* chore: remove unwanted log
This commit is contained in:
Jacob Heun 2020-01-30 13:03:15 +01:00 committed by GitHub
parent ed0c2cb6c1
commit f39e8f0da9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -0,0 +1,178 @@
# Migrating to the new API
A migration guide for refactoring your application code from libp2p v0.26.x to v0.27.0.
## Table of Contents
- [Migrating from callbacks](#migrating-from-callbacks)
- [Pull Streams to Streaming Iterables](#pull-streams-to-streaming-iterables)
- [Sample API Migrations](#sample-api-migrations)
- [Registering Protocol Handlers](#registering-protocol-handlers)
- [Dialing and Sending Data](#dialing-and-sending-data)
- [Checking if a peer is connected](#checking-if-a-peer-is-connected)
- [Pinging another peer](#pinging-another-peer)
- [Pubsub](#pubsub)
- [Getting subscribers](#getting-subscribers)
- [Getting subscribed topics](#getting-subscribed-topics)
## Migrating from callbacks
Callbacks are no longer supported in the libp2p API, as the API has now fully moved to async / await. You can see a full list of the available methods in the [API readme][api]
**Before**
```js
libp2p.start((err) => {
if (err) throw err
console.log('libp2p started')
})
```
**After**
```js
await libp2p.start()
console.log('libp2p started')
```
## Pull Streams to Streaming Iterables
The libp2p API no longer supports Pull Streams and has migrated to [Streaming Iterables][streaming_iterable]. If you would like to continue using Pull Streams in your application code, or need additional time to migrate your code base, you can leverage the conversion modules [async-iterator-to-pull-stream](https://github.com/alanshaw/async-iterator-to-pull-stream) and [pull-stream-to-async-iterator](https://github.com/alanshaw/pull-stream-to-async-iterator).
For a growing list of async iterator modules, you should follow the [it-awesome repo][it_awesome].
## Sample API Migrations
### Registering Protocol Handlers
Protocol registration is very similar to how it previously was, however, the handler now takes a single parameter containing the incoming stream and its protocol. Additionally, you can now pass an array of protocols to `.handle`, but a single string is still supported.
**Before**
```js
const pull = require('pull-stream')
libp2p.handle('/echo/1.0.0', (protocol, conn) => pull(conn, conn))
```
**After**
```js
const pipe = require('it-pipe')
libp2p.handle(['/echo/1.0.0'], ({ protocol, stream }) => pipe(stream, stream))
```
### Dialing and Sending Data
`dialProtocol` no longer takes a callback, and will now return a [Streaming Iterable][streaming_iterable] and the protocol that was successfully negotiated. The new stream can be used with async iterator modules, see [it-awesome][it_awesome], instead of pull streams.
**Before**
```js
const pull = require('pull-stream')
libp2p.dialProtocol(peerInfo, '/echo/1.0.0', (err, conn) => {
if (err) { throw err }
pull(
pull.values(['hey']),
conn,
pull.drain((data) => {
console.log('received echo:', data.toString())
}, (err) => {
if (err) { throw err }
})
)
})
```
**After**
```js
const pipe = require('it-pipe')
const { protocol, stream } = await libp2p.dialProtocol(peerInfo, '/echo/1.0.0')
await pipe(
['hey'],
stream,
async function (source) {
for await (const data of source) {
console.log('received echo:', data.toString())
}
}
)
```
### Checking if a peer is connected
`peerInfo.isConnected` has been deprecated. libp2p now tracks all connections centrally and will no longer update the state of `peerInfo.isConnected`. Consumers should switch to using `libp2p.registrar.getConnection(peerInfo)`, which will return an open connection to that peer if one exists.
**Before**
```js
if (peerInfo.isConnected()) {
// ...do something if connected
}
```
**After**
```js
const connection = libp2p.registrar.getConnection(peerInfo)
if (connection) {
// ...do something if connected
}
```
### Pinging another peer
`libp2p.ping` will no longer callback with a `Ping` event emitter. The internal logic has been simplified to give more flexibility to the API. `libp2p.ping` will now execute a single ping and return the latency.
**Before**
```js
libp2p.ping(peerInfo, (err, ping) => {
if (err) throw err
ping.once('ping', (latency) => {
console.log('Latency is %s ms', latency)
ping.stop()
})
ping.start()
})
```
**After**
```js
const latency = await libp2p.ping(peerInfo)
console.log('Latency is %s ms', latency)
```
### Pubsub
#### Getting subscribers
`libp2p.pubsub.peers()` is now `libp2p.pubsub.getSubscribers()` and is no longer an asynchronous action.
**Before**
```js
libp2p.pubsub.peers(topic, (err, subscribers) => {
if (err) throw err
console.log('Subscribers:', subscribers)
})
```
**After**
```js
const subscribers = libp2p.pubsub.getSubscribers(topic)
console.log('Subscribers:', subscribers)
```
#### Getting subscribed topics
`libp2p.pubsub.ls()` is now `libp2p.pubsub.getTopics()` and is no longer an asynchronous action.
**Before**
```js
libp2p.pubsub.ls((err, topics) => {
if (err) throw err
console.log('Topics:', topics)
})
```
**After**
```js
const topics = libp2p.pubsub.getTopics()
console.log('Topics:', topics)
```
[api]: ../API.md
[it_awesome]: https://github.com/alanshaw/it-awesome
[streaming_iterable]: ../STREAMING_ITERABLES.md