pingora-ketama

A Rust port of the nginx consistent hashing algorithm.

This crate provides a consistent hashing algorithm which is identical in behavior to nginx consistent hashing.

Using a consistent hash strategy like this is useful when one wants to minimize the amount of requests that need to be rehashed to different nodes when a node is added or removed.

Here's a simple example of how one might use it:

use pingora_ketama::{Bucket, Continuum};

# #[allow(clippy::needless_doctest_main)]
fn main() {
    // Set up a continuum with a few nodes of various weight.
    let mut buckets = vec![];
    buckets.push(Bucket::new("127.0.0.1:12345".parse().unwrap(), 1));
    buckets.push(Bucket::new("127.0.0.2:12345".parse().unwrap(), 2));
    buckets.push(Bucket::new("127.0.0.3:12345".parse().unwrap(), 3));
    let ring = Continuum::new(&buckets);

    // Let's see what the result is for a few keys:
    for key in &["some_key", "another_key", "last_key"] {
        let node = ring.node(key.as_bytes()).unwrap();
        println!("{}: {}:{}", key, node.ip(), node.port());
    }
}

# Output:
some_key: 127.0.0.3:12345
another_key: 127.0.0.3:12345
last_key: 127.0.0.2:12345

We've provided a health-aware example in pingora-ketama/examples/health_aware_selector.rs.

For a carefully crafted real-world example, see the pingora-load-balancing crate.