skiff_rs/
lib.rs

1//! # skiff
2//!
3//! An embedded [Raft](https://raft.github.io/) consensus library backed by
4//! [sled](https://docs.rs/sled).  Skiff lets you embed a replicated key-value
5//! store directly in your application without running a separate consensus
6//! service.
7//!
8//! ## Architecture
9//!
10//! Each participating process runs a [`Skiff`] node.  Nodes elect a leader
11//! among themselves using the Raft protocol.  All writes are routed to the
12//! leader, replicated to a majority of followers, and only acknowledged once
13//! they are durably committed.  Followers automatically forward client
14//! requests to the current leader, so callers can connect to any node.
15//!
16//! Persistent state (Raft hard state, the log, and applied key-value data) is
17//! stored in a [sled](https://docs.rs/sled) embedded database.  A node that
18//! restarts will recover its identity and log from disk and re-join the
19//! cluster without any manual intervention.
20//!
21//! ## Quick start
22//!
23//! ```no_run
24//! use std::net::Ipv4Addr;
25//! use skiff_rs::{Builder, Client};
26//!
27//! #[tokio::main]
28//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
29//!     // Build and start a single-node cluster.
30//!     let node = Builder::new()
31//!         .set_dir("/tmp/my-skiff-node")
32//!         .bind("127.0.0.1".parse()?)
33//!         .build()?;
34//!
35//!     let node_ref = node.clone();
36//!     tokio::spawn(async move { node_ref.start().await });
37//!
38//!     // Block until a leader is elected before connecting a client.
39//!     node.wait_for_leader(std::time::Duration::from_secs(2)).await?;
40//!
41//!     // Connect a client and perform some operations.
42//!     let mut client = Client::new(vec!["127.0.0.1".parse()?]);
43//!     client.connect().await?;
44//!
45//!     client.insert("greeting", "hello world").await?;
46//!     let value: Option<String> = client.get("greeting").await?;
47//!     println!("{:?}", value);
48//!
49//!     Ok(())
50//! }
51//! ```
52//!
53//! ## Multi-node cluster
54//!
55//! Pass the addresses of existing cluster members to [`Builder::join_cluster`]
56//! when constructing additional nodes.  The new node will contact one of its
57//! peers and register itself via the Raft `add_server` RPC.
58//!
59//! ```no_run
60//! use skiff_rs::Builder;
61//!
62//! # #[tokio::main]
63//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
64//! // Node 1 – sole member of a brand-new cluster.
65//! let node1 = Builder::new()
66//!     .set_dir("/tmp/node1")
67//!     .bind("127.0.0.1".parse()?)
68//!     .build()?;
69//!
70//! // Node 2 – joins the cluster seeded by node 1.
71//! let node2 = Builder::new()
72//!     .set_dir("/tmp/node2")
73//!     .bind("127.0.0.2".parse()?)
74//!     .join_cluster(vec!["127.0.0.1".parse()?])
75//!     .build()?;
76//! # Ok(())
77//! # }
78//! ```
79
80mod builder;
81mod client;
82mod error;
83mod skiff;
84mod subscriber;
85
86pub use builder::Builder;
87pub use client::Client;
88pub use error::Error;
89pub use skiff::{ElectionState, Skiff};
90pub use subscriber::Subscriber;
skiff_rs/lib.rs

skiff_rs/
lib.rs
