#consistent-hashing #pingora #hashing

pingora-ketama

Rust port of the nginx consistent hash function

5 releases (3 breaking)

0.4.0 Nov 1, 2024
0.3.0 Jul 12, 2024
0.2.0 May 10, 2024
0.1.1 Apr 18, 2024
0.1.0 Feb 28, 2024

#269 in Caching

Download history 9571/week @ 2024-12-15 4995/week @ 2024-12-22 4792/week @ 2024-12-29 8823/week @ 2025-01-05 9548/week @ 2025-01-12 11553/week @ 2025-01-19 14312/week @ 2025-01-26 18099/week @ 2025-02-02 17525/week @ 2025-02-09 12233/week @ 2025-02-16 13974/week @ 2025-02-23 11946/week @ 2025-03-02 11638/week @ 2025-03-09 13429/week @ 2025-03-16 7871/week @ 2025-03-23 3100/week @ 2025-03-30

37,760 downloads per month
Used in 14 crates (via pingora-load-balancing)

Apache-2.0

44KB
278 lines

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};

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.

Dependencies

~78KB