mongo-lock 1.0.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MGRiNTY2ZDM1N2YyM2M3MjcwZGNmMTI3ZTVhM2YyMmM1MWNlNWI3Zg==
+  data.tar.gz: !binary |-
+    Y2VlMzFlMDU2MDljMGE3ZTI1NTQwZWE1NDU2OTJmMmMwYjUzOWRmZQ==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    ZDU5MmM1YTYxN2Y4ZDhjNDMxYmM5NjQzYjliMmZhN2YzZmIwODQ1NzkwMWVi
+    MmFlMGNhYmE1NTk2ZTI4NDY1M2ZlNWY1MjMxN2E5YjBhNTlmMzEwMWVmZDFk
+    ZTY3YTgyYWJhOWU3YmE3ODE4MmQ0ZjZjZTM2N2M1NTQ0ZTk0Mjc=
+  data.tar.gz: !binary |-
+    MTQzNWNiYTYxYWVkZDQ2MjNlZGEwNDYzMTQ2MzBkNTA3OTZkODZmNDczYzEx
+    YmViNzkyN2RlMzU0MDA4MDE5NGMzNzNlMzE2MWUzNTM2YjUyZTFhYTJmZDQ3
+    M2VjYjg0NDQwNWE4YzEyNTFhNzBkMWY4OWUzMDhjNTczOWQxODQ=

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in trakio-ruby.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,51 @@
+PATH
+  remote: .
+  specs:
+    mongo-lock (1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (4.0.3)
+      i18n (~> 0.6, >= 0.6.4)
+      minitest (~> 4.2)
+      multi_json (~> 1.3)
+      thread_safe (~> 0.1)
+      tzinfo (~> 0.3.37)
+    atomic (1.1.14)
+    coderay (1.1.0)
+    diff-lcs (1.2.5)
+    fuubar (1.3.2)
+      rspec (>= 2.14.0, < 3.1.0)
+      ruby-progressbar (~> 1.3)
+    i18n (0.6.9)
+    method_source (0.8.2)
+    minitest (4.7.5)
+    multi_json (1.8.4)
+    pry (0.9.12.6)
+      coderay (~> 1.0)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.5)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.5)
+    ruby-progressbar (1.4.1)
+    slop (3.4.7)
+    thread_safe (0.1.3)
+      atomic
+    tzinfo (0.3.38)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport
+  fuubar
+  mongo-lock!
+  pry
+  rspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014 trak.io Ltd
+
+MIT License
+
+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,291 @@
+Mongo::Lock
+==========
+
+[![Code Climate](https://codeclimate.com/github/trakio/mongo-lock.png)](https://codeclimate.com/github/trakio/mongo-lock)
+
+Key based pessimistic locking for Ruby and MongoDB. Is this key avaliable? Yes - Lock it for me for a sec will you. No - OK I'll just wait here until its ready.
+
+It handles timeouts and and vanishing lock owners (such as machine failures)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mongo-lock'
+```
+
+And then execute:
+
+```
+$ bundle
+```
+
+Or install it yourself as:
+
+```
+$ gem install mongo-lock
+```
+
+Build you indexes on any collection that is going to hold locks:
+
+```ruby
+Mongo::Lock.ensure_indexes # Will use the collection provided to #configure
+```
+
+For this to work you must have configured your collection or collections in when intializing locks, in #configure or .configure.
+
+## Shout outs
+
+We took quite a bit of inspiration from the [redis versions](https://github.com/mlanett/redis-lock) [of this gem](https://github.com/PatrickTulskie/redis-lock) by [@mlanett](https://github.com/mlanett/redis-lock) and [@PatrickTulskie](https://github.com/PatrickTulskie). If you aren't already using MongoDB or are already using Redis in your stack you probably want to think about using one of them.
+
+We also looked at [mongo-locking gem](https://github.com/servio/mongo-locking) by [@servio](https://github.com/servio). It was a bit complicated for ours needs, but if you need to lock related and embedded documents rather than just keys it could be what you need.
+
+## Background
+
+A lock has an expected lifetime. If the owner of a lock disappears (due to machine failure, network failure, process death), you want the lock to expire and another owner to be able to acquire the lock. At the same time, the owner of a lock should be able to extend its lifetime. Thus, you can acquire a lock with a conservative estimate on lifetime, and extend it as necessary, rather than acquiring the lock with a very long lifetime which will result in long waits in the event of failures.
+
+A lock has an owner. Mongo::Lock defaults to using an owner id of HOSTNAME:PID:TID.
+
+## Configuration
+
+Mongo::Lock makes no effort to help configure the MongoDB connection - that's
+what the Mongo Ruby Driver is for.
+
+Configuring Mongo::Lock with the Mongo Ruby Driver would look like this:
+
+```ruby
+Mongo::Lock.configure collection: Mongo::Connection.new("localhost").db("somedb").collection("locks")
+```
+
+Or using Mongoid:
+
+```ruby
+Mongo::Lock.configure collection: Mongoid.database.collection("locks")
+```
+
+You can add multiple collections with a hash that can be referenced later using symbols:
+
+```ruby
+Mongo::Lock.configure collections: { default: Mongoid.database.collection("locks"), other: Mongoid.database.collection("other_locks") }
+Mongo::Lock.acquire('my_lock') # Locks in the default collection
+Mongo::Lock.acquire('my_lock', collection: :other) # Locks in the other_locks collection
+```
+
+You can also configure using a block:
+
+```ruby
+Mongo::Lock.configure do |config|
+  config.collections: {
+    default: Mongoid.database.collection("locks"),
+    other: Mongoid.database.collection("other_locks")
+  }
+end
+```
+
+### Acquisition timeout_in
+
+A lock may need more than one attempt to acquire it. Mongo::Lock offers:
+
+```ruby
+Mongo::Lock.configure do |config|
+  config.timeout_in = false # timeout_in in seconds on acquisition; this defaults to false ie no time limit.
+  config.limit = 100 # The limit on the number of acquisition attempts; this defaults to 100.
+  config.frequency = 1 # Frequency in seconds for acquisition attempts ; this defaults to 1.
+  # acquisition_attempt_frequency can also be given as a proc which will be passed the attempt number
+  config.frequency = Proc.new { |x| x**2 }
+end
+```
+
+### Lock Expiry
+
+A lock will automatically be relinquished once its expiry has passed. Expired locks are cleaned up by [MongoDB's TTL index](http://docs.mongodb.org/manual/tutorial/expire-data/), which may take up to 60 seconds or more depending on load to actually remove expired locks. Expired locks that have not been cleaned out can still be acquire. **You must have built your indexes to ensure expired locks are cleaned out.**
+
+```ruby
+Mongo::Lock.configure do |config|
+  config.expires_after = false # timeout_in in seconds for lock expiry; this defaults to 10.
+end
+```
+
+You can remove expired locks yourself with:
+
+```ruby
+Mongo::Lock.clean_expired
+```
+
+
+### Raising Errors
+
+If a lock cannot be acquired, released or extended it will return false, you can set the raise option to true to raise a Mongo::Lock::LockNotAcquiredError or Mongo::Lock::LockNotReleasedError.
+
+```ruby
+Mongo::Lock.configure do |config|
+  config.raise = true # Whether to raise an error when acquire, release or extend fail.
+end
+```
+
+Using .acquire!, #acquire!, .release!, #release!, #extend_by! and #extend! will also raise exceptions instead of returning false.
+
+### Owner
+
+By default the owner id will be generated using the following Proc:
+
+```ruby
+Proc.new { "#{`hostname`.strip}:#{Process.pid}:#{Thread.object_id}" }
+```
+
+You can override this with either a Proc that returns any object that responds to to_s, or with any object that responds to #to_s.
+
+```ruby
+Mongo::Lock.configure do |config|
+  config.owner = ['my', 'owner', 'id']
+end
+# Or
+Mongo::Lock.configure do |config|
+  config.owner = Proc.new { [`hostname`.strip, Process.pid] }
+end
+```
+
+Note: Hosts, threads or processes using the same owner can acquire each others locks.
+
+## Usage
+
+You can use Mongo::Lock's class methods:
+
+```ruby
+Mongo::Lock.acquire('my_key', options) do |lock|
+  # Do Something here that needs my_key locked
+end
+
+lock = Mongo::Lock.new('my_key', options).acquire
+# Do Something here that needs my_key locked
+lock.release
+# or
+Mongo::Lock.release('my_key')
+```
+
+Or you can initialise your own instance.
+
+```ruby
+Mongo::Lock.new('my_key', options).acquire do |lock|
+  # Do Something here that needs my_key locked
+end
+
+lock = Mongo::Lock.acquire('my_key', options)
+# Do Something here that needs my_key locked
+lock.release
+# or
+Mongo::Lock.release('my_key')
+```
+
+### Options
+
+When using Mongo::Lock#acquire, Mongo::Lock#release or Mongo::Lock#new after the key you may overide any of the following options:
+
+```ruby
+Mongo::Lock.new 'my_key', {
+  collection: Mongo::Connection.new("localhost").db("somedb").collection("locks"), # May also be a symbol if that symbol was provided in the collections hash to Mongo::Lock.configure
+  timeout_in: 10, # timeout_in in seconds on acquisition; this defaults to false ie no time limit.
+  limit: 10, # The limit on the number of acquisition attempts; this defaults to 100.
+  frequency: 2, # Frequency in seconds for acquisition attempts ; this defaults to 1.
+  expires_after: 10,# timeout_in in seconds for lock expiry; this defaults to 10.
+}
+```
+
+### Extending lock
+
+You can extend a lock by calling Mongo::Lock#extend_by with the number of seconds to extend the lock.
+
+```ruby
+Mongo::Lock.new 'my_key' do |lock|
+  lock.extend_by 10
+end
+```
+
+You can also call Mongo::Lock#extend and it will extend by the lock's expires_after option.
+
+```ruby
+Mongo::Lock.new 'my_key' do |lock|
+  lock.extend
+end
+```
+
+### Check you still hold a lock
+
+```ruby
+Mongo::Lock.acquire 'my_key', expires_after: 10 do |lock|
+  sleep 9
+  lock.expired? # False
+  sleep 11
+  lock.expired? # True
+end
+```
+
+### Check a key is already locked without acquiring it
+
+```ruby
+Mongo::Lock.available? 'my_key'
+# Or
+lock = Mongo::Lock.new('my_key')
+lock.available?
+```
+
+### Failures
+
+If Mongo::Lock#acquire cannot acquire a lock within its configuration limits it will return false.
+
+```ruby
+unless Mongo::Lock.acquire 'my_key'
+  # Maybe try again tomorrow
+end
+```
+
+If Mongo::Lock#release cannot release a lock because it wasn't acquired it will return false. If it has already been released, or has expired it will do nothing and return true.
+
+```ruby
+unless Mongo::Lock.release 'my_key'
+  # Eh somebody else should release it eventually
+end
+```
+
+If Mongo::Lock#extend cannot be extended because it has already been released, it is owned by someone else or it was never acquired it will return false.
+
+```ruby
+unless lock.extend_by 10
+  # Eh somebody else should release it eventually
+end
+```
+
+If the raise error option is set to true or you append ! to the end of the method name and you call any of the acquire, release, extend_by or extend methods they will raise a Mongo::Lock::NotAcquiredError, Mongo::Lock::NotReleasedError or Mongo::Lock::NotExtendedError instead of returning false.
+
+```ruby
+begin
+  Mongo::Lock.acquire! 'my_key'
+rescue Mongo::Lock::LockNotAcquiredError => e
+  # Maybe try again tomorrow
+end
+
+# Or
+
+begin
+  Mongo::Lock.acquire 'my_key', raise: true
+rescue Mongo::Lock::LockNotAcquiredError => e
+  # Maybe try again tomorrow
+end
+```
+
+## Contributors
+
+Matthew Spence (msaspence)
+
+The bulk of this gem has been developed for and by [trak.io](http://trak.io)
+
+[![trak.io](http://trak.io/assets/images/logo@2x.png)](http://trak.io)
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test

data/lib/mongo-lock.rb

@@ -0,0 +1,296 @@
+require 'mongo-lock/configuration'
+
+module Mongo
+  class Lock
+
+    class NotAcquiredError < StandardError ; end
+    class NotReleasedError < StandardError ; end
+    class NotExtendedError < StandardError ; end
+
+    attr_accessor :configuration
+    attr_accessor :key
+    attr_accessor :acquired
+    attr_accessor :expires_at
+    attr_accessor :released
+
+    def self.configure options = {}, &block
+      defaults = {
+        timeout_in: 10,
+        limit: 100,
+        frequency: 1,
+        expires_after: 10,
+        raise: false,
+        owner: Proc.new { "#{`hostname`.strip}:#{Process.pid}:#{Thread.object_id}" }
+      }
+      defaults = defaults.merge(@@default_configuration) if defined?(@@default_configuration) && @@default_configuration
+      @@default_configuration = Configuration.new(defaults, options, &block)
+    end
+
+    def self.configuration
+      if defined? @@default_configuration
+        @@default_configuration
+      else
+        @@default_configuration = configure
+      end
+    end
+
+    def self.release_all options = {}
+      if options.include? :collection
+        release_collection configuration.collection(options[:collection]), options[:owner]
+      else
+        configuration.collections.each_pair do |key,collection|
+          release_collection collection, options[:owner]
+        end
+      end
+    end
+
+    def self.release_collection collection, owner=nil
+      selector = if owner then { owner: owner } else {} end
+      collection.remove(selector)
+    end
+
+    def self.init_and_send key, options = {}, method
+      lock = self.new(key, options)
+      lock.send(method)
+      lock
+    end
+
+    def self.acquire key, options = {}
+      init_and_send key, options, :acquire
+    end
+
+    def self.release key, options = {}
+      init_and_send key, options, :release
+    end
+
+    def self.acquire! key, options = {}
+      init_and_send key, options, :acquire!
+    end
+
+    def self.release! key, options = {}
+      init_and_send key, options, :release!
+    end
+
+    def self.available? key, options = {}
+      init_and_send key, options, :available?
+    end
+
+    def self.ensure_indexes
+      configuration.collections.each_pair do |key, collection|
+        collection.create_index([
+          ['key', Mongo::ASCENDING],
+          ['owner', Mongo::ASCENDING],
+          ['expires_at', Mongo::ASCENDING]
+        ])
+        collection.create_index([['ttl', Mongo::ASCENDING]],{ expireAfterSeconds: 0 })
+      end
+    end
+
+    def self.clear_expired
+      configuration.collections.each_pair do |key,collection|
+        collection.remove expires_at: { '$lt' => Time.now }
+      end
+    end
+
+    def initialize key, options = {}
+      self.configuration = Configuration.new self.class.configuration.to_hash, options
+      self.key = key
+      acquire_if_acquired
+    end
+
+    def configure options = {}, &block
+      self.configuration = Configuration.new self.configuration.to_hash, options
+      yield self.configuration if block_given?
+    end
+
+    def acquire options = {}
+      options = configuration.to_hash.merge options
+      i = 1
+      time_spent = 0
+
+      loop do
+        # If timeout has expired
+        if options[:timeout_in] && options[:timeout_in] < time_spent
+          return raise_or_false options
+
+        # If limit has expired
+        elsif options[:limit] && options[:limit] < i
+          return raise_or_false options
+
+        # If there is an existing lock
+        elsif existing_lock = find_or_insert(options)
+
+          # If the lock is owned by me
+          if existing_lock['owner'] == options[:owner]
+            self.acquired = true
+            extend_by options[:expires_after]
+            return true
+          end
+
+        # If the lock was acquired
+        else
+          self.acquired = true
+          return true
+
+        end
+
+        if options[:frequency].is_a? Proc
+          frequency = options[:frequency].call(i)
+        else
+          frequency = options[:frequency]
+        end
+        sleep frequency
+        time_spent += frequency
+        i += 1
+      end
+    end
+
+    def acquire! options = {}
+      options[:raise] = true
+      acquire options
+    end
+
+    def release options = {}
+      options = configuration.to_hash.merge options
+
+      # If the lock has already been released
+      if released?
+        return true
+
+      # If the lock has expired its as good as released
+      elsif expired?
+        self.released = true
+        self.acquired = false
+        return true
+
+      # We must have acquired the lock to release it
+      elsif !acquired?
+        if acquire options.merge(raise: false)
+          return release options
+        else
+          return raise_or_false options, NotReleasedError
+        end
+
+      else
+        self.released = true
+        self.acquired = false
+        collection.remove key: key, owner: options[:owner]
+        return true
+      end
+    end
+
+    def release! options = {}
+      options[:raise] = true
+      release options
+    end
+
+    def raise_or_false options, error = NotAcquiredError
+      raise error if options[:raise]
+      false
+    end
+
+    def find_or_insert options
+      to_expire_at = Time.now + options[:expires_after]
+      existing_lock = collection.find_and_modify({
+        query: query,
+        update: {
+          '$setOnInsert' => {
+            key: key,
+            owner: options[:owner],
+            expires_at: to_expire_at,
+            ttl: to_expire_at
+          }
+        },
+        upsert: true
+      })
+
+      if existing_lock
+        self.expires_at = existing_lock['expires_at']
+      else
+        self.expires_at = to_expire_at
+      end
+
+      existing_lock
+    end
+
+    def extend_by time, options = {}
+      options = configuration.to_hash.merge options
+
+      # Can't extend a lock that hasn't been acquired
+      if !acquired?
+        return raise_or_false options, NotExtendedError
+
+      # Can't extend a lock that has started
+      elsif expired?
+        return raise_or_false options, NotExtendedError
+
+      else
+        to_expire_at = expires_at + time
+        existing_lock = collection.find_and_modify({
+          query: query,
+          update: {
+            '$set' => {
+              key: key,
+              owner: options[:owner],
+              expires_at: to_expire_at,
+              ttl: to_expire_at
+            }
+          },
+          upsert: true
+        })
+        true
+      end
+    end
+
+    def extend options = {}
+      time = configuration.to_hash.merge(options)[:expires_after]
+      extend_by time, options
+    end
+
+    def extend_by! time, options = {}
+      options[:raise] = true
+      extend_by time, options
+    end
+
+    def extend! options = {}
+      options[:raise] = true
+      extend options
+    end
+
+    def available? options = {}
+      options = configuration.to_hash.merge options
+      existing_lock = collection.find(query).first
+      !existing_lock || existing_lock['owner'] == options[:owner]
+    end
+
+    def query
+      {
+        key: key,
+        expires_at: { '$gt' => Time.now }
+      }
+    end
+
+    def acquired?
+      !!acquired && !expired?
+    end
+
+    def expired?
+      !!(expires_at && expires_at < Time.now)
+    end
+
+    def released?
+      !!released
+    end
+
+    def acquire_if_acquired
+      if (collection.find({
+          key: key,
+          owner: configuration.owner,
+          expires_at: { '$gt' => Time.now }
+        }).count > 0)
+        self.acquired = true
+      end
+    end
+
+  end
+end