zk-group 0.1.1

data/.dotfiles/rspec-logging

@@ -0,0 +1,4 @@
+--color
+--require ./spec/logging_progress_bar_formatter.rb
+--format LoggingProgressBarFormatter
+

data/.dotfiles/rvmrc

@@ -0,0 +1,2 @@
+rvm 1.9.3@zk-group --create
+

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.rspec
+.rvmrc
+*.log

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "releaseops"]
+	path = releaseops
+	url = git@github.com:slyphon/releaseops.git

data/Gemfile

@@ -0,0 +1,36 @@
+source :rubygems
+
+# git 'git://github.com/slyphon/zookeeper.git', :ref => '8dfdd6be' do
+#     gem 'zookeeper', '>= 1.0.0.beta.1'
+# end
+
+git 'git://github.com/slyphon/zk', :ref => '41bfd35' do
+  gem 'zk'
+end
+
+gem 'pry', :group => [:development, :test]
+
+group :test do
+  gem 'rspec', '~> 2.8'
+end
+
+group :docs do
+  gem 'yard', '~> 0.7.5'
+
+  platform :mri_19 do
+    gem 'redcarpet'
+  end
+end
+
+group :development do
+  gem 'guard',          :require => false
+  gem 'guard-rspec',    :require => false
+  gem 'guard-bundler',  :require => false
+  
+  gem 'growl'  if `uname -s` =~ /darwin/i
+end
+
+# Specify your gem's dependencies in zk-group.gemspec
+gemspec
+
+

data/Guardfile

@@ -0,0 +1,16 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'bundler' do
+  watch('Gemfile')
+  watch(/^.+\.gemspec/)
+end
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r%^lib/zk\.rb%) { "spec" }
+
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+

data/MIT_LICENSE

@@ -0,0 +1,22 @@
+Copyright (C) 2012 by Hewlett Packard Development Company, L.P.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,41 @@
+# ZK::Group
+
+A Group implementation for [ZK][]. Why do you need ZK::Group? Let's say you have a bunch of services. One might even be so bold as to call it "a cluster" (especially in the presence of CTOs or investors).
+
+If you'd like to:
+
+* Know who in the group is currently available
+* Be notified when the members of the group have changed
+* What changed about the list of members
+
+Then ZK::Group is the tool for you. Intentionally lightweight. Use it as-is or subclass and extend for _even more fun_.
+
+_"You'll love it. It's a way of life." - The Central Scrutinizer_
+
+[ZK]: https://github.com/slyphon/zk
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'zk-group'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install zk-group
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,68 @@
+release_ops_path = File.expand_path('../releaseops/lib', __FILE__)
+
+# if the special submodule is availabe, use it
+# we use a submodule because it doesn't depend on anything else (*cough* bundler)
+# and can be shared across projects
+#
+if File.exists?(release_ops_path)
+  require File.join(release_ops_path, 'releaseops')
+
+  # sets up the multi-ruby zk:test_all rake tasks
+  ReleaseOps::TestTasks.define_for(*%w[1.8.7 1.9.2 jruby ree 1.9.3])
+
+  # sets up the task :default => 'spec:run' and defines a simple
+  # "run the specs with the current rvm profile" task
+  ReleaseOps::TestTasks.define_simple_default_for_travis
+
+  # Define a task to run code coverage tests
+  ReleaseOps::TestTasks.define_simplecov_tasks
+
+  # set up yard:server, yard:gems, and yard:clean tasks 
+  # for doing documentation stuff
+  ReleaseOps::YardTasks.define
+
+  namespace :zk do
+    namespace :gems do
+      task :build do
+        require 'tmpdir'
+
+        raise "You must specify a TAG" unless ENV['TAG']
+
+        ReleaseOps.with_tmpdir(:prefix => 'zk-group') do |tmpdir|
+          tag = ENV['TAG']
+
+          sh "git clone . #{tmpdir}"
+
+          orig_dir = Dir.getwd
+
+          cd tmpdir do
+            sh "git co #{tag} && git reset --hard && git clean -fdx"
+
+            sh "rvm 1.8.7 do gem build zk-group.gemspec"
+
+            mv FileList['*.gem'], orig_dir
+          end
+        end
+      end
+
+      task :push do
+        gems = FileList['*.gem']
+        raise "No gemfiles to push!" if gems.empty?
+
+        gems.each do |gem|
+          sh "gem push #{gem}"
+        end
+      end
+
+      task :clean do
+        rm_rf FileList['*.gem']
+      end
+
+      task :all => [:build, :push, :clean]
+    end
+  end
+
+
+  task :clean => 'yard:clean'
+end
+

