sidekiq_lockable_job 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c4078ebd3f7c4c03e6167d73f0ec1c4510403045ad09f09bef28386321932ef
-  data.tar.gz: 87b5bb9b9f8a2b8a61b5b69b63487fa2a44d992e43aa2090db017c69bfdc0229
+  metadata.gz: f55d67805fbdfb7c7dab6270ed0b74620e59ba5ac3022a1c5cb97e5ebc2dad20
+  data.tar.gz: c47ff60f8342d3d4432a8afddcb4b4bae330e08e43ef3573a3d6e175c9c9bad8
 SHA512:
-  metadata.gz: 72966453281278f758578bb8e904e9a61c0fab7e05e7cceaa47184a61974dc4277d4620185d592410f042a2b98f5650d2595b310aeb14554e5cd90890c2ece6b
-  data.tar.gz: 7b194fced1ac5ec4e12f148c67b70202680bc88bfe0a03dfd720dcddc6aa2ba2c725791c417f9341399b0211192d375b7aed7a0e54a65f53ddffaee9705772ed
+  metadata.gz: abeb924fe55362a5cfc2ee4f2e4b904d8c8f18f07f9bea6ad02b09b5d946bf4f34eb0355917ac2ab0fb593ba969323820840284186b3630b738da07ebb44db4d
+  data.tar.gz: 4a7855f124c9b2b5e4a6cb4a8ade26aac03d00527d300f8b764ee97487d9f82019de823f5f2f1a3874d9e4edb9604ac404a7493f453eec01a05db55c6c23426b

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sidekiq_lockable_job (0.1.0)
+    sidekiq_lockable_job (0.1.1)
       redis (= 4.0.1)
       sidekiq (= 5.0.5)
 

data/README.md

@@ -1,4 +1,4 @@
-# SidekiqLockableJob
+# Sidekiq::LockableJob
 
 Prevent a job to run until another one complete.
 
@@ -6,7 +6,21 @@ Prevent a job to run until another one complete.
 
 But sometime your jobs will be enqueued independently, then for you do not know the job id on which you depend on (you could parse Sidekiq queue, but...)
 
-`SidekiqLockableJob` allows you to set some locks ( based on job params ) when a job is enqueued or processed (store in redis), to prevent any other jobs to run if locked ( based on job params ) and will unlock any previously set locks ( based on job params ) when a job is **succesfully** completed.
+`Sidekiq::LockableJob` allows you to set some locks ( based on job params ) when a job is enqueued or processed (store in redis), to prevent any other jobs to run if locked ( based on job params ) and will unlock any previously set locks ( based on job params ) when a job is **succesfully** completed.
+
+## Use cases
+
+For a real exemple at @Babylist.
+
+Let's say a third party service send you a webhook request when some products of an order are shipped. (-> job A)
+Then send you an eventual webhook request when some products of this order can not be shipped (without explicitely telling you which ones). (-> job B), on which you want to cancelled any non shipped products for this order.
+
+Your third party service obviously send you this two webhook in the right order.
+But if something went wrong processing the first job (database issue, ...), you might ended cancelled the full order because the first job A haven't run prior to the second job B.
+
+In this scenario, you will request a lock `denied_order_cancellation_ABC` to be set when you first job A is enqueued (order key `ABC` being extracted from the job params), and you will request to raise a lock error (which will retry the job later) when the second job B is about to be processed if any lock exist for `denied_order_cancellation_ABC (order key `ABC` being extracted from the job params)`. And finally you will request an unlock of `denied_order_cancellation_ABC` when the first job A is **successfully** completed later on, which will allow the second job to succeed on its later retry.
+
+> If you expect multiple job of type A to be enqueued and needs to wait for all this locks to be lift (using the same key), see `MultiLockService`
 
 ## Installation
 
@@ -30,7 +44,7 @@ The gem is compose of four parts:
 
 - Setting locks when job is **enqueued**
 - Setting locks when job is **processed**
-- Raising `LockableJob::LockedJobError` when job **start** to processed but is locked
+- Raising `Sidekiq::LockableJob::LockedJobError` when job **start** to processed but is locked
 - Unsetting locks when job is **succesfully** processed
 
 ### Setting locks when job is **enqueued**
