partial-io

Helpers for testing I/O behavior with partial, interrupted and blocking reads and writes.

This library provides:

PartialRead and PartialWrite, which wrap existing Read and Write implementations and allow specifying arbitrary behavior on the next read, write or flush call.
With the optional futures03 and tokio1 features, PartialAsyncRead and PartialAsyncWrite to wrap existing AsyncRead and AsyncWrite implementations. These implementations are task-aware, so they will know how to pause and unpause tasks if they return a WouldBlock error.
With the optional proptest1 (proptest) and quickcheck1 (quickcheck) features, generation of random sequences of operations for property-based testing. See the proptest_types and quickcheck_types documentation for more.

Motivation

A Read or Write wrapper is conceptually simple but can be difficult to get right, especially if the wrapper has an internal buffer. Common issues include:

A partial read or write, even without an error, might leave the wrapper in an invalid state (example fix).

With the AsyncRead and AsyncWrite provided by futures03 and tokio1:

A call to read_to_end or write_all within the wrapper might be partly successful but then error out. These functions will return the error without informing the caller of how much was read or written. Wrappers with an internal buffer will want to advance their state corresponding to the partial success, so they can't use read_to_end or write_all (example fix).
Instances must propagate Poll::Pending up, but that shouldn't leave them in an invalid state.

These situations can be hard to think about and hard to test.

partial-io can help in two ways:

For a known bug involving any of these situations, partial-io can help you write a test.
With the quickcheck1 feature enabled, partial-io can also help shake out bugs in your wrapper. See quickcheck_types for more.

Examples

use std::io::{self, Cursor, Read};

use partial_io::{PartialOp, PartialRead};

let data = b"Hello, world!".to_vec();
let cursor = Cursor::new(data);  // Cursor<Vec<u8>> implements io::Read
let ops = vec![PartialOp::Limited(7), PartialOp::Err(io::ErrorKind::Interrupted)];
let mut partial_read = PartialRead::new(cursor, ops);

let mut out = vec![0; 256];

// The first read will read 7 bytes.
assert_eq!(partial_read.read(&mut out).unwrap(), 7);
assert_eq!(&out[..7], b"Hello, ");
// The second read will fail with ErrorKind::Interrupted.
assert_eq!(partial_read.read(&mut out[7..]).unwrap_err().kind(), io::ErrorKind::Interrupted);
// The iterator has run out of operations, so it no longer truncates reads.
assert_eq!(partial_read.read(&mut out[7..]).unwrap(), 6);
assert_eq!(&out[..13], b"Hello, world!");

For a real-world example, see the tests in zstd-rs.

Minimum supported Rust version

The minimum supported Rust version (MSRV) is 1.56.

While a crate is pre-release status (0.x.x) it may have its MSRV bumped in a patch release. Once a crate has reached 1.x, any MSRV bump will be accompanied with a new minor version.

Contributing

See the CONTRIBUTING file for how to help out.

License

This project is available under the MIT license.

sunshowers-code / partial-io