A consistent hashring compatible with ketama hashing and python's hash_ring
The HashRing module provides consistent hashing that is compatible with the
original libketama library that was developed at last.fm. In addition to beeing
libketama it's also compatible with the
hash_ring module for
Python. See the compatiblity section of the API for more details on this.
The advised installation of module is done through the Node package manager (npm).
npm install hashring --save
--save parameter tells npm that it should automatically add the module to
dependencies field in your package.json.
var HashRing = require'hashring';
The HashRing constructor is designed to handle different argument types as a consistent hash ring can be use for different use cases. You can supply the constructor with:
A single server, possible, but pointless in most cases if you only use one server, then done use the HashRing at all, it only adds overhead.
var ring = '127.0.0.1:11211';
Multiple servers for the HashRing.
var ring = '127.0.0.1:11211' '127.0.0.2:11211';
An Object where the keys of the Object are the servers and the value can be a
Number and it will be seen as weight for server. The value can also be an
Object. Where the key can be a weight or a vnode.
Weights or vnodes are used to give servers a bigger distribution in the HashRing. For example you have 3 servers where you want to distribute your keys over but not all servers are equal in capacity as 2 of those machines have 200mb of memory and the other has 3.2 gig of memory. The last server is substantially bigger and there for should receive a greater distrubtion in the ring.
For a rule of thumb use the amount of memory as weight:
var HashRing = require'hashring';var ring ='127.0.0.1:11211': 200'127.0.0.2:11211': weight: 200 // same as above'127.0.0.3:11211': 3200;
If you want create a server with multiple vnodes (virtual nodes):
var HashRing = require'hashring';var ring ='127.0.0.1:11211': vnodes: 50'127.0.0.2:11211': vnodes: 200'127.0.0.3:11211': vnodes: 100;
With the second argument you can configure the algorithm that is used to hash
the keys. It defaults to
md5 and can only contain values that are accepted in
crypto API. Alternatively you can supply it with a function for a
custom hasher. But do note that the hashValue will be calculated on the result.
vnode countThe amount of virtual nodes per server, defaults to 40 as this generates 160 points per server as used by ketama hashing.
compatiblityAllows you to force a compatibility mode of the HashRing. It default to ketama hash rings but if you are coming from a python world you might want compatibility with the
hash_ringmodule. There's a small diff between
ketamaand that's the amount of replica's of a server. Ketama uses 4 and
hash_ringuses 3. Set this to
hash_ringif you want to use 3.
replicasThe amount of replicas per server. Defaults to 4.
max cache sizeWe use a simple LRU cache inside the module to speed up frequent key lookups, you can customize the amount of keys that need to be cached. It defaults to 5000.
default portThe default port number which will removed from the server address to provide ketama compatibility.
'use strict';// require the module, it returns a HashRing constructorvar HashRing = require'hashring';// Setup hash rings with your servers, in this example I just assume that all// servers are equal, and we want to bump the cache size to 10.000 items.var ring ='127.0.0.1''127.0.0.2''127.0.0.3''127.0.0.4''md5''max cache size': 10000;// Now we are going to get some a server for a keyringget'foo bar banana'; // returns 127.0.0.x// Or if you might want to do some replication scheme and store/fetch data from// multiple serversringrange'foo bar banana' 2forEachconsole.logserver; // do stuff with your server;// Add or remove a new a server to the ring, they accept the same arguments as// the constructorringadd'127.0.0.7'remove'127.0.0.1';
Generates the continuum of server a.k.a as the Hash Ring based on their weights and virtual nodes assigned.
Find the correct node for the key which is closest to the point after what the given key hashes to.
returns: The matching server address.
Returns a range of servers. Could be useful for replication.
returns: The array of servers that we found.
Hotswap identical servers with each other. This doesn't require the cache to be completely nuked and the hash ring distribution to be re-calculated.
Please note that removing the server and a new adding server could potentially create a different distribution.
Add a new server to ring without having to re-initialize the hashring. It accepts the same arguments as you can use in the constructor.
Remove a server from the hash ring.
Checks if a given server exists in the hash ring.
Reset the HashRing and clean up it's references.
Reset's the HashRing and closes the ring.
Finds the correct position of the given hashValue in the hashring.
returns: Index of the value in the ring.
Generates the hash for the key.
returns: The hashed valued.
Digest hash so we can make a numeric representation from the hash. So it can be fed in to our hashValue.
returns: An array of charCodeAt(0) converted chars.
Get the hashed value of the given key, it does the digesting, hashing yo.
returns: The hash value of the key.
Returns the points per server.
returns: A Object with server -> Array of points mapping
The 0.0.x releases had some serious flaws that causes it to be incompatible with the 1.0.0 release. These flaws are the reason that 1.0.0 got released. They are not backwards compatible as they change the way that keys are hashed. The following incompatible changes have been made for the sake of consistency:
swap. The replace API is now removing the given server and adds it again. As this causes the servers to be properly re-hashed.