Class: GossipRing

Clusterluck.GossipRing(kernel, chash, vclock, opts)

GossipRing GossipRing

Constructor

new GossipRing(kernel, chash, vclock, opts)

Gossip ring implementation. Maintains a consistent hash ring to manage cluster membership and external connections in the netkernel. Maintains a vector clock to compare the most up-to-date information about the cluster. Listens for messages from the netkernel about cluster joins/departures/updates, with an internal map to register message streams. On an interval, sends messages to the cluster about current state and trims it's internal vector clock. To handle vector clock conflicts, which are possible in this architecture, a LWW approach is adopted. This is largely because insertions/deletions (the deciding factor for LWW) are centralized from a task-management standpoint (the system administrator will be the one administering these operations), therefore time is a practically controllable dimension. In addition, for future work, metrics will be emitted on a routine basis from the same source (a node sharing work-load information across the cluster), meaning any conflict that occurs with this data can easily be resolved.

Parameters:
Name Type Description
kernel Clusterluck.NetKernel

Network kernel to communicate with other nodes.
chash Clusterluck.CHash

Consistent hash ring to represent cluster membership.
vclock Clusterluck.VectorClock

Vector clock to represent current state of ring relative to other nodes in the cluster.
opts Object

Options object for state management.

Properties
Name Type Description
interval Number

Internval in ms to send ring to members of cluster.
wquorum Number

Write quorum for distributed writes. Prototypical member of this class.
vclockOpts Object

Options for periodic trimming of internal vector clock.
connOpts Object

Options for whe connecting to new nodes.
Source:

Methods

actor(actoropt) → {String}

Acts as a getter/setter for the current actor of this instance.

Parameters:
Name Type Attributes Description
actor String <optional>

Actor to set on this instance.
Source:
Returns:

Actor of this instance.

Type
String

find(data, sizeopt) → {Array}

Finds the bucket of this instance's hash ring that data routes to, based on the nodes the corresponding node replicates to. This differs from range in that range provides replication on a per-key basis, whereas with find any data routed to node has the same replicants.

Parameters:
Name Type Attributes Description
data Buffer | String

Data to find hash bucket of.
size Number <optional>

Number of elements to return in bucket.
Source:
Returns:

Array of nodes responsible for the bucket data hashes to.

Type
Array

flush() → {Clusterluck.GossipRing}

Function that executes on this cluster's internal flush interval. Flushes this node's ring state to disk.

Source:
Fires:
Returns:

This instance.

Type
Clusterluck.GossipRing

insert(node, weight, forceopt) → {Clusterluck.GossipRing}

Inserts node into this node's cluster, asynchronously propagating this new state through the cluster. Provides the option to forcibly insert node, meaning it will precede any existing internal message streams pending completion.

Parameters:
Name Type Attributes Description
node Clusterluck.Node

Node to insert into this gossip ring's cluster.
weight Number

Number of virtual nodes to assign to node.
force Boolean <optional>

Whether to forcibly add node into the current state of this ring, or wait for an idle state. Defaults to false.
Source:
Fires:
Listens to Events:
Returns:

This instance.

Type
Clusterluck.GossipRing

join(ringID) → {Clusterluck.GossipRing}

Joins the ring ringID if not already a member of a ring. Otherwise, will return an error noting that this instance already belongs to a ring.

Parameters:
Name Type Description
ringID String

Ring ID for this node to join.
Source:
Listens to Events:
Returns:

This instance.

Type
Clusterluck.GossipRing

leave(forceopt) → {Clusterluck.GossipRing}

Leaves the current cluster, removing all nodes from it's hash ring and creating a new vector clock for this new ring. Triggers the removal of this ring's message handler on the network kernel. Provides the option to forcibly leave the cluster, meaning this function won't wait for an idle state to execute and execute immediately. Otherwise, will wait for message streams to complete.

Parameters:
Name Type Attributes Description
force Boolean <optional>

Whether to forcibly leave this ring or not. If false, will wait for an idle state before leaving the ring and clearing the internal message stream map. Otherwise, will immediately clear any pending updates and leave the ring. Defaults to false.
Source:
Fires:
Listens to Events:
Returns:

This instance.

Type
Clusterluck.GossipRing

load(cb)

Loads existing gossip ring from disk. If no path is specified or the file does not exist, we simple do nothing. Otherwise, the result JSON is parsed read into this instance's hash ring, vector clock, ring ID, and current actor.

Parameters:
Name Type Description
cb function

Called when loading state has finished. On error, will operate as cb(err). Otherwise, will operate as cb().
Source:

meet(node) → {Clusterluck.GossipRing}

Joins the cluster present at node, using it as a seed node for inserting this instance's node identifier in to the cluster. This process occurs asynchronously, thus this node's cluster state won't be updated until future rounds of gossip.

Parameters:
Name Type Description
node Clusterluck.Node

Node to seed ring-join with.
Source:
Fires:
Returns:

This instance.

Type
Clusterluck.GossipRing

minsert(nodes, weight, forceopt) → {Clusterluck.GossipRing}

