Namespace: Clusterluck

Clusterluck

Source:

Classes

CHash
ClusterNode
Connection
DLMServer
DSMServer
DTable
GenServer
GossipRing
Lock
MTable
NetKernel
Node
Semaphore
VectorClock

Methods

(static) createCHash(rfactor, pfactor) → {Clusterluck.CHash}

Constructs a new instance of the consistent hash ring class.

Parameters:
Name Type Description
rfactor Number

Replication factor for every node inserted into the ring. Defaults to 3.
pfactor Number

Persistence factor for every node inserted into the ring (used when calling .next on a consistent hash ring). Defaults to 2.
Source:
Returns:

A consistent hash ring instance.

Type
Clusterluck.CHash
Example
let chash = clusterluck.createCHash(3, 2);
assert.equal(chash.rfactor(), 3);
assert.equal(chash.pfactor(), 2);

(static) createCluster(Identifier, host, port, optsopt) → {Clusterluck.ClusterNode}

Constructs an instance of a cluster node, the preferred and encompassing way to start/stop the underlying IPC node, as well as refer to underlying actors in the cluster (gossip ring, kernel, command server, forthcoming actors, etc.).

Parameters:
Name Type Attributes Description
Identifier String

for the node associated with this network kernel. Needs to be unique across the cluster, since nodes are addressed by id this way.
host String

Hostname for this network kernel to bind to. Can be an IPV4 address, IPV6 address, or a hostname. Hostname resolution isn't done when checking the existence of a node inside a cluster, so this hostname is taken literally for the lifetime of the node (i.e. localhost vs. 127.0.0.1 vs > hostname). Defaults to os.hostname().
port Number

Port for this network kernel to listen on. Defaults to 7022.
opts Object <optional>

Options object that controls configuration options for the constructed network kernel and gossip ring.

Properties
Name Type Attributes Description
kernelOpts Object <optional>

Refer to createKernel for an explanation of available options.
gossipOpts Object <optional>

Refer to createGossip for an explanation of available options.
Source:
Returns:

A new cluster node instance.

Type
Clusterluck.ClusterNode
Example
let node = clusterluck.createCluster("foo", "localhost", 7022);
assert.equal(node.kernel().id(), "foo");
assert.equal(node.kernel().host(), "localhost");
assert.equal(node.kernel().port(), 7022);
assert.ok(node.kernel().self().equals(new Node("foo", "localhost", 7022)));
assert.equal(node.gossip().ring().rfactor(), 3);
assert.equal(node.gossip().ring().pfactor(), 2);

(static) createCommServer(gossip, kernel) → {Clusterluck.CommandServer}

Constructs an instance of a command server, which responds to CLI commands.

Parameters:
Name Type Description
gossip Clusterluck.Gossip

Gossip processor for this command server to report/manipulate the state of.
kernel Clusterluck.Kernel

Network kernel this command server uses to reply over to a CLI process' IPC socket.
Source:
Returns:

A new command server instance.

Type
Clusterluck.CommandServer
Example
let comms = clusterluck.createCommServer(gossip, kernel);
assert.deepEqual(comms.gossip(), gossip);
assert.deepEqual(comms.kernel(), kernel);

(static) createDLM(cluster, optsopt) → {Clusterluck.DLMServer}

Constructs a DLM server instance. Handles creating read locks, write locks, as well as removing such locks across a cluster of nodes. See documentation of the DLMServer class for how locks are routed and partitioned across the cluster.

Parameters:
Name Type Attributes Description
cluster Clusterluck.ClusterNode

Cluster for this generic server to bind to.
opts Object <optional>

Options object for creating DLM server.

Properties
Name Type Attributes Description
rquorum Number <optional>

Quorum for read lock requests.
wquorum Number <optional>

Quorum for write lock requests.
minWaitTimeout Number <optional>

Minimum amount of time in milliseconds to wait for a retry on a locking request.
maxWaitTimeout Number <optional>

Maximum amount of time in milliseconds to wait for a retry on a locking request.
disk Boolean <optional>

Whether to persist lock state to disk. If true is passed, the following options will be read.
path String <optional>

Path for underlying DTable instance to flush state to.
writeThreshold Number <optional>

Write threshold of underlying DTable instance.
autoSave Number <optional>

Autosave interval of underlying DTable instance.
fsyncInterval Number <optional>

Fsync interval of underlying DTable instance.
compress Boolean <optional>

Whether to run RDB snapshot streams through a GZIP compression stream. Defaults to false.
name String <optional>

Name to start table with; can be used as a replacement for passing name to the start function. Required to be passed if you don't want a race condition between table loads and the idle interval that runs to trigger RDB snapshot logic. Defaults to undefined.
Source:
Returns:

