diff --git a/README.md b/README.md index faeedaaf27af166e56eb1dc45065ff8cc0678450..67db169fe84a5aed8ee8c8826003da9e6ea7a4d4 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,48 @@ -# Rafty -Please note rafty is experimental -Rafty is an implementation of the Raft concensus algorythm [see here](https://raft.github.io/) created using C# and .NET core. Rafty is the algorythm only and does not provide useful implementation of the transport between nodes, the state machine or log. Instead Rafty provides interfaces that you will need to implement. I reccomend at least 5 nodes in your cluster for Rafty to operate optimally and this is basically all I've tested.... +Rafty 是一个 Raft 共识算法的实现,旨在提供一个简单易用的分布式一致性协议库。该项目适用于希望在分布式系统中实现高效可靠数据同步与领导选举的开发者。 -Rafty was built to allow Ocelot (another project of mine) to run in a cluster without a database or relying on another piece of software to persist state. This will also allow me to turn Ocelot into a service discovery provider and key value store so its pretty nice....if it works! +## 安装 -## Install +要使用 Rafty,您需要将其集成到您的项目中。可以通过以下步骤进行安装: -Bring the rafty package into your project using nuget. +1. 克隆仓库到本地。 +2. 在您的项目中引用 Rafty 项目。 +3. 构建 Rafty 项目以生成所需的依赖项。 -```Install-Package Rafty``` +## 接口和组件 -This will make all the raft code available to you! +Rafty 项目包含多个关键接口和类,这些是构建和使用 Raft 共识算法的基础: -## ILog +- **ILog**: 提供日志存储的接口。 +- **IFiniteStateMachine**: 定义状态机的行为。 +- **IPeer**: 代表集群中的节点,用于节点之间的通信。 +- **IPeersProvider**: 提供获取集群节点列表的功能。 +- **ISettings**: 配置 Raft 实现的设置,例如超时时间。 +- **IState**: 代表节点可能处于的三种状态之一:Follower、Candidate 或 Leader。 -You must implement ILog which provides a description of each member in the summary comments of the interface. This log implementation should be persistant and not shared between nodes. +## 启动 -## IFiniteStateMachine +为了启动一个 Rafty 节点,您需要提供一个 `NodeId`、`ILog`、`IFiniteStateMachine`、`ISettings`、`IPeersProvider` 和 `ILoggerFactory`。节点启动后,它将根据 Raft 箝议的规则自动管理状态转换。 -You must implement IFiniteStateMachine which provides a description of each member in the summary comments of the interface. This just takes a command of T and you execute it! Pretty simple. +## 进一步帮助 -## IPeer +如需进一步帮助,您可以查阅项目中的单元测试和集成测试以获得实际使用案例。接受测试的类和方法可以帮助您理解如何使用 Rafty 的各种组件。 -You must implement IPeer which provides a description of each member in the summary comments of the interface. This encapsulates the transport logic to each node in the cluster. +## 未来 -## IPeersProvider +Rafty 项目仍处于持续开发和测试中。未来可能会增加更多特性,如持久化日志、更复杂的配置选项、以及网络通信的改进。 -You must implement IPeersProvider which provides a description of each member in the summary comments of the interface. This should return all available nodes in the cluster as peers. +如您有任何问题或需要帮助,请提交 issue 或联系项目维护者。 -## ISettings +## 贡献 -You must implement ISettings which provides a description of each member in the summary comments of the interface. Holds some basic settings information that you might want to tweak such as timeout. +我们鼓励开源社区的贡献。如果您发现任何错误或有改进的想法,请提交 pull request 或打开 issue 进行讨论。 -## Startup +## 许可证 -Rafty provides some in memory implementations of its interfaces (you shouldn't use these for anything serious). +Rafty 项目使用 MIT 许可证。确保在使用本项目代码时,您遵守许可证的条款和条件。 -```csharp +## 致谢 - var log = new InMemoryLog(); - var fsm = new InMemoryStateMachine(); - var settings = new InMemorySettings(1000, 3500, 50, 5000); - var peersProvider = new InMemoryPeersProvider(_peers); - var node = new Node(fsm, log, settings, peersProvider); - node.Start(); - -``` - -The above code will get a Rafty node up and running. If the IPeersProvider does not return any IPeers then it will elect itself leader and just run along happily. If something joins the cluster later it will update that new node as the node will get a heartbeat before it can elect itself. Or an election will start! - -So in order to get Rafty really running the IPeerProvider needs to return peers. The easiest way to do this is just provide a HTTP transport version of IPeer. The host and port of these peers is known to each node and you just push them into memory and return them. The request will then flow through the IPeer interfaces from the nodes! - -Finally you need to expose the INode interface to some kind of HTTP. I would advise just a plain old .net core web api type thing. These are the methods you need to expose and the transport in your IPeer should hit these URLS (hope that makes some sense). You can look at NodePeer to see how I do this in memory. - -```csharp - -Task Request(AppendEntries appendEntries); -Task Request(RequestVote requestVote); -Task> Request(T command); - -``` - -## Further help - -The Acceptance and Integration tests will be helpful for anyone who wants to use Rafty. - -## Future - -I will provide some half decent implementations of these interfaces so you don't have to. +感谢所有为 Rafty 项目做出贡献的开发者和测试人员。没有开源社区的协助,这个项目不可能实现。 \ No newline at end of file