zookeeper 0.4.4 → 0.9.3

data/lib/zookeeper.rb

@@ -1,59 +1,54 @@
 # Ruby wrapper for the Zookeeper C API
 
-require 'zookeeper_c'
 require 'thread'
-require 'zookeeper/callbacks'
+require 'monitor'
+require 'forwardable'
+require 'logger'
+
+require 'zookeeper/common'
 require 'zookeeper/constants'
+require 'zookeeper/callbacks'
 require 'zookeeper/exceptions'
 require 'zookeeper/stat'
 require 'zookeeper/acls'
 
-class Zookeeper < CZookeeper
-  include ZookeeperCallbacks
-  include ZookeeperConstants
-  include ZookeeperExceptions
-  include ZookeeperACLs
-  include ZookeeperStat
-
-  ZKRB_GLOBAL_CB_REQ   = -1
-
-  # debug levels
-  ZOO_LOG_LEVEL_ERROR  = 1
-  ZOO_LOG_LEVEL_WARN   = 2
-  ZOO_LOG_LEVEL_INFO   = 3
-  ZOO_LOG_LEVEL_DEBUG  = 4
-
-  def reopen(timeout = 10)
-    init(@host)
-    if timeout > 0
-      time_to_stop = Time.now + timeout
-      until state == Zookeeper::ZOO_CONNECTED_STATE
-        break if Time.now > time_to_stop
-        sleep 0.1
-      end
-    end
-    # flushes all outstanding watcher reqs.
-    @watcher_reqs = { ZKRB_GLOBAL_CB_REQ => { :watcher => get_default_global_watcher } }
-    setup_dispatch_thread!
-    state
+
+if defined?(::JRUBY_VERSION)
+  $LOAD_PATH.unshift(File.expand_path('../java', File.dirname(__FILE__))).uniq!
+else
+  $LOAD_PATH.unshift(File.expand_path('../ext', File.dirname(__FILE__))).uniq!
+end
+
+require 'zookeeper_base'
+
+class Zookeeper < ZookeeperBase
+  unless defined?(@@logger)
+    @@logger = Logger.new($stderr).tap { |l| l.level = Logger::ERROR } 
+  end
+
+  def self.logger
+    @@logger
   end
 
-  def initialize(host, timeout = 10)
-    @watcher_reqs = {}
-    @completion_reqs = {}
-    @req_mutex = Mutex.new
-    @current_req_id = 1
-    @host = host
-    return nil if reopen(timeout) != Zookeeper::ZOO_CONNECTED_STATE
+  def self.logger=(logger)
+    @@logger = logger
+  end
+
+  def reopen(timeout=10, watcher=nil)
+    warn "WARN: ZookeeperBase#reopen watcher argument is now ignored" if watcher
+    super
+  end
+
+  def initialize(host, timeout=10, watcher=nil)
+    super
   end
 
-public
   def get(options = {})
     assert_open
     assert_supported_keys(options, [:path, :watcher, :watcher_context, :callback, :callback_context])
     assert_required_keys(options, [:path])
 
-    req_id = setup_call(options)
+    req_id = setup_call(:get, options)
     rc, value, stat = super(req_id, options[:path], options[:callback], options[:watcher])
 
     rv = { :req_id => req_id, :rc => rc }
@@ -64,9 +59,10 @@ public
     assert_open
     assert_supported_keys(options, [:path, :data, :version, :callback, :callback_context])
     assert_required_keys(options, [:path])
+    assert_valid_data_size!(options[:data])
     options[:version] ||= -1
 
-    req_id = setup_call(options)
+    req_id = setup_call(:set, options)
     rc, stat = super(req_id, options[:path], options[:data], options[:callback], options[:version])
 
     rv = { :req_id => req_id, :rc => rc }
@@ -78,7 +74,7 @@ public
     assert_supported_keys(options, [:path, :callback, :callback_context, :watcher, :watcher_context])
     assert_required_keys(options, [:path])
 
-    req_id = setup_call(options)
+    req_id = setup_call(:get_children, options)
     rc, children, stat = super(req_id, options[:path], options[:callback], options[:watcher])
 
     rv = { :req_id => req_id, :rc => rc }
@@ -90,7 +86,7 @@ public
     assert_supported_keys(options, [:path, :callback, :callback_context, :watcher, :watcher_context])
     assert_required_keys(options, [:path])
 
-    req_id = setup_call(options)
+    req_id = setup_call(:stat, options)
     rc, stat = exists(req_id, options[:path], options[:callback], options[:watcher])
 
     rv = { :req_id => req_id, :rc => rc }
