simple_mutex 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 386f8c08c9a13c4402812145555a49a710fe28bf016455491bb779aa58cd7a90
+  data.tar.gz: 1a7e87acc3d54d3a90fd31a515c92c861823e10c054511c1466303fd5afc5e1f
+SHA512:
+  metadata.gz: c94e26f6ac88dd2d3be0b7a788051ef0bf8cda52acd41173d18dabb53521c9bb1feb639ba76deac1feccae666a0e3c359563569a5c5fd81175980d87bd324eac
+  data.tar.gz: bc0f67a008af4a252e118673584c691de022ad5568b83a088654e9070ad45a20c3fec5c77b2b2abd1f1208ca4831b36a4e276a20fbe49d3854886eda48dfd81f

data/.github/worklows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    # We want to run on external PRs, but not on our own internal PRs as they'll be run on push event
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != 'umbrellio/table_sync'
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["2.6", "2.7", "3.0"]
+
+    name: ${{ matrix.ruby }}
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - run: bundle exec rake bundle:audit
+      - run: bundle exec rubocop
+      - run: bundle exec rspec
+
+      - uses: coverallsapp/github-action@v1.1.2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,14 @@
+inherit_gem:
+  rubocop-config-umbrellio: lib/rubocop.yml
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle:
+    - key
+    - table
+  EnforcedColonStyle:
+    - key
+    - table
+
+Naming/VariableNumber:
+  Exclude:
+    - 'spec/**/*'

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,113 @@
+PATH
+  remote: .
+  specs:
+    simple_mutex (1.0.0)
+      redis
+      redis-namespace
+      sidekiq
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (6.1.4.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    ast (2.4.2)
+    bundler-audit (0.9.0.1)
+      bundler (>= 1.2.0, < 3)
+      thor (~> 1.0)
+    concurrent-ruby (1.1.9)
+    connection_pool (2.2.5)
+    diff-lcs (1.4.4)
+    i18n (1.8.10)
+      concurrent-ruby (~> 1.0)
+    minitest (5.14.4)
+    mock_redis (0.29.0)
+      ruby2_keywords
+    parallel (1.21.0)
+    parser (3.0.2.0)
+      ast (~> 2.4.1)
+    rack (2.2.3)
+    rainbow (3.0.0)
+    redis (4.5.1)
+    redis-namespace (1.8.1)
+      redis (>= 3.0.4)
+    regexp_parser (2.1.1)
+    rexml (3.2.5)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.2)
+    rubocop (1.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.7.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.12.0)
+      parser (>= 3.0.1.1)
+    rubocop-config-umbrellio (1.17.0.53)
+      rubocop (= 1.17.0)
+      rubocop-performance (= 1.10.0)
+      rubocop-rails (= 2.9.1)
+      rubocop-rake (= 0.5.1)
+      rubocop-rspec (= 2.2.0)
+      rubocop-sequel (= 0.2.0)
+    rubocop-performance (1.10.0)
+      rubocop (>= 0.90.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    rubocop-rails (2.9.1)
+      activesupport (>= 4.2.0)
+      rack (>= 1.1)
+      rubocop (>= 0.90.0, < 2.0)
+    rubocop-rake (0.5.1)
+      rubocop
+    rubocop-rspec (2.2.0)
+      rubocop (~> 1.0)
+      rubocop-ast (>= 1.1.0)
+    rubocop-sequel (0.2.0)
+      rubocop (~> 1.0)
+    ruby-progressbar (1.11.0)
+    ruby2_keywords (0.0.5)
+    sidekiq (6.2.2)
+      connection_pool (>= 2.2.2)
+      rack (~> 2.0)
+      redis (>= 4.2.0)
+    thor (1.1.0)
+    timecop (0.9.4)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.1.0)
+    zeitwerk (2.5.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler
+  bundler-audit
+  mock_redis
+  rspec
+  rubocop
+  rubocop-config-umbrellio
+  rubocop-rspec
+  simple_mutex!
+  timecop
+
+BUNDLED WITH
+   2.2.22

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Umbrellio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,364 @@
+# SimpleMutex
+
+`SimpleMutex::Mutex` - Redis-based locks with ability to store custom data inside them.
+
+`SimpleMutex::SidekiqSupport::JobWrapper` - wrapper for Sidekiq jobs that generates locks using
+job's class name and arguments (optional)
+
+`SimpleMutex:SidekiqSupport::JobMixin` - mixin for Sidekiq jobs with DSL simplifying usage
+of `SimpleMutex::SidekiqSupport::JobWrapper`
+
+`SimpleMutex::SidekiqSupport::JobCleaner` - cleaner for leftover locks created by SimpleMutex::Job
+if Sidekiq dies unexpectedly.
+
+`SimpleMutex::SidekiqSupport::Batch` - wrapper for Sidekiq Pro batches that use SimpleMutex::Mutex
+to prevent running multiple batch instances.
+
+`SimpleMutex:SidekiqSupport::BatchCleaner` - cleaner for leftover lock created by SimpleMutex::Batch
+if Sidekiq dies unexpectedly.
+
+`SimpleMutex::Helper` - auxiliary class for debugging purposes. Allows to inspect existing locks.
+
+
+## Configuration
+
+Providing Redis instance before using gem is mandatory.
+
+```ruby
+SimpleMutex.redis = Redis.new(
+  # ...
+)
+```
+
+Providing logger is optional (used by `SimpleMutex::SidekiqSupport::JobCleaner` and
+`SimpleMutex::SidekiqSupport::BatchCleaner`).
+
+```ruby
+SimpleMutex.logger = Logger.new(
+  # ...
+)
+```
+
+When using gem with Ruby on Rails you can set those in initializers
+
+## SimpleMutex::Mutex Usage
+
+### Initialization
+
+#### Arguments
+
+##### mandatory
+
+* `lock_key` - string that identifies lock, mandatory. Two pieces of locked code can't be run
+  simultaneously if they use same `lock_key`. They don't interfere with each other if different
+  `lock_key`'s are used
+
+##### optional
+
+Keyword arguments are used for optional args.
+
+* `expires_in:` - mutex TTL in second (or ActiveSupport::Numeric time interval), lock will be
+  removed by redis automatically when expired, lock will expire in 1 hour (`3600`) if not provided
+* `signature:` - string used to determine ownership of lock, checked when manually deleting lock,
+  will be generated by `SecureRandom.uuid` if not provided
+* `payload:` - any object that can be serialized as JSON, `nil` if not provided
+
+#### Example
+
+```ruby
+SimpleMutex::Mutex
+  .new(
+  "some_lock_key",
+  expires_in: 3600,
+  signature: "qwe123",
+  payload: { "started_at" => Time.now }
+)
+```
+
+### Wrapping block in mutex
+
+You can use method `#with_lock` to wrap code block in mutex
+
+```ruby
+  SimpleMutex::Mutex
+    .new(
+      "some_lock_key",
+      expires_in: 3600,
+      signature: "qwe123",
+      payload: { "started_at" => Time.now }
+    ).with_lock do
+    # your code
+  end
+```
+
+Method has delegator defined on class, so it can be used without manual instantiation
+
+```ruby
+  SimpleMutex::Mutex
+    .with_lock(
+      "some_lock_key",
+      expires_in: 3600,
+      signature: "qwe123",
+      payload: { "started_at" => Time.now }
+    ) do
+    # your code
+  end
+```
+
+### Manual lock control
+
+##### Using mutex instance
+
+```ruby
+  mutex = SimpleMutex::Mutex.new(
+            "some_lock_key",
+             expires_in: 3600,
+             signature: "qwe123",
+             payload: { "started_at" => Time.now }
+          )
+
+  mutex.lock!
+  # your code
+  mutex.unlock!
+```
+
+If you for some reason don't want exceptions to be raised when obtaining/deleting lock is failed,
+you can use non-! methods.
+
+```ruby
+  mutex = SimpleMutex::Mutex.new("some_lock_key")
+  # obtaining of lock is not guaranteed
+  mutex.lock
+  # but you can check if it is obtained (true if lock with correct signature exists)
+  mutex.lock_obtained?
+  # releasing of lock is not guaranteed
+  mutex.unlock 
+```
+
+##### Using without instance
+
+There are `::lock`/`::lock!`/`::unlock`/`::unlock!` methods defined on class if you don't want to 
+explicitly use initializer (though it still will be used behind the scenes as `::lock` and `::lock!`
+class methods are just delegators).
+
+Mutexes have random `signature` stored inside to determine ownership. By default it prevents
+deleting locks with signature different from provided. You can use `force: true` to ignore
+signature check.
+
+`::lock` and `::lock!` class methods accept same arguments as in `::new`
+
+`::unlock` and `::unlock!` accept next arguments:
+
+* `lock_key` - same as in `::new`
+* `signature:` - same as in `::new`
+* `force:` - boolean, signature will be ignored if `true`, optional, `false` by default
+
+```ruby
+  SimpleMutex::Mutex.lock!("some_lock_key", signature: "abra_kadabra")
+
+  # This will work because signature is same as in lock
+  SimpleMutex::Mutex.unlock!("some_lock_key", signature: "abra_kadabra")
+
+  # This won't work, because signature is missing
+  SimpleMutex::Mutex.unlock!("some_lock_key")
+
+  # This won't work, because signature is different
+  SimpleMutex::Mutex.unlock!("some_lock_key", signature: "alakazam")
+
+  # This will work because of force: true
+  SimpleMutex::Mutex.unlock!("some_lock_key", force: true)
+
+  # This will work because of force: true
+  SimpleMutex::Mutex.unlock!("some_lock_key", signature: "alakazam", force: true)
+```
+
+### Getting signature from instance
+
+You can get signature from instance if you want. By default it is UUID generated by SecureRandom.
+
+```ruby
+  mutex = SimpleMutex::Mutex.new("some_lock_key")
+  mutex.signature
+```
+
+## SimpleMutex::SidekiqSupport::JobWrapper Usage
+
+This class made to simplify usage for locking of sidekiq jobs. It will create lock with
+`lock_key` based on job's `class.name` and it's arguments if `lock_with_params: true`.
+
+Job's ID (`jid`) and time when job's execution is started will be stored inside mutex value.
+
+```ruby
+  class SomeJob
+    include Sidekiq::Worker
+
+    def perform(*args)
+      SimpleMutex::SidekiqSupport::JobWrapper.new(
+        self,
+        params:           args,
+        lock_with_params: true,
+        expires_in:       1.hour,
+        payload:          { this_is_optional: true }
+      ).with_redlock do
+        # your code
+      end
+    end
+  end
+```
+
+`params` will be used to generate `lock_key` if `lock_with_params: true`.
+
+`expires_in:` is in seconds, optional, 5 hours by default.
+
+`payload:` optional serializable object.
+
+## SimpleMutex::SidekiqSupport::Batch Usage
+
+This is wrapper for `Sidekiq::Batch` (from Sidekiq Pro) that helps to prevent running two
+similar batches.
+
+```ruby
+  batch = SimpleMutex::SidekiqSupport::Batch.new(
+      lock_key: "my_batch",
+      expires_in: 23.hours.to_i,
+    )
+
+    batch.description = "batch of MyJobs"
+    batch.on(:success, self.class, {}) # you can add custom callbacks like with Sidekiq::Batch
+    batch.on(:death ,  self.class, {})
+
+    batch.jobs do
+      set_of_job_attributes.each do |job_attributes|
+        MyJob.perform(job_attributes)
+      end
+    end
+```
+
+* `lock_key` - manatory lock key
+* `expires_in:` - optional TTL, 6 hours if not provided
+
+## SimpleMutex::SidekiqSupport::JobCleaner Usage
+
+If you use SimpleMutex for locking jobs via `SimpleMutex::SidekiqSupport::Job`, when Sidekiq dies
+unexpectedely, there can be leftover mutexes for dead jobs. To delete them you can use:
+
+```ruby
+  SimpleMutex::SidekiqSupport::JobCleaner.unlock_dead_jobs
+```
+
+
+## SimpleMutex::SidekiqSupport::BatchCleaner Usage
+
+If you use SimpleMutex for locking Batches via `SimpleMutex::SidekiqSupport::Batch`, when Sidekiq
+dies unexpectedely, there can be leftover mutexes for dead batches. To delete them you can use:
+
+```ruby
+  SimpleMutex::SidekiqSupport::BatchCleaner.unlock_dead_batches
+```
+
+## SimpleMutex::Helper Usage
+
+Getting lock by `lock_key` (returns nil if no such lock)
+
+```ruby
+SimpleMutex::Helper.get("some_lock_key")
+```
+
+Listing existing locks.
+
+```ruby
+SimpleMutex::Helper.list(mode: :default)
+```
+
+`mode:` paramater allows to filter locks by type:
+* `:all` - all locks including manual
+* `:job` - job locks
+* `:batch`   - batch locks
+* `:default` - job and batch locks
+
+## SimpleMutex::SidekiqSupport::JobMixin Usage
+
+Base Job class
+
+```ruby
+class ApplicationJob
+  include Sidekiq::Worker
+  include SimpleMutex::SidekiqSupport::JobMixin
+
+  class << self
+    def inherited(job_class)
+      # Setting default timeout for mutex.
+      job_class.set_job_timeout(5 * 60 * 60) # 5 hours
+
+      job_class.prepend(
+        Module.new do
+          def perform(*args)
+              with_redlock(args) { super }
+          end
+        end,
+      )
+    end
+  end
+end
+```
+
+DSL:
+ - `locking!` - enables locking with simple_mutex for jobs of this class
+ - `lock_with_params!` - locks are specific for set of arguments. Same job with other arguments
+can still be called.
+ - `skip_locking_error?` - suppresses `SimpleMutex::Mutex::LockError`
+ - `set_job_timeout` - redis mutex TTL in seconds (will be removed by redis itself on timeout)
+
+Example:
+
+```ruby
+class SpecificJob < ApplicaionJob
+  locking!
+  lock_with_params!
+  set_job_timeout 6 * 60 * 60
+
+  def perform
+    # ...
+  end
+end
+```
+
+You can also override error processing for SimpleMutex::Mutex::LockError
+
+```ruby
+  # DEFAULT ERROR PROCESSING
+  # def process_locking_error(error)
+  #   raise error unless self.class.skip_locking_error?
+  # end
+
+  class SpecificJob < ApplicaionJob
+    locking!
+
+    def perform
+      # ...
+    end
+
+    def process_locking_error(error)
+      SomeLogger.error(error.msg)
+      raise error unless self.class.skip_locking_error?
+    end
+  end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/umbrellio/simple_mutex.
+
+## License
+
+Released under MIT License.
+
+## Authors
+
+Team Umbrellio
+
+---
+
+<a href="https://github.com/umbrellio/">
+<img style="float: left;" src="https://umbrellio.github.io/Umbrellio/supported_by_umbrellio.svg" alt="Supported by Umbrellio" width="439" height="72">
+</a>

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "simple_mutex"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/simple_mutex/base_cleaner.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module SimpleMutex
+  class BaseCleaner
+    def unlock
+      ::SimpleMutex.redis_check!
+
+      logger&.info(start_msg)
+
+      redis.keys.select do |lock_key|
+        redis.watch(lock_key) do
+          raw_data = redis.get(lock_key)
+
+          next redis.unwatch if raw_data.nil?
+
+          parsed_data = safe_parse(raw_data)
+
+          next redis.unwatch unless parsed_data&.dig("payload", "type") == type
+
+          entity_id = parsed_data&.dig(*path_to_entity_id)
+
+          next redis.unwatch if entity_id.nil? || active?(entity_id)
+
+          return_value = redis.multi { redis.del(lock_key) }
+
+          log_iteration(lock_key, raw_data, return_value) unless logger.nil?
+
+          return_value.first.positive?
+        end
+      end
+
+      logger&.info(end_msg)
+    end
+
+    private
+
+    def active?(entity_id)
+      active_entity_ids.include?(entity_id)
+    end
+
+    def type
+      raise NoMethodError
+    end
+
+    def path_to_entity_id
+      raise NoMethodError
+    end
+
+    def get_active_entity_ids
+      raise NoMethodError
+    end
+
+    def safe_parse(raw_data)
+      JSON.parse(raw_data)
+    rescue JSON::ParserError, TypeError
+      nil
+    end
+
+    def active_entity_ids
+      return @active_entity_ids if defined? @active_entity_ids
+
+      @active_entity_ids = get_active_entity_ids
+    end
+
+    def log_iteration(lock_key, raw_data, return_value)
+      log_msg = generate_log_msg(lock_key, raw_data, return_value)
+
+      if return_value&.first.is_a?(Integer)
+        logger.info(log_msg)
+      else
+        logger.error(log_msg)
+      end
+    end
+
+    def start_msg
+      "START #{self.class.name}"
+    end
+
+    def end_msg
+      "END #{self.class.name}"
+    end
+
+    def generate_log_msg(lock_key, raw_data, return_value)
+      "Trying to delete row with key <#{lock_key.inspect}> "\
+      "and value <#{raw_data.inspect}>. "\
+      "MULTI returned value <#{return_value.inspect}>."
+    end
+
+    def redis
+      ::SimpleMutex.redis
+    end
+
+    def logger
+      ::SimpleMutex.logger
+    end
+  end
+end