with_transactional_lock 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 39e6b2f7021e9656666cecc940c89da9b7e8152b
+  data.tar.gz: aa13d311218556caa23e1ea7f8212f6cfc920d55
+SHA512:
+  metadata.gz: 478fd8a135e213bc74a9b1bd3d446a8091761685b19b1936bc129bafe9491dd9d8bc6d0b99ad412bedc314b3aaebfdba042c5a7aaa7c27e3b2d2201dde556aca
+  data.tar.gz: adc45942dd45574a4b6a1a1f9b14df677b3c9f350dccdd2bf82d3a4ee388e526572c6c8f19bbc50e0f0c1027ecece4407eaf008f8bebc5cbcefec6a17739869a

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016-2018 Betterment
+
+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,125 @@
+# with_transactional_lock
+
+[![Build Status](https://travis-ci.com/Betterment/with_transactional_lock.svg?token=6b6DErRMUHX47kEoBZ3t&branch=master)](https://travis-ci.com/Betterment/with_transactional_lock)
+
+A simple extension to ActiveRecord for performing advisory locking on
+MySQL and PostgreSQL.
+
+An advisory lock is a database-level mutex that can be used to prevent
+concurrent access to a shared resource or to prevent two workers from
+performing the same process concurrently.
+
+This gem is different from other advisory locking gems because it
+uses advisory transaction locks instead of advisory session locks. 
+
+## Why transactional?
+
+At Betterment correctness is paramount. As such, we chose to use
+transaction-level locks because we find them to be more trustworthy for
+our production use.
+
+Some types of advisory locks can be held for the lifetime of a database
+session. In a typical database connection pooling configuration, like
+that of ActiveRecord, a connection and its associated session are not
+reset when the connection is returned to the pool. In that case, if you
+do not properly release a session-level lock, it will leak and become
+effectively unreleasable. In our Betterment production systems, that
+type of risk is unacceptable. Fortunately, because ActiveRecord
+doesn't leak open transactions back into the connection pool, we can
+use transactional locks as our safety device rather than becoming
+familiar with the nuances necessary to be confident that we are
+preventing leaks.
+
+Additionally, application developers tend to think about discrete units
+of database work in terms of transactions. By leveraging the transaction
+boundary, we ensure the advisory lock is released at the earliest
+possible moment that it can be and no sooner. 
+
+## Lock acquisition efficiency & fairness
+
+Some libraries providing advisory locking use try-lock semantics. This
+library uses a blocking strategy for lock acquisition. It will wait
+until the lock can be acquired instead of immediately returning false
+and forcing the application layer to manage retry behavior.
+Additionally, by waiting in line (in the database) for locks that cannot
+be immediately acquired, you get fairness in the acquisition sequence.
+
+Notably, this library performs lock-waiting in the database rather than
+using `Timeout.timeout`. That means that the waiting is bounded by your
+database timeout rather than a library-specific option. We see this as a
+strength of the library. In practice, we have found that if there is a
+chance of contention that you can't afford to wait for, you should
+perform the operation that requires the lock asynchronously and/or
+reduce the time spent in your critical section so that you can afford to
+wait.
+
+In contrast, when using a try-based strategy your ability to acquire a
+lock can get worse at higher levels of concurrency. You may spend more
+time spinning in application code issuing requests for a lock instead of
+waiting on I/O (possibly allowing another thread to use the CPU).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+``` ruby
+gem 'with_transactional_lock'
+```
+
+And then bundle install:
+
+```
+$ bundle install
+```
+
+And then if you're using MySQL, you will need to run the installer:
+
+```
+$ rails g with_transactional_lock:install
+```
+
+This will create a migration that will add an
+`transactional_advisory_locks` table to your database.
+
+## Usage
+
+Because transactional locks are meaningless outside of the context of a
+transaction, we provide an interface that wraps your work in a
+transaction and acquires the lock.
+
+```ruby
+ActiveRecord::Base.with_transactional_lock('name_of_a_resource') do
+  # do something critical in here
+  # this block is already inside a transaction
+end
+```
+
+This call will attempt to acquire an exclusive lock using the provided 
+lock name. It will wait indefinitely for that lock -- or at least as
+long as your database connection timeout is willing to allow. Once the
+lock is acquired you will have exclusive ownership of the advisory lock
+with the name that you provided. Your block is free to execute its
+critical work. Upon completion of your transaction, the lock will be 
+released.
+
+## Supported databases
+
+### PostgreSQL
+
+PostgreSQL has first-class support for transactional advisory locks via
+`pg_advisory_xact_lock`. This is an exclusive lock that is held for the
+duration of a given transaction and automatically released upon
+transaction commit.
+
+### MySQL
+
+MySQL does not have built-in support for transactional advisory locks.
+So, MySQL gets a special treatment. We emulate the behavior of PostgreSQL
+using a special `transactional_advisory_locks` table with a unique index 
+on the `lock_id` column. This allows us to provide the same transactional 
+and mutual exclusivity guarantees as PostgreSQL. The trade-off is that 
+you need to add another table to your database.
+
+## License
+
+Any contributions made to this project are covered under the MIT License, found [here](LICENSE)

data/Rakefile

@@ -0,0 +1,41 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'WithTransactionalLock'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+load 'rails/tasks/statistics.rake'
+
+Bundler::GemHelper.install_tasks
+
+if Rails.env.development? || Rails.env.test?
+  if defined? Dummy
+    require 'rspec/core'
+    require 'rspec/core/rake_task'
+    require 'rubocop/rake_task'
+
+    RuboCop::RakeTask.new
+    RSpec::Core::RakeTask.new(:spec)
+
+    task(:default).clear
+    if ENV['APPRAISAL_INITIALIZED'] || ENV['TRAVIS']
+      task default: %i(rubocop spec)
+    else
+      require 'appraisal'
+      Appraisal::Task.new
+      task default: :appraisal
+    end
+  end
+end

data/lib/generators/with_transactional_lock/install/install_generator.rb

@@ -0,0 +1,34 @@
+require 'rails/generators/base'
+require 'rails/generators/active_record'
+
+module WithTransactionalLock
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path('../templates', __FILE__)
+
+      def show_readme
+        readme 'README'
+      end
+
+      def create_with_transactional_lock_migration
+        if mysql?
+          migration_template(
+            'db/migrate/create_transactional_advisory_locks.rb',
+            'db/migrate/create_transactional_advisory_locks.rb'
+          )
+        end
+      end
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      private
+
+      def mysql?
+        ActiveRecord::Base.connection.adapter_name.downcase =~ /mysql/
+      end
+    end
+  end
+end

data/lib/generators/with_transactional_lock/install/templates/README

@@ -0,0 +1,8 @@
+*******************************************************************************
+
+If you're using MySql, then run `rake db:migrate` to setup the `transactional_advisory_locks`
+table.
+
+If you're using Postgresql, then you're all set!
+
+*******************************************************************************

data/lib/generators/with_transactional_lock/install/templates/db/migrate/create_transactional_advisory_locks.rb

@@ -0,0 +1,8 @@
+class CreateTransactionalAdvisoryLocks < ActiveRecord::Migration
+  def change
+    create_table :transactional_advisory_locks, id: false do |t|
+      t.integer :lock_id, null: false, limit: 8
+    end
+    add_index(:transactional_advisory_locks, :lock_id, unique: true, name: 'index_transactional_advisory_locks_on_lock_id')
+  end
+end

data/lib/tasks/with_transactional_lock_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :with_transactional_lock do
+#   # Task goes here
+# end

data/lib/with_transactional_lock.rb

@@ -0,0 +1,11 @@
+require "with_transactional_lock/engine"
+
+module WithTransactionalLock
+  extend ActiveSupport::Autoload
+  autoload :Mixin
+  autoload :MySqlHelper
+end
+
+ActiveSupport.on_load :active_record do
+  ActiveRecord::Base.send :include, WithTransactionalLock::Mixin
+end

data/lib/with_transactional_lock/engine.rb

@@ -0,0 +1,4 @@
+module WithTransactionalLock
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/with_transactional_lock/mixin.rb

@@ -0,0 +1,72 @@
+require 'active_support/concern'
+
+module WithTransactionalLock
+  module Mixin
+    extend ActiveSupport::Concern
+    delegate :with_transactional_lock, to: :class
+
+    module ClassMethods
+      def with_transactional_lock(lock_name, &block)
+        _advisory_lock_class.new(connection, lock_name).yield_with_lock(&block)
+      end
+
+      private
+
+      def _advisory_lock_class
+        @_advisory_lock_class ||= AdvisoryLockClassLocator.locate(connection)
+      end
+    end
+
+    module AdvisoryLockClassLocator
+      def self.locate(connection)
+        adapter = connection.adapter_name.downcase.to_sym
+        case adapter
+          when :mysql, :mysql2
+            MySqlAdvisoryLock
+          when :postgresql
+            PostgresAdvisoryLock
+          else
+            raise "adapter not supported: #{adapter}"
+        end
+      end
+    end
+
+    class AdvisoryLockBase
+      attr_reader :connection, :lock_name
+
+      def initialize(connection, lock_name)
+        @connection = connection
+        @lock_name = lock_name
+      end
+
+      def yield_with_lock
+        connection.transaction do
+          acquire_lock
+          yield
+        end
+      end
+
+      private
+
+      def db_lock_name
+        @db_lock_name ||= Digest::SHA256.digest(lock_name)[0, 8].unpack('q').first
+      end
+    end
+
+    class MySqlAdvisoryLock < AdvisoryLockBase
+      private
+
+      def acquire_lock
+        connection.execute("insert into transactional_advisory_locks values (#{connection.quote(db_lock_name)}) on duplicate key update lock_id = lock_id")
+      end
+    end
+
+    class PostgresAdvisoryLock < AdvisoryLockBase
+      private
+
+      def acquire_lock
+        connection.execute("select pg_advisory_xact_lock(#{connection.quote(db_lock_name)})")
+      end
+    end
+  end
+end

data/lib/with_transactional_lock/my_sql_helper.rb

@@ -0,0 +1,13 @@
+module WithTransactionalLock
+  class MySqlHelper
+    def self.cleanup(klass = ActiveRecord::Base)
+      klass.connection_pool.with_connection do |conn|
+        target_count = conn.select_value('select count(1) from transactional_advisory_locks')
+        count = 0
+        until count >= target_count
+          count += conn.delete('delete from transactional_advisory_locks limit 1000')
+        end
+      end
+    end
+  end
+end

data/lib/with_transactional_lock/version.rb

@@ -0,0 +1,3 @@
+module WithTransactionalLock
+  VERSION = "1.0.0"
+end

metadata

@@ -0,0 +1,174 @@
+--- !ruby/object:Gem::Specification
+name: with_transactional_lock
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Sam Moore
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-05-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+- !ruby/object:Gem::Dependency
+  name: database_cleaner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mime-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rspec-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-betterment
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: travis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Advisory locking support for MySQL and Postgresql done right.
+email:
+- sam@betterment.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/generators/with_transactional_lock/install/install_generator.rb
+- lib/generators/with_transactional_lock/install/templates/README
+- lib/generators/with_transactional_lock/install/templates/db/migrate/create_transactional_advisory_locks.rb
+- lib/tasks/with_transactional_lock_tasks.rake
+- lib/with_transactional_lock.rb
+- lib/with_transactional_lock/engine.rb
+- lib/with_transactional_lock/mixin.rb
+- lib/with_transactional_lock/my_sql_helper.rb
+- lib/with_transactional_lock/version.rb
+homepage: https://github.com/Betterment/with_transactional_lock
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Transactional advisory locks for ActiveRecord
+test_files: []