powerhome-resque-status 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d9c0c0ab1c7036c3336d46117db310f73503b76d19ee9117dd4944668abc1a0
+  data.tar.gz: e9df86dd8599410cec3c1ce09e2afdc8785b36011fa921c9f2b11052a2b2a38d
+SHA512:
+  metadata.gz: 022f4fedf4fd1ef8ceeb413a0ded6c9e118ae67ca78f0a3c3f044c79a0e950d274a4d5db4178022eeda6b14b04beab7c6f710bb0355502e871b8fefbcf2d70db
+  data.tar.gz: ba037b5c574172c20bd394955ed6a9c822c0cb717d8da027b9b1d0a1330dae9dfd459f380484a9254a956f07bc85b317332575660133b5886e63585a06f7f19c

data/.document

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

data/Gemfile

@@ -0,0 +1,12 @@
+source 'https://rubygems.org'
+
+gem 'resque', '~>1.19'
+
+group :test do
+  gem 'mocha', '~>0.9'
+  gem 'minitest', '~> 5.5'
+end
+
+group :development do
+  gem 'jeweler'
+end

data/Gemfile.lock

@@ -0,0 +1,85 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.4.0)
+    builder (3.2.4)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    faraday (0.9.2)
+      multipart-post (>= 1.2, < 3)
+    git (1.7.0)
+      rchardet (~> 1.8)
+    github_api (0.16.0)
+      addressable (~> 2.4.0)
+      descendants_tracker (~> 0.0.4)
+      faraday (~> 0.8, < 0.10)
+      hashie (>= 3.4)
+      mime-types (>= 1.16, < 3.0)
+      oauth2 (~> 1.0)
+    hashie (4.1.0)
+    highline (2.0.3)
+    jeweler (2.3.9)
+      builder
+      bundler
+      git (>= 1.2.5)
+      github_api (~> 0.16.0)
+      highline (>= 1.6.15)
+      nokogiri (>= 1.5.10)
+      psych
+      rake
+      rdoc
+      semver2
+    jwt (2.2.2)
+    metaclass (0.0.2)
+    mime-types (2.99.3)
+    mini_portile2 (2.4.0)
+    minitest (5.5.1)
+    mocha (0.14.0)
+      metaclass (~> 0.0.1)
+    multi_json (1.15.0)
+    multi_xml (0.6.0)
+    multipart-post (2.1.1)
+    nokogiri (1.10.10)
+      mini_portile2 (~> 2.4.0)
+    oauth2 (1.4.4)
+      faraday (>= 0.8, < 2.0)
+      jwt (>= 1.0, < 3.0)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (>= 1.2, < 3)
+    psych (3.2.0)
+    rack (1.6.13)
+    rack-protection (1.2.0)
+      rack
+    rake (13.0.1)
+    rchardet (1.8.0)
+    rdoc (6.2.1)
+    redis (3.0.2)
+    redis-namespace (1.2.1)
+      redis (~> 3.0.0)
+    resque (1.23.0)
+      multi_json (~> 1.0)
+      redis-namespace (~> 1.0)
+      sinatra (>= 0.9.2)
+      vegas (~> 0.1.2)
+    semver2 (3.4.2)
+    sinatra (1.3.3)
+      rack (~> 1.3, >= 1.3.6)
+      rack-protection (~> 1.2)
+      tilt (~> 1.3, >= 1.3.3)
+    thread_safe (0.3.6)
+    tilt (1.3.3)
+    vegas (0.1.11)
+      rack (>= 1.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  jeweler
+  minitest (~> 5.5)
+  mocha (~> 0.9)
+  resque (~> 1.19)
+
+BUNDLED WITH
+   2.1.4

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,185 @@
+= 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
+
+resque-status *requires Redis >= 1.1* (though I recommend getting the latest stable version).
+You can download Redis here: http://code.google.com/p/redis/ or install it
+using homebrew (brew install redis).
+
+Install the resque-status gem (which will pull in the dependencies).
+
+  gem install resque-status
+
+With newer Rails add this to your Gemfile:
+
+  # Gemfile
+  gem 'resque-status'
+
+Then in an initializer:
+
+  # config/initializers/resque.rb
+  Resque.redis = "your/redis/socket" # default localhost:6379
+  Resque::Plugins::Status::Hash.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::Plugins::Status module. An example job would look something like:
+
+  class SleepJob
+    include Resque::Plugins::Status
+
+    def perform
+      total = (options['length'] || 1000).to_i
+      total.times do |i|
+        num = i+1
+        at(num, total, "At #{num} of #{total}")
+        sleep(1)
+      end
+    end
+  end
+
+One major difference is that instead 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::Plugins::Status::Hash.get(job_id)
+
+This returns a Resque::Plugins::Status::Hash 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::Plugins::Status::Hash.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::Plugins::Status::Hash.statuses #=> [#<Resque::Plugins::Status::Hash>, ...]
+
+=== Passing back data from the job
+
+You may want to save data from inside the job to access it from outside the job.
+
+A common use-case is web-triggered jobs that create files, later available for
+download by the user.
+
+A Status is actually just a hash, so inside a job you can do:
+
+    set_status(filename: "myfilename")
+
+Also, all the status setting methods take any number of hash arguments. So you could do:
+
+    completed('filename' => '/myfilename')
+
+=== 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::Plugins::Status::Hash.kill(job_id)
+
+The next time the job at job_id calls <tt>at</tt> or <tt>tick</tt>, it will raise a <tt>Killed</tt>
+error and set the status to killed.
+
+=== Percent Complete and setting the message
+
+Use <tt>at</tt> or <tt>tick</tt> to show progress in your job's <tt>perform</tt> function
+(which is displayed on the resque-web status tab). This will also be where <tt>Killed</tt>
+is raised if the job is killed.
+
+  at(steps_completed, total_steps, "${steps_completed} of #{total_steps} steps completed!")
+
+=== 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 their related keys will expire in expire_in seconds from the last time theyre updated:
+
+  Resque::Plugins::Status::Hash.expire_in = (60 * 60) # 1 hour
+=== Testing
+
+Recent versions of Resque introduced `Resque.inline` which changes the behavior to
+instead of enqueueing and performing jobs to just executing them inline. In Resque
+itself this removes the dependency on a Redis, however, `Resque::Status` uses Redis
+to store information about jobs, so though `inline` "works", you will still need
+to use or mock a redis connection. You should be able to use a library like
+https://github.com/causes/mock_redis alongside `inline` if you really want to
+avoid Redis connections in your test.
+
+=== resque-web
+
+Though the main purpose of these trackable jobs is to allow you to surface the status
+of user created jobs through your 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'
+
+Then 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
+
+== More
+
+Source: http://github.com/quirkey/resque-status
+API Docs: http://rdoc.info/projects/quirkey/resque-status
+Examples: http://github.com/quirkey/resque-status/tree/master/examples
+Resque: http://github.com/defunkt/resque
+
+== 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,48 @@
+$LOAD_PATH.unshift './lib'
+
+require 'rubygems'
+require 'rake'
+require 'resque-status'
+require 'resque/tasks'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "powerhome-resque-status"
+    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::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"
+    gem.authors = ["Aaron Quint"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::RubygemsDotOrgTasks.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
+
+task :default => :test

data/examples/sleep_job.rb

@@ -0,0 +1,36 @@
+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
+  include Resque::Plugins::Status
+
+  def perform
+    total = options.has_key?('length') ? 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::Plugins::Status::Hash.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-status.rb

@@ -0,0 +1 @@
+require "#{File.dirname(__FILE__)}/resque/status"

data/lib/resque/job_with_status.rb

@@ -0,0 +1,5 @@
+module Resque
+  class JobWithStatus
+    include Resque::Plugins::Status
+  end
+end

data/lib/resque/plugins/status.rb

@@ -0,0 +1,254 @@
+module Resque
+  module Plugins
+
+    # Resque::Plugins::Status is a module your 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
+      VERSION = '0.6.0'
+
+      STATUS_QUEUED = 'queued'
+      STATUS_WORKING = 'working'
+      STATUS_COMPLETED = 'completed'
+      STATUS_FAILED = 'failed'
+      STATUS_KILLED = 'killed'
+      STATUSES = [
+        STATUS_QUEUED,
+        STATUS_WORKING,
+        STATUS_COMPLETED,
+        STATUS_FAILED,
+        STATUS_KILLED
+      ].freeze
+
+      autoload :Hash, 'resque/plugins/status/hash'
+
+      # The error class raised when a job is killed
+      class Killed < RuntimeError; end
+      class NotANumber < 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 if the job was queued, or nil if the job was
+        # rejected by a before_enqueue hook.
+        def enqueue(klass, options = {})
+          self.enqueue_to(Resque.queue_from_class(klass) || queue, klass, options)
+        end
+
+        # Adds a job of type <tt>klass<tt> to a specified queue with <tt>options<tt>.
+        #
+        # Returns the UUID of the job if the job was queued, or nil if the job was
+        # rejected by a before_enqueue hook.
+        def enqueue_to(queue, klass, options = {})
+          uuid = Resque::Plugins::Status::Hash.generate_uuid
+          Resque::Plugins::Status::Hash.create uuid, :options => options
+
+          if Resque.enqueue_to(queue, klass, uuid, options)
+            uuid
+          else
+            Resque::Plugins::Status::Hash.remove(uuid)
+            nil
+          end
+        end
+
+        # Removes a job of type <tt>klass<tt> from the queue.
+        #
+        # The initially given options are retrieved from the status hash.
+        # (Resque needs the options to find the correct queue entry)
+        def dequeue(klass, uuid)
+          status = Resque::Plugins::Status::Hash.get(uuid)
+          Resque.dequeue(klass, uuid, status.options)
+        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)
+          self.enqueue_to(queue, self, *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' => STATUS_WORKING})
+        perform
+        if status && status.failed?
+          on_failure(status.message) if respond_to?(:on_failure)
+          return
+        elsif status && !status.completed?
+          completed
+        end
+        on_success if respond_to?(:on_success)
+      rescue Killed
+        Resque::Plugins::Status::Hash.killed(uuid)
+        on_killed if respond_to?(:on_killed)
+      rescue => e
+        failed("The task failed because of an error: #{e}")
+        if respond_to?(:on_failure)
+          on_failure(e)
+        else
+          raise e
+        end
+      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)
+        if total.to_f <= 0.0
+          raise(NotANumber, "Called at() with total=#{total} which is not a number")
+        end
+        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' => STATUS_WORKING}, *messages)
+      end
+
+      # set the status to 'failed' passing along any additional messages
+      def failed(*messages)
+        set_status({'status' => STATUS_FAILED}, *messages)
+      end
+
+      # set the status to 'completed' passing along any addional messages
+      def completed(*messages)
+        set_status({
+          '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' => 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