jobba 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f4e9d94c44e106165f0d2ac0e0cfc45999e491e9
-  data.tar.gz: 6f6d8db0eb8b7cbc17a9825e55b9a35365b8c4a8
+  metadata.gz: cb1d6250e365236cfdbe87245b5ccd520809fe5a
+  data.tar.gz: 24e9272312ad529d7ec0e33c4d21e8f06c4836b5
 SHA512:
-  metadata.gz: 787771b8aaaf606437ee72425667dce7caa899ef95d965d2703710422bd50274c67a4f40992ae9306da4ead581878fe4380c6e5fb1cb2ae42cedf7d71782106b
-  data.tar.gz: 6bb44328f4be0c0230e0760071fa1dd28a15f611c20ffb7724402674e6237d8813ff20b6ddd46d147ac4826242aa9cf0fb40727ec93a323ae72b3d181ffdf53c
+  metadata.gz: 26f7a2a14a1de1761acec0c584bc3d3946ae23f955ba583e2a72dcd30ee3bd647cf2daa41f32b312729d8e451ed8ffbf5a3d7deaae191746f4b9f54bc106e0ab
+  data.tar.gz: ff3d42902f0094392848149d37379739c87b72a4cacd77f1e3e84343855defbd574b9dc8a1b9c3c2deefe08c0b150f776dc832228f8981edd6614a8aab52d366

data/README.md

@@ -127,7 +127,7 @@ The order of states is not enforced, and you do not have to use all states.  How
 
 Generally-speaking, you should only enter any state once.  Jobba only records the timestamp the first time you enter a state.
 
-The expection to this rule is that if call `started!` a second time, Jobba will note this as a restart.  The current values in the status will be archived and your status will look like a `started` status, with the exception that the `attempt` count will be incremented.  A restarted status can then enter `succeeded`, `failed`, or `killed` states and those timestamps will be stored.  `job_name` and `job_args` survive the restart.
+The exception to this rule is that if call `started!` a second time, Jobba will note this as a restart.  The current values in the status will be archived and your status will look like a `started` status, with the exception that the `attempt` count will be incremented.  A restarted status can then enter `succeeded`, `failed`, or `killed` states and those timestamps will be stored.  `job_name`, `job_args` and `provider_job_id` survive the restart.
 
 The `attempt` field is zero-indexed, so the first attempt is attempt `0`.
 
@@ -171,7 +171,7 @@ my_status.save("some string")
 
 Note that if you `save` or `add_error` contains a hash with symbol keys, those keys will be converted to strings.  In fact, any argument passed in to these methods will be converted to JSON and parsed back again so that the `data` and `errors` attributes returns the same thing regardless of if they are retrieved immediately after being set or after being loaded from Redis.
 
-## Setting Job Name and Arguments
+## Setting Job Name, Arguments and Provider Job ID
 
 If you want to be able to query for all statuses for a certain kind of job, you can set the job's name in the status:
 
@@ -191,6 +191,12 @@ You probably will only want to track complex arguments, e.g. models in your appl
 
 Note that you can set job args with names that are either symbols or strings, but you can only read the args back by the string form of their name, e.g.
 
+If you want to be able to query for the status for a specific job record or to find the job record associated with a status, you can set the job's provider_job_id in the status:
+
+```ruby
+my_status.set_provider_job_id(42)
+```
+
 ```ruby
 my_status.set_job_args(foo: "bar")
 my_status.job_args['foo']          # => "bar"
@@ -333,7 +339,7 @@ Jobba.where(job_name: ["MySpecialBackgroundJob", "MyOtherJob"])
 
 **Job Arguments**
 
-(requires having called the optional `add_job_arg` method)
+(requires having called the optional `set_job_args` method)
 
 ```ruby
 Jobba.where(job_arg: "gid://app/MyModel/42")

data/lib/jobba.rb

@@ -20,7 +20,7 @@ module Jobba
   class << self
     extend Forwardable
 
-    def_delegators Jobba::Status, :all, :where, :create, :create!, :find, :find!
+    def_delegators Jobba::Status, :all, :where, :find_by, :create, :create!, :find, :find!
   end
 
   def self.configure

data/lib/jobba/clause.rb

@@ -6,18 +6,18 @@ class Jobba::Clause
   # if `keys` or `suffixes` is an array, all entries will be included in the resulting set
   def initialize(prefix: nil, suffixes: nil, keys: nil, min: nil, max: nil)
     if keys.nil? && prefix.nil? && suffixes.nil?
-      raise ArgumentError, "Either `keys` or both `prefix` and `suffix` must be specified."
+      raise ArgumentError, "Either `keys` or both `prefix` and `suffix` must be specified.", caller
     end
 
     if (prefix.nil? && !suffixes.nil?) || (!prefix.nil? && suffixes.nil?)
