stalk_climber 0.0.6 → 0.1.0

data/lib/stalk_climber/connection_pool.rb

@@ -3,10 +3,17 @@ module StalkClimber
 
     class InvalidURIScheme < RuntimeError; end
 
-    attr_reader :addresses, :test_tube
+    # Addresses the pool is connected to
+    attr_reader :addresses
 
-    # Constructs a Beaneater::Pool from a less strict URL
-    # +url+ can be a string i.e 'localhost:11300' or an array of addresses.
+    # Test tube used when probing Beanstalk server for information
+    attr_reader :test_tube
+
+    # Constructs a Beaneater::Pool from a less strict URL +url+ can be a string
+    # or an array of addresses. Valid URLs match any of the following forms:
+    #   localhost (host only)
+    #   192.168.1.100:11300 (host and port)
+    #   beanstalk://127.0.0.1:11300 (host and port prefixed by beanstalk scheme)
     def initialize(addresses = nil, test_tube = nil)
       @addresses = Array(parse_addresses(addresses) || host_from_env || Beaneater.configuration.beanstalkd_url)
       @test_tube = test_tube
@@ -14,16 +21,39 @@ module StalkClimber
     end
 
 
+    def tubes
+      @tubes ||= StalkClimber::Tubes.new(self)
+    end
+
+
     protected
 
-    # Parses the given url into a collection of beanstalk addresses
+    # :call-seq:
+    #   parse_addresses(addresses) => String
+    #
+    # Parses the given urls into a collection of beanstalk addresses
     def parse_addresses(addresses)
       return if addresses.empty?
       uris = addresses.is_a?(Array) ? addresses.dup : addresses.split(/[\s,]+/)
       uris.map! do |uri_string|
-        uri = URI.parse(uri_string)
-        raise(InvalidURIScheme, "Invalid beanstalk URI: #{uri_string}") unless uri.scheme == 'beanstalk'
-        "#{uri.host}:#{uri.port || 11300}"
+        begin
+          uri = URI.parse(uri_string)
+        rescue URI::InvalidURIError
+          # IP based hosts without a scheme will fail to parse
+        end
+        if uri && uri.scheme && uri.host
+          raise(InvalidURIScheme, "Invalid beanstalk URI: #{uri_string}") unless uri.scheme == 'beanstalk'
+          host = uri.host
+          port = uri.port
+        else
+          # if parse failure or missing scheme or host, assume the uri format is a
+          # hostname optionally followed by a port.
+          # i.e. 'localhost:11300' or '0.0.0.0'
+          match = uri_string.split(/:/)
+          host = match[0]
+          port = match[1]
+        end
+        "#{host}:#{port || 11300}"
       end
     end
 

data/lib/stalk_climber/job.rb

@@ -1,62 +1,83 @@
-require 'json'
-
 module StalkClimber
-  class Job
+  class Job < Beaneater::Job
+
+    # Attributes that are retrieved each request by default
+    FRESH_ATTRIBUTES = %w[delay pri state time-left]
+
+    # Attributes that return cached values by default
+    CACHED_ATTRIBUTES = %w[age buries kicks releases reserves timeouts ttr tube]
+
+    # All attributes available via a job's stats
+    STATS_ATTRIBUTES = (CACHED_ATTRIBUTES + FRESH_ATTRIBUTES).sort!
 
-    STATS_ATTRIBUTES = %w[age buries delay kicks pri releases reserves state time-left timeouts ttr tube]
-    HASH_ATTRIBUTES = (STATS_ATTRIBUTES + %w[body connection id]).sort!.map!(&:to_sym)
-    attr_reader :id
+    # Lookup table of which method to call to retrieve each stat
+    STATS_METHODS = Hash[
+      STATS_ATTRIBUTES.zip(STATS_ATTRIBUTES.map {|stat| stat.gsub(/-/, '_')})
+    ]
 
-    STATS_ATTRIBUTES.each do |method_name|
-      define_method method_name do |force_refresh = false|
-        return stats(force_refresh)[method_name]
+    STATS_METHODS.each_pair do |stat, method_name|
+      force = FRESH_ATTRIBUTES.include?(stat)
+      define_method method_name do |force_refresh = force|
+        return stats(force_refresh).send(method_name)
       end
     end
 
 
-    # Returns or fetches the body of the job obtained via the peek command
+    # :call-seq:
+    #   body() => String
+    #
+    # Returns or fetches the body of the job. If not already present the body of
+    # the job is obtained via the peek command.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('reserve'))
+    #   job.body
+    #     #=> "Work to be done"
     def body
       return @body ||= connection.transmit("peek #{id}")[:body]
     end
 
 
