Rework the transport upgrade API.

[romanb]

This is a proposal for #953.

Motivation

Although transport upgrades must follow a specific pattern in order for the resulting transport to be usable with a Network or Swarm, that pattern is currently not well reflected in the transport upgrade API. Rather, transport upgrades are somewhat laborious and involve non-trivial code duplication.

Overview

This PR introduces a transport::upgrade::Builder that is obtained from Transport::upgrade. The Builder encodes the previously implicit rules for transport upgrades:

1. Authentication upgrades must happen first.
2. Any number of upgrades may follow.
3. A multiplexer upgrade must happen last.

Since multiplexing is the last (regular) transport upgrade (because that upgrade yields a StreamMuxer which is no longer a AsyncRead / AsyncWrite resource, which the upgrade process is based on),
the upgrade starts with Transport::upgrade and ends with Builder::multiplex, which drops back down to the Transport, providing a fluent API.

Contract for authenticators and multiplexers

Authentication and multiplexer upgrades must adhere to a minimal contract w.r.t their outputs:

1. An authentication upgrade is given an (async) I/O resource C and must produce a pair (I, D) where I: ConnectionInfo and D is a new (async) I/O resource D.

2. A multiplexer upgrade is given an (async) I/O resource C and must produce a M: StreamMuxer.

To that end, two changes to the secio and noise protocols have been made:

1. The secio upgrade now outputs a pair of (PeerId, SecioOutput). The former implements ConnectionInfo and the latter AsyncRead / AsyncWrite, fulfilling the Builder contract.

2. A new NoiseAuthenticated upgrade has been added that wraps around any noise upgrade (i.e. NoiseConfig) and has an output of (PeerId, NoiseOutput), i.e. it checks if the RemoteIdentity from the handshake output is an IdentityKey, failing if that is not the case. This is the standard upgrade procedure one wants for integrating noise with libp2p-core/swarm.

Examples

A typical example before/after:

Before

   let transport = libp2p_tcp::TcpConfig::new()
            .with_upgrade(libp2p_secio::SecioConfig::new(local_key))
            .and_then(move |out, endpoint| {
                let peer_id = out.remote_key.into_peer_id();
                let peer_id2 = peer_id.clone();
                let upgrade = libp2p_mplex::MplexConfig::default()
                    .map_outbound(move |muxer| (peer_id, muxer))
                    .map_inbound(move |muxer| (peer_id2, muxer));
                upgrade::apply(out.stream, upgrade, endpoint)
            });

After

  let transport = libp2p_tcp::TcpConfig::new()
            .upgrade()
            .authenticate(libp2p_secio::SecioConfig::new(local_key))
            .multiplex(libp2p_mplex::MplexConfig::new());

Fore more examples, see the diff, which removes all of the related TODOs.

Since Transport::with_upgrade is removed and transport::upgrade::Upgrade changed to fit into the Builder pipeline, these changes are not fully backward-compatible, but adapting existing code should be easy.

[twittner]

👍

[tomaka]

Nit

[tomaka]

Needs the license.