io_check/
lib.rs

1#![doc = "
2## About
3
4The `read` and `write` methods of their respective traits are not guaranteed to use the whole provided buffer.
5A correct application must handle these cases.
6This is usually achieved using `read_exact` or `write_all` but it is possible that people forget about those
7or have special reasons to avoid them but fail to write the code correctly.
8
9This crate provides a tool for testing such implementations automatically and even finding the exact location of the call that wasn't properly handled!
10
11## Usage
12
13The interface is very simple: there are just two functions, one for read testing, the other for write testing.
14`test_read` accepts the bytes that should be returned from `Read` and a closure implementing the test.
15The closure acepts a reader as an argument and should call your decoding function.
16You should then compare the decoded value to the expected value and *panic* if they are not equal - just as in tests.
17Similarly, `test_write` accepts the expected bytes as an argument and a closure implementing the test.
18The closure accepts a writer has to write data into it.
19The written data is internally compared to the expected.
20
21If your code has a bug caused by improper handling of splits this crate will find it and even find the exact incorrectly-handled call.
22Finding the culprit requires `backtrace` feature which is on by default.
23
24Keep 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.
25Once you fix it you can re-run the test and it will report the next bug.
26Repeat this until you fix all of them.
27
28Note that this crate should be normally used as a dev-dependency only.
29
30## How it works
31
32### Read
33
34The closure is called first with a reader that returns data byte-by-byte.
35If there is a bug that causes reliance on `read` reading whole buffer this will trigger it unless the code is very exotic.
36However, people usually fill the buffer with zeros first and if the input also contains zeros the bug would not trigger.
37To avoid this the unused part of the buffer is scrambled such that the data is guaranteed to be invalid.
38
39If the bug triggers the panic is caught using `catch_unwind` and search is run to find the exact place where it occurs.
40The closure gets called multiple times with another reader that splits the input in two.
41The sizes of the two parts change by one on each call.
42Once a call panics we learn the position in the input where the problem is.
43
44To find the actual function call the reader captures a backtrace when the `read` call provides a buffer that overlaps the split position.
45There is only a single `read` call that can trigger this per iteration.
46If the closure panics the captured backtrace is used in error reporting.
47
48### Write
49
50As opposed to read, write can detect bugs on-the-fly so it will find the bug and probable location a bit sooner.
51However it can report a wrong location, so the plan is to make it more similar to read.
52See issue [#1](https://github.com/Kixunil/io_check/issues/1) for more information.
53
54Other than that it is very similar - splits writes at each position and if written data don't match it reports an error.
55Backtrace 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.
56
57## MSRV
58
591.41.1 without `backtrace` feature, 1.48 with `backtrace` feature.
60
61## License
62
63MITNFA
64"]
65
66pub use read::hack::test_read;
67pub use write::hack::test_write;
68
69pub mod read;
70pub mod write;
71mod backtrace_impl;
io_check/lib.rs

io_check/
lib.rs