data/lib/zk-group.rb

@@ -0,0 +1,82 @@
+require 'thread'
+require 'forwardable'
+
+require 'zk'
+
+module ZK
+  # A Group is a basic membership primitive. You pick a name
+  # for the group, and then join, leave, and receive updates when
+  # group membership changes. You can also get a list of other members of the
+  # group.
+  #
+  module Group
+    # common znode data access
+    module Common
+      # the data my znode contains
+      def data
+        zk.get(path).first
+      end
+
+      # Set the data in my group znode (the data at {#path})
+      # 
+      # In the base implementation, no version is given, this will just
+      # overwrite whatever is currently there.
+      #
+      # @param [String] val the data to set
+      # @return [String] the data that was set
+      def data=(val)
+        zk.set(path, val)
+        val
+      end
+    end
+
+    # A simple proxy for catching client errors and re-raising them as Group specific
+    # errors (for clearer error reporting...we hope)
+    #
+    # @private
+    class GroupExceptionTranslator
+      def initialize(zk, group)
+        @zk = zk
+        @group = group
+      end
+
+      private
+        def method_missing(m, *a, &b)
+          super unless @zk.respond_to?(m)
+          @zk.__send__(m, *a, &b)
+        rescue Exceptions::NoNode
+          raise Exceptions::GroupDoesNotExistError, "group at #{@group.path} has not been created yet", caller
+        rescue Exceptions::NodeExists
+          raise Exceptions::GroupAlreadyExistsError, "group at #{@group.path} already exists", caller
+        end
+    end
+   
+    # A simple proxy for catching client errors and re-raising them as Group specific
+    # errors (for clearer error reporting...we hope)
+    #
+    # @private
+    class MemberExceptionTranslator
+      def initialize(zk)
+        @zk = zk
+      end
+
+      private
+        def method_missing(m, *a, &b)
+          super unless @zk.respond_to?(m)
+          @zk.__send__(m, *a, &b)
+        rescue Exceptions::NoNode
+          raise Exceptions::MemberDoesNotExistError, "group at #{path} has not been created yet", caller
+        rescue Exceptions::NodeExists
+          raise Exceptions::MemberAlreadyExistsError, "group at #{path} already exists", caller
+        end
+    end
+  end # Group
+end # ZK
+
+require 'zk-group/version'
+require 'zk-group/exceptions'
+require 'zk-group/membership_subscription'
+require 'zk-group/group'
+require 'zk-group/member'
+
+

data/lib/zk-group/exceptions.rb

@@ -0,0 +1,16 @@
+module ZK
+  module Exceptions
+    # Raised when you try to perform an operation on a group but it hasn't been
+    # created yet
+    class GroupDoesNotExistError < NoNode; end
+
+    # Raised when you try to create! a group but it already exists
+    class GroupAlreadyExistsError < NodeExists; end
+
+    # Raised if an operation is performed that assumes that a membership is active but it wasn't
+    class MemberDoesNotExistError < NoNode; end
+
+    # for symmetry with GroupAlreadyExistsError but in the base implementation, should probably never happen
+    class MemberAlreadyExistsError < NodeExists; end
+  end
+end

data/lib/zk-group/group.rb

