resque-state 1.0.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: def5514d96c48b47f9f04cb7c6531c475fdacc71
-  data.tar.gz: 55d4f6107656c9bf627c9a863cf767df92db2cad
+  metadata.gz: 780ed4ffab1f5d88c532ed4e505cf9bf80efa584
+  data.tar.gz: 55857ef7b3c22c689e496dd7e2758bd74cd048a6
 SHA512:
-  metadata.gz: 98191a7d19376ed31345aebee07d699743a24ab64c32e0ed872eae7a97fc02dd0e51cf5a952362d908871232960ec6c1f4e73c0803df25a74070002b273ba4ba
-  data.tar.gz: 69795a7d0a60b5a9ac19e8894c36b2d384848ad1f424e6b3a1a42fc1a90a503c37e6254a99c783dc6b28fd83877aa589b20ff6d39a5ea44b1fc794b497a39ca6
+  metadata.gz: '0309cc6512943aed87f89aa0f49a209753609c49a1f27f569edb105c012088adf460e0ecb8709a6f73cf0a67c0fa706b39600a4b38181c814314c53c934208c8'
+  data.tar.gz: 49fcf5105f608210123c50e6beada0d0ed0f32e012c51758da30a484f98f45c6fa72c35bea16d1adf1f9a2049d92b3f9f0f4d717fa941cac5806f11646c95e51

data/.travis.yml

@@ -1,6 +1,6 @@
 language: ruby
 rvm:
- - 2.2
+ - 2.2.2
  - 2.3.4
  - 2.4.1
  - ruby-head

data/Gemfile.lock

@@ -1,8 +1,7 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.5.1)
-      public_suffix (~> 2.0, >= 2.0.2)
+    addressable (2.4.0)
     builder (3.2.3)
     codeclimate-test-reporter (1.0.7)
       simplecov
@@ -14,22 +13,21 @@ GEM
     faraday (0.9.2)
       multipart-post (>= 1.2, < 3)
     git (1.3.0)
-    github_api (0.11.3)
-      addressable (~> 2.3)
-      descendants_tracker (~> 0.0.1)
+    github_api (0.16.0)
+      addressable (~> 2.4.0)
+      descendants_tracker (~> 0.0.4)
       faraday (~> 0.8, < 0.10)
-      hashie (>= 1.2)
-      multi_json (>= 1.7.5, < 2.0)
-      nokogiri (~> 1.6.0)
-      oauth2
+      hashie (>= 3.4)
+      mime-types (>= 1.16, < 3.0)
+      oauth2 (~> 1.0)
     hashie (3.5.5)
     highline (1.7.8)
     jar-dependencies (0.3.11)
-    jeweler (2.3.3)
+    jeweler (2.3.6)
       builder
-      bundler (>= 1.0)
+      bundler (>= 1)
       git (>= 1.2.5)
-      github_api (~> 0.11.0)
+      github_api (~> 0.16.0)
       highline (>= 1.6.15)
       nokogiri (>= 1.5.10)
       psych (~> 2.2)
@@ -40,19 +38,21 @@ GEM
     json (2.1.0-java)
     jwt (1.5.6)
     metaclass (0.0.4)
-    mini_portile2 (2.1.0)
-    minitest (5.10.1)
+    mime-types (2.99.3)
+    mini_portile2 (2.2.0)
+    minitest (5.10.2)
     mocha (1.2.1)
       metaclass (~> 0.0.1)
     mono_logger (1.1.0)
     multi_json (1.12.1)
     multi_xml (0.6.0)
     multipart-post (2.0.0)
-    nokogiri (1.6.8.1)
-      mini_portile2 (~> 2.1.0)
-    nokogiri (1.6.8.1-java)
-    oauth2 (1.3.1)
-      faraday (>= 0.8, < 0.12)
+    mustermann (1.0.0)
+    nokogiri (1.8.0)
+      mini_portile2 (~> 2.2.0)
+    nokogiri (1.8.0-java)
+    oauth2 (1.4.0)
+      faraday (>= 0.8, < 0.13)
       jwt (~> 1.0)
       multi_json (~> 1.3)
       multi_xml (~> 0.5)
@@ -60,9 +60,8 @@ GEM
     psych (2.2.4)
     psych (2.2.4-java)
       jar-dependencies (>= 0.1.7)
-    public_suffix (2.0.5)
-    rack (1.6.5)
-    rack-protection (1.5.3)
+    rack (2.0.3)
+    rack-protection (2.0.0)
       rack
     rake (12.0.0)
     rdoc (5.1.0)
