feat(rt/tokio): additive tokio and hyper i/o adaptors

[cratelyn]

this commit introduces two new i/o adaptors, akin to rt::tokio::TokioIo<I>.

see this small program demonstrating the motivation for this:

 #![allow(unreachable_code, unused_variables, dead_code)]

 use {
     hyper::rt::{Read, Write},
     hyper_util::rt::TokioIo,
     tokio::io::{AsyncRead, AsyncWrite},
     tokio::net::TcpStream,
 };

 fn is_tokio_io<I>(_: &I)
 where
     I: AsyncRead + AsyncWrite,
 {
 }

 fn is_hyper_io<I>(_: &I)
 where
     I: Read + Write,
 {
 }

 fn check_io_impls() {
     // `I: AsyncRead + AsyncWrite` does not implement hyper's `Read` and `Write`.
     let stream: TcpStream = todo!();
     is_tokio_io(&stream);
     // is_hyper_io(&stream); does not compile

     // `TokioIo<I: AsyncRead + AsyncWrite>` does not implement `tokio::io` traits.
     let stream: TokioIo<TcpStream> = TokioIo::new(stream);
     // is_tokio_io(&stream); does not compile
     is_hyper_io(&stream);

     // `TokioIo<TokioIo<I: AsyncRead + AsyncWrite>>` does not implement hyper's `Read` and `Write`.
     let stream: TokioIo<TokioIo<TcpStream>> = TokioIo::new(stream);
     is_tokio_io(&stream);
     // is_hyper_io(&stream); does not compile
 }

 fn main() {}

TokioIo<I> is not an adaptor that is additive with respect to its inner i/o transport. if it implements hyper's i/o, the wrapped type will implement tokio's at the expense of hyper's, and vice versa.

this is often fine for simple programs, but this "switching" approach can interfere with larger applications' ability to make use of middleware that is generic across different kinds of i/o streams.

this commit introduces types that allow a caller to add Read or Write implementations to tokio readers and writers, or inversely, AsyncRead and AsyncWrite implementations to hyper readers and writers.

[seanmonstar]

I appreciate the need for the types. My only concern is about confusing users which one they need... Perhaps at the top of the Tokio module here, we can add a section about IO, and bullet points about why you would want each one. What do you think?

[cratelyn]

I appreciate the need for the types. My only concern is about confusing users which one they need... Perhaps at the top of the Tokio module here, we can add a section about IO, and bullet points about why you would want each one. What do you think?

that sounds sensible to me! i'll add some documentation comparing and contrasting these types later today.

[cratelyn]

pardon the delay, i've written some documentation for hyper::rt::tokio. included in these docs are a table outlining what IO traits are implemented by which types, given transport from either hyper or tokio. some advice is included outlining that TokioIo<I> is generally the correct tool for most use-cases, along with links to tokio::io's upstream documentation.

nb: this is currently based upon #174, to address a CI error at the time of writing.

[cratelyn]

this is no longer based upon #174. at time of writing, CI errors related to the MSRV are to be expected.