@@ -0,0 +1,321 @@
+module ZK
+  module Group
+    @@mutex = Mutex.new unless defined?(@@mutex)
+
+    DEFAULT_ROOT = '/_zk/groups'
+    
+    # @private
+    DEFAULT_PREFIX = 'm'.freeze
+
+    class << self
+      # @private
+      def mutex
+        @@mutex
+      end
+
+      # The path under which all groups will be created. 
+      # defaults to DEFAULT_ROOT if not set
+      def zk_root
+        @@mutex.synchronize { @@zk_root ||= DEFAULT_ROOT }
+      end
+
+      # Sets the default global zk root path.
+      def zk_root=(path)
+        @@mutex.synchronize { @@zk_root = path.dup.freeze }
+      end
+    end
+
+    def self.new(*args)
+      ZK::Group::Group.new(*args)
+    end
+
+    # The basis for forming different kinds of Groups with customizable
+    # memberhip policies.
+    class Group
+      extend Forwardable
+      include Logging
+      include Common
+
+      def_delegators :@mutex, :synchronize
+      protected :synchronize
+
+      # the ZK Client instance
+      attr_reader :zk
+
+      # the name for this group
+      attr_reader :name
+
+      # the absolute root path of this group, generally, this can be left at the default
+      attr_reader :root
+
+      # the combination of `"#{root}/#{name}"`
+      attr_reader :path 
+
+      # @return [ZK::Stat] the stat from the last time we either set or retrieved
+      #   data from the server. 
+      # @private
+      attr_accessor :last_stat
+
+      # Prefix used for creating sequential nodes under {#path} that represent membership.
+      # The default is 'm', so for the path `/_zk/groups/foo` a member path would look like
+      # `/zkgroups/foo/m000000078`
+      #
+      # @return [String] the prefix 
+      attr_accessor :prefix
+
+      def initialize(zk, name, opts={})
+        @orig_zk    = zk
+        @zk         = GroupExceptionTranslator.new(zk, self)
+
+        raise ArgumentError, "name must not be nil" unless name
+
+        @name       = name.to_s
+        @root       = opts[:root] || ZK::Group.zk_root
+        @prefix     = opts[:prefix] || DEFAULT_PREFIX
+        @path       = File.join(@root, @name)
+        @mutex      = Monitor.new
+        @created    = false
+
+        @known_members = []
+        @membership_subscriptions = []
+
+        # ThreadedCallback will queue calls to the block and deliver them one at a time
+        # on their own thread. This guarantees order and simplifies locking.
+        @broadcast_callback = ThreadedCallback.new { |event| broadcast_membership_change!(event) }
+
+        @membership_ev_sub = zk.register(path, :only => :child) do |event|
+          @broadcast_callback.call(event)
+        end
+
+        @on_connected_sub = zk.on_connected do |event|
+          @broadcast_callback.call(event)
+        end
+
+        validate!
+      end
+
+      # stop receiving event notifications, tracking membership changes, etc.
+      # XXX: what about memberships?
+      def close
+        synchronize do
+          return unless @created
+          @created = false
+
+          @broadcast_callback.shutdown
+
+          @on_connected_sub.unsubscribe
+          @membership_ev_sub.unsubscribe
+
+          @known_members.clear
+          @membership_subscriptions.each(&:unsubscribe)
+          @orig_zk.delete(@path, :ignore => [:no_node, :not_empty])
+        end
+      end
+
+      # this is "are we set up" not "did *we* create the group"
+      def created?
+        synchronize { !!@created }
+      end
+
+      # does the group exist already?
+      def exists?
+        zk.exists?(path)
+      end
+
+      # creates this group, does not raise an exception if the group already
+      # exists.
+      #
+      # @return [String,nil] String containing the path of this group if
+      #   created, nil if group already exists
+      #
+      # @overload create(}
+      #   creates this group with empty data
+      #
+      # @overload create(data)
+      #   creates this group with the given data. if the group already exists
+      #   the data will not be written. 
+      #
+      #   @param [String] data the data to be set for this group
+      #
+      def create(*args)
+        synchronize do
+          begin
+            create!(*args)
+          rescue Exceptions::GroupAlreadyExistsError
+            # ok, this is a little odd, if you call create! and it fails, semantically
+            # in this method we're supposed to catch the exception and return. The problem
+            # is that the @known_members and @last_stat won't have been set up. we want
+            # both of these methods available, so we need to set that state up here, but
+            # only if create! fails in this particular way
+            @created = true
+            broadcast_membership_change!
+            nil
+          end
+        end
+      end
+
+      # same as {#create} but raises an exception if the group already exists
+      #
+      # @raise [Exceptions::GroupAlreadyExistsError] if the group already exists
+      def create!(*args)
+        ensure_root_exists!
+
+        data = args.empty? ? '' : args.first
+
+        synchronize do
+          zk.create(path, data).tap do
+            logger.debug { "create!(#{path.inspect}, #{data.inspect}) succeeded, setting initial state" }
+            @created = true
+            broadcast_membership_change!
+          end
+        end
+      end
+
+      # Creates a Member object that represents 'belonging' to this group.
+      # 
+      # The basic behavior is creating a unique path under the {#path} (using
+      # a sequential, ephemeral node).
+      #
+      # You may receive notification that the member was created before this method
+      # returns your Member instance. "heads up"
+      #
+      # @overload join(opts={})
+      #   join the group and set the node's data to blank
+      #
+      #   @option opts [Class] :member_class (ZK::Group::Member) an alternate
+      #     class to manage membership in the group. if this is set to nil,
+      #     no Member will be created and just the created path will be
+      #     returned
+      #
+      # @overload join(data, opts={})
+      #   join the group and set the node's initial data
+      #
+      #   @option opts [Class] :member_class (ZK::Group::Member) an alternate
+      #     class to manage membership in the group. If this is set to nil,
+      #     no Member will be created and just the created path will be
+      #     returned
+      #
+      #   @param data [String] (nil) the data this node should have to start
+      #     with, default is no data
+      #
+      # @return [Member] used to control a single member of the group
+      #
+      def join(*args)
+        # TODO: clarify how the membership interacts with the group. if you
+        #       close the group what happens to the member?
+        opts = args.extract_options!
+        data = args.first || ''
+        member_class = opts.fetch(:member_class, Member)
+        member_path = zk.create("#{path}/#{prefix}", data, :sequence => true, :ephemeral => true)
+        member_class ? member_class.new(@orig_zk, self, member_path) : member_path
+      end
+
+      # returns the current list of member names, sorted.
+      #
+      # @option opts [true,false] :absolute (false) return member information
+      #   as absolute znode paths.
+      #
+      # @option opts [true,false] :watch (true) causes a watch to be set on
+      #   this group's znode for child changes. This will cause the on_membership_change
+      #   callback to be triggered, when delivered.
+      #
+      def member_names(opts={})
+        watch    = opts.fetch(:watch, true)
+        absolute = opts.fetch(:absolute, false)
+
+        zk.children(path, :watch => watch).sort.tap do |rval|
+          rval.map! { |n| File.join(path, n) } if absolute
+        end
+      end
+
+      # Register a block to be called back when the group membership changes. 
+      #
+      # Notifications will be delivered concurrently (i.e. using the client's
+      # threadpool), but serially. In other words, when notification is
+      # delivered to us that the group membership has changed, we queue up
+      # notifications for all callbacks before handling the next event. This
+      # way each callback will see the same sequence of updates every other
+      # callback sees in order. They just may receive the notifications at
+      # different times.
+      #
+      # @note Due to the way ZooKeeper works, it's possible that you may not see every 
+      #   change to the membership of the group. That is *very* important to know. 
+      #   ZooKeeper _may batch updates_, so you can see a jump of members, especially
+      #   if they're added very quickly. DO NOT assume you will receive a callback for _each
+      #   individual membership added_.
+      #
+      # @options opts [true,false] :absolute (false) block will be called with members
+      #   as absolute paths
+      #
+      # @yield [last_members,current_members] called when membership of the
+      #   current group changes.
+      #
+      # @yieldparam [Array] last_members the last known membership list of the group
+      #
+      # @yieldparam [Array] current_members the list of members just retrieved from zookeeper
+      #
+      def on_membership_change(opts={}, &blk)
+        MembershipSubscription.new(self, opts, blk).tap do |ms|
+          # the watch is registered in create!
+          synchronize { @membership_subscriptions << ms }
+        end
+      end
+
+      # called by the MembershipSubscription object to deregister itself
+      # @private
+      def unregister(subscription)
+        synchronize do
+          @membership_subscriptions.delete(subscription)
+        end
+        nil
+      end
+      
+      # @private
+      def broadcast_membership_change!(_ignored=nil)
+        synchronize do
+          logger.debug { "#{__method__} received event #{_ignored.inspect}" }
+          
+          # we might get an on_connected event before creation
+          unless created?
+            logger.debug { "uh, created? #{created?} so returning" }
+            return
+          end
+
+          last_members, @known_members = @known_members, member_names(:watch => true)
+
+          logger.debug { "last_members: #{last_members.inspect}" }
+          logger.debug { "@known_members: #{@known_members.inspect}" }
+
+          # we do this check so that on a connected event, we can run this callback
+          # without producing false positives
+          #
+          if last_members == @known_members
+            logger.debug { "membership data did not actually change, not notifying" }
+          else
+            @membership_subscriptions.each do |sub|
+              lm, km = last_members.dup, @known_members.dup
+              sub.notify(lm, km)
+            end
+          end
+        end
+      end
+
+      private
+        # Creates a Member instance for this Group. This its own method to allow
+        # subclasses to override. By default, uses Member
+        def create_member(znode_path, member_klass)
+          logger.debug { "created member #{znode_path.inspect} returning object" }
+          member_klass.new(@orig_zk, self, znode_path)
+        end
+
+        def ensure_root_exists!
+          zk.mkdir_p(root)
+        end
+
+        def validate!
+          raise ArgumentError, "root must start with '/'" unless @root.start_with?('/')
+        end
+    end # Group
+  end # Group
+end # ZK
+

