From f39e8f0da953557b5412e3e7e3bb82c56f6b0786 Mon Sep 17 00:00:00 2001 From: Jacob Heun Date: Thu, 30 Jan 2020 13:03:15 +0100 Subject: [PATCH] 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 --- doc/migrations/v0.26-v0.27.md | 178 ++++++++++++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 doc/migrations/v0.26-v0.27.md diff --git a/doc/migrations/v0.26-v0.27.md b/doc/migrations/v0.26-v0.27.md new file mode 100644 index 00000000..599b54bc --- /dev/null +++ b/doc/migrations/v0.26-v0.27.md @@ -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