{"id":19224684,"url":"https://github.com/khanh1998/raft-go","last_synced_at":"2026-04-22T23:35:16.612Z","repository":{"id":179904939,"uuid":"664302669","full_name":"khanh1998/raft-go","owner":"khanh1998","description":"a simple distributed key-value database, built on top of Raft consensus algorithm","archived":false,"fork":false,"pushed_at":"2025-01-05T07:32:29.000Z","size":1215,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-27T03:09:43.357Z","etag":null,"topics":["database","distributed-systems","go","key-value","raft"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/khanh1998.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-09T14:58:38.000Z","updated_at":"2025-01-05T07:32:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"7d1c4720-2227-4574-a8c2-f1f835d04b9f","html_url":"https://github.com/khanh1998/raft-go","commit_stats":null,"previous_names":["khanh1998/raft-go"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/khanh1998/raft-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khanh1998%2Fraft-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khanh1998%2Fraft-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khanh1998%2Fraft-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khanh1998%2Fraft-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/khanh1998","download_url":"https://codeload.github.com/khanh1998/raft-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khanh1998%2Fraft-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32159959,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T17:06:48.269Z","status":"ssl_error","status_checked_at":"2026-04-22T17:06:19.037Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["database","distributed-systems","go","key-value","raft"],"created_at":"2024-11-09T15:12:32.205Z","updated_at":"2026-04-22T23:35:16.594Z","avatar_url":"https://github.com/khanh1998.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Raft Protocol Implementation and Applications\nThis project implements the Raft consensus protocol in Go, allowing developers to build distributed systems with fault-tolerant consensus mechanisms. The core Raft protocol is designed to be extensible, enabling the creation of custom extensions.\n\nCurrently, two extensions have been built on top of the Raft core:\n\n- Classic: A simple in-memory key-value database.\n- Etcd: Inspired by etcd 2.3, mimicking its interface and behavior.\n\n## Raft implementation\nThis implementation includes all the core components described in the Raft paper:\n- Leader Election: Ensures that one node is elected as the leader for decision-making and log replication.\n- Log Replication: Ensures that logs are replicated across all nodes, providing consistency in the system.\n- Safety: Guarantees that logs are never lost or overwritten, ensuring strong consistency.\n- Client Interaction: Provides APIs for client requests, enabling users to interact with the distributed system.\n- Cluster Membership Changes: Allows for dynamic changes in the cluster, including node additions and removals.\n- Log Compaction: Implements snapshotting to truncate logs and keep the system efficient.\n\n## Extensions\n### [Classic (Key-Value DB)](extensions/classic/README.md)\nClassic is a simple, hashmap-based key-value store built on top of the Raft protocol. It closely follows the original Raft paper to demonstrate how Raft can provide consistency in a basic database.\n#### Key Features:\n- Hash-based in-memory storage: Fast and lightweight key-value storage.\n- Key-value operations: Supports `get`, `set`, `del`, and key-specific locking.\n- Client session management: Includes `register` and `keep-alive` for client sessions with automatic request de-duplication.\n- Static and dynamic clusters: Works with both fixed and adjustable cluster configurations.\n- Consistency: Guarantees consistent reads and writes via Raft.\n\n### [Etcd Clone (v2.3)](extensions/etcd/README.md)\nThe etcd clone replicates the interface and functionality of etcd 2.3, enabling seamless interaction with the cluster using tools like `curl`. This extension demonstrates how the Raft protocol can serve as the foundation for a distributed key-value store with a familiar and user-friendly API.\n\n#### Key Features:\n- etcd-inspired API: Implements functionality like `put`, `ttl`, `cas`, `get`, `delete`, `watch`, and more.\n- B-tree-based in-memory storage: Supports efficient prefix-based get and delete operations.\n- Static and dynamic clusters: Compatible with both fixed and adjustable cluster configurations.\n- Consistency and fault tolerance: Ensures reliable and consistent operations using Raft.\n\u003e [!NOTE]  \n\u003e The API is inspired by etcd 2.3 but is not fully compatible with it. The etcd-clone uses a flat key structure but supports prefix-based operations to mimic folder-like functionality.\n\n## Getting Started\n### Prerequisites\n- Go 1.22 or higher\n- Dependencies: See `go.mod` for all required dependencies\n- `make` is recommended\n### Installation\n1. Clone the repository: \n    ```bash\n    git clone https://github.com/khanh1998/raft-go.git\n    cd raft-go\n    ```\n2. Install dependencies:\n    ```bash\n    go mod tidy\n    ```\n### Running the Applications\n**Running the Etcd Extension**\nNavigate to the etcd extension directory and start a node:\n```bash\ncd extensions/etcd\nmake noded1\n```\n### Configuration\nEach extension uses a `config.yml` file for configuration, including cluster size, ports, and other options. Ensure the file is properly configured before starting the applications.\n- [Raft core configuration](raft_core/README.md)\n\n### Client Communication\nBoth extensions use HTTP for client communication.\n**Example: Interacting with the Etcd Extension**\nYou can use curl to interact with the etcd extension. For example, to get a key:\n```bash\ncurl -L http://localhost:8080/v2/keys/cs/db/sql/mysql\n```\n\n## Building Your Own Extension\nThis project is designed to be extensible. You can create your own applications based on the Raft core by implementing a new extension under the `extensions/` directory. Use the existing `extensions/classic` and `extensions/etcd` examples as a reference.\n\n## Contributing\nContributions are welcome! If you have ideas for improvements or new extensions, feel free to open an issue or submit a pull request.\n\nSteps to contribute:\n1. Fork the repository.\n2. Create a feature branch:\n    ```bash\n    git checkout -b feature/new-extension\n    ```\n3. Commit your changes:\n    ```bash\n    git commit -m \"Add new feature\"\n    ```\n4. Push to your branch and open a pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhanh1998%2Fraft-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkhanh1998%2Fraft-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhanh1998%2Fraft-go/lists"}