-    # Returns the connection provided by the job data given to the initialize method
-    def connection
-      return @connection
-    end
-
-
-    # Deletes the job from beanstalk. If the job is not found it is assumed that it
-    # has already been otherwise deleted.
+    # :call-seq:
+    #   delete() => Hash{Symbol => String,Integer}
+    #
+    # Tries to delete the job from beanstalk. Returns the Beanstalkd response for the command.
+    # Raises Beaneater::NotFoundError if the job could not be found.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('reserve'))
+    #   job.delete
+    #     #=> {:status=>"DELETED", :body=>nil, :connection=>#<Beaneater::Connection host="localhost" port=11300>}
     def delete
-      return true if @status == 'DELETED'
-      begin
-        @connection.transmit("delete #{id}")
-      rescue Beaneater::NotFoundError
-      end
+      result = super
       @status = 'DELETED'
       @stats = nil
       @body = nil
-      return true
+      return result
     end
 
 
+    # :call-seq:
+    #   exists?() => Boolean
+    #
     # Determines if a job exists by retrieving stats for the job. If Beaneater can't find
     # the job then it does not exist and false is returned. The stats command is used
     # because it will return a response of a near constant size, whereas, depending on
     # the job, the peek command could return a much larger response. Rather than waste
     # the trip to the server, stats are updated each time the method is called.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('reserve'))
+    #   job.exists?
+    #     #=> true
+    #   job.delete
+    #   job.exists?
+    #     #=> false
     def exists?
-      return false if @status == 'DELETED'
-      begin
-        stats(:force_refresh)
-        return true
-      rescue Beaneater::NotFoundError
-        return false
-      end
+      return @status == 'DELETED' ? false : super
     end
 
 
+    # :call-seq:
+    #   new(job_data) => Job
+    #
     # Initializes a Job instance using +job_data+ which should be the Beaneater response to either
     # a put, peek, or stats-job command. Other Beaneater responses are not supported.
     #
@@ -67,124 +88,306 @@ module StalkClimber
     # Put provides only the ID of the job and as such yields the least informed instance. Both a
     # peek and stats-job call may be required to retrieve anything but the ID of the instance
     #
-    # Peek provides the ID and body of the job. A stats-job call may be required to access anything
-    # but the ID or body of the job.
+    # Peek and reserve provide the ID and body of the job. A stats-job call may be required to
+    # access anything but the ID or body of the job.
     #
     # Stats-job provides the most information about the job, but lacks the crtical component of the
     # job body. As such, a peek call would be required to access the body of the job.
+    #
+    #   reserve_response = connection.transmit('reserve')
+    #   StalkClimber::Job.new(reserve_response)
+    #     #=> #<StalkClimber::Job id=1 body="Work to be done">
     def initialize(job_data)
       case job_data[:status]
       when 'INSERTED' # put
         @id = job_data[:id].to_i
         @body = @stats = nil
-      when 'FOUND' # peek
+      when 'FOUND', 'RESERVED' # peek, reserve
         @id = job_data[:id].to_i
         @body = job_data[:body]
         @stats = nil
       when 'OK' # stats-job
-        @stats = job_data[:body].dup
-        @id = @stats.delete('id').to_i
+        @stats = Beaneater::StatStruct.from_hash(job_data[:body])
+        @id = @stats.id.to_i
         @body = nil
       else
         raise RuntimeError, "Unexpected job status: #{job_data[:status]}"
       end
       @status = job_data[:status]
       @connection = job_data[:connection]
+      # Don't set @reserved to force lookup each time to handle job TTR expiration
     end
 
 
+    # :call-seq:
+    #   stats(force_refresh = true) => Beaneater::StatStruct
+    #
     # Returns or retrieves stats for the job. Optionally, a retrieve may be forced
     # by passing a non-false value for +force_refresh+
-    def stats(force_refresh = false)
-      return @stats unless @stats.nil? || force_refresh
-      @stats = connection.transmit("stats-job #{id}")[:body]
-      @stats.delete('id')
+    #
+    #   job = StalkClimber::Job.new(peek_response)
+    #   job.stats
+    #     #=> #<Beaneater::StatStruct id=2523, tube="stalk_climber", state="ready", pri=0, age=25, delay=0, ttr=120, time_left=0, file=0, reserves=0, timeouts=0, releases=0, buries=0, kicks=0>
+    def stats(force_refresh = true)
+      if @stats.nil? || force_refresh
+        @stats = super()
+      end
       return @stats
     end
 
 
-    # Returns a hash of all job attributes
+    # :call-seq:
+    #   to_h() => Hash
+    #
+    # Returns a hash of all job attributes derived from updated stats
+    #
+    #   job = StalkClimber::Job.new(peek_response)
+    #   job.to_h
+    #     #=> {"age"=>144, "body"=>"Work to be done", "buries"=>0, "connection"=>#<Beaneater::Connection host="localhost" port=11300>, "delay"=>0, "id"=>2523, "kicks"=>0, "pri"=>0, "releases"=>0, "reserves"=>0, "state"=>"ready", "time-left"=>0, "timeouts"=>0, "ttr"=>120, "tube"=>"stalk_climber"}
     def to_h
