Crate nbio

Description

This crate aims to make bi-directional, nonblocking I/O easier to reason about by using patterns that extend beyond dealing directly with raw bytes, the std::io::Read and std::io::Write traits, and std::io::ErrorKind::WouldBlock errors. Since this crate’s main focus is nonblocking I/O, all Session implementations provided by this crate are non-blocking by default.

Sessions

The core Session API utilizes associated types to express nonblocking read and write operations. While the tcp module provides a Session implementation that provides unframed non-blocking binary IO operations, other Session impls are able to provide significantly more functionality using the same non-blocking patterns.

Associated Types

Sessions operate on implementation-specific Session::ReadData and Session::WriteData types. Instead of populating a mutable buffer provided by the user a-la std::io::Read operations, a reference to a received event is returned. This allows Session implementations to perform internal buffering, framing, and serialization to support implementation-specific types.

Errors

The philosophy of this crate is that an Err should always represent a transport or protocol-level error. An Err should not be returned by a function as a condition that should be handled during normal branching logic. As a result, instead of forcing you to handle std::io::ErrorKind::WouldBlock everywhere you deal with nonblocking code, this crate will indicate partial read/write operations using ReadStatus::None, ReadStatus::Buffered, and WriteStatus::Pending as Result::Ok.

Non-Blocking Examples

Streaming TCP

The following example shows how to use streaming TCP to send and receive a traditional stream of bytes.

use nbio::{ReadStatus, Session, WriteStatus};
use nbio::tcp::StreamingTcpSession;

// establish connection
let mut client = StreamingTcpSession::connect("192.168.123.456:54321").unwrap();

// send some bytes until completion
let mut remaining_write = "hello world!".as_bytes();
while let WriteStatus::Pending(pending) = client.write(remaining_write).unwrap() {
    remaining_write = pending;
    client.drive().unwrap();
}

// print received bytes
loop {
    if let ReadStatus::Data(data) = client.read().unwrap() {
        println!("received: {data:?}");
    }
}

Framing TCP

The following example shows how to frame messages over TCP to send and receive payloads framed with a preceeding u64 length field. Notice how it is almost identical to the code above, except it guarantees that read slices are always identical to their corresponding write slices.

use nbio::{ReadStatus, Session, WriteStatus};
use nbio::tcp::StreamingTcpSession;
use nbio::frame::{FramingSession, U64FramingStrategy};

// establish connection wrapped in a framing session
let client = StreamingTcpSession::connect("192.168.123.456:54321").unwrap();
let mut client = FramingSession::new(client, U64FramingStrategy::new(), 4096);

// send some bytes until completion
let mut remaining_write = "hello world!".as_bytes();
while let WriteStatus::Pending(pending) = client.write(remaining_write).unwrap() {
    remaining_write = pending;
    client.drive().unwrap();
}

// print received bytes
loop {
    if let ReadStatus::Data(data) = client.read().unwrap() {
        println!("received: {data:?}");
    }
}

HTTP Request/Response

The following example shows how to use the http module to drive an HTTP 1.x request/response using the same non-blocking model. Notice how the primitives of driving a buffered write to completion and receiving a framed response is the same as any other framed session. In fact, the conn returned by client.request(..) is simply a frame::FramingSession that utilizes a http::Http1FramingStrategy.

use http::Request;
use nbio::{Session, ReadStatus};
use nbio::http::HttpClient;
use tcp_stream::OwnedTLSConfig;

// create the client and make the request
let mut client = HttpClient::new(OwnedTLSConfig::default());
let mut conn = client
    .request(Request::get("http://icanhazip.com").body(()).unwrap())
    .unwrap();

// drive and read the conn until a full response is received
loop {
    conn.drive().unwrap();
    if let ReadStatus::Data(r) = conn.read().unwrap() {
        // validate the response
        println!("Response Body: {}", String::from_utf8_lossy(r.body()));
        break;
    }
}

Re-exports

• pub extern crate http as hyperium_http;
• pub extern crate tcp_stream;

Modules

• frame
  FramingSession will “frame” messages using an underlying binary Session.
• http
  A non-blocking HTTP 1.x client
• mock
  Mock sessions, most useful for testing
• tcp
  This module provides a TCP Session implementation and simple TcpServer.
• util
  Utilities that use or encapsulate a Session

Enums

• ReadStatus
  Returned by the Session read function, providing the outcome or information about the read action.
• WriteStatus
  Returned by the Session write function, providing the outcome of the write action.

Traits

• Session
  A bi-directional connection supporting generic read and write events.
• TlsSession
  Optionally implemented for Session implementations that support TLS