{"id":13672601,"url":"https://github.com/nwtnni/paxos","last_synced_at":"2026-03-17T21:42:25.407Z","repository":{"id":67137102,"uuid":"160851420","full_name":"nwtnni/paxos","owner":"nwtnni","description":"Distributed consensus protocol for replicated state machines","archived":false,"fork":false,"pushed_at":"2019-01-05T21:14:15.000Z","size":192,"stargazers_count":60,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-11T10:42:36.475Z","etag":null,"topics":["distributed-systems","paxos","replicated-state-machine","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nwtnni.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-12-07T16:52:50.000Z","updated_at":"2024-08-25T08:15:25.000Z","dependencies_parsed_at":"2023-06-09T22:15:07.047Z","dependency_job_id":null,"html_url":"https://github.com/nwtnni/paxos","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/nwtnni%2Fpaxos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nwtnni%2Fpaxos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nwtnni%2Fpaxos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nwtnni%2Fpaxos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nwtnni","download_url":"https://codeload.github.com/nwtnni/paxos/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251219601,"owners_count":21554444,"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":["distributed-systems","paxos","replicated-state-machine","rust"],"created_at":"2024-08-02T09:01:41.131Z","updated_at":"2026-03-17T21:42:25.333Z","avatar_url":"https://github.com/nwtnni.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# paxos\n\n[Paxos][1] is a fault-tolerant distributed consensus algorithm. It guarantees safety and liveness\nin asynchronous settings with less than `n / 2` crash failures, where `n` is the number of processes.\n\nThis library uses Paxos to implement a generic replicated state machine (also known as Multi-Paxos).\nAssuming all commands are executed deterministically, replicas that execute \nthem in the same order will arrive at the same final state. Command logs and \nother data are serialized to disk as `*.paxos` files for failure recovery, and \nneed to be deleted between fresh runs.\n\n## Overview\n\nThis repository contains the following:\n\n- A library implementation of Paxos (based on the paper [\"Paxos Made Moderately Complex\"][2]) in `paxos`.\n- An example replicated state machine in `chatroom`.\n- A test harness for `chatroom` in `harness`.\n- A test suite in `tests`\n\n**Note:** this project was partially written to test out Rust's new async/await features,\nand therefore requires Rust Nightly for now. You can override your default compiler for this\nrepository using the following command:\n\n```\n\u003e rustup override set nightly-2018-12-24\n```\n\n## Running Tests\n\nFor more information about the test harness binary, you can run:\n\n```\n\u003e cargo run --bin harness -- --help\n```\n\nExample usage for running the `basic.json` test:\n\n```\n\u003e cargo build\n\u003e cargo run --bin harness -- --server target/debug/chatroom-server --file tests/basic.json\n```\n\nThe test suite covers some basic failure modes and higher throughput concurrent\nwrites--it's definitely not comprehensive though.\n\n## Launching Chatroom\n\nFor help launching a chatroom server, you can run:\n\n```\n\u003e cargo run --bin chatroom-server -- --help\n```\n\nFor example, you can start a cluster of three servers running in the background locally with:\n\n```\n\u003e cargo run --bin chatroom-server -- --count 3 --id 0 --port 10000\n\u003e cargo run --bin chatroom-server -- --count 3 --id 1 --port 10001\n\u003e cargo run --bin chatroom-server -- --count 3 --id 2 --port 10002\n```\n\nFor help launching a chatroom client, you can run:\n\n```\n\u003e cargo run --bin chatroom-client -- --help\n```\n\nFor example, you can start a single client with:\n\n```\n\u003e cargo run --bin chatroom-client -- --id 0\n```\n\nLogging is configurable on a per-server basis by passing `-v` flags to the\n`chatroom-server` binary, if you want to see the messages being passed around\nduring the execution of the protocol.\n\n## Using Library\n\nTo set up a replicated state machine, you have to implement the following traits:\n\n```rust\n/// Unique identifier\npub trait Identifier: std::hash::Hash\n    + std::fmt::Debug\n    + Clone\n    + Eq\n    + Send\n    + Sync\n{\n}\n\n/// Operation that can be applied to a state machine\npub trait Command: Send\n    + Clone\n    + std::fmt::Debug\n    + serde::Serialize\n    + serde::de::DeserializeOwned\n{\n    type ClientID: Identifier;\n    type LocalID: Identifier;\n    fn client_id(\u0026self) -\u003e Self::ClientID;\n    fn local_id(\u0026self) -\u003e Self::LocalID;\n}\n\n/// Result of applying an operation to a state machine\npub trait Response: Send\n    + std::fmt::Debug\n    + serde::Serialize\n{\n}\n\n/// Replicated state machine\npub trait State: Default + Send + 'static {\n    type Command: Command;\n    type Response: Response;\n    fn execute(\u0026mut self, slot: usize, command: Self::Command) -\u003e Option\u003cSelf::Response\u003e;\n}\n```\n\nFrom there, you can create an instance of `Config` with the appropriate\nparameters and types:\n\n```rust\n/// Defines a single Paxos server with state type `S`.\n#[derive(Copy, Clone, Debug)]\npub struct Config\u003cS\u003e {\n    /// Unique replica ID\n    id: usize,\n\n    /// Port for incoming client requests\n    port: usize,\n\n    /// Total number of replicas\n    count: usize,\n\n    /// Timeout for detecting unresponsive servers\n    timeout: std::time::Duration,\n\n    _marker: std::marker::PhantomData\u003cS\u003e,\n}\n```\n\nFinally, you can launch your server using the `tokio::run_async` or `tokio::spawn_async`.\nFor example:\n\n```rust\nmod state;\n\nfn main() {\n  let config = Config::\u003cstate::State\u003e::new(0, 10000, 1);\n  tokio::run_async(config.run())\n}\n```\n\nTake a look at the `chatroom` sub-crate for an example of how to launch and communicate\nwith servers.\n\n## References\n\n1. Lamport, Leslie (1998). [\"The Part-Time Parliament\"][3]\n2. Lamport, Leslie (2001). [\"Paxos Made Simple\"][4]\n3. Renesse, Robbert Van and Altinbuken, Deniz (2015). [\"Paxos Made Moderately Complex\"][2].\n\n[1]: https://en.wikipedia.org/wiki/Paxos_(computer_science)\n[2]: http://paxos.systems/index.html\n[3]: https://lamport.azurewebsites.net/pubs/lamport-paxos.pdf\n[4]: https://lamport.azurewebsites.net/pubs/paxos-simple.pdf\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnwtnni%2Fpaxos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnwtnni%2Fpaxos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnwtnni%2Fpaxos/lists"}