sidekiq-unique-jobs 6.0.0.rc6 → 6.0.0.rc7

data/lib/sidekiq_unique_jobs/on_conflict/strategy.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SidekiqUniqueJobs
+  module OnConflict
+    # Abstract conflict strategy class
+    #
+    # @abstract
+    # @author Mikael Henriksson <mikael@zoolutions.se>
+    class Strategy
+      include SidekiqUniqueJobs::Logging
+
+      # The sidekiq job hash
+      # @return [Hash] the Sidekiq job hash
+      attr_reader :item
+
+      # @param [Hash] item the Sidekiq job hash
+      def initialize(item)
+        @item = item
+      end
+
+      # Use strategy on conflict
+      # @raise [NotImplementedError] needs to be implemented in child class
+      def call
+        fail NotImplementedError, 'needs to be implemented in child class'
+      end
+    end
+  end
+end

data/lib/sidekiq_unique_jobs/options_with_fallback.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 module SidekiqUniqueJobs
-  # Shared logic for dealing with options
-  # This class requires 3 things to be defined in the class including it
+  # Module containing methods shared between client and server middleware
+  #
+  # Requires the following methods to be defined in the including class
   #   1. item (required)
   #   2. options (can be nil)
   #   3. worker_class (required, can be anything)
+  # @author Mikael Henriksson <mikael@zoolutions.se>
   module OptionsWithFallback
     LOCKS = {
       until_and_while_executing: SidekiqUniqueJobs::Lock::UntilAndWhileExecuting,
@@ -21,32 +23,45 @@ module SidekiqUniqueJobs
       base.send(:include, SidekiqUniqueJobs::SidekiqWorkerMethods)
     end
 
+    # Check if unique has been enabled
+    # @return [true, false] indicate if the gem has been enabled
     def unique_enabled?
       SidekiqUniqueJobs.config.enabled && lock_type
     end
 
+    # Check if unique has been disabled
     def unique_disabled?
       !unique_enabled?
     end
 
+    # Check if we should log duplicate payloads
     def log_duplicate_payload?
       options[LOG_DUPLICATE_KEY] || item[LOG_DUPLICATE_KEY]
     end
 
+    # Check if we should log duplicate payloads
+    # @return [SidekiqUniqueJobs::Lock::BaseLock] an instance of a child class
     def lock
       @lock ||= lock_class.new(item, after_unlock_hook, @redis_pool)
     end
 
+    # Check if we should log duplicate payloads
+    # @return [SidekiqUniqueJobs::Lock::BaseLock] an instance of a child class
     def lock_class
       @lock_class ||= begin
         LOCKS.fetch(lock_type.to_sym) do
-          fail UnknownLock, "No implementation for `unique: :#{lock_type}`"
+          fail UnknownLock, "No implementation for `lock: :#{lock_type}`"
         end
       end
     end
 
+    # @return [Symbol]
     def lock_type
-      @lock_type ||= options[UNIQUE_KEY] || item[UNIQUE_KEY]
+      @lock_type ||= options[LOCK_KEY] || item[LOCK_KEY] || unique_type
+    end
+
+    def unique_type
+      options[UNIQUE_KEY] || item[UNIQUE_KEY]
     end
 
     def options

data/lib/sidekiq_unique_jobs/scripts.rb

@@ -5,6 +5,9 @@ require 'digest/sha1'
 require 'concurrent/map'
 
 module SidekiqUniqueJobs
+  # Interface to dealing with .lua files
+  #
+  # @author Mikael Henriksson <mikael@zoolutions.se>
   module Scripts
     LUA_PATHNAME ||= Pathname.new(__FILE__).dirname.join('../../redis').freeze
     SCRIPT_SHAS ||= Concurrent::Map.new
@@ -13,6 +16,14 @@ module SidekiqUniqueJobs
 
     module_function
 
+    # Call a lua script with the provided file_name
+    # @param [Symbol] file_name the name of the lua script
+    # @param [Sidekiq::RedisConnection, ConnectionPool] redis_pool the redis connection
+    # @param [Hash] options arguments to pass to the script file
+    # @option options [Array] :keys the array of keys to pass to the script
+    # @option options [Array] :argv the array of arguments to pass to the script
+    # @note this method is recursive if we need to load a lua script
+    #   that wasn't previously loaded.
     def call(file_name, redis_pool, options = {})
       execute_script(file_name, redis_pool, options)
     rescue Redis::CommandError => ex
@@ -21,6 +32,12 @@ module SidekiqUniqueJobs
       end
     end
 
+    # Execute the script file
+    # @param [Symbol] file_name the name of the lua script
+    # @param [Sidekiq::RedisConnection, ConnectionPool] redis_pool the redis connection
+    # @param [Hash] options arguments to pass to the script file
+    # @option options [Array] :keys the array of keys to pass to the script
+    # @option options [Array] :argv the array of arguments to pass to the script
     def execute_script(file_name, redis_pool, options = {})
       redis(redis_pool) do |conn|
         sha = script_sha(conn, file_name)
@@ -28,6 +45,10 @@ module SidekiqUniqueJobs
       end
     end
 
+    # Return sha of already loaded lua script or load it and return the sha
+    # @param [Sidekiq::RedisConnection] conn the redis connection
+    # @param [Symbol] file_name the name of the lua script
+    # @return [String] sha of the script file
     def script_sha(conn, file_name)
       if (sha = SCRIPT_SHAS.get(file_name))
         return sha
@@ -38,6 +59,10 @@ module SidekiqUniqueJobs
       sha
     end
 
+    # Return sha of already loaded lua script or load it and return the sha
+    # @param [Redis::CommandError] ex exception to handle
+    # @param [Symbol] file_name the name of the lua script
+    # @raise [ScriptError] when the error isn't handled
     def handle_error(ex, file_name)
       if ex.message == 'NOSCRIPT No matching script. Please use EVAL.'
         SCRIPT_SHAS.delete(file_name)
@@ -47,10 +72,16 @@ module SidekiqUniqueJobs
       raise ScriptError, file_name: file_name, source_exception: ex
     end
 
+    # Reads the lua file from disk
+    # @param [Symbol] file_name the name of the lua script
+    # @return [String] the content of the lua file
     def script_source(file_name)
       script_path(file_name).read
     end
 
+    # Construct a Pathname to a lua script
+    # @param [Symbol] file_name the name of the lua script
+    # @return [Pathname] the full path to the gems lua script
     def script_path(file_name)
       LUA_PATHNAME.join("#{file_name}.lua")
     end

data/lib/sidekiq_unique_jobs/server/middleware.rb

@@ -2,9 +2,19 @@
 
 module SidekiqUniqueJobs
   module Server
+    # The unique sidekiq middleware for the server processor
+    #
+    # @author Mikael Henriksson <mikael@zoolutions.se>
     class Middleware
       include OptionsWithFallback
 
+      # Runs the server middleware
+      #   Used from Sidekiq::Processor#process
+      # @param [Sidekiq::Worker] worker_class
+      # @param [Hash] item a sidekiq job hash
+      # @param [String] queue name of the queue
+      # @yield when uniqueness is disabled
+      # @yield when the lock class executes successfully
       def call(worker_class, item, queue)
         @worker_class = worker_class
         @item         = item

data/lib/sidekiq_unique_jobs/sidekiq_worker_methods.rb

@@ -1,24 +1,38 @@
 # frozen_string_literal: true
 
 module SidekiqUniqueJobs
+  # Module with convenience methods for the Sidekiq::Worker class
+  #
+  # @author Mikael Henriksson <mikael@zoolutions.se>
   module SidekiqWorkerMethods
+    # Avoids duplicating worker_class.respond_to? in multiple places
+    # @return [true, false]
     def worker_method_defined?(method_sym)
       worker_class.respond_to?(method_sym)
     end
 
+    # Wraps #get_sidekiq_options to always work with a hash
+    # @return [Hash] of the worker class sidekiq options
     def worker_options
       return {} unless sidekiq_worker_class?
       worker_class.get_sidekiq_options.stringify_keys
     end
 
+    # Tests that the
+    # @return [true] if worker_class responds to get_sidekiq_options
+    # @return [false] if worker_class does not respond to get_sidekiq_options
     def sidekiq_worker_class?
       worker_method_defined?(:get_sidekiq_options)
     end
 
+    # The Sidekiq::Worker implementation
+    # @return [Sidekiq::Worker]
     def worker_class
       @_worker_class ||= worker_class_constantize # rubocop:disable Naming/MemoizedInstanceVariableName
     end
 
+    # The hook to call after a successful unlock
+    # @return [Proc]
     def after_unlock_hook
       -> { worker_class.after_unlock if worker_method_defined?(:after_unlock) }
     end
@@ -26,7 +40,7 @@ module SidekiqUniqueJobs
     # Attempt to constantize a string worker_class argument, always
     # failing back to the original argument when the constant can't be found
     #
-    # raises an error for other errors
+    # @return [Sidekiq::Worker]
     def worker_class_constantize(klazz = @worker_class)
       return klazz unless klazz.is_a?(String)
       Object.const_get(klazz)

data/lib/sidekiq_unique_jobs/timeout/calculator.rb

@@ -2,28 +2,39 @@
 
 module SidekiqUniqueJobs
   module Timeout
+    # Calculates timeout and expiration
+    #
+    # @author Mikael Henriksson <mikael@zoolutions.se>
     class Calculator
       include SidekiqUniqueJobs::SidekiqWorkerMethods
+
+      # @attr [Hash] item the Sidekiq job hash
       attr_reader :item
 
+      # @param [Hash] item the Sidekiq job hash
+      # @option item [Integer, nil] :lock_expiration the configured lock expiration
+      # @option item [Integer, nil] :lock_timeout the configured lock timeout
+      # @option item [String] :class the class of the sidekiq worker
+      # @option item [Float] :at the unix time the job is scheduled at
       def initialize(item)
         @item         = item
         @worker_class = item[CLASS_KEY]
       end
 
+      # The time until a job is scheduled
+      # @return [Integer] the number of seconds until job is scheduled
       def time_until_scheduled
         return 0 unless scheduled_at
         scheduled_at.to_i - Time.now.utc.to_i
       end
 
+      # The time a job is scheduled
+      # @return [Float] the exact unix time the job is scheduled at
       def scheduled_at
         @scheduled_at ||= item[AT_KEY]
       end
 
-      def seconds
-        raise NotImplementedError, "##{__method__} needs to be implemented in #{self.class}"
-      end
-
+      # The configured lock_expiration
       def lock_expiration
         @lock_expiration ||= begin
           expiration = item[LOCK_EXPIRATION_KEY]
@@ -32,6 +43,7 @@ module SidekiqUniqueJobs
         end
       end
 
+      # The configured lock_timeout
       def lock_timeout
         @lock_timeout = begin
           timeout = default_worker_options[LOCK_TIMEOUT_KEY]
@@ -41,6 +53,7 @@ module SidekiqUniqueJobs
         end
       end
 
+      # The default lock_timeout of this gem
       def default_lock_timeout
         SidekiqUniqueJobs.config.default_lock_timeout
       end

data/lib/sidekiq_unique_jobs/unique_args.rb

@@ -4,17 +4,25 @@ require 'digest'
 require 'sidekiq_unique_jobs/normalizer'
 
 module SidekiqUniqueJobs
-  # This class exists to be testable and the entire api should be considered private
+  # Handles uniqueness of sidekiq arguments
+  #
+  # @author Mikael Henriksson <mikael@zoolutions.se>
   class UniqueArgs
     include SidekiqUniqueJobs::Logging
     include SidekiqUniqueJobs::SidekiqWorkerMethods
 
+    # Convenience method for returning a digest
+    # @param [Hash] item a Sidekiq job hash
+    # @return [String] a unique digest
     def self.digest(item)
       new(item).unique_digest
     end
 
+    # The sidekiq job hash
+    # @return [Hash] the Sidekiq job hash
     attr_reader :item
 
+    # @param [Hash] item a Sidekiq job hash
     def initialize(item)
       @item         = item
       @worker_class = item[CLASS_KEY]
@@ -22,52 +30,73 @@ module SidekiqUniqueJobs
       add_uniqueness_to_item
     end
 
+    # Appends the keys unique_prefix, unique_args and {#unique_digest} to the sidekiq job hash {#item}
+    # @return [void]
     def add_uniqueness_to_item
       item[UNIQUE_PREFIX_KEY] ||= unique_prefix
       item[UNIQUE_ARGS_KEY]     = unique_args(item[ARGS_KEY])
       item[UNIQUE_DIGEST_KEY]   = unique_digest
     end
 
+    # Memoized unique_digest
+    # @return [String] a unique digest
     def unique_digest
       @unique_digest ||= create_digest
     end
 
+    # Creates a namespaced unique digest based on the {#digestable_hash} and the {#unique_prefix}
+    # @return [String] a unique digest
     def create_digest
       digest = Digest::MD5.hexdigest(Sidekiq.dump_json(digestable_hash))
       "#{unique_prefix}:#{digest}"
     end
 
+    # A prefix to use as namespace for the {#unique_digest}
+    # @return [String] a unique digest
     def unique_prefix
       worker_options[UNIQUE_PREFIX_KEY] || SidekiqUniqueJobs.config.unique_prefix
     end
 
+    # Filter a hash to use for digest
+    # @return [Hash] to use for digest
     def digestable_hash
       @item.slice(CLASS_KEY, QUEUE_KEY, UNIQUE_ARGS_KEY).tap do |hash|
-        hash.delete(QUEUE_KEY) if unique_on_all_queues?
+        hash.delete(QUEUE_KEY) if unique_across_queues?
         hash.delete(CLASS_KEY) if unique_across_workers?
       end
     end
 
+    # The unique arguments to use for creating a lock
+    # @return [Array] the arguments filters by the {#filtered_args} method if {#unique_args_enabled?}
     def unique_args(args)
       return filtered_args(args) if unique_args_enabled?
       args
     end
 
-    def unique_on_all_queues?
+    # Checks if we should disregard the queue when creating the unique digest
+    # @return [true, false]
+    def unique_across_queues?
       item[UNIQUE_ACROSS_QUEUES_KEY] || worker_options[UNIQUE_ACROSS_QUEUES_KEY] ||
         item[UNIQUE_ON_ALL_QUEUES_KEY] || worker_options[UNIQUE_ON_ALL_QUEUES_KEY] # TODO: Remove in v 6.1
     end
 
+    # Checks if we should disregard the worker when creating the unique digest
+    # @return [true, false]
     def unique_across_workers?
       item[UNIQUE_ACROSS_WORKERS_KEY] || worker_options[UNIQUE_ACROSS_WORKERS_KEY]
     end
 
+    # Checks if the worker class has been enabled for unique_args?
+    # @return [true, false]
     def unique_args_enabled?
       unique_args_method # && !unique_args_method.is_a?(Boolean)
     end
 
     # Filters unique arguments by proc or symbol
-    # returns provided arguments for other configurations
+    # @param [Array] args the arguments passed to the sidekiq worker
+    # @return [Array] {#filter_by_proc} when {#unique_args_method} is a Proc
+    # @return [Array] {#filter_by_symbol} when {#unique_args_method} is a Symbol
+    # @return [Array] args unfiltered when neither of the above
     def filtered_args(args)
       return args if args.empty?
       json_args = Normalizer.jsonify(args)
@@ -83,10 +112,17 @@ module SidekiqUniqueJobs
       end
     end
 
+    # Filters unique arguments by proc configured in the sidekiq worker
+    # @param [Array] args the arguments passed to the sidekiq worker
+    # @return [Array] with the filtered arguments
     def filter_by_proc(args)
       unique_args_method.call(args)
     end
 
+    # Filters unique arguments by method configured in the sidekiq worker
+    # @param [Array] args the arguments passed to the sidekiq worker
+    # @return [Array] unfiltered unless {#worker_method_defined?}
+    # @return [Array] with the filtered arguments
     def filter_by_symbol(args)
       return args unless worker_method_defined?(unique_args_method)
 
@@ -96,10 +132,16 @@ module SidekiqUniqueJobs
       args
     end
 
+    # The method to use for filtering unique arguments
     def unique_args_method
       @unique_args_method ||= worker_options[UNIQUE_ARGS_KEY]
       @unique_args_method ||= :unique_args if worker_method_defined?(:unique_args)
-      @unique_args_method ||= Sidekiq.default_worker_options.stringify_keys[UNIQUE_ARGS_KEY]
+      @unique_args_method ||= default_unique_args_method
+    end
+
+    # The global worker options defined in Sidekiq directly
+    def default_unique_args_method
+      Sidekiq.default_worker_options.stringify_keys[UNIQUE_ARGS_KEY]
     end
   end
 end

data/lib/sidekiq_unique_jobs/unlockable.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 module SidekiqUniqueJobs
+  # Utility module to help manage unique keys in redis.
+  # Useful for deleting keys that for whatever reason wasn't deleted
+  #
+  # @author Mikael Henriksson <mikael@zoolutions.se>
   module Unlockable
     module_function
 
+    # Unlocks a job.
+    # @param [Hash] item a Sidekiq job hash
     def unlock(item)
       SidekiqUniqueJobs::UniqueArgs.digest(item)
       SidekiqUniqueJobs::Locksmith.new(item).unlock
     end
 
+    # Deletes a lock regardless of if it was locked or not.
+    #
+    # This is good for situations when a job is locked by another item
+    # @param [Hash] item a Sidekiq job hash
     def delete(item)
       SidekiqUniqueJobs::UniqueArgs.digest(item)
       SidekiqUniqueJobs::Locksmith.new(item).delete!