Expand description
Openraft
§API status
Openraft API is currently unstable.
Incompatibilities may arise in upgrades prior to 1.0.0.
Refer to our Change-Log for details.
Upgrade Guides explains how to upgrade.
Each commit message begins with a keyword indicating the type of change:
DataChange:Changes to on-disk data types, possibly requiring manual upgrade.Change:Introduces incompatible API changes.Feature:Adds compatible, non-breaking new features.Fix:Addresses bug fixes.
§Feature flags
Openraft supports several feature flags to customize functionality:
Default features: tokio-rt
Runtime:
tokio-rt- Enable Tokio async runtime support (default)single-threaded- Disallow sharing Raft instance across threads
Serialization:
serde- Addserde::Serializeandserde::Deserializebounds to data types
Error handling:
bt- Enable error backtraces (requires nightly Rust)
Development:
bench- Enable benchmarks in unit tests (requiresRUSTC_BOOTSTRAP=1with stable Rust)
Compatibility:
compat- Provide basic compatible types for upgradestype-alias- Enableopenraft::alias::*type shortcuts (unstable)
§Openraft Document
If you’re starting to build an application with Openraft, check out
For an overview of Openraft’s capabilities and their APIs, see
To maintain an Openraft cluster, e.g., add or remove nodes, refer to
cluster_control:cluster_formationdescribes how to form a cluster;dynamic membershipdescribes how to add or remove nodes without downtime;joint_consensusdescribes detail of joint consensus implementation;threshold_membershipexplains how to choose the write quorum size ofThresholdMembership;weighted_membershipexplains how to choose the voter weights ofWeightedMembership;hierarchical_membershipexplains how to choose the groups and write thresholds ofHierarchicalMembership;grid_membershipexplains how to choose the voter grid ofGridMembership;explicit_membershipexplains how to list the quorums ofExplicitMembership;node lifecycledescribes the transition of a node’s state;
When upgrading an Openraft application, consult:
To learn about the data structures used in Openraft and the commit protocol, see
feature_flags;data:Voteis the core in a distributed system;Log pointersshows how Openraft tracks entries in the log;IOIdexplains the I/O operation identifier for both vote and log operations;LogIOIdexplains the monotonic I/O operation identifier for log entries;Log I/O Progressexplains how Openraft tracks log I/O operations through three stages;Leader leaseexplains leader lease for a Leader and a Follower;Extended membershipexplains how members are organized in Openraft;Effective membershipexplains when membership config takes effect;
componentsexplains the components in Openraft;RaftStateMachineis the core API for managing the state machine and snapshot functionalities;
protocol:check_quorumexplains how a leader stops accepting new proposals when its quorum lease expires;election_quorumexplains which quorums elect a candidate in each leader ID mode;io_orderingexplains why IO re-ordering is disallowed;readexplains how to do linearizable read;replication;leader_leaseoutlines the leader validity criteria for Leaders and Followers;log_replicationprovides an overview of the general replication protocol;log_streamdiscusses the core aspects of streaming log replication;snapshot_replication;
Contributors who want to understand the internals of Openraft can find relevant information in
internal:- Architecture shows the overall architecture of Openraft;
- Threading describes the threading model of Openraft;
Finally, the archived and discarded documents:
obsoletedescribes obsolete design documents and why they are discarded;
Re-exports§
pub extern crate openraft_macros as macros;pub extern crate openraft_macros;pub extern crate openraft_rt as rt;
Re-exports§
pub use errors as error;pub use type_config::async_runtime;pub use self::storage::LogState;pub use self::storage::RaftLogReader;pub use self::storage::RaftSnapshotBuilder;pub use self::storage::Snapshot;pub use self::storage::SnapshotMeta;pub use self::storage::StorageHelper;pub use crate::base::OptionalSerde;pub use crate::entry::Entry;pub use crate::entry::EntryPayload;pub use crate::log_id::LogId;pub use crate::log_id::LogIdOptionExt;pub use crate::log_id::LogIndexOptionExt;pub use crate::membership::Membership;pub use crate::membership::StoredMembership;pub use crate::metrics::RaftMetrics;pub use crate::network::RPCTypes;pub use crate::network::RaftNetwork;Deprecated pub use crate::network::RaftNetworkFactory;pub use crate::network::RaftNetworkV2;pub use crate::raft::Precondition;pub use crate::raft::Raft;pub use crate::raft::ReadPolicy;pub use crate::raft::WatchChangeHandle;pub use crate::raft::linearizable_read::LinearizerOption;pub use crate::type_config::RaftTypeConfig;pub use crate::vote::Vote;pub use anyerror;
Modules§
- base
- Basic types and traits with optional feature support.
- batch
- A container that stores elements efficiently by avoiding heap allocation for single elements.
- compat
- This mod is an upgrade helper that provides functionalities for a newer openraft application to read data written by an older application.
- docs
- Openraft Document
- entry
- Log entry types and traits.
- errors
- Error types exposed by this crate.
- impls
- Default implementations for common Openraft traits.
- log_id
- Log identification and comparison.
- membership
- Cluster membership configuration and management.
- metrics
- Raft metrics for observability.
- network
- The Raft network interface.
- raft
- Public Raft interface and data types.
- storage
- The Raft storage interface and data types.
- testing
- Testing utilities for Openraft applications.
- type_
config - Define the configuration of types used by the Raft, such as
NodeId, logEntry, etc. - vote
- Election and voting types.
Macros§
- declare_
raft_ types - Define types for a Raft type configuration.
Structs§
- AnyError
- AnyError is a serializable wrapper
Error. - Basic
Node - An implementation of the
Nodetrait that contains minimal node information. - Config
- Runtime configuration for a Raft node.
- Empty
Node - EmptyNode is an implementation of the
Nodetrait that contains nothing. - Extensions
- A type-map for storing user-defined extension data.
- Membership
State - The state of membership configs a raft node needs to know.
- Node
Info - An implementation of the
Nodetrait that contains a Raft address and user-defined data. - Raft
State - A struct used to represent the raft state which a Raft node needs.
- Snapshot
Segment Id Deprecated - REMOVED: Use
openraft_legacy::network_v1::SnapshotSegmentIdinstead. - Storage
Error - Error that occurs when operating the store.
- Tokio
Instant - Tokio
Runtime Tokiois the default asynchronous executor.
Enums§
- Change
Members - Defines various actions to change the membership, including adding or removing learners or voters.
- Config
Error - Error variants related to configuration.
- Error
Subject - The subject of a storage error, indicating what operation or component failed.
- Error
Verb - What it is doing when an error occurs.
- Server
State - All possible states of a Raft node.
- Snapshot
Policy - Log compaction and snapshot policy.
- Step
Down Policy - Policy for stepping down a Leader that is removed from a committed membership config.
Traits§
- AppData
- A trait defining application-specific data.
- AppData
Response - A trait defining application-specific response data.
- Async
Runtime - A trait defining interfaces with an asynchronous runtime.
- Instant
- A measurement of a monotonically non-decreasing clock.
- Message
Summary - Convert a type
Tto string. - Node
- A Raft
Node, this trait holds all relevant node information. - NodeId
- A Raft node’s ID.
- Optional
Send - A trait that is empty if the
single-threadedfeature flag is enabled, otherwise it extendsSend. - Optional
Sync - A trait that is empty if the
single-threadedfeature flag is enabled, otherwise it extendsSync. - ToStorage
Result - Convert error to StorageError::IO();
- TryAs
Ref - Similar to
AsRef<T>, it does a cheap reference-to-reference conversion, but with the ability to returnNoneif it is unable to perform the conversion to&T. - Watch
Sender - Sends values to the associated Receiver.
Type Aliases§
- Snapshot
Id - Id of a snapshot stream.
- StorageIO
Error Deprecated - Backward compatible with old application using
StorageIOError
Attribute Macros§
- add_
async_ trait - This proc macro attribute optionally adds
Sendbounds to a trait.