data/lib/zk-group/member.rb

@@ -0,0 +1,52 @@
+module ZK
+  module Group
+    class Member
+      include Common
+
+      attr_reader :zk 
+
+      # @return [Group] the group instance this member belongs to
+      attr_reader :group
+
+      # @return [String] the relative path of this member under `group.path`
+      attr_reader :name
+
+      # @return [String] the absolute path of this member
+      attr_reader :path
+
+      def initialize(zk, group, path)
+        @zk = zk
+        @group = group
+        @path = path
+        @name = File.basename(@path)
+        @mutex = Mutex.new
+      end
+
+      # probably poor choice of name, but does this member still an active membership
+      # to its group (i.e. is its path still good). 
+      #
+      # This will return false after leave is called.
+      def active?
+        zk.exists?(path)
+      end
+
+      # Leave the group this membership is associated with.
+      # In the basic implementation, this is not meant to kick another member
+      # out of the group.
+      #
+      def leave
+        zk.delete(path)
+      end
+
+      def data
+        @data ||= zk.get(path).first
+      end
+
+      def data=(data)
+        @data = data
+        zk.set(path, data)
+        data
+      end
+    end # Member
+  end # Group
+end # ZK

data/lib/zk-group/membership_subscription.rb

@@ -0,0 +1,36 @@
+module ZK
+  module Group
+    class MembershipSubscription < ZK::Subscription::Base
+      include ZK::Logging
+
+      attr_reader :opts
+
+      alias group parent
+
+      def initialize(group, opts, block)
+        super(group, block)
+        @opts = opts
+      end
+
+      def notify(last_members, current_members)
+        # XXX: implement this in here for now, but for very large membership lists
+        #      it would likely be more efficient to implement this in the caller
+        if absolute_paths?
+          group_path = group.path
+
+          last_members    = last_members.map { |m| File.join(group_path, m) }
+          current_members = current_members.map { |m| File.join(group_path, m) }
+        end
+
+        call(last_members, current_members)
+      end
+
+      def absolute_paths?
+        opts[:absolute]
+      end
+
+      protected :call
+    end
+  end
+end
+