@@ -80,11 +79,12 @@ GEM
       docile (~> 1.1.0)
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.0)
-    sinatra (1.4.8)
-      rack (~> 1.5)
-      rack-protection (~> 1.4)
-      tilt (>= 1.3, < 3)
+    simplecov-html (0.10.1)
+    sinatra (2.0.0)
+      mustermann (~> 1.0)
+      rack (~> 2.0)
+      rack-protection (= 2.0.0)
+      tilt (~> 2.0)
     thread_safe (0.3.6)
     thread_safe (0.3.6-java)
     tilt (2.0.7)
@@ -105,4 +105,4 @@ DEPENDENCIES
   simplecov (~> 0.14)
 
 BUNDLED WITH
-   1.14.3
+   1.14.6

data/README.rdoc

@@ -22,7 +22,7 @@ and allowing the job instances to report their state from within their iteration
 
 == Installation
 
-Ruby 2.0+ and JRuby 9.0+ are supported.
+Ruby 2.2.2+ and JRuby 9.1+ 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
@@ -139,6 +139,25 @@ again.
 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.
 
+As of 1.1 pause! can be called from the job itself with an optional string argument
+that allows you to set a specific status along with the paused state if you'd like.
+
+=== Back it up
+
+Perhaps you want a job to be able to undo what it did. Well; that's what revert is 
+all about. Jobs that support on_revert can be told to revert and will run insructions
+in that method to undo whatever they might need to. While you could do similar things
+with on_failure on_revert was added to provide a separate status for reverting and
+reverted cases so you can see later which jobs failed (probably due to an error) or
+which ones might have been intentionally reverted by a user or automation.
+
+  Resque::Plugins::State::Hash.revert(job_id)
+
+This is all you need to tell that job to go back and undo it's work. For jobs that
+do not support on_revert those jobs will pause themeslves and leave a note to the user
+that the job doesn't allow that functionality. This lets the user decide if the job
+should be killed or let continue.
+
 === 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

data/lib/resque/plugins/state.rb

@@ -30,7 +30,7 @@ module Resque
     # end we update the status telling anyone listening to this job that its
     # complete.
     module State
-      VERSION = '1.0.4'.freeze
+      VERSION = '1.1.0'.freeze
 
       STATUS_QUEUED = 'queued'.freeze
       STATUS_WORKING = 'working'.freeze
@@ -39,6 +39,8 @@ module Resque
       STATUS_KILLED = 'killed'.freeze
       STATUS_PAUSED = 'paused'.freeze
       STATUS_WAITING = 'waiting'.freeze
+      STATUS_REVERTING = 'reverting'.freeze
+      STATUS_REVERTED = 'reverted'.freeze
       STATUSES = [
         STATUS_QUEUED,
         STATUS_WORKING,
@@ -46,13 +48,16 @@ module Resque
         STATUS_FAILED,
         STATUS_KILLED,
         STATUS_PAUSED,
-        STATUS_WAITING
+        STATUS_WAITING,
+        STATUS_REVERTING,
+        STATUS_REVERTED
       ].freeze
 
       autoload :Hash, 'resque/plugins/state/hash'
 
       # The error class raised when a job is killed
       class Killed < RuntimeError; end
+      class Revert < RuntimeError; end
       class NotANumber < RuntimeError; end
 
       attr_reader :uuid, :options
@@ -157,9 +162,10 @@ module Resque
 
       # Create a new instance with <tt>uuid</tt> and <tt>options</tt>
       def initialize(uuid, options = {})
-        @uuid    = uuid
-        @options = options
-        @logger = Resque.logger
+        @reverting = false
+        @uuid      = uuid
+        @options   = options
+        @logger    = Resque.logger
       end
 
       # Run by the Resque::Worker when processing this job. It wraps the
@@ -181,7 +187,21 @@ module Resque
       rescue Killed
         Resque::Plugins::State::Hash.killed(uuid)
         on_killed if respond_to?(:on_killed)
+      rescue Revert
+        Resque::Plugins::State::Hash.revert(uuid)
+        if respond_to?(:on_revert)
+          on_revert
+          messages = ["Reverted at #{Time.now}"]
+          job_status('status' => STATUS_REVERTED,
+                     'message' => messages[0])
+        else
+          @logger.error("Job #{@uuid}: Attempted revert on job with no revert"\
+                        " support")
+          pause!('This job does not support revert functionality')
+        end
       rescue => e
+        messages = ["Failed at #{Time.now}: #{e.message}"]
+        @logger.error("Job #{@uuid}: #{messages.join(' ')}")
         failed("The task failed because of an error: #{e}")
         raise e unless respond_to?(:on_failure)
         on_failure(e)