@@ -101,6 +97,7 @@ public
     assert_open
     assert_supported_keys(options, [:path, :data, :acl, :ephemeral, :sequence, :callback, :callback_context])
     assert_required_keys(options, [:path])
+    assert_valid_data_size!(options[:data])
 
     flags = 0
     flags |= ZOO_EPHEMERAL if options[:ephemeral]
@@ -108,7 +105,7 @@ public
 
     options[:acl] ||= ZOO_OPEN_ACL_UNSAFE
 
-    req_id = setup_call(options)
+    req_id = setup_call(:create, options)
     rc, newpath = super(req_id, options[:path], options[:data], options[:callback], options[:acl], flags)
 
     rv = { :req_id => req_id, :rc => rc }
@@ -121,19 +118,37 @@ public
     assert_required_keys(options, [:path])
     options[:version] ||= -1
 
-    req_id = setup_call(options)
+    req_id = setup_call(:delete, options)
     rc = super(req_id, options[:path], options[:version], options[:callback])
 
     { :req_id => req_id, :rc => rc }
   end
 
+  # this method is *only* asynchronous
+  #
+  # @note There is a discrepancy between the zkc and java versions. zkc takes
+  #   a string_callback_t, java takes a VoidCallback. You should most likely use
+  #   the ZookeeperCallbacks::VoidCallback and not rely on the string value.
+  #
+  def sync(options = {})
+    assert_open
+    assert_supported_keys(options, [:path, :callback, :callback_context])
+    assert_required_keys(options, [:path, :callback])
+
+    req_id = setup_call(:sync, options)
+
+    rc = super(req_id, options[:path]) # we don't pass options[:callback] here as this method is *always* async
+
+    { :req_id => req_id, :rc => rc }
+  end
+
   def set_acl(options = {})
     assert_open
     assert_supported_keys(options, [:path, :acl, :version, :callback, :callback_context])
     assert_required_keys(options, [:path, :acl])
     options[:version] ||= -1
 
-    req_id = setup_call(options)
+    req_id = setup_call(:set_acl, options)
     rc = super(req_id, options[:path], options[:acl], options[:callback], options[:version])
 
     { :req_id => req_id, :rc => rc }
@@ -144,121 +159,139 @@ public
     assert_supported_keys(options, [:path, :callback, :callback_context])
     assert_required_keys(options, [:path])
 
-    req_id = setup_call(options)
+    req_id = setup_call(:get_acl, options)
     rc, acls, stat = super(req_id, options[:path], options[:callback])
 
     rv = { :req_id => req_id, :rc => rc }
     options[:callback] ? rv : rv.merge(:acl => acls, :stat => Stat.new(stat))
   end
 
-  # To close a Zk handle, first shutdown the dispatcher thread; this is done by
-  # signalling the waiting thread that there is a pending close. We then release
-  # the C-land Zk state.
+  # close this client and any underyling connections
   def close
-    signal_pending_close
-    @dispatcher.join
     super
   end
 
-private
-  def setup_dispatch_thread!
-    @dispatcher = Thread.new {
-      while true do
-        hash = get_next_event
-        break if hash.nil? # Pending close => exit dispatcher thread
-        dispatch_event(hash)
-      end
-    }
+  def state
+    super
   end
 
-  def dispatch_event(hash)
-    is_completion = hash.has_key?(:rc)
+  def connected?
+    super
+  end
 
-    hash[:stat] = Stat.new(hash[:stat]) if hash.has_key?(:stat)
-    hash[:acl] = hash[:acl].map { |acl| ACL.new(acl) } if hash[:acl]
+  def connecting?
+    super
+  end
 
-    callback_context = is_completion ? get_completion(hash[:req_id]) : get_watcher(hash[:req_id])
-    callback = is_completion ? callback_context[:callback] : callback_context[:watcher]
-    hash[:context] = callback_context[:context]
+  def associating?
+    super
+  end
+  
+  # There are some operations that are dangerous in the context of the event
+  # dispatch thread (because they would block further event delivery). This
+  # method allows clients to know if they're currently executing in the context of an
+  # event.
+  #
+  # @returns [true,false] true if the current thread is the event dispatch thread
+  def event_dispatch_thread?
+    super
+  end
 
