resque-status 0.2.4 → 0.3.0

data/lib/resque/plugins/status.rb

@@ -0,0 +1,213 @@
+require 'resque/plugins/status/hash'
+
+module Resque
+  module Plugins
+
+    # Resque::Plugins::Status is a module you're jobs will include.
+    # It provides helper methods for updating the status/etc from within an
+    # instance as well as class methods for creating and queuing the jobs.
+    #
+    # All you have to do to get this functionality is include Resque::Plugins::Status
+    # and then implement a <tt>perform<tt> method.
+    #
+    # For example
+    #
+    #       class ExampleJob
+    #         include Resque::Plugins::Status
+    #
+    #         def perform
+    #           num = options['num']
+    #           i = 0
+    #           while i < num
+    #             i += 1
+    #             at(i, num)
+    #           end
+    #           completed("Finished!")
+    #         end
+    #
+    #       end
+    #
+    # This job would iterate num times updating the status as it goes. At the end
+    # we update the status telling anyone listening to this job that its complete.
+    module Status
+
+      # The error class raised when a job is killed
+      class Killed < RuntimeError; end
+
+      attr_reader :uuid, :options
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+
+        # The default queue is :statused, this can be ovveridden in the specific job
+        # class to put the jobs on a specific worker queue
+        def queue
+          :statused
+        end
+
+        # used when displaying the Job in the resque-web UI and identifiyng the job
+        # type by status. By default this is the name of the job class, but can be
+        # ovveridden in the specific job class to present a more user friendly job
+        # name
+        def name
+          self.to_s
+        end
+
+        # Create is the primary method for adding jobs to the queue. This would be
+        # called on the job class to create a job of that type. Any options passed are
+        # passed to the Job instance as a hash of options. It returns the UUID of the
+        # job.
+        #
+        # == Example:
+        #
+        #       class ExampleJob
+        #         include Resque::Plugins::Status
+        #
+        #         def perform
+        #           set_status "Hey I'm a job num #{options['num']}"
+        #         end
+        #
+        #       end
+        #
+        #       job_id = ExampleJob.create(:num => 100)
+        #
+        def create(options = {})
+          self.enqueue(self, options)
+        end
+
+        # Adds a job of type <tt>klass<tt> to the queue with <tt>options<tt>.
+        # Returns the UUID of the job
+        def enqueue(klass, options = {})
+          uuid = Resque::Plugins::Status::Hash.create :options => options
+          Resque.enqueue(klass, uuid, options)
+          uuid
+        end
+
+        # This is the method called by Resque::Worker when processing jobs. It
+        # creates a new instance of the job class and populates it with the uuid and
+        # options.
+        #
+        # You should not override this method, rahter the <tt>perform</tt> instance method.
+        def perform(uuid=nil, options = {})
+          uuid ||= Resque::Plugins::Status::Hash.generate_uuid
+          instance = new(uuid, options)
+          instance.safe_perform!
+          instance
+        end
+
+        # Wrapper API to forward a Resque::Job creation API call into a Resque::Plugins::Status call.
+        # This is needed to be used with resque scheduler
+        # http://github.com/bvandenbos/resque-scheduler
+        def scheduled(queue, klass, *args)
+          create(*args)
+        end
+      end
+
+      # Create a new instance with <tt>uuid</tt> and <tt>options</tt>
+      def initialize(uuid, options = {})
+        @uuid    = uuid
+        @options = options
+      end
+
+      # Run by the Resque::Worker when processing this job. It wraps the <tt>perform</tt>
+      # method ensuring that the final status of the job is set regardless of error.
+      # If an error occurs within the job's work, it will set the status as failed and
+      # re-raise the error.
+      def safe_perform!
+        set_status({'status' => 'working'})
+        perform
+        completed unless status && status.completed?
+        on_success if respond_to?(:on_success)
+      rescue Killed
+        logger.info "Job #{self} Killed at #{Time.now}"
+        Resque::Plugins::Status::Hash.killed(uuid)
+        on_killed if respond_to?(:on_killed)
+      rescue => e
+        logger.error e
+        failed("The task failed because of an error: #{e}")
+        if respond_to?(:on_failure)
+          on_failure(e)
+        else
+          raise e
+        end
+      end
+
+      # Returns a Redisk::Logger object scoped to this paticular job/uuid
+      def logger
+        @logger ||= Resque::Plugins::Status::Hash.logger(uuid)
+      end
+
+      # Set the jobs status. Can take an array of strings or hashes that are merged
+      # (in order) into a final status hash.
+      def status=(new_status)
+        Resque::Plugins::Status::Hash.set(uuid, *new_status)
+      end
+
+      # get the Resque::Plugins::Status::Hash object for the current uuid
+      def status
+        Resque::Plugins::Status::Hash.get(uuid)
+      end
+
+      def name
+        "#{self.class.name}(#{options.inspect unless options.empty?})"
+      end
+
+      # Checks against the kill list if this specific job instance should be killed
+      # on the next iteration
+      def should_kill?
+        Resque::Plugins::Status::Hash.should_kill?(uuid)
+      end
+
+      # set the status of the job for the current itteration. <tt>num</tt> and
+      # <tt>total</tt> are passed to the status as well as any messages.
+      # This will kill the job if it has been added to the kill list with
+      # <tt>Resque::Plugins::Status::Hash.kill()</tt>
+      def at(num, total, *messages)
+        tick({
+          'num' => num,
+          'total' => total
+        }, *messages)
+      end
+
+      # sets the status of the job for the current itteration. You should use
+      # the <tt>at</tt> method if you have actual numbers to track the iteration count.
+      # This will kill the job if it has been added to the kill list with
+      # <tt>Resque::Plugins::Status::Hash.kill()</tt>
+      def tick(*messages)
+        kill! if should_kill?
+        set_status({'status' => 'working'}, *messages)
+      end
+
+      # set the status to 'failed' passing along any additional messages
+      def failed(*messages)
+        set_status({'status' => 'failed'}, *messages)
+      end
+
+      # set the status to 'completed' passing along any addional messages
+      def completed(*messages)
+        set_status({
+          'status' => 'completed',
+          'message' => "Completed at #{Time.now}"
+        }, *messages)
+      end
+
+      # kill the current job, setting the status to 'killed' and raising <tt>Killed</tt>
+      def kill!
+        set_status({
+          'status' => 'killed',
+          'message' => "Killed at #{Time.now}"
+        })
+        raise Killed
+      end
+
+      private
+      def set_status(*args)
+        self.status = [status, {'name'  => self.name}, args].flatten
+      end
+
+    end
+  end
+end