data/lib/zk-group/version.rb

@@ -0,0 +1,5 @@
+module ZK
+  module Group
+    VERSION = "0.1.1"
+  end
+end

data/spec/logging_progress_bar_formatter.rb

@@ -0,0 +1,12 @@
+require 'rspec/core/formatters/progress_formatter'
+
+# essentially a monkey-patch to the ProgressBarFormatter, outputs 
+# '== #{example_proxy.description} ==' in the logs before each test.  makes it
+# easier to match up tests with the SQL they produce
+class LoggingProgressBarFormatter < RSpec::Core::Formatters::ProgressFormatter
+  def example_started(example)
+    ::Logging.logger['spec'].write(yellow("\n=====<([ #{example.full_description} ])>=====\n"))
+    super
+  end
+end
+

data/spec/shared/client_contexts.rb

@@ -0,0 +1,14 @@
+shared_context 'connections' do
+  let(:connection_opts) { ['localhost:2181', {:thread => :per_callback}] }
+
+  before do 
+    @zk = ZK.new(*connection_opts)
+    @base_path = '/zk-group'
+    @zk.rm_rf(@base_path)
+  end
+
+  after do 
+    @zk.close! unless @zk.closed?
+    ZK.open(*connection_opts) { |zk| zk.rm_rf(@base_path) }
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,48 @@
+require 'rubygems'
+require 'bundler/setup'
+
+Bundler.require(:development, :test)
+
+require 'zk-group'
+require 'benchmark'
+
+# Requires supporting ruby files with custom matchers and macros, etc,
+# in spec/support/ and its subdirectories.
+Dir[File.expand_path("../{support,shared}/**/*.rb", __FILE__)].each {|f| require f}
+
+RSpec.configure do |config|
+  config.mock_with :rspec
+
+  config.include(WaitWatchers)
+  config.extend(WaitWatchers)
+
+  config.include(SpecGlobalLogger)
+  config.extend(SpecGlobalLogger)
+end
+
+class ::Thread
+  # join with thread until given block is true, the thread joins successfully, 
+  # or timeout seconds have passed
+  #
+  def join_until(timeout=2)
+    time_to_stop = Time.now + timeout
+
+    until yield
+      break if Time.now > time_to_stop
+      break if join(0)
+      Thread.pass
+    end
+  end
+  
+  def join_while(timeout=2)
+    time_to_stop = Time.now + timeout
+
+    while yield
+      break if Time.now > time_to_stop
+      break if join(0)
+      Thread.pass
+    end
+  end
+end
+
+

