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()

hashring(opts)

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](http://npm.im/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.

instance.lookup(key)

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:

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

instance.next(key[, skip])

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:

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

instance.whoami()

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

instance.mymeta()

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

instance.allocatedToMe(key)

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

instance.hash(key)

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

instance.peers(myself)

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

instance.close()

Close the instance, detaching it from the gossip network.

License

MIT