-      return Hash[HASH_ATTRIBUTES.map { |attr| [attr, send(attr) ] } ]
+      stats
+      stats_pairs = STATS_METHODS.map { |stat, method_name| [stat, stats(false)[method_name]]}
+      stats_pairs.concat([['body', body], ['connection', connection], ['id', id]]).sort_by!(&:first)
+      return Hash[stats_pairs]
     end
 
 
+    # :call-seq:
+    #   to_s() => String
+    #
+    # Returns string representation of job
+    #
+    #   job = StalkClimber::Job.new(peek_response)
+    #   job.to_s
+    #     #=> #<StalkClimber::Job id=1 body="Work to be done">
+    def to_s
+      "#<StalkClimber::Job id=#{id} body=#{body.inspect}>"
+    end
+    alias :inspect :to_s
+
+
     # :method: age
+    # :call-seq:
+    #   age(force_refresh = false) => Integer
+    #
     # Retrieves the age of the job from the job's stats. Passing a non-false value for
     # +force_refresh+ will force retrieval of updated stats for the job
-    # :call-seq:
-    #   age(force_refresh = false)
+    #
+    #   job = StalkClimber::Job.new(peek_response)
+    #   job.age
+    #     #=> 1024
 
     # :method: buries
+    # :call-seq:
+    #   buries(force_refresh = false) => Integer
+    #
     # Retrieves the number of times the job has been buried from the job's stats. Passing
     # a non-false value for +force_refresh+ will force retrieval of updated stats for the job
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('peek-buried'))
+    #   job.buries
+    #     #=> 1
+
+    # :method: connection
+    # :call-seq:
+    #   connection() => Beaneater::Connection
+    #
+    # Returns the Beaneater::Connection instance which retrieved job.
+    #
+    #   job = StalkClimber::Job.new(peek_response)
+    #   job.connection
+    #     #=> #<Beaneater::Connection host="localhost" port=11300>
+
+    # :method: id
     # :call-seq:
-    #   buries(force_refresh = false)
+    #   id() => Integer
+    #
+    # Returns the id of the job.
+    #
+    #   job = StalkClimber::Job.new(peek_response)
+    #   job.id
+    #     #=> 1
+
+    # :method: bury
+    # :call-seq:
+    #   bury() => Hash{Symbol => String,Integer}
+    #
+    # Sends command to bury a reserved job. Returns the Beanstalkd response for
+    # the command.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('reserve'))
+    #   job.bury
+    #     #=> {:status=>"BURIED", :body=>nil, :connection=>#<Beaneater::Connection host="localhost" port=11300>}
 
     # :method: delay
+    # :call-seq:
+    #   delay(force_refresh = false) => Integer
+    #
     # Retrieves the the remaining delay before the job is ready from the job's stats. Passing
-    # a non-false value for +force_refresh+ will force retrieval of updated stats for the job
+    # a non-false value for +force_refresh+ will force retrieval of updated stats for the job.
+    # By default the value for delay is refreshed every time it is requested.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('peek-delayed'))
+    #   job.delay
+    #     #=> 1024
+
+    # :method: kick
     # :call-seq:
-    #   delay(force_refresh = false)
+    #   kick() => Hash{Symbol => String,Integer}
+    #
+    # Sends command to kick a buried job. Returns the Beanstalkd response for the command.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('peek-buried'))
+    #   job.kick
+    #     #=> {:status=>"KICKED", :body=>nil, :connection=>#<Beaneater::Connection host="localhost" port=11300>}
 
     # :method: kicks
+    # :call-seq:
+    #   kicks(force_refresh = false) => Integer
+    #
     # Retrieves the number of times the job has been kicked from the job's stats. Passing
     # a non-false value for +force_refresh+ will force retrieval of updated stats for the job
-    # :call-seq:
-    #   kicks(force_refresh = false)
+    # By default the value for kicks is cached and will not be updated unless forced.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('peek-buried'))
+    #   job.kicks
+    #     #=> 5
 
     # :method: pri
+    # :call-seq:
+    #   pri(force_refresh = false) => Integer
+    #
     # Retrieves the priority of the job from the job's stats. Passing a non-false value for
-    # +force_refresh+ will force retrieval of updated stats for the job
+    # +force_refresh+ will force retrieval of updated stats for the job.
+    # By default the the value for pri is refreshed every time it is requested.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('peek-ready'))
+    #   job.pri
+    #     #=> 0
+
+    # :method: release
     # :call-seq:
