https://github.com/penberg/vsr-rs
Viewstamped Replication for Rust
https://github.com/penberg/vsr-rs
consensus distributed-systems rust viewstamped-replication
Last synced: about 1 year ago
JSON representation
Viewstamped Replication for Rust
- Host: GitHub
- URL: https://github.com/penberg/vsr-rs
- Owner: penberg
- License: mit
- Created: 2022-10-28T07:33:45.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-05-06T09:07:23.000Z (about 3 years ago)
- Last Synced: 2025-03-18T09:21:47.981Z (about 1 year ago)
- Topics: consensus, distributed-systems, rust, viewstamped-replication
- Language: Rust
- Homepage:
- Size: 72.3 KB
- Stars: 67
- Watchers: 5
- Forks: 5
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Viewstamped Replication for Rust
This is a _work-in-progress_ Rust implementation of the Viewstamped Replication consensus algorithm.
## Getting Started
Run the example:
```console
cargo run --example example
```
To see some debug traces, use `RUST_LOG` environment variable:
```console
RUST_LOG=trace cargo run --example example
```
## ToDo
* [x] Normal operation
* [x] State transfer
* [x] Deterministic simulator
* [ ] View changes
* [ ] Failed replica recovery
* [ ] Reconfiguration
## Testing
You can run the tests with:
```console
cargo test -- --nocapture
```
The run will print out a *seed* value such as:
```console
Seed: 10693013600028533629
```
If the simulation triggers a problem, you can reproduce the exact same run by passing a seed to the simulator:
```console
SEED=10693013600028533629 cargo test -- --nocapture
```
You can also increase logging level to see more output of the run with:
```console
RUST_LOG=debug cargo test
```
You can get a test coverage report with:
```console
cargo tarpaulin -o html
```
## References
The implementation of `vsr-rs` is based on the paper [Viewstamped Replication Revisited](https://pmg.csail.mit.edu/papers/vr-revisited.pdf) by Liskov and Cowling.
However, the algorithm in the paper has the following known bugs:
* The recovery algorithm described in Section 4.3 can result in the system being in an inconsistent state as reported by Michael et al in Appendix B1 of [Recovering Shared Objects Without Stable Storage](https://drkp.net/papers/recovery-tr17.pdf)
* The state transfer algorithm described in Section 5.2 can cause data loss as discovered by Jack Vanlightly in https://twitter.com/vanlightly/status/1596190819421413377 and https://twitter.com/vanlightly/status/1596425599026970624.
The `vsr-rs` library does not yet implement recovery or view changes so the bugs are not addressed.
For more information on VSR, please also check out the following presentations and blog posts:
* [Paper: VR Revisited - An analysis with TLA+](https://jack-vanlightly.com/analyses/2022/12/20/vr-revisited-an-analysis-with-tlaplus)
* [Reading Group: Viewstamped Replication Revisited](http://charap.co/reading-group-viewstamped-replication-revisited/)
* [Viewstamped Replication explained](https://blog.brunobonacci.com/2018/07/15/viewstamped-replication-explained/)