Inserts nodes into this node's cluster, asynchronously propagating this new state through the cluster. Provides the option to forcibly insert nodes, meaning it will precede any existing internal message streams pending completion.

Parameters:
Name Type Attributes Description
nodes Array

Nodes to insert into this gossip ring's cluster.
weight Number

Number of virtual nodes to assign to each node in nodes.
force Boolean <optional>

Whether to forcibly add nodes into the current state of this ring, or wait for an idle state. Defaults to false.
Source:
Fires:
Listens to Events:
Returns:

This instance.

Type
Clusterluck.GossipRing

mremove(nodes, forceopt) → {Clusterluck.GossipRing}

Removes nodes from this node's cluster, asynchronously propagating this new state through the cluster. Provides the option to forcibly remove nodes, meaning it will precede any existing internal message streams pending completion.

Parameters:
Name Type Attributes Description
nodes Array

Nodes to remove from this gossip ring's cluster.
force Boolean <optional>

Whether to forcibly remove nodes from the current state of this ring, or wait for an idle state. Defaults to false.
Source:
Fires:
Listens to Events:
Returns:

This instance.

Type
Clusterluck.GossipRing

pause() → {Clusterluck.GossipRing}

Pauses the GossipRing's message processing. As a reuslt, any messages routed from the network kernel to this instance will be missed until this.resume() is called.

Source:
Fires:
Returns:

This instance.

Type
Clusterluck.GossipRing

poll() → {Clusterluck.GossipRing}

Function that executes on this cluster's internal interval. Trims this instance's vector clock and sends the ring to random recipients in the cluster.

Source:
Returns:

This instance.

Type
Clusterluck.GossipRing

range(data, sizeopt) → {Array}

Finds the bucket of this instance's hash ring that data routes to, based on a per-key replication strategy. This differs from find in that find provides per-node replication, where as with range every key has it's own set of nodes for replication.

Parameters:
Name Type Attributes Description
data Buffer | String

Data to find hash bucket of.
size Number <optional>

Number of elements to return in bucket.
Source:
Returns:

Array of nodes responsible for the bucket data hashes to.

Type
Array

remove(node, forceopt) → {Clusterluck.GossipRing}

Removes node from this node's cluster, asynchronously propagating this new state through the cluster. Provides the option to forcibly remove node, meaning it will precede any existing internal message streams pending completion.

Parameters:
Name Type Attributes Description
node Node

Node to remove from this gossip ring's cluster.
force Boolean <optional>

Whether to forcibly remove node from the current state of this ring, or wait for an idle state. Defaults to false.
Source:
Fires:
Listens to Events:
Returns:

This instance.

Type
Clusterluck.GossipRing

resume() → {Clusterluck.GossipRing}

Resumes the processing of message streams on this instance. Any messages missed in between pausing and now will result in failed message parsing (since all JSON contents are sent in one message).

Source:
Fires:
Listens to Events:
Returns:

This instance.

Type
Clusterluck.GossipRing

ring(ringopt) → {Clusterluck.CHash}

Acts as a getter/setter for the hash ring of this instance.

Parameters:
Name Type Attributes Description
ring Clusterluck.CHash <optional>

Consistent hash ring to set on this instance.
Source:
Returns:

Consistent hash ring of this instance.

Type
Clusterluck.CHash

ringID(ringopt) → {String}

Acts as a getter/setter for the ring ID of this instance.

Parameters:
Name Type Attributes Description
ring String <optional>

Ring ID to set on this instance.
Source:
Returns:

Ring ID of this instance.

Type
String

route(nodes, event, msg, actor, clock, nopt) → {Clusterluck.GossipRing}

Sends event of this ring at round n with message msg, sending it to nodes if the round number is greater than zero.

Parameters:
Name Type Attributes Description
nodes Array

Nodes to send this message to.
event String

Event to send.
msg Object

Value to send with this message.
actor String

Actor representing the snapshot of this message.
clock Clusterluck.VectorClock

Vector clock to send this message with.
n Number <optional>

Gossip round of this message. Defaults to 1.
Source:
Fires:
Returns:

This instance.

Type
Clusterluck.GossipRing

selectRandom(nopt) → {Array}

Selects n random nodes, different than this node, from it's hash ring.

Parameters:
Name Type Attributes Description
n Number <optional>

Number of nodes to randomly select from this ring. Defaults to 1.
Source:
Returns:

Array of nodes selected from this instance's hash ring.

Type
Array

selectRandomFrom(nodes, nopt) → {Array}

Selects n random nodes from a list of nodes.

Parameters:
Name Type Attributes Description
nodes Array

Array of nodes to select random nodes from.
n Number <optional>

Number of nodes to randomly select from this ring. Defaults to 1.
Source:
Returns:

Array of nodes selected.

Type
Array

send(event, msg, actor, clock, nopt) → {Clusterluck.GossipRing}

Sends event of this ring at round n with message msg, selecting several nodes to propagate this gossip message to if the round number is non-zero.

Parameters:
Name Type Attributes Description
event String

