swim-hashring

Application-level sharding for node.js, similar to
ringpop. You can use it to
maintain in-memory state between a cluster of nodes, and it allows you
to route your requests accordingly.

swim-hashring is a library that implements a distributed sharding system using a gossip membership protocol (swim) and a consistent hash ring based on farmhash.

This library does not assume any particular application protocol.

Install

``
npm i swim-hashring -g
`


## API

* hashring()
* instance.lookup()
* instance.next()
* instance.allocatedToMe()
* instance.peers()
* instance.whoami()
* instance.mymeta()
* instance.hash()
* instance.close()

$3

Create a new hashring.

Options:

* name: the name of the ring, it defaults to 'hashring'. Needed if
you want to run mulitple hashrings into the same swim network.
* meta: all the metadata for the current node, it will be disseminated
across the gossip network.
* hashFunc: the hashing function you want to use, default to
farmhash.hash32.
* replicaPoints: the number of replica points each node would have.
Every node needs to have the same configuration for this value.
* host: the ip address the current node will use to advertise itself
on the swim network. Defaults to what is returned by
network-address.
* port: the port the current node will use to advertise itself
on the swim network. Randomly picked if not specified.
* base: an array of nodes that will be used to boostrap the swim
network. The value is what is returned by whoami().
* client: if you are writing an hashring client rather than a normal
peer. Defaults to false.

Events:

* 'up': when the node is up and running
* 'peerUp': when a peer that is part of the hashring gets online
* 'peerDown': when a peer that is part of the hashring gets offline
* 'move': when a part of the hashring is moved from the current peer
to another peer, relevant keys start, end, to.
* 'steal': when a part of the hashring is stolen by the current peer
from another peer, relevant keys start, end, from.
* 'error': when an error occurs in the swim instance.

$3

Lookup the peer handling a given key, which it can be a String, a
Buffer or an integer. The integer needs to be the result of
instance.hash(key).

It returns:

`js
{
id: '192.168.0.1',
meta: {
// all metadata specified in
},
points: [
// n integers, where n is the number of replica points
]
}
`

$3

Lookup the next peer in the hashring for the given key. It is possible
to specify a skip list of ids of peers. Because of the skip list, it
is possible to implement a circuit breaker
to avoid messages that keeps flowing in infinite loops.

It returns:

`js
{
id: '192.168.0.1',
meta: {
// all metadata specified in
},
points: [
// n integers, where n is the number of replica points
]
}
`

$3

The id of the current peer. It will throw if the node has not emitted
'up' yet.

$3

It returns the info of the current node in the same format of
lookup().

$3

Similar to lookup(key), but returns true or false
depending if the given key has been allocated to this node or not.

$3

Hashes the given key using the same hash function used to calculate
replica points. It returns an integer.

$3

All the other peers, in the format of lookup.
if myself is set to true`, the current instance is returned as
well.

$3

Close the instance, detaching it from the gossip network.

License

MIT