zk 0.9.1 → 1.0.0.rc.1

data/lib/zk.rb

@@ -1,2 +1,239 @@
-require File.expand_path('../z_k', __FILE__)
+require 'rubygems'
+
+require 'logger'
+require 'zookeeper'
+require 'forwardable'
+require 'thread'
+require 'monitor'
+require 'set'
+require 'time'
+require 'date'
+
+require 'zk/core_ext'
+require 'zk/logging'
+require 'zk/exceptions'
+require 'zk/extensions'
+require 'zk/event'
+require 'zk/stat'
+require 'zk/threadpool'
+require 'zk/event_handler_subscription'
+require 'zk/event_handler'
+require 'zk/message_queue'
+require 'zk/locker'
+require 'zk/election'
+require 'zk/mongoid'
+require 'zk/client'
+require 'zk/pool'
+require 'zk/find'
+
+module ZK
+  silence_warnings do
+    # @private
+    ZK_ROOT = File.expand_path('../..', __FILE__).freeze
+    
+    # @private
+    DEFAULT_SERVER = 'localhost:2181'.freeze
+  end
+
+  unless defined?(KILL_TOKEN) 
+    # @private
+    KILL_TOKEN = Object.new 
+  end
+
+
+  unless @logger
+    @logger = Logger.new($stderr).tap { |n| n.level = Logger::ERROR }
+  end
+
+  # The logger used by the ZK library. uses a Logger stderr with Logger::ERROR
+  # level. The only thing that should ever be logged are exceptions that are
+  # swallowed by background threads.
+  #
+  # You can change this logger by setting ZK#logger= to an object that
+  # implements the stdllb Logger API.
+  #
+  def self.logger
+    @logger
+  end
+
+  # Assign the Logger instance to be used by ZK
+  def self.logger=(logger)
+    @logger = logger
+  end
+
+  # Create a new ZK::Client instance. If no arguments are given, the default
+  # config of `localhost:2181` will be used. Otherwise all args will be passed
+  # to ZK::Client#new
+  #
+  # if a block is given, it will be yielded the client *before* the connection
+  # is established, this is useful for registering connected-state handlers.
+  #
+  # Since 1.0, if you pass a chrooted host string, i.e. `localhost:2181/foo/bar/baz` this
+  # method will create two connections. The first will be short lived, and will create the 
+  # chroot path, the second will be the chrooted one and returned to the user. This is
+  # meant as a convenience to users who want to use chrooted connections.
+  #
+  # @note As it says in the ZooKeeper [documentation](http://zookeeper.apache.org/doc/r3.4.3/zookeeperProgrammers.html#ch_gotchas), 
+  #   if you are running a cluster: "The list of ZooKeeper servers used by the
+  #   client must match the list of ZooKeeper servers that each ZooKeeper
+  #   server has. Things can work, although not optimally, if the client list
+  #   is a subset of the real list of ZooKeeper servers, but not if the client
+  #   lists ZooKeeper servers not in the ZooKeeper cluster."
+  #
+  # @example Connection using defaults
+  #
+  #   zk = ZK.new   # will connect to 'localhost:2181' 
+  #
+  # @example Connection to a single server
+  #
+  #   zk = ZK.new('localhost:2181')
+  #
+  # @example Connection to a single server with a chroot (automatically created)
+  #
+  #   zk = ZK.new('localhost:2181/look/around/you')
+  #
+  # @example Connection to multiple servers (a cluster)
+  #   
+  #   zk = ZK.new('server1:2181,server2:2181,server3:2181')
+  #
+  # @example Connection to multiple servers with a chroot (chroot will automatically be creatd)
+  #
+  #   zk = ZK.new('server1:2181,server2:2181,server3:2181/look/around/you')
+  #
+  # @example Connection to a single server, assert that chroot path exists, but do not create it
+  #
+  #   zk = ZK.new('localhost:2181/look/around/you', :chroot => :check)
+  #
+  # @example Connection to a single server, use a chrooted connection, do not check for validity, do not create
+  # 
+  #   zk = ZK.new('localhost:2181/look/around/you', :chroot => :do_nothing)
+  #
+  # @example Connection to a single server, chroot path specified as an option
+  #
+  #   zk = ZK.new('localhost:2181', :chroot => '/look/around/you')
+  #
+  # @overload new(connection_str, opts={}, &block)
+  #   @param [String] connection_str A zookeeper host connection string, which
+  #     is a comma-separated list of zookeeper servers and an optional chroot
+  #     path.
+  #
+  #   @option opts [:create,:check,:do_nothing,String] :chroot (:create) if a chrooted
+  #     `connection_str`, `:chroot` can have the following values:
+  #
+  #     * `:create` (the default), then we will use a secondary (short-lived)
+  #     un-chrooted connection to ensure that the path exists before returning
+  #     the chrooted connection. 
+  #
+  #     * `:check`, we will not attempt to create the connection, but rather
+  #     will raise a {Exceptions::ChrootPathDoesNotExistError
+  #     ChrootPathDoesNotExistError} if the path doesn't exist. 
+  #
+  #     * `:do_nothing`, we do not create the path and furthermore we do not
+  #     perform the check (the `<= 0.9` behavior).
+  #
+  #     * if a `String` is given, it is used as the chroot path, and we will follow
+  #     the same rules as if `:create` was given if `connection_str` also
+  #     contains a chroot path, we raise an `ArgumentError`
+  #
+  #     * if you don't like this for some reason, you can always use
+  #     {ZK::Client::Threaded#initialize Threaded.new} directly. You probably
+  #     also hate happiness and laughter.
+  #
+  #   @raise [ChrootPathDoesNotExistError] if a chroot path is specified,
+  #     `:chroot` is `:check`, and the path does not exist.
+  #
+  #   @raise [ArgumentError] if both a chrooted `connection_str` is given *and* a
+  #     `String` value for the `:chroot` option is given
+  #
+  def self.new(*args, &block)
+    opts = args.extract_options!
+
+    chroot_opt = opts.fetch(:chroot, :create)
+
+    args = [DEFAULT_SERVER]  if args.empty?     # the ZK.new() case
+
+    if args.first.kind_of?(String)
+      if new_cnx_str = do_chroot_setup(args.first, chroot_opt)
+        args[0] = new_cnx_str
+      end
+    else
+      raise ArgumentError, "cannot create a connection given args array: #{args}"
+    end
+
+    opts.delete(:chroot_opt)
+
+    args << opts
+
+    Client.new(*args, &block)
+  end
+
+  # Like new, yields a connection to the given block and closes it when the
+  # block returns
+  def self.open(*args)
+    cnx = new(*args)
+    yield cnx
+  ensure
+    cnx.close! if cnx
+  end
+
+  # creates a new ZK::Pool::Bounded with the default options.
+  def self.new_pool(host, opts={})
+    ZK::Pool::Bounded.new(host, opts)
+  end
+
+  # @private
+  def self.join(*paths)
+    File.join(*paths)
+  end
+
+  private
+    # @return [String] a possibly modified connection string (with chroot info
+    #   added)
+    #
+    def self.do_chroot_setup(cnx_str, chroot_opt=:create)
+      # "it should set up the chroot for us," they says. 
+      # "it's confusing if it doesn't do that for us," they says.
+      # sheesh, look at this...
+
+      host, chroot_path = Client.split_chroot(cnx_str)
+
+      case chroot_opt
+      when :do_nothing
+        return
+      when String
+        if chroot_path
+          raise ArgumentError, "You cannot give a connection_str with a chroot path (#{cnx_str}) *and* specify a :chroot => #{chroot_opt} too!"
+        else
+          # ok, cnx_str didn't have a chroot path on it, but the user
+          # specified :chroot => '/path'. we'll use that, then
+          chroot_path = chroot_opt.dup
+          chroot_opt  = :create
+
+          # oh, and return the correct string later
+          cnx_str = "#{host}#{chroot_path}"
+        end
+      when :create, :check
+        # no-op, valid options for later
+      else
+        raise ArgumentError, ":chroot must be one of :create, :check, :do_nothing, or a String, not: #{chroot_opt.inspect}" 
+      end
+
+      return cnx_str unless chroot_path  # if by this point, we don't have a chroot_path, then there isn't one to be had
+
+      # make sure the given path is kosher
+      Client.assert_valid_chroot_str!(chroot_path)
+
+      open(host) do |zk|                # do path stuff with the virgin connection
+        unless zk.exists?(chroot_path)  # someting must be done
+          if chroot_opt == :create      # here, let me...
+            zk.mkdir_p(chroot_path)     # ...get that for you
+          else                          # careful with that axe
+            raise Exceptions::ChrootPathDoesNotExistError.new(host, chroot_path)  # ...eugene
+          end                                                                               
+        end
+      end
+
+      cnx_str   # the possibly-modified connection string (with chroot info)
+    end
+end
 

