refactor: switch to async iterators

[alanshaw]

BREAKING CHANGE: Switch to using async/await and async iterators. The transport and connection interfaces have changed.

Dials are now abortable! Pass an AbortSignal as signal to the options to abort the connection whenever you like!

For example, abort during dial:

const controller = new AbortController

// Already aborted!
controller.abort()

try {
  const socket = await transport.dial(ma, { signal: controller.signal })
} catch (err) {
  if (err.type === 'aborted') {
    // dial was aborted while connecting...
  }
}

For example, abort after dial:

const { collect } = require('streaming-iterables')
const pipe = require('it-pipe')

const controller = new AbortController

// Successful dial
const socket = await transport.dial(ma, { signal: controller.signal })

const infiniteRandom = {
  [Symbol.asyncIterator] () { return this },
  next () { return new Promise(r => setTimeout(() => r(Math.random()), 1000)) }
}

// Abort after 5s
setTimeout(() => controller.abort(), 5000)

try {
  await pipe(infiniteRandom, socket, collect)
} catch (err) {
  if (err.type === 'aborted') {
    // connection was aborted after connected
  }
}

Note: there is an adapter class that allows use of the new API via the old one, usage: const Websockets = require('libp2p-websockets/src/adapter')

Interface Transport

dial(ma<Multiaddr>, [options<Object>]): Promise<Connection>

Dial to a peer at the given multiaddr, returns a promise that is resolved when the connection has opened. Throws if connection error or any other error opening the connection, including if the connection is aborted.

The promise resolves to a Connection (which is a duplex object) that can be used to communicate with the peer.

Options

• signal - an AbortSignal that can be used to abort the dial. You can obtain one from an AbortController

createListener([options<Object>], [handler<Function<Connection>>]): Listener

Create a new listener, where incoming connections are handled by handler. The handler function is called for each new incoming connection. It is passed a Connection (which is a duplex object). Note the handler param is optional and can be registered later by listening for the 'connected' event.

filter(mas<Multiaddr[]>): Multiaddr[]

Filter the multiaddrs this transport can dial.

Events

listening

After the listener has started listening.

connected

For every new connection. The event handler is passed a Connection (which is a duplex object).

close

After the listener has stopped listening.

Interface Listener

listen(): Promise

getAddrs(): Promise<Multiaddr[]>

Interface Connection

sink<Function>

https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9#sink-it

source<Iterable>

https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9#source-it

getObservedAddrs(): Promise<Multiaddr[]>

close(): Promise

---

• test/adapter/compliance/* are just a copy of the old interface-transport tests

[jacobheun]

With the change over to async/await something that may be valuable to look at adding to dial is AbortController support. Currently in js-libp2p there is no way to abort a dial, which can lead to connection leaks if not properly accounted for. For example, if I dial to a peer that has 4 websocket addresses, we usually want to dial all 4 in parallel as some of them may be inaccurate. Once I get a valid connection back I want to be able to abort the other 3.

It also makes it much easier to properly close outbound dials when shutting a node down.

[dirkmc]

Good idea @jacobheun 👍

[alanshaw]

After some thinking, abort controller support was actually super easy to add using abortable-iterator. The only tricky bit was allowing abort before connection is established.

Should be good for review.

[dirkmc]

interface-transport now has a few extra tests for cancelling dials, which require a new connector object to be passed to setup(). See the libp2p-tcp async/await PR for an example. I also copied the Adapter class into interface-transport, example here.

[jacobheun]

Should we do the async/await update to interface-connection for this? It should be a pretty quick change and will prevent us from needing to come back and update this later.

[alanshaw]

@dirkmc do you want to send a PR for this?

cc @vasco-santos (I know you were thinking of working on it this week)

[dirkmc]

I'm not sure what fields / methods should be required on the interface, I opened an issue to discuss: libp2p/interface-connection#28

[olizilla]

This PR would also get us of pull-ws which depends on ws@1.1.5 which is triggering github vulnrability warnings on projects that depend on js-ipfs...

websockets/ws@c4fe466

[daviddias]

If #master, why not released? //cc @jacobheun

[jacobheun]

That's wrong, this is outdated. We're tackling tcp first and then will circle back to this and the other transports.

[jacobheun]

Superseded by #92