[tcp] Port-reuse, async-io, if-watch (#1887)

* Update tomls.

* Let transports decide when to translate.

* Improve tcp transport.

* Update stuff.

* Remove background task. Enhance documentation.

To avoid spawning a background task and thread within
`TcpConfig::new()`, with communication via unbounded channels,
a `TcpConfig` now keeps track of the listening addresses
for port reuse in an `Arc<RwLock>`. Furthermore, an `IfWatcher`
is only used by a `TcpListenStream` if it listens on any interface
and directly polls the `IfWatcher` both for initialisation and
new events.

Includes some documentation and test enhancements.

* Reintroduce feature flags for tokio vs async-io.

To avoid having an extra reactor thread running for tokio
users and to make sure all TCP I/O uses the mio-based
tokio reactor.

Thereby run tests with both backends.

* Add missing files.

* Fix docsrs attributes.

* Update transports/tcp/src/lib.rs

Co-authored-by: Max Inden <mail@max-inden.de>

* Restore chat-tokio example.

* Forward poll_write_vectored for tokio's AsyncWrite.

* Update changelogs.

Co-authored-by: David Craven <david@craven.ch>
Co-authored-by: Max Inden <mail@max-inden.de>

transports/tcp/src/provider.rs

@@ -0,0 +1,81 @@
+// Copyright 2020 Parity Technologies (UK) Ltd.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the "Software"),
+// to deal in the Software without restriction, including without limitation
+// the rights to use, copy, modify, merge, publish, distribute, sublicense,
+// and/or sell copies of the Software, and to permit persons to whom the
+// Software is furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+
+//! The interface for providers of non-blocking TCP implementations.
+
+#[cfg(feature = "async-io")]
+pub mod async_io;
+
+#[cfg(feature = "tokio")]
+pub mod tokio;
+
+use futures::io::{AsyncRead, AsyncWrite};
+use futures::future::BoxFuture;
+use ipnet::IpNet;
+use std::task::{Context, Poll};
+use std::{fmt, io};
+use std::net::{SocketAddr, TcpListener, TcpStream};
+
+/// An event relating to a change of availability of an address
+/// on a network interface.
+pub enum IfEvent {
+    Up(IpNet),
+    Down(IpNet),
+}
+
+/// An incoming connection returned from [`Provider::poll_accept()`].
+pub struct Incoming<S> {
+    pub stream: S,
+    pub local_addr: SocketAddr,
+    pub remote_addr: SocketAddr,
+}
+
+/// The interface for non-blocking TCP I/O providers.
+pub trait Provider: Clone + Send + 'static {
+    /// The type of TCP streams obtained from [`Provider::new_stream`]
+    /// and [`Provider::poll_accept`].
+    type Stream: AsyncRead + AsyncWrite + Send + Unpin + fmt::Debug;
+    /// The type of TCP listeners obtained from [`Provider::new_listener`].
+    type Listener: Send + Unpin;
+    /// The type of network interface observers obtained from [`Provider::if_watcher`].
+    type IfWatcher: Send + Unpin;
+
+    /// Creates an instance of [`Self::IfWatcher`] that can be polled for
+    /// network interface changes via [`Self::poll_interfaces`].
+    fn if_watcher() -> BoxFuture<'static, io::Result<Self::IfWatcher>>;
+
+    /// Creates a new listener wrapping the given [`TcpListener`] that
+    /// can be polled for incoming connections via [`Self::poll_accept()`].
+    fn new_listener(_: TcpListener) -> io::Result<Self::Listener>;
+
+    /// Creates a new stream for an outgoing connection, wrapping the
+    /// given [`TcpStream`]. The given `TcpStream` is initiating a
+    /// connection, but implementations must wait for the connection
+    /// setup to complete, i.e. for the stream to be writable.
+    fn new_stream(_: TcpStream) -> BoxFuture<'static, io::Result<Self::Stream>>;
+
+    /// Polls a [`Self::Listener`] for an incoming connection, ensuring a task wakeup,
+    /// if necessary.
+    fn poll_accept(_: &mut Self::Listener, _: &mut Context<'_>) -> Poll<io::Result<Incoming<Self::Stream>>>;
+
+    /// Polls a [`Self::IfWatcher`] for network interface changes, ensuring a task wakeup,
+    /// if necessary.
+    fn poll_interfaces(_: &mut Self::IfWatcher, _: &mut Context<'_>) -> Poll<io::Result<IfEvent>>;
+}

transports/tcp/src/provider/async_io.rs

@@ -0,0 +1,83 @@
+// Copyright 2020 Parity Technologies (UK) Ltd.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the "Software"),
+// to deal in the Software without restriction, including without limitation
+// the rights to use, copy, modify, merge, publish, distribute, sublicense,
+// and/or sell copies of the Software, and to permit persons to whom the
+// Software is furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+
+use super::{Provider, IfEvent, Incoming};
+
+use async_io_crate::Async;
+use futures::{
+    future::{BoxFuture, FutureExt},
+    prelude::*,
+};
+use std::io;
+use std::task::{Poll, Context};
+use std::net;
+
+#[derive(Copy, Clone)]
+pub enum Tcp {}
+
+impl Provider for Tcp {
+    type Stream = Async<net::TcpStream>;
+    type Listener = Async<net::TcpListener>;
+    type IfWatcher = if_watch::IfWatcher;
+
+    fn if_watcher() -> BoxFuture<'static, io::Result<Self::IfWatcher>> {
+        if_watch::IfWatcher::new().boxed()
+    }
+
+    fn new_listener(l: net::TcpListener) -> io::Result<Self::Listener> {
+        Async::new(l)
+    }
+
+    fn new_stream(s: net::TcpStream) -> BoxFuture<'static, io::Result<Self::Stream>> {
+        async move {
+            let stream = Async::new(s)?;
+            stream.writable().await?;
+            Ok(stream)
+        }.boxed()
+    }
+
+    fn poll_accept(l: &mut Self::Listener, cx: &mut Context<'_>) -> Poll<io::Result<Incoming<Self::Stream>>> {
+        let (stream, remote_addr) = loop {
+            match l.poll_readable(cx) {
+                Poll::Pending => return Poll::Pending,
+                Poll::Ready(Err(err)) => return Poll::Ready(Err(err)),
+                Poll::Ready(Ok(())) => match l.accept().now_or_never() {
+                    Some(Err(e)) => return Poll::Ready(Err(e)),
+                    Some(Ok(res)) => break res,
+                    None => {
+                        // Since it doesn't do any harm, account for false positives of
+                        // `poll_readable` just in case, i.e. try again.
+                    }
+                }
+            }
+        };
+
+        let local_addr = stream.get_ref().local_addr()?;
+
+        Poll::Ready(Ok(Incoming { stream, local_addr, remote_addr }))
+    }
+
+    fn poll_interfaces(w: &mut Self::IfWatcher, cx: &mut Context<'_>) -> Poll<io::Result<IfEvent>> {
+        w.next().map_ok(|e| match e {
+            if_watch::IfEvent::Up(a) => IfEvent::Up(a),
+            if_watch::IfEvent::Down(a) => IfEvent::Down(a),
+        }).boxed().poll_unpin(cx)
+    }
+}

