libp2p-ping improvements. (#1049)

* libp2p-ping improvements.

  * re #950: Removes use of the `OneShotHandler`, but still sending each
    ping over a new substream, as seems to be intentional since #828.

  * re #842: Adds an integration test that exercises the ping behaviour through
    a Swarm, requiring the RTT to be below a threshold. This requires disabling
    Nagle's algorithm as it can interact badly with delayed ACKs (and has been
    observed to do so in the context of the new ping example and integration test).

  * re #864: Control of the inbound and outbound (sub)stream protocol upgrade
    timeouts has been moved from the `NodeHandlerWrapperBuilder` to the
    `ProtocolsHandler`. That may also alleviate the need for a custom timeout
    on an `OutboundSubstreamRequest` as a `ProtocolsHandler` is now free to
    adjust these timeouts over time.

Other changes:

  * A new ping example.
  * Documentation improvements.

* More documentation improvements.

* Add PingPolicy and ensure no event is dropped.

* Remove inbound_timeout/outbound_timeout.

As per review comment, the inbound timeout is now configured
as part of the `listen_protocol` and the outbound timeout as
part of the `OutboundSubstreamRequest`.

* Simplify and generalise.

Generalise `ListenProtocol` to `SubstreamProtocol`, reusing it in
the context of `ProtocolsHandlerEvent::OutboundSubstreamRequest`.

* Doc comments for SubstreamProtocol.

* Adapt to changes in master.

* Relax upper bound for ping integration test rtt.

For "slow" CI build machines?

examples/ping.rs

@@ -0,0 +1,91 @@
+// Copyright 2018 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.
+
+//! A basic example demonstrating some core APIs and concepts of libp2p.
+//!
+//! In the first terminal window, run:
+//!
+//! ```sh
+//! cargo run --example ping
+//! ```
+//!
+//! It will print the PeerId and the listening address, e.g. `Listening on
+//! "/ip4/0.0.0.0/tcp/24915"`
+//!
+//! In the second terminal window, start a new instance of the example with:
+//!
+//! ```sh
+//! cargo run --example ping -- /ip4/127.0.0.1/tcp/24915
+//! ```
+//!
+//! The two nodes establish a connection, negotiate the ping protocol
+//! and begin pinging each other.
+
+use futures::{prelude::*, future};
+use libp2p::{ identity, PeerId, ping::Ping, Swarm };
+use std::env;
+
+fn main() {
+    env_logger::init();
+
+    // Create a random PeerId.
+    let id_keys = identity::Keypair::generate_ed25519();
+    let peer_id = PeerId::from(id_keys.public());
+    println!("Local peer id: {:?}", peer_id);
+
+    // Create a transport.
+    let transport = libp2p::build_development_transport(id_keys);
+
+    // Create a ping network behaviour.
+    let behaviour = Ping::default();
+
+    // Create a Swarm that establishes connections through the given transport
+    // and applies the ping behaviour on each connection.
+    let mut swarm = Swarm::new(transport, behaviour, peer_id);
+
+    // Listen on all interfaces and a random, OS-assigned port.
+    let listen_addr = Swarm::listen_on(&mut swarm, "/ip4/0.0.0.0/tcp/0".parse().unwrap()).unwrap();
+    println!("Listening on {:?}", listen_addr);
+
+    // Dial the peer identified by the multi-address given as the second
+    // command-line argument, if any.
+    if let Some(addr) = env::args().nth(1) {
+        let remote_addr = addr.clone();
+        match addr.parse() {
+            Ok(remote) => {
+                match Swarm::dial_addr(&mut swarm, remote) {
+                    Ok(()) => println!("Dialed {:?}", remote_addr),
+                    Err(e) => println!("Dialing {:?} failed with: {:?}", remote_addr, e)
+                }
+            },
+            Err(err) => println!("Failed to parse address to dial: {:?}", err),
+        }
+    }
+
+    // Use tokio to drive the `Swarm`.
+    tokio::run(future::poll_fn(move || -> Result<_, ()> {
+        loop {
+            match swarm.poll().expect("Error while polling swarm") {
+                Async::Ready(Some(e)) => println!("{:?}", e),
+                Async::Ready(None) | Async::NotReady => return Ok(Async::NotReady),
+            }
+        }
+    }));
+}