-      raise ArgumentError, "When `prefix` is given, so must `suffix` be, and vice versa."
+      raise ArgumentError, "When `prefix` is given, so must `suffix` be, and vice versa.", caller
     end
 
     if keys
       @keys = [keys].flatten
     else
       prefix = "#{prefix}:" unless prefix[-1] == ":"
-      @keys = [suffixes].flatten.collect{|suffix| prefix + suffix}
+      @keys = [suffixes].flatten.collect{|suffix| "#{prefix}#{suffix}"}
     end
 
     @min = min

data/lib/jobba/clause_factory.rb

@@ -5,7 +5,7 @@ class Jobba::ClauseFactory
   def self.new_clause(key, value)
     if value.nil?
       raise ArgumentError, "Nil search criteria are not currently " \
-                           "accepted in a Jobba `where` call"
+                           "accepted in a Jobba `where` call", caller
     end
 
     case key.to_sym
@@ -15,12 +15,14 @@ class Jobba::ClauseFactory
       Jobba::Clause.new(prefix: "job_name", suffixes: value)
     when :job_arg
       Jobba::Clause.new(prefix: "job_arg", suffixes: value)
+    when :provider_job_id
+      Jobba::Clause.new(prefix: "provider_job_id", suffixes: value)
     when :id
       Jobba::IdClause.new(value)
     when /.*_at/
       timestamp_clause(key, value)
     else
-      raise ArgumentError, "#{key} is not a valid key in a Jobba `where` call"
+      raise ArgumentError, "#{key} is not a valid key in a Jobba `where` call", caller
     end
   end
 
@@ -31,7 +33,7 @@ class Jobba::ClauseFactory
       case options
       when Array
         if options.length != 2
-          raise ArgumentError, "Wrong number of array entries for '#{timestamp_name}'."
+          raise ArgumentError, "Wrong number of array entries for '#{timestamp_name}'.", caller
         end
 
         [options[0], options[1]]
@@ -40,7 +42,8 @@ class Jobba::ClauseFactory
       else
         raise ArgumentError,
               "#{option_value} is not a valid value for a " +
-              "#{option_key} key in a Jobba `where` call"
+              "#{option_key} key in a Jobba `where` call",
+              caller
       end
 
     min = Jobba::Utils.time_to_usec_int(min)
@@ -68,14 +71,14 @@ class Jobba::ClauseFactory
   def self.validate_state_name!(state_name)
     [state_name].flatten.each do |name|
       if Jobba::State::ALL.none?{|state| state.name == name.to_s}
-        raise ArgumentError, "'#{name}' is not a valid state name."
+        raise ArgumentError, "'#{name}' is not a valid state name.", caller
       end
     end
   end
 
   def self.validate_timestamp_name!(timestamp_name)
     if Jobba::State::ALL.none?{|state| state.timestamp_name == timestamp_name.to_s}
-      raise ArgumentError, "'#{timestamp_name}' is not a valid timestamp."
+      raise ArgumentError, "'#{timestamp_name}' is not a valid timestamp.", caller
     end
   end
 

data/lib/jobba/status.rb

@@ -14,6 +14,10 @@ module Jobba
       all.where(*args)
     end
 
+    def self.find_by(*args)
+      all.where(*args).first
+    end
+
     def self.create!
       create(state: State::UNQUEUED)
     end
@@ -36,8 +40,9 @@ module Jobba
     end
 
     def self.local_attrs
-      %w(id state progress errors data kill_requested_at job_name job_args attempt) +
-      State::ALL.collect(&:timestamp_name)
+      %w(id state progress errors data kill_requested_at
+        job_name job_args provider_job_id attempt prior_attempts) +
+        State::ALL.collect(&:timestamp_name)
     end
 
     def reload!
@@ -111,7 +116,8 @@ module Jobba
     end
 
     def set_job_name(job_name)
-      raise ArgumentError, "`job_name` must not be blank" if job_name.nil? || job_name.empty?
+      raise ArgumentError, "`job_name` must not be blank", caller \
+        if job_name.nil? || job_name.empty?
 
       redis.multi do
         redis.srem(job_name_key, id)
@@ -121,8 +127,9 @@ module Jobba
     end
 
     def set_job_args(args_hash={})
-      raise ArgumentError, "All values in the hash passed to `set_job_args` must be strings" \
-        if args_hash.values.any?{|val| !val.is_a?(String)}
+      raise ArgumentError,
+            "All values in the hash passed to `set_job_args` must be strings",
+            caller if args_hash.values.any?{|val| !val.is_a?(String)}
 
       args_hash = normalize_for_json(args_hash)
 
@@ -133,8 +140,19 @@ module Jobba
       end
     end
 
