barricade 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Envato & Pete Yandell
+
+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,98 @@
+Barricade
+=========
+
+Better locking for ActiveRecord.
+
+
+Installation
+------------
+
+    gem install barricade
+    
+Don’t forget to add it to your environment.rb or Gemfile.
+    
+
+Usage
+-----
+
+ActiveRecord provides the `lock!` method, but it's not very robust
+for anything beyond really simple locks.
+
+This plugin provides a couple of useful methods:
+
+    Post.transaction_with_locks(post, user) do
+      ...
+    end
+
+This starts a new transaction, and immediately locks all the passed
+in objects.
+
+The transaction *MUST* be the outermost transaction, not a nested
+transaction, otherwise `transaction_with_locks` will raise a
+`Barricade::LockMustBeOutermostTransaction` exception.
+
+It sorts the locked objects before locking, to help avoid deadlocks. If a
+deadlock does occur, it retries the locks and continues with the
+transaction.
+
+Within the transaction block, you can raise a
+`Barricade::RetryTransaction` exception to retry the transaction
+from the beginning and make sure all the locks are in place.
+
+You can double-check that you have a lock on an object by calling
+its `confirm_locked!` method. This raises a `Barricade::LockNotHeld`
+exception if you don't have the lock.
+
+It's safe to re-acquire a lock inside an existing transaction, so
+the following will work:
+
+    Post.transaction_with_locks(post) do
+      Post.transaction_with_locks(post) do
+        ...
+      end
+    end
+
+but this will raise an exception:
+
+    Post.transaction_with_locks(post) do
+      Post.transaction_with_locks(user) do
+        ...
+      end
+    end
+     
+
+Background
+----------
+
+There are a few things you need to know to understand the difficulty of
+using ActiveRecord for locking.
+
+InnoDB is pretty good at detected and flagging deadlocks.
+(See [Deadlock Detection and Rollback](http://dev.mysql.com/doc/refman/5.1/en/innodb-deadlock-detection.html))
+
+Any attempt to grab an exclusive lock on a record can result in a
+deadlock, and a deadlock causes a couple of things to happen:
+
+1. MySQL will roll back the outermost current transaction.
+
+2. ActiveRecord will throw a `ActiveRecord::StatementInvalid` exception
+
+The end result is that your ActiveRecord objects may end up out of sync
+with their corresponding database records.
+
+Barricade avoids this by doing all the locking at the very start of
+the transaction. A deadlock when grabbing the locks will cause an
+immediate retry, before any code that has side effects can be run.
+
+The downside is that you have to do your locking in the outermost
+transaction, which can make it difficult to encapsulate logic in
+your model without placing restrictions on where your model can be
+called from.
+
+
+Credits
+-------
+
+Copyright © 2010 [Envato](http://envato.com).
+Initially developed by [Pete Yandell](http://notahat.com).
+Released under an MIT license.

data/init.rb

@@ -0,0 +1 @@
+require 'barricade'

data/lib/barricade.rb

@@ -0,0 +1,99 @@
+# Methods defined here are included as instance methods on ActiveRecord::Base.
+module Barricade
+
+  def self.configuration #:nodoc:
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  class Configuration
+    # Set this in your tests if you're using transactional_fixtures, so
+    # Barricade will know not to complain about a containing
+    # transaction when you call transaction_with_locks.
+    attr_accessor :running_inside_transactional_fixtures
+
+    def initialize
+      @running_inside_transactional_fixtures = false
+    end
+  end
+
+  def self.included(base) #:nodoc:
+    base.extend(ClassMethods)
+  end
+
+  # Confirms that this object has been locked in an enclosing call to
+  # transaction_with_locks. Raises LockNotHeld if the lock isn't held.
+  def confirm_locked!
+    raise LockNotHeld unless ActiveRecord::Base.locked_objects.include?(self)
+  end
+   
+  # Methods defined here are included as class methods on ActiveRecord::Base.
+  module ClassMethods
+    # Perform a transaction with the given ActiveRecord objects locked.
+    #
+    # e.g.
+    #   Post.transaction_with_locks(post) do
+    #     post.comments.create!(...)
+    #   end
+    def transaction_with_locks(*objects)
+      objects = objects.flatten.compact
+      return if objects.all? {|object| ActiveRecord::Base.locked_objects.include?(object) }
+
+      minimum_transaction_level = Barricade.configuration.running_inside_transactional_fixtures ? 1 : 0
+      raise LockMustBeOutermostTransaction unless connection.open_transactions == minimum_transaction_level
+    
+      objects.sort_by {|object| [object.class.name, object.send(object.class.primary_key)] }
+      begin
+        ActiveRecord::Base.locked_objects = nil
+        transaction do
+          begin
+            objects.each(&:lock!)
+            ActiveRecord::Base.locked_objects = objects
+          rescue ActiveRecord::StatementInvalid => exception
+            if exception.message =~ /Deadlock/
+              raise RetryTransaction
+            else
+              raise
+            end
+          end
+
+          yield
+        end
+      rescue RetryTransaction
+        retry
+      ensure
+        ActiveRecord::Base.locked_objects = nil
+      end
+    end
+
+    def locked_objects=(objects) #:nodoc:
+      @locked_objects = objects
+    end
+
+    def locked_objects #:nodoc:
+      @locked_objects || []
+    end
+  end
+
+  # Raised when transaction_with_locks is called inside an existing transaction.
+  class LockMustBeOutermostTransaction < RuntimeError
+  end
+
+  # Raised when confirm_locked! is called on an object that's not locked.
+  class LockNotHeld < RuntimeError
+  end
+
+  # Raise this to retry the current transaction from the beginning.
+  class RetryTransaction < RuntimeError
+  end
+
+end
+
+module ActiveRecord #:nodoc:
+  class Base #:nodoc:#
+    include Barricade
+  end
+end

data/spec/barricade_spec.rb

@@ -0,0 +1,68 @@
+require File.dirname(__FILE__) + '/spec_helper'
+require 'active_record'
+require 'barricade'
+
+describe Barricade do
+
+  before(:suite) do
+    ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/spec.log")
+    ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => ":memory:")
+    load(File.dirname(__FILE__) + "/schema.rb")
+  end
+
+  class Post < ActiveRecord::Base
+  end
+
+  before(:all) do
+    @post = Post.create!
+    @another_post = Post.create!
+  end
+
+  it "should not allow locking inside a transaction" do
+    Post.transaction do
+      lambda do 
+        Post.transaction_with_locks(@post) { }
+      end.should raise_error(Barricade::LockMustBeOutermostTransaction)
+    end
+  end
+
+  it "should not allow locking additional objects inside an existing locked transaction" do
+    Post.transaction_with_locks(@post) do
+      lambda do 
+        Post.transaction_with_locks(@another_post) { }
+      end.should raise_error(Barricade::LockMustBeOutermostTransaction)
+    end
+  end
+
+  it "should allow locking an object if a lock is already set on that object" do
+    Post.transaction_with_locks(@post) do
+      lambda do 
+        Post.transaction_with_locks(@post) { }
+      end.should_not raise_error
+    end
+  end
+
+  it "should mark an object as locked inside a transaction with locks" do
+    lambda { @post.confirm_locked! }.should raise_error(Barricade::LockNotHeld)
+    Post.transaction_with_locks(@post) do
+      lambda { @post.confirm_locked! }.should_not raise_error
+    end
+    lambda { @post.confirm_locked! }.should raise_error(Barricade::LockNotHeld)
+  end
+
+  it "should flatten and compact the list of objects to be locked" do
+    Post.transaction_with_locks(@post, @another_post) do
+      ActiveRecord::Base.locked_objects.should == [@post, @another_post]
+    end
+    Post.transaction_with_locks([@post, @another_post]) do
+      ActiveRecord::Base.locked_objects.should == [@post, @another_post]
+    end
+    Post.transaction_with_locks([@post, [@another_post]]) do
+      ActiveRecord::Base.locked_objects.should == [@post, @another_post]
+    end
+    Post.transaction_with_locks([@post, nil, @another_post]) do
+      ActiveRecord::Base.locked_objects.should == [@post, @another_post]
+    end
+  end
+
+end

data/spec/schema.rb

@@ -0,0 +1,7 @@
+ActiveRecord::Schema.define(:version => 0) do
+  create_table :posts, :force => true do |t|
+    t.column :title, :string
+    t.column :body, :text
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'rubygems'
+require 'test/unit'
+require 'spec'
+
+Spec::Runner.configure do |config|
+end
+

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: barricade
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Pete Yandell
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-22 00:00:00 +10:00
+default_executable: 
+dependencies: []
+
+description: Makes ActiveRecord locking more secure and robust
+email: pete@envato.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- README.md
+- init.rb
+- lib/barricade.rb
+- spec/barricade_spec.rb
+- spec/schema.rb
+- spec/spec_helper.rb
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/envato/barricade
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Better ActiveRecord locking
+test_files: 
+- spec/barricade_spec.rb
+- spec/schema.rb
+- spec/spec_helper.rb