resque-status 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,23 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+doc
+.yardoc

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Aaron Quint
+
+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.rdoc

@@ -0,0 +1,145 @@
+= resque-status
+
+resque-status is an extension to the resque queue system that provides simple trackable jobs.
+
+== About
+
+resque-status provides a set of simple classes that extend resque's default 
+functionality (with 0% monkey patching) to give apps a way to track specific
+job instances and their status. It achieves this by giving job instances UUID's
+and allowing the job instances to report their status from within their iterations.
+
+== Installation
+
+  gem install resque-status
+  
+To use with Rails, you can install as a plugin or add the gem to you're config:
+  
+  # environment.rb
+  config.gem 'resque-status', :lib => '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
+  
+== 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:
+
+  class SleepJob < Resque::JobWithStatus
+  
+    def perform
+      total = options['length'].to_i || 1000
+      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 
+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
+we'll use the <tt>create</tt> class method which will wrap <tt>enqueue</tt> and 
+creating a unique id (UUID) for us to track the job with.
+
+  job_id = SleepJob.create(:length => 100)
+  
+This will create a UUID enqueue the job and pass the :length option on the SleepJob
+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)
+  
+This returns a Resque::Status object, which is a Hash (with benefits).
+
+  status.pct_complete #=> 0
+  status.status #=> 'queued'
+  status.queued? #=> true
+  status.working? #=> false
+  status.time #=> Time object        
+  status.message #=> "Created at ..."
+
+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.working? #=> true
+  status.num #=> 5
+  status.total => 100
+  status.pct_complete => 5
+
+If an error occurs within the job instance, the status is set to 'failed' and then
+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>, ...]
+
+=== Kill! Kill! Kill!
+
+Because we're tracking UUIDs per instance, and we're checking in/updating the status
+on each iteration (using <tt>at</tt> or <tt>tick</tt>) we can kill specific jobs
+by UUID.
+
+  Resque::Status.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.
+
+=== Expiration
+
+Since Redis is RAM based, we probably don't want to keep these statuses around forever 
+(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-web
+
+Though the main purpose of these trackable jobs is to allow you to surface the status
+of user created jobs through you're apps' own UI, I've added a simple example UI
+as a plugin to resque-web.
+
+To use, you need to setup a resque-web config file:
+
+  # ~/resque_conf.rb  
+  require 'resque/status_server'
+  
+The start resque-web with your config:
+
+  resque-web ~/resque_conf.rb
+  
+This should launch resque-web in your browser and you should see a 'Statuses' tab.
+
+http://img.skitch.com/20100119-k166xyijcjpkk6xtwnw3854a8g.jpg
+            
+== Thanks
+
+Resque is awesome, @defunkt needs a shout-out. 
+  
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Aaron Quint. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,60 @@
+require 'rubygems'
+require 'rake'
+require 'lib/resque/status'
+require 'resque/tasks'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "resque-status"
+    gem.version = Resque::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.email = "aaron@quirkey.com"
+    gem.homepage = "http://github.com/quirkey/resque-status"
+    gem.rubyforge_project = "quirkey"
+    gem.authors = ["Aaron Quint"]
+    gem.add_dependency "uuid", ">=2.0.2"
+    gem.add_dependency "resque", ">=1.3.1"
+    gem.add_dependency "redisk", ">=0.2.0"
+    gem.add_development_dependency "shoulda", ">=2.10.2"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "resque-status #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/examples/sleep_job.rb

@@ -0,0 +1,35 @@
+require 'resque/job_with_status' # in rails you would probably do this in an initializer
+
+# sleeps for _length_ seconds updating the status every second
+
+class SleepJob < Resque::JobWithStatus
+  
+  def perform
+    total = options['length'].to_i || 1000
+    num = 0
+    while num < total
+      at(num, total, "At #{num} of #{total}")
+      sleep(1)
+      num += 1
+    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?
+    sleep 1
+    puts status.inspect
+  end
+end

data/init.rb

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

data/lib/resque/job_with_status.rb

@@ -0,0 +1,187 @@
+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
+      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, options = {})
+      instance = new(uuid, options)
+      instance.safe_perform!
+      instance
+    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!
+      perform
+      completed unless status && status.completed?
+    rescue Killed
+      logger.info "Job #{self} Killed at #{Time.now}"
+      Resque::Status.killed(uuid)
+    rescue => e
+      logger.error e
+      failed("The task failed because of an error: #{e.inspect}")
+      raise e
+    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
+    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"
+      })
+      raise Killed
+    end
+    
+    private
+    def set_status(*args)
+      self.status = [{'name'  => self.name}, args].flatten
+    end
+    
+  end
+end