data/spec/message_queue_spec.rb

@@ -3,8 +3,8 @@ require File.join(File.dirname(__FILE__), %w[spec_helper])
 describe ZK::MessageQueue do
 
   before(:each) do
-    @zk = ZK.new("localhost:#{ZK_TEST_PORT}", :watcher => :default)
-    @zk2 = ZK.new("localhost:#{ZK_TEST_PORT}", :watcher => :default)
+    @zk = ZK.new("localhost:#{ZK_TEST_PORT}")
+    @zk2 = ZK.new("localhost:#{ZK_TEST_PORT}")
     wait_until{ @zk.connected? && @zk2.connected? }
     @queue_name = "_specQueue"
     @consume_queue = @zk.queue(@queue_name)

data/spec/shared/client_contexts.rb

@@ -3,30 +3,18 @@ shared_context 'threaded client connection' do
     @connection_string = "localhost:#{ZK_TEST_PORT}"
     @base_path = '/zktests'
     @zk = ZK::Client::Threaded.new(@connection_string).tap { |z| wait_until { z.connected? } }
+    @zk.on_exception { |e| raise e }
     @zk.rm_rf(@base_path)
   end
 
   after do
-    @zk.rm_rf(@base_path)
-    @zk.close!
-
-    wait_until(2) { @zk.closed? }
-  end
-end
-
-shared_context 'multiplexed client connection' do
-  before do
-    @connection_string = "localhost:#{ZK_TEST_PORT}"
-    @base_path = '/zktests'
-    @zk = ZK::Client::Multiplexed.new(@connection_string).tap { |z| wait_until { z.connected? } }
-    @zk.rm_rf(@base_path)
-  end
-
-  after do
-    @zk.rm_rf(@base_path)
-    @zk.close!
-
-    wait_until(2) { @zk.closed? }
+    if @zk.closed?
+      ZK.open(@connection_string) { |z| z.rm_rf(@base_path) }
+    else
+      @zk.rm_rf(@base_path)
+      @zk.close!
+      wait_until(2) { @zk.closed? }
+    end
   end
 end
 

