@joblift/node-zookeeper-client
Advanced tools
A pure Javascript ZooKeeper client module for Node.js.
This module is designed to resemble the ZooKeeper Java client API but with tweaks to follow the convention of Node.js modules. Developers that are familiar with the ZooKeeper Java client would be able to pick it up quickly.
This module has been tested to work with ZooKeeper version 3.4.*.
You can install it using npm:
$ npm install node-zookeeper-client
1. Create a node using given path:
var zookeeper = require('node-zookeeper-client');
var client = zookeeper.createClient('localhost:2181');
var path = process.argv[2];
client.once('connected', function () {
console.log('Connected to the server.');
client.create(path, function (error) {
if (error) {
console.log('Failed to create node: %s due to: %s.', path, error);
} else {
console.log('Node: %s is successfully created.', path);
}
client.close();
});
});
client.connect();
2. List and watch the children of given node:
var zookeeper = require('node-zookeeper-client');
var client = zookeeper.createClient('localhost:2181');
var path = process.argv[2];
function listChildren(client, path) {
client.getChildren(
path,
function (event) {
console.log('Got watcher event: %s', event);
listChildren(client, path);
},
function (error, children, stat) {
if (error) {
console.log(
'Failed to list children of %s due to: %s.',
path,
error
);
return;
}
console.log('Children of %s are: %j.', path, children);
}
);
}
client.once('connected', function () {
console.log('Connected to ZooKeeper.');
listChildren(client, path);
});
client.connect();
More examples can be found here.
Factory method to create a new zookeeper client instance.
Arguments
connectionString String - Comma separated host:port pairs, each
represents a ZooKeeper server. You can optionally append a chroot path, then
the client would be rooted at the given path. e.g.
'localhost:3000,locahost:3001,localhost:3002'
'localhost:2181,localhost:2182/test'
options Object - An object to set the client options. Currently available
options are:
sessionTimeout Session timeout in milliseconds, defaults to 30 seconds.spinDelay The delay (in milliseconds) between each connection attempts.retries The number of retry attempts for connection loss exception.Defaults options:
{
sessionTimeout: 30000,
spinDelay : 1000,
retries : 0
}
Example
var client = zookeeper.createClient(
'localhost:2181/test',
{ sessionTimeout: 10000 }
);
This is the main class of ZooKeeper client module. An application must
use createClient method to
instantiate the client.
Once a connection from the client to the server is established, a session id is assigned to the client. The client will starts sending heart beats to the server periodically to keep the session valid.
If the client fails to send heart beats to the server for a prolonged period of time (exceeding the sessionTimeout value), the server will expire the session. The client object will no longer be usable.
If the ZooKeeper server the client currently connects to fails or otherwise does not respond, the client will automatically try to connect to another server before its session times out. If successful, the application can continue to use the client.
This class inherits from events.EventEmitter class, see Event for details.
Initiate the connection to the provided server list (ensemble). The client will pick an arbitrary server from the list and attempt to connect to it. If the establishment of the connection fails, another server will be tried (picked randomly) until a connection is established or close method is invoked.
Close this client. Once the client is closed, its session becomes invalid. All the ephemeral nodes in the ZooKeeper server associated with the session will be removed. The watchers left on those nodes (and on their parents) will be triggered.
Create a node with given path, data, acls and mode.
Arguments
String - Path of the node.Buffer - The data buffer, optional, defaults to null.Array - An array of ACL objects, optional, defaults to
ACL.OPEN_ACL_UNSAFECreateMode - The creation mode, optional, defaults to
CreateMode.PERSISTENTFunction - The callback function.Example
zookeeper.create(
'/test/demo',
new Buffer('data'),
CreateMode.EPHEMERAL,
function (error, path) {
if (error) {
console.log(error.stack);
return;
}
console.log('Node: %s is created.', path);
}
);
Delete a node with the given path and version. If version is provided and not equal to -1, the request will fail when the provided version does not match the server version.
Arguments
String - Path of the node.Number - The version of the node, optional, defaults to -1.Function - The callback function.Example
zookeeper.remove('/test/demo', -1, function (error) {
if (error) {
console.log(error.stack);
return;
}
console.log('Node is deleted.');
});
Check the existence of a node. The callback will be invoked with the
stat of the given path, or null if no such node exists.
If the watcher function is provided and the operation is successful (no error), a watcher will be placed on the node with the given path. The watcher will be triggered by a successful operation that creates the node, deletes the node or sets the data on the node.
Arguments
String - Path of the node.Function - The watcher function, optional. The event is an
instance of EventFunction - The callback function. The stat is an
instance of Stat.Example
zookeeper.exists('/test/demo', function (error, stat) {
if (error) {
console.log(error.stack);
return;
}
if (stat) {
console.log('Node exists.');
} else {
console.log('Node does not exist.');
}
});
For the given node path, retrieve the children list and the stat. The children will be an unordered list of strings.
If the watcher callback is provided and the operation is successfully, a watcher will be placed the given node. The watcher will be triggered when an operation successfully deletes the given node or creates/deletes the child under it.
Arguments
String - Path of the node.Function - The watcher function, optional. The event is an
instance of EventFunction - The callback function. The
children is an array of strings and the stat is an instance of
Stat.Example
zookeeper.getChildren('/test/demo', function (error, children, stats) {
if (error) {
console.log(error.stack);
return;
}
console.log('Children are: %j.', children);
});
Retrieve the data and the stat of the node of the given path. If the watcher function is provided and the operation is successful (no error), a watcher will be placed on the node with the given path. The watch will be triggered by a successful operation which sets data on the node, or deletes the node.
Arguments
String - Path of the node.Function - The watcher function, optional. The event is an
instance of EventFunction - The callback function. The data is
an instance of Buffer and stat is an
instance of Stat.Example
zookeeper.getData(
'/test/demo',
function (event) {
console.log('Got event: %s.', event);
},
function (error, data, stat) {
if (error) {
console.log(error.stack);
return;
}
console.log('Got data: %s', data.toString('utf8'));
}
);
Set the data for the node of the given path if such a node exists and the optional given version matches the version of the node (if the given version is -1, it matches any node's versions). The stat of the node will be returned through the callback function.
Arguments
String - Path of the node.Buffer - The data buffer.Number - The version of the node, optional, defaults to -1.Function - The callback function. The stat is an
instance of Stat.Example
zookeeper.setData('/test/demo', null, 2, function (error, stat) {
if (error) {
console.log(error.stack);
return;
}
console.log('Data is set.');
});
Retrieve the list of ACL and stat of the node of the given path.
Arguments
String - Path of the node.Function - The callback function. acls is an
array of ACL instances. The stat is an instance of
Stat.Example
zookeeper.getACL('/test/demo', function (error, acls, stat) {
if (error) {
console.log(error.stack);
return;
}
console.log('ACL(s) are: %j', acls);
});
Set the ACL for the node of the given path if such a node exists and the given version (optional) matches the version of the node on the server. (if the given version is -1, it matches any versions).
Arguments
String - Path of the node.Array - An array of ACL instances.Number - The version of the node, optional, defaults to -1.Function - The callback function. The stat is an
instance of Stat.Example
zookeeper.setACL(
'/test/demo',
[
new zookeeper.ACL(
zookeeeper.Permission.ADMIN,
new zookeeper.Id('ip', '127.0.0.1')
)
],
function (error, acls, stat) {
if (error) {
console.log(error.stack);
return;
}
console.log('New ACL is set.');
}
);
Create and return a new Transaction instance which provides a builder object that can be used to construct and commit a set of operations atomically.
See Transaction for details.
Example
var transaction = zookeeper.transaction();
Create given path in a way similar to mkdir -p.
Arguments
String - Path of the node.Buffer - The data buffer, optional, defaults to null.Array - An array of ACL objects, optional, defaults to
ACL.OPEN_ACL_UNSAFECreateMode - The creation mode, optional, defaults to
CreateMode.PERSISTENTFunction - The callback function.Example
zookeeper.mkdirp('/test/demo/1/2/3', function (error, path) {
if (error) {
console.log(error.stack);
return;
}
console.log('Node: %s is created.', path);
});
Add the specified scheme:auth information to this client.
Arguments
String - The authentication scheme.Buffer - The authentication data buffer.Example
zookeeper.addAuthInfo('ip', new Buffer('127.0.0.1'));
Return the current client state.
Example
var client = zookeeper.createClient({...});
var state = client.getState();
console.log('Current state is: %s', state);
Returns the session id of this client instance. The value returned is not valid until the client connects to a server and may change after a re-connect.
The id returned is a long integer stored into a 8 bytes
Buffer since Javascript does not support
long integer natively.
Example
var client = zookeeper.createClient({...});
var id = client.getSessionId();
console.log('Session id is: %s', id.toString('hex'));
Returns the session password of this client instance. The value returned is not valid until the client connects to a server and may change after a re-connect.
The value returned is an instance of
Buffer.
Example
var client = zookeeper.createClient({...});
var pwd = client.getSessionPassword();
Returns the negotiated session timeout (in milliseconds) for this client instance. The value returned is not valid until the client connects to a server and may change after a re-connect.
Example
var client = zookeeper.createClient({...});
var sessionTimeout = client.getSessionTimeout();
After the connect() method is invoked, the ZooKeeper client starts its
life cycle and transitions its state as described in the following diagram.
There are two ways to watch the client state changes:
1. Node.js convention: Register event listener on the specific event which interests you. The following is the list of events that can be watched:
connected - Client is connected and ready.connectedReadOnly - Client is connected to a readonly server.disconnected - The connection between client and server is dropped.expired - The client session is expired.authenticationFailed - Failed to authenticate with the server.Note: some events (e.g. connected or disconnected) maybe be emitted more
than once during the client life cycle.
Example
client.on('connected', function () {
console.log('Client state is changed to connected.');
});
2. Java client convention: Register one event listener on the state event
to watch all state transitions. The listener callback will be called with an
instance of the State class. The following is the list of exported state
instances:
State.CONNECTED - Client is connected and ready.State.CONNECTED_READ_ONLY - Client is connected to a readonly server.State.DISCONNECTED - The connection between client and server is dropped.State.EXPIRED - The client session is expired.State.AUTH_FAILED - Failed to authenticate with the server.client.on('state', function (state) {
if (state === zookeeper.State.SYNC_CONNECTED) {
console.log('Client state is changed to connected.');
}
});
Optionally, you can register watcher functions when calling
exists,
getChildren and
getData methods. The watcher function
will be called with an instance of Event.
Properties
There are four type of events are exposed as Event class properties.
NODE_CREATED - Watched node is created.NODE_DELETED - watched node is deleted.NODE_DATA_CHANGED - Data of watched node is changed.NODE_CHILDREN_CHANGED - Children of watched node is changed.Return the type of the event.
Return the name of the event.
Return the path of the event.
Return a string representation of the event.
Transaction provides a builder interface to construct and commit a set of operations atomically.
Example
var client = zookeeper.createClient(process.argv[2] || 'localhost:2181');
client.once('connected', function () {
client.transaction().
create('/txn').
create('/txn/1', new Buffer('transaction')).
setData('/txn/1', new Buffer('test'), -1).
check('/txn/1').
remove('/txn/1', -1).
remove('/txn').
commit(function (error, results) {
if (error) {
console.log(
'Failed to execute the transaction: %s, results: %j',
error,
results
);
return;
}
console.log('Transaction completed.');
client.close();
});
});
client.connect();
Add a create operation with given path, data, acls and mode.
Arguments
String - Path of the node.Buffer - The data buffer, optional, defaults to null.Array - An array of ACL objects, optional, defaults to
ACL.OPEN_ACL_UNSAFECreateMode - The creation mode, optional, defaults to
CreateMode.PERSISTENTAdd a set-data operation with the given path, data and optional version.
Arguments
String - Path of the node.Buffer - The data buffer, or null.Number - The version of the node, optional, defaults to -1.Add a check (existence) operation with given path and optional version.
Arguments
String - Path of the node.Number - The version of the node, optional, defaults to -1.Add a delete operation with the given path and optional version.
Arguments
String - Path of the node.Number - The version of the node, optional, defaults to -1.Execute the transaction atomically.
Arguments
Function - The callback function.If the requested operation fails due to reason related to ZooKeeper, the error
which is passed into callback function will be an instance of Exception class.
The exception can be identified through its error code, the following is the
list of error codes that are exported through Exception class.
Exception.OKException.SYSTEM_ERRORException.RUNTIME_INCONSISTENCYException.DATA_INCONSISTENCYException.CONNECTION_LOSSException.MARSHALLING_ERRORException.UNIMPLEMENTEDException.OPERATION_TIMEOUTException.BAD_ARGUMENTSException.API_ERRORException.NO_NODEException.NO_AUTHException.BAD_VERSIONException.NO_CHILDREN_FOR_EPHEMERALSException.NODE_EXISTSException.NOT_EMPTYException.SESSION_EXPIREDException.INVALID_CALLBACKException.INVALID_ACLException.AUTH_FAILEDExample
zookeeper.create('/test/demo', function (error, path) {
if (error) {
if (error.getCode() == zookeeper.Exception.NODE_EXISTS) {
console.log('Node exists.');
} else {
console.log(error.stack);
}
return;
}
console.log('Node: %s is created.', path);
});
Return the error code of the exception.
Return the associated node path of the exception. The path can be undefined
if the exception is not related to node.
--
Return the exception name as defined in aforementioned list.
Return the exception in a readable string.
This module depends on the following third-party libraries:
This module is licensed under MIT License
FAQs
A pure Javascript ZooKeeper client for Node.js.
The npm package @joblift/node-zookeeper-client receives a total of 3 weekly downloads. As such, @joblift/node-zookeeper-client popularity was classified as not popular.
We found that @joblift/node-zookeeper-client demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.