{"id":16915124,"url":"https://github.com/kixunil/io_check","last_synced_at":"2025-04-05T13:26:54.857Z","repository":{"id":50397787,"uuid":"517115707","full_name":"Kixunil/io_check","owner":"Kixunil","description":"A Rust crate for thorough checking of `std::io::Read` and (in the future) `std::io::Write` uses.","archived":false,"fork":false,"pushed_at":"2022-07-30T15:17:59.000Z","size":19,"stargazers_count":0,"open_issues_count":6,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-13T01:36:40.847Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kixunil.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-07-23T17:00:01.000Z","updated_at":"2022-07-28T19:04:51.000Z","dependencies_parsed_at":"2022-09-26T21:31:24.178Z","dependency_job_id":null,"html_url":"https://github.com/Kixunil/io_check","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kixunil%2Fio_check","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kixunil%2Fio_check/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kixunil%2Fio_check/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kixunil%2Fio_check/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kixunil","download_url":"https://codeload.github.com/Kixunil/io_check/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247341321,"owners_count":20923415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T19:17:05.440Z","updated_at":"2025-04-05T13:26:54.428Z","avatar_url":"https://github.com/Kixunil.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IO check\n\nA Rust crate for thorough checking of `std::io::Read` and `std::io::Write` uses.\n\n## About\n\nThe `read` and `write` methods of their respective traits are not guaranteed to use the whole provided buffer.\nA correct application must handle these cases.\nThis is usually achieved using `read_exact` or `write_all` but it is possible that people forget about those\nor have special reasons to avoid them but fail to write the code correctly.\n\nThis crate provides a tool for testing such implementations automatically and even finding the exact location of the call that wasn't properly handled!\n\n## Usage\n\nThe interface is very simple: there are just two functions, one for read testing, the other for write testing.\n`test_read` accepts the bytes that should be returned from `Read` and a closure implementing the test.\nThe closure acepts a reader as an argument and should call your decoding function.\nYou should then compare the decoded value to the expected value and *panic* if they are not equal - just as in tests.\nSimilarly, `test_write` accepts the expected bytes as an argument and a closure implementing the test.\nThe closure accepts a writer has to write data into it.\nThe written data is internally compared to the expected.\n\nIf your code has a bug caused by improper handling of splits this crate will find it and even find the exact incorrectly-handled call.\nFinding the culprit requires `backtrace` feature which is on by default.\n\nKeep 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.\nOnce you fix it you can re-run the test and it will report the next bug.\nRepeat this until you fix all of them.\n\nNote that this crate should be normally used as a dev-dependency only.\n\n## How it works\n\n### Read\n\nThe closure is called first with a reader that returns data byte-by-byte.\nIf there is a bug that causes reliance on `read` reading whole buffer this will trigger it unless the code is very exotic.\nHowever, people usually fill the buffer with zeros first and if the input also contains zeros the bug would not trigger.\nTo avoid this the unused part of the buffer is scrambled such that the data is guaranteed to be invalid.\n\nIf the bug triggers the panic is caught using `catch_unwind` and search is run to find the exact place where it occurs.\nThe closure gets called multiple times with another reader that splits the input in two.\nThe sizes of the two parts change by one on each call.\nOnce a call panics we learn the position in the input where the problem is.\n\nTo find the actual function call the reader captures a backtrace when the `read` call provides a buffer that overlaps the split position.\nThere is only a single `read` call that can trigger this per iteration.\nIf the closure panics the captured backtrace is used in error reporting.\n\n### Write\n\nAs opposed to read, write can detect bugs on-the-fly so it will find the bug and probable location a bit sooner.\nHowever it can report a wrong location, so the plan is to make it more similar to read.\nSee issue [#1](https://github.com/Kixunil/io_check/issues/1) for more information.\n\nOther than that it is very similar - splits writes at each position and if written data don't match it reports an error.\nBacktrace 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.\n\n## MSRV\n\n1.41.1 without `backtrace` feature, 1.48 with `backtrace` feature.\n\n## License\n\nMITNFA\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkixunil%2Fio_check","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkixunil%2Fio_check","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkixunil%2Fio_check/lists"}