ringlet-hash 0.2.1

Consistent hashing with weighted nodes and cluster migration previews
Documentation
ringlet-hash-0.2.1 has been yanked.

Ringlet

Test line coverage: 100% Public API docs: 100%

Ringlet is a consistent hashing library for assigning keys to physical nodes. It uses virtual nodes to distribute ownership and supports weighted nodes, multiple distinct owners per key, and migration previews when cluster membership changes.

Quick start

The crates.io package is ringlet-hash; Rust imports use ringlet_hash.

cargo add ringlet-hash
use std::hash::{BuildHasherDefault, DefaultHasher};
use ringlet_hash::{ClusterManager, RingConfig};

fn main() -> Result<(), ringlet_hash::RingError> {
    let server_a = String::from("server-a");
    let server_b = String::from("server-b");
    let mut cluster = ClusterManager::try_new(RingConfig {
        virtual_node_base_count: 50,
        build_hasher: BuildHasherDefault::<DefaultHasher>::default(),
    })?;

    cluster.add_node(&server_a, "a", 1)?;
    cluster.add_node(&server_b, "b", 2)?;

    let owner = cluster.get_node(&"customer-42");
    let replicas = cluster.get_nodes(&"customer-42", 2);
    let migration = cluster.calculate_migration_on_remove("a")?;

    assert!(owner.is_some());
    assert_eq!(replicas.len(), 2);
    assert!(!migration.is_empty());
    Ok(())
}

ConsistentRing borrows each physical node and stores its identifier and weight once; its virtual positions refer to those entries by index. Keep node values alive while the ring uses them. ClusterManager provides checked membership changes over a ring. cluster.nodes() returns physical nodes in insertion order, with identifier(), value(), and weight() accessors. Adding and looking up nodes does not require T: Clone; migration previews still require it because they return owned values. Use the same hash builder, identifiers, weights, and key types across processes that share a ring.

Coverage

The coverage workflow refreshes these badges on the default branch after successful checks. The current values are:

Metric Result How it is measured
Test line coverage 100% (257/257 lines) cargo llvm-cov on library source; tests and benchmarks excluded
Public API documentation 100% (33/33 items) Rustdoc --show-coverage documented-item count

Recheck them with:

cargo test
cargo llvm-cov --summary-only --ignore-filename-regex 'tests/|benches/'
RUSTDOCFLAGS='-D missing_docs -D rustdoc::broken_intra_doc_links' cargo doc --no-deps
RUSTDOCFLAGS='-Z unstable-options --show-coverage --output-format json' cargo +nightly doc --no-deps

The coverage command requires cargo-llvm-cov and the llvm-tools-preview component for the selected Rust toolchain. The documentation percentage is Rustdoc's documented-item count; it does not score the detail or accuracy of the prose. Rustdoc currently calculates that percentage with a nightly-only option.