Summerset

Summerset is a distributed, replicated, protocol-generic key-value store supporting a wide range of state machine replication (SMR) protocols for research purposes.

List of currently implemented protocols...

Name	Description
RepNothing	Simplest protocol w/o any replication
SimplePush	Pushing to peers w/o consistency guarantees
ChainRep	Bare implementation of Chain Replication (paper)
MultiPaxos	Classic MultiPaxos (paper) w/ modern features
EPaxos	Leaderless-style Egalitarian Paxos (paper)
Raft	Raft with explicit log and strong leadership (paper)
RSPaxos	MultiPaxos w/ RS erasure code sharding (paper)
CRaft	Raft w/ erasure code sharding and fallback (paper)
QuorumLeases	Local reads at leaseholders when quiescent (paper)

Formal TLA+ specification of some protocols are provided in tla+/.

More exciting protocols are actively being added!

Why is Summerset different from other codebases...

• Async Rust: Summerset is written in Rust and demonstrates canonical usage of async programming structures backed by the tokio framework.
• Channel/event-based: Summerset adopts a channel-oriented, event-based system architecture; each replication protocol is basically just a set of event handlers plus a tokio::select! loop. The entire codebase contains 0 explicit usage of Mutex.
• Modularized: Common components of a distributed KV store, e.g. network transport and durable logger, as well as protocol-specific parallelism tasks, are cleanly separated from each other and connected through channels. This extends Go's philosophy of doing "synchronization by (low-cost) communication (of ownership transfers)".
• Protocol-generic: With the above points combined, Summerset is able (and strives) to support a set of different replication protocols in one codebase, with common functionalities abstracted out, leaving each protocol's implementation concise and to-the-point.

These design choices make protocol implementation in Summerset rather straight-forward and understandable, without making a sacrifice on performance.

Comments / issues / PRs are always welcome!

Build

Install the Rust toolchain if haven't. For *nix:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Build everything in debug or release (-r) mode:

cargo build [-r] --workspace [--features ...]

Run all unit tests:

cargo test --workspace

Generate & open documentation for the core library in browser:

cargo doc --open

Usage

Summerset currently assumes a Linux environment and is tested on Ubuntu 24.04.

Launch a Cluster

First, launch the cluster manager oracle (which only serves setup & testing purposes and does not participate in any of the protocol logic):

cargo run [-r] -p summerset_manager -- -h

Then, launch server replica executables:

cargo run [-r] -p summerset_server -- -h

The default logging level is set as >= info. To display debugging or even tracing logs, set the RUST_LOG environment variable to debug or trace, e.g.:

RUST_LOG=debug cargo run ...

Run Client Endpoints

To run a client endpoint executable:

cargo run [-r] -p summerset_client -- -h

Currently supported client utility modes include: repl for an interactive CLI, bench for performance benchmarking, and tester for correctness testing.

Helper Scripts

Some helper scripts for running Summerset processes are provided. First, install dependencies:

pip3 install toml

You can find the scripts for running Summerset processes locally in scripts/:

python3 scripts/local_cluster.py -h
python3 scripts/local_clients.py -h

And for a set of distributed machines (requiring correctly filled scripts/remote_hosts.toml file):

python3 scripts/distr_cluster.py -h
python3 scripts/distr_clients.py -h

Note that these scripts use sudo and assume specific ranges of available ports, so a Linux server machine environment is recommended.

---

Lore: Summerset Isles is the name of an elvish archipelagic province in the Elder Scrolls series.