├── .gitignore ├── ci.sh ├── simple ├── Cargo.toml ├── examples │ ├── echo_client_server.rs │ ├── stream_client.rs │ ├── ping_pong.rs │ └── handshake.rs └── src │ └── lib.rs ├── streaming ├── Cargo.toml ├── examples │ └── stdout_server.rs └── src │ └── lib.rs ├── multiplexed ├── Cargo.toml ├── examples │ └── echo_client_server.rs └── src │ └── lib.rs ├── LICENSE-MIT ├── README.md └── LICENSE-APACHE /.gitignore: -------------------------------------------------------------------------------- 1 | target 2 | Cargo.lock 3 | -------------------------------------------------------------------------------- /ci.sh: -------------------------------------------------------------------------------- 1 | set -e 2 | 3 | pushd multiplexed 4 | cargo update 5 | cargo test 6 | popd 7 | 8 | pushd simple 9 | cargo update 10 | cargo test 11 | popd 12 | 13 | pushd streaming 14 | cargo update 15 | cargo test 16 | popd 17 | -------------------------------------------------------------------------------- /simple/Cargo.toml: -------------------------------------------------------------------------------- 1 | [package] 2 | name = "tokio-line" 3 | version = "0.1.0" 4 | authors = ["Carl Lerche "] 5 | 6 | [dependencies] 7 | futures = "0.1" 8 | tokio-io = "0.1" 9 | tokio-core = "0.1" 10 | tokio-proto = "0.1" 11 | tokio-service = "0.1" 12 | bytes = "0.4" 13 | 14 | [dev-dependencies] 15 | service-fn = { git = "https://github.com/tokio-rs/service-fn" } 16 | -------------------------------------------------------------------------------- /streaming/Cargo.toml: -------------------------------------------------------------------------------- 1 | [package] 2 | name = "tokio-line-streaming" 3 | version = "0.1.0" 4 | authors = ["Carl Lerche "] 5 | 6 | [dependencies] 7 | futures = "0.1" 8 | tokio-io = "0.1" 9 | tokio-core = "0.1" 10 | tokio-proto = "0.1" 11 | tokio-service = "0.1" 12 | bytes = "0.4" 13 | 14 | [dev-dependencies] 15 | service-fn = { git = "https://github.com/tokio-rs/service-fn" } 16 | -------------------------------------------------------------------------------- /multiplexed/Cargo.toml: -------------------------------------------------------------------------------- 1 | [package] 2 | name = "tokio-line-multiplexed" 3 | version = "0.1.0" 4 | authors = ["Carl Lerche "] 5 | 6 | [dependencies] 7 | log = "0.3.6" 8 | futures = "0.1" 9 | tokio-io = "0.1" 10 | tokio-core = "0.1" 11 | tokio-proto = "0.1" 12 | tokio-service = "0.1" 13 | bytes = "0.4" 14 | 15 | [dev-dependencies] 16 | service-fn = { git = "https://github.com/tokio-rs/service-fn" } 17 | -------------------------------------------------------------------------------- /LICENSE-MIT: -------------------------------------------------------------------------------- 1 | Copyright (c) 2017 Tokio contributors 2 | 3 | Permission is hereby granted, free of charge, to any 4 | person obtaining a copy of this software and associated 5 | documentation files (the "Software"), to deal in the 6 | Software without restriction, including without 7 | limitation the rights to use, copy, modify, merge, 8 | publish, distribute, sublicense, and/or sell copies of 9 | the Software, and to permit persons to whom the Software 10 | is furnished to do so, subject to the following 11 | conditions: 12 | 13 | The above copyright notice and this permission notice 14 | shall be included in all copies or substantial portions 15 | of the Software. 16 | 17 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF 18 | ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 19 | TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 20 | PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT 21 | SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 22 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 23 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR 24 | IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 25 | DEALINGS IN THE SOFTWARE. 26 | -------------------------------------------------------------------------------- /multiplexed/examples/echo_client_server.rs: -------------------------------------------------------------------------------- 1 | extern crate tokio_line_multiplexed as line; 2 | 3 | extern crate futures; 4 | extern crate tokio_core; 5 | extern crate tokio_service; 6 | extern crate service_fn; 7 | 8 | use futures::Future; 9 | use tokio_core::reactor::Core; 10 | use tokio_service::Service; 11 | use service_fn::service_fn; 12 | use std::thread; 13 | use std::time::Duration; 14 | 15 | pub fn main() { 16 | let mut core = Core::new().unwrap(); 17 | 18 | // This brings up our server. 19 | let addr = "127.0.0.1:12345".parse().unwrap(); 20 | 21 | thread::spawn(move || { 22 | line::serve( 23 | addr, 24 | || { 25 | Ok(service_fn(|msg| { 26 | println!("SERVER: {:?}", msg); 27 | Ok(msg) 28 | })) 29 | }); 30 | }); 31 | 32 | // A bit annoying, but we need to wait for the server to connect 33 | thread::sleep(Duration::from_millis(100)); 34 | 35 | let handle = core.handle(); 36 | 37 | core.run( 38 | line::Client::connect(&addr, &handle) 39 | .and_then(|client| { 40 | client.call("Hello".to_string()) 41 | .and_then(move |response| { 42 | println!("CLIENT: {:?}", response); 43 | client.call("Goodbye".to_string()) 44 | }) 45 | .and_then(|response| { 46 | println!("CLIENT: {:?}", response); 47 | Ok(()) 48 | }) 49 | }) 50 | ).unwrap(); 51 | } 52 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Tokio Line 2 | 3 | Examples of how to implement simple pipelined and multiplexed protocols using 4 | [tokio-proto](https://github.com/tokio-rs/tokio-proto). 5 | 6 | ## Getting Started 7 | 8 | Clone this repo, then `cd` into `simple`. Then, run the 9 | following command: 10 | 11 | ``` 12 | $ cargo run --example echo_client_server 13 | ``` 14 | 15 | You should see the following: 16 | 17 | ``` 18 | SERVER: "Hello" 19 | CLIENT: "Hello" 20 | SERVER: "Goodbye" 21 | CLIENT: "Goodbye" 22 | ``` 23 | 24 | ## More examples 25 | 26 | This repository includes a number of examples that demonstrate how to use 27 | [tokio-proto](https://github.com/tokio-rs/tokio-proto): 28 | 29 | * [simple](simple/src/lib.rs) implements a simple line-based protocol with an 30 | [example](simple/examples/echo_client_server.rs) of how to use it. 31 | * [multiplexed](multiplexed/src/lib.rs) implements a simple multiplexed 32 | protocol with an [example](multiplexed/examples/echo_client_server.rs) of how 33 | to use it. 34 | * [streaming](streaming/src/lib.rs) implements a line-based protocol that is 35 | able to stream requests and responses with an 36 | [example](streaming/examples/stdout_server.rs) of how to use it. 37 | * [handshake](simple/examples/handshake.rs) shows how to handle the handshake 38 | phase of a protocol, this may include SSL, authentication, etc... 39 | * [ping_pong](simple/examples/ping_pong.rs) shows how to implement protocol 40 | logic at the transport layer. 41 | * [stream_client](simple/examples/stream_client.rs) shows how to use a transport 42 | directly without using tokio-proto. This makes sense for protocols that aren't 43 | request / response oriented. 44 | 45 | ## License 46 | 47 | Tokio is primarily distributed under the terms of both the MIT license 48 | and the Apache License (Version 2.0), with portions covered by various 49 | BSD-like licenses. 50 | 51 | See LICENSE-APACHE, and LICENSE-MIT for details. 52 | -------------------------------------------------------------------------------- /simple/examples/echo_client_server.rs: -------------------------------------------------------------------------------- 1 | //! Using tokio-proto to get a request / response oriented client and server 2 | //! 3 | //! This example illustrates how to implement a client and server for a request 4 | //! / response oriented protocol. The protocol is a simple line-based string 5 | //! protocol. Each line represents a request or response. 6 | //! 7 | //! A transport is setup to handle framing the protocl to `String` messages. 8 | //! Then the transport is passed to `tokio-proto` which handles the details of 9 | //! managing the necessary state to implemnet `Service`. 10 | 11 | extern crate tokio_line as line; 12 | 13 | extern crate futures; 14 | extern crate tokio_core; 15 | extern crate tokio_service; 16 | extern crate service_fn; 17 | 18 | use futures::Future; 19 | use tokio_core::reactor::Core; 20 | use tokio_service::Service; 21 | use service_fn::service_fn; 22 | use std::thread; 23 | use std::time::Duration; 24 | 25 | pub fn main() { 26 | let mut core = Core::new().unwrap(); 27 | 28 | // This brings up our server. 29 | let addr = "127.0.0.1:12345".parse().unwrap(); 30 | 31 | thread::spawn(move || { 32 | line::serve( 33 | addr, 34 | || { 35 | Ok(service_fn(|msg| { 36 | println!("SERVER: {:?}", msg); 37 | Ok(msg) 38 | })) 39 | }); 40 | }); 41 | 42 | // A bit annoying, but we need to wait for the server to connect 43 | thread::sleep(Duration::from_millis(100)); 44 | 45 | let handle = core.handle(); 46 | 47 | core.run( 48 | line::Client::connect(&addr, &handle) 49 | .and_then(|client| { 50 | client.call("Hello".to_string()) 51 | .and_then(move |response| { 52 | println!("CLIENT: {:?}", response); 53 | client.call("Goodbye".to_string()) 54 | }) 55 | .and_then(|response| { 56 | println!("CLIENT: {:?}", response); 57 | Ok(()) 58 | }) 59 | }) 60 | ).unwrap(); 61 | } 62 | -------------------------------------------------------------------------------- /streaming/examples/stdout_server.rs: -------------------------------------------------------------------------------- 1 | //! Using tokio-proto to get a request / response oriented client and server 2 | //! 3 | //! This example illustrates how to implement a client and server for a request 4 | //! / response oriented protocol. The protocol is a simple line-based string 5 | //! protocol. Each line represents a request or response. 6 | //! 7 | //! A transport is setup to handle framing the protocl to `String` messages. 8 | //! Then the transport is passed to `tokio-proto` which handles the details of 9 | //! managing the necessary state to implemnet `Service`. 10 | 11 | extern crate tokio_line_streaming as line; 12 | 13 | extern crate futures; 14 | extern crate tokio_core; 15 | extern crate tokio_service; 16 | extern crate service_fn; 17 | 18 | use line::{Client, Line, LineStream}; 19 | 20 | use futures::{future, Future, Stream, Sink}; 21 | use tokio_core::reactor::Core; 22 | use tokio_service::Service; 23 | use service_fn::service_fn; 24 | 25 | use std::{io, thread}; 26 | use std::time::Duration; 27 | 28 | pub fn main() { 29 | let mut core = Core::new().unwrap(); 30 | 31 | // This brings up our server. 32 | let addr = "127.0.0.1:12345".parse().unwrap(); 33 | 34 | thread::spawn(move || { 35 | line::serve( 36 | addr, 37 | || { 38 | Ok(service_fn(|msg| { 39 | match msg { 40 | Line::Once(line) => { 41 | println!("{}", line); 42 | Box::new(future::done(Ok(Line::Once("Ok".to_string())))) 43 | } 44 | Line::Stream(body) => { 45 | let resp = body 46 | .for_each(|line| { 47 | println!(" + {}", line); 48 | Ok(()) 49 | }) 50 | .map(|_| Line::Once("Ok".to_string())); 51 | 52 | Box::new(resp) as Box> 53 | } 54 | } 55 | })) 56 | }); 57 | }); 58 | 59 | // A bit annoying, but we need to wait for the server to connect 60 | thread::sleep(Duration::from_millis(100)); 61 | 62 | let handle = core.handle(); 63 | 64 | core.run( 65 | Client::connect(&addr, &handle) 66 | .and_then(|client| { 67 | client.call(Line::Once("Hello".to_string())) 68 | .and_then(move |response| { 69 | println!("CLIENT: {:?}", response); 70 | 71 | // Now, spawn a thread that streams to the server 72 | 73 | let (mut tx, rx) = LineStream::pair(); 74 | 75 | thread::spawn(move || { 76 | for msg in &["one", "two", "three", "four"] { 77 | thread::sleep(Duration::from_millis(500)); 78 | tx = tx.send(Ok(msg.to_string())).wait().unwrap(); 79 | } 80 | }); 81 | 82 | client.call(Line::Stream(rx)) 83 | }) 84 | .and_then(|response| { 85 | println!("CLIENT: {:?}", response); 86 | Ok(()) 87 | }) 88 | }) 89 | ).unwrap(); 90 | } 91 | 92 | -------------------------------------------------------------------------------- /simple/examples/stream_client.rs: -------------------------------------------------------------------------------- 1 | //! Using a transport directly 2 | //! 3 | //! This example illustrates a use case where the protocol isn't request / 4 | //! response oriented. In this case, the connection is established, and "log" 5 | //! entries are streamed to the remote. 6 | //! 7 | //! Given that the use case is not request / response oriented, it doesn't make 8 | //! sense to use `tokio-proto`. Instead, we use the transport directly. 9 | 10 | extern crate tokio_line; 11 | 12 | extern crate futures; 13 | extern crate tokio_io; 14 | extern crate tokio_core; 15 | 16 | use tokio_line::LineCodec; 17 | 18 | use futures::{stream, Future, Stream, Sink}; 19 | 20 | use tokio_io::AsyncRead; 21 | use tokio_core::net::{TcpStream, TcpListener}; 22 | use tokio_core::reactor::Core; 23 | 24 | use std::{io, thread}; 25 | use std::time::Duration; 26 | 27 | /// Run the server. The server will simply listen for new connections, receive 28 | /// strings, and write them to STDOUT. 29 | /// 30 | /// The function will block until the server is shutdown. 31 | pub fn server() { 32 | let mut core = Core::new().unwrap(); 33 | let handle = core.handle(); 34 | let remote_addr = "127.0.0.1:14566".parse().unwrap(); 35 | 36 | let listener = TcpListener::bind(&remote_addr, &handle).unwrap(); 37 | 38 | // Accept all incoming sockets 39 | let server = listener.incoming().for_each(move |(socket, _)| { 40 | // Use the `Io::framed` helper to get a transport from a socket. The 41 | // `LineCodec` handles encoding / decoding frames. 42 | let transport = socket.framed(LineCodec); 43 | 44 | // The transport is a `Stream`. So we can now operate at 45 | // at the frame level. For each received line, write the string to 46 | // STDOUT. 47 | // 48 | // The return value of `for_each` is a future that completes once 49 | // `transport` is done yielding new lines. This happens when the 50 | // underlying socket closes. 51 | let process_connection = transport.for_each(|line| { 52 | println!("GOT: {}", line); 53 | Ok(()) 54 | }); 55 | 56 | // Spawn a new task dedicated to processing the connection 57 | handle.spawn(process_connection.map_err(|_| ())); 58 | 59 | Ok(()) 60 | }); 61 | 62 | // Open listener 63 | core.run(server).unwrap(); 64 | } 65 | 66 | pub fn main() { 67 | // Run the server in a dedicated thread 68 | thread::spawn(|| server()); 69 | 70 | // Wait a moment for the server to start... 71 | thread::sleep(Duration::from_millis(100)); 72 | 73 | // Connect to the remote and write some lines 74 | let mut core = Core::new().unwrap(); 75 | let handle = core.handle(); 76 | let remote_addr = "127.0.0.1:14566".parse().unwrap(); 77 | 78 | let work = TcpStream::connect(&remote_addr, &handle) 79 | .and_then(|socket| { 80 | // Once the socket has been established, use the `framed` helper to 81 | // create a transport. 82 | let transport = socket.framed(LineCodec); 83 | 84 | // We're just going to send a few "log" messages to the remote 85 | let lines_to_send: Vec> = vec![ 86 | Ok("Hello world".to_string()), 87 | Ok("This is another message".to_string()), 88 | Ok("Not much else to say".to_string()), 89 | ]; 90 | 91 | // Send all the messages to the remote. The strings will be encoded by 92 | // the `Codec`. `send_all` returns a future that completes once 93 | // everything has been sent. 94 | transport.send_all(stream::iter(lines_to_send)) 95 | }); 96 | 97 | core.run(work).unwrap(); 98 | 99 | // Wait a bit to make sure that the server had time to receive the lines and 100 | // print them to STDOUT 101 | thread::sleep(Duration::from_millis(100)); 102 | } 103 | -------------------------------------------------------------------------------- /simple/examples/ping_pong.rs: -------------------------------------------------------------------------------- 1 | //! Using tokio-proto to get a request / response oriented client and server 2 | //! 3 | //! This example is similar to `echo_client_server`, however it also illustrates 4 | //! how to augment a transport to support additional protocol level details. 5 | //! 6 | //! In this case, we are adding a keep alive feature to our line-based protocol. 7 | //! Every so often, the client will send a "ping" message to the remote, and the 8 | //! remote is expected to immediately respond with a pong. It doesn't really 9 | //! make sense to expose the ping / pong at the service level because handling 10 | //! it isn't application specific. So, we end up handling it at the transport 11 | //! layer. 12 | 13 | extern crate tokio_line as line; 14 | 15 | #[macro_use] 16 | extern crate futures; 17 | extern crate tokio_io; 18 | extern crate tokio_core; 19 | extern crate tokio_proto; 20 | extern crate tokio_service; 21 | extern crate service_fn; 22 | 23 | use futures::{Future, Stream, Poll, Async}; 24 | use futures::{Sink, AsyncSink, StartSend}; 25 | 26 | use tokio_io::{AsyncRead, AsyncWrite}; 27 | use tokio_io::codec::Framed; 28 | use tokio_core::reactor::Core; 29 | use tokio_proto::TcpServer; 30 | use tokio_proto::pipeline::ServerProto; 31 | use tokio_service::{Service, NewService}; 32 | 33 | use service_fn::service_fn; 34 | 35 | use std::{io, thread}; 36 | use std::net::SocketAddr; 37 | use std::time::Duration; 38 | 39 | /// The PingPong will be composed of a transport and will intercept any [ping] 40 | /// messages and immediately respond with a [pong]. 41 | struct PingPong { 42 | // The upstream transport 43 | upstream: T, 44 | // Number of remaining pongs to send 45 | pongs_remaining: usize, 46 | } 47 | 48 | /// Implement `Stream` for our transport "middleware" 49 | impl Stream for PingPong 50 | where T: Stream, 51 | T: Sink, 52 | { 53 | type Item = String; 54 | type Error = io::Error; 55 | 56 | fn poll(&mut self) -> Poll, io::Error> { 57 | loop { 58 | // Poll the upstream transport. `try_ready!` will bubble up errors 59 | // and Async::NotReady. 60 | match try_ready!(self.upstream.poll()) { 61 | Some(ref msg) if msg == "[ping]" => { 62 | // Intercept [ping] messages 63 | self.pongs_remaining += 1; 64 | 65 | // Try flushing the pong, only bubble up errors 66 | try!(self.poll_complete()); 67 | } 68 | m => return Ok(Async::Ready(m)), 69 | } 70 | } 71 | } 72 | } 73 | 74 | /// Implement Sink for our transport "middleware" 75 | impl Sink for PingPong 76 | where T: Sink, 77 | { 78 | type SinkItem = String; 79 | type SinkError = io::Error; 80 | 81 | fn start_send(&mut self, item: String) -> StartSend { 82 | // Only accept the write if there are no pending pongs 83 | if self.pongs_remaining > 0 { 84 | return Ok(AsyncSink::NotReady(item)); 85 | } 86 | 87 | // If there are no pending pongs, then send the item upstream 88 | self.upstream.start_send(item) 89 | } 90 | 91 | fn poll_complete(&mut self) -> Poll<(), io::Error> { 92 | while self.pongs_remaining > 0 { 93 | // Try to send the pong upstream 94 | let res = try!(self.upstream.start_send("[pong]".to_string())); 95 | 96 | if !res.is_ready() { 97 | // The upstream is not ready to accept new items 98 | break; 99 | } 100 | 101 | // The pong has been sent upstream 102 | self.pongs_remaining -= 1; 103 | } 104 | 105 | // Call poll_complete on the upstream 106 | // 107 | // If there are remaining pongs to send, this call may create additional 108 | // capacity. One option could be to attempt to send the pongs again. 109 | // However, if a `start_send` returned NotReady, and this poll_complete 110 | // *did* create additional capacity in the upstream, then *our* 111 | // `poll_complete` will get called again shortly. 112 | // 113 | // Hopefully this makes sense... it probably doesn't, so please ask 114 | // questions in the Gitter channel and help me explain this better :) 115 | self.upstream.poll_complete() 116 | } 117 | } 118 | 119 | /// Our custom `LineProto` that will include ping / pong 120 | struct LineProto; 121 | 122 | /// Start a server, listening for connections on `addr`. 123 | /// 124 | /// Similar to the `serve` function in `lib.rs`, however since we are changing 125 | /// the protocol to include ping / pong, we will need to use the tokio-proto 126 | /// builders directly 127 | pub fn serve(addr: SocketAddr, new_service: T) 128 | where T: NewService + Send + Sync + 'static, 129 | { 130 | // We want responses returned from the provided request handler to be well 131 | // formed. The `Validate` wrapper ensures that all service instances are 132 | // also wrapped with `Validate`. 133 | let new_service = line::Validate::new(new_service); 134 | 135 | // Use the tokio-proto TCP server builder, this will handle creating a 136 | // reactor instance and other details needed to run a server. 137 | TcpServer::new(LineProto, addr) 138 | .serve(new_service); 139 | } 140 | 141 | impl ServerProto for LineProto { 142 | type Request = String; 143 | type Response = String; 144 | 145 | /// `Framed` is the return value of `io.framed(LineCodec)` 146 | type Transport = PingPong>; 147 | type BindTransport = Result; 148 | 149 | fn bind_transport(&self, io: T) -> Self::BindTransport { 150 | Ok(PingPong { 151 | upstream: io.framed(line::LineCodec), 152 | pongs_remaining: 0, 153 | }) 154 | } 155 | } 156 | 157 | pub fn main() { 158 | let mut core = Core::new().unwrap(); 159 | 160 | // This brings up our server. 161 | let addr = "127.0.0.1:12345".parse().unwrap(); 162 | 163 | thread::spawn(move || { 164 | // Use our `serve` fn 165 | serve( 166 | addr, 167 | || { 168 | Ok(service_fn(|msg| { 169 | println!("SERVER: {:?}", msg); 170 | Ok(msg) 171 | })) 172 | }); 173 | }); 174 | 175 | // A bit annoying, but we need to wait for the server to connect 176 | thread::sleep(Duration::from_millis(100)); 177 | 178 | let handle = core.handle(); 179 | 180 | core.run( 181 | line::Client::connect(&addr, &handle) 182 | .and_then(|client| { 183 | // Start with a ping 184 | client.ping() 185 | .and_then(move |_| { 186 | println!("Pong received..."); 187 | client.call("Goodbye".to_string()) 188 | }) 189 | .and_then(|response| { 190 | println!("CLIENT: {:?}", response); 191 | Ok(()) 192 | }) 193 | }) 194 | ).unwrap(); 195 | } 196 | -------------------------------------------------------------------------------- /simple/examples/handshake.rs: -------------------------------------------------------------------------------- 1 | //! Using tokio-proto to get a request / response oriented client and server 2 | //! 3 | //! This example is similar to `echo_client_server`, however it also illustrates 4 | //! how to implement a connection handshake before starting to accept requests. 5 | //! 6 | //! In this case, when a client connects to a server, it has to send the 7 | //! following line: `You ready?`. Once the server is ready to accept requests, 8 | //! it responds with: `Bring it!`. If the server wants to reject the client for 9 | //! some reason, it responds with: `No! Go away!`. The client is then expected 10 | //! to close the socket. 11 | //! 12 | //! To do this, we need to implement a `ClientLineProto` and a `ServerLineProto` 13 | //! that handle the handshakes on the client and server side respectively. 14 | 15 | extern crate tokio_line as line; 16 | 17 | #[macro_use] 18 | extern crate futures; 19 | extern crate tokio_io; 20 | extern crate tokio_core; 21 | extern crate tokio_proto; 22 | extern crate tokio_service; 23 | extern crate service_fn; 24 | 25 | use futures::future; 26 | use futures::{Future, Stream, Sink}; 27 | 28 | use tokio_io::{AsyncRead, AsyncWrite}; 29 | use tokio_io::codec::Framed; 30 | use tokio_core::reactor::Core; 31 | use tokio_proto::{TcpClient, TcpServer}; 32 | use tokio_proto::pipeline::{ClientProto, ServerProto}; 33 | use tokio_service::{Service, NewService}; 34 | 35 | use service_fn::service_fn; 36 | 37 | use std::{io, thread}; 38 | use std::net::SocketAddr; 39 | use std::time::Duration; 40 | 41 | struct ClientLineProto; 42 | struct ServerLineProto; 43 | 44 | /// Start a server, listening for connections on `addr`. 45 | /// 46 | /// Similar to the `serve` function in `lib.rs`, however since we are changing 47 | /// the protocol to include ping / pong, we will need to use the tokio-proto 48 | /// builders directly 49 | pub fn serve(addr: SocketAddr, new_service: T) 50 | where T: NewService + Send + Sync + 'static, 51 | { 52 | // We want responses returned from the provided request handler to be well 53 | // formed. The `Validate` wrapper ensures that all service instances are 54 | // also wrapped with `Validate`. 55 | let new_service = line::Validate::new(new_service); 56 | 57 | // Use the tokio-proto TCP server builder, this will handle creating a 58 | // reactor instance and other details needed to run a server. 59 | TcpServer::new(ServerLineProto, addr) 60 | .serve(new_service); 61 | } 62 | 63 | impl ServerProto for ServerLineProto { 64 | type Request = String; 65 | type Response = String; 66 | 67 | /// `Framed` is the return value of `io.framed(LineCodec)` 68 | type Transport = Framed; 69 | type BindTransport = Box>; 70 | 71 | fn bind_transport(&self, io: T) -> Self::BindTransport { 72 | // Construct the line-based transport 73 | let transport = io.framed(line::LineCodec); 74 | 75 | // The handshake requires that the client sends `You ready?`, so wait to 76 | // receive that line. If anything else is sent, error out the connection 77 | let handshake = transport.into_future() 78 | // If the transport errors out, we don't care about the transport 79 | // anymore, so just keep the error 80 | .map_err(|(e, _)| e) 81 | .and_then(|(line, transport)| { 82 | // A line has been received, check to see if it is the handshake 83 | match line { 84 | Some(ref msg) if msg == "You ready?" => { 85 | println!("SERVER: received client handshake"); 86 | // Send back the acknowledgement 87 | Box::new(transport.send("Bring it!".to_string())) as Self::BindTransport 88 | } 89 | _ => { 90 | // The client sent an unexpected handshake, error out 91 | // the connection 92 | println!("SERVER: client handshake INVALID"); 93 | let err = io::Error::new(io::ErrorKind::Other, "invalid handshake"); 94 | Box::new(future::err(err)) as Self::BindTransport 95 | } 96 | } 97 | }); 98 | 99 | Box::new(handshake) 100 | } 101 | } 102 | 103 | impl ClientProto for ClientLineProto { 104 | type Request = String; 105 | type Response = String; 106 | 107 | /// `Framed` is the return value of `io.framed(LineCodec)` 108 | type Transport = Framed; 109 | type BindTransport = Box>; 110 | 111 | fn bind_transport(&self, io: T) -> Self::BindTransport { 112 | // Construct the line-based transport 113 | let transport = io.framed(line::LineCodec); 114 | 115 | // Send the handshake frame to the server. 116 | let handshake = transport.send("You ready?".to_string()) 117 | // Wait for a response from the server, if the transport errors out, 118 | // we don't care about the transport handle anymore, just the error 119 | .and_then(|transport| transport.into_future().map_err(|(e, _)| e)) 120 | .and_then(|(line, transport)| { 121 | // The server sent back a line, check to see if it is the 122 | // expected handshake line. 123 | match line { 124 | Some(ref msg) if msg == "Bring it!" => { 125 | println!("CLIENT: received server handshake"); 126 | Ok(transport) 127 | } 128 | Some(ref msg) if msg == "No! Go away!" => { 129 | // At this point, the server is at capacity. There are a 130 | // few things that we could do. Set a backoff timer and 131 | // try again in a bit. Or we could try a different 132 | // remote server. However, we're just going to error out 133 | // the connection. 134 | 135 | println!("CLIENT: server is at capacity"); 136 | let err = io::Error::new(io::ErrorKind::Other, "server at capacity"); 137 | Err(err) 138 | } 139 | _ => { 140 | println!("CLIENT: server handshake INVALID"); 141 | let err = io::Error::new(io::ErrorKind::Other, "invalid handshake"); 142 | Err(err) 143 | } 144 | } 145 | }); 146 | 147 | Box::new(handshake) 148 | } 149 | } 150 | 151 | pub fn main() { 152 | let mut core = Core::new().unwrap(); 153 | 154 | // This brings up our server. 155 | let addr = "127.0.0.1:12345".parse().unwrap(); 156 | 157 | thread::spawn(move || { 158 | // Use our `serve` fn 159 | serve( 160 | addr, 161 | || { 162 | Ok(service_fn(|msg| { 163 | println!("SERVER: {:?}", msg); 164 | Ok(msg) 165 | })) 166 | }); 167 | }); 168 | 169 | // A bit annoying, but we need to wait for the server to connect 170 | thread::sleep(Duration::from_millis(100)); 171 | 172 | let handle = core.handle(); 173 | 174 | let client = TcpClient::new(ClientLineProto) 175 | .connect(&addr, &handle) 176 | .map(|client_service| line::Validate::new(client_service)); 177 | 178 | core.run( 179 | client 180 | .and_then(|client| { 181 | client.call("Goodbye".to_string()) 182 | .and_then(|response| { 183 | println!("CLIENT: {:?}", response); 184 | Ok(()) 185 | }) 186 | }) 187 | ).unwrap(); 188 | } 189 | -------------------------------------------------------------------------------- /simple/src/lib.rs: -------------------------------------------------------------------------------- 1 | //! A simple client and server implementation of a line-based protocol 2 | 3 | #![deny(warnings, missing_docs)] 4 | 5 | extern crate futures; 6 | extern crate tokio_io; 7 | extern crate tokio_core; 8 | extern crate tokio_proto; 9 | extern crate tokio_service; 10 | extern crate bytes; 11 | 12 | use futures::{future, Future}; 13 | 14 | use tokio_io::{AsyncRead, AsyncWrite}; 15 | use tokio_io::codec::{Framed, Encoder, Decoder}; 16 | use tokio_core::net::TcpStream; 17 | use tokio_core::reactor::Handle; 18 | use tokio_proto::{TcpClient, TcpServer}; 19 | use tokio_proto::pipeline::{ServerProto, ClientProto, ClientService}; 20 | use tokio_service::{Service, NewService}; 21 | 22 | use bytes::{BytesMut, BufMut}; 23 | 24 | use std::{io, str}; 25 | use std::net::SocketAddr; 26 | 27 | /// Line-based client handle 28 | /// 29 | /// This type just wraps the inner service. This is done to encapsulate the 30 | /// details of how the inner service is structured. Specifically, we don't want 31 | /// the type signature of our client to be: 32 | /// 33 | /// Validate> 34 | /// 35 | /// This also allows adding higher level API functions that are protocol 36 | /// specific. For example, our line client has a `ping()` function, which sends 37 | /// a "ping" request. 38 | pub struct Client { 39 | inner: Validate>, 40 | } 41 | 42 | /// A `Service` middleware that validates the correctness of requests and 43 | /// responses. 44 | /// 45 | /// Our line protocol does not support escaping '\n' in strings, this means that 46 | /// requests and responses cannot contain new lines. The `Validate` middleware 47 | /// will check the messages for new lines and error the request if one is 48 | /// detected. 49 | pub struct Validate { 50 | inner: T, 51 | } 52 | 53 | /// Our line-based codec 54 | pub struct LineCodec; 55 | 56 | /// Protocol definition 57 | struct LineProto; 58 | 59 | /// Start a server, listening for connections on `addr`. 60 | /// 61 | /// For each new connection, `new_service` will be used to build a `Service` 62 | /// instance to process requests received on the new connection. 63 | /// 64 | /// This function will block as long as the server is running. 65 | pub fn serve(addr: SocketAddr, new_service: T) 66 | where T: NewService + Send + Sync + 'static, 67 | { 68 | // We want responses returned from the provided request handler to be well 69 | // formed. The `Validate` wrapper ensures that all service instances are 70 | // also wrapped with `Validate`. 71 | let new_service = Validate { inner: new_service }; 72 | 73 | // Use the tokio-proto TCP server builder, this will handle creating a 74 | // reactor instance and other details needed to run a server. 75 | TcpServer::new(LineProto, addr) 76 | .serve(new_service); 77 | } 78 | 79 | impl Client { 80 | /// Establish a connection to a line-based server at the provided `addr`. 81 | pub fn connect(addr: &SocketAddr, handle: &Handle) -> Box> { 82 | let ret = TcpClient::new(LineProto) 83 | .connect(addr, handle) 84 | .map(|client_service| { 85 | let validate = Validate { inner: client_service}; 86 | Client { inner: validate } 87 | }); 88 | 89 | Box::new(ret) 90 | } 91 | 92 | /// Send a `ping` to the remote. The returned future resolves when the 93 | /// remote has responded with a pong. 94 | /// 95 | /// This function provides a bit of sugar on top of the the `Service` trait. 96 | pub fn ping(&self) -> Box> { 97 | // The `call` response future includes the string, but since this is a 98 | // "ping" request, we don't really need to include the "pong" response 99 | // string. 100 | let resp = self.call("[ping]".to_string()) 101 | .and_then(|resp| { 102 | if resp != "[pong]" { 103 | Err(io::Error::new(io::ErrorKind::Other, "expected pong")) 104 | } else { 105 | Ok(()) 106 | } 107 | }); 108 | 109 | // Box the response future because we are lazy and don't want to define 110 | // a new future type and `impl T` isn't stable yet... 111 | Box::new(resp) 112 | } 113 | } 114 | 115 | impl Service for Client { 116 | type Request = String; 117 | type Response = String; 118 | type Error = io::Error; 119 | // For simplicity, box the future. 120 | type Future = Box>; 121 | 122 | fn call(&self, req: String) -> Self::Future { 123 | self.inner.call(req) 124 | } 125 | } 126 | 127 | impl Validate { 128 | 129 | /// Create a new `Validate` 130 | pub fn new(inner: T) -> Validate { 131 | Validate { inner: inner } 132 | } 133 | } 134 | 135 | impl Service for Validate 136 | where T: Service, 137 | T::Future: 'static, 138 | { 139 | type Request = String; 140 | type Response = String; 141 | type Error = io::Error; 142 | // For simplicity, box the future. 143 | type Future = Box>; 144 | 145 | fn call(&self, req: String) -> Self::Future { 146 | // Make sure that the request does not include any new lines 147 | if req.chars().find(|&c| c == '\n').is_some() { 148 | let err = io::Error::new(io::ErrorKind::InvalidInput, "message contained new line"); 149 | return Box::new(future::done(Err(err))) 150 | } 151 | 152 | // Call the upstream service and validate the response 153 | Box::new(self.inner.call(req) 154 | .and_then(|resp| { 155 | if resp.chars().find(|&c| c == '\n').is_some() { 156 | Err(io::Error::new(io::ErrorKind::InvalidInput, "message contained new line")) 157 | } else { 158 | Ok(resp) 159 | } 160 | })) 161 | } 162 | } 163 | 164 | impl NewService for Validate 165 | where T: NewService, 166 | ::Future: 'static 167 | { 168 | type Request = String; 169 | type Response = String; 170 | type Error = io::Error; 171 | type Instance = Validate; 172 | 173 | fn new_service(&self) -> io::Result { 174 | let inner = try!(self.inner.new_service()); 175 | Ok(Validate { inner: inner }) 176 | } 177 | } 178 | 179 | /// Implementation of the simple line-based protocol. 180 | /// 181 | /// Frames consist of a UTF-8 encoded string, terminated by a '\n' character. 182 | impl Decoder for LineCodec { 183 | type Item = String; 184 | type Error = io::Error; 185 | 186 | fn decode(&mut self, buf: &mut BytesMut) -> Result, io::Error> { 187 | // Check to see if the frame contains a new line 188 | if let Some(n) = buf.as_ref().iter().position(|b| *b == b'\n') { 189 | // remove the serialized frame from the buffer. 190 | let line = buf.split_to(n); 191 | 192 | // Also remove the '\n' 193 | buf.split_to(1); 194 | 195 | // Turn this data into a UTF string and return it in a Frame. 196 | return match str::from_utf8(&line.as_ref()) { 197 | Ok(s) => Ok(Some(s.to_string())), 198 | Err(_) => Err(io::Error::new(io::ErrorKind::Other, "invalid string")), 199 | } 200 | } 201 | 202 | Ok(None) 203 | } 204 | } 205 | 206 | impl Encoder for LineCodec { 207 | type Item = String; 208 | type Error = io::Error; 209 | 210 | fn encode(&mut self, msg: String, buf: &mut BytesMut) -> io::Result<()> { 211 | // Reserve enough space for the line 212 | buf.reserve(msg.len() + 1); 213 | 214 | buf.extend(msg.as_bytes()); 215 | buf.put_u8(b'\n'); 216 | 217 | Ok(()) 218 | } 219 | } 220 | 221 | impl ClientProto for LineProto { 222 | type Request = String; 223 | type Response = String; 224 | 225 | /// `Framed` is the return value of `io.framed(LineCodec)` 226 | type Transport = Framed; 227 | type BindTransport = Result; 228 | 229 | fn bind_transport(&self, io: T) -> Self::BindTransport { 230 | Ok(io.framed(LineCodec)) 231 | } 232 | } 233 | 234 | impl ServerProto for LineProto { 235 | type Request = String; 236 | type Response = String; 237 | 238 | /// `Framed` is the return value of `io.framed(LineCodec)` 239 | type Transport = Framed; 240 | type BindTransport = Result; 241 | 242 | fn bind_transport(&self, io: T) -> Self::BindTransport { 243 | Ok(io.framed(LineCodec)) 244 | } 245 | } 246 | -------------------------------------------------------------------------------- /multiplexed/src/lib.rs: -------------------------------------------------------------------------------- 1 | //! A simple client and server implementation fo a multiplexed, line-based 2 | //! protocol 3 | 4 | #![deny(warnings, missing_docs)] 5 | 6 | extern crate futures; 7 | extern crate tokio_io; 8 | extern crate tokio_core; 9 | extern crate tokio_proto; 10 | extern crate tokio_service; 11 | extern crate bytes; 12 | 13 | use futures::{future, Future}; 14 | 15 | use tokio_io::{AsyncRead, AsyncWrite}; 16 | use tokio_io::codec::{Encoder, Decoder, Framed}; 17 | use tokio_core::net::TcpStream; 18 | use tokio_core::reactor::Handle; 19 | use tokio_proto::{TcpClient, TcpServer}; 20 | use tokio_proto::multiplex::{RequestId, ServerProto, ClientProto, ClientService}; 21 | use tokio_service::{Service, NewService}; 22 | 23 | use bytes::{BytesMut, Buf, BufMut, BigEndian}; 24 | 25 | use std::{io, str}; 26 | use std::net::SocketAddr; 27 | 28 | /// Multiplexed line-based client handle 29 | /// 30 | /// This type just wraps the inner service. This is done to encapsulate the 31 | /// details of how the inner service is structured. Specifically, we don't want 32 | /// the type signature of our client to be: 33 | /// 34 | /// Validate> 35 | /// 36 | /// This also allows adding higher level API functions that are protocol 37 | /// specific. For example, our line client has a `ping()` function, which sends 38 | /// a "ping" request. 39 | pub struct Client { 40 | inner: Validate>, 41 | } 42 | 43 | /// A `Service` middleware that validates the correctness of requests and 44 | /// responses. 45 | /// 46 | /// Our line protocol does not support escaping '\n' in strings, this means that 47 | /// requests and responses cannot contain new lines. The `Validate` middleware 48 | /// will check the messages for new lines and error the request if one is 49 | /// detected. 50 | struct Validate { 51 | inner: T, 52 | } 53 | 54 | /// Our multiplexed line-based codec 55 | struct LineCodec; 56 | 57 | /// Protocol definition 58 | struct LineProto; 59 | 60 | /// Start a server, listening for connections on `addr`. 61 | /// 62 | /// For each new connection, `new_service` will be used to build a `Service` 63 | /// instance to process requests received on the new connection. 64 | /// 65 | /// This function will block as long as the server is running. 66 | pub fn serve(addr: SocketAddr, new_service: T) 67 | where T: NewService + Send + Sync + 'static, 68 | { 69 | // We want responses returned from the provided request handler to be well 70 | // formed. The `Validate` wrapper ensures that all service instances are 71 | // also wrapped with `Validate`. 72 | let new_service = Validate { inner: new_service }; 73 | 74 | // Use the tokio-proto TCP server builder, this will handle creating a 75 | // reactor instance and other details needed to run a server. 76 | TcpServer::new(LineProto, addr) 77 | .serve(new_service); 78 | } 79 | 80 | impl Client { 81 | /// Establish a connection to a multiplexed line-based server at the 82 | /// provided `addr`. 83 | pub fn connect(addr: &SocketAddr, handle: &Handle) -> Box> { 84 | let ret = TcpClient::new(LineProto) 85 | .connect(addr, handle) 86 | .map(|client_service| { 87 | let validate = Validate { inner: client_service}; 88 | Client { inner: validate } 89 | }); 90 | 91 | Box::new(ret) 92 | } 93 | } 94 | 95 | impl Service for Client { 96 | type Request = String; 97 | type Response = String; 98 | type Error = io::Error; 99 | // For simplicity, box the future. 100 | type Future = Box>; 101 | 102 | fn call(&self, req: String) -> Self::Future { 103 | self.inner.call(req) 104 | } 105 | } 106 | 107 | impl Service for Validate 108 | where T: Service, 109 | T::Future: 'static, 110 | { 111 | type Request = String; 112 | type Response = String; 113 | type Error = io::Error; 114 | // For simplicity, box the future. 115 | type Future = Box>; 116 | 117 | fn call(&self, req: String) -> Self::Future { 118 | // Make sure that the request does not include any new lines 119 | if req.chars().find(|&c| c == '\n').is_some() { 120 | let err = io::Error::new(io::ErrorKind::InvalidInput, "message contained new line"); 121 | return Box::new(future::done(Err(err))) 122 | } 123 | 124 | // Call the upstream service and validate the response 125 | Box::new(self.inner.call(req) 126 | .and_then(|resp| { 127 | if resp.chars().find(|&c| c == '\n').is_some() { 128 | Err(io::Error::new(io::ErrorKind::InvalidInput, "message contained new line")) 129 | } else { 130 | Ok(resp) 131 | } 132 | })) 133 | } 134 | } 135 | 136 | impl NewService for Validate 137 | where T: NewService, 138 | ::Future: 'static 139 | { 140 | type Request = String; 141 | type Response = String; 142 | type Error = io::Error; 143 | type Instance = Validate; 144 | 145 | fn new_service(&self) -> io::Result { 146 | let inner = try!(self.inner.new_service()); 147 | Ok(Validate { inner: inner }) 148 | } 149 | } 150 | 151 | /// Implementation of the multiplexed line-based protocol. 152 | /// 153 | /// Frames begin with a 4 byte header, consisting of the numeric request ID 154 | /// encoded in network order, followed by the frame payload encoded as a UTF-8 155 | /// string and terminated with a '\n' character: 156 | /// 157 | /// # An example frame: 158 | /// 159 | /// +-- request id --+------- frame payload --------+ 160 | /// | | | 161 | /// | \x00000001 | This is the frame payload \n | 162 | /// | | | 163 | /// +----------------+------------------------------+ 164 | /// 165 | impl Decoder for LineCodec { 166 | type Item = (RequestId, String); 167 | type Error = io::Error; 168 | 169 | fn decode(&mut self, buf: &mut BytesMut) -> Result, io::Error> { 170 | // At least 5 bytes are required for a frame: 4 byte head + one byte 171 | // '\n' 172 | if buf.len() < 5 { 173 | return Ok(None); 174 | } 175 | 176 | // Check to see if the frame contains a new line, skipping the first 4 177 | // bytes which is the request ID 178 | if let Some(n) = buf.as_ref()[4..].iter().position(|b| *b == b'\n') { 179 | // remove the serialized frame from the buffer. 180 | let line = buf.split_to(n + 4); 181 | 182 | // Also remove the '\n' 183 | buf.split_to(1); 184 | 185 | // Deserialize the request ID 186 | let request_id = io::Cursor::new(&line[0..4]).get_u32::(); 187 | 188 | // Turn this data into a UTF string and return it in a Frame. 189 | return match str::from_utf8(&line.as_ref()[4..]) { 190 | Ok(s) => Ok(Some((request_id as RequestId, s.to_string()))), 191 | Err(_) => Err(io::Error::new(io::ErrorKind::Other, "invalid string")), 192 | } 193 | } 194 | 195 | Ok(None) 196 | } 197 | } 198 | 199 | impl Encoder for LineCodec { 200 | type Item = (RequestId, String); 201 | type Error = io::Error; 202 | 203 | fn encode(&mut self, msg: (RequestId, String), buf: &mut BytesMut) -> io::Result<()> { 204 | // Reserve enough space for the frame 205 | let len = 4 + msg.1.len() + 1; 206 | buf.reserve(len); 207 | 208 | let (request_id, msg) = msg; 209 | 210 | buf.put_u32::(request_id as u32); 211 | buf.put_slice(msg.as_bytes()); 212 | buf.put_u8(b'\n'); 213 | 214 | Ok(()) 215 | } 216 | } 217 | 218 | impl ClientProto for LineProto { 219 | type Request = String; 220 | type Response = String; 221 | 222 | /// `Framed` is the return value of `io.framed(LineCodec)` 223 | type Transport = Framed; 224 | type BindTransport = Result; 225 | 226 | fn bind_transport(&self, io: T) -> Self::BindTransport { 227 | Ok(io.framed(LineCodec)) 228 | } 229 | } 230 | 231 | impl ServerProto for LineProto { 232 | type Request = String; 233 | type Response = String; 234 | 235 | /// `Framed` is the return value of `io.framed(LineCodec)` 236 | type Transport = Framed; 237 | type BindTransport = Result; 238 | 239 | fn bind_transport(&self, io: T) -> Self::BindTransport { 240 | Ok(io.framed(LineCodec)) 241 | } 242 | } 243 | -------------------------------------------------------------------------------- /LICENSE-APACHE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright 2017 Tokio contributors 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /streaming/src/lib.rs: -------------------------------------------------------------------------------- 1 | //! A simple client and server implementation of a line-based protocol with 2 | //! streaming capabilities. 3 | //! 4 | //! The protocol is line-based, however if a line is empty, this implies that it 5 | //! is being streamed. All subsequent lines are the streaming body until another 6 | //! empty line is reached. 7 | 8 | #![deny(warnings, missing_docs)] 9 | 10 | extern crate futures; 11 | extern crate tokio_io; 12 | extern crate tokio_core; 13 | extern crate tokio_proto; 14 | extern crate tokio_service; 15 | extern crate bytes; 16 | 17 | use futures::{Future, Stream, Poll}; 18 | use futures::sync::mpsc; 19 | 20 | use tokio_io::{AsyncRead, AsyncWrite}; 21 | use tokio_io::codec::{Encoder, Decoder, Framed}; 22 | use tokio_core::reactor::Handle; 23 | use tokio_proto::{TcpClient, TcpServer}; 24 | use tokio_proto::streaming::{Body, Message}; 25 | use tokio_proto::streaming::pipeline::{Frame, ServerProto, ClientProto}; 26 | use tokio_proto::util::client_proxy::ClientProxy; 27 | use tokio_service::{Service, NewService}; 28 | 29 | use bytes::{BytesMut, BufMut}; 30 | 31 | use std::{io, str}; 32 | use std::net::SocketAddr; 33 | 34 | /// Line-based client handle 35 | /// 36 | /// This type just wraps the inner service. This is done to encapsulate the 37 | /// details of how the inner service is structured. Specifically, we don't want 38 | /// the type signature of our client to be: 39 | /// 40 | /// ClientTypeMap> 41 | /// 42 | /// This also allows adding higher level API functions that are protocol 43 | /// specific. For example, our line client has a `ping()` function, which sends 44 | /// a "ping" request. 45 | pub struct Client { 46 | inner: ClientTypeMap>, 47 | } 48 | 49 | /// The request and response type for the streaming line-based service. 50 | /// 51 | /// A message is either "oneshot" and includes the full line, or it is streaming 52 | /// and the line is broken up into chunks. 53 | #[derive(Debug)] 54 | pub enum Line { 55 | /// The full line 56 | Once(String), 57 | /// A stream of line chunks 58 | Stream(LineStream), 59 | } 60 | 61 | /// A stream of line chunks. 62 | /// 63 | /// We defined a custom type that wraps `tokio_proto::streaming::Body` in order 64 | /// to keep tokio-proto as an implementation detail. 65 | #[derive(Debug)] 66 | pub struct LineStream { 67 | inner: Body, 68 | } 69 | 70 | impl LineStream { 71 | /// Returns a `LineStream` with its sender half. 72 | pub fn pair() -> (mpsc::Sender>, LineStream) { 73 | let (tx, rx) = Body::pair(); 74 | (tx, LineStream { inner: rx }) 75 | } 76 | } 77 | 78 | impl Stream for LineStream { 79 | type Item = String; 80 | type Error = io::Error; 81 | 82 | fn poll(&mut self) -> Poll, io::Error> { 83 | self.inner.poll() 84 | } 85 | } 86 | 87 | /// Message type used to communicate with tokio-proto. The library should hide 88 | /// this and instead expose a custom message type 89 | type LineMessage = Message>; 90 | 91 | /// Maps types between Line <-> LineMessage for the server service 92 | struct ServerTypeMap { 93 | inner: T, 94 | } 95 | 96 | /// Maps types between Line <-> LineMessage for the client service 97 | struct ClientTypeMap { 98 | inner: T, 99 | } 100 | 101 | /// Our line-based codec 102 | /// 103 | /// In this version of the `LineCodec`, some state is required. We need to track 104 | /// if we are currently decoding a message "head" or the streaming body. 105 | pub struct LineCodec { 106 | decoding_head: bool, 107 | } 108 | 109 | /// Protocol definition 110 | struct LineProto; 111 | 112 | /// Start a server, listening for connections on `addr`. 113 | /// 114 | /// For each new connection, `new_service` will be used to build a `Service` 115 | /// instance to process requests received on the new connection. 116 | /// 117 | /// This function will block as long as the server is running. 118 | pub fn serve(addr: SocketAddr, new_service: T) 119 | where T: NewService + Send + Sync + 'static, 120 | { 121 | let new_service = ServerTypeMap { inner: new_service }; 122 | 123 | // Use the tokio-proto TCP server builder, this will handle creating a 124 | // reactor instance and other details needed to run a server. 125 | TcpServer::new(LineProto, addr) 126 | .serve(new_service); 127 | } 128 | 129 | impl Client { 130 | /// Establish a connection to a line-based server at the provided `addr`. 131 | pub fn connect(addr: &SocketAddr, handle: &Handle) -> Box> { 132 | let ret = TcpClient::new(LineProto) 133 | .connect(addr, handle) 134 | .map(|client_proxy| { 135 | // Wrap the returned client handle with our `ClientTypeMap` 136 | // service middleware 137 | let type_map = ClientTypeMap { inner: client_proxy }; 138 | Client { inner: type_map } 139 | }); 140 | 141 | Box::new(ret) 142 | } 143 | } 144 | 145 | impl Service for Client { 146 | type Request = Line; 147 | type Response = Line; 148 | type Error = io::Error; 149 | // For simplicity, box the future. 150 | type Future = Box>; 151 | 152 | fn call(&self, req: Line) -> Self::Future { 153 | self.inner.call(req) 154 | } 155 | } 156 | 157 | /* 158 | * 159 | * ===== impl Line ===== 160 | * 161 | */ 162 | 163 | impl From for Line { 164 | fn from(src: LineMessage) -> Line { 165 | match src { 166 | Message::WithoutBody(line) => Line::Once(line), 167 | Message::WithBody(head, body) => { 168 | assert_eq!(head, ""); 169 | Line::Stream(LineStream { inner: body }) 170 | } 171 | } 172 | } 173 | } 174 | 175 | impl From for Message> { 176 | fn from(src: Line) -> Self { 177 | match src { 178 | Line::Once(line) => Message::WithoutBody(line), 179 | Line::Stream(body) => { 180 | let LineStream { inner } = body; 181 | Message::WithBody("".to_string(), inner) 182 | } 183 | } 184 | } 185 | } 186 | 187 | /* 188 | * 189 | * ===== ServerTypeMap ===== 190 | * 191 | */ 192 | 193 | impl Service for ServerTypeMap 194 | where T: Service, 195 | T::Future: 'static 196 | { 197 | type Request = LineMessage; 198 | type Response = LineMessage; 199 | type Error = io::Error; 200 | type Future = Box>; 201 | 202 | fn call(&self, req: LineMessage) -> Self::Future { 203 | Box::new(self.inner.call(req.into()) 204 | .map(LineMessage::from)) 205 | } 206 | } 207 | 208 | impl NewService for ServerTypeMap 209 | where T: NewService, 210 | ::Future: 'static 211 | { 212 | type Request = LineMessage; 213 | type Response = LineMessage; 214 | type Error = io::Error; 215 | type Instance = ServerTypeMap; 216 | 217 | fn new_service(&self) -> io::Result { 218 | let inner = try!(self.inner.new_service()); 219 | Ok(ServerTypeMap { inner: inner }) 220 | } 221 | } 222 | 223 | /* 224 | * 225 | * ===== ClientTypeMap ===== 226 | * 227 | */ 228 | 229 | impl Service for ClientTypeMap 230 | where T: Service, 231 | T::Future: 'static 232 | { 233 | type Request = Line; 234 | type Response = Line; 235 | type Error = io::Error; 236 | type Future = Box>; 237 | 238 | fn call(&self, req: Line) -> Self::Future { 239 | Box::new(self.inner.call(req.into()) 240 | .map(Line::from)) 241 | } 242 | } 243 | 244 | /// Implementation of the simple line-based protocol. 245 | /// 246 | /// Frames consist of a UTF-8 encoded string, terminated by a '\n' character. 247 | impl Decoder for LineCodec { 248 | type Item = Frame; 249 | type Error = io::Error; 250 | 251 | 252 | fn decode(&mut self, buf: &mut BytesMut) -> Result, io::Error> { 253 | // Check to see if the frame contains a new line 254 | if let Some(n) = buf.as_ref().iter().position(|b| *b == b'\n') { 255 | // remove the serialized frame from the buffer. 256 | let line = buf.split_to(n); 257 | 258 | // Also remove the '\n' 259 | buf.split_to(1); 260 | 261 | // Turn this data into a UTF string and return it in a Frame. 262 | return match str::from_utf8(&line.as_ref()) { 263 | Ok(s) => { 264 | // Got an empty line, which means that the state should be 265 | // toggled. 266 | if s == "" { 267 | let decoding_head = self.decoding_head; 268 | // Toggle the state 269 | self.decoding_head = !decoding_head; 270 | 271 | if decoding_head { 272 | Ok(Some(Frame::Message { 273 | // The message head is an empty line 274 | message: s.to_string(), 275 | // We will be streaming a body after this 276 | body: true, 277 | })) 278 | } else { 279 | // We parsed the streaming body "termination" frame, 280 | // which is represented as `None`. 281 | Ok(Some(Frame::Body { 282 | chunk: None 283 | })) 284 | } 285 | } else { 286 | if self.decoding_head { 287 | // This is a "oneshot" message with no streaming 288 | // body 289 | Ok(Some(Frame::Message { 290 | message: s.to_string(), 291 | body: false, 292 | })) 293 | } else { 294 | // This line is a chunk in a streaming body 295 | Ok(Some(Frame::Body { 296 | chunk: Some(s.to_string()), 297 | })) 298 | } 299 | } 300 | } 301 | Err(_) => Err(io::Error::new(io::ErrorKind::Other, "invalid string")), 302 | } 303 | } 304 | 305 | Ok(None) 306 | } 307 | } 308 | 309 | impl Encoder for LineCodec { 310 | type Item = Frame; 311 | type Error = io::Error; 312 | 313 | 314 | fn encode(&mut self, msg: Self::Item, buf: &mut BytesMut) -> io::Result<()> { 315 | match msg { 316 | Frame::Message { message, body } => { 317 | // Our protocol dictates that a message head that includes a 318 | // streaming body is an empty string. 319 | assert!(message.is_empty() == body); 320 | 321 | buf.reserve(message.len()); 322 | buf.extend(message.as_bytes()); 323 | } 324 | Frame::Body { chunk } => { 325 | if let Some(chunk) = chunk { 326 | buf.reserve(chunk.len()); 327 | buf.extend(chunk.as_bytes()); 328 | } 329 | } 330 | Frame::Error { error } => { 331 | // Our protocol does not support error frames, so this results 332 | // in a connection level error, which will terminate the socket. 333 | return Err(error); 334 | } 335 | } 336 | 337 | // Push the new line 338 | buf.put_u8(b'\n'); 339 | 340 | Ok(()) 341 | } 342 | } 343 | 344 | impl ClientProto for LineProto { 345 | type Request = String; 346 | type RequestBody = String; 347 | type Response = String; 348 | type ResponseBody = String; 349 | type Error = io::Error; 350 | 351 | /// `Framed` is the return value of `io.framed(LineCodec)` 352 | type Transport = Framed; 353 | type BindTransport = Result; 354 | 355 | fn bind_transport(&self, io: T) -> Self::BindTransport { 356 | let codec = LineCodec { 357 | decoding_head: true, 358 | }; 359 | 360 | Ok(io.framed(codec)) 361 | } 362 | } 363 | 364 | impl ServerProto for LineProto { 365 | type Request = String; 366 | type RequestBody = String; 367 | type Response = String; 368 | type ResponseBody = String; 369 | type Error = io::Error; 370 | 371 | /// `Framed` is the return value of `io.framed(LineCodec)` 372 | type Transport = Framed; 373 | type BindTransport = Result; 374 | 375 | fn bind_transport(&self, io: T) -> Self::BindTransport { 376 | let codec = LineCodec { 377 | decoding_head: true, 378 | }; 379 | 380 | Ok(io.framed(codec)) 381 | } 382 | } 383 | --------------------------------------------------------------------------------