redis_failover 0.8.0 → 0.8.1

data/.yardopts

@@ -0,0 +1,6 @@
+-m markdown
+--readme README.md
+-
+Changes.md
+LICENSE
+

data/Changes.md

@@ -1,3 +1,9 @@
+0.8.1
+-----------
+- Added YARD documentation.
+- Improve ZooKeeper client connection management.
+- Upgrade to latest ZK gem stable release.
+
 0.8.0
 -----------
 - Added manual failover support (can be initiated via RedisFailover::Client#manual_failover)

data/README.md

@@ -131,6 +131,10 @@ server passed to #manual_failover, or it will pick a random slave to become the
     client = RedisFailover::Client.new(:zkservers => 'localhost:2181,localhost:2182,localhost:2183')
     client.manual_failover(:host => 'localhost', :port => 2222)
 
+## Documentation
+
+redis_failover uses YARD for its API documentation. Refer to the generated [API documentation](http://rubydoc.info/github/ryanlecompte/redis_failover/master/frames) for full coverage.
+
 ## Requirements
 
 - redis_failover is actively tested against MRI 1.9.2/1.9.3 and JRuby 1.6.7 (1.9 mode only). Other rubies may work, although I don't actively test against them. 1.8 is not supported.

data/lib/redis_failover/cli.rb

@@ -1,6 +1,10 @@
 module RedisFailover
   # Parses server command-line arguments.
   class CLI
+    # Parses the source of options.
+    #
+    # @param [Array] source the command-line options to parse
+    # @return [Hash] the parsed options
     def self.parse(source)
       options = {}
       parser = OptionParser.new do |opts|
@@ -55,12 +59,17 @@ module RedisFailover
       prepare(options)
     end
 
+    # @return [Boolean] true if required options missing, false otherwise
     def self.required_options_missing?(options)
       return true if options.empty?
       return true unless options.values_at(:nodes, :zkservers).all?
       false
     end
 
+    # Parses options from a YAML file.
+    #
+    # @param [String] file the filename
+    # @return [Hash] the parsed options
     def self.from_file(file)
       unless File.exists?(file)
         raise ArgumentError, "File #{file} can't be found"
@@ -72,6 +81,10 @@ module RedisFailover
       options
     end
 
+    # Prepares the options for the rest of the system.
+    #
+    # @param [Hash] options the options to prepare
+    # @return [Hash] the prepared options
     def self.prepare(options)
       options.each_value { |v| v.strip! if v.respond_to?(:strip!) }
       # turns 'host1:port,host2:port' => [{:host => host, :port => port}, ...]

data/lib/redis_failover/client.rb

@@ -8,8 +8,7 @@ module RedisFailover
   # Redis clients appropriately. RedisFailover::Client also directs write operations to the master,
   # and all read operations to the slaves.
   #
-  # Examples
-  #
+  # @example Usage
   #   client = RedisFailover::Client.new(:zkservers => 'localhost:2181,localhost:2182,localhost:2183')
   #   client.set('foo', 1) # will be directed to master
   #   client.get('foo') # will be directed to a slave
@@ -86,15 +85,16 @@ module RedisFailover
 
     # Creates a new failover redis client.
     #
-    # Options:
-    #   :zkservers     - comma-separated ZooKeeper host:port pairs (required)
-    #   :znode_path    - the Znode path override for redis server list (optional)
-    #   :password      - password for redis nodes (optional)
-    #   :db            - db to use for redis nodes (optional)
-    #   :namespace     - namespace for redis nodes (optional)
-    #   :logger        - logger override (optional)
-    #   :retry_failure - indicate if failures should be retried (default true)
-    #   :max_retries   - max retries for a failure (default 3)
+    # @param [Hash] options the options used to initialize the client instance
+    # @option options [String] :zkservers comma-separated ZooKeeper host:port pairs (required)
+    # @option options [String] :znode_path znode path override for redis server list
+    # @option options [String] :password password for redis nodes
+    # @option options [String] :db database to use for redis nodes
+    # @option options [String] :namespace namespace for redis nodes
+    # @option options [Logger] :logger logger override
+    # @option options [Boolean] :retry_failure indicates if failures should be retried
+    # @option options [Integer] :max_retries max retries for a failure
+    # @return [RedisFailover::Client]
     def initialize(options = {})
       Util.logger = options[:logger] if options[:logger]
       @zkservers = options.fetch(:zkservers) { raise ArgumentError, ':zkservers required'}
@@ -108,7 +108,7 @@ module RedisFailover
       @slaves = []
       @queue = Queue.new
       @lock = Monitor.new
-      start_zk
+      setup_zk
       build_clients
     end
 
@@ -121,10 +121,14 @@ module RedisFailover
       end
     end
 
-    def respond_to?(method)
-      redis_operation?(method) || super
+    # Determines whether or not an unknown method can be handled.
+    #
+    # @return [Boolean] indicates if the method can be handled
+    def respond_to_missing?(method)
+      redis_operation?(method)
     end
 
+    # @return [String] a string representation of the client
     def inspect
       "#<RedisFailover::Client (master: #{master_name}, slaves: #{slave_names})>"
     end
@@ -134,9 +138,9 @@ module RedisFailover
     # via options. If no options are passed, a random slave will be selected as
     # the candidate for the new master.
     #
-    # Options:
-    #   :host - the host of the failover candidate
-    #   :port - the port of the failover candidate
+    # @param [Hash] options the options used for manual failover
+    # @option options [String] :host the host of the failover candidate
+    # @option options [String] :port the port of the failover candidate
     def manual_failover(options = {})
       Manual.failover(zk, options)
       self
@@ -144,73 +148,45 @@ module RedisFailover
 
     private
 
-    def zk
-      @lock.synchronize { @zk }
-    end
-
-    def start_zk
-      @delivery_thread ||= Thread.new do
-        while event = @queue.pop
-          begin
-            Proc === event ? event.call : handle_zk_event(event)
-          rescue => ex
-            logger.error("Error while handling event: #{ex.inspect}")
-            logger.error(ex.backtrace.join("\n"))
-          end
-        end
-      end
-
-      reconnect_zk
-    end
-
-    def handle_session_established
-      @lock.synchronize do
-        @zk.watcher.register(@znode) do |event|
-          @queue << event
-        end
-        @zk.on_expired_session do
-          @queue << proc { reconnect_zk }
-        end
-        @zk.event_handler.register_state_handler(:connecting) do
-          @queue << proc { handle_lost_connection }
-        end
-        @zk.on_connected do
-          @zk.stat(@znode, :watch => true)
-        end
-        @zk.stat(@znode, :watch => true)
-      end
+    # Sets up the underlying ZooKeeper connection.
+    def setup_zk
+      @zk = ZK.new(@zkservers)
+      @zk.watcher.register(@znode) { |event| handle_zk_event(event) }
+      @zk.on_expired_session { purge_clients }
+      @zk.on_connected { @zk.stat(@znode, :watch => true) }
+      @zk.stat(@znode, :watch => true)
+      update_znode_timestamp
     end
 
+    # Handles a ZK event.
+    #
+    # @param [ZK::Event] event the ZK event to handle
     def handle_zk_event(event)
       update_znode_timestamp
       if event.node_created? || event.node_changed?
         build_clients
       elsif event.node_deleted?
         purge_clients
-        zk.stat(@znode, :watch => true)
+        @zk.stat(@znode, :watch => true)
       else
         logger.error("Unknown ZK node event: #{event.inspect}")
       end
     end
 
-    def reconnect_zk
-      @lock.synchronize do
-        handle_lost_connection
-        @zk.close! if @zk
-        @zk = ZK.new(@zkservers)
-        handle_session_established
-        update_znode_timestamp
-      end
-    end
-
-    def handle_lost_connection
-      purge_clients
-    end
-
+    # Determines if a method is a known redis operation.
+    #
+    # @param [Symbol] method the method to check
+    # @return [Boolean] true if redis operation, false otherwise
     def redis_operation?(method)
       Redis.public_instance_methods(false).include?(method)
     end
 
+    # Dispatches a redis operation to a master or slave.
+    #
+    # @param [Symbol] method the method to dispatch
+    # @param [Array] args the arguments to pass to the method
+    # @param [Proc] block an optional block to pass to the method
+    # @return [Object] the result of dispatching the command
     def dispatch(method, *args, &block)
       unless recently_heard_from_node_manager?
         @lock.synchronize do
@@ -243,6 +219,10 @@ module RedisFailover
       end
     end
 
+    # Returns the currently known master.
+    #
+    # @return [Redis] the Redis client for the current master
+    # @raise [NoMasterError] if no master is available
     def master
       if master = @lock.synchronize { @master }
         verify_role!(master, :master)
@@ -251,6 +231,11 @@ module RedisFailover
       raise NoMasterError
     end
 
+    # Returns a random slave from the list of known slaves.
+    #
+    # @note If there are no slaves, the master is returned.
+    # @return [Redis] the Redis client for the slave or master
+    # @raise [NoMasterError] if no master fallback is available
     def slave
       # pick a slave, if none available fallback to master
       if slave = @lock.synchronize { @slaves.sample }
@@ -260,6 +245,8 @@ module RedisFailover
       master
     end
 
+    # Builds the Redis clients for the currently known master/slaves.
+    # The current master/slaves are fetched via ZooKeeper.
     def build_clients
       @lock.synchronize do
         retried = false
@@ -289,14 +276,21 @@ module RedisFailover
       end
     end
 
+    # Fetches the known redis nodes from ZooKeeper.
+    #
+    # @return [Hash] the known master/slave redis servers
     def fetch_nodes
-      data = zk.get(@znode, :watch => true).first
+      data = @zk.get(@znode, :watch => true).first
       nodes = symbolize_keys(decode(data))
       logger.debug("Fetched nodes: #{nodes}")
 
       nodes
     end
 
+    # Builds new Redis clients for the specified nodes.
+    #
+    # @param [Array<String>] nodes the array of redis host:port pairs
+    # @return [Array<Redis>] the array of corresponding Redis clients
     def new_clients_for(*nodes)
       nodes.map do |node|
         host, port = node.split(':')
@@ -311,15 +305,23 @@ module RedisFailover
       end
     end
 
+    # @return [String] a friendly name for current master
     def master_name
       address_for(@master) || 'none'
     end
 
+    # @return [Array<String>] friendly names for current slaves
     def slave_names
       return 'none' if @slaves.empty?
       addresses_for(@slaves).join(', ')
     end
 
+    # Verifies the actual role for a redis node.
+    #
+    # @param [Redis] node the redis node to check
+    # @param [Symbol] role the role to verify
+    # @return [Symbol] the verified role
+    # @raise [InvalidNodeRoleError] if the role is invalid
     def verify_role!(node, role)
       current_role = node.info['role']
       if current_role.to_sym != role
@@ -328,29 +330,48 @@ module RedisFailover
       role
     end
 
+    # Ensures that the method is supported.
+    #
+    # @raise [UnsupportedOperationError] if the operation isn't supported
     def verify_supported!(method)
       if UNSUPPORTED_OPS.include?(method)
         raise UnsupportedOperationError.new(method)
       end
     end
 
+    # Returns node addresses.
+    #
+    # @param [Array<Redis>] nodes the redis clients
+    # @return [Array<String>] the addresses for the nodes
     def addresses_for(nodes)
       nodes.map { |node| address_for(node) }
     end
 
+    # Returns a node address.
+    #
+    # @param [Redis] node a redis client
+    # @return [String] the address for the node
     def address_for(node)
       return unless node
       "#{node.client.host}:#{node.client.port}"
     end
 
+    # Determines if the currently known redis servers is different
+    # from the nodes returned by ZooKeeper.
+    #
+    # @param [Array<String>] new_nodes the new redis nodes
+    # @return [Boolean] true if nodes are different, false otherwise
     def nodes_changed?(new_nodes)
       return true if address_for(@master) != new_nodes[:master]
       return true if different?(addresses_for(@slaves), new_nodes[:slaves])
       false
     end
 
-    def disconnect(*connections)
-      connections.each do |conn|
+    # Disconnects one or more redis clients.
+    #
+    # @param [Array<Redis>] redis_clients the redis clients
+    def disconnect(*redis_clients)
+      redis_clients.each do |conn|
         if conn
           begin
             conn.client.disconnect
@@ -361,6 +382,7 @@ module RedisFailover
       end
     end
 
+    # Disconnects current redis clients and resets this client's view of the world.
     def purge_clients
       @lock.synchronize do
         logger.info("Purging current redis clients")
@@ -370,10 +392,12 @@ module RedisFailover
       end
     end
 
+    # Updates timestamp when an event is received by the Node Manager.
     def update_znode_timestamp
       @last_znode_timestamp = Time.now
     end
 
+    # @return [Boolean] indicates if we recently heard from the Node Manager
     def recently_heard_from_node_manager?
       return false unless @last_znode_timestamp
       Time.now - @last_znode_timestamp <= ZNODE_UPDATE_TIMEOUT

data/lib/redis_failover/errors.rb

@@ -1,33 +1,36 @@
 module RedisFailover
+  # Base class for all RedisFailover errors.
   class Error < StandardError
-    attr_reader :original
-    def initialize(msg = nil, original = $!)
-      super(msg)
-      @original = original
-    end
   end
 
+  # Raised when a node is specified incorrectly.
   class InvalidNodeError < Error
   end
 
+  # Raised when a node changes to an invalid/unknown state.
   class InvalidNodeStateError < Error
     def initialize(node, state)
       super("Invalid state change `#{state}` for node #{node}")
     end
   end
 
+  # Raised when a node is unavailable (i.e., unreachable via network).
   class NodeUnavailableError < Error
     def initialize(node)
       super("Node: #{node}")
     end
   end
 
+  # Raised when no master is currently available.
   class NoMasterError < Error
   end
 
+  # Raised when no slave is currently available.
   class NoSlaveError < Error
   end
 
+  # Raised when a redis server is no longer using the same role
+  # as previously assumed.
   class InvalidNodeRoleError < Error
     def initialize(node, assumed, actual)
       super("Invalid role detected for node #{node}, client thought " +
@@ -35,6 +38,7 @@ module RedisFailover
     end
   end
 
+  # Raised when an unsupported redis operation is performed.
   class UnsupportedOperationError < Error
     def initialize(operation)
       super("Operation `#{operation}` is currently unsupported")

data/lib/redis_failover/manual.rb

@@ -9,6 +9,13 @@ module RedisFailover
     # Denotes that any slave can be used as a candidate for promotion.
     ANY_SLAVE = "ANY_SLAVE".freeze
 
+    # Performs a manual failover. If options is empty, a random slave will
+    # be used as a failover candidate.
+    #
+    # @param [ZK] zk the ZooKeeper client
+    # @param [Hash] options the options used for manual failover
+    # @option options [String] :host the host of the failover candidate
+    # @option options [String] :port the port of the failover candidate
     def failover(zk, options = {})
       create_path(zk)
       node = options.empty? ? ANY_SLAVE : "#{options[:host]}:#{options[:port]}"
@@ -17,6 +24,9 @@ module RedisFailover
 
     private
 
+    # Creates the znode path used for coordinating manual failovers.
+    #
+    # @param [ZK] zk the ZooKeeper cilent
     def create_path(zk)
       zk.create(ZNODE_PATH)
     rescue ZK::Exceptions::NodeExists

data/lib/redis_failover/node.rb

@@ -10,26 +10,44 @@ module RedisFailover
     # NodeUnavailableError will be raised.
     MAX_OP_WAIT_TIME = 5
 
-    attr_reader :host, :port
+    # @return [String] the redis server host
+    attr_reader :host
 
+    # @return [Integer] the redis server port
+    attr_reader :port
+
+    # Creates a new instance.
+    #
+    # @param [Hash] options the options used to create the node
+    # @option options [String] :host the host of the redis server
+    # @option options [String] :port the port of the redis server
     def initialize(options = {})
       @host = options.fetch(:host) { raise InvalidNodeError, 'missing host'}
       @port = Integer(options[:port] || 6379)
       @password = options[:password]
     end
 
+    # @return [Boolean] true if this node is a master, false otherwise
     def master?
       role == 'master'
     end
 
+    # @return [Boolean] true if this node is a slave, false otherwise
     def slave?
       !master?
     end
 
+    # Determines if this node is a slave of the given master.
+    #
+    # @param [Node] master the master to check
+    # @return [Boolean] true if slave of master, false otherwise
     def slave_of?(master)
       current_master == master
     end
 
+    # Determines current master of this slave.
+    #
+    # @return [Node] the node representing the master of this slave
     def current_master
       info = fetch_info
       return unless info[:role] == 'slave'
@@ -47,12 +65,17 @@ module RedisFailover
       end
     end
 
+    # Wakes up this node by pushing a value to its internal
+    # queue used by #wait.
     def wakeup
       perform_operation do |redis|
         redis.lpush(wait_key, '1')
       end
     end
 
+    # Makes this node a slave of the given node.
+    #
+    # @param [Node] node the node of which to become a slave
     def make_slave!(node)
       perform_operation do |redis|
         unless slave_of?(node)
@@ -63,6 +86,7 @@ module RedisFailover
       end
     end
 
+    # Makes this node a master node.
     def make_master!
       perform_operation do |redis|
         unless master?
@@ -73,14 +97,20 @@ module RedisFailover
       end
     end
 
+    # @return [String] an inspect string for this node
     def inspect
       "<RedisFailover::Node #{to_s}>"
     end
 
+    # @return [String] a friendly string for this node
     def to_s
       "#{@host}:#{@port}"
     end
 
+    # Determines if this node is equal to another node.
+    #
+    # @param [Node] other the other node to compare
+    # @return [Boolean] true if equal, false otherwise
     def ==(other)
       return false unless Node === other
       return true if self.equal?(other)
@@ -88,10 +118,15 @@ module RedisFailover
     end
     alias_method :eql?, :==
 
+
+    # @return [Integer] a hash value for this node
     def hash
       to_s.hash
     end
 
+    # Fetches information/stats for this node.
+    #
+    # @return [Hash] the info for this node
     def fetch_info
       perform_operation do |redis|
         symbolize_keys(redis.info)
@@ -99,12 +134,14 @@ module RedisFailover
     end
     alias_method :ping, :fetch_info
 
+    # @return [Boolean] determines if this node prohibits stale reads
     def prohibits_stale_reads?
       perform_operation do |redis|
         redis.config('get', 'slave-serve-stale-data').last == 'no'
       end
     end
 
+    # @return [Boolean] determines if this node is syncing with its master
     def syncing_with_master?
       perform_operation do |redis|
         fetch_info[:master_sync_in_progress] == '1'
@@ -113,18 +150,25 @@ module RedisFailover
 
     private
 
+    # @return [String] the current role for this node
     def role
       fetch_info[:role]
     end
 
+    # @return [String] the name of the wait queue for this node
     def wait_key
       @wait_key ||= "_redis_failover_#{SecureRandom.hex(32)}"
     end
 
+    # @return [Redis] a new redis client instance for this node
     def new_client
       Redis.new(:host => @host, :password => @password, :port => @port)
     end
 
+    # Safely performs a redis operation within a given timeout window.
+    #
+    # @yield [Redis] the redis client to use for the operation
+    # @raise [NodeUnavailableError] if node is currently unreachable
     def perform_operation
       redis = nil
       Timeout.timeout(MAX_OP_WAIT_TIME) do

data/lib/redis_failover/node_manager.rb

@@ -20,6 +20,14 @@ module RedisFailover
     # Number of seconds to wait before retrying bootstrap process.
     TIMEOUT = 5
 
+    # Creates a new instance.
+    #
+    # @param [Hash] options the options used to initialize the manager
+    # @option options [String] :zkservers comma-separated ZooKeeper host:port pairs (required)
+    # @option options [String] :znode_path znode path override for redis server list
+    # @option options [String] :password password for redis nodes
+    # @option options [Array<String>] :nodes the nodes to manage
+    # @option options [String] :max_failures the max failures for a particular node
     def initialize(options)
       logger.info("Redis Node Manager v#{VERSION} starting (#{RUBY_DESCRIPTION})")
       @options = options
@@ -28,6 +36,9 @@ module RedisFailover
       @mutex = Mutex.new
     end
 
+    # Starts the node manager.
+    #
+    # @note This is a blocking method, it does not return until the manager terminates.
     def start
       @queue = Queue.new
       @leader = false
@@ -49,10 +60,16 @@ module RedisFailover
       retry
     end
 
+    # Notifies the manager of a state change. Used primarily by {RedisFailover::NodeWatcher}
+    # to inform the manager of watched node states.
+    #
+    # @param [Node] node the node
+    # @param [Symbol] state the state
     def notify_state(node, state)
       @queue << [node, state]
     end
 
+    # Performs a graceful shutdown of the manager.
     def shutdown
       @queue.clear
       @queue << nil
@@ -62,6 +79,7 @@ module RedisFailover
 
     private
 
+    # Configures the ZooKeeper client.
     def setup_zk
       @zk.close! if @zk
       @zk = ZK.new(@options[:zkservers])
@@ -74,12 +92,11 @@ module RedisFailover
         end
       end
 
-      @zk.on_connected do
-        @zk.stat(@manual_znode, :watch => true)
-      end
+      @zk.on_connected { @zk.stat(@manual_znode, :watch => true) }
       @zk.stat(@manual_znode, :watch => true)
     end
 
+    # Handles periodic state reports from {RedisFailover::NodeWatcher} instances.
     def handle_state_reports
       while state_report = @queue.pop
         begin
@@ -104,6 +121,9 @@ module RedisFailover
       end
     end
 
+    # Handles an unavailable node.
+    #
+    # @param [Node] node the unavailable node
     def handle_unavailable(node)
       # no-op if we already know about this node
       return if @unavailable.include?(node)
@@ -119,6 +139,9 @@ module RedisFailover
       end
     end
 
+    # Handles an available node.
+    #
+    # @param [Node] node the available node
     def handle_available(node)
       reconcile(node)
 
@@ -138,6 +161,9 @@ module RedisFailover
       @unavailable.delete(node)
     end
 
+    # Handles a node that is currently syncing.
+    #
+    # @param [Node] node the syncing node
     def handle_syncing(node)
       reconcile(node)
 
@@ -151,6 +177,9 @@ module RedisFailover
       handle_available(node)
     end
 
+    # Handles a manual failover request to the given node.
+    #
+    # @param [Node] node the candidate node for failover
     def handle_manual_failover(node)
       # no-op if node to be failed over is already master
       return if @master == node
@@ -162,6 +191,10 @@ module RedisFailover
       promote_new_master(node)
     end
 
+    # Promotes a new master.
+    #
+    # @param [Node] node the optional node to promote
+    # @note if no node is specified, a random slave will be used
     def promote_new_master(node = nil)
       delete_path
       @master = nil
@@ -182,6 +215,7 @@ module RedisFailover
       logger.info("Successfully promoted #{candidate} to master.")
     end
 
+    # Discovers the current master and slave nodes.
     def discover_nodes
       @unavailable = []
       nodes = @options[:nodes].map { |opts| Node.new(opts) }.uniq
@@ -194,6 +228,7 @@ module RedisFailover
       redirect_slaves_to(@master)
     end
 
+    # Spawns the {RedisFailover::NodeWatcher} instances for each managed node.
     def spawn_watchers
       @watchers = [@master, @slaves, @unavailable].flatten.map do |node|
         NodeWatcher.new(self, node,  @options[:max_failures] || 3)
@@ -201,6 +236,10 @@ module RedisFailover
       @watchers.each(&:watch)
     end
 
+    # Searches for the master node.
+    #
+    # @param [Array<Node>] nodes the nodes to search
+    # @return [Node] the found master node, nil if not found
     def find_master(nodes)
       nodes.find do |node|
         begin
@@ -211,6 +250,9 @@ module RedisFailover
       end
     end
 
+    # Redirects all slaves to the specified node.
+    #
+    # @param [Node] node the node to which slaves are redirected
     def redirect_slaves_to(node)
       @slaves.dup.each do |slave|
         begin
@@ -222,6 +264,9 @@ module RedisFailover
       end
     end
 
+    # Forces a slave to be marked as unavailable.
+    #
+    # @param [Node] node the node to force as unavailable
     def force_unavailable_slave(node)
       @slaves.delete(node)
       @unavailable << node unless @unavailable.include?(node)
@@ -231,6 +276,8 @@ module RedisFailover
     # and completely lost its dynamically set run-time role by the node
     # manager. This method ensures that the node resumes its role as
     # determined by the manager.
+    #
+    # @param [Node] node the node to reconcile
     def reconcile(node)
       return if @master == node && node.master?
       return if @master && node.slave_of?(@master)
@@ -248,6 +295,7 @@ module RedisFailover
       end
     end
 
+    # @return [Hash] the set of current nodes grouped by category
     def current_nodes
       {
         :master => @master ? @master.to_s : nil,
@@ -256,6 +304,7 @@ module RedisFailover
       }
     end
 
+    # Deletes the znode path containing the redis nodes.
     def delete_path
       @zk.delete(@znode)
       logger.info("Deleted ZooKeeper node #{@znode}")
@@ -263,6 +312,7 @@ module RedisFailover
       logger.info("Tried to delete missing znode: #{ex.inspect}")
     end
 
+    # Creates the znode path containing the redis nodes.
     def create_path
       @zk.create(@znode, encode(current_nodes), :ephemeral => true)
       logger.info("Created ZooKeeper node #{@znode}")
@@ -270,16 +320,19 @@ module RedisFailover
       # best effort
     end
 
+    # Initializes the znode path containing the redis nodes.
     def initialize_path
       create_path
       write_state
     end
 
+    # Writes the current redis nodes state to the znode path.
     def write_state
       create_path
       @zk.set(@znode, encode(current_nodes))
     end
 
+    # Schedules a manual failover to a redis node.
     def schedule_manual_failover
       return unless @leader
       new_master = @zk.get(@manual_znode, :watch => true).first

data/lib/redis_failover/node_watcher.rb

@@ -8,6 +8,11 @@ module RedisFailover
     # Time to sleep before checking on the monitored node's status.
     WATCHER_SLEEP_TIME = 2
 
+    # Creates a new instance.
+    #
+    # @param [NodeManager] manager the node manager
+    # @param [Node] node the node to watch
+    # @param [Integer] max_failures the max failues before reporting node as down
     def initialize(manager, node, max_failures)
       @manager = manager
       @node = node
@@ -16,11 +21,16 @@ module RedisFailover
       @done = false
     end
 
+    # Starts the node watcher.
+    #
+    # @note this method returns immediately and causes monitoring to be
+    #   performed in a new background thread
     def watch
       @monitor_thread ||= Thread.new { monitor_node }
       self
     end
 
+    # Performs a graceful shutdown of this watcher.
     def shutdown
       @done = true
       @node.wakeup
@@ -31,6 +41,8 @@ module RedisFailover
 
     private
 
+    # Periodically monitors the redis node and reports state changes to
+    # the {RedisFailover::NodeManager}.
     def monitor_node
       failures = 0
 
@@ -57,6 +69,9 @@ module RedisFailover
       end
     end
 
+    # Notifies the manager of a node's state.
+    #
+    # @param [Symbol] state the node's state
     def notify(state)
       @manager.notify_state(@node, state)
     end

data/lib/redis_failover/runner.rb

@@ -1,6 +1,11 @@
 module RedisFailover
-  # Runner is responsible for bootstrapping the redis Node Manager.
+  # Runner is responsible for bootstrapping the Node Manager.
   class Runner
+    # Launches the Node Manager in a background thread.
+    #
+    # @param [Array] options the command-line options
+    # @note this method blocks and does not return until the
+    #   Node Manager is gracefully stopped
     def self.run(options)
       options = CLI.parse(options)
       @node_manager = NodeManager.new(options)
@@ -9,6 +14,7 @@ module RedisFailover
       node_manager_thread.join
     end
 
+    # Traps shutdown signals.
     def self.trap_signals
       [:INT, :TERM].each do |signal|
         trap(signal) do

data/lib/redis_failover/util.rb

@@ -18,14 +18,24 @@ module RedisFailover
       REDIS_ERRORS
     ].flatten.freeze
 
+    # Symbolizes the keys of the specified hash.
+    #
+    # @param [Hash] hash a hash for which keys should be symbolized
+    # @return [Hash] a new hash with symbolized keys
     def symbolize_keys(hash)
       Hash[hash.map { |k, v| [k.to_sym, v] }]
     end
 
+    # Determines if two arrays are different.
+    #
+    # @param [Array] ary_a the first array
+    # @param [Array] ary_b the second array
+    # @return [Boolean] true if arrays are different, false otherwise
     def different?(ary_a, ary_b)
       ((ary_a | ary_b) - (ary_a & ary_b)).size > 0
     end
 
+    # @return [Logger] the logger instance to use
     def self.logger
       @logger ||= begin
         logger = Logger.new(STDOUT)
@@ -37,18 +47,30 @@ module RedisFailover
       end
     end
 
+    # Sets a new logger to use.
+    #
+    # @param [Logger] logger a new logger to use
     def self.logger=(logger)
       @logger = logger
     end
 
+    # @return [Logger] the logger instance to use
     def logger
       Util.logger
     end
 
+    # Encodes the specified data in JSON format.
+    #
+    # @param [Object] data the data to encode
+    # @return [String] the JSON-encoded data
     def encode(data)
       MultiJson.encode(data)
     end
 
+    # Decodes the specified JSON data.
+    #
+    # @param [String] data the JSON data to decode
+    # @return [Object] the decoded data
     def decode(data)
       return unless data
       MultiJson.decode(data)

data/lib/redis_failover/version.rb

@@ -1,3 +1,3 @@
 module RedisFailover
-  VERSION = "0.8.0"
+  VERSION = "0.8.1"
 end

data/redis_failover.gemspec

@@ -18,8 +18,9 @@ Gem::Specification.new do |gem|
   gem.add_dependency('redis')
   gem.add_dependency('redis-namespace')
   gem.add_dependency('multi_json', '~> 1')
-  gem.add_dependency('zk', '~> 1.0')
+  gem.add_dependency('zk', '~> 1.1')
 
   gem.add_development_dependency('rake')
   gem.add_development_dependency('rspec')
+  gem.add_development_dependency('yard')
 end

data/spec/client_spec.rb

@@ -19,7 +19,8 @@ module RedisFailover
       }
     end
 
-    def setup_zookeeper_client
+    def setup_zk
+      @zk = NullObject.new
       update_znode_timestamp
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis_failover
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-02 00:00:00.000000000 Z
+date: 2012-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -66,7 +66,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -74,7 +74,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -107,6 +107,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Redis Failover is a ZooKeeper-based automatic master/slave failover solution
   for Ruby
 email:
@@ -118,6 +134,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .travis.yml
+- .yardopts
 - Changes.md
 - Gemfile
 - LICENSE
@@ -160,7 +177,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3688012640966712276
+      hash: -3105018591679682945
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -169,7 +186,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3688012640966712276
+      hash: -3105018591679682945
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -187,3 +204,4 @@ test_files:
 - spec/support/node_manager_stub.rb
 - spec/support/redis_stub.rb
 - spec/util_spec.rb
+has_rdoc: