mongoid-locker 0.3.5 → 2.0.1

data/RELEASING.md

@@ -0,0 +1,68 @@
+Releasing Mongoid::Locker
+=========================
+
+There're no particular rules about when to release mongoid-locker. Release bug fixes frequently, features not so frequently and breaking API changes rarely.
+
+### Release
+
+Run tests, check that all tests succeed locally.
+
+```
+bundle install
+bundle exec rake
+```
+
+Check that the last build succeeded in [Travis CI](https://travis-ci.org/mongoid/mongoid-locker) for all supported platforms.
+
+Check the version, if needed modify [lib/mongoid/locker/version.rb](lib/mongoid/locker/version.rb).
+
+*  Increment the third number if the release has bug fixes and/or very minor features, only (eg. change `0.5.1` to `0.5.2`).
+*  Increment the second number if the release contains major features or breaking API changes (eg. change `0.5.1` to `0.4.0`).
+
+Change "Next Release" in [CHANGELOG.md](CHANGELOG.md) to the new version.
+
+```
+### 0.4.0 (2014-01-27)
+```
+
+Remove the line with "Your contribution here.", since there will be no more contributions to this release.
+
+Commit your changes.
+
+```
+git add CHANGELOG.md lib/mongoid-locker/version.rb
+git commit -m "Preparing for release, 0.4.0."
+git push origin master
+```
+
+Release.
+
+```
+$ bundle exec rake release
+
+mongoid-locker 0.4.0 built to pkg/mongoid-locker-0.4.0.gem.
+Tagged v0.4.0.
+Pushed git commits and tags.
+Pushed mongoid-locker 0.4.0 to rubygems.org.
+```
+
+### Prepare for the Next Version
+
+Add the next release to [CHANGELOG.md](CHANGELOG.md).
+
+```
+Next Release
+============
+
+* Your contribution here.
+```
+
+Increment the minor version, modify [lib/mongoid-locker/version.rb](lib/mongoid-locker/version.rb).
+
+Commit your changes.
+
+```
+git add CHANGELOG.md lib/mongoid-locker/version.rb
+git commit -m "Preparing for next release, 0.4.1."
+git push origin master
+```

data/Rakefile

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 require 'rubygems'
 require 'bundler/setup'
@@ -14,4 +14,4 @@ end
 require 'rubocop/rake_task'
 RuboCop::RakeTask.new(:rubocop)
 
-task default: [:rubocop, :spec]
+task default: %i[rubocop spec]

data/UPGRADING.md

@@ -0,0 +1,37 @@
+## Upgrading Mongoid-Locker
+
+## Upgrading to 2.0.0
+
+Mongoid-Locker supports only `5`, `6` and `7` versions of Mongoid.
+Since this version `Mongoid::Locker` uses unique name of locking and time is set by MongoDB. `Mongoid::Locker` no longer uses `locked_until` field and this field may be deleted with `User.all.unset(:locked_until)`. You must define new `locking_name` field of `String` type.
+
+```ruby
+class User
+  include Mongoid::Document
+  include Mongoid::Locker
+
+  field :locking_name, type: String
+  field :locked_at, type: Time
+end
+```
+
+The options `:timeout` and `retry_sleep` of `#with_lock` method was deprecated and have no effect. For details see [RubyDoc.info](https://www.rubydoc.info/gems/mongoid-locker/2.0.0/Mongoid/Locker#with_lock-instance_method).
+If you handle `Mongoid::Locker::LockError` error then this error should be renamed to `Mongoid::Locker::Errors::DocumentCouldNotGetLock`.
+
+### Upgrading to 1.0.0
+
+`Mongoid::Locker` no longer defines `locked_at` and `locked_until` fields when included. You must define these fields manually.
+
+```ruby
+class User
+  include Mongoid::Document
+  include Mongoid::Locker
+
+  field :locked_at, type: Time
+  field :locked_until, type: Time
+end
+```
+
+You can customize the fields used with a `locker` class method or via a global `configure`. See [Customizable :locked_at and :locked_until field names](https://github.com/mongoid/mongoid-locker#customizable-locked_at-and-locked_until-field-names) for more information.
+
+See [#55](https://github.com/mongoid/mongoid-locker/pull/55) for more information.

data/lib/config/locales/en.yml

@@ -0,0 +1,9 @@
+en:
+  mongoid:
+    locker:
+      errors:
+        messages:
+          document_could_not_get_lock:
+            message: "Document could not get lock for class %{klass} with id %{id}."
+          invalid_parameter:
+            message: "Invalid parameter :%{parameter} provided for class %{klass}."

data/lib/mongoid-locker.rb

@@ -1,2 +1,11 @@
+# frozen_string_literal: true
+
 require 'mongoid'
-require File.expand_path(File.join(File.dirname(__FILE__), 'mongoid', 'locker'))
+
+require 'mongoid/locker'
+require 'mongoid/locker/version'
+require 'mongoid/locker/wrapper'
+require 'mongoid/locker/errors'
+
+# Load english locale by default.
+I18n.load_path << File.join(File.dirname(__FILE__), 'config/locales', 'en.yml')

data/lib/mongoid/locker.rb

@@ -1,168 +1,313 @@
-require File.expand_path(File.join(File.dirname(__FILE__), 'locker', 'version'))
-require File.expand_path(File.join(File.dirname(__FILE__), 'locker', 'wrapper'))
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'securerandom'
 
 module Mongoid
   module Locker
-    # Error thrown if document could not be successfully locked.
-    class LockError < Exception; end
+    class << self
+      # Available parameters for +Mongoid::Locker+ module, a class where the module is included and it's instances.
+      MODULE_METHODS = %i[
+        locking_name_field
+        locked_at_field
+        maximum_backoff
+        lock_timeout
+        locker_write_concern
+        backoff_algorithm
+        locking_name_generator
+      ].freeze
+
+      attr_accessor(*MODULE_METHODS)
+
+      # Generates secure random string of +name#attempt+ format.
+      #
+      # @example
+      #   Mongoid::Locker.secure_locking_name(doc, { attempt: 1 })
+      #   #=> "zLmulhOy9yn_NE886OWNYw#1"
+      #
+      # @param doc [Mongoid::Document]
+      # @param opts [Hash] (see #with_lock)
+      # @return [String]
+      def secure_locking_name(_doc, opts)
+        "#{SecureRandom.urlsafe_base64}##{opts[:attempt]}"
+      end
+
+      # Returns random number of seconds depend on passed options.
+      #
+      # @example
+      #   Mongoid::Locker.exponential_backoff(doc, { attempt: 0 })
+      #   #=> 1.2280675023095662
+      #   Mongoid::Locker.exponential_backoff(doc, { attempt: 1 })
+      #   #=> 2.901641863236713
+      #   Mongoid::Locker.exponential_backoff(doc, { attempt: 2 })
+      #   #=> 4.375030664612267
+      #
+      # @param _doc [Mongoid::Document]
+      # @param opts [Hash] (see #with_lock)
+      # @return [Float]
+      def exponential_backoff(_doc, opts)
+        2**opts[:attempt] + rand
+      end
+
+      # Returns time in seconds remaining to complete the lock of the provided document. Makes requests to the database.
+      #
+      # @example
+      #   Mongoid::Locker.locked_at_backoff(doc, opts)
+      #   #=> 2.32422359
+      #
+      # @param doc [Mongoid::Document]
+      # @param opts [Hash] (see #with_lock)
+      # @return [Float | Integer]
+      # @return [0] if the provided document is not locked
+      def locked_at_backoff(doc, opts)
+        return doc.maximum_backoff if opts[:attempt] * doc.lock_timeout >= doc.maximum_backoff
+
+        locked_at = Wrapper.locked_at(doc).to_f
+        return 0 unless locked_at > 0
+
+        current_time = Wrapper.current_mongodb_time(doc.class).to_f
+        delay = doc.lock_timeout - (current_time - locked_at)
+
+        delay < 0 ? 0 : delay + rand
+      end
+
+      # Sets configuration using a block.
+      #
+      # @example
+      #   Mongoid::Locker.configure do |config|
+      #     config.locking_name_field     = :locking_name
+      #     config.locked_at_field        = :locked_at
+      #     config.lock_timeout           = 5
+      #     config.locker_write_concern   = { w: 1 }
+      #     config.maximum_backoff        = 60.0
+      #     config.backoff_algorithm      = :exponential_backoff
+      #     config.locking_name_generator = :secure_locking_name
+      #   end
+      def configure
+        yield(self) if block_given?
+      end
+
+      # Resets to default configuration.
+      #
+      # @example
+      #   Mongoid::Locker.reset!
+      def reset!
+        # The parameters used by default.
+        self.locking_name_field     = :locking_name
+        self.locked_at_field        = :locked_at
+        self.lock_timeout           = 5
+        self.locker_write_concern   = { w: 1 }
+        self.maximum_backoff        = 60.0
+        self.backoff_algorithm      = :exponential_backoff
+        self.locking_name_generator = :secure_locking_name
+      end
+
+      # @api private
+      def included(klass)
+        klass.extend(Forwardable) unless klass.ancestors.include?(Forwardable)
+
+        klass.extend ClassMethods
+        klass.singleton_class.instance_eval { attr_accessor(*MODULE_METHODS) }
+
+        klass.locking_name_field = locking_name_field
+        klass.locked_at_field = locked_at_field
+        klass.lock_timeout = lock_timeout
+        klass.locker_write_concern = locker_write_concern
+        klass.maximum_backoff = maximum_backoff
+        klass.backoff_algorithm = backoff_algorithm
+        klass.locking_name_generator = locking_name_generator
+
+        klass.def_delegators(klass, *MODULE_METHODS)
+        klass.singleton_class.delegate(*(methods(false) - MODULE_METHODS.flat_map { |method| [method, "#{method}=".to_sym] } - %i[included reset! configure]), to: self)
+      end
+    end
+
+    reset!
 
     module ClassMethods
       # A scope to retrieve all locked documents in the collection.
       #
+      # @example
+      #   Account.count
+      #   #=> 1717
+      #   Account.locked.count
+      #   #=> 17
+      #
       # @return [Mongoid::Criteria]
       def locked
-        where :locked_until.gt => Time.now
+        where(
+          '$and': [
+            { locking_name_field => { '$exists': true, '$ne': nil } },
+            { locked_at_field => { '$exists': true, '$ne': nil } },
+            { '$where': "new Date() - this.#{locked_at_field} < #{lock_timeout * 1000}" }
+          ]
+        )
       end
 
       # A scope to retrieve all unlocked documents in the collection.
       #
+      # @example
+      #   Account.count
+      #   #=> 1717
+      #   Account.unlocked.count
+      #   #=> 1700
+      #
       # @return [Mongoid::Criteria]
       def unlocked
-        any_of({ locked_until: nil }, :locked_until.lte => Time.now)
+        where(
+          '$or': [
+            {
+              '$or': [
+                { locking_name_field => { '$exists': false } },
+                { locked_at_field => { '$exists': false } }
+              ]
+            },
+            {
+              '$or': [
+                { locking_name_field => { '$eq': nil } },
+                { locked_at_field => { '$eq': nil } }
+              ]
+            },
+            {
+              '$where': "new Date() - this.#{locked_at_field} >= #{lock_timeout * 1000}"
+            }
+          ]
+        )
       end
 
-      # Set the default lock timeout for this class.  Note this only applies to new locks.  Defaults to five seconds.
+      # Unlock all locked documents in the collection. Sets locking_name_field and locked_at_field fields to nil. Returns number of unlocked documents.
       #
-      # @param [Fixnum] new_time the default number of seconds until a lock is considered "expired", in seconds
-      # @return [void]
-      def timeout_lock_after(new_time)
-        @lock_timeout = new_time
-      end
-
-      # Retrieve the lock timeout default for this class.
+      # @example
+      #   Account.unlock_all
+      #   #=> 17
+      #   Account.locked.unlock_all
+      #   #=> 0
       #
-      # @return [Fixnum] the default number of seconds until a lock is considered "expired", in seconds
-      def lock_timeout
-        # default timeout of five seconds
-        @lock_timeout || 5
+      # @return [Integer]
+      def unlock_all
+        update_all('$set': { locking_name_field => nil, locked_at_field => nil }).modified_count
       end
-    end
 
-    # @api private
-    def self.included(mod)
-      mod.extend ClassMethods
+      # Sets configuration for this class.
+      #
+      # @example
+      #   locker locking_name_field: :locker_locking_name,
+      #          locked_at_field: :locker_locked_at,
+      #          lock_timeout: 3,
+      #          locker_write_concern: { w: 1 },
+      #          maximum_backoff: 30.0,
+      #          backoff_algorithm: :locked_at_backoff,
+      #          locking_name_generator: :custom_locking_name
+      #
+      # @param locking_name_field [Symbol]
+      # @param locked_at_field [Symbol]
+      # @param maximum_backoff [Float, Integer]
+      # @param lock_timeout [Float, Integer]
+      # @param locker_write_concern [Hash]
+      # @param backoff_algorithm [Symbol]
+      # @param locking_name_generator [Symbol]
+      def locker(**params)
+        invalid_parameters = params.keys - Mongoid::Locker.singleton_class.const_get('MODULE_METHODS')
+        raise Mongoid::Locker::Errors::InvalidParameter.new(self.class, invalid_parameters.first) unless invalid_parameters.empty?
 
-      mod.field :locked_at, type: Time
-      mod.field :locked_until, type: Time
+        params.each_pair do |key, value|
+          send("#{key}=", value)
+        end
+      end
     end
 
-    # Returns whether the document is currently locked or not.
+    # Returns whether the document is currently locked in the database or not.
+    #
+    # @example
+    #   document.locked?
+    #   #=> false
     #
     # @return [Boolean] true if locked, false otherwise
     def locked?
-      !!(locked_until && locked_until > Time.now)
+      persisted? && self.class.where(_id: id).locked.limit(1).count == 1
     end
 
     # Returns whether the current instance has the lock or not.
     #
+    # @example
+    #   document.has_lock?
+    #   #=> false
+    #
     # @return [Boolean] true if locked, false otherwise
     def has_lock?
-      !!(@has_lock && self.locked?)
+      @has_lock || false
     end
 
-    # Primary method of plugin: execute the provided code once the document has been successfully locked.
+    # Executes the provided code once the document has been successfully locked. Otherwise, raises error after the number of retries to lock the document is exhausted or it is reached {ClassMethods#maximum_backoff} limit (depending what comes first).
+    #
+    # @example
+    #   document.with_lock(reload: true, retries: 3) do
+    #     document.quantity = 17
+    #     document.save!
+    #   end
     #
     # @param [Hash] opts for the locking mechanism
-    # @option opts [Fixnum] :timeout The number of seconds until the lock is considered "expired" - defaults to the {ClassMethods#lock_timeout}
-    # @option opts [Fixnum] :retries If the document is currently locked, the number of times to retry. Defaults to 0 (note: setting this to 1 is the equivalent of using :wait => true)
-    # @option opts [Float] :retry_sleep How long to sleep between attempts to acquire lock - defaults to time left until lock is available
-    # @option opts [Boolean] :wait If the document is currently locked, wait until the lock expires and try again - defaults to false. If set, :retries will be ignored
-    # @option opts [Boolean] :reload After acquiring the lock, reload the document - defaults to true
-    # @return [void]
-    def with_lock(opts = {})
-      had_lock = self.has_lock?
-
-      unless had_lock
-        opts[:retries] = 1 if opts[:wait]
-        lock(opts)
-      end
+    # @option opts [Fixnum] :retries (INFINITY) If the document is currently locked, the number of times to retry
+    # @option opts [Boolean] :reload (true) After acquiring the lock, reload the document
+    # @option opts [Integer] :attempt (0) Increment with each retry (not accepted by the method)
+    # @option opts [String] :locking_name Generate with each retry (not accepted by the method)
+    def with_lock(**opts)
+      opts = opts.dup
+      opts[:retries] ||= Float::INFINITY
+      opts[:reload] = opts[:reload] != false
+
+      acquire_lock(opts) if persisted? && (had_lock = !has_lock?)
 
       begin
         yield
       ensure
-        unlock if locked? && !had_lock
+        unlock!(opts) if had_lock
       end
     end
 
     protected
 
-    def acquire_lock(opts = {})
-      time = Time.now
-      timeout = opts[:timeout] || self.class.lock_timeout
-      expiration = time + timeout
-
-      # lock the document atomically in the DB without persisting entire doc
-      locked = Mongoid::Locker::Wrapper.update(
-        self.class,
-        {
-          :_id => id,
-          '$or' => [
-            # not locked
-            { locked_until: nil },
-            # expired
-            { locked_until: { '$lte' => time } }
-          ]
-        },
+    def acquire_lock(opts)
+      opts[:attempt] = 0
 
-        '$set' => {
-          locked_at: time,
-          locked_until: expiration
-        }
+      loop do
+        opts[:locking_name] = self.class.send(locking_name_generator, self, opts)
+        return if lock!(opts)
 
-      )
+        opts[:attempt] += 1
+        delay = self.class.send(backoff_algorithm, self, opts)
 
-      if locked
-        # document successfully updated, meaning it was locked
-        self.locked_at = time
-        self.locked_until = expiration
-        reload unless opts[:reload] == false
-        @has_lock = true
-      else
-        @has_lock = false
+        raise Errors::DocumentCouldNotGetLock.new(self.class, id) if delay >= maximum_backoff || opts[:attempt] >= opts[:retries]
+
+        sleep delay
       end
     end
 
-    def lock(opts = {})
-      opts = { retries: 0 }.merge(opts)
-
-      attempts_left = opts[:retries] + 1
-      retry_sleep = opts[:retry_sleep]
-
-      loop do
-        return if acquire_lock(opts)
-
-        attempts_left -= 1
+    def lock!(opts)
+      result = Mongoid::Locker::Wrapper.find_and_lock(self, opts)
 
-        if attempts_left > 0
-          # if not passed a retry_sleep value, we sleep for the remaining life of the lock
-          unless opts[:retry_sleep]
-            locked_until = Mongoid::Locker::Wrapper.locked_until(self)
-            # the lock might be released since the last check so make another attempt
-            next unless locked_until
-            retry_sleep = locked_until - Time.now
-          end
-
-          sleep retry_sleep if retry_sleep > 0
+      if result
+        if opts[:reload]
+          reload
         else
-          fail LockError.new('could not get lock')
+          self[locking_name_field] = result[locking_name_field.to_s]
+          self[locked_at_field] = result[locked_at_field.to_s]
         end
+
+        @has_lock = true
+      else
+        @has_lock = false
       end
     end
 
-    def unlock
-      # unlock the document in the DB without persisting entire doc
-      Mongoid::Locker::Wrapper.update(
-        self.class,
-        { _id: id },
-
-        '$set' => {
-          locked_at: nil,
-          locked_until: nil
-        }
+    def unlock!(opts)
+      Mongoid::Locker::Wrapper.find_and_unlock(self, opts)
 
-      )
+      unless destroyed?
+        self[locking_name_field] = nil
+        self[locked_at_field] = nil
+      end
 
-      self.attributes = { locked_at: nil, locked_until: nil } unless destroyed?
       @has_lock = false
     end
   end