resque-status 0.2.4 → 0.3.0

data/Gemfile

@@ -0,0 +1,8 @@
+source :rubygems
+
+gem 'redisk', '>= 0.2.1'
+gem 'resque', '>= 1.3.1'
+gem 'uuid', '>= 2.0.2'
+gem 'mocha', '>= 0.9.8'
+gem 'shoulda', '>= 2.10.2'
+gem 'jeweler'

data/Gemfile.lock

@@ -0,0 +1,51 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    jeweler (1.6.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+    json (1.4.6)
+    macaddr (1.5.0)
+      systemu (>= 2.4.0)
+    metaclass (0.0.1)
+    mocha (0.10.3)
+      metaclass (~> 0.0.1)
+    rack (1.4.0)
+    rack-protection (1.2.0)
+      rack
+    rake (0.9.2.2)
+    redis (2.2.2)
+    redis-namespace (1.1.0)
+      redis (< 3.0.0)
+    redisk (0.2.2)
+      redis (>= 0.1.1)
+      redis-namespace (>= 0.1.0)
+    resque (1.15.0)
+      json (~> 1.4.6)
+      redis-namespace (>= 0.10.0)
+      sinatra (>= 0.9.2)
+      vegas (~> 0.1.2)
+    shoulda (2.11.3)
+    sinatra (1.3.2)
+      rack (~> 1.3, >= 1.3.6)
+      rack-protection (~> 1.2)
+      tilt (~> 1.3, >= 1.3.3)
+    systemu (2.4.2)
+    tilt (1.3.3)
+    uuid (2.3.4)
+      macaddr (~> 1.0)
+    vegas (0.1.8)
+      rack (>= 1.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  jeweler
+  mocha (>= 0.9.8)
+  redisk (>= 0.2.1)
+  resque (>= 1.3.1)
+  shoulda (>= 2.10.2)
+  uuid (>= 2.0.2)

data/README.rdoc

@@ -19,41 +19,53 @@ Install the resque-status gem (which will pull in the dependencies).
 
   gem install resque-status
   
-To use with Rails, you can install as a plugin or add the gem to you're config:
+To use with Rails 2.x, you can install as a plugin or add the gem to you're config:
   
   # environment.rb
-  config.gem 'resque-status', :lib => 'resque/status'
-  
+  config.gem 'resque-status'
+
+With newer Rails add this to your Gemfile:
+
+  # Gemfile
+  gem 'resque-status'
+
 Then in an initializer:
   
   # config/initializers/resque.rb
-  require 'resque/job_with_status'
-  
   Resque.redis = "your/redis/socket" # default localhost:6379
-  Resque::Status.expire_in = (24 * 60 * 60) # 24hrs in seconds
+  Resque::Plugins::Status::Hash.expire_in = (24 * 60 * 60) # 24hrs in seconds
+
+== NOTES ABOUT UPGRADING TO >= v0.3 
+
+Even though this was one of the first resque plugins, later versions of resque added stricter plugin conventions 
+that resque-status did not completely conform to (See: https://github.com/defunkt/resque/blob/master/docs/PLUGINS.md)
+
+Thanks to some work from @EugZol and @bukowskis v0.3 moved around some code to conform:
+
+`Resque::Status` is now `Resque::Plugins::Status` and is now an `include`able module.
+`Resque::Status.get/etc` have been moved to `Resque::Plugins::Status::Hash`
   
 == Usage
 
 The most direct way to use resque-status is to create your jobs using the 
-Resque::JobWithStatus class. An example job would look something like:
+Resque::Plugins::Status module. An example job would look something like:
 
-  class SleepJob < Resque::JobWithStatus
+  class SleepJob
+    include Resque::Plugins::Status
   
     def perform
-      total = options['length'].to_i || 1000
+      total = (options['length'] || 1000).to_i
       num = 0
       while num < total
         at(num, total, "At #{num} of #{total}")
         sleep(1)
         num += 1
       end
-      completed
     end
   
   end
 
-Instead of normal Resque job classes, we inherit from the JobWithStatus class. 
-Another major difference is that intead of implementing <tt>perform</tt> as a 
+One major difference is that intead of implementing <tt>perform</tt> as a 
 class method, we do our job implementation within instances of the job class.
 
 In order to queue a SleepJob up, we also won't use <tt>Resque.enqueue</tt>, instead
@@ -67,9 +79,9 @@ instance as options['length'] (as you can see above).
 
 Now that we have a UUID its really easy to get the status:
 
-  status = Resque::Status.get(job_id)
+  status = Resque::Plugins::Status::Hash.get(job_id)
   
-This returns a Resque::Status object, which is a Hash (with benefits).
+This returns a Resque::Plugins::Status::Hash object, which is a Hash (with benefits).
 
   status.pct_complete #=> 0
   status.status #=> 'queued'
@@ -81,7 +93,7 @@ This returns a Resque::Status object, which is a Hash (with benefits).
 Once the worker reserves the job, the instance of SleepJob updates the status at
 each iteration using <tt>at()</tt>
 
-  status = Resque::Status.get(job_id)
+  status = Resque::Plugins::Status::Hash.get(job_id)
   status.working? #=> true
   status.num #=> 5
   status.total => 100
@@ -92,7 +104,7 @@ the error is re-raised so that Resque can capture it.
 
 Its also possible to get a list of current/recent job statuses:
 
-  Resque::Status.statuses #=> [#<Resque::Status>, ...]
+  Resque::Plugins::Status::Hash.statuses #=> [#<Resque::Plugins::Status::Hash>, ...]
 
 === Passing back data from the job
 
@@ -115,7 +127,7 @@ Because we're tracking UUIDs per instance, and we're checking in/updating the st
 on each iteration (using <tt>at</tt> or <tt>tick</tt>) we can kill specific jobs
 by UUID.
 
-  Resque::Status.kill(job_id)
+  Resque::Plugins::Status::Hash.kill(job_id)
 
 The next time the job at job_id calls <tt>at</tt> or tick, it will raise a Killed 
 error and set the status to killed.
@@ -126,7 +138,7 @@ Since Redis is RAM based, we probably don't want to keep these statuses around f
 (at least until @antirez releases the VM feature). By setting expire_in, all statuses
 and thier related keys will expire in expire_in seconds from the last time theyre updated:
 
-  Resque::Status.expire_in = (60 * 60) # 1 hour
+  Resque::Plugins::Status::Hash.expire_in = (60 * 60) # 1 hour
 
 === resque-web
 

data/Rakefile

@@ -1,15 +1,17 @@
+$LOAD_PATH.unshift './lib'
+
 require 'rubygems'
 require 'rake'
-require File.join(File.expand_path('.'), 'lib/resque/status')
+require 'resque-status'
 require 'resque/tasks'
 
 begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
     gem.name = "resque-status"
-    gem.version = Resque::Status::VERSION
+    gem.version = Resque::Plugins::Status::VERSION
     gem.summary = %Q{resque-status is an extension to the resque queue system that provides simple trackable jobs.}
-    gem.description = %Q{resque-status is an extension to the resque queue system that provides simple trackable jobs. It provides a Resque::Status class which can set/get the statuses of jobs and a Resque::JobWithStatus class that when subclassed provides easily trackable/killable jobs.}
+    gem.description = %Q{resque-status is an extension to the resque queue system that provides simple trackable jobs. It provides a Resque::Plugins::Status::Hash class which can set/get the statuses of jobs and a Resque::Plugins::Status class that when included provides easily trackable/killable jobs.}
     gem.email = "aaron@quirkey.com"
     gem.homepage = "http://github.com/quirkey/resque-status"
     gem.rubyforge_project = "quirkey"
@@ -46,7 +48,7 @@ rescue LoadError
   end
 end
 
-task :test => :check_dependencies
+task :test
 
 task :default => :test
 

data/examples/sleep_job.rb

@@ -2,10 +2,11 @@ require 'resque/job_with_status' # in rails you would probably do this in an ini
 
 # sleeps for _length_ seconds updating the status every second
 
-class SleepJob < Resque::JobWithStatus
-  
+class SleepJob
+  include Resque::Plugins::Status
+
   def perform
-    total = options['length'].to_i || 1000
+    total = options.has_key?('length') ? options['length'].to_i : 1000
     num = 0
     while num < total
       at(num, total, "At #{num} of #{total}")
@@ -14,22 +15,22 @@ class SleepJob < Resque::JobWithStatus
     end
     completed
   end
-  
+
 end
 
 
 if __FILE__ == $0
   # Make sure you have a worker running
   # rake -rexamples/sleep_job.rb resque:work QUEUE=statused
-  
+
   # running the job
   puts "Creating the SleepJob"
   job_id = SleepJob.create :length => 100
   puts "Got back #{job_id}"
-  
+
   # check the status until its complete
-  while status = Resque::Status.get(job_id) and !status.completed? && !status.failed?
+  while status = Resque::Plugins::Status::Hash.get(job_id) and !status.completed? && !status.failed?
     sleep 1
     puts status.inspect
   end
-end
+end

data/init.rb

@@ -1 +1 @@
-require 'resque/status'
+require 'resque-status'

data/lib/resque-status.rb

@@ -0,0 +1 @@
+require 'resque/status'

data/lib/resque/job_with_status.rb

@@ -1,202 +1,5 @@
-require 'resque/status'
-
 module Resque
-
-  # JobWithStatus is a base class that you're jobs will inherit from.
-  # 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 inherit from JobWithStatus
-  # and then implement a <tt>perform<tt> method.
-  #
-  # For example:
-  #
-  #       class ExampleJob < Resque::JobWithStatus
-  #
-  #         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.
   class JobWithStatus
-
-    # The error class raised when a job is killed
-    class Killed < RuntimeError; end
-
-    attr_reader :uuid, :options
-
-    # The default queue is :statused, this can be ovveridden in the specific job
-    # class to put the jobs on a specific worker queue
-    def self.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 self.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 < Resque::JobWithStatus
-    #
-    #         def perform
-    #           set_status "Hey I'm a job num #{options['num']}"
-    #         end
-    #
-    #       end
-    #
-    #       job_id = ExampleJob.create(:num => 100)
-    #
-    def self.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 self.enqueue(klass, options = {})
-      uuid = Resque::Status.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 self.perform(uuid=nil, options = {})
-      uuid ||= Resque::Status.generate_uuid
-      instance = new(uuid, options)
-      instance.safe_perform!
-      instance
-    end
-
-    # Wrapper API to forward a Resque::Job creation API call into a JobWithStatus call.
-    # This is needed to be used with resque scheduler
-    # http://github.com/bvandenbos/resque-scheduler
-    def self.scheduled(queue, klass, *args)
-      create(*args)
-    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::Status.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::Status.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::Status.set(uuid, *new_status)
-    end
-
-    # get the Resque::Status object for the current uuid
-    def status
-      Resque::Status.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::Status.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::Status.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::Status.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
-
+    include Resque::Plugins::Status
   end
 end