What Makes Olric’s Go Architecture a Masterclass in Distributed KV Design

Why Olric’s Architecture Deserves Close Study

Olric combines the advantages of embedded key‑value stores (like Badger) and standalone services (like Redis), offering both direct API usage and independent deployment. This dual capability is achieved through a clear, reusable kernel that separates server logic from core modules.

Clean and Highly Engineered Source Layout

The repository is organized to highlight responsibility boundaries:

cmd/olric-server/   → server entry point
config/           → shared configuration for embedded and server modes
internal/          → core distributed logic
  cluster/        → node management and gossip coordination
  partition/      → partition table, routing, migration
  storage/        → local storage engine
  dmap/           → distributed Map API
  rebalancer/     → rebalancing logic
  transport/      → network RPC and pipeline
pkg/               → public packages
  client/         → official client
  olric/          → embedded API
hasher/           → Jump consistent hash implementation
events/           → cluster event handling
stats/            → monitoring and metrics

Key characteristics include a hierarchical structure, reusable modules, composable configuration, and isolation of server logic from internal components.

Three‑Layer Decoupling Model

Olric’s design separates concerns into three layers:

Logic Layer (DMap) : Exposes the public API (Put, Get, Delete, Lock, Atomic) and handles request routing.

Routing Layer (Partition Table) : Determines the partition and owner node for each key, supporting backups and rebalancing.

Storage Layer (Storage Engine) : Persists data in memory structures optimized for performance.

The data flow follows:

Application → DMap → Partition Router → Storage Engine

Core Data Structure 1 – DMap (Distributed Map)

DMap is the API entry point. It decides the partition for a key, forwards requests to remote nodes when needed, and manages replicas and consistency.

type DMap struct {
    name       string
    partitions []*Partition
    ctx        context.Context
}

Typical call chain:

DMap.Put(key, value)
  → Partition Table: compute partition
    ├─ Local partition → write to Storage Engine
    └─ Remote partition → cluster.Put → RPC → Storage Engine
  → Replicate to backup nodes for consistency

Simple Interface : hides complex logic.

Logic‑Storage Separation : DMap only routes and schedules.

Distributed Primitives : supports TTL, CAS, distributed locks.

Core Data Structure 2 – Partition Table

The Partition Table acts as the system’s “brain”, mapping keys to partitions and owners, tracking backups, and generating migration plans during node changes.

type Partition struct {
    ID      uint32
    OwnerID uint64
    Backups []uint64
    Replica map[uint32]*EntrySet
}

Fixed Number of Partitions : controls migration granularity and simplifies replication.

Efficient Routing : uses Jump Hash to locate the target node in a single computation.

Rebalancing Support : creates and executes migration plans when nodes join or leave.

Core Data Structure 3 – Storage Engine

The storage engine is the final destination for data, designed for low‑latency access and minimal GC pressure.

Sharded map + RWMutex : avoids global locks and reduces contention.

Entry Structure :

type Entry struct {
    Key       []byte
    Value     []byte
    TTL       int64
    Timestamp int64
    Version   uint64
}

No interface{} usage, reducing escape and GC overhead.

Cache‑friendly contiguous memory layout for values.

TTL/LRU managed by batch processes instead of per‑item timers.

Sharding layout example:

[ shard0 ]  [ shard1 ]  …  [ shardN ]

Takeaways

Practical Go engineering practices for clean, maintainable code.

Design patterns for systems that can be both embedded and run as independent services.

Philosophy behind distributed data structures and concurrency control.

Concrete techniques for lock granularity, memory optimization, and rebalancing.

Overall system aesthetics: simplicity, extensibility, and performance.

Olric’s source code serves as a real‑world textbook for Go engineering and modern distributed system design; studying it deepens both language mastery and architectural insight.