How otoolep/hraftd works
Project type and purpose
• This is a small Go-based distributed system (“hraftd”) that demonstrates a replicated key-value store using the Hashicorp Raft consensus library.
• The README describes it as a reference implementation of Raft: each node exposes an HTTP API for GET/POST on keys, and internally uses Raft to replicate changes across a cluster.
File structure
• main.go: sets up the Raft node and HTTP server.
• http/service.go (+ service_test.go): HTTP API layer that handles client requests.
• store/store.go (+ store_test.go): in-memory key-value store implementing Raft’s FSM interface (applies committed log entries).
• go.mod/go.sum: dependency management (notably hashicorp/raft).
• CLUSTERING.md: documentation for multi-node setups.
• .circleci/config.yml, appveyor.yml: CI pipelines.
README for additional insights
• Describes how nodes discover each other (–join flag) and how Raft handles leader election, replication, and failure recovery.
• Mentions that HTTP requests for writes must go to the leader; GETs can be served by any node (allowing stale reads).
a. Main components
• Client(s): CLI or curl issuing HTTP requests.
• HTTP Service layer: Go net/http handlers (service.go).
• Raft Node (Hashicorp Raft library):
– Transport layer (RPC between nodes)
– Log store (on-disk)
– Finite State Machine (FSM) interface implemented by store/store.go
• In-memory key-value store (FSM state)
• Persistent storage directories (per-node data directory)
• Peers (other hraftd instances)
b. Relationships and interactions
1. Client → HTTP Service: POST /key and GET /key/{k}.
2. On POST: HTTP Service calls raft.Apply(entry).
3. Raft Leader appends entry to local log store, then replicates via Transport RPCs to followers.
4. Once a quorum acknowledges, the log is marked committed.
5. Raft calls FSM.Apply(logEntry) on all nodes, invoking store/store.go to update the in-memory map.
6. HTTP Service returns a success response to the client.
7. On GET: HTTP Service reads directly from the in-memory store and returns the value.
c. Architectural patterns & design principles
– Replicated State Machine: all nodes apply the same sequence of log entries.
– Leader-Follower Consensus: one leader coordinates writes, followers replicate logs.
– Pluggable FSM: separation of Raft protocol (transport + log) from application state (key-value store).
– Stateless HTTP layer (aside from hitting the FSM).
d. Technologies & libraries
– Go (language)
– net/http for service.go
– github.com/hashicorp/raft for consensus
– Filesystem for log storage and snapshots (under node data directory)
– Testing: Go’s built-in testing framework