How gengruizhang/cabinet works
Project type and purpose
• This is a Go-based distributed consensus system called “Cabinet.”
• It implements a leader-based, weighted consensus protocol (an alternative to Raft/Paxos).
• It also includes an integrated benchmarking framework (TPC-C and YCSB workloads) and optional MongoDB storage.
File structure
Top-level modules:
• main.go – entry point, parameter parsing, bootstraps leader or follower
• config/ – cluster configuration (.conf files) and parsing logic (config.go)
• consensus.go – core consensus routines (leader election, log replication)
• primary.go – leader logic
• conns.go – network connection management
• smr/ – state machine replication support (state.go, priority.go, pmgr.go)
• mongodb/ – optional MongoDB client for persistence (leader & follower modes)
• tpcc/ – TPC-C benchmark implementation and driver
• ycsb/ – YCSB benchmark integration (data generation, workload scripts)
• eval/ – metrics, meters and measurement utilities
• scripts/ – shell/python scripts for deployment, latency injection, initialization
Key insights from README
• Weighted consensus with dynamic node weights
• Leader/follower roles: ID=0 is always the leader, others are followers
• Benchmarks (YCSB, TPC-C) plug into the same framework
• Runs locally or across machines via the config folder
• Metrics are collected under /eval and /tpcc/measurement
Main components
A. Client layer
• Benchmark clients: TPCC driver, YCSB loader
• Management scripts (initialization, add_latency, killall…)
B. Consensus cluster
• Leader node (primary.go, consensus.go)
• Follower nodes
• Network layer (conns.go)
C. State machine replication (smr/)
• Priority manager (selects high-weight nodes)
• State machine (applies commands)
D. Persistence layer (optional)
• MongoDB client (mongodb/)
• Local logs (if –pd)
E. Metrics & evaluation
• eval/meters.go
• tpcc/measurement/…
Relationships and data flow
1. Benchmark client issues workload requests → connects to leader’s API port
2. Leader receives transaction proposal → consensus.go
3. Leader sends proposals to a quorum of followers → conns.go
4. Followers respond (ACKs) → leader collects until weight quorum is reached
5. Leader commits entry → applies to state machine (smr/state.go)
6. If using MongoDB, state machine writes to MongoDB
7. Metrics emitted to eval and tpcc/measurement modules
8. Client receives confirmation
Architectural patterns and design principles
• Leader/follower pattern (a single leader, multiple followers)
• Weighted quorum (dynamic weights, smaller quorum for faster consensus)
• Modular benchmark framework (pluggable YCSB and TPC-C drivers)
• Clean separation: consensus core vs. storage vs. benchmarking
Technologies and frameworks
• Go modules (go.mod, go.sum)
• MongoDB Go driver
• Shell/Python scripts for orchestration
• TPCC & YCSB standards for benchmarking
Putting it all together
• On the left: “Benchmark Clients” (TPC-C, YCSB)
• Below: “Followers” (×N) with the same sub-modules
• On the right: “MongoDB Persistence” (optional)
• At the bottom: “Metrics & Evaluation” (eval/, tpcc/measurement/)