@@ -39,6 +53,8 @@ The gem is compose of four parts:
 > including `Sidekiq::LockableJob` auto set the middleware chain
 
 ```ruby
+require 'sidekiq_lockable_job'
+
 class Worker
   include Sidekiq::Worker
   include Sidekiq::LockableJob
@@ -62,6 +78,8 @@ When your job is **ENQUEUED** (`Worker.perform_async`), sidekiq LockableJob clie
 > including `Sidekiq::LockableJob` auto set the middleware chain
 
 ```ruby
+require 'sidekiq_lockable_job'
+
 class Worker
   include Sidekiq::Worker
   include Sidekiq::LockableJob
@@ -79,12 +97,14 @@ end
 
 When your job is **PROCESSED**, sidekiq LockableJob server middleware, will call `lockable_job_client_lock_keys` (before running the job) with the jobs arguments and set a lock for any returned keys
 
-### Raising `LockableJob::LockedJobError` when job start to processed but is locked
+### Raising `Sidekiq::LockableJob::LockedJobError` when job start to processed but is locked
 
 > happens in the sidekiq server middleware (on you rails worker)
 > including `Sidekiq::LockableJob` auto set the middleware chain
 
 ```ruby
+require 'sidekiq_lockable_job'
+
 class Worker
   include Sidekiq::Worker
   include Sidekiq::LockableJob
@@ -100,7 +120,10 @@ class Worker
 end
 ```
 