-    #   pri(force_refresh = false)
+    #   release(options = {}) => Hash{Symbol => String,Integer}
+    #
+    # Sends command to release a job back to ready state. Return value
+    # is the Beanstalkd response to the command.
+    #
+    # Options may include an Integer pri to set a new pri for the job and/or an
+    # Integer delay to assign a new delay to the job
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('reserve'))
+    #   job.release(:delay => 120, :pri => 1024)
+    #     #=> {:status=>"RELEASED", :body=>nil, :connection=>#<Beaneater::Connection host="localhost" port=11300>}
 
     # :method: releases
+    # :call-seq:
+    #   releases(force_refresh = false) => Integer
+    #
     # Retrieves the number of times the job has been released from the job's stats. Passing
     # a non-false value for +force_refresh+ will force retrieval of updated stats for the job
+    # By default the value for releases is cached and will not be updated unless forced.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('peek-ready'))
+    #   job.releases
+    #     #=> 3
+
+    # :method: reserved?
     # :call-seq:
-    #   releases(force_refresh = false)
+    #   reserved?() => Boolean
+    #
+    # Returns true if a job is currently in a reserved state.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('reserve'))
+    #   job.reserved?
+    #     #=> true
 
     # :method: reserves
+    # :call-seq:
+    #   reserves(force_refresh = false) => Integer
+    #
     # Retrieves the number of times the job has been reserved from the job's stats. Passing
     # a non-false value for +force_refresh+ will force retrieval of updated stats for the job
-    # :call-seq:
-    #   reserves(force_refresh = false)
+    # By default the value for reserves is cached and will not be updated unless forced.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('reserve'))
+    #   job.reserves
+    #     #=> 1
 
     # :method: state
+    # :call-seq:
+    #   state(force_refresh = false) => String
+    #
     # Retrieves the state of the job from the job's stats. Value will be one of "ready",
     # "delayed", "reserved", or "buried". Passing a non-false value for +force_refresh+
     # will force retrieval of updated stats for the job
-    # :call-seq:
-    #   timeouts(force_refresh = false)
+    # By default the the value for state is refreshed every time it is requested.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('peek-ready'))
+    #   job.state
+    #     #=> 'ready'
 
-    # :method: time-left
+    # :method: time_left
+    # :call-seq:
+    #   time_left(force_refresh = false) => Integer
+    #
     # Retrieves the number of seconds left until the server puts this job into the ready
     # queue. This number is only meaningful if the job is reserved or delayed. If the job
     # is reserved and this amount of time elapses before its state changes, it is considered
     # to have timed out. Passing a non-false value for +force_refresh+ will force retrieval
-    # of updated stats for the job
-    # :call-seq:
-    #   timeouts(force_refresh = false)
+    # of updated stats for the job By default the the value for time_left is refreshed every
+    # time it is requested.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('reserve'))
+    #   job.time_left
+    #     #=> 119
 
     # :method: timeouts
+    # :call-seq:
+    #   timeouts(force_refresh = false) => Integer
+    #
     # Retrieves the number of times the job has timed out from the job's stats. Passing
     # a non-false value for +force_refresh+ will force retrieval of updated stats for the job
+    # By default the value for timeouts is cached and will not be updated unless forced.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('reserve'))
+    #   job.timeouts
+    #     #=> 0
+
+    # :method: touch
     # :call-seq:
-    #   timeouts(force_refresh = false)
+    #   touch => Hash{Symbol => String,Integer}
+    #
+    # Sends command to touch job which extends the ttr. Returns the Beanstalkd response for
+    # the command.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('reserve'))
+    #   job.touch
+    #     #=> {:status=>"TOUCHED", :body=>nil, :connection=>#<Beaneater::Connection host="localhost" port=11300>}
 
     # :method: ttr
+    # :call-seq:
+    #   ttr(force_refresh = false) => Integer
+    #
     # Retrieves the time to run for the job, the number of seconds a worker is allowed to work
     # to run the job. Passing a non-false value for +force_refresh+ will force retrieval of
-    # updated stats for the job
-    # :call-seq:
-    #   timeouts(force_refresh = false)
+    # updated stats for the job By default the value for ttr is cached and will not be updated
+    # unless forced.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('reserve'))
+    #   job.ttr
+    #     #=> 120
 
     # :method: tube
-    # Retrieves the name of the tube that contains job. Passing a non-false value for
-    # +force_refresh+ will force retrieval of updated stats for the job
     # :call-seq:
-    #   timeouts(force_refresh = false)
+    #   tube => String
+    #
+    # Retrieves the name of the tube that contains job. Passing a non-false value for
+    # +force_refresh+ will force retrieval of updated stats for the job By default the
+    # value for tube is cached and will not be updated unless forced.
+    #
+    #   job = StalkClimber::Job.new(connection.transmit('reserve'))
+    #   job.tube
+    #     #=> "stalk_climber"
 
   end
 end