data/spec/support/custom_matchers.rb

@@ -0,0 +1,12 @@
+RSpec::Matchers.define :exist do 
+  match do |actual|
+    actual.exists?
+  end
+end
+
+RSpec::Matchers.define :start_with do |expected|
+  match do |actual|
+    actual.start_with?(expected)
+  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

@@ -0,0 +1,26 @@
+module ZK
+  LOG_FILE = File.expand_path('../../../test.log', __FILE__)
+end
+
+ZK.logger = Logger.new(ZK::LOG_FILE).tap { |log| log.level = Logger::DEBUG }
+
+# Zookeeper.logger = ZK.logger
+# Zookeeper.set_debug_level(4)
+
+ZK.logger.debug { "LOG OPEN" }
+
+module SpecGlobalLogger
+  def logger
+    ZK.logger
+  end
+
+  # sets the log level to FATAL for the duration of the block
+  def mute_logger
+    orig_level, ZK.logger.level = ZK.logger.level, Logger::FATAL
+    orig_zk_level, Zookeeper.debug_level = Zookeeper.debug_level, ZookeeperConstants::ZOO_LOG_LEVEL_ERROR
+    yield
+  ensure
+    ZK.logger.level = orig_level
+  end
+end
+

data/spec/support/wait_watchers.rb

@@ -0,0 +1,48 @@
+module WaitWatchers
+  class TimeoutError < StandardError; end
+
+  # method to wait until block passed returns truthy (false will not work) or
+  # timeout (default is 2 seconds) is reached raises TiemoutError on timeout
+  #
+  # @returns the truthy value
+  #
+  # @example 
+  #     
+  #   @a = nil
+  #
+  #   th = Thread.new do
+  #     sleep(1)
+  #     @a = :fudge
+  #   end
+  #
+  #   wait_until(2) { @a }.should == :fudge
+  #
+  def wait_until(timeout=2)
+    time_to_stop = Time.now + timeout
+    while true
+      rval = yield
+      return rval if rval
+      raise TimeoutError, "timeout of #{timeout}s exceeded" if Time.now > time_to_stop
+      Thread.pass
+    end
+  end
+
+  # inverse of wait_until
+  def wait_while(timeout=2)
+    time_to_stop = Time.now + timeout
+    while true
+      rval = yield
+      return rval unless rval
+      raise TimeoutError, "timeout of #{timeout}s exceeded" if Time.now > time_to_stop
+      Thread.pass
+    end
+  end
+
+  def report_realtime(what)
+    return yield
+    t = Benchmark.realtime { yield }
+    $stderr.puts "#{what}: %0.3f" % [t.to_f]
+  end
+end
+
+

data/spec/zk-group/group_spec.rb

