resque-state 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 31009a841c78f3ee6288076f7aaf5e5bb7e1f1b0
+  data.tar.gz: 7afc133998ecc29bb2cc87e35b3af102a1d9cc14
+SHA512:
+  metadata.gz: 55a8fe604e4f315a3c994f5381fe35c824a0d8995c99f9c573afa7a882d4ff719df3a157e8d923f5b9a1210162264b590f0d67537e6771d4fedcf5ee355f02a2
+  data.tar.gz: d7d756b11b3dbd8cde9f6c3694a6f094c72a772412c75c400fce68ef658859a97e507c01701047f84682d6c23e93d245241a0ecfaa8a0210027d28241e01dbe9

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+ - 2.2
+ - jruby

data/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+gem 'resque', '~>1.19'
+
+group :test do
+  gem 'mocha', '~>0.9'
+  gem 'minitest', '~> 5.5'
+  gem 'simplecov'
+  gem 'fakeredis', '~> 0.5.0'
+  gem "codeclimate-test-reporter", require: nil
+end
+
+group :development do
+  gem 'jeweler', '~> 2.1'
+end

data/Gemfile.lock

@@ -0,0 +1,102 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.4.0)
+    builder (3.2.2)
+    codeclimate-test-reporter (0.6.0)
+      simplecov (>= 0.7.1, < 1.0.0)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    docile (1.1.5)
+    fakeredis (0.5.0)
+      redis (~> 3.0)
+    faraday (0.9.2)
+      multipart-post (>= 1.2, < 3)
+    git (1.3.0)
+    github_api (0.14.5)
+      addressable (~> 2.4.0)
+      descendants_tracker (~> 0.0.4)
+      faraday (~> 0.8, < 0.10)
+      hashie (>= 3.4)
+      oauth2 (~> 1.0)
+    hashie (3.4.4)
+    highline (1.7.8)
+    jeweler (2.1.1)
+      builder
+      bundler (>= 1.0)
+      git (>= 1.2.5)
+      github_api
+      highline (>= 1.6.15)
+      nokogiri (>= 1.5.10)
+      rake
+      rdoc
+      semver
+    json (1.8.3)
+    json (1.8.3-java)
+    jwt (1.5.4)
+    metaclass (0.0.4)
+    mini_portile2 (2.1.0)
+    minitest (5.9.0)
+    mocha (0.14.0)
+      metaclass (~> 0.0.1)
+    mono_logger (1.1.0)
+    multi_json (1.12.1)
+    multi_xml (0.5.5)
+    multipart-post (2.0.0)
+    nokogiri (1.6.8)
+      mini_portile2 (~> 2.1.0)
+      pkg-config (~> 1.1.7)
+    nokogiri (1.6.8-java)
+    oauth2 (1.2.0)
+      faraday (>= 0.8, < 0.10)
+      jwt (~> 1.0)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (>= 1.2, < 3)
+    pkg-config (1.1.7)
+    rack (1.6.4)
+    rack-protection (1.5.3)
+      rack
+    rake (11.2.2)
+    rdoc (4.2.2)
+      json (~> 1.4)
+    redis (3.3.1)
+    redis-namespace (1.5.2)
+      redis (~> 3.0, >= 3.0.4)
+    resque (1.26.0)
+      mono_logger (~> 1.0)
+      multi_json (~> 1.0)
+      redis-namespace (~> 1.3)
+      sinatra (>= 0.9.2)
+      vegas (~> 0.1.2)
+    semver (1.0.1)
+    simplecov (0.12.0)
+      docile (~> 1.1.0)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    sinatra (1.4.7)
+      rack (~> 1.5)
+      rack-protection (~> 1.4)
+      tilt (>= 1.3, < 3)
+    thread_safe (0.3.5)
+    thread_safe (0.3.5-java)
+    tilt (2.0.5)
+    vegas (0.1.11)
+      rack (>= 1.0.0)
+
+PLATFORMS
+  java
+  ruby
+
+DEPENDENCIES
+  codeclimate-test-reporter
+  fakeredis (~> 0.5.0)
+  jeweler (~> 2.1)
+  minitest (~> 5.5)
+  mocha (~> 0.9)
+  resque (~> 1.19)
+  simplecov
+
+BUNDLED WITH
+   1.12.5

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2016 Nathan V
+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,208 @@
+= resque-state
+
+{<img src="https://img.shields.io/badge/license-MIT-blue.svg" />}[https://github.com/nathan-v/resque-state/blob/master/LICENSE]
+
+{<img src="https://codeclimate.com/github/nathan-v/resque-state/badges/gpa.svg" />}[https://codeclimate.com/github/nathan-v/resque-state]
+{<img src="https://codeclimate.com/github/nathan-v/resque-state/badges/issue_count.svg" />}[https://codeclimate.com/github/nathan-v/resque-state]
+{<img src="https://codeclimate.com/github/nathan-v/resque-state/badges/coverage.svg" />}[https://codeclimate.com/github/nathan-v/resque-state/coverage]
+{<img src="https://travis-ci.org/nathan-v/resque-state.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/nathan-v/resque-state]
+{<img src="https://gemnasium.com/badges/github.com/nathan-v/resque-state.svg" />}[https://gemnasium.com/github.com/nathan-v/resque-state]
+{<img src="https://img.shields.io/github/issues/nathan-v/resque-state.svg" />}[https://github.com/nathan-v/resque-state/issues]
+
+
+resque-state is an extension to the resque queue system that provides simple trackable jobs.
+
+== About
+
+resque-state 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 state. It achieves this by giving job instances UUID's
+and allowing the job instances to report their state from within their iterations.
+
+== Installation
+
+Ruby 1.9.3 and up are supported.
+
+resque-state <b>requires Redis >= 1.1</b> (though I recommend getting the latest stable version).
+You can download Redis here: http://redis.io/ or install it
+using homebrew (brew install redis).
+
+Install the resque-state gem (which will pull in the dependencies).
+
+  gem install resque-state
+
+With newer Rails add this to your Gemfile:
+
+  # Gemfile
+  gem 'resque-state'
+
+Then in an initializer:
+
+  # config/initializers/resque.rb
+  Resque.redis = "your/redis/socket" # default localhost:6379
+  Resque::Plugins::State::Hash.expire_in = (24 * 60 * 60) # 24hrs in seconds
+
+== Usage
+
+The most direct way to use resque-state is to create your jobs using the
+Resque::Plugins::State module. An example job would look something like:
+
+  class SleepJob
+    include Resque::Plugins::State
+
+    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 state:
+
+  state = Resque::Plugins::State::Hash.get(job_id)
+
+This returns a Resque::Plugins::State::Hash object, which is a Hash (with benefits).
+
+  state.pct_complete #=> 0
+  state.status #=> 'queued'
+  state.queued? #=> true
+  state.working? #=> false
+  state.time #=> Time object
+  state.message #=> "Created at ..."
+
+Once the worker reserves the job, the instance of SleepJob updates the state at
+each iteration using <tt>at()</tt>
+
+  state = Resque::Plugins::State::Hash.get(job_id)
+  state.working? #=> true
+  state.num #=> 5
+  state.total #=> 100
+  state.pct_complete #=> 5
+
+If an error occurs within the job instance, the state 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::State::Hash.statuses #=> [#<Resque::Plugins::State::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::State::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.
+
+=== Hold up: Pausing
+
+Since we perhaps might want to just have a job sit and wait a bit rather than have it die
+completely there's pause. This tells the job to sleep for 10 seconds before checking in
+again.
+
+  Resque::Plugins::State::Hash.pause(job_id)
+
+The next time the job at job_id calls <tt>at</tt> or <tt>tick</tt>, it will start a while
+loop with a 10 second sleep until Resque::Plugins::State::Hash.unpause is called.
+
+=== 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 state 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::State::Hash.expire_in = (60 * 60) # 1 hour
+
+=== Testing
+
+Recent versions of Resque introduced <tt>Resque.inline</tt> 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, <tt>Resque::State</tt> uses Redis
+to store information about jobs, so though <tt>inline</tt> "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 <tt>inline</tt> 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. This adds a State tab to resque-web
+
+To use, you need to setup a resque-web config file:
+
+  # ~/resque_conf.rb
+  require 'resque/state_server'
+
+Then start resque-web with your config:
+
+  resque-web ~/resque_conf.rb
+
+If you're using Rails you can just require 'resque/state_server' in your resque
+initializer or application.rb.
+
+
+== More
+
+* Source: http://github.com/nathan-v/resque-state
+* API Docs: http://rdoc.info/projects/nathan-v/resque-state
+* Examples: http://github.com/nathan-v/resque-state/tree/master/examples
+* Resque: https://github.com/resque/resque
+
+== Thanks
+
+Resque is awesome, @defunkt needs a shout-out.
+
+== Note on Patches/Pull Requests
+
+PRs are welcome. Please always include relevant tests and ensure your changes follow
+Ruby style conventions as much as possible.
+
+== Copyright
+
+Copyright (c) 2016 Nathan V.
+
+Copyright (c) 2010 Aaron Quint.
+
+MIT licensed. See LICENSE file for details.

data/Rakefile

@@ -0,0 +1,48 @@
+$LOAD_PATH.unshift './lib'
+
+require 'rake'
+require 'resque-state'
+require 'resque/tasks'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = 'resque-state'
+    gem.version = Resque::Plugins::State::VERSION.dup
+    gem.summary = %(resque-state is an extension to the resque queue system
+      that provides simple trackable jobs.).gsub("\n", ' ').squeeze(' ')
+    gem.description = %(resque-state is an extension to the resque queue
+      system that provides simple trackable jobs. It provides a
+      Resque::Plugins::State::Hash class which can set/get the statuses of jobs
+      and a Resque::Plugins::State class that, when included, provides easily
+      trackable/killable/pausable jobs.).gsub("\n", ' ').squeeze(' ')
+    gem.email = 'nathan.v@gmail.com'
+    gem.homepage = 'http://github.com/nathan-v/resque-state'
+    gem.rubyforge_project = 'nathan-v'
+    gem.authors = ['Aaron Quint', 'Nathan V']
+    gem.licenses = 'MIT'
+    # 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'.gsub("\n", ' ').squeeze(' ')
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+desc 'Generates a coverage report'
+task :coverage do
+  ENV['COVERAGE'] = 'true'
+  Rake::Task['test'].execute
+end
+
+task :test
+
+task default: :coverage

data/examples/sleep_job.rb

@@ -0,0 +1,36 @@
+require 'resque/job_with_state' # in rails you would probably do this in an initializer
+
+# sleeps for _length_ seconds updating the status every second
+
+class SleepJob
+  include Resque::Plugins::State
+
+  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::State::Hash.get(job_id) and !status.completed? && !status.failed?
+    sleep 1
+    puts status.inspect
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require 'resque-state'

data/lib/resque/job_with_state.rb

@@ -0,0 +1,5 @@
+module Resque
+  class JobWithState
+    include Resque::Plugins::State
+  end
+end