com.github.ishugaliy:allgood-consistent-hash

AllGood Consistent-Hash

Overview

AllGood Consistent Hash is a Java implementation of Consistent Hash Ring with Virtual Nodes that supports customization of hashing and partition rate. The library is very lightweight and user-friendly, which provides several examples, making it easy to understand and use.

Download

Gradle

// authenticate with github packages
repositories {
    maven {
        url 'https://maven.pkg.github.com/ishugaliy/allgood-consistent-hash'
        credentials {
            username = '{your_username}'
            password = '{your_access_token}'
        }
    }
}

dependencies {
    implementation 'org.ishugaliy:allgood-consistent-hash:1.0.0'
}

Gradle with GitHub Packages

Maven

settings.xml

// authenticate with github packages
<profiles>
    <profile>
        <id>github</id>
        <repositories>
            <repository>
                <id>github</id>
                <name>GitHub IShugaliy Apache Maven Packages</name>
                <url>https://maven.pkg.github.com/ishugaliy/allgood-consistent-hash</url>
            </repository>
        </repositories>
    </profile>
</profiles>

<servers>
    <server>
        <id>github</id>
        <username>{your_github_username}</username>
        <password>{your_github_access_token}</password>
    </server>
</servers>

pom.xml

<dependency>
    <groupId>org.ishugaliy</groupId>
    <artifactId>allgood-consistent-hash</artifactId>
    <version>1.0.0</version>
</dependency>

Maven with GitHub Packages

Usage

Structure

• ConsistentHash - consistent-hash implementation abstraction.
  • HashRing - consistent-hash ring with virtual nodes implementation.
• Node - consistent-hash nodes abstraction.
  • SimpleNode - a simple node implementation, represents a single value.
  • ServerNode - represents server or host.
• Hasher - hash function abstraction.
  • DefaultHasher - list of build-in hash functions.

Basic

// Build hash ring
ConsistentHash<SimpleNode> ring = HashRing.<SimpleNode>newBuilder().build();

// Add nodes
ring.add(SimpleNode.of("dc1.node.1"));
ring.add(SimpleNode.of("dc2.node.2"));
ring.add(SimpleNode.of("dc3.node.3"));

// Locate node
Optional<SimpleNode> node = ring.locate("your_key");

Advanced

// Create nodes
ServerNode n1 = new ServerNode("192.168.1.1", 80);
ServerNode n2 = new ServerNode("192.168.1.132", 80);
ServerNode n3 = new ServerNode("aws", "11.32.98.1", 9231);
ServerNode n4 = new ServerNode("aws", "11.32.328.1", 9231);

// Build hash ring
ConsistentHash<ServerNode> ring = HashRing.<ServerNode>newBuilder()
        .name("file_cache_hash_ring")       // set hash ring name
        .hasher(DefaultHasher.METRO_HASH)   // hash function to distribute partitions
        .partitionRate(10)                  // number of partitions per node
        .nodes(Arrays.asList(n1, n2))       // initial nodes set
        .build();

// add nodes
ring.addAll(Arrays.asList(n3, n4));        

// Locate 2 nodes
Set<ServerNode> nodes = ring.locate("your_key", 2);

More samples can be found here

Sandboxes

The sources contains sandboxes to analyze different load metrics (standard deviation, nodes miss-hits, etc):

• HasherLoadDistributionSandbox
  The sandbox allows checking consistent hash load distribution between nodes with different hash functions. Showing how the distribution rate depends on the hash function and partition rate.
• NodesMissHitsSandbox
  The sandbox allows checking consistent hash nodes miss-hits. Showing dependency between miss-hits and partition rate.

More sandboxes can be found here

Logging

AllGood Consistent Hash library uses a slf4 logging facade that allows plug it in the desired logging framework at deployment time.

Namespace: org.ishugaliy.allgood.consistent.hash

Logback example:

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <logger name="org.ishugaliy.allgood.consistent.hash" level="error"/>
    <root level="debug">
        <appender-ref ref="STDOUT" />
    </root>
</configuration>

Requirements

Compile requirements: JDK 8+ and Maven 3.2.5+

References

• Consistent Hashing: Algorithmic Tradeoffs
• Stanfort: Consistent Hashing
• DataStax: Consistent Hash
• Hash Function Comparison
• StackOverflow: Hashing Algorithms Comparison
• Google: Consistent Hashing with Bounded Loads

License

The MIT License

Copyright (c) 2020 Iurii Shugalii

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.