{"id":17339979,"url":"https://github.com/resetius/miniraft-cpp","last_synced_at":"2025-08-21T15:33:21.735Z","repository":{"id":208702324,"uuid":"722277890","full_name":"resetius/miniraft-cpp","owner":"resetius","description":"Raft Consensus Algorithm. Uses in-house C++20 coroutines-based library for communications. Tested with unit-tests.","archived":false,"fork":false,"pushed_at":"2024-07-28T17:52:23.000Z","size":138,"stargazers_count":43,"open_issues_count":1,"forks_count":8,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-11T00:03:25.370Z","etag":null,"topics":["coroutines","cpp","cpp20","raft","raft-consensus-algorithm","raft-cpp","raft-protocol"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/resetius.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-22T19:56:13.000Z","updated_at":"2024-11-19T13:51:04.000Z","dependencies_parsed_at":"2023-12-16T18:28:44.152Z","dependency_job_id":"b8d8e786-3f73-482b-99c2-11e13fbd71a6","html_url":"https://github.com/resetius/miniraft-cpp","commit_stats":null,"previous_names":["resetius/miniraft-cpp"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/resetius%2Fminiraft-cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/resetius%2Fminiraft-cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/resetius%2Fminiraft-cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/resetius%2Fminiraft-cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/resetius","download_url":"https://codeload.github.com/resetius/miniraft-cpp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230520392,"owners_count":18238948,"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":["coroutines","cpp","cpp20","raft","raft-consensus-algorithm","raft-cpp","raft-protocol"],"created_at":"2024-10-15T15:43:40.419Z","updated_at":"2025-08-21T15:33:21.721Z","avatar_url":"https://github.com/resetius.png","language":"C++","readme":"# MiniRaft-CPP\n\n[![Number of GitHub stars](https://img.shields.io/github/stars/resetius/miniraft-cpp)](https://github.com/resetius/miniraft-cpp/stargazers)\n![GitHub commit activity](https://img.shields.io/github/commit-activity/m/resetius/miniraft-cpp)\n[![GitHub license which is BSD-2-Clause license](https://img.shields.io/github/license/resetius/miniraft-cpp)](https://github.com/resetius/miniraft-cpp)\n\n## Table of Contents\n- [Overview](#overview)\n- [Key Features](#key-features)\n- [Project Structure](#project-structure)\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Building the Project](#building-the-project)\n  - [Running the Application](#running-the-application)\n- [Example: State Machine (RSM) with Key-Value Store](#example-state-machine-rsm-with-key-value-store)\n  - [Server Mode](#server-mode)\n  - [Client Mode](#client-mode)\n- [Media](#media)\n\n---\n\n## Overview\n**MiniRaft-CPP** is a C++20 implementation of the Raft consensus algorithm.\nIt uses the [coroio library](https://github.com/resetius/coroio) for efficient asynchronous I/O and\naims to provide a straightforward reference for how Raft handles leader election,\nlog replication, and fault tolerance in a distributed system.\n\n---\n\n## Key Features\n- **Leader Election** (supported)\n- **Log Replication** (supported)\n- **Persistence** (supported)\n- **Snapshots** (not supported yet)\n- **Membership Change** (not supported yet)\n\nThe project focuses on a clear, modular design that leverages C++20 coroutines to simplify asynchronous flows.\n\n---\n\n## Project Structure\n\n- **`miniraft/`**\n  This directory contains the **MiniRaft library**, which implements all core components required for Raft consensus.\n  - **`raft.h` / `raft.cpp`**: Core files defining the Raft algorithm (leader election, log replication, etc.).\n\n- **`miniraft/net/`**\n  A **network library** that builds on top of MiniRaft and uses [coroio](https://github.com/resetius/coroio) for asynchronous I/O.\n  - **`server.h` / `server.cpp`**: Main networking/server implementation for node-to-node communication and client handling.\n\n- **`examples/`**\n  Contains sample applications that demonstrate how to use the MiniRaft libraries:\n  - **`kv.cpp`**: A distributed key-value store implemented on top of Raft.\n\n\n### Using MiniRaft as a Git Submodule\nIf you want to embed this project into your own codebase as a submodule, you can do one of the following:\n\n1. **Consensus Only**: If you only need the Raft consensus logic without networking, you can include:\n```cmake\n   add_subdirectory(miniraft)\n```\n\nThen link against the miniraft library.\n\n2. **Consensus + Networking**: If you also need the built-in server/network layer, add:\n\n```cmake\nadd_subdirectory(miniraft)\nadd_subdirectory(miniraft/net)\n```\n\nThen link against miniraft.net which also brings in miniraft internally.\n\n---\n\n## Getting Started\n\n### Prerequisites\n- A C++20-compatible compiler\n- CMake (for building)\n- [Cmocka](https://cmocka.org/) (for unit tests only)\n\n### Building the Project\n1. Clone the repository:\n   ```\n   git clone https://github.com/resetius/miniraft-cpp\n   ```\n2. Initialize and update the submodule:\n   ```\n   git submodule init\n   git submodule update\n   ```\n3. Navigate to the project directory:\n   ```\n   cd miniraft-cpp\n   ```\n4. Build the project using CMake:\n   ```\n   cmake .\n   make\n   ```\n\n### Running the Application\n\nThis is a simple application designed to demonstrate log replication in the Raft consensus algorithm.\n\nTo start the application, launch the servers with the following commands:\n```\n./server --id 1 --node 127.0.0.1:8001:1 --node 127.0.0.1:8002:2 --node 127.0.0.1:8003:3\n./server --id 2 --node 127.0.0.1:8001:1 --node 127.0.0.1:8002:2 --node 127.0.0.1:8003:3\n./server --id 3 --node 127.0.0.1:8001:1 --node 127.0.0.1:8002:2 --node 127.0.0.1:8003:3\n```\n\nTo interact with the system, run the client as follows:\n```\n./client --node 127.0.0.1:8001:1\n```\nThe client expects an input string to be added to the distributed log. If the input string starts with an underscore (`_`), it should be followed by a number (e.g., `_ 3`). In this case, the client will attempt to read the log entry at the specified number.\n\n### Example: State Machine (RSM) with Key-Value Store\n\nMiniRaft-CPP includes an example of a distributed Key-Value store implemented as a replicated state machine on top of Raft. The source code for this example resides in examples/kv.cpp\n\n#### Server Mode\n\nTo start the KV store servers, use:\n```\n./kv --server --id 1 --node 127.0.0.1:8001:1 --node 127.0.0.1:8002:2 --node 127.0.0.1:8003:3\n./kv --server --id 2 --node 127.0.0.1:8001:1 --node 127.0.0.1:8002:2 --node 127.0.0.1:8003:3\n./kv --server --id 3 --node 127.0.0.1:8001:1 --node 127.0.0.1:8002:2 --node 127.0.0.1:8003:3\n```\n\n#### Client Mode\n\nTo run the KV client, use:\n```\n./kv --client --node 127.0.0.1:8001:1\n```\nThe KV client expects commands as input:\n1. `set \u003ckey\u003e \u003cvalue\u003e` - Adds or updates a value in the KV store.\n2. `get \u003ckey\u003e` - Retrieves a value by its key.\n3. `list` - Displays all key/value pairs in the store.\n4. `del \u003ckey\u003e` - Deletes a key from the store.\n\n---\n\n## Media\n1. [Implementation of the Raft Consensus Algorithm Using C++20 Coroutines](https://dzone.com/articles/implementation-of-the-raft-consensus-algorithm-usi)\n2. [Разработка сетевой библиотеки на C++20: интеграция асинхронности и алгоритма Raft (часть 1)](https://www.linux.org.ru/articles/development/17447126)\n3. [Разработка сетевой библиотеки на C++20: интеграция асинхронности и алгоритма Raft (часть 2)](https://www.linux.org.ru/articles/development/17449693)\n4. [High-performance network library using C++20 coroutines](https://habr.com/ru/articles/768418/)\n5. [Simplifying Raft with C++20 coroutines](https://youtu.be/xztv-zIDLxc?si=3amGsi0Co9ZP6flT)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fresetius%2Fminiraft-cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fresetius%2Fminiraft-cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fresetius%2Fminiraft-cpp/lists"}