mongoid_optimistic_locking 0.0.2

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.idea
+*.iml
+.rvmrc

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in mongoid_optimistic_locking.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2012 Boxee
+
+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,57 @@
+# mongoid\_optimistic\_locking
+
+This gem helps to abstract the ["Update if Current"](http://www.mongodb.org/display/DOCS/Atomic+Operations#AtomicOperations-%22UpdateifCurrent%22) method which may be used as a replacement for [transactions in Mongo](http://docs.mongodb.org/manual/faq/developers/#how-do-i-do-transactions-and-locking-in-mongodb).
+
+The gem is an addon over [Mongoid ODM](http://mongoid.org/) and is based on [ActiveRecord's Optimistic Locking](http://api.rubyonrails.org/classes/ActiveRecord/Locking/Optimistic.html).
+
+## Compatibility
+
+So far it works with the Rails 3 and Mongoid 2.4.
+
+Created branch for edge *Mongoid 3*.
+
+## Rails 3 Installation
+
+Add the gem to your `Gemfile`:
+
+    gem 'mongoid_optimistic_locking'
+
+## Usage
+
+To use it, all you have to do is add include `Mongoid::OptimisticLocking`:
+
+    class Post
+      include Mongoid::Document
+      include Mongoid::OptimisticLocking
+
+      field :text
+    end
+
+This will add a `_lock_version` field in the document which will be incremented every time a save is called.
+Be sure to rescue `Mongoid::Errors::StaleDocument` to handle applicative logic in case the object was changed.
+
+For example:
+
+    class PostController < ApplicationController
+      ## Adds an "UPDATE: ...some text..." to an existing document
+      def add_update
+        begin
+          post = Post.find(params[:id])
+          post.text += "---UPDATE---  " + params[:more_text]
+          post.save
+        rescue Mongoid::Errors::StaleDocument
+          retry
+        end
+      end
+    end
+
+That's it!
+
+## Open sourced by
+
+[Boxee](http://www.boxee.tv)
+
+## References
+[Mongo Developer FAQ - How do I do transactions/locking?](http://docs.mongodb.org/manual/faq/developers/#how-do-i-do-transactions-and-locking-in-mongodb)
+
+[Mongo Atomic Operations - "Update if Current"](http://www.mongodb.org/display/DOCS/Atomic+Operations#AtomicOperations-%22UpdateifCurrent%22)

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/config/locales/en.yml

@@ -0,0 +1,9 @@
+en:
+  mongoid:
+    errors:
+      messages:
+        stale_document:
+          update:
+            "Attempted to update a stale document: %{klass}"
+          destroy:
+            "Attempted to destroy a stale document: %{klass}"

data/lib/mongoid/errors/stale_document.rb

@@ -0,0 +1,28 @@
+require 'mongoid/errors/mongoid_error'
+
+module Mongoid
+  module Errors
+
+    # Raised when trying to update a document that has been updated by
+    # another process.
+    #
+    # @example Create the error.
+    #   StaleDocument.new('update', document)
+    class StaleDocument < MongoidError
+
+      attr_reader :action, :document
+
+      def initialize(action, document)
+        @action = action
+        @document = document
+
+        super(
+          translate(
+            "stale_document.#{action}",
+            { :klass => document.class.name }
+          )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/lockable.rb

@@ -0,0 +1,13 @@
+module Mongoid
+
+  module Lockable
+
+    extend ActiveSupport::Concern
+
+    included do
+      ActiveSupport::Deprecation.warn 'Mongoid::Lockable is deprecated and will be removed. Use Mongoid::OptimisticLocking instead.', caller
+      include Mongoid::OptimisticLocking
+    end
+
+  end
+end

data/lib/mongoid/optimistic_locking.rb

@@ -0,0 +1,39 @@
+require 'mongoid'
+require 'mongoid/errors/stale_document'
+require 'mongoid/lockable'
+require 'mongoid/optimistic_locking/deprecated'
+require 'mongoid/optimistic_locking/lock_version'
+require 'mongoid/optimistic_locking/operations'
+require 'mongoid/optimistic_locking/threaded_with_unlocked'
+require 'mongoid/optimistic_locking/unlocked'
+require 'mongoid/optimistic_locking/version'
+
+# monkey patch Threaded
+Mongoid::Threaded.send :include, Mongoid::OptimisticLocking::ThreadedWithUnlocked
+
+# add english load path to translations
+I18n.load_path << File.expand_path('../../config/locales/en.yml', __FILE__)
+
+module Mongoid
+  # == What is Optimistic Locking
+  #
+  # See <http://api.rubyonrails.org/classes/ActiveRecord/Locking/Optimistic.html>.
+  #
+  # == Usage
+  #
+  # TODO ...
+  module OptimisticLocking
+
+    extend ActiveSupport::Concern
+
+    include Deprecated
+    include LockVersion
+    include Operations
+    include Unlocked
+
+    included do
+      field LOCKING_FIELD, :type => Integer, :default => 0
+    end
+
+  end
+end

data/lib/mongoid/optimistic_locking/deprecated.rb

@@ -0,0 +1,12 @@
+module Mongoid
+  module OptimisticLocking
+    module Deprecated
+
+      def save_optimistic!(*args)
+        ActiveSupport::Deprecation.warn 'save_optimistic! is deprecated and will be removed. Use save or save! instead', caller
+        save! *args
+      end
+
+    end
+  end
+end

data/lib/mongoid/optimistic_locking/lock_version.rb

@@ -0,0 +1,29 @@
+module Mongoid
+  module OptimisticLocking
+    module LockVersion
+
+      LOCKING_FIELD = :_lock_version
+
+      private
+
+      attr_reader :lock_version_for_selector
+
+      def set_lock_version_for_selector
+        @lock_version_for_selector = self[LOCKING_FIELD]
+        yield
+      rescue Exception
+        @lock_version_for_selector = nil
+        raise
+      end
+
+      def increment_lock_version
+        self[LOCKING_FIELD] = self[LOCKING_FIELD] ? self[LOCKING_FIELD] + 1 : 1
+        yield
+      rescue Exception
+        self[LOCKING_FIELD] = self[LOCKING_FIELD] ? self[LOCKING_FIELD] - 1 : 0
+        raise
+      end
+
+    end
+  end
+end

data/lib/mongoid/optimistic_locking/operations.rb

@@ -0,0 +1,53 @@
+module Mongoid
+  module OptimisticLocking
+    module Operations
+
+      def insert(*args)
+        return super unless optimistic_locking?
+        increment_lock_version do
+          super
+        end
+      end
+
+      def update(*args)
+        return super unless optimistic_locking?
+        set_lock_version_for_selector do
+          increment_lock_version do
+            result = super
+            unless Mongoid.database.command({:getlasterror => 1})['updatedExisting']
+              raise Mongoid::Errors::StaleDocument.new('update', self)
+            end
+            result
+          end
+        end
+      end
+
+      def remove(*args)
+        return super unless optimistic_locking?
+        set_lock_version_for_selector do
+          result = super
+          unless Mongoid.database.command({:getlasterror => 1})['updatedExisting']
+            raise Mongoid::Errors::StaleDocument.new('destroy', self)
+          end
+          result
+        end
+      end
+
+      def atomic_selector
+        result = super
+        if optimistic_locking? && lock_version_for_selector
+          key =
+            if metadata && metadata.embedded?
+              path = metadata.path(self)
+              "#{path.path}._lock_version"
+            else
+              '_lock_version'
+            end
+          result[key] = lock_version_for_selector
+        end
+        result
+      end
+
+    end
+  end
+end

data/lib/mongoid/optimistic_locking/threaded_with_unlocked.rb

@@ -0,0 +1,30 @@
+module Mongoid
+  module OptimisticLocking
+    module ThreadedWithUnlocked
+
+      extend ActiveSupport::Concern
+      
+      module ClassMethods
+
+        def optimistic_locking?
+          !unlocked
+        end
+
+        def unlocked
+          !!Thread.current["[mongoid]:unlocked"]
+        end
+
+        def unlocked=(value)
+          Thread.current["[mongoid]:unlocked"] = value
+        end
+
+        def clear_options!
+          self.unlocked = false
+          super
+        end
+
+      end
+
+    end
+  end
+end

data/lib/mongoid/optimistic_locking/unlocked.rb

@@ -0,0 +1,26 @@
+module Mongoid
+  module OptimisticLocking
+    module Unlocked
+
+      extend ActiveSupport::Concern
+
+      def unlocked
+        Threaded.unlocked = true
+        self
+      end
+
+      def optimistic_locking?
+        Threaded.optimistic_locking?
+      end
+
+      module ClassMethods
+
+        def unlocked
+          Threaded.unlocked = true
+        end
+
+      end
+
+    end
+  end
+end

data/lib/mongoid/optimistic_locking/version.rb

@@ -0,0 +1,5 @@
+module Mongoid
+  module OptimisticLocking
+    VERSION = '0.0.2'
+  end
+end

data/lib/mongoid_optimistic_locking.rb

@@ -0,0 +1 @@
+require 'mongoid/optimistic_locking'

data/mongoid_optimistic_locking.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "mongoid/optimistic_locking/version"
+
+Gem::Specification.new do |s|
+  s.name        = "mongoid_optimistic_locking"
+  s.version     = Mongoid::OptimisticLocking::VERSION
+  s.authors     = ["Alon Burg", "John Nishinaga"]
+  s.email       = ["burgalon@gmail.com", "jingoro@casa-z.org"]
+  s.homepage    = "https://github.com/burgalon/mongoid_optimistic_locking"
+  s.summary     = %q{Allows optimisitic locking for Mongoid models}
+  s.description = %q{Allows optimisitic locking for Mongoid models. See https://github.com/burgalon/mongoid_optimistic_locking}
+
+  s.add_dependency 'mongoid', '~> 2.4'
+  s.add_development_dependency 'rake', '~> 0.9.0'
+  s.add_development_dependency 'rspec', '~> 2.6'
+  s.add_development_dependency 'bson_ext', '~> 1.5'
+
+  s.rubyforge_project = "mongoid_optimistic_locking"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  # s.add_development_dependency "rspec"
+  # s.add_runtime_dependency "rest-client"
+end

data/spec/lockable_spec.rb

@@ -0,0 +1,119 @@
+require 'spec_helper'
+
+class Post
+  include Mongoid::Document
+  ::ActiveSupport::Deprecation.silence do
+    include Mongoid::Lockable
+  end
+
+  field :title
+
+  embeds_many :comments
+end
+
+class Comment
+  include Mongoid::Document
+  ::ActiveSupport::Deprecation.silence do
+    include Mongoid::Lockable
+  end
+
+  field :text
+  embedded_in :post
+end
+
+describe Mongoid::Lockable do
+
+  before { ::ActiveSupport::Deprecation.silenced = true }
+  after { ::ActiveSupport::Deprecation.silenced = false }
+
+  before :all do
+    @post = Post.create(:text => 'original-text')
+    @post._lock_version.should == 1
+  end
+
+  it "simulate a migration situation in which _lock_version did not exist" do
+    Post.update_all(:_lock_version => nil)
+    @post.reload.save_optimistic!.should == true
+  end
+
+  describe "test root documents" do
+    it "saves regularly if there's no other process changing the data in the background" do
+      @post.text = 'changed-text'
+      @post.save_optimistic!.should == true
+      @post._lock_version.should == 2
+      @post.reload
+      @post.text.should == 'changed-text'
+      @post._lock_version.should == 2
+    end
+
+    it "raises Stale exception if another process/background code updates the object" do
+      post_clone = Post.find(@post.id)
+      # the before_filter should increments the version by one, thus making the object stale
+      post_clone.text = 'changed-in-background'
+      post_clone.save
+
+      @post.text = 'changed-text'
+      expect { @post.save_optimistic! }.to raise_error(Mongoid::Errors::StaleDocument)
+
+      # Should fail again if still not refreshed
+      # i.e: test that _lock_version is decremented upon failure
+      expect { @post.save_optimistic! }.to raise_error(Mongoid::Errors::StaleDocument)
+
+      # Test StaleDocument error
+      begin
+        @post.save_optimistic!
+      rescue Mongoid::Errors::StaleDocument => e
+        e.message().should match('Post')
+      end
+
+      @post.reload
+      @post.text.should == 'changed-in-background'
+
+      post_clone.text = 'changed-in-background'
+      post_clone.save
+    end
+  end
+
+  describe "test embedded documents" do
+    before :all do
+      @post = Post.create(:text => 'original-text')
+      @comment = @post.comments.create!(:text => 'First comment')
+    end
+
+    it "saves regularly if there's no other process changing the data in the background" do
+      @comment.text = 'First comment updated!'
+      @comment.save_optimistic!.should == true
+      @comment._lock_version.should == 2
+      @comment.reload
+      @comment.text.should == 'First comment updated!'
+      @comment._lock_version.should == 2
+    end
+
+    it "raises Stale exception if another process/background code updates the object" do
+      @comment_clone = Post.find(@post.id).comments.find(@comment.id)
+      # the before_filter should increments the version by one, thus making the object stale
+      @comment_clone.text = 'changed-in-background'
+      @comment_clone.save
+
+      @comment.text = 'changed-text'
+      expect { @comment.save_optimistic! }.to raise_error(Mongoid::Errors::StaleDocument)
+
+      # Should fail again if still not refreshed
+      # i.e: test that _lock_version is decremented upon failure
+      expect { @comment.save_optimistic! }.to raise_error(Mongoid::Errors::StaleDocument)
+
+      # Test StaleDocument error
+      begin
+        @comment.save_optimistic!
+      rescue Mongoid::Errors::StaleDocument => e
+        e.message().should match('Comment')
+      end
+
+      @comment.reload
+      @comment.text.should == 'changed-in-background'
+
+      @comment_clone.text = 'changed-in-background'
+      @comment_clone.save
+    end
+  end
+end

data/spec/optimistic_locking_spec.rb

@@ -0,0 +1,107 @@
+require 'spec_helper'
+
+describe Mongoid::OptimisticLocking do
+
+  context 'without optimistic locking' do
+
+    let(:company_class) do
+      Class.new do
+        include Mongoid::Document
+        self.collection_name = 'companies' 
+        field :name
+      end
+    end
+
+    it 'should allow collisions' do
+      c1 = company_class.create!(:name => 'Acme')
+      c2 = company_class.find(c1.id)
+      c1.name = 'Biz'
+      c1.save.should == true
+      c2.name = 'Baz'
+      c2.save.should == true
+    end
+
+  end
+
+  context 'three instances of the same document' do
+
+    let(:person_class) do
+      Class.new do
+        include Mongoid::Document
+        include Mongoid::OptimisticLocking
+        self.collection_name = 'people' 
+        field :name
+      end
+    end
+
+    before do
+      @p1 = person_class.create!(:name => 'Bob')
+      @p2 = person_class.find(@p1.id)
+      @p3 = person_class.find(@p1.id)
+    end
+
+    context 'after updating the first' do
+
+      before do
+        @p1.name = 'Michael'
+        @p1.save.should == true
+      end
+
+      it 'should fail when updating the second' do
+        expect {
+          @p2.name = 'George'
+          @p2.save
+        }.to raise_error(Mongoid::Errors::StaleDocument)
+      end
+
+      it 'should succeed when updating the second without locking' do
+        @p2.name = 'George'
+        @p2.unlocked.save.should == true
+      end
+
+      it 'should succeed when updating the second without locking, ' +
+         'then fail when updating the third' do
+        @p2.name = 'George'
+        @p2.unlocked.save.should == true
+        expect {
+          @p3.name = 'Sally'
+          @p3.save
+        }.to raise_error(Mongoid::Errors::StaleDocument)
+      end
+
+      it 'should fail when destroying the second' do
+        expect {
+          @p2.destroy
+        }.to raise_error(Mongoid::Errors::StaleDocument)
+      end
+
+      it 'should succeed when destroying the second without locking' do
+        @p2.unlocked.destroy
+      end
+
+      it 'should succeed when destroying the second without locking, ' +
+         'then fail when destroying the third' do
+        @p2.unlocked.destroy
+        expect {
+          @p3.destroy
+        }.to raise_error(Mongoid::Errors::StaleDocument)
+      end
+
+    end
+
+    it 'should give a deprecation warning for #save_optimistic!' do
+      ::ActiveSupport::Deprecation.should_receive(:warn).once
+      @p1.save_optimistic!
+    end
+
+    it 'should give a deprecation warning for including Mongoid::Lockable' do
+      ::ActiveSupport::Deprecation.should_receive(:warn).once
+      Class.new do
+        include Mongoid::Document
+        include Mongoid::Lockable
+      end
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+require 'rubygems'
+require 'bundler'
+Bundler.setup
+
+require 'mongoid'
+
+Mongoid.configure do |config|
+  config.master = Mongo::Connection.new.db("mongoid_optimistic_locking_test")
+end
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+
+require 'mongoid_optimistic_locking'
+require 'rspec'

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: mongoid_optimistic_locking
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+  prerelease: 
+platform: ruby
+authors:
+- Alon Burg
+- John Nishinaga
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mongoid
+  requirement: &2161833600 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2161833600
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &2161832880 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+  type: :development
+  prerelease: false
+  version_requirements: *2161832880
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &2161832180 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :development
+  prerelease: false
+  version_requirements: *2161832180
+- !ruby/object:Gem::Dependency
+  name: bson_ext
+  requirement: &2161831560 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: *2161831560
+description: Allows optimisitic locking for Mongoid models. See https://github.com/burgalon/mongoid_optimistic_locking
+email:
+- burgalon@gmail.com
+- jingoro@casa-z.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/config/locales/en.yml
+- lib/mongoid/errors/stale_document.rb
+- lib/mongoid/lockable.rb
+- lib/mongoid/optimistic_locking.rb
+- lib/mongoid/optimistic_locking/deprecated.rb
+- lib/mongoid/optimistic_locking/lock_version.rb
+- lib/mongoid/optimistic_locking/operations.rb
+- lib/mongoid/optimistic_locking/threaded_with_unlocked.rb
+- lib/mongoid/optimistic_locking/unlocked.rb
+- lib/mongoid/optimistic_locking/version.rb
+- lib/mongoid_optimistic_locking.rb
+- mongoid_optimistic_locking.gemspec
+- spec/lockable_spec.rb
+- spec/optimistic_locking_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/burgalon/mongoid_optimistic_locking
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: mongoid_optimistic_locking
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Allows optimisitic locking for Mongoid models
+test_files:
+- spec/lockable_spec.rb
+- spec/optimistic_locking_spec.rb
+- spec/spec_helper.rb