io_check 0.1.2

Tool for testing read and write split handling.
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

#![doc = "
## About

The `read` and `write` methods of their respective traits are not guaranteed to use the whole provided buffer.
A correct application must handle these cases.
This is usually achieved using `read_exact` or `write_all` but it is possible that people forget about those
or have special reasons to avoid them but fail to write the code correctly.

This crate provides a tool for testing such implementations automatically and even finding the exact location of the call that wasn't properly handled!

## Usage

The interface is very simple: there are just two functions, one for read testing, the other for write testing.
`test_read` accepts the bytes that should be returned from `Read` and a closure implementing the test.
The closure acepts a reader as an argument and should call your decoding function.
You should then compare the decoded value to the expected value and *panic* if they are not equal - just as in tests.
Similarly, `test_write` accepts the expected bytes as an argument and a closure implementing the test.
The closure accepts a writer has to write data into it.
The written data is internally compared to the expected.

If your code has a bug caused by improper handling of splits this crate will find it and even find the exact incorrectly-handled call.
Finding the culprit requires `backtrace` feature which is on by default.

Keep in mind that if there are multiple such bugs the crate only finds one at a time - the one corresponding to the leftmost part of the input.
Once you fix it you can re-run the test and it will report the next bug.
Repeat this until you fix all of them.

Note that this crate should be normally used as a dev-dependency only.

## How it works

### Read

The closure is called first with a reader that returns data byte-by-byte.
If there is a bug that causes reliance on `read` reading whole buffer this will trigger it unless the code is very exotic.
However, people usually fill the buffer with zeros first and if the input also contains zeros the bug would not trigger.
To avoid this the unused part of the buffer is scrambled such that the data is guaranteed to be invalid.

If the bug triggers the panic is caught using `catch_unwind` and search is run to find the exact place where it occurs.
The closure gets called multiple times with another reader that splits the input in two.
The sizes of the two parts change by one on each call.
Once a call panics we learn the position in the input where the problem is.

To find the actual function call the reader captures a backtrace when the `read` call provides a buffer that overlaps the split position.
There is only a single `read` call that can trigger this per iteration.
If the closure panics the captured backtrace is used in error reporting.

### Write

As opposed to read, write can detect bugs on-the-fly so it will find the bug and probable location a bit sooner.
However it can report a wrong location, so the plan is to make it more similar to read.
See issue [#1](https://github.com/Kixunil/io_check/issues/1) for more information.

Other than that it is very similar - splits writes at each position and if written data don't match it reports an error.
Backtrace capturing is similar as well - the last call is captured and if the current call writes unexpected data last one is reported as likely culprit.

## MSRV

1.41.1 without `backtrace` feature, 1.48 with `backtrace` feature.

## License

MITNFA
"]

pub use read::hack::test_read;
pub use write::hack::test_write;

pub mod read;
pub mod write;
mod backtrace_impl;