data/lib/resque/plugins/status/hash.rb

@@ -0,0 +1,242 @@
+module Resque
+  module Plugins
+    module Status
+      VERSION = '0.3.0'
+
+      # Resque::Plugins::Status::Hash is a Hash object that has helper methods for dealing with
+      # the common status attributes. It also has a number of class methods for
+      # creating/updating/retrieving status objects from Redis
+      class Hash < ::Hash
+
+        extend Resque::Helpers
+
+        # Create a status, generating a new UUID, passing the message to the status
+        # Returns the UUID of the new status.
+        def self.create(*messages)
+          uuid = generate_uuid
+          set(uuid, *messages)
+          redis.zadd(set_key, Time.now.to_i, uuid)
+          redis.zremrangebyscore(set_key, 0, Time.now.to_i - @expire_in) if @expire_in
+          uuid
+        end
+
+        # Get a status by UUID. Returns a Resque::Plugins::Status::Hash
+        def self.get(uuid)
+          val = redis.get(status_key(uuid))
+          val ? Resque::Plugins::Status::Hash.new(uuid, decode(val)) : nil
+        end
+
+        # set a status by UUID. <tt>messages</tt> can be any number of stirngs or hashes
+        # that are merged in order to create a single status.
+        def self.set(uuid, *messages)
+          val = Resque::Plugins::Status::Hash.new(uuid, *messages)
+          redis.set(status_key(uuid), encode(val))
+          if expire_in
+            redis.expire(status_key(uuid), expire_in)
+          end
+          val
+        end
+
+        # clear statuses from redis passing an optional range. See `statuses` for info
+        # about ranges
+        def self.clear(range_start = nil, range_end = nil)
+          status_ids(range_start, range_end).each do |id|
+            redis.del(status_key(id))
+            redis.zrem(set_key, id)
+          end
+        end
+
+        # returns a Redisk::Logger scoped to the UUID. Any options passed are passed
+        # to the logger initialization.
+        #
+        # Ensures that Redisk is logging to the same Redis connection as Resque.
+        def self.logger(uuid, options = {})
+          Redisk.redis = redis
+          Redisk::Logger.new(logger_key(uuid), options)
+        end
+
+        def self.count
+          redis.zcard(set_key)
+        end
+
+        # Return <tt>num</tt> Resque::Plugins::Status::Hash objects in reverse chronological order.
+        # By default returns the entire set.
+        # @param [Numeric] range_start The optional starting range
+        # @param [Numeric] range_end The optional ending range
+        # @example retuning the last 20 statuses
+        #   Resque::Plugins::Status::Hash.statuses(0, 20)
+        def self.statuses(range_start = nil, range_end = nil)
+          status_ids(range_start, range_end).collect do |id|
+            get(id)
+          end.compact
+        end
+
+        # Return the <tt>num</tt> most recent status/job UUIDs in reverse chronological order.
+        def self.status_ids(range_start = nil, range_end = nil)
+          unless range_end && range_start
+            # Because we want a reverse chronological order, we need to get a range starting
+            # by the higest negative number.
+            redis.zrevrange(set_key, 0, -1) || []
+          else
+            # Because we want a reverse chronological order, we need to get a range starting
+            # by the higest negative number. The ordering is transparent from the API user's
+            # perspective so we need to convert the passed params
+            (redis.zrevrange(set_key, (range_start.abs), ((range_end || 1).abs)) || [])
+          end
+        end
+
+        # Kill the job at UUID on its next iteration this works by adding the UUID to a
+        # kill list (a.k.a. a list of jobs to be killed. Each iteration the job checks
+        # if it _should_ be killed by calling <tt>tick</tt> or <tt>at</tt>. If so, it raises
+        # a <tt>Resque::Plugins::Status::Killed</tt> error and sets the status to 'killed'.
+        def self.kill(uuid)
+          redis.sadd(kill_key, uuid)
+        end
+
+        # Remove the job at UUID from the kill list
+        def self.killed(uuid)
+          redis.srem(kill_key, uuid)
+        end
+
+        # Return the UUIDs of the jobs on the kill list
+        def self.kill_ids
+          redis.smembers(kill_key)
+        end
+
+        # Check whether a job with UUID is on the kill list
+        def self.should_kill?(uuid)
+          redis.sismember(kill_key, uuid)
+        end
+
+        # The time in seconds that jobs and statuses should expire from Redis (after
+        # the last time they are touched/updated)
+        def self.expire_in
+          @expire_in
+        end
+
+        # Set the <tt>expire_in</tt> time in seconds
+        def self.expire_in=(seconds)
+          @expire_in = seconds.nil? ? nil : seconds.to_i
+        end
+
+        def self.status_key(uuid)
+          "status:#{uuid}"
+        end
+
+        def self.set_key
+          "_statuses"
+        end
+
+        def self.kill_key
+          "_kill"
+        end
+
+        def self.logger_key(uuid)
+          "_log:#{uuid}"
+        end
+
+        def self.generate_uuid
+          UUID.generate(:compact)
+        end
+
+        def self.hash_accessor(name, options = {})
+          options[:default] ||= nil
+          coerce = options[:coerce] ? ".#{options[:coerce]}" : ""
+          module_eval <<-EOT
+          def #{name}
+            value = (self['#{name}'] ? self['#{name}']#{coerce} : #{options[:default].inspect})
+            yield value if block_given?
+            value
+          end
+
+          def #{name}=(value)
+            self['#{name}'] = value
+          end
+
+          def #{name}?
+            !!self['#{name}']
+          end
+          EOT
+        end
+
+        STATUSES = %w{queued working completed failed killed}.freeze
+
+        hash_accessor :uuid
+        hash_accessor :name
+        hash_accessor :status
+        hash_accessor :message
+        hash_accessor :time
+        hash_accessor :options
+
+        hash_accessor :num
+        hash_accessor :total
+
+        # Create a new Resque::Plugins::Status::Hash object. If multiple arguments are passed
+        # it is assumed the first argument is the UUID and the rest are status objects.
+        # All arguments are subsequentily merged in order. Strings are assumed to
+        # be messages.
+        def initialize(*args)
+          super nil
+          base_status = {
+            'time' => Time.now.to_i,
+            'status' => 'queued'
+          }
+          base_status['uuid'] = args.shift if args.length > 1
+          status_hash = args.inject(base_status) do |final, m|
+            m = {'message' => m} if m.is_a?(String)
+            final.merge(m || {})
+          end
+          self.replace(status_hash)
+        end
+
+        # calculate the % completion of the job based on <tt>status</tt>, <tt>num</tt>
+        # and <tt>total</tt>
+        def pct_complete
+          case status
+          when 'completed' then 100
+          when 'queued' then 0
+          else
+            t = (total == 0 || total.nil?) ? 1 : total
+            (((num || 0).to_f / t.to_f) * 100).to_i
+          end
+        end
+
+        # Return the time of the status initialization. If set returns a <tt>Time</tt>
+        # object, otherwise returns nil
+        def time
+          time? ? Time.at(self['time']) : nil
+        end
+
+        STATUSES.each do |status|
+          define_method("#{status}?") do
+            self['status'] === status
+          end
+        end
+
+        # Can the job be killed? 'failed', 'completed', and 'killed' jobs cant be killed
+        # (for pretty obvious reasons)
+        def killable?
+          !['failed', 'completed', 'killed'].include?(self.status)
+        end
+
+        unless method_defined?(:to_json)
+          def to_json(*args)
+            json
+          end
+        end
+
+        # Return a JSON representation of the current object.
+        def json
+          h = self.dup
+          h['pct_complete'] = pct_complete
+          self.class.encode(h)
+        end
+
+        def inspect
+          "#<Resque::Plugins::Status::Hash #{super}>"
+        end
+
+      end
+    end
+  end
+end