-    # TODO: Eventually enforce derivation from Zookeeper::Callback
-    if callback.respond_to?(:call)
-      callback.call(hash)
-    else
-      # puts "dispatch_next_callback found non-callback => #{callback.inspect}"
+  # for expert use only. set the underlying debug level for the C layer, has no
+  # effect in java
+  #
+  # @private
+  def self.set_debug_level(val)
+    if defined?(::CZookeeper)
+      CZookeeper.set_debug_level(val.to_i)
     end
   end
 
-  def setup_call(opts)
-    req_id = nil
-    @req_mutex.synchronize {
-      req_id = @current_req_id
-      @current_req_id += 1
-      setup_completion(req_id, opts) if opts[:callback]
-      setup_watcher(req_id, opts) if opts[:watcher]
-    }
-    req_id
+  # @private
+  def self.get_debug_level
+    if defined?(::CZookeeper)
+      CZookeeper.get_debug_level
+    end
   end
 
-  def setup_watcher(req_id, call_opts)
-    @watcher_reqs[req_id] = { :watcher => call_opts[:watcher],
-                              :context => call_opts[:watcher_context] }
+  class << self
+    # @private
+    alias :debug_level= :set_debug_level
+    
+    # @private
+    alias :debug_level :get_debug_level
   end
 
-  def setup_completion(req_id, call_opts)
-    @completion_reqs[req_id] = { :callback => call_opts[:callback],
-                                 :context => call_opts[:callback_context] }
+  # DEPRECATED: use the class-level method instead
+  def set_debug_level(val)
+    super
   end
 
-  def get_watcher(req_id)
-    @req_mutex.synchronize {
-      req_id != ZKRB_GLOBAL_CB_REQ ? @watcher_reqs.delete(req_id) : @watcher_reqs[req_id]
-    }
+  # has the underlying connection been closed?
+  def closed?
+    super
   end
 
-  def get_completion(req_id)
-    @req_mutex.synchronize { @completion_reqs.delete(req_id) }
+  # is the event delivery system running?
+  def running?
+    super
   end
 
-public
-  # TODO: Sanitize user mistakes by unregistering watchers from ops that
-  # don't return ZOK (except wexists)?  Make users clean up after themselves for now.
-  def unregister_watcher(req_id)
-    @req_mutex.synchronize {
-      @watcher_reqs.delete(req_id)
-    }
+  # return the session id of the current connection as an Fixnum
+  def session_id
+    super
   end
 
-private
-  # TODO: Make all global puts configurable
+  # Return the passwd portion of this connection's credentials as a String
+  def session_passwd
+    super
+  end
+
+protected
+  # used during shutdown, awaken the event delivery thread if it's blocked
+  # waiting for the next event
+  def wake_event_loop!
+    super
+  end
+  
+  # starts the event delivery subsystem going. after calling this method, running? will be true
+  def setup_dispatch_thread!
+    super
+  end
+
+  # TODO: describe what this does
   def get_default_global_watcher
-    Proc.new { |args|
-      # puts "Ruby ZK Global CB called type=#{event_by_value(args[:type])} state=#{state_by_value(args[:state])}"
-      true
-    }
+    super
   end
 
-  # if either of these happen, the user will need to renegotiate a connection via reopen
-  def assert_open
-    if state == ZOO_EXPIRED_SESSION_STATE
-      raise ZookeeperException::SessionExpired
-    elsif state != Zookeeper::ZOO_CONNECTED_STATE
-      raise ZookeeperException::ConnectionClosed
-    end
+  def logger
+    Zookeeper.logger
   end
 
-  def assert_supported_keys(args, supported)
-    unless (args.keys - supported).empty?
-      raise ZookeeperException::BadArguments,
-            "Supported arguments are: #{supported.inspect}, but arguments #{args.keys.inspect} were supplied instead"
+  def assert_valid_data_size!(data)
+    return if data.nil?
+
+    data = data.to_s
+    if data.length >= 1048576 # one megabyte 
+      raise ZookeeperException::DataTooLargeException, "data must be smaller than 1 MiB, your data starts with: #{data[0..32].inspect}"
     end
+    nil
   end
 
-  def assert_required_keys(args, required)
-    unless (required - args.keys).empty?
-      raise ZookeeperException::BadArguments,
-            "Required arguments are: #{required.inspect}, but only the arguments #{args.keys.inspect} were supplied."
-    end
+private
+  # TODO: Sanitize user mistakes by unregistering watchers from ops that
+  # don't return ZOK (except wexists)?  Make users clean up after themselves for now.
+  #
+  # XXX: is this dead code?
+  def unregister_watcher(req_id)
+    @mutex.synchronize {
+      @watcher_reqs.delete(req_id)
+    }
+  end
+  
+  # must be supplied by parent class impl.
+  def assert_open
+    super
   end
 end
 

