{"id":36482556,"url":"https://github.com/jathurchan/raftlock","last_synced_at":"2026-01-12T01:03:40.282Z","repository":{"id":282451278,"uuid":"941990639","full_name":"jathurchan/raftlock","owner":"jathurchan","description":"A fault-tolerant distributed lock service for coordinating distributed applications","archived":false,"fork":false,"pushed_at":"2025-07-31T12:01:54.000Z","size":1376,"stargazers_count":6,"open_issues_count":36,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-31T15:16:56.705Z","etag":null,"topics":["coordination","distributed-systems","golang","locks"],"latest_commit_sha":null,"homepage":"","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/jathurchan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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,"zenodo":null}},"created_at":"2025-03-03T11:49:26.000Z","updated_at":"2025-07-31T12:04:37.000Z","dependencies_parsed_at":"2025-04-29T17:28:23.866Z","dependency_job_id":"ca3666ee-739b-4a7a-b86e-4002eef62211","html_url":"https://github.com/jathurchan/raftlock","commit_stats":null,"previous_names":["jathurchan/raftlock"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jathurchan/raftlock","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jathurchan%2Fraftlock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jathurchan%2Fraftlock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jathurchan%2Fraftlock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jathurchan%2Fraftlock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jathurchan","download_url":"https://codeload.github.com/jathurchan/raftlock/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jathurchan%2Fraftlock/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28330175,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"ssl_error","status_checked_at":"2026-01-12T00:36:15.229Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["coordination","distributed-systems","golang","locks"],"created_at":"2026-01-12T01:03:40.220Z","updated_at":"2026-01-12T01:03:40.274Z","avatar_url":"https://github.com/jathurchan.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RaftLock\n\n[![Unit Tests](https://github.com/jathurchan/raftlock/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/jathurchan/raftlock/actions/workflows/unit-tests.yml)\n[![Integration Tests](https://github.com/jathurchan/raftlock/actions/workflows/integration-tests.yml/badge.svg)](https://github.com/jathurchan/raftlock/actions/workflows/integration-tests.yml)\n[![codecov](https://codecov.io/gh/jathurchan/raftlock/graph/badge.svg?token=RW0H2MKNMV)](https://codecov.io/gh/jathurchan/raftlock)\n[![Lint](https://github.com/jathurchan/raftlock/actions/workflows/lint.yml/badge.svg)](https://github.com/jathurchan/raftlock/actions/workflows/lint.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Go Report Card](https://goreportcard.com/badge/github.com/jathurchan/raftlock)](https://goreportcard.com/report/github.com/jathurchan/raftlock)\n\n`raftlock` is a fault-tolerant distributed lock service for coordinating distributed applications. It is written in Go and is designed to be a reliable and highly available solution for managing distributed locks.\n\n## What the project does\n\nIn distributed systems, coordinating actions between different services or nodes can be a complex challenge. `raftlock` provides a simple and robust solution for this by offering a distributed locking mechanism. This ensures that only one process can access a particular resource at a time, preventing data corruption and ensuring consistency across your distributed application.\n\nThe project is built on top of the **Raft consensus algorithm**, which guarantees fault tolerance. This means that `raftlock` can withstand failures of some of its nodes without losing availability or data.\n\n## Why the project is useful\n\n`raftlock` is useful for a variety of use cases in distributed systems, including:\n\n* **Leader Election:** Electing a single leader from a group of nodes to perform a specific task.\n* **Distributed Cron Jobs:** Ensuring that a scheduled task is executed by only one node in a cluster.\n* **Resource Locking:** Preventing multiple processes from concurrently modifying a shared resource, such as a file or a database record.\n* **Distributed Semaphores:** Limiting the number of concurrent processes that can access a pool of resources.\n\nBy providing a reliable and easy-to-use distributed lock service, `raftlock` simplifies the development of robust and scalable distributed applications.\n\n## Architecture Overview\n\nRaftLock is composed of several key packages, each handling a specific aspect of the distributed lock service.\n\n* **`server/`**: Implements the gRPC server that exposes the distributed locking API to clients. It handles request validation, leader redirection, and coordination with the underlying Raft consensus. For more details, see the [Server Package README](server/README.md).\n* **`raft/`**: Contains a custom-built implementation of the Raft consensus algorithm. This is the core engine for maintaining strong consistency and fault tolerance across the cluster. Dive deeper into its design in the [Raft Consensus Module README](raft/README.md).\n* **`lock/`**: Provides the distributed lock manager, which acts as the application-level state machine for the Raft cluster. It manages lock states, expirations, and waiter queues. Learn more in the [Distributed Lock Manager README](lock/README.md).\n* **`storage/`**: Offers a durable and crash-resilient persistence layer for Raft data, including persistent state, log entries, and snapshots. Details can be found in the [RaftLock Storage Package README](storage/README.md).\n* **`client/`**: Provides the Go client library for applications to communicate with a RaftLock cluster, offering interfaces for standard lock operations, administration, and advanced features. For usage, refer to the [Client Package README](client/README.md).\n* **`proto/`**: Defines the Protocol Buffer messages and gRPC service for the RaftLock API, ensuring type-safe and efficient communication between clients and the server. See the [RaftLock Protocol Buffers README](proto/README.md).\n\n## How users can get started with the project\n\nYou can run the `raftlock` server using either Docker or by building from the source.\n\n### Running with Docker 🐳\n\nThis is the recommended way to run `raftlock`. We use `docker-compose` to easily manage a multi-node cluster.\n\n1. **Start the cluster:**\n    This command will build the Docker images and start a 3-node `raftlock` cluster in the background.\n\n    ```bash\n    docker-compose up --build -d\n    ```\n\n2. **Check the logs:**\n    You can monitor the logs of each node to see the cluster formation and leader election process.\n\n    ```bash\n    docker-compose logs node1\n    docker-compose logs node2\n    docker-compose logs node3\n    ```\n\n3. **Stop the cluster:**\n    To stop and remove the containers, networks, and volumes, run:\n\n    ```bash\n    docker-compose down -v\n    ```\n\n### Building from Source\n\nIf you prefer to build from the source code:\n\n1. **Clone the repository:**\n\n    ```bash\n    git clone https://github.com/jathurchan/raftlock.git\n    cd raftlock\n    ```\n\n2. **Build the binary:**\n\n    ```bash\n    go build\n    ```\n\n3. **Run a server node:**\n    You'll need to run multiple instances on different ports to form a cluster. See the **Configuration** section for more details.\n\n    ```bash\n    ./raftlock --id node1 --api-addr \":8080\" --raft-addr \":12379\" --raft-bootstrap\n    ```\n\n## Example: Distributed Payment 💳\n\nTo see `raftlock` in action, you can run the payment example located in the `examples/payment` directory. This example demonstrates how to use a distributed lock to ensure a payment process is handled by only one node at a time, preventing double spending.\n\n**Run the example with the following command:**\n\n```bash\ngo run examples/payment/main.go --payment-id payment456 --client-id client002 --servers localhost:8080\n```\n\nThis will start a client that interacts with the `raftlock` server to acquire a lock before processing a mock payment. You will see output indicating whether the lock was acquired and the payment was processed.\n\n## API Usage\n\nYou can interact with `raftlock` using its simple REST API. Here are some examples using `curl`.\n\n### Acquire a Lock\n\nTo acquire a lock, send a `POST` request to the `/lock` endpoint with the `resource` you want to lock and a `ttl` (time-to-live) in seconds.\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" -d '{\n  \"resource\": \"my-critical-resource\",\n  \"ttl\": 30\n}' http://localhost:8080/lock\n```\n\nIf successful, you will receive a `lock_id`.\n\n### Release a Lock\n\nTo release a lock, send a `POST` request to the `/unlock` endpoint with the `lock_id` you received when acquiring the lock.\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" -d '{\n  \"lock_id\": \"your-lock-id-here\"\n}' http://localhost:8080/unlock\n```\n\n## Where users can get help with your project\n\nIf you have any questions or encounter any issues while using `raftlock`, please feel free to open an issue on the [**GitHub repository**](https://github.com/jathurchan/raftlock/issues). We will do our best to help you as soon as possible.\n\n## Contributing\n\nWe welcome contributions from the community\\! If you are interested in contributing to `raftlock`, please follow these steps:\n\n1. **Fork the repository** on GitHub.\n2. **Create a new branch** for your feature or bug fix: `git checkout -b my-new-feature`.\n3. **Make your changes** and commit them with clear, descriptive messages.\n4. **Run the tests** to ensure everything is working: `go test ./...`.\n5. **Push your branch** to your fork: `git push origin my-new-feature`.\n6. **Submit a pull request** to the `main` branch of the `jathurchan/raftlock` repository.\n\n## Who maintains and contributes to the project\n\n`raftlock` is maintained by a team of dedicated developers:\n\n* **Jathurchan Selvakumar**\n* **Patrice Zhou**\n* **Mathusan Selvakumar**\n\nWe welcome contributions from the community\\! If you are interested in contributing to `raftlock`, please fork the repository and submit a pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjathurchan%2Fraftlock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjathurchan%2Fraftlock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjathurchan%2Fraftlock/lists"}