simple_stream/
lib.rs

1// Copyright 2015 Nathan Sizemore <nathanrsizemore@gmail.com>
2//
3// This Source Code Form is subject to the terms of the
4// Mozilla Public License, v. 2.0. If a copy of the MPL was not
5// distributed with this file, You can obtain one at
6// http://mozilla.org/MPL/2.0/.
7
8//! simple-stream is a buffered stream wrapper over anything that implements
9//! `std::io::Read` and `std::io::Write`. It works by buffering all reads and
10//! checking the buffers against a `FrameBuilder`, which will inform the stream
11//! that a complete `Frame` has been received, and removes it out of the buffer.
12//!
13//! The crate comes with a few types of Framing options, and provides both a plain
14//! text and encrypted stream via [rust-openssl][rust-openssl-repo].
15//!
16//! ## Example Usage
17//!
18//! ```ignore
19//! extern crate simple_stream as ss;
20//!
21//! use std::net::TcpStream;
22//!
23//! use ss::frame::{SimpleFrame, SimpleFrameBuilder};
24//! use ss::{Plain, NonBlocking};
25//!
26//!
27//! fn main() {
28//!     // Create some non-blocking type that implements Read + Write
29//!     let stream = TcpStream::connect("rust-lang.org:80").unwrap();
30//!     stream.set_nonblocking(true).unwrap();
31//!
32//!     // Create a Plain Text stream that sends and receives messages in the
33//!     // `SimpleFrame` format.
34//!     let mut plain_stream = Plain::<TcpStream, SimpleFrameBuilder>::new(stream);
35//!
36//!     // Perform a non-blocking write
37//!     let buf = vec!(1, 2, 3, 4);
38//!     let frame = SimpleFrame::new(&buf[..]);
39//!     match plain_stream.nb_send(&frame) {
40//!         Ok(_) => { }
41//!         Err(e) => println!("Error during write: {}", e)
42//!     };
43//!
44//!     // Perform a non-blocking read
45//!     match plain_stream.nb_recv() {
46//!         Ok(frames) => {
47//!             for _ in frames {
48//!                 // Do stuff with received frames
49//!             }
50//!         }
51//!         Err(e) => println!("Error during read: {}", e)
52//!     };
53//! }
54//! ```
55//!
56//!
57//! [rust-openssl-repo]: https://github.com/sfackler/rust-openssl
58
59#[macro_use]
60extern crate bitflags;
61extern crate libc;
62#[macro_use]
63extern crate log;
64#[cfg(feature = "openssl")]
65extern crate openssl;
66
67pub mod frame;
68mod plain;
69#[cfg(feature = "openssl")]
70mod secure;
71
72use std::io;
73
74use frame::Frame;
75
76pub use plain::*;
77#[cfg(feature = "openssl")]
78pub use secure::*;
79
80/// The `Blocking` trait provides method definitions for use with blocking streams.
81pub trait Blocking {
82    /// Performs a blocking read on the underlying stream until a complete Frame has been read
83    /// or an `std::io::Error` has occurred.
84    fn b_recv(&mut self) -> io::Result<Box<dyn Frame>>;
85    /// Performs a blocking send on the underlying stream until a complete frame has been sent
86    /// or an `std::io::Error` has occurred.
87    fn b_send(&mut self, frame: &dyn Frame) -> io::Result<()>;
88}
89
90/// The `NonBlocking` trait provides method definitions for use with non-blocking streams.
91pub trait NonBlocking {
92    /// Performs a non-blocking read on the underlying stream until `ErrorKind::WouldBlock` or an
93    /// `std::io::Error` has occurred.
94    ///
95    /// # `simple_stream::Secure` notes
96    ///
97    /// Unlike its blocking counterpart, errors received on the OpenSSL level will be returned as
98    /// `ErrorKind::Other` with various OpenSSL error information as strings in the description
99    /// field of the `std::io::Error`.
100    fn nb_recv(&mut self) -> io::Result<Vec<Box<dyn Frame>>>;
101    /// Performs a non-blocking send on the underlying stream until `ErrorKind::WouldBlock` or an
102    /// `std::io::Error` has occurred.
103    ///
104    /// # `simple_stream::Secure` notes
105    ///
106    /// Unlike its blocking counterpart, errors received on the OpenSSL level will be returned as
107    /// `ErrorKind::Other` with various OpenSSL error information as strings in the description
108    /// field of the `std::io::Error`.
109    fn nb_send(&mut self, frame: &dyn Frame) -> io::Result<()>;
110}
simple_stream/lib.rs

simple_stream/
lib.rs