data/notes.txt

@@ -0,0 +1,14 @@
+Notes on this fork of http://github.com/twitter/zookeeper
+
+The main purpose of this fork is to provide JRuby compatibility with the MRI driver of the original. We have been using an early fork with an incomplete binding to the C client, and had recently bumped up against a fairly serious bug with handling events. The twitter/zookeeper driver solved this problem but was lacking JRuby support (which is a core piece of our environment).
+
+I've packaged the Java client (and its dependency on log4j) as gems that are installed separately from this codebase to cut down on the size of the zookeeper gem. If this poses a problem (for instance, if the original goal was to have an all-in-one install with no external dependencies), it would be trivial to package those jars along with this code.
+
+In the course of writing the wrapper for JRuby, I've written nearly-complete specs for all of the public API methods: get, set, get_children, stat, create, delete, get_acl, and set_acl. The reason I say they're "nearly" complete is that I have no use for set_acl, and quite honestly, couldn't figure out how to make it work. 
+
+I'm planning on writing a companion gem, 'ZK', that would take some of the higher-level constructs that we'd written around the lower-level driver to implement features like locking and queues, and also to provide a more ruby-like interface.
+
+I'd like to reorganize this codebase in a number of ways, most of all to move all of the various classes and modules under a common "Zookeeper" namespace, however I thought that would be a radical enough change where I'd want to discuss/coordinate with you on how exactly to do it.
+
+
+

data/spec/c_zookeeper_spec.rb

@@ -0,0 +1,50 @@
+# tests the CZookeeper, obviously only available when running under MRI
+require 'spec_helper'
+
+if Module.const_defined?(:CZookeeper)
+  describe CZookeeper do
+    def pop_all_events
+      [].tap do |rv|
+        begin
+          rv << @event_queue.pop(non_blocking=true)
+        rescue ThreadError
+        end
+      end
+    end
+
+    def wait_until_connected(timeout=2)
+      wait_until(timeout) { @czk.state == ZookeeperConstants::ZOO_CONNECTED_STATE }
+    end
+
+    describe do
+      before do
+        @event_queue = ZookeeperCommon::QueueWithPipe.new
+        @czk = CZookeeper.new('localhost:2181', @event_queue)
+      end
+
+      after do
+        @czk.close rescue Exception
+        @event_queue.close rescue Exception
+      end
+
+      it %[should be in connected state within a reasonable amount of time] do
+        wait_until_connected.should be_true
+      end
+
+      describe :after_connected do
+        before do
+          wait_until_connected.should be_true
+        end
+
+        it %[should have a connection event after being connected] do
+          event = wait_until(2) { @event_queue.pop }
+          event.should be
+          event[:req_id].should == ZookeeperCommon::ZKRB_GLOBAL_CB_REQ
+          event[:type].should   == ZookeeperConstants::ZOO_SESSION_EVENT
+          event[:state].should  == ZookeeperConstants::ZOO_CONNECTED_STATE
+        end
+      end
+    end
+  end
+end
+

data/spec/chrooted_connection_spec.rb

@@ -0,0 +1,81 @@
+require 'spec_helper'
+require 'shared/connection_examples'
+
+describe 'Zookeeper chrooted' do
+  let(:path) { "/_zkchroottest_" }
+  let(:data) { "underpants" } 
+  let(:chroot_path) { '/slyphon-zookeeper-chroot' }
+
+  let(:connection_string) { "localhost:2181#{chroot_path}" }
+
+  before do
+    @zk = Zookeeper.new(connection_string)
+  end
+
+  after do
+    @zk and @zk.close
+  end
+
+  def zk
+    @zk
+  end
+
+  describe 'non-existent' do
+    describe 'with existing parent' do
+      let(:chroot_path) { '/one-level' }
+
+      describe 'create' do
+        before do
+          with_open_zk do |z|
+            rm_rf(z, chroot_path)
+          end
+        end
+
+        it %[should successfully create the path] do
+          rv = zk.create(:path => '/', :data => '')
+          rv[:rc].should be_zero
+          rv[:path].should == ''
+        end
+      end
+    end
+
+    describe 'with missing parent' do
+      let(:chroot_path) { '/deeply/nested/path' }
+
+      describe 'create' do
+        before do
+          with_open_zk do |z|
+            rm_rf(z, chroot_path)
+          end
+        end
+
+        it %[should return ZNONODE] do
+          rv = zk.create(:path => '/', :data => '')
+          rv[:rc].should_not be_zero
+          rv[:rc].should == ZookeeperExceptions::ZNONODE
+        end
+      end
+    end
+  end
+
+
+  describe do
+    before :all do
+      Zookeeper.logger.warn "running before :all"
+
+      with_open_zk do |z|
+        z.create(:path => chroot_path, :data => '')
+      end
+    end
+
+    after :all do
+      with_open_zk do |z|
+        rm_rf(z, chroot_path)
+      end
+    end
+
+    it_should_behave_like "connection"
+  end
+end
+
+

