Add helpers to create a transport with secio and mplex/yamux

[tomaka]

Most people just want secio, mplex and yamux. We should add a helper that easily creates a transport like that.

[tomaka]

An important motivation for this change is that we want to reserve the right to break the API of the underlying combinators, and it would be nicer if we could avoid breaking everyone's code in the process.

[dvdplm]

What API do you have in mind for this? let t = AllYouEverNeedTransport::new() with a builder to set up options? Or more similar to what we do today, something like

let t = CommonTransport::new()
    .with_upgrade(secio::SecioConfig::new(key))
    .with_upgrade(yamux::Config::default())

[tomaka]

What API do you have in mind for this?

That's the difficult part of this issue!

Using with_upgrade doesn't work, as secio produces a SecioOutput while yamux expects a simple stream as input.

[miketang84]

What API do you have in mind for this?

That's the difficult part of this issue!

Using with_upgrade doesn't work, as secio produces a SecioOutput while yamux expects a simple stream as input.

This is ugly and rigid on current API. Very unfriendly!

[dvdplm]

@daogangtang as a user, what would the ideal API look like?

[miketang84]

@daogangtang as a user, what would the ideal API look like?

We wish multiple with_upgrade(), one by one, as above.

[tomaka]

The approach with AllYouEverNeedTransport::new() is the best to me, because:

• It's the most concise and the most simple. Makes it easy to write examples and tests.
• I don't think there are that many different schemes that are going to be used in practice. For example, why would you not want to support TCP or WebSockets in your application? Consequently I don't see why someone would use something else than TCP+WebSockets. Same for muxers. Therefore, in practice, very few combinations of protocols will be used in the wild.
• Right now if we wanted to allow piling up with_upgrade, then we would have to build in mplex and yamux the assumption that they are on top of secio. This is not great. I don't think it is possible to combine with_upgrade and genericity. Combinators (and_then, map, ...) are a bit complicated to use.
• In the future we probably want to add support for protocols such as QUIC, except that QUIC doesn't need secio/mplex/yamux. This complicates even more the stack of combinators.

More specifically, I would go for something like that:

/// Can add support for new protocols, and maybe break backwards compatibility by removing deprecated protocols.
pub fn build_general_transport(k: SecioKeyPair) -> impl Transport {
     build_tcp_ws_secio_mplex_yamux(k)
}
/// Guaranteed to never change.
pub fn build_tcp_ws_secio_mplex_yamux(k: SecioKeyPair) -> impl Transport { ... }

In other words, we would provide one transport for the "general" case, and one transport for the common situations. If the user needs something more fine-grained, they can always fall back to using combinators.

[tomaka]

Similarly I would automatically add a timeout to the Transport returned by these helper functions, but not automatically to the one that the user builds manually.