transports/tcp/src/provider/tokio.rs

@@ -0,0 +1,168 @@
+// Copyright 2020 Parity Technologies (UK) Ltd.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the "Software"),
+// to deal in the Software without restriction, including without limitation
+// the rights to use, copy, modify, merge, publish, distribute, sublicense,
+// and/or sell copies of the Software, and to permit persons to whom the
+// Software is furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+
+use super::{Provider, IfEvent, Incoming};
+
+use futures::{
+    future::{self, BoxFuture, FutureExt},
+    prelude::*,
+};
+use futures_timer::Delay;
+use if_addrs::{IfAddr, get_if_addrs};
+use ipnet::{IpNet, Ipv4Net, Ipv6Net};
+use std::collections::HashSet;
+use std::convert::TryFrom;
+use std::io;
+use std::task::{Poll, Context};
+use std::time::Duration;
+use std::net;
+use std::pin::Pin;
+
+#[derive(Copy, Clone)]
+pub enum Tcp {}
+
+pub struct IfWatcher {
+    addrs: HashSet<IpNet>,
+    delay: Delay,
+    pending: Vec<IfEvent>,
+}
+
+impl Provider for Tcp {
+    type Stream = TcpStream;
+    type Listener = tokio_crate::net::TcpListener;
+    type IfWatcher = IfWatcher;
+
+    fn if_watcher() -> BoxFuture<'static, io::Result<Self::IfWatcher>> {
+        future::ready(Ok(
+            IfWatcher {
+                addrs: HashSet::new(),
+                delay: Delay::new(Duration::from_secs(0)),
+                pending: Vec::new(),
+            }
+        )).boxed()
+    }
+
+    fn new_listener(l: net::TcpListener) -> io::Result<Self::Listener> {
+        tokio_crate::net::TcpListener::try_from(l)
+    }
+
+    fn new_stream(s: net::TcpStream) -> BoxFuture<'static, io::Result<Self::Stream>> {
+        async move {
+            let stream = tokio_crate::net::TcpStream::try_from(s)?;
+            stream.writable().await?;
+            Ok(TcpStream(stream))
+        }.boxed()
+    }
+
+    fn poll_accept(l: &mut Self::Listener, cx: &mut Context<'_>)
+        -> Poll<io::Result<Incoming<Self::Stream>>>
+    {
+        let (stream, remote_addr) = match l.poll_accept(cx) {
+            Poll::Pending => return Poll::Pending,
+            Poll::Ready(Err(e)) => return Poll::Ready(Err(e)),
+            Poll::Ready(Ok((stream, remote_addr))) => (stream, remote_addr)
+        };
+
+        let local_addr = stream.local_addr()?;
+        let stream = TcpStream(stream);
+
+        Poll::Ready(Ok(Incoming { stream, local_addr, remote_addr }))
+    }
+
+    fn poll_interfaces(w: &mut Self::IfWatcher, cx: &mut Context<'_>) -> Poll<io::Result<IfEvent>> {
+        loop {
+            if let Some(event) = w.pending.pop() {
+                return Poll::Ready(Ok(event))
+            }
+
+            match Pin::new(&mut w.delay).poll(cx) {
+                Poll::Pending => return Poll::Pending,
+                Poll::Ready(()) => {
+                    let ifs = get_if_addrs()?;
+                    let addrs = ifs.into_iter().map(|iface| match iface.addr {
+                        IfAddr::V4(ip4) => {
+                            let prefix_len = (!u32::from_be_bytes(ip4.netmask.octets())).leading_zeros();
+                            let ipnet = Ipv4Net::new(ip4.ip, prefix_len as u8)
+                                .expect("prefix_len can not exceed 32");
+                            IpNet::V4(ipnet)
+                        }
+                        IfAddr::V6(ip6) => {
+                            let prefix_len = (!u128::from_be_bytes(ip6.netmask.octets())).leading_zeros();
+                            let ipnet = Ipv6Net::new(ip6.ip, prefix_len as u8)
+                                .expect("prefix_len can not exceed 128");
+                            IpNet::V6(ipnet)
+                        }
+                    }).collect::<HashSet<_>>();
+
+                    for down in w.addrs.difference(&addrs) {
+                        w.pending.push(IfEvent::Down(*down));
+                    }
+
+                    for up in addrs.difference(&w.addrs) {
+                        w.pending.push(IfEvent::Up(*up));
+                    }
+
+                    w.addrs = addrs;
+                    w.delay.reset(Duration::from_secs(10));
+                }
+            }
+        }
+    }
+}
+
+/// A [`tokio_crate::net::TcpStream`] that implements [`AsyncRead`] and [`AsyncWrite`].
+#[derive(Debug)]
+pub struct TcpStream(pub tokio_crate::net::TcpStream);
+
+impl Into<tokio_crate::net::TcpStream> for TcpStream {
+    fn into(self: TcpStream) -> tokio_crate::net::TcpStream {
+        self.0
+    }
+}
+
+impl AsyncRead for TcpStream {
+    fn poll_read(mut self: Pin<&mut Self>, cx: &mut Context, buf: &mut [u8]) -> Poll<Result<usize, io::Error>> {
+        let mut read_buf = tokio_crate::io::ReadBuf::new(buf);
+        futures::ready!(tokio_crate::io::AsyncRead::poll_read(Pin::new(&mut self.0), cx, &mut read_buf))?;
+        Poll::Ready(Ok(read_buf.filled().len()))
+    }
+}
+
+impl AsyncWrite for TcpStream {
+    fn poll_write(mut self: Pin<&mut Self>, cx: &mut Context, buf: &[u8]) -> Poll<Result<usize, io::Error>> {
+        tokio_crate::io::AsyncWrite::poll_write(Pin::new(&mut self.0), cx, buf)
+    }
+
+    fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context) -> Poll<Result<(), io::Error>> {
+        tokio_crate::io::AsyncWrite::poll_flush(Pin::new(&mut self.0), cx)
+    }
+
+    fn poll_close(mut self: Pin<&mut Self>, cx: &mut Context) -> Poll<Result<(), io::Error>> {
+        tokio_crate::io::AsyncWrite::poll_shutdown(Pin::new(&mut self.0), cx)
+    }
+
+    fn poll_write_vectored(
+        mut self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        bufs: &[io::IoSlice<'_>]
+    ) -> Poll<io::Result<usize>> {
+        tokio_crate::io::AsyncWrite::poll_write_vectored(Pin::new(&mut self.0), cx, bufs)
+    }
+}