A new generic server instance.

Type
Clusterluck.DLMServer
Example
let server = clusterluck.createDLM(cluster, {disk: true, path: "/path/to/dir"});
server.load((err) => {
  server.start("foo");
});

(static) createDSM(cluster, optsopt) → {Clusterluck.DSMServer}

Constructs a DSM server instance. Handles creating/reading/destroying semaphores, as well as posting and closing semaphores with requesters/actors. See documentation of the DSMServer class for how semaphores are routed and partitioned across the cluster.

Parameters:
Name Type Attributes Description
cluster Clusterluck.ClusterNode

Cluster for this generic server to bind to.
opts Object <optional>

Options object for creating DSM server.

Properties
Name Type Attributes Description
minWaitTimeout Number <optional>

Minimum amount of time in milliseconds to wait for a retry on a post request.
maxWaitTimeout Number <optional>

Maximum amount of time in milliseconds to wait for a retry on a post request.
disk Boolean <optional>

Whether to persist semaphore state to disk. If true is passed, the following options will be read.
path String <optional>

Path for underlying DTable instance to flush state to.
writeThreshold Number <optional>

Write threshold of underlying DTable instance.
autoSave Number <optional>

Autosave interval of underlying DTable instance.
fsyncInterval Number <optional>

Fsync interval of underlying DTable instance.
compress Boolean <optional>

Whether to run RDB snapshot streams through a GZIP compression stream. Defaults to false.
name String <optional>

Name to start table with; can be used as a replacement for passing name to the start function. Required to be passed if you don't want a race condition between table loads and the idle interval that runs to trigger RDB snapshot logic. Defaults to undefined.
Source:
Returns:

A new generic server instance.

Type
Clusterluck.DSMServer
Example
let server = clusterluck.createDSM(cluster, {disk: true, path: "/path/to/dir"});
server.load((err) => {
  server.start("foo");
});

(static) createDTable(opts) → {Clusterluck.DTable}

Constructs a dtable instance, an in-memory key/value storage that persists to disk periodically.

Parameters:
Name Type Description
opts Object

Options object for creating dtable.

Properties
Name Type Attributes Description
path String

Directory store table snapshot and log files under.
writeThreshold Number <optional>

Number of write operations to the log file before triggering a snapshot flush to disk. Defaults to 100 writes.
autoSave Number <optional>

Number of milliseconds this table will wait in an idle state before triggering a snapshot flush to disk. Defaults to 180000 milliseconds.
fsyncInterval Number <optional>

Internval in milliseconds to fsync the log file. Defaults to 1000 milliseconds.
compress Boolean <optional>

Whether to run RDB snapshot streams through a GZIP compression stream. Defaults to false.
encodeFn function <optional>

Encoding function to use when serializing writes to the AOF file and when saving to the RDB snapshot. Defaults to DTable.encodeValue.
decodeFn function <optional>

Decoding function to use when loading contents from disk. Defaults to DTable.decodeValue.
name String <optional>

Name to start table with; can be used as a replacement for passing name to the start function. Required to be passed if you don't want a race condition between table loads and the idle interval that runs to trigger RDB snapshot logic. Defaults to undefined.
Source:
Returns:

A new dtable instance.

Type
Clusterluck.DTable
Examples
let table = clusterluck.createDTable({
  path: "/path/to/dir",
  writeThreshold: 100,
  autoSave: 180000,
  fsyncInterval: 1000
});
table.start("foo");
let table = clusterluck.createDTable({
  path: "/path/to/dir",
  writeThreshold: 100,
  autoSave: 180000,
  fsyncInterval: 1000,
  name: "TABLE_NAME"
});
table.load((err) => {
  if (err) process.exit(1);
  table.start();
});

(static) createGenServer(cluster, optsopt) → {Clusterluck.GenServer}

Constructs a generic server instance. Generic servers listen to the network kernel for events targetted at it's name/ID. For example, the gossip ring is a generic server that listens for events on the ID of the ring it belongs to.

Parameters:
Name Type Attributes Description
cluster Clusterluck.ClusterNode

Cluster for this generic server to bind to.
opts Object <optional>

Options object for creating generic server.

Properties
Name Type Attributes Description
streamTimeout Number <optional>

Timeframe a generic server will receive data for a given stream before invalidating it.
Source:
Returns:

A new generic server instance.

Type
Clusterluck.GenServer
Example
let server = clusterluck.createGenServer(cluster);
// based on how messages are parsed, will operate on event 'command_name' sent by another actor to this node
server.on("command_name", handlerForCommand);
// will listen on server.kernel() for messages emitted on event 'foo'.
server.start("foo");