data/spec/default_watcher_spec.rb

@@ -0,0 +1,41 @@
+require File.expand_path('../spec_helper', __FILE__) 
+
+describe Zookeeper do
+  describe :initialize, 'with watcher block' do
+    before do
+      @events = []
+      @watch_block = lambda do |hash| 
+        $stderr.puts "watch_block: #{hash.inspect}"
+        @events << hash
+      end
+
+      @zk = Zookeeper.new('localhost:2181', 10, @watch_block)
+
+      wait_until(2) { @zk.connected? }
+      @zk.should be_connected
+      $stderr.puts "connected!"
+
+      wait_until(2) { !@events.empty? }
+      $stderr.puts "got events!"
+    end
+
+    after do
+      @zk.close if @zk.connected?
+    end
+
+    it %[should receive initial connection state events] do
+      @events.should_not be_empty
+      @events.length.should == 1
+      @events.first[:state].should == Zookeeper::ZOO_CONNECTED_STATE
+    end
+
+    it %[should receive disconnection events] do
+      pending "the C driver doesn't appear to deliver disconnection events (?)"
+      @events.clear
+      @zk.close
+      wait_until(2) { !@events.empty? }
+      @events.should_not be_empty
+    end
+  end
+end
+

data/spec/em_spec.rb

@@ -0,0 +1,51 @@
+require File.expand_path('../spec_helper', __FILE__)
+require 'zookeeper/em_client'
+
+gem 'evented-spec', '~> 0.9.0'
+require 'evented-spec'
+
+
+describe 'ZookeeperEM' do
+  describe 'Client' do
+    include EventedSpec::SpecHelper
+    default_timeout 3.0
+
+    def setup_zk
+      @zk = ZookeeperEM::Client.new('localhost:2181')
+      em do
+        @zk.on_attached do
+          yield
+        end
+      end
+    end
+
+    def teardown_and_done
+      @zk.close do 
+        logger.debug { "TEST: about to call done" }
+        EM.next_tick do
+          done
+        end
+      end
+    end
+
+    describe 'callbacks' do
+      it %[should be called on the reactor thread] do
+        cb = lambda do |h|
+          EM.reactor_thread?.should be_true
+          logger.debug { "called back on the reactor thread? #{EM.reactor_thread?}" }
+          teardown_and_done
+        end
+
+        setup_zk do
+          @zk.on_attached do |*|
+            logger.debug { "on_attached called" }
+            rv = @zk.get(:path => '/', :callback => cb) 
+            logger.debug { "rv from @zk.get: #{rv.inspect}" }
+          end
+        end
+      end
+    end
+  end
+end
+
+

data/spec/log4j.properties

@@ -0,0 +1,17 @@
+log4j.rootLogger        = DEBUG,S
+
+log4j.appender.S        = org.apache.log4j.FileAppender
+log4j.appender.S.File   = /tmp/zk-test.log
+
+log4j.appender.S.layout = org.apache.log4j.PatternLayout
+log4j.appender.S.layout.ConversionPattern  = %5p [%t] (%c:%F:%L) - %m%n
+
+log4j.appender.C        = org.apache.log4j.FileAppender
+log4j.appender.C.File   = /tmp/zk-test-client.log
+
+log4j.appender.C.layout = org.apache.log4j.PatternLayout
+log4j.appender.C.layout.ConversionPattern  = %5p [%t] (%c:%F:%L) - %m%n
+
+log4j.org.apache.zookeeper.ZooKeeper = DEBUG,C
+log4j.org.apache.zookeeper.server    = DEBUG,S
+

data/spec/shared/all_success_return_values.rb

@@ -0,0 +1,10 @@
+shared_examples_for "all success return values" do
+  it %[should have a return code of Zookeeper::ZOK] do
+    @rv[:rc].should == Zookeeper::ZOK
+  end
+
+  it %[should have a req_id integer] do
+    @rv[:req_id].should be_kind_of(Integer)
+  end
+end
+