Add an example that pings an IPFS node (#89)

example/Cargo.toml

@@ -9,6 +9,7 @@ futures = "0.1"
 multiaddr = { path = "../rust-multiaddr" }
 multiplex = { path = "../multiplex-rs" }
 libp2p-peerstore = { path = "../libp2p-peerstore" }
+libp2p-ping = { path = "../libp2p-ping" }
 libp2p-secio = { path = "../libp2p-secio" }
 libp2p-swarm = { path = "../libp2p-swarm" }
 libp2p-tcp-transport = { path = "../libp2p-tcp-transport" }

example/README.md

@@ -13,6 +13,8 @@ The follow examples exist:
 - `echo-server` will listen on `/ip4/0.0.0.0/tcp/10333`, negotiate the `/echo/1.0.0` protocol with
   each incoming connection, then send back any entering message. Compatible with the `echo-dialer`
   example.
+- `ping-client` will try to connect to `/ip4/127.0.0.1/tcp/4001`, which is the default address of
+  your local IPFS node if you're running one. It will then open a substream and ping the node.
 
 ## How the keys were generated
 

example/examples/ping-client.rs

@@ -0,0 +1,102 @@
+// Copyright 2017 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.
+
+extern crate bytes;
+extern crate futures;
+extern crate libp2p_ping as ping;
+extern crate libp2p_secio as secio;
+extern crate libp2p_swarm as swarm;
+extern crate libp2p_tcp_transport as tcp;
+extern crate multiplex;
+extern crate tokio_core;
+extern crate tokio_io;
+
+use futures::Future;
+use std::env;
+use swarm::{UpgradeExt, Transport, DeniedConnectionUpgrade};
+use tcp::TcpConfig;
+use tokio_core::reactor::Core;
+
+fn main() {
+    // Determine which address to dial.
+    let target_addr = env::args().nth(1).unwrap_or("/ip4/127.0.0.1/tcp/4001".to_owned());
+
+    // We start by building the tokio engine that will run all the sockets.
+    let mut core = Core::new().unwrap();
+
+    // Now let's build the transport stack.
+    // We start by creating a `TcpConfig` that indicates that we want TCP/IP.
+    let transport = TcpConfig::new(core.handle())
+
+        // On top of TCP/IP, we will use either the plaintext protocol or the secio protocol,
+        // depending on which one the remote supports.
+        .with_upgrade({
+            let plain_text = swarm::PlainTextConfig;
+
+            let secio = {
+                let private_key = include_bytes!("test-private-key.pk8");
+                let public_key = include_bytes!("test-public-key.der").to_vec();
+                secio::SecioConfig {
+                    key: secio::SecioKeyPair::rsa_from_pkcs8(private_key, public_key).unwrap(),
+                }
+            };
+
+            plain_text.or_upgrade(secio)
+        })
+
+        // On top of plaintext or secio, we will use the multiplex protocol.
+        .with_upgrade(multiplex::MultiplexConfig)
+        // The object returned by the call to `with_upgrade(MultiplexConfig)` can't be used as a
+        // `Transport` because the output of the upgrade is not a stream but a controller for
+        // muxing. We have to explicitly call `into_connection_reuse()` in order to turn this into
+        // a `Transport`.
+        .into_connection_reuse();
+
+    // Let's put this `transport` into a *swarm*. The swarm will handle all the incoming
+    // connections for us. The second parameter we pass is the connection upgrade that is accepted
+    // by the listening part. We don't want to accept anything, so we pass a dummy object that
+    // represents a connection that is always denied.
+    let (swarm_controller, swarm_future) = swarm::swarm(transport, DeniedConnectionUpgrade,
+        |_socket, _client_addr| -> Result<(), _> {
+            unreachable!("All incoming connections should have been denied")
+        });
+
+    // We now use the controller to dial to the address.
+    swarm_controller
+        .dial_custom_handler(target_addr.parse().expect("invalid multiaddr"), ping::Ping,
+            |(mut pinger, future)| {
+                let ping = pinger.ping().map_err(|_| unreachable!()).inspect(|_| {
+                    println!("Received pong from the remote");
+                });
+                ping.select(future).map(|_| ()).map_err(|(e, _)| e)
+            })
+        // If the multiaddr protocol exists but is not supported, then we get an error containing
+        // the original multiaddress.
+        .expect("unsupported multiaddr");
+
+    // The address we actually listen on can be different from the address that was passed to
+    // the `listen_on` function. For example if you pass `/ip4/0.0.0.0/tcp/0`, then the port `0`
+    // will be replaced with the actual port.
+
+    // `swarm_future` is a future that contains all the behaviour that we want, but nothing has
+    // actually started yet. Because we created the `TcpConfig` with tokio, we need to run the
+    // future through the tokio core.
+    core.run(swarm_future).unwrap();
+}