simple_mutex 1.0.0

data/lib/simple_mutex/helper.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SimpleMutex
+  class Helper
+    LIST_MODES = %i[job batch default all].freeze
+
+    class << self
+      def get(lock_key)
+        new.get(lock_key)
+      end
+
+      def list(**options)
+        new.list(**options)
+      end
+    end
+
+    def get(lock_key)
+      raw_data = redis.get(lock_key)
+
+      return if raw_data.nil?
+
+      parsed_data = safe_parse(raw_data)
+
+      {
+        key: lock_key,
+        value: parsed_data.nil? ? raw_data : parsed_data,
+      }
+    end
+
+    # rubocop:disable Metrics/MethodLength, Style/HashEachMethods, Performance/CollectionLiteralInLoop
+    def list(mode: :default)
+      check_mode(mode)
+
+      result = []
+
+      redis.keys.each do |lock_key|
+        redis.watch(lock_key) do
+          raw_data = redis.get(lock_key)
+
+          unless raw_data.nil?
+            parsed_data = safe_parse(raw_data)
+
+            if parsed_data.nil?
+              result << { key: lock_key, value: raw_data } if mode == :all
+            else
+              lock_type = parsed_data&.dig("payload", "type")
+
+              if (mode == :all) ||
+                 (lock_type == "Job" && %i[job default].include?(mode)) ||
+                 (lock_type == "Batch" && %i[batch default].include?(mode))
+                result << { key: lock_key, value: parsed_data }
+              end
+            end
+          end
+
+          redis.unwatch
+        end
+      end
+
+      result
+    end
+    # rubocop:enable Metrics/MethodLength, Style/HashEachMethods, Performance/CollectionLiteralInLoop
+
+    private
+
+    def check_mode(mode)
+      return if LIST_MODES.include?(mode)
+      raise ::SimpleMutex::Error, "invalid mode ( only [:job, :batch, :default, :all] allowed)."
+    end
+
+    def redis
+      ::SimpleMutex.redis
+    end
+
+    def safe_parse(raw_data)
+      JSON.parse(raw_data)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/simple_mutex/mutex.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "json"
+
+module SimpleMutex
+  class Mutex
+    DEFAULT_EXPIRES_IN = 60 * 60 # 1 hour
+
+    ERR_MSGS = {
+      unlock: {
+        unknown: lambda do |lock_key|
+          "something when wrong when deleting lock key <#{lock_key}>."
+        end,
+        key_not_found: lambda do |lock_key|
+          "lock not found for lock key <#{lock_key}>."
+        end,
+        signature_mismatch: lambda do |lock_key|
+          "signature mismatch for lock key <#{lock_key}>."
+        end,
+      }.freeze,
+      lock: {
+        basic: lambda do |lock_key|
+          "failed to acquire lock <#{lock_key}>."
+        end,
+      }.freeze,
+    }.freeze
+
+    BaseError = Class.new(::StandardError) do
+      attr_reader :lock_key
+
+      def initialize(msg, lock_key)
+        @lock_key = lock_key
+        super(msg)
+      end
+    end
+
+    LockError   = Class.new(BaseError)
+    UnlockError = Class.new(BaseError)
+
+    class << self
+      attr_accessor :redis
+
+      def lock(lock_key, **options)
+        new(lock_key, **options).lock
+      end
+
+      def lock!(lock_key, **options)
+        new(lock_key, **options).lock!
+      end
+
+      def unlock(lock_key, signature: nil, force: false)
+        ::SimpleMutex.redis_check!
+
+        redis = ::SimpleMutex.redis
+
+        redis.watch(lock_key) do
+          raw_data = redis.get(lock_key)
+
+          if raw_data && (force || signature_valid?(raw_data, signature))
+            redis.multi { |multi| multi.del(lock_key) }.first.positive?
+          else
+            redis.unwatch
+            false
+          end
+        end
+      end
+
+      def unlock!(lock_key, signature: nil, force: false)
+        ::SimpleMutex.redis_check!
+
+        redis = ::SimpleMutex.redis
+
+        redis.watch(lock_key) do
+          raw_data = redis.get(lock_key)
+
+          begin
+            raise_error(UnlockError, :key_not_found, lock_key) unless raw_data
+
+            unless force || signature_valid?(raw_data, signature)
+              raise_error(UnlockError, :signature_mismatch, lock_key)
+            end
+
+            success = redis.multi { |multi| multi.del(lock_key) }.first.positive?
+
+            raise_error(UnlockError, :unknown, lock_key) unless success
+          ensure
+            redis.unwatch
+          end
+        end
+      end
+
+      def with_lock(lock_key, **options, &block)
+        new(lock_key, **options).with_lock(&block)
+      end
+
+      def raise_error(error_class, msg_template, lock_key)
+        template_base = error_class.name.split("::").last.gsub("Error", "").downcase.to_sym
+        error_msg     = ERR_MSGS[template_base][msg_template].call(lock_key)
+
+        raise(error_class.new(error_msg, lock_key))
+      end
+
+      def signature_valid?(raw_data, signature)
+        return false if raw_data.nil?
+
+        JSON.parse(raw_data)["signature"] == signature
+      rescue JSON::ParseError, TypeError
+        false
+      end
+    end
+
+    attr_reader :lock_key, :expires_in, :signature, :payload
+
+    def initialize(lock_key,
+                   expires_in: DEFAULT_EXPIRES_IN,
+                   signature:  SecureRandom.uuid,
+                   payload:    nil)
+      ::SimpleMutex.redis_check!
+
+      self.lock_key    = lock_key
+      self.expires_in  = expires_in.to_i
+      self.signature   = signature
+      self.payload     = payload
+    end
+
+    def lock
+      !!redis.set(lock_key, generate_data, nx: true, ex: expires_in)
+    end
+
+    def unlock(force: false)
+      self.class.unlock(lock_key, signature: signature, force: force)
+    end
+
+    def with_lock
+      lock!
+
+      begin
+        yield
+      ensure
+        unlock
+      end
+    end
+
+    def lock_obtained?
+      self.class.signature_valid?(redis.get(lock_key), signature)
+    end
+
+    def lock!
+      lock or raise_error(LockError, :basic)
+    end
+
+    def unlock!(force: false)
+      self.class.unlock!(lock_key, signature: signature, force: force)
+    end
+
+    private
+
+    attr_writer :lock_key, :expires_in, :signature, :payload
+
+    def generate_data
+      JSON.generate(
+        "signature"  => signature,
+        "created_at" => Time.now.to_s,
+        "payload"    => payload,
+      )
+    end
+
+    def redis
+      ::SimpleMutex.redis
+    end
+
+    def raise_error(error_class, msg_template)
+      self.class.raise_error(error_class, msg_template, lock_key)
+    end
+  end
+end