@@ -214,6 +234,12 @@ module Resque
         Resque::Plugins::State::Hash.should_pause?(uuid)
       end
 
+      # Checks against the revert list if this specific job instance should be
+      # paused on the next iteration
+      def should_revert?
+        Resque::Plugins::State::Hash.should_revert?(uuid)
+      end
+
       # Checks against the lock list if this specific job instance should wait
       # before starting
       def locked?(key)
@@ -244,6 +270,10 @@ module Resque
         kill! if should_kill?
         if should_pause?
           pause!
+        elsif should_revert?
+          return revert! unless @reverting
+          job_status({ 'status' => STATUS_REVERTING }, *messages)
+          @logger.info("Job #{@uuid}: #{messages.join(' ')}")
         else
           job_status({ 'status' => STATUS_WORKING }, *messages)
           @logger.info("Job #{@uuid}: #{messages.join(' ')}")
@@ -256,6 +286,12 @@ module Resque
         @logger.error("Job #{@uuid}: #{messages.join(' ')}")
       end
 
+      # set the status to 'reverted' passing along any additional messages
+      def reverted(*messages)
+        job_status({ 'status' => STATUS_REVERTED }, *messages)
+        @logger.error("Job #{@uuid}: #{messages.join(' ')}")
+      end
+
       # set the status to 'completed' passing along any addional messages
       def completed(*messages)
         job_status({
@@ -275,17 +311,30 @@ module Resque
         raise Killed
       end
 
+      # revert the current job, setting the status to 'reverting' and raising
+      # <tt>Revert</tt>
+      def revert!
+        messages = ["Reverting at #{Time.now}"]
+        Resque::Plugins::State::Hash.unpause(uuid) if should_pause?
+        @reverting = true
+        job_status('status' => STATUS_REVERTING,
+                   'message' => messages[0])
+        @logger.info("Job #{@uuid}: #{messages.join(' ')}")
+        raise Revert
+      end
+
       # pause the current job, setting the status to 'paused' and sleeping 10
       # seconds
-      def pause!
+      def pause!(pause_text = nil)
         Resque::Plugins::State::Hash.pause(uuid)
-        messages = ["Paused at #{Time.now}"]
+        messages = ["Paused at #{Time.now} #{pause_text}"]
         job_status('status' => STATUS_PAUSED,
                    'message' => messages[0])
         raise Killed if @testing # Don't loop or complete during testing
         @logger.info("Job #{@uuid}: #{messages.join(' ')}")
         while should_pause?
           kill! if should_kill?
+          revert! if should_revert?
           sleep 10
         end
       end

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

@@ -187,6 +187,24 @@ module Resque
           redis.sismember(pause_key, uuid)
         end
 
+        # revert the job at UUID on its next iteration this works by adding the UUID to a
+        # revert list (a.k.a. a list of jobs to be reverted. Each iteration the job checks
+        # if it _should_ be reverted by calling <tt>tick</tt> or <tt>at</tt>. If so, it sleeps
+        # for 10 seconds before checking again if it should continue sleeping
+        def self.revert(uuid)
+          redis.sadd(revert_key, uuid)
+        end
+
+        # Return the UUIDs of the jobs on the revert list
+        def self.revert_ids
+          redis.smembers(revert_key)
+        end
+
+        # Check whether a job with UUID is on the revert list
+        def self.should_revert?(uuid)
+          redis.sismember(revert_key, uuid)
+        end
+
         # Set a lock key to allow jobs to run as singletons. Optional timeout in
         # seconds
         def self.lock(key, timeout = 3600)
@@ -231,6 +249,10 @@ module Resque
           '_pause'
         end
 
+        def self.revert_key
+          '_revert'
+        end
+
         def self.generate_uuid
           SecureRandom.hex.to_s
         end
@@ -320,16 +342,22 @@ module Resque
           end
         end
 
-        # Can the job be killed? failed, completed, and killed jobs can't be
-        # killed, for obvious reasons
+        # Can the job be killed? failed, completed, reverted, and killed jobs
+        # can't be killed, for obvious reasons
         def killable?
-          !failed? && !completed? && !killed?
+          !failed? && !completed? && !killed? && !reverted?
+        end
+
+        # Can the job be paused? failed, completed, paused, reverted, and killed
+        # jobs can't be paused, for obvious reasons
+        def pausable?
+          !failed? && !completed? && !killed? && !paused? && !reverted?
         end
 
-        # Can the job be paused? failed, completed, paused, and killed jobs
+        # Can the job be reverted? failed, completed, reverted, and killed jobs
         # can't be paused, for obvious reasons
         def pausable?
-          !failed? && !completed? && !killed? && !paused?
+          !failed? && !completed? && !killed? && !reverted?
         end
 
         unless method_defined?(:to_json)

data/resque-state.gemspec

@@ -2,18 +2,18 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: resque-state 1.0.4 ruby lib
+# stub: resque-state 1.1.0 ruby lib
 
 Gem::Specification.new do |s|
-  s.name = "resque-state".freeze
-  s.version = "1.0.4"
+  s.name = "resque-state"
+  s.version = "1.1.0"
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
-  s.require_paths = ["lib".freeze]
-  s.authors = ["Aaron Quint".freeze, "Nathan V".freeze]
-  s.date = "2017-05-04"
-  s.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.".freeze
-  s.email = "nathan.v@gmail.com".freeze
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.require_paths = ["lib"]
+  s.authors = ["Aaron Quint", "Nathan V"]
+  s.date = "2017-06-17"
+  s.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."
+  s.email = "nathan.v@gmail.com"
   s.extra_rdoc_files = [
     "LICENSE",
     "README.rdoc"
@@ -41,25 +41,25 @@ Gem::Specification.new do |s|
     "test/test_resque_plugins_state.rb",
     "test/test_resque_plugins_state_hash.rb"
   ]
-  s.homepage = "http://github.com/nathan-v/resque-state".freeze
-  s.licenses = ["MIT".freeze]
-  s.rubyforge_project = "nathan-v".freeze
-  s.rubygems_version = "2.6.11".freeze
-  s.summary = "resque-state is an extension to the resque queue system that provides simple trackable jobs.".freeze
+  s.homepage = "http://github.com/nathan-v/resque-state"
+  s.licenses = ["MIT"]
+  s.rubyforge_project = "nathan-v"
+  s.rubygems_version = "2.4.5"
+  s.summary = "resque-state is an extension to the resque queue system that provides simple trackable jobs."
 
   if s.respond_to? :specification_version then
     s.specification_version = 4
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<resque>.freeze, ["~> 1.27"])
-      s.add_development_dependency(%q<jeweler>.freeze, ["~> 2.3"])
+      s.add_runtime_dependency(%q<resque>, ["~> 1.27"])
+      s.add_development_dependency(%q<jeweler>, ["~> 2.3"])
     else
-      s.add_dependency(%q<resque>.freeze, ["~> 1.27"])
-      s.add_dependency(%q<jeweler>.freeze, ["~> 2.3"])
+      s.add_dependency(%q<resque>, ["~> 1.27"])
+      s.add_dependency(%q<jeweler>, ["~> 2.3"])
     end
   else
-    s.add_dependency(%q<resque>.freeze, ["~> 1.27"])
-    s.add_dependency(%q<jeweler>.freeze, ["~> 2.3"])
+    s.add_dependency(%q<resque>, ["~> 1.27"])
+    s.add_dependency(%q<jeweler>, ["~> 2.3"])
   end
 end
 

data/test/test_helper.rb

@@ -72,6 +72,20 @@ class SleeperJob
   end
 end
 
+class RevertJob
+  include Resque::Plugins::State
+
+  def perform
+    Resque.redis.set("#{uuid}:iterations", 0)
+    100.times do |num|
+      Resque.redis.incr("#{uuid}:iterations")
+      at(num, 100, "At #{num} of 100")
+    end
+  end
+
+  def on_revert; end
+end
+
 class BasicJob
   include Resque::Plugins::State
 end

data/test/test_resque_plugins_state.rb

@@ -290,6 +290,29 @@ class TestResquePluginsStatus < Minitest::Test
       end
     end
 
+    describe 'reverting a job' do
+      before do
+        @uuid      = RevertJob.create(num: 100)
+        @payload   = Resque.pop(:statused)
+        Resque::Plugins::State::Hash.revert(@uuid)
+        @performed = RevertJob.perform(*@payload['args'])
+        @status = Resque::Plugins::State::Hash.get(@uuid)
+      end
+
+      after do
+        Resque::Plugins::State::Hash.kill(@uuid)
+      end
+
+      it 'set the status to reverted' do
+        assert @status.reverted?
+        assert !@status.completed?
+      end
+
+      it 'persist the revert key' do
+        assert_includes Resque::Plugins::State::Hash.revert_ids, @uuid
+      end
+    end
+
     describe 'pausing a job' do
       before do
         @uuid      = SleeperJob.create(num: 100)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: resque-state
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.1.0
 platform: ruby
 authors:
 - Aaron Quint
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-05-04 00:00:00.000000000 Z
+date: 2017-06-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: resque
@@ -91,7 +91,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: nathan-v
-rubygems_version: 2.6.11
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: resque-state is an extension to the resque queue system that provides simple