data/spec/shared/client_examples.rb

@@ -3,6 +3,7 @@ shared_examples_for 'client' do
     before(:each) do
       @path_ary = %w[test mkdir_p path creation]
       @bogus_path = File.join('/', *@path_ary)
+      @zk.rm_rf('/test')
     end
     
     it %[should create all intermediate paths for the path givem] do
@@ -14,6 +15,95 @@ shared_examples_for 'client' do
     end
   end
 
+  # nail down all possible cases
+  describe :create do
+    describe 'only path given' do
+      it %[should create a node with blank data] do
+        @zk.create(@base_path)
+        @zk.get(@base_path).first.should == ''
+      end
+    end
+
+    describe 'path and data given' do
+      it %[should create a node with the path and data] do
+        @zk.create(@base_path, 'blah')
+        @zk.get(@base_path).first.should == 'blah'
+      end
+    end
+
+    describe 'path and sequential' do
+      it %[should create a sequential node with blank data] do
+        @zk.create(@base_path)
+        path = @zk.create("#{@base_path}/v", :sequential => true)
+        path.start_with?(@base_path).should be_true
+
+        File.basename(path).should match(/v\d+/)
+
+        @zk.get(path).first.should == ''
+      end
+
+      it %[should create a sequential node with given data] do
+        @zk.create(@base_path)
+        path = @zk.create("#{@base_path}/v", 'thedata', :sequential => true)
+        path.start_with?(@base_path).should be_true
+
+        File.basename(path).should match(/v\d+/)
+
+        data, st = @zk.get(path)
+        data.should == 'thedata'
+        st.should_not be_ephemeral
+      end
+    end
+
+    describe 'path and ephemeral' do
+      it %[should create an ephemeral node with blank data] do
+        @zk.create(@base_path, :ephemeral => true)
+        @zk.get(@base_path).last.should be_ephemeral
+      end
+
+      it %[should create an ephemeral node with given data] do
+        @zk.create(@base_path, 'thedata', :ephemeral => true)
+        data, stat = @zk.get(@base_path)
+        data.should == 'thedata'
+        stat.should be_ephemeral
+      end
+    end
+
+    describe 'path and sequential and ephemeral' do
+      it %[should create a sequential ephemeral node with blank data] do
+        @zk.create(@base_path)
+        path = @zk.create("#{@base_path}/v", :sequential => true, :ephemeral => true)
+        path.start_with?(@base_path).should be_true
+
+        File.basename(path).should match(/v\d+/)
+
+        data, st = @zk.get(path)
+        data.should == ''
+        st.should be_ephemeral
+      end
+
+      it %[should create a sequential ephemeral node with given data] do
+        @zk.create(@base_path)
+        path = @zk.create("#{@base_path}/v", 'thedata', :sequential => true, :ephemeral => true)
+        path.start_with?(@base_path).should be_true
+
+        File.basename(path).should match(/v\d+/)
+
+        data, st = @zk.get(path)
+        data.should == 'thedata'
+        st.should be_ephemeral
+      end
+    end
+
+    it %[should barf if someone hands 3 params] do
+      lambda { @zk.create(@base_path, 'data', :sequence) }.should raise_error(ArgumentError)
+    end
+
+    it %[should barf if both :sequence and :sequential are given] do
+      lambda { @zk.create(@base_path, 'data', :sequence => true, :sequential => true) }.should raise_error(ArgumentError)
+    end
+  end
+
   describe :stat do
     describe 'for a missing node' do
       before do