-When your job is **about** to be **processed**, sidekiq LockableJob server middleware, will call `lockable_job_locked_by_keys` (before processing the job) with the jobs arguments and raise `Sidekiq::LockableJob::LockedJobError` if any of the returned keys is locked
+When your job is **about** to be **processed**, sidekiq LockableJob server middleware, will call `lockable_job_locked_by_keys` (before processing the job) with the jobs arguments and raise `Sidekiq::LockableJob::LockedJobError` if any of the returned keys is locked.
+
+> [Sidekiq Error Handling](https://github.com/mperham/sidekiq/wiki/Error-Handling)
+> Sidekiq will retry failures with an exponential backoff using the formula (retry_count ** 4) + 15 + (rand(30) * (retry_count + 1)) (i.e. 15, 16, 31, 96, 271, ... seconds + a random amount of time). It will perform 25 retries over approximately 21 days. Assuming you deploy a bug fix within that time, the job will get retried and successfully processed. After 25 times, Sidekiq will move that job to the Dead Job queue, assuming that it will need manual intervention to work.
 
 ### Unsetting locks when job is **succesfully** processed
 
@@ -108,6 +131,8 @@ When your job is **about** to be **processed**, sidekiq LockableJob server middl
 > including `Sidekiq::LockableJob` auto set the middleware chain
 
 ```ruby
+require 'sidekiq_lockable_job'
+
 class Worker
   include Sidekiq::Worker
   include Sidekiq::LockableJob
@@ -125,6 +150,72 @@ end
 
 When your job is **successfully** to be **performed**, sidekiq LockableJob server middleware, will call `lockable_job_unlock_keys` (after processing the job) with the jobs arguments and unset lock for any returned keys
 
+
+## LockService vs MultiLockService vs CustomLockService
+
+By default `Sidekiq::LockableJob` use `Sidekiq::LockableJob::LockService` to lock, unlock and check lock.
+This service set lock time in redis when lock, unset redis key when unlock and check for redis key existance at lock check.
+
+This is enough for most common scenario, but you can use `Sidekiq::LockableJob::MultiLockService` if you need to count the number of lock.
+Each lock will increase the lock count, each unlock will decrease it, job will raise only if lock exist and count if > 0.
+
+> If you're using both default lock and multi lock, keys handle by a lock should all use the same lock service
+> see `lib/sidekiq/lockable_job/multi_lock_service.rb`
+
+```ruby
+require 'sidekiq_lockable_job'
+
+class MultiLockWorker
+  include Sidekiq::Worker
+  include Sidekiq::LockableJob
+  lockable_job_lock_service Sidekiq::LockableJob::MultiLockService
+end
+```
+
+If you want to use your own locking mechanism (to store somewhere else than redis, or handle locked differently), you can set your own `LockService` class.
+
+```ruby
+module CustomLockService
+  def self.lock(key)
+    // do you own lock
+  end
+
+  def self.unlock(key)
+    // do you own unlock
+  end
+
+  # non required helper method
+  def self.locked?(key)
+    // return true if locked
+  end
+
+  def self.handle_locked_by(key, worker_instance:, job:)
+    // do you own handle if locked
+    if locked?(key)
+      worker_instance.class.perform_in(3.hours, **job['args'])
+      return true
+    end
+    // return true if job should NOT run or false if it should
+    false
+  end
+end
+
+class Worker
+  include Sidekiq::Worker
+  include Sidekiq::LockableJob
+  lockable_job_lock_service CustomLockService
+end
+```
+
+## Roadmap
+
+- [x] `Sidekiq::LockableJob` lock (on enqueuing, processing), unlock (on successfully processed), raise if locked (before processing)
+- [x] `Sidekiq::LockableJob` auto add itself to sidekiq middleware
+- [x] Supporting lock/unlock count (if a job is queued 3 times, will increase the lock count to 3, and will require 3 unlock to be lifted)
+- [x] Externalize locking/unlocking/locked? mechanism (`LockableJobService`), and give option to use different service (ie.: not storing in Redis)
+- [x] Option to requeue job (with delay), or swallow job failure if locked
+- [ ] Option to no auto include to middleware (and use locks manually or add in different order in middleware chain)
+
 ## Specs
 
 ```
@@ -136,7 +227,7 @@ Sidekiq::LockableJob
   .locked?
     true if locked
     false if NOT locked
-  .raise_if_locked_by
+  .handle_locked_by
     raise if locked by any key
     raise if locked by single key
     DOT NOT raise if not locked by
@@ -155,7 +246,7 @@ Sidekiq::LockableJob::Middleware::Client::SetLocks
       behaves like set locks
         set locks
 
-Sidekiq::LockableJob::Middleware::Server::RaiseIfLocked
+Sidekiq::LockableJob::Middleware::Server::HandleLockedBy
   with no lock
     behaves like perform the job
       example at ./spec/sidekiq/lockable_job/middleware/server/shared.rb:13

data/lib/sidekiq/lockable_job/lock_service.rb

@@ -0,0 +1,38 @@
+require 'redis'
+
+module Sidekiq::LockableJob
+  module LockService
+    class Error < StandardError; end
+
+    REDIS_PREFIX_KEY = self.to_s.downcase
+
+    def self.lock(key)
+      redis.set(redis_key(key), Time.now.to_i)
+    end
+
+    def self.unlock(key)
+      redis.del(redis_key(key))
+    end
+
+    def self.locked?(key)
+      redis.exists(redis_key(key))
+    end
+
+    def self.handle_locked_by(keys, worker_instance:, job:)
+      keys = [keys] unless keys.nil? || keys.is_a?(Array)
+      keys&.each do |key|
+        raise LockedJobError.new("Locked by #{key}") if locked?(key)
+      end
+      # job is not locked and should be processed
+      false
+    end
+
+    def self.redis_key(key)
+      "#{REDIS_PREFIX_KEY}:#{key}"
+    end
+
+    def self.redis
+      $redis
+    end
+  end
+end

data/lib/sidekiq/lockable_job/middleware/client/set_locks.rb

@@ -20,7 +20,7 @@ module Sidekiq::LockableJob
             keys = worker_klass.send(:lockable_job_client_lock_keys, job['args'])
             keys = [keys] unless keys.nil? || keys.is_a?(Array)
             keys&.compact&.each do |key|
-              Sidekiq::LockableJob.lock(key)
+              worker_klass.current_lockable_job_lock_service.lock(key)
             end
           end
           yield

data/lib/sidekiq/lockable_job/middleware/middleware.rb

@@ -1,5 +1,5 @@
 
 require_relative 'client/set_locks.rb'
-require_relative 'server/raise_if_locked.rb'
+require_relative 'server/handle_locked_by.rb'
 require_relative 'server/unset_locks.rb'
 require_relative 'server/set_locks.rb'

data/lib/sidekiq/lockable_job/middleware/server/{raise_if_locked.rb → handle_locked_by.rb}

@@ -4,7 +4,7 @@ require 'sidekiq'
 module Sidekiq::LockableJob
   module Middleware
     module Server
-      class RaiseIfLocked
+      class HandleLockedBy
         # @param [Object] worker the worker instance
         # @param [Hash] job the full job payload
         #   * @see https://github.com/mperham/sidekiq/wiki/Job-Format
@@ -16,7 +16,11 @@ module Sidekiq::LockableJob
           if worker_klass.respond_to?(:lockable_job_locked_by_keys)
             keys = worker_klass.send(:lockable_job_locked_by_keys, job['args'])
             keys = [keys] unless keys.nil? || keys.is_a?(Array)
-            Sidekiq::LockableJob.raise_if_locked_by(keys)
+            locked = worker_klass.current_lockable_job_lock_service.handle_locked_by(keys, worker_instance: worker, job: job)
+            # LockableJobService && MultiLockService raise if job is lock
+            # but a CustomLockService could decide to re-enqueued the job
+            # if the service return true, it mean the job is lock and we skip it's processing (don't yield)
+            return if locked
           end
           yield
         end

data/lib/sidekiq/lockable_job/middleware/server/set_locks.rb

@@ -17,7 +17,7 @@ module Sidekiq::LockableJob
             keys = worker_klass.send(:lockable_job_server_lock_keys, job['args'])
             keys = [keys] unless keys.nil? || keys.is_a?(Array)
             keys&.compact&.each do |key|
-              Sidekiq::LockableJob.lock(key)
+              worker_klass.current_lockable_job_lock_service.lock(key)
             end
           end
           yield

data/lib/sidekiq/lockable_job/middleware/server/unset_locks.rb

@@ -18,7 +18,7 @@ module Sidekiq::LockableJob
             keys = worker_klass.send(:lockable_job_unlock_keys, job['args'])
             keys = [keys] unless keys.nil? || keys.is_a?(Array)
             keys&.compact&.each do |key|
-              Sidekiq::LockableJob.unlock(key)
+              worker_klass.current_lockable_job_lock_service.unlock(key)
             end
           end
         end

data/lib/sidekiq/lockable_job/multi_lock_service.rb

@@ -0,0 +1,38 @@
+require 'redis'
+
+module Sidekiq::LockableJob
+  module MultiLockService
+    class Error < StandardError; end
+
+    REDIS_PREFIX_KEY = self.to_s.downcase
+
+    def self.lock(key)
+      redis.incr(redis_key(key))
+    end
+
+    def self.unlock(key)
+      redis.decr(redis_key(key))
+    end
+
+    def self.locked?(key)
+      (redis.get(redis_key(key))&.to_i || 0) > 0
+    end
+
+    def self.handle_locked_by(keys, worker_instance:, job:)
+      keys = [keys] unless keys.nil? || keys.is_a?(Array)
+      keys&.each do |key|
+        raise LockedJobError.new("Locked by #{key}") if locked?(key)
+      end
+      # job is not locked and should be processed
+      false
+    end
+
+    def self.redis_key(key)
+      "#{REDIS_PREFIX_KEY}:#{key}"
+    end
+
+    def self.redis
+      $redis
+    end
+  end
+end

data/lib/sidekiq/{lockable_job/lockable_job.rb → lockable_job.rb}

@@ -1,49 +1,22 @@
 require 'sidekiq'
 require 'redis'
-require_relative 'middleware/middleware.rb'
+require_relative 'lockable_job/middleware/middleware.rb'
+require_relative 'lockable_job/lock_service'
+require_relative 'lockable_job/multi_lock_service'
 
 module Sidekiq
   module LockableJob
     class Error < StandardError; end
     class LockedJobError < StandardError; end
 
-    LOCKABLE_JOB_REDIS_PREFIX_KEY = 'sidekiq_locks'
-
-    def self.lock(key)
-      redis.set(redis_key(key), Time.now)
-    end
-
-    def self.unlock(key)
-      redis.del(redis_key(key))
-    end
-
-    def self.locked?(key)
-      redis.exists(redis_key(key))
-    end
-
-    def self.raise_if_locked_by(keys)
-      keys = [keys] unless keys.nil? || keys.is_a?(Array)
-      keys&.each do |key|
-        # perform in instead of retry?
-        # perform_in(2.minutes, *args)
-        raise LockedJobError.new("Locked by #{key}") if locked?(key)
-      end
-    end
-
-    def self.redis_key(key)
-      "#{LOCKABLE_JOB_REDIS_PREFIX_KEY}:#{key}"
-    end
-
-    def self.redis
-      $redis = Redis.new
-    end
+    DEFAULT_LOCKABLE_JOB_SERVICE = LockService
 
     def self.included(base)
       unless base.ancestors.include? Sidekiq::Worker
         raise ArgumentError, "Sidekiq::LockableJob can only be included in a Sidekiq::Worker"
       end
 
-      # base.extend(ClassMethods)
+      base.extend(ClassMethods)
 
       # Automatically add sidekiq middleware when we're first included
       #
@@ -52,8 +25,11 @@ module Sidekiq
       # chain is invoked so we're all good.
       #
       Sidekiq.configure_server do |config|
-        unless config.server_middleware.exists? Sidekiq::LockableJob::Middleware::Server::RaiseIfLocked
-          config.server_middleware.add Sidekiq::LockableJob::Middleware::Server::RaiseIfLocked
+        unless config.client_middleware.exists? Sidekiq::LockableJob::Middleware::Server::SetLocks
+          config.client_middleware.add Sidekiq::LockableJob::Middleware::Server::SetLocks
+        end
+        unless config.server_middleware.exists? Sidekiq::LockableJob::Middleware::Server::HandleLockedBy
+          config.server_middleware.add Sidekiq::LockableJob::Middleware::Server::HandleLockedBy
         end
         unless config.server_middleware.exists? Sidekiq::LockableJob::Middleware::Server::UnsetLocks
           config.server_middleware.add Sidekiq::LockableJob::Middleware::Server::UnsetLocks
@@ -65,5 +41,15 @@ module Sidekiq
         end
       end
     end
+
+    module ClassMethods
+      def current_lockable_job_lock_service
+        @lockable_job_lock_service || DEFAULT_LOCKABLE_JOB_SERVICE
+      end
+
+      def lockable_job_lock_service(service)
+        @lockable_job_lock_service = service
+      end
+    end
   end
 end

data/lib/sidekiq_lockable_job/version.rb

@@ -1,3 +1,3 @@
 module SidekiqLockableJob
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/sidekiq_lockable_job.rb

@@ -1,5 +1,5 @@
 require "sidekiq_lockable_job/version"
-require "sidekiq/lockable_job/lockable_job.rb"
+require_relative "sidekiq/lockable_job"
 
 module SidekiqLockableJob
   class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sidekiq_lockable_job
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Hugues Bernet-Rollande
@@ -118,12 +118,14 @@ files:
 - bin/console
 - bin/rspec
 - bin/setup
-- lib/sidekiq/lockable_job/lockable_job.rb
+- lib/sidekiq/lockable_job.rb
+- lib/sidekiq/lockable_job/lock_service.rb
 - lib/sidekiq/lockable_job/middleware/client/set_locks.rb
 - lib/sidekiq/lockable_job/middleware/middleware.rb
-- lib/sidekiq/lockable_job/middleware/server/raise_if_locked.rb
+- lib/sidekiq/lockable_job/middleware/server/handle_locked_by.rb
 - lib/sidekiq/lockable_job/middleware/server/set_locks.rb
 - lib/sidekiq/lockable_job/middleware/server/unset_locks.rb
+- lib/sidekiq/lockable_job/multi_lock_service.rb
 - lib/sidekiq_lockable_job.rb
 - lib/sidekiq_lockable_job/version.rb
 - sidekiq_lockable_job.gemspec