data/lib/simple_mutex/sidekiq_support/batch.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module SimpleMutex
+  module SidekiqSupport
+    class Batch
+      extend Forwardable
+
+      DEFAULT_EXPIRES_IN = 6 * 60 * 60
+
+      class Error < StandardError; end
+
+      attr_reader :batch, :lock_key, :expires_in
+
+      def_delegators :@batch, :on, :bid, :description, :description=
+
+      def initialize(lock_key:, expires_in: DEFAULT_EXPIRES_IN)
+        ::SimpleMutex.sidekiq_pro_check!
+
+        self.lock_key   = lock_key
+        self.expires_in = expires_in
+        self.batch      = ::Sidekiq::Batch.new
+      end
+
+      def jobs(&block)
+        mutex.lock!
+
+        set_callbacks(mutex.signature)
+
+        begin
+          batch.jobs(&block)
+        rescue => error
+          mutex.unlock!
+          raise error
+        end
+
+        status = ::Sidekiq::Batch::Status.new(batch.bid)
+
+        if status.total.zero?
+          mutex.unlock!
+          raise Error, "Batch should contain at least one job."
+        end
+      end
+
+      private
+
+      attr_writer :batch, :lock_key, :expires_in
+
+      def mutex
+        return @mutex if defined? @mutex
+
+        @mutex = ::SimpleMutex::Mutex.new(
+          lock_key,
+          expires_in: expires_in,
+          payload:    generate_payload(batch),
+        )
+      end
+
+      def generate_payload(batch)
+        { "type"       => "Batch",
+          "started_at" => Time.now.to_s,
+          "bid"        => batch.bid }
+      end
+
+      def set_callbacks(signature)
+        %i[death success].each do |event|
+          batch.on(
+            event,
+            ::SimpleMutex::SidekiqSupport::BatchCallbacks,
+            "lock_key"  => lock_key,
+            "signature" => signature,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/simple_mutex/sidekiq_support/batch_callbacks.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SimpleMutex
+  module SidekiqSupport
+    class BatchCallbacks
+      def on_death(_status, options)
+        ::SimpleMutex::Mutex.unlock!(options["lock_key"], signature: options["signature"])
+      end
+
+      def on_success(_status, options)
+        ::SimpleMutex::Mutex.unlock!(options["lock_key"], signature: options["signature"])
+      end
+    end
+  end
+end

data/lib/simple_mutex/sidekiq_support/batch_cleaner.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SimpleMutex
+  module SidekiqSupport
+    class BatchCleaner < ::SimpleMutex::BaseCleaner
+      class << self
+        def unlock_dead_batches
+          new.unlock
+        end
+      end
+
+      def initialize
+        ::SimpleMutex.sidekiq_pro_check!
+        super
+      end
+
+      private
+
+      def type
+        "Batch"
+      end
+
+      def path_to_entity_id
+        %w[payload bid]
+      end
+
+      def active_entity_ids
+        ::Sidekiq::BatchSet.new.map(&:bid)
+      end
+    end
+  end
+end

data/lib/simple_mutex/sidekiq_support/job_cleaner.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module SimpleMutex
+  module SidekiqSupport
+    class JobCleaner < ::SimpleMutex::BaseCleaner
+      class << self
+        def unlock_dead_jobs
+          new.unlock
+        end
+      end
+
+      private
+
+      def type
+        "Job"
+      end
+
+      def path_to_entity_id
+        %w[payload jid]
+      end
+
+      def active_entity_ids
+        ::Sidekiq::Workers.new.map { |_pid, _tid, work| work["payload"]["jid"] }
+      end
+    end
+  end
+end

data/lib/simple_mutex/sidekiq_support/job_mixin.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SimpleMutex
+  module SidekiqSupport
+    module JobMixin
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def locking!
+          @locking = true
+        end
+
+        def locking?
+          !!@locking
+        end
+
+        def skip_locking_error!
+          @skip_locking_error = true
+        end
+
+        def skip_locking_error?
+          !!@skip_locking_error
+        end
+
+        def lock_with_params!
+          @lock_with_params = true
+        end
+
+        def lock_with_params?
+          !!@lock_with_params
+        end
+
+        def set_job_timeout(value)
+          @job_timeout = value
+        end
+
+        def job_timeout
+          @job_timeout
+        end
+      end
+
+      def with_redlock(args = [], &block)
+        return yield unless self.class.locking?
+
+        options = {
+          params:           args,
+          lock_with_params: self.class.lock_with_params?,
+        }
+
+        options[:expires_in] = self.class.job_timeout unless self.class.job_timeout.nil?
+
+        ::SimpleMutex::SidekiqSupport::JobWrapper.new(self, **options).with_redlock(&block)
+      rescue SimpleMutex::Mutex::LockError => error
+        process_locking_error(error)
+      end
+
+      # override for custom processing
+      def process_locking_error(error)
+        raise error unless self.class.skip_locking_error?
+      end
+    end
+  end
+end

data/lib/simple_mutex/sidekiq_support/job_wrapper.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SimpleMutex
+  module SidekiqSupport
+    class JobWrapper
+      attr_reader :job, :params, :lock_key, :lock_with_params, :expires_in
+
+      DEFAULT_EXPIRES_IN = 5 * 60 * 60 # 5 hours
+
+      def initialize(job,
+                     params:           [],
+                     lock_key:         nil,
+                     lock_with_params: false,
+                     expires_in:       DEFAULT_EXPIRES_IN)
+        self.job              = job
+        self.params           = params
+
+        self.lock_key         = lock_key
+        self.lock_with_params = lock_with_params
+        self.expires_in       = expires_in
+      end
+
+      def with_redlock(&block)
+        ::SimpleMutex::Mutex.with_lock(
+          lock_key || generate_lock_key,
+          expires_in: expires_in,
+          payload:    generate_payload,
+          &block
+        )
+      end
+
+      private
+
+      attr_writer :job, :params, :lock_key, :lock_with_params, :expires_in
+
+      def generate_lock_key
+        key = if lock_with_params
+                "#{job.class.name}<#{params.to_json}>"
+              else
+                job.class.name
+              end
+        key.tr(":", "_")
+      end
+
+      def generate_payload
+        { "type"       => "Job",
+          "started_at" => Time.now.to_s,
+          "jid"        => job.jid }
+      end
+    end
+  end
+end

data/lib/simple_mutex/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SimpleMutex
+  VERSION = "1.0.0"
+end

data/lib/simple_mutex.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module SimpleMutex
+  require_relative "simple_mutex/version"
+  require_relative "simple_mutex/mutex"
+
+  require_relative "simple_mutex/base_cleaner"
+
+  require_relative "simple_mutex/sidekiq_support/job_wrapper"
+  require_relative "simple_mutex/sidekiq_support/job_cleaner"
+  require_relative "simple_mutex/sidekiq_support/job_mixin"
+
+  require_relative "simple_mutex/sidekiq_support/batch"
+  require_relative "simple_mutex/sidekiq_support/batch_callbacks"
+  require_relative "simple_mutex/sidekiq_support/batch_cleaner"
+
+  require_relative "simple_mutex/helper"
+
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :redis, :logger
+  end
+
+  def redis_check!
+    raise Error, no_redis_error unless redis
+  end
+
+  def sidekiq_pro_check!
+    raise Error, no_sidekiq_pro_error unless sidekiq_pro_installed?
+  end
+
+  def sidekiq_pro_installed?
+    Object.const_defined?("Sidekiq::Pro::VERSION")
+  end
+
+  def no_redis_error
+    "You should set SimpleMutex.redis before using any functions of this gem."
+  end
+
+  def no_sidekiq_pro_error
+    "Batch related functionality requires Sidekiq Pro to be installed."
+  end
+
+  module_function :redis_check!, :sidekiq_pro_check!, :sidekiq_pro_installed?,
+                  :no_redis_error, :no_sidekiq_pro_error
+end

data/simple_mutex.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/simple_mutex/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "simple_mutex"
+  spec.version       = SimpleMutex::VERSION
+  spec.authors       = ["bob-umbr"]
+  spec.email         = ["bob@umbrellio.biz"]
+
+  spec.summary       = "Redis-based mutex library for using with sidekiq jobs and batches."
+  spec.description   = "Redis-based mutex library for using with sidekiq jobs and batches."
+  spec.homepage      = "https://github.com/umbrellio/simple_mutex"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.5.0")
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "redis"
+  spec.add_runtime_dependency "redis-namespace"
+  spec.add_runtime_dependency "sidekiq"
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "bundler-audit"
+  spec.add_development_dependency "mock_redis"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rubocop"
+  spec.add_development_dependency "rubocop-config-umbrellio"
+  spec.add_development_dependency "rubocop-rspec"
+  spec.add_development_dependency "timecop"
+end