simple-stream 0.11.0

Building blocks for streaming chunks of data over io::Read and io::Write impls.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

// Copyright 2015 Nathan Sizemore <nathanrsizemore@gmail.com>
//
// This Source Code Form is subject to the terms of the
// Mozilla Public License, v. 2.0. If a copy of the MPL was not
// distributed with this file, You can obtain one at
// http://mozilla.org/MPL/2.0/.

//! simple-stream is a buffered stream wrapper over anything that implements
//! `std::io::Read` and `std::io::Write`. It works by buffering all reads and
//! checking the buffers against a `FrameBuilder`, which will inform the stream
//! that a complete `Frame` has been received, and removes it out of the buffer.
//!
//! The crate comes with a few types of Framing options, and provides both a plain
//! text and encrypted stream via [rust-openssl][rust-openssl-repo].
//!
//! ## Example Usage
//!
//! ```ignore
//! extern crate simple_stream as ss;
//!
//! use std::net::TcpStream;
//!
//! use ss::frame::{SimpleFrame, SimpleFrameBuilder};
//! use ss::{Plain, NonBlocking};
//!
//!
//! fn main() {
//!     // Create some non-blocking type that implements Read + Write
//!     let stream = TcpStream::connect("rust-lang.org:80").unwrap();
//!     stream.set_nonblocking(true).unwrap();
//!
//!     // Create a Plain Text stream that sends and receives messages in the
//!     // `SimpleFrame` format.
//!     let mut plain_stream = Plain::<TcpStream, SimpleFrameBuilder>::new(stream);
//!
//!     // Perform a non-blocking write
//!     let buf = vec!(1, 2, 3, 4);
//!     let frame = SimpleFrame::new(&buf[..]);
//!     match plain_stream.nb_send(&frame) {
//!         Ok(_) => { }
//!         Err(e) => println!("Error during write: {}", e)
//!     };
//!
//!     // Perform a non-blocking read
//!     match plain_stream.nb_recv() {
//!         Ok(frames) => {
//!             for _ in frames {
//!                 // Do stuff with received frames
//!             }
//!         }
//!         Err(e) => println!("Error during read: {}", e)
//!     };
//! }
//! ```
//!
//!
//! [rust-openssl-repo]: https://github.com/sfackler/rust-openssl

#[macro_use]
extern crate bitflags;
extern crate libc;
#[macro_use]
extern crate log;
#[cfg(feature = "openssl")]
extern crate openssl;

pub mod frame;
mod plain;
#[cfg(feature = "openssl")]
mod secure;

use std::io;

use frame::Frame;

pub use plain::*;
#[cfg(feature = "openssl")]
pub use secure::*;

/// The `Blocking` trait provides method definitions for use with blocking streams.
pub trait Blocking {
    /// Performs a blocking read on the underlying stream until a complete Frame has been read
    /// or an `std::io::Error` has occurred.
    fn b_recv(&mut self) -> io::Result<Box<dyn Frame>>;
    /// Performs a blocking send on the underlying stream until a complete frame has been sent
    /// or an `std::io::Error` has occurred.
    fn b_send(&mut self, frame: &dyn Frame) -> io::Result<()>;
}

/// The `NonBlocking` trait provides method definitions for use with non-blocking streams.
pub trait NonBlocking {
    /// Performs a non-blocking read on the underlying stream until `ErrorKind::WouldBlock` or an
    /// `std::io::Error` has occurred.
    ///
    /// # `simple_stream::Secure` notes
    ///
    /// Unlike its blocking counterpart, errors received on the OpenSSL level will be returned as
    /// `ErrorKind::Other` with various OpenSSL error information as strings in the description
    /// field of the `std::io::Error`.
    fn nb_recv(&mut self) -> io::Result<Vec<Box<dyn Frame>>>;
    /// Performs a non-blocking send on the underlying stream until `ErrorKind::WouldBlock` or an
    /// `std::io::Error` has occurred.
    ///
    /// # `simple_stream::Secure` notes
    ///
    /// Unlike its blocking counterpart, errors received on the OpenSSL level will be returned as
    /// `ErrorKind::Other` with various OpenSSL error information as strings in the description
    /// field of the `std::io::Error`.
    fn nb_send(&mut self, frame: &dyn Frame) -> io::Result<()>;
}