@@ -0,0 +1,202 @@
+require 'spec_helper'
+
+describe ZK::Group::Group do
+  include_context 'connections'
+
+  let(:group_name) { 'the_mothers' }
+  let(:group_data) { 'of invention' }
+  let(:member_names) { %w[zappa jcb collins estrada underwood] }
+
+  subject { described_class.new(@zk, group_name, :root => @base_path) }
+  after { subject.close }
+ 
+  describe :create do
+    it %[should create the group with empty data] do
+      subject.create
+      @zk.stat(subject.path).should be_exist
+    end
+
+    it %[should create the group with specified data] do
+      subject.create(group_data)
+      @zk.get(subject.path).first.should == group_data
+    end
+
+    it %[should return nil if the group is not created] do
+      @zk.mkdir_p(subject.path)
+      subject.create.should be_nil
+    end
+  end # create
+
+  describe :exists? do
+    it %[should return false if the group has not been created] do
+      @zk.stat(subject.path).should_not exist
+      subject.should_not exist
+    end
+
+    it %[should return true if the group has been created] do
+      subject.create
+      @zk.stat(subject.path).should exist
+      subject.should exist
+    end
+  end
+
+  describe :create! do
+    it %[should raise GroupAlreadyExistsError if the group already exists] do
+      @zk.mkdir_p(subject.path)
+      lambda { subject.create! }.should raise_error(ZK::Exceptions::GroupAlreadyExistsError)
+    end
+  end # create!
+
+  describe :data do
+    it %[should return the group's data] do
+      @zk.mkdir_p(subject.path)
+      @zk.set(subject.path, group_data)
+      subject.data.should == group_data
+    end
+  end # data
+
+  describe :data= do
+    it %[should set the group's data] do
+      @zk.mkdir_p(subject.path)
+      subject.data = group_data
+      @zk.get(subject.path).first == group_data
+    end
+  end # data=
+
+  describe :member_names do
+    before do
+      member_names.each do |name|
+        @zk.mkdir_p("#{subject.path}/#{name}")
+      end
+    end
+
+    it %[should return a list of relative znode paths that belong to the group] do
+      subject.member_names.should == member_names.sort
+    end
+
+    it %[should return a list of absolute znode paths that belong to the group when :absolute => true is given] do
+      subject.member_names(:absolute => true).should == member_names.sort.map {|n| "#{subject.path}/#{n}" }
+    end
+  end # member_names
+
+  describe :join do
+    it %[should raise GroupDoesNotExistError if the group has not been created already] do
+      lambda { subject.join }.should raise_error(ZK::Exceptions::GroupDoesNotExistError)
+    end
+
+    it %[should return a Member object if the join succeeds] do
+      subject.create!
+      subject.join.should be_kind_of(ZK::Group::Member)
+    end
+
+    it %[should return just the path if :member_class => nil] do
+      subject.create!
+
+      subject.join(:member_class => nil).should match(%r%^#{subject.path}%)
+    end
+  end # join
+
+  describe :on_membership_change do
+    before { @events = [] }
+
+    describe 'with default options' do
+      before do
+        subject.on_membership_change do |old,cur|
+          @events << [old,cur]
+        end
+
+        subject.create!
+      end
+
+      it %[should return an object with an unsubscribe method] do
+        sub = subject.on_membership_change { |old,cur| }
+
+        sub.should respond_to(:unsubscribe)
+      end
+
+      it %[should deliver when the membership changes] do
+        subject.should be_created
+
+        member = subject.join
+        wait_while { @events.empty? }
+        @events.length.should == 1
+
+        old, cur = @events.first
+
+        old.should be_empty
+        cur.length.should == 1
+        cur.first.should match(/\Am\d+\Z/)
+      end
+
+      it %[should deliver notification when a member joins or leaves] do
+        subject.should be_created
+
+        members = []
+
+        10.times { members << subject.join }
+
+        # wait until we've received notification that includes our last created member
+        wait_until { @events.last.last.length == 10 }
+
+        # there should be a difference in the size of the group
+        # this won't always be true, but in this case it should be
+        @events.each do |old,cur|
+          old.length.should < cur.length
+        end
+
+        @events.clear
+
+        members.each { |m| m.leave }
+
+        # wait until we've received notification that includes our last created member
+        wait_until { @events.last.last.empty? }
+
+        @events.each do |old,cur|
+          old.length.should > cur.length
+        end
+      end
+
+      it %[should deliver all events to all listeners in order] do
+        other_events = []
+        mutex = Monitor.new
+        offset = 10
+        saw_six = false
+
+        subject.on_membership_change do |old,cur|
+          num = mutex.synchronize { (offset -= 1) + 1 }
+          sleep(num * 0.005)
+          other_events << [old,cur]
+          mutex.synchronize { saw_six = (cur.length == 6) }
+        end
+
+        6.times { subject.join }
+
+        wait_until { @events.last.last.length == 6 }
+        wait_until { @events.length == other_events.length }
+
+        @events.should == other_events
+      end # in order
+    end # default options
+
+    describe 'with :absolute => true' do
+      before do
+        subject.on_membership_change(:absolute => true) do |old,cur|
+          @events << [old,cur]
+        end
+
+        subject.create!
+      end
+
+      it %[should deliver the members as absolute paths if the :absolute option is true] do
+        member = subject.join
+
+        wait_while { @events.empty? }
+        @events.length.should == 1
+
+        old, cur = @events.first
+
+        cur.first.should start_with('/')
+      end
+    end # absolute
+  end # on_membership_changed
+end # ZK::Group::Base

data/spec/zk-group/member_spec.rb

@@ -0,0 +1,61 @@
+require 'spec_helper'
+
+describe ZK::Group::Member do
+  include_context 'connections'
+
+  let(:group_name) { 'the_mothers' }
+  let(:group) do
+    double(
+      name: group_name, 
+      root: @base_path,
+      path: "#{ZK::Group::DEFAULT_ROOT}/#{group_name}"
+    )
+  end
+
+  let(:member_data) { "LA DI *FREAKIN* DA!" }
+
+  let(:member_path) do 
+    @zk.mkdir_p group.path
+    @zk.create("#{group.path}/#{ZK::Group::DEFAULT_PREFIX}", member_data, ephemeral: true, sequential: true)
+  end
+  
+  subject { described_class.new(@zk, group, member_path) }
+
+  describe :active? do
+    it %[should return true if the path exists] do
+      @zk.stat(member_path).should exist
+      subject.should be_active
+    end
+
+    it %[should return false if the path does not exist] do
+      @zk.delete(member_path)
+      subject.should_not be_active
+    end
+  end
+
+  describe :leave do
+    it %[should delete the underlying path] do
+      subject.leave
+      @zk.stat(member_path).should_not exist
+    end
+
+    it %[should not be active after leave] do
+      subject.leave
+      subject.should_not be_active
+    end
+  end
+
+  describe :data do
+    it %[should return the data in the member's node] do
+      subject.data.should == member_data
+    end
+  end
+
+  describe :data= do
+    it %[should set the data for the member's node] do
+      subject.data = "new data"
+      @zk.get(member_path).first.should == 'new data'
+    end
+  end
+end
+

data/zk-group.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/zk-group/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.authors       = ["Jonathan D. Simms"]
+  s.email         = ["slyphon@gmail.com"]
+  s.description   = %q{A Group abstraction on top of the high-level ZooKeeper library ZK}
+  s.summary       = %q{
+Provides Group-like behaviors such as listing members of a group, joining,
+leaving, and notifications when group memberhsip changes
+  
+Part of the ZK project.
+}
+  s.homepage      = "https://github.com/slyphon/zk-group"
+
+  s.add_runtime_dependency 'zk', '~> 1.6.0'
+
+  s.files         = `git ls-files`.split($\)
+  s.executables   = s.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.name          = "zk-group"
+  s.require_paths = ["lib"]
+  s.version       = ZK::Group::VERSION
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification 
+name: zk-group
+version: !ruby/object:Gem::Version 
+  hash: 25
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 1
+  version: 0.1.1
+platform: ruby
+authors: 
+- Jonathan D. Simms
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-08-21 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: zk
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 1
+        - 6
+        - 0
+        version: 1.6.0
+  type: :runtime
+  version_requirements: *id001
+description: A Group abstraction on top of the high-level ZooKeeper library ZK
+email: 
+- slyphon@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .dotfiles/rspec-logging
+- .dotfiles/rvmrc
+- .gitignore
+- .gitmodules
+- Gemfile
+- Guardfile
+- MIT_LICENSE
+- README.md
+- Rakefile
+- lib/zk-group.rb
+- lib/zk-group/exceptions.rb
+- lib/zk-group/group.rb
+- lib/zk-group/member.rb
+- lib/zk-group/membership_subscription.rb
+- lib/zk-group/version.rb
+- spec/logging_progress_bar_formatter.rb
+- spec/shared/client_contexts.rb
+- spec/spec_helper.rb
+- spec/support/custom_matchers.rb
+- spec/support/exist_matcher.rb
+- spec/support/logging.rb
+- spec/support/wait_watchers.rb
+- spec/zk-group/group_spec.rb
+- spec/zk-group/member_spec.rb
+- zk-group.gemspec
+homepage: https://github.com/slyphon/zk-group
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Provides Group-like behaviors such as listing members of a group, joining, leaving, and notifications when group memberhsip changes  Part of the ZK project.
+test_files: 
+- spec/logging_progress_bar_formatter.rb
+- spec/shared/client_contexts.rb
+- spec/spec_helper.rb
+- spec/support/custom_matchers.rb
+- spec/support/exist_matcher.rb
+- spec/support/logging.rb
+- spec/support/wait_watchers.rb
+- spec/zk-group/group_spec.rb
+- spec/zk-group/member_spec.rb