examples: improve echo example consistency (#7256)

Author: nskins

examples/Cargo.toml

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

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

@@ -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.rs renamed to examples/echo-tcp.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/echo-udp.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:
 //!