Railyard

Railyard is an implementation of the Raft concensus algorithm using the Tonic gRPC framework. This project aims to provide a reusable foundation for building distributed systems that require high availability and fault tolerance.

⚠️ Warning: Experimental ⚠️

Railyard is currently in early development. It should not be used in production systems as it has not been tested and may still undergo significant changes and improvements.

Getting Started

To incorporate Railyard into your project, add it as a dependency in your Cargo.toml:

[dependencies]
railyard = "0.1.0"

Initialize and run a Railyard cluster by including it in your Rust application:

use railyard::Railyard;

#[tokio::main]
async fn main() {
    let my_cluster = Railyard::new_server("node_id", vec!["peer1:port", "peer2:port"]).await;
    my_cluster.run().await;
}

For detailed examples and usage, see the examples directory and refer to the API documentation.

Running Examples

Cargo Run

To run the server example locally, set the port and at least 2 other peers:

cd examples/server
cargo run -- -p 8001 --peer 127.0.0.1:8002 --peer 127.0.0.1:8002 --peer 127.0.0.1:8003 &
cargo run -- -p 8002 --peer 127.0.0.1:8002 --peer 127.0.0.1:8001 --peer 127.0.0.1:8003 &
cargo run -- -p 8003 --peer 127.0.0.1:8002 --peer 127.0.0.1:8001 --peer 127.0.0.1:8002 &

To aid in spinning up a cluster, the examples/server directory contains a start_cluster.sh script that will start a cluster with 3 nodes:

./examples/server/start_cluster.sh

Docker Compose

To run the server using Docker Compose:

docker-compose up

This will startup a cluster with 3 nodes by default and automatically configure the peers to listen on port 8000.

Testing

Once the cluster is running the API can be tested with grpcurl:

grpcurl -plaintext -import-path ./proto -proto cluster_management.proto -d '{"entries": ["test"]}' '[::1]:8001' railyard.ClusterManagement/AppendEntries

Resources

• Raft Paper
• Tonic Framework

License

This project is licensed under the MIT license.