+    def set_provider_job_id(provider_job_id)
+      raise ArgumentError, "`provider_job_id` must not be blank", caller \
+        if provider_job_id.nil? || (provider_job_id.respond_to?(:empty?) && provider_job_id.empty?)
+
+      redis.multi do
+        redis.srem(provider_job_id_key, id)
+        set(provider_job_id: provider_job_id)
+        redis.sadd(provider_job_id_key, id)
+      end
+    end
+
     def add_error(error)
-      raise ArgumentError, "The argument to `add_error` cannot be nil" if error.nil?
+      raise ArgumentError, "The argument to `add_error` cannot be nil", caller if error.nil?
 
       errors.push(normalize_for_json(error))
       set(errors: errors)
@@ -162,7 +180,7 @@ module Jobba
     end
 
     def prior_attempts
-      [*0..attempt-1].collect{|ii| self.class.find!("#{id}:#{ii}")}
+      @prior_attempts ||= [*0..attempt-1].collect{|ii| self.class.find!("#{id}:#{ii}")}
     end
 
     protected
@@ -188,7 +206,8 @@ module Jobba
         progress: 0,
         errors: [],
         job_name: job_name,
-        job_args: job_args
+        job_args: job_args,
+        provider_job_id: provider_job_id
       }
 
       archive_attempt!
@@ -223,6 +242,7 @@ module Jobba
         @attempt  = attrs[:attempt]  || 0
         @job_args = attrs[:job_args] || {}
         @job_name = attrs[:job_name]
+        @provider_job_id = attrs[:provider_job_id]
 
         if attrs[:persist]
           redis.multi do
@@ -316,9 +336,12 @@ module Jobba
         redis.srem(job_name_key, id)
 
         delete_self_from_job_args_set!
+
+        redis.srem(provider_job_id_key, id)
       end
 
       prior_attempts.each(&:delete!)
+      @prior_attempts = nil
     end
 
     def delete_locally!
@@ -351,7 +374,7 @@ module Jobba
     end
 
     def self.job_key(id, attempt=nil)
-      raise(ArgumentError, "`id` cannot be nil") if id.nil?
+      raise ArgumentError, "`id` cannot be nil", caller if id.nil?
       attempt.nil? ? "id:#{id}" : "id:#{id}:#{attempt}"
     end
 
@@ -359,20 +382,26 @@ module Jobba
       "job_arg:#{arg}"
     end
 
+    def provider_job_id_key
+      "provider_job_id:#{provider_job_id}"
+    end
+
     def job_errors_key(id)
-      raise(ArgumentError, "`id` cannot be nil") if id.nil?
+      raise ArgumentError, "`id` cannot be nil", caller if id.nil?
       "#{id}:errors"
     end
 
     def compute_fractional_progress(at, out_of)
       if at.nil?
-        raise ArgumentError, "Must specify at least `at` argument to `progress` call"
+        raise ArgumentError, "Must specify at least `at` argument to `progress` call", caller
       elsif at < 0
-        raise ArgumentError, "progress cannot be negative (at=#{at})"
+        raise ArgumentError, "progress cannot be negative (at=#{at})", caller
       elsif out_of && out_of < at
-        raise ArgumentError, "`out_of` must be greater than `at` in `progress` calls"
+        raise ArgumentError, "`out_of` must be greater than `at` in `progress` calls", caller
       elsif out_of.nil? && (at < 0 || at > 1)
-        raise ArgumentError, "If `out_of` not specified, `at` must be in the range [0.0, 1.0]"
+        raise ArgumentError,
+              "If `out_of` not specified, `at` must be in the range [0.0, 1.0]",
+              caller
       end
 
       at.to_f / (out_of || 1).to_f

data/lib/jobba/statuses.rb

@@ -11,7 +11,8 @@ class Jobba::Statuses
 
   def_delegators :@ids, :empty?
 
-  def_delegators :load, :any?, :none?, :all?, :count, :map, :collect
+  def_delegators :load, :any?, :none?, :all?, :count, :length, :size,
+                 :map, :collect, :reduce, :inject, :first, :last
 
   def select!(&block)
     modify!(:select!, &block)
@@ -25,14 +26,18 @@ class Jobba::Statuses
     if any?(&:incomplete?)
       raise(Jobba::NotCompletedError,
             "This status cannot be deleted because it isn't complete.  Use " \
-            "`delete!` if you want to delete anyway.")
+            "`delete_all!` if you want to delete anyway.")
     end
 
-    delete!
+    delete_all!
   end
 
   def delete_all!
     load
+
+    # preload prior attempts because loading them is not `multi`-friendly
+    @cache.each(&:prior_attempts)
+
     redis.multi do
       @cache.each(&:delete!)
     end

data/lib/jobba/version.rb

@@ -1,3 +1,3 @@
 module Jobba
-  VERSION = "1.4.0"
+  VERSION = "1.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jobba
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - JP Slavinsky
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-01-20 00:00:00.000000000 Z
+date: 2017-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -161,7 +161,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
 summary: Redis-based background job status tracking.