How to choose the right PartitionCount for consistent hashing?

Select a prime number and a sufficiently large value based on your key volume; the README suggests bigger counts for many keys, but tuning is required—test with examples like load_distribution.go to find an optimum.

What happens when a node fails in buraksezer/consistent?

When a node is removed via the Remove method, partitions are redistributed among remaining members while respecting bounded loads, minimizing relocation. Your application must handle the removal logic and health checks externally.

How does buraksezer/consistent compare to other Go libraries like github.com/stathat/consistent?

Buraksezer/consistent implements the bounded loads algorithm for guaranteed no-overload distribution, whereas others may not. However, it lacks built-in hash functions and has a fixed partition count, making it more complex to set up but more robust for load-sensitive systems.

Can I use this for load balancing in a microservices setup?

Yes, it's used in production by projects like Easegress for traffic orchestration. Integrate it with service discovery to map requests to nodes, but note that you'll need to implement health checks and failover separately.

How to implement a custom hasher for consistent library?

Create a struct that implements the Hasher interface with a Sum64 method, using a hash like xxhash as shown in the example. This allows flexibility but requires careful testing to ensure uniform distribution.

What are the best practices for configuring Load and ReplicationFactor?

Start with defaults from the examples (e.g., Load 1.25, ReplicationFactor 20) and adjust based on your cluster size and tolerance for relocation. Use the relocation_percentage.go example to simulate changes and minimize movement.

Open-Awesome

consistent

MITGov0.10.0

A Go library implementing consistent hashing with bounded loads for uniform key distribution and load balancing.

Visit Website GitHub

775 stars77 forks0 contributors

What is consistent?

Consistent is a Go library that implements consistent hashing with bounded loads, a distributed algorithm for mapping keys to nodes in a cluster. It solves the problem of uneven load distribution and excessive data movement when nodes are added or removed, making it ideal for scalable load balancers, caches, and distributed databases.

Target Audience

Go developers building distributed systems such as caches, databases, load balancers, or any service requiring scalable and efficient key-to-node mapping.

Value Proposition

Developers choose Consistent for its strict adherence to the bounded loads algorithm, which guarantees no node is overloaded, and its production-ready performance with minimal relocation overhead during cluster changes.

Overview

Consistent hashing with bounded loads in Golang

Use Cases

Best For

Building distributed caching systems like Olric
Implementing load balancers for microservices
Designing scalable key-value stores
Creating distributed data structures in Go
Developing cloud-native traffic orchestration systems
Adding consistent hashing to Kubernetes operators

Not Ideal For

Systems that require dynamic adjustment of partition count after initialization
Projects seeking an out-of-the-box hashing solution without custom Hasher implementation
Applications where graceful degradation is preferred over panics during cluster overload

Pros & Cons

Pros

Bounded Load Enforcement

Guarantees no node exceeds the calculated average load, preventing hotspots as per the research-backed algorithm from Google, ensuring predictable performance in distributed systems.

High Performance Lookups

Locates key owners in constant time (252 ns/op in benchmarks) with no memory allocation during key location, making it efficient for high-throughput applications.

Minimal Relocation Overhead

Limits partition movement when nodes are added or removed, as demonstrated in the example where only 6% of partitions relocated, reducing data transfer and system churn.

Thread-Safe Design

Supports concurrent member additions, removals, and key lookups, making it suitable for production environments with multiple goroutines.

Cons

Fixed Partition Count

The number of partitions cannot be changed after creation, limiting scalability adjustments without reinitializing the entire consistent hashing ring, which can be disruptive.

No Default Hasher

Requires implementing a custom Hasher interface, adding setup complexity and potential for errors compared to libraries that provide built-in hash functions out of the box.

Panic on Overload

If all members are at maximum load, attempting to add a new member causes a panic, which may crash the application rather than offering graceful error handling or queuing mechanisms.

Frequently Asked Questions

Related Projects

Go-zero

A cloud-native Go microservices framework with cli tool for productivity.

Stars33,106

Forks4,307

Last commit3 days ago

go-kit

A standard library for microservices.

Stars27,429

Forks2,442

Last commit1 year ago

Kratos

Your ultimate Go microservices framework for the cloud-native era.

Stars25,730

Forks4,163

Last commit2 days ago

grpc-go

The Go language implementation of gRPC. HTTP/2 based RPC

Stars22,962

Forks4,694