Event to send.
msg Object

Value to send with this message.
actor String

Actor representing the snapshot of this message.
clock Clusterluck.VectorClock

Vector clock to send this message with.
n Number <optional>

Gossip round of this message. Defaults to 1.
Source:
Returns:

This instance.

Type
Clusterluck.GossipRing

sendRing(nopt) → {Clusterluck.GossipRing}

Sends the state of this ring at round n as type 'update', selecting several nodes to propagate this gossip message to if the round number is non-zero and the internal ring is non-trivial.

Parameters:
Name Type Attributes Description
n Number <optional>

Number of rounds to send this data in the cluster. Defauls to 1.
Source:
Returns:

This instance.

Type
Clusterluck.GossipRing

start(ringID) → {Clusterluck.GossipRing}

Starts the gossip handler: listens for events related to ringID on the netkernel, and sets the internal interval to send messages about this instance's state. When this process leaves the current ring ID, will remove the previously created kernel event listener.

Parameters:
Name Type Description
ringID String

Ring ID to listen for events on.
Source:
Listens to Events:
Returns:

This instance.

Type
Clusterluck.GossipRing

stop(forceopt) → {Clusterluck.GossipRing}

Stops this handler. Provides the option to forcibly stop, meaning all internal message streams will be cleared and this node will immediately leave it's current cluster.

Parameters:
Name Type Attributes Description
force Boolean <optional>

Whether to forcibly stop this process. If false, will wait for an idle state before leaving the ring and clearing the internal message stream map. Otherwise, will immediately clear any pending updates and leave the ring. Defaults to false.
Source:
Fires:
Listens to Events:
Returns:

This instance.

Type
Clusterluck.GossipRing

update(node, weight, forceopt) → {Clusterluck.GossipRing}

Updates node in this node's cluster with weight weight, asynchronously propagating this new state through the cluster. Provides the option to forcibly update node, meaning it will precede any existing internal message streams pending completion.

Parameters:
Name Type Attributes Description
node Clusterluck.Node

Node to update in this gossip ring's cluster.
weight Number

Number of virtual nodes to assign node in the hash ring.
force Boolean <optional>

Whether to forcibly update node into the current state of this ring, or wait for an idle state. Defaults to false.
Source:
Fires:
Listens to Events:
Returns:

This instance.

Type
Clusterluck.GossipRing

vclock(vclockopt) → {Clusterluck.VectorClock}

Acts as a getter/setter for the vector clock of this instance.

Parameters:
Name Type Attributes Description
vclock Clusterluck.VectorClock <optional>

Vector clock to set on this instance.
Source:
Returns:

Vector clock of this instance.

Type
Clusterluck.VectorClock

Events

GossipRing:close

Emitted when this instance has left it's current ring, overwritten it's ring ID to null, and disconnected from all other nodes in the cluster.

Source:
Listeners of This Event:

GossipRing:conflict

Emitted when the ring state of another node, based off a received message off the network kernel, is in conflict with the current state of this instance. More for documenting purposes in this class, since all ring conflicts are handled with a "Last Write Wins" approach. However, in any new classes that may use similar logic to this, will be useful for custom state conflict.

Properties:
Name Type Description
RecRing Clusterluck.CHash

Received ring in conflict with the current ring.
RecClock Clusterluck.VectorClock

Received vector clock conflicting with the current vector clock.
Source:

GossipRing:flushing

Emitted when this instance begins to flush state to disk. NOT a reliable indicator for when state is actually flushed to disk, as this event is fired whenever this.flush() is called (as opposed to firing when it makes an fs call).

Source:

GossipRing:leave

Emitted when the ring state on this instance has been cleared, and the resulting ring with this node removed has been sent.

Properties:
Name Type Description
sendRing Clusterluck.CHash

Ring that will be sent to all nodes in the old cluster except this node (since we're leaving when this event has fired).
Source:

GossipRing:process

Emitted whenever this instance changes it's consistent hash ring, either based on events generated by the CLI or
by gossipped messages.

Properties:
Name Type Description
oldRing Clusterluck.CHash

Previous ring before this event is fired.
currRing Clusterluck.CHash

Current ring when this event is fired.
Source:

GossipRing:ring

Event emitted when any ring updates occur and are gossipped around the cluster. Since the GossipRing class extends the GenServer class, this event is emitted whenever a message stream is parsed with event "ring".

Type:
  • Object
Properties:
Name Type Description
data Clusterluck.CHash

Consistent hash ring sent with this ring update message.
vclock Clusterluck.VectorClock

Vector clock associated with this message. Based on comparison between this value and this instance's own vector clock, the message may be ignored.
actor String

Actor associated with the most recent update to vclock.
type String

Update type. Can be either "join" (meet request) or "update" (anything else).
Source:
Listeners of This Event:

GossipRing:send

Emitted whenever this instance sends a message to another node in the cluster.

Properties:
Name Type Description
vclock Clusterluck.VectorClock

Vector clock of message sent.
event String

Event name of message sent.
msg Object

Message contents.
Source: