How hashicorp/raft-boltdb works
Project type and purpose
• This is a Go library (“raftboltdb”) providing a BoltStore implementation of the HashiCorp Raft interfaces (LogStore, StableStore).
• Its purpose is to persist Raft log entries and stable state to BoltDB, and optionally emit runtime metrics.
File structure
• Top-level files:
• bolt_store.go/bolt_store_test.go – core store implementation + tests
• metrics.go – metrics-emission glue
• util.go – supporting helpers
• bench_test.go – benchmarks
• go.mod/go.sum – module definitions
• CI config (GitHub Actions, Travis, lint settings)
• v2/ directory: a parallel v2 implementation (same structure), indicating a versioned API line.
README for additional insights
• Core components: BoltStore, metrics via build tags (armonmetrics vs hashicorpmetrics).
• External dependencies:
• github.com/boltdb/bolt (persistent KV store)
• github.com/hashicorp/raft (Raft consensus library)
• github.com/armon/go-metrics OR github.com/hashicorp/go-metrics (metrics emitters)
Main components
a. Application / Raft layer
• Represents the consuming system (e.g., Consul) that instantiates Raft and injects this store.
b. Raft API
• The raft package interfaces (LogStore, StableStore) that BoltStore satisfies.
c. BoltStore (this library)
• Implements the Raft interfaces. Core module: bolt_store.go.
d. BoltDB
• Underlying on-disk key/value store.
e. Metrics adapters
• Pluggable metric clients selected at build time:
• Armon/go-metrics adapter
• HashiCorp/go-metrics adapter
f. Build-tag switch
• Decides which metrics adapter is compiled in (armonmetrics vs hashicorpmetrics).
Relationships and interactions
• Application → Raft package → calls BoltStore APIs (Append, FirstIndex, Get, Set, etc.).
• BoltStore → BoltDB: performs reads/writes within BoltDB buckets.
• BoltStore → Metrics adapter: emits operation-level counters/timers/gauges.
• Build tag → selects which metrics library is linked.
Architectural patterns / design principles
• Adapter pattern: BoltStore adapts Raft interfaces to BoltDB calls.
• Plugin/configuration by build tag: metrics backend is swapped at compile time.
• Single responsibility: store logic vs metrics emission vs util helpers separated.
• Versioned API branch (v2/) side-by-side with v1 for migration path.
Technologies, frameworks, libraries
• Go modules (v1 & v2)
• BoltDB (embedded KV store)
• HashiCorp Raft (consensus)
• Two metrics libraries (Armon & HashiCorp)
• GitHub Actions / Travis CI for build/test
• golangci-lint for static analysis
Key callouts
• Data flows: persistent writes vs metrics emission.
• Versioning: v1 vs v2 module paths (github.com/hashicorp/raft-boltdb vs /v2).