{"id":27329570,"url":"https://github.com/sky-big/raft","last_synced_at":"2025-04-12T12:58:49.724Z","repository":{"id":57617947,"uuid":"106680437","full_name":"sky-big/raft","owner":"sky-big","description":"golang for raft","archived":false,"fork":false,"pushed_at":"2017-10-12T10:57:44.000Z","size":51,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-06-20T15:43:04.014Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sky-big.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-12T10:48:33.000Z","updated_at":"2019-10-15T08:25:10.000Z","dependencies_parsed_at":"2022-09-05T21:40:28.013Z","dependency_job_id":null,"html_url":"https://github.com/sky-big/raft","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky-big%2Fraft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky-big%2Fraft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky-big%2Fraft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky-big%2Fraft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sky-big","download_url":"https://codeload.github.com/sky-big/raft/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248571918,"owners_count":21126521,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-12T12:58:49.138Z","updated_at":"2025-04-12T12:58:49.708Z","avatar_url":"https://github.com/sky-big.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"go-raft [![Build Status](https://drone.io/github.com/goraft/raft/status.png)](https://drone.io/github.com/goraft/raft/latest) [![Coverage Status](https://coveralls.io/repos/goraft/raft/badge.png?branch=master)](https://coveralls.io/r/goraft/raft?branch=master)\n=======\n\n## Overview\n\n![unmaintained](http://img.shields.io/badge/status-unmaintained-red.png)\n\n\n**NOTE**: This project is unmaintained. If you are using goraft in a project\nand want to carry the project forward please file an issue with your ideas and\nintentions. The original project authors have created new raft implementations\nnow used in [etcd](https://godoc.org/github.com/coreos/etcd/raft) and [InfluxDB](https://godoc.org/github.com/influxdb/influxdb/raft).\n\nThis is a Go implementation of the Raft distributed consensus protocol.\nRaft is a protocol by which a cluster of nodes can maintain a replicated state machine.\nThe state machine is kept in sync through the use of a replicated log.\n\nFor more details on Raft, you can read [In Search of an Understandable Consensus Algorithm][raft-paper] by Diego Ongaro and John Ousterhout.\n\n## Project Status\n\nThis library is feature complete but should be considered experimental until it has seen more usage.\nIf you have any questions on implementing go-raft in your project please file an issue.\nThere is an [active community][community] of developers who can help.\ngo-raft is under the MIT license.\n\n[community]: https://github.com/goraft/raft/contributors\n\n### Features\n\n- Leader election\n- Log replication\n- Configuration changes\n- Log compaction\n- Unit tests\n- Fast Protobuf Log Encoding\n- HTTP transport\n\n### Projects\n\nThese projects are built on go-raft:\n\n\n- [goraft/raftd](https://github.com/goraft/raftd) - A reference implementation for using the go-raft library for distributed consensus.\n- [Weed File System](https://weed-fs.googlecode.com) - A scalable distributed key-to-file system with O(1) disk access for each read.\n- [rqlite](https://github.com/otoolep/rqlite) - A replicated SQLite database, distributing the database replicas across multiple nodes.\n\nIf you have a project that you're using go-raft in, please add it to this README so others can see implementation examples.\n\n## Contact and Resources\n\n- [raft-dev][raft-dev] is a mailing list for discussion about best practices\n  and implementation of Raft. Not goraft specific but helpful if you have\n  questions.\n- [Slides from Ben's talk][bens-talk] which includes easy to understand\n  diagrams of leader election and replication\n- The [Raft Consensus homepage][raft-home] has links to additional raft\n  implementations, slides to talks on Raft and general information\n\n[raft-home]:  http://raftconsensus.github.io/\n[raft-dev]: https://groups.google.com/forum/#!forum/raft-dev\n[bens-talk]: https://speakerdeck.com/benbjohnson/raft-the-understandable-distributed-consensus-protocol\n\n## The Raft Protocol\n\nThis section provides a summary of the Raft protocol from a high level.\nFor a more detailed explanation on the failover process and election terms please see the full paper describing the protocol: [In Search of an Understandable Consensus Algorithm][raft-paper].\n\n### Overview\n\nMaintaining state in a single process on a single server is easy.\nYour process is a single point of authority so there are no conflicts when reading and writing state.\nEven multi-threaded processes can rely on locks or coroutines to serialize access to the data.\n\nHowever, in a distributed system there is no single point of authority.\nServers can crash or the network between two machines can become unavailable or any number of other problems can occur.\n\nA distributed consensus protocol is used for maintaining a consistent state across multiple servers in a cluster.\nMany distributed systems are built upon the Paxos protocol but Paxos can be difficult to understand and there are many gaps between Paxos and real world implementation.\n\nAn alternative is the [Raft distributed consensus protocol][raft-paper] by Diego Ongaro and John Ousterhout.\nRaft is a protocol built with understandability as a primary tenet and it centers around two things:\n\n1. Leader Election\n2. Replicated Log\n\nWith these two constructs, you can build a system that can maintain state across multiple servers -- even in the event of multiple failures.\n\n### Leader Election\n\nThe Raft protocol effectively works as a master-slave system whereby state changes are written to a single server in the cluster and are distributed out to the rest of the servers in the cluster.\nThis simplifies the protocol since there is only one data authority and conflicts will not have to be resolved.\n\nRaft ensures that there is only one leader at a time.\nIt does this by performing elections among the nodes in the cluster and requiring that a node must receive a majority of the votes in order to become leader.\nFor example, if you have 3 nodes in your cluster then a single node would need 2 votes in order to become the leader.\nFor a 5 node cluster, a server would need 3 votes to become leader.\n\n### Replicated Log\n\nTo maintain state, a log of commands is maintained.\nEach command makes a change to the state of the server and the command is deterministic.\nBy ensuring that this log is replicated identically between all the nodes in the cluster we can replicate the state at any point in time in the log by running each command sequentially.\n\nReplicating the log under normal conditions is done by sending an `AppendEntries` RPC from the leader to each of the other servers in the cluster (called Peers).\nEach peer will append the entries from the leader through a 2-phase commit process which ensure that a majority of servers in the cluster have entries written to log.\n\n\n## Raft in Practice\n\n### Optimal Cluster Size\n\nThe primary consideration when choosing the node count in your Raft cluster is the number of nodes that can simultaneously fail.\nBecause Raft requires a majority of nodes to be available to make progress, the number of node failures the cluster can tolerate is `(n / 2) - 1`.\n\nThis means that a 3-node cluster can tolerate 1 node failure.\nIf 2 nodes fail then the cluster cannot commit entries or elect a new leader so progress stops.\nA 5-node cluster can tolerate 2 node failures. A 9-node cluster can tolerate 4 node failures.\nIt is unlikely that 4 nodes will simultaneously fail so clusters larger than 9 nodes are not common.\n\nAnother consideration is performance.\nThe leader must replicate log entries for each follower node so CPU and networking resources can quickly be bottlenecked under stress in a large cluster.\n\n\n### Scaling Raft\n\nOnce you grow beyond the maximum size of your cluster there are a few options for scaling Raft:\n\n1. *Core nodes with dumb replication.*\n   This option requires you to maintain a small cluster (e.g. 5 nodes) that is involved in the Raft process and then replicate only committed log entries to the remaining nodes in the cluster.\n   This works well if you have reads in your system that can be stale.\n\n2. *Sharding.*\n   This option requires that you segment your data into different clusters.\n   This option works well if you need very strong consistency and therefore need to read and write heavily from the leader.\n\nIf you have a very large cluster that you need to replicate to using Option 1 then you may want to look at performing hierarchical replication so that nodes can better share the load.\n\n\n## History\n\nBen Johnson started this library for use in his behavioral analytics database called [Sky](https://github.com/skydb/sky).\nHe put it under the MIT license in the hopes that it would be useful for other projects too.\n\n[raft-paper]: https://ramcloud.stanford.edu/raft.pdf\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsky-big%2Fraft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsky-big%2Fraft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsky-big%2Fraft/lists"}