@@ -60,7 +150,7 @@ shared_examples_for 'client' do
 
     describe 'node exists initially' do
       before do
-        @zk.create(@path, '', :mode => :ephemeral)
+        @zk.create(@path, :mode => :ephemeral)
         @zk.exists?(@path).should be_true
       end
 
@@ -113,7 +203,7 @@ shared_examples_for 'client' do
         end
 
         @zk.exists?(@path, :watch => true).should be_false
-        @zk.create(@path, '')
+        @zk.create(@path)
 
         logger.debug { "waiting for event delivery" } 
 
@@ -151,6 +241,50 @@ shared_examples_for 'client' do
         ensure_event_delivery!
       end
     end
+
+  end # reopen
+
+  describe 'reconnection' do
+    it %[should if it receives a client_invalid? event] do
+      flexmock(@zk) do |m|
+        m.should_receive(:reopen).with(0).once
+      end
+
+      bogus_event = flexmock(:expired_session_event, :session_event? => true, :client_invalid? => true, :state_name => 'ZOO_EXPIRED_SESSION_STATE')
+
+      @zk.raw_event_handler(bogus_event)
+    end
+  end # reconnection
+
+  describe :on_exception do
+    it %[should register a callback that will be called if an exception is raised on the threadpool] do
+      @ary = []
+
+      @zk.on_exception { |exc| @ary << exc }
+        
+      @zk.defer { raise "ZOMG!" }
+
+      wait_while(2) { @ary.empty? }
+
+      @ary.length.should == 1
+
+      e = @ary.shift
+
+      e.should be_kind_of(RuntimeError)
+      e.message.should == 'ZOMG!'
+    end
+  end
+
+  describe :on_threadpool? do
+    it %[should be true if we're on the threadpool] do
+      @ary = []
+
+      @zk.defer { @ary << @zk.on_threadpool? }
+
+      wait_while(2) { @ary.empty? }
+      @ary.length.should == 1
+      @ary.first.should be_true
+    end
   end
 end
 

data/spec/spec_helper.rb

@@ -1,12 +1,14 @@
 require 'rubygems'
 require 'bundler/setup'
 
-$LOAD_PATH.unshift(File.expand_path('../../lib', __FILE__))
+# $LOAD_PATH.unshift(File.expand_path('../../lib', __FILE__))
+
+Bundler.require(:development, :test)
 
 require 'zk'
 require 'benchmark'
 
-ZK_TEST_PORT = 2181
+ZK_TEST_PORT = 2181 unless defined?(ZK_TEST_PORT)
 
 # Requires supporting ruby files with custom matchers and macros, etc,
 # in spec/support/ and its subdirectories.

data/spec/support/event_catcher.rb

@@ -0,0 +1,11 @@
+class EventCatcher < Struct.new(:created, :changed, :deleted, :child, :all)
+    
+  def initialize(*args)
+    super
+
+    [:created, :changed, :deleted, :child, :all].each do |k|
+      self.__send__(:"#{k}=", []) if self.__send__(:"#{k}").nil?
+    end
+  end
+end
+

data/spec/support/exist_matcher.rb

@@ -0,0 +1,6 @@
+RSpec::Matchers.define :exist do 
+  match do |actual|
+    actual.exists?
+  end
+end
+

data/spec/support/logging.rb

@@ -1,5 +1,6 @@
 module ZK
-  LOG_FILE = File.open(File.join(ZK::ZK_ROOT, 'test.log'), 'a').tap { |f| f.sync = true }
+#   LOG_FILE = File.open(File.join(ZK::ZK_ROOT, 'test.log'), 'a').tap { |f| f.sync = true }
+  LOG_FILE = File.join(ZK::ZK_ROOT, 'test.log')
 #   LOG_FILE = $stderr
 end