examples: improve echo example consistency (#7256)

examples/Cargo.toml

@@ -33,17 +33,21 @@ name = "chat"
 path = "chat.rs"
 
 [[example]]
-name = "connect"
-path = "connect.rs"
+name = "connect-tcp"
+path = "connect-tcp.rs"
+
+[[example]]
+name = "connect-udp"
+path = "connect-udp.rs"
+
+[[example]]
+name = "echo-tcp"
+path = "echo-tcp.rs"
 
 [[example]]
 name = "echo-udp"
 path = "echo-udp.rs"
 
-[[example]]
-name = "echo"
-path = "echo.rs"
-
 [[example]]
 name = "hello_world"
 path = "hello_world.rs"

examples/README.md

@@ -10,7 +10,7 @@ cargo run --example $name
 ```
 
 A good starting point for the examples would be [`hello_world`](hello_world.rs)
-and [`echo`](echo.rs). Additionally [the tokio website][tokioweb] contains
+and [`echo-tcp`](echo-tcp.rs). Additionally [the tokio website][tokioweb] contains
 additional guides for some of the examples.
 
 For a larger "real world" example, see the [`mini-redis`][redis] repository.

examples/connect-tcp.rs

@@ -0,0 +1,71 @@
+//! An example of hooking up stdin/stdout to a TCP stream.
+//!
+//! This example will connect to a socket address specified in the argument list
+//! and then forward all data read on stdin to the server, printing out all data
+//! received on stdout. Each line entered on stdin will be translated to a TCP
+//! packet which is then sent to the remote address.
+//!
+//! Note that this is not currently optimized for performance, especially
+//! around buffer management. Rather it's intended to show an example of
+//! working with a client.
+//!
+//! This example can be quite useful when interacting with the other examples in
+//! this repository! Many of them recommend running this as a simple "hook up
+//! stdin/stdout to a server" to get up and running.
+
+#![warn(rust_2018_idioms)]
+
+use tokio::io::{stdin, stdout};
+use tokio::net::TcpStream;
+use tokio_util::codec::{BytesCodec, FramedRead, FramedWrite};
+
+use bytes::Bytes;
+use futures::{future, Sink, SinkExt, Stream, StreamExt};
+use std::env;
+use std::error::Error;
+use std::net::SocketAddr;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    // Parse what address we're going to connect to
+    let args = env::args().skip(1).collect::<Vec<_>>();
+    let addr = args
+        .first()
+        .ok_or("this program requires at least one argument")?;
+    let addr = addr.parse::<SocketAddr>()?;
+
+    let stdin = FramedRead::new(stdin(), BytesCodec::new());
+    let stdin = stdin.map(|i| i.map(|bytes| bytes.freeze()));
+    let stdout = FramedWrite::new(stdout(), BytesCodec::new());
+
+    connect(&addr, stdin, stdout).await?;
+
+    Ok(())
+}
+
+pub async fn connect(
+    addr: &SocketAddr,
+    mut stdin: impl Stream<Item = Result<Bytes, std::io::Error>> + Unpin,
+    mut stdout: impl Sink<Bytes, Error = std::io::Error> + Unpin,
+) -> Result<(), Box<dyn Error>> {
+    let mut stream = TcpStream::connect(addr).await?;
+    let (r, w) = stream.split();
+    let mut sink = FramedWrite::new(w, BytesCodec::new());
+    // filter map Result<BytesMut, Error> stream into just a Bytes stream to match stdout Sink
+    // on the event of an Error, log the error and end the stream
+    let mut stream = FramedRead::new(r, BytesCodec::new())
+        .filter_map(|i| match i {
+            //BytesMut into Bytes
+            Ok(i) => future::ready(Some(i.freeze())),
+            Err(e) => {
+                println!("failed to read from socket; error={e}");
+                future::ready(None)
+            }
+        })
+        .map(Ok);
+
+    match future::join(sink.send_all(&mut stdin), stdout.send_all(&mut stream)).await {
+        (Err(e), _) | (_, Err(e)) => Err(e.into()),
+        _ => Ok(()),
+    }
+}

examples/connect-udp.rs

@@ -0,0 +1,91 @@
+//! An example of hooking up stdin/stdout to a UDP stream.
+//!
+//! This example will connect to a socket address specified in the argument list
+//! and then forward all data read on stdin to the server, printing out all data
+//! received on stdout. Each line entered on stdin will be translated to a UDP
+//! packet which is then sent to the remote address.
+//!
+//! Note that this is not currently optimized for performance, especially
+//! around buffer management. Rather it's intended to show an example of
+//! working with a client.
+//!
+//! This example can be quite useful when interacting with the other examples in
+//! this repository! Many of them recommend running this as a simple "hook up
+//! stdin/stdout to a server" to get up and running.
+
+#![warn(rust_2018_idioms)]
+
+use tokio::io::{stdin, stdout};
+use tokio::net::UdpSocket;
+use tokio_util::codec::{BytesCodec, FramedRead, FramedWrite};
+
+use bytes::Bytes;
+use futures::{Sink, SinkExt, Stream, StreamExt};
+use std::env;
+use std::error::Error;
+use std::net::SocketAddr;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    // Parse what address we're going to connect to
+    let args = env::args().skip(1).collect::<Vec<_>>();
+    let addr = args
+        .first()
+        .ok_or("this program requires at least one argument")?;
+    let addr = addr.parse::<SocketAddr>()?;
+
+    let stdin = FramedRead::new(stdin(), BytesCodec::new());
+    let stdin = stdin.map(|i| i.map(|bytes| bytes.freeze()));
+    let stdout = FramedWrite::new(stdout(), BytesCodec::new());
+
+    connect(&addr, stdin, stdout).await?;
+
+    Ok(())
+}
+
+pub async fn connect(
+    addr: &SocketAddr,
+    stdin: impl Stream<Item = Result<Bytes, std::io::Error>> + Unpin,
+    stdout: impl Sink<Bytes, Error = std::io::Error> + Unpin,
+) -> Result<(), Box<dyn Error>> {
+    // We'll bind our UDP socket to a local IP/port, but for now we
+    // basically let the OS pick both of those.
+    let bind_addr = if addr.ip().is_ipv4() {
+        "0.0.0.0:0"
+    } else {
+        "[::]:0"
+    };
+
+    let socket = UdpSocket::bind(&bind_addr).await?;
+    socket.connect(addr).await?;
+
+    tokio::try_join!(send(stdin, &socket), recv(stdout, &socket))?;
+
+    Ok(())
+}
+
+async fn send(
+    mut stdin: impl Stream<Item = Result<Bytes, std::io::Error>> + Unpin,
+    writer: &UdpSocket,
+) -> Result<(), std::io::Error> {
+    while let Some(item) = stdin.next().await {
+        let buf = item?;
+        writer.send(&buf[..]).await?;
+    }
+
+    Ok(())
+}
+
+async fn recv(
+    mut stdout: impl Sink<Bytes, Error = std::io::Error> + Unpin,
+    reader: &UdpSocket,
+) -> Result<(), std::io::Error> {
+    loop {
+        let mut buf = vec![0; 1024];
+        let n = reader.recv(&mut buf[..]).await?;
+
+        if n > 0 {
+            stdout.send(Bytes::from(buf)).await?;
+        }
+    }
+}

examples/connect.rs

@@ -1,147 +0,0 @@
-//! An example of hooking up stdin/stdout to either a TCP or UDP stream.
-//!
-//! This example will connect to a socket address specified in the argument list
-//! and then forward all data read on stdin to the server, printing out all data
-//! received on stdout. An optional `--udp` argument can be passed to specify
-//! that the connection should be made over UDP instead of TCP, translating each
-//! line entered on stdin to a UDP packet to be sent to the remote address.
-//!
-//! Note that this is not currently optimized for performance, especially
-//! around buffer management. Rather it's intended to show an example of
-//! working with a client.
-//!
-//! This example can be quite useful when interacting with the other examples in
-//! this repository! Many of them recommend running this as a simple "hook up
-//! stdin/stdout to a server" to get up and running.
-
-#![warn(rust_2018_idioms)]
-
-use futures::StreamExt;
-use tokio::io;
-use tokio_util::codec::{BytesCodec, FramedRead, FramedWrite};
-
-use std::env;
-use std::error::Error;
-use std::net::SocketAddr;
-
-#[tokio::main]
-async fn main() -> Result<(), Box<dyn Error>> {
-    // Determine if we're going to run in TCP or UDP mode
-    let mut args = env::args().skip(1).collect::<Vec<_>>();
-    let tcp = match args.iter().position(|a| a == "--udp") {
-        Some(i) => {
-            args.remove(i);
-            false
-        }
-        None => true,
-    };
-
-    // Parse what address we're going to connect to
-    let addr = args
-        .first()
-        .ok_or("this program requires at least one argument")?;
-    let addr = addr.parse::<SocketAddr>()?;
-
-    let stdin = FramedRead::new(io::stdin(), BytesCodec::new());
-    let stdin = stdin.map(|i| i.map(|bytes| bytes.freeze()));
-    let stdout = FramedWrite::new(io::stdout(), BytesCodec::new());
-
-    if tcp {
-        tcp::connect(&addr, stdin, stdout).await?;
-    } else {
-        udp::connect(&addr, stdin, stdout).await?;
-    }
-
-    Ok(())
-}
-
-mod tcp {
-    use bytes::Bytes;
-    use futures::{future, Sink, SinkExt, Stream, StreamExt};
-    use std::{error::Error, io, net::SocketAddr};
-    use tokio::net::TcpStream;
-    use tokio_util::codec::{BytesCodec, FramedRead, FramedWrite};
-
-    pub async fn connect(
-        addr: &SocketAddr,
-        mut stdin: impl Stream<Item = Result<Bytes, io::Error>> + Unpin,
-        mut stdout: impl Sink<Bytes, Error = io::Error> + Unpin,
-    ) -> Result<(), Box<dyn Error>> {
-        let mut stream = TcpStream::connect(addr).await?;
-        let (r, w) = stream.split();
-        let mut sink = FramedWrite::new(w, BytesCodec::new());
-        // filter map Result<BytesMut, Error> stream into just a Bytes stream to match stdout Sink
-        // on the event of an Error, log the error and end the stream
-        let mut stream = FramedRead::new(r, BytesCodec::new())
-            .filter_map(|i| match i {
-                //BytesMut into Bytes
-                Ok(i) => future::ready(Some(i.freeze())),
-                Err(e) => {
-                    println!("failed to read from socket; error={e}");
-                    future::ready(None)
-                }
-            })
-            .map(Ok);
-
-        match future::join(sink.send_all(&mut stdin), stdout.send_all(&mut stream)).await {
-            (Err(e), _) | (_, Err(e)) => Err(e.into()),
-            _ => Ok(()),
-        }
-    }
-}
-
-mod udp {
-    use bytes::Bytes;
-    use futures::{Sink, SinkExt, Stream, StreamExt};
-    use std::error::Error;
-    use std::io;
-    use std::net::SocketAddr;
-    use tokio::net::UdpSocket;
-
-    pub async fn connect(
-        addr: &SocketAddr,
-        stdin: impl Stream<Item = Result<Bytes, io::Error>> + Unpin,
-        stdout: impl Sink<Bytes, Error = io::Error> + Unpin,
-    ) -> Result<(), Box<dyn Error>> {
-        // We'll bind our UDP socket to a local IP/port, but for now we
-        // basically let the OS pick both of those.
-        let bind_addr = if addr.ip().is_ipv4() {
-            "0.0.0.0:0"
-        } else {
-            "[::]:0"
-        };
-
-        let socket = UdpSocket::bind(&bind_addr).await?;
-        socket.connect(addr).await?;
-
-        tokio::try_join!(send(stdin, &socket), recv(stdout, &socket))?;
-
-        Ok(())
-    }
-
-    async fn send(
-        mut stdin: impl Stream<Item = Result<Bytes, io::Error>> + Unpin,
-        writer: &UdpSocket,
-    ) -> Result<(), io::Error> {
-        while let Some(item) = stdin.next().await {
-            let buf = item?;
-            writer.send(&buf[..]).await?;
-        }
-
-        Ok(())
-    }
-
-    async fn recv(
-        mut stdout: impl Sink<Bytes, Error = io::Error> + Unpin,
-        reader: &UdpSocket,
-    ) -> Result<(), io::Error> {
-        loop {
-            let mut buf = vec![0; 1024];
-            let n = reader.recv(&mut buf[..]).await?;
-
-            if n > 0 {
-                stdout.send(Bytes::from(buf)).await?;
-            }
-        }
-    }
-}

examples/echo-tcp.rs

@@ -9,13 +9,13 @@
 //!
 //! To see this server in action, you can run this in one terminal:
 //!
-//!     cargo run --example echo
+//!     cargo run --example echo-tcp
 //!
 //! and in another terminal you can run:
 //!
-//!     cargo run --example connect 127.0.0.1:8080
+//!     cargo run --example connect-tcp 127.0.0.1:8080
 //!
-//! Each line you type in to the `connect` terminal should be echo'd back to
+//! Each line you type in to the `connect-tcp` terminal should be echo'd back to
 //! you! If you open up multiple terminals running the `connect` example you
 //! should be able to see them all make progress simultaneously.
 

examples/echo-udp.rs

@@ -6,9 +6,9 @@
 //!
 //! and in another terminal you can run:
 //!
-//!     cargo run --example connect -- --udp 127.0.0.1:8080
+//!     cargo run --example connect-udp 127.0.0.1:8080
 //!
-//! Each line you type in to the `nc` terminal should be echo'd back to you!
+//! Each line you type in to the `connect-udp` terminal should be echo'd back to you!
 
 #![warn(rust_2018_idioms)]
 

examples/print_each_packet.rs

@@ -13,9 +13,9 @@
 //!
 //! and in another terminal you can run:
 //!
-//!     cargo run --example connect 127.0.0.1:8080
+//!     cargo run --example connect-tcp 127.0.0.1:8080
 //!
-//! Each line you type in to the `connect` terminal should be written to terminal!
+//! Each line you type in to the `connect-tcp` terminal should be written to terminal!
 //!
 //! Minimal js example:
 //!

examples/proxy.rs

@@ -11,11 +11,11 @@
 //!
 //! This in another terminal
 //!
-//!     cargo run --example echo
+//!     cargo run --example echo-tcp
 //!
 //! And finally this in another terminal
 //!
-//!     cargo run --example connect 127.0.0.1:8081
+//!     cargo run --example connect-tcp 127.0.0.1:8081
 //!
 //! This final terminal will connect to our proxy, which will in turn connect to
 //! the echo server, and you'll be able to see data flowing between them.

examples/tinydb.rs

@@ -12,9 +12,9 @@
 //!
 //! and next in another windows run:
 //!
-//!     cargo run --example connect 127.0.0.1:8080
+//!     cargo run --example connect-tcp 127.0.0.1:8080
 //!
-//! In the `connect` window you can type in commands where when you hit enter
+//! In the `connect-tcp` window you can type in commands where when you hit enter
 //! you'll get a response from the server for that command. An example session
 //! is:
 //!