(static) createGossip(kernel, optsopt) → {Clusterluck.GossipRing}

Constructs an instance of a gossip processor against network kernel kernel.

Parameters:
Name Type Attributes Description
kernel Clusterluck.NetKernel

Network kernel this new gossip processor instance will listen for jobs against.
opts Object <optional>

Gossip ring options to instantiate with. Affects vector clock trimming options, consistent hash ring instantiation, how often to gossip ring state against the cluster, and when/where to flush state to disk.

Properties
Name Type Attributes Description
rfactor Number <optional>

Replication factor for every node inserted into the ring. Defaults to 3.
pfactor Number <optional>

Persistence factor for every node inserted into the ring (used when calling .next on a consistent hash ring). Defaults to 2.
interval Number <optional>

Interval to select a random node from the cluster and gossip the state of the ring with, with a granularity of milliseconds. Defaults to 1000.
flushInterval Number <optional>

Interval to flush the state of the ring to disk, with a granularity of milliseconds. Defaults to 1000.
flushPath String <optional>

Path string to flush the state of the ring to; if set to null, the gossip ring will just skip flushing state to disk. Defaults to null.
vclockOpts Object <optional>

Vector clock options for trimming; occurs at the same interval as interval. Defaults to clusterluck.consts.vclockOpts.
connOpts Object <optional>

Connection options for when connecting to new nodes.
Source:
Returns:

A new gossip ring instance.

Type
Clusterluck.GossipRing
Example
// initializes gossip ring with defaults found in `clusterluck.consts.gossipOpts`
let gossip = clusterluck.createGossip(kernel);
assert.equal(gossip.ring().rfactor(), 3);
assert.equal(gossip.ring().pfactor(), 2);
assert.deepEqual(gossip.kernel(), kernel);

(static) createKernel(id, host, port, optsopt) → {Clusterluck.NetKernel}

Constructs an instance of a network kernel with id, listening on hostname host and port port.

Parameters:
Name Type Attributes Description
id String

Identifier for the node associated with this network kernel. Needs to be unique across the cluster, since nodes are addressed by id this way.
host String

Hostname for this network kernel to bind to. Can be an IPV4 address, IPV6 address, or a hostname. Hostname resolution isn't done when checking the existence of a node inside a cluster, so this hostname is taken literally for the lifetime of the node (i.e. localhost vs. 127.0.0.1 vs > hostname). Defaults to os.hostname().
port Number

Port for this network kernel to listen on. Defaults to 7022.
opts Object <optional>

Network kernel options to instantiate with. Affects whether the server runs with TLS or just TCP, on what interval to attempt reconnect logic on a closed socket, and how many times to retry.

Properties
Name Type Attributes Description
networkHost String <optional>

Default network hostname to set on this network kernel. Defaults to os.hostname().
networkPort Number <optional>

Default network port to listen on for this network kernel. Defaults to 7022.
retry Number <optional>

Default amount of time to wait before retrying a connection attempt between two nodes. Defaults to 5000.
tls Object <optional>

TLS options to set on this network kernel. Defaults to null.
maxRetries Number <optional>

Maximum number of attempts to reconnect to a node; currently, Infinity is the most stable option, since the Connection class only listens for the 'connect' and 'disconnect' events on the underlying IPC socket. Defaults to Infinity.
silent Boolean <optional>

Whether to silence underlying IPC logs emitted by the node-ipc module. Defaults to true.
Source:
Returns:

A new network kernel instance.

Type
Clusterluck.NetKernel
Example
let kernel = clusterluck.createKernel("foo", "localhost", 7022);
assert.equal(kernel.id(), "foo");
assert.equal(kernel.host(), "localhost");
assert.equal(kernel.port(), 7022);
assert.ok(kernel.self().equals(new Node("foo", "localhost", 7022)));

(static) createMTable() → {Clusterluck.MTable}

Constructs a mtable instance, an in-memory key/value storage.

Source:
Returns:

A new mtable instance.

Type
Clusterluck.MTable
Example
let table = clusterluck.createMTable();
table.start("foo");

(static) createVClock(id, count) → {Clusterluck.VectorClock}

Constructs a new instance of the vector clock class.

Parameters:
Name Type Description
id String

Identifier to insert this new vector clock on creation.
count Number

Count to initialize id at in this new vector clock.
Source:
Returns:

A vector clock instance.

Type
Clusterluck.VectorClock
Example
let vclock = clusterluck.createVClock();
assert.equal(vclock.size(), 0);
vclock = clutserluck.createVClock("id", 1);
assert.equal(vclock.size(), 1);
assert.ok(vclock.has("id"));