ZK is a high-level interface to the Apache ZooKeeper server. It is based on the zookeeper gem which is a multi-Ruby low-level driver. Currently MRI 1.8.7, 1.9.2, and JRuby are supported (rubinius 1.2 is experimental but should work). It is licensed under the MIT license.
Note: 1.9.3-p0 support is currently under development, there are a few bugs to work out still...
This library is heavily used in a production deployment and is actively developed and maintained.
Development is sponsored by Snapfish and has been generously released to the Open Source community by HPDC, L.P.
ZooKeeper is a multi-purpose tool that is designed to allow you to write code that coordinates many nodes in a cluster. It can be used as a directory service, a configuration database, and can provide cross-cluster locking, leader election, and group membership (to name a few). It presents to the user what looks like a distributed file system, with a few important differences: every node can have children and data, and there is a 1MB limit on data size for any given node. ZooKeeper provides atomic semantics and a simple API for manipulating data in the heirarchy.
One of the most useful aspects of ZooKeeper is the ability to set "watches" on nodes. This allows one to be notified when a node has been deleted, created, has had a child modified, or had its data modified. The asynchronous nature of these watches enables you to write code that can react to changes in your environment.
ZooKeeper is also (relatively) easy to deploy in a Highly Available configuration, and the clients natively understand the clustering and how to resume a session transparently when one of the cluster nodes goes away.
The zookeeper gem provides a low-level, cross platform library for interfacing with ZooKeeper. While it is full featured, it only handles the basic operations that the driver provides. ZK implements the majority of the recipes in the ZooKeeper documentation, plus a number of other conveniences for a production environment.
ZK provides:
- a robust lock implementation (both shared and exclusive locks)
- an extension for the Mongoid ORM to provide advisory locks on mongodb records
- a leader election implementation with both "leader" and "observer" roles
- a higher-level interface to the ZooKeeper callback/watcher mechanism than the zookeeper gem provides
- a simple threadpool implementation
- a bounded, dynamically-growable (threadsafe) client pool implementation
- a recursive Find class (like the Find module in ruby-core)
- unix-like rm_rf and mkdir_p methods (useful for functional testing)
In addition to all of that, I would like to think that the public API the ZK::Client provides is more convenient to use for the common (synchronous) case. For use with EventMachine there is zk-eventmachine which provides a convenient API for writing evented code that uses the ZooKeeper server.
ZK strives to be a complete, correct, and convenient way of interacting with ZooKeeper. There are a few weak points in the implementation:
-
ACLS: HOW DO THEY WORK?! ACL support is mainly faith-based now. I have not had a need for ACLs, and the authors of the upstream twitter/zookeeper code also don't seem to have much experience with them/use for them (purely my opinion, no offense intended). If you are using ACLs and you find bugs or have suggestions, I would much appreciate feedback or examples of how they should work so that support and tests can be added.
-
ZK::Client supports asynchronous calls of all basic methods (get, set, delete, etc.) however these versions are kind of inconvenient to use. For a fully evented stack, try zk-eventmachine, which is designed to be compatible and convenient to use in event-driven code.
-
ZooKeeper "chroot" connection syntax (search for "chroot" in page) is not currently working in the C drivers, and I don't have tests for the Java version. This hasn't been an incredibly high priority item, but support for this feature is intended.
-
I am currently in the process of cleaning up the API documentation and converting it to use YARD.
-
The slyphon-zookeeper gem (repo, branch with Gemfile here), which adds JRuby compatibility and a full suite of tests to the excellent twitter/zookeeper project. (I'm hoping to get this merged upstream, but it's a large change and, you know, people have day jobs).
-
For JRuby, the slyphon-zookeeper_jar gem (repo), which just wraps the upstream zookeeper driver jar in a gem for easy installation
There are a few related projects that extend ZK.
- ZK::Znode: a simple ORM to provide ActiveModel semantics around znodes. While still in early development, may also be a useful example of how to use ZK.