positioning 0.1.7 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3287b3ffda224e17c32b5601cc2f14aba284bcac50d7627be46300f1c7473521
-  data.tar.gz: 9027f931d4dc6781241cd80faacf056d320307e94fb0a1ded2e8563bc7d86b59
+  metadata.gz: ea25e9b2c25e0268da3078ed8b9d9d992aa4d4e67020f5ae317e2cdf9fa5fd10
+  data.tar.gz: ac3996e32d7b6936a9d97d486bd63cab73c371eed718bec034bb420c262f36c1
 SHA512:
-  metadata.gz: 8f0a3353940e24c88f89835fee413eef989a67e3ef1a984d8cba2611d377be6a68f0743568090cb5a58da2f6c8f2eb17d15cfa2f4880b4f0b209f4ad582b176f
-  data.tar.gz: 975fa2efc49eacb1dc5a96de826ccc9e6db72f8adb82a4d44f72dff57581cd551581c77458c40b06686c90232aebff127006503369cee3faed0ad704160e8c21
+  metadata.gz: 2f0fd43a324b0629b689658b26ecec629e8103823c2a275ee24c303c2583a91b09e9599a09d5759e5236ce9cc888e7320bff5c04771ab60b2c697340bbbf1b41
+  data.tar.gz: b752f5801180797144f8bce5ea5437495769d95522fc67213a89d953ca71fd4212c4ff08240b42c30d554d847fa56611cf84e743869d682a1d52276fec074ae6

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.2.0] - 2024-03-12
+
+- Add an Advisory Lock to ensure isolation for the entirety of the create, update, and destroy cycles.
+- Add SQLite Advisory Lock support using a file lock.
+
 ## [0.1.7] - 2024-03-06
 
 - Seperated the Concern that is included into ActiveRecord::Base into its own submodule so that Mechanisms isn't also included.

data/README.md

@@ -39,11 +39,11 @@ The Positioning gem uses `0` and negative integers to rearrange the lists it man
 To declare that your model should keep track of the position of its records you can use the `positioned` method. Here are some examples:
 
 ```ruby
-# The scope is global (all records will belong to the same list) and the databse column
+# The scope is global (all records will belong to the same list) and the database column
 # is 'positioned'
 positioned
 
-# The scope is on the belongs_to relationship 'list' and the databse column is 'positioned'
+# The scope is on the belongs_to relationship 'list' and the database column is 'positioned'
 # We check if the scope is a belongs_to relationship and use its declared foreign_key as
 # the scope value. In this case it would be 'list_id' since we haven't overridden the
 # default foreign key.
@@ -151,21 +151,21 @@ other_item.id # => 11
 item.update position: {after: 11}
 ```
 
-##### Relative Positining in Forms
+##### Relative Positioning in Forms
 
-It can be tricky to provide the hash forms of relative positining using Rails form helpers, but it is possible. We've declared a special `Struct` for you to use for this purpose.
+It can be tricky to provide the hash forms of relative positioning using Rails form helpers, but it is possible. We've declared a special `Struct` for you to use for this purpose.
 
-Firstly you need to allow nested Strong Parameters for the `position` column like so:
+Firstly you need to allow both scalar and nested Strong Parameters for the `position` column like so:
 
 ```ruby
 def item_params
-  params.require(:item).permit :name, position: [:before]
+  params.require(:item).permit :name, :position, { position: :before }
 end
 ```
 
 In the example above we're always declaring what item (by its `id`) we want to position our item **before**. You could change this to `:after` if you'd rather.
 
-Next, in your `new` method you may wish to intialise the `position` column with a value supplied by incoming parameters:
+Next, in your `new` method you may wish to initialise the `position` column with a value supplied by incoming parameters:
 
 ```ruby
 def new
@@ -177,7 +177,7 @@ You can now just pass the `before` parameter (the `id` of the item you want to a
 
 In the form itself, so that your intended position survives a failed `create` attempt and form redisplay you can declare the `position` value like so:
 
-```erb
+```
   <% if item.new_record? %>
     <%= form.fields :position, model: Positioning::RelativePosition.new(item.position_before_type_cast) do |fields| %>
       <%= fields.hidden_field :before %>
@@ -225,13 +225,31 @@ item.update list: other_list, position: {after: 11}
 
 It's important to note that in the examples above, `other_item` must already belong to the `other_list` scope.
 
+## Concurrency
+
+The queries that this gem runs, especially those that seek the next position integer available are vulnerable to race conditions. To this end, we've introduced an Advisory Lock to ensure that our model callbacks that determine and assign positions run sequentially. In short, an advisory lock prevents more than one process from running a particular block of code at the same time. The lock occurs in the database (or in the case of SQLite, on the filesystem), so as long as all of your processes are using the same database, the lock will prevent multiple positioning callbacks from executing on the same table and positioning column combination at the same time.
+
+If you are using SQLite, you'll want to add the following line to your database.yml file in order to increase the exclusivity of Active Record's default write transactions:
+
+```yaml
+default_transaction_mode: EXCLUSIVE
+```
+
+You may also want to try `IMMEDIATE` as a less aggressive alternative.
+
+You're encouraged to review the Advisory Lock code to ensure it fits with your environment:
+
+https://github.com/brendon/positioning/blob/main/lib/positioning/advisory_lock.rb
+
+If you have any concerns or improvements please file a GitHub issue.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 This gem is tested against SQLite, PostgreSQL and MySQL. The default database for testing is MySQL. You can target other databases by prepending the environment variable `DB=sqlite` or `DB=postgresql` before `rake test`. For example: `DB=sqlite rake test`.
 
-The PostgreSQL and MySQL environments are configured under `test/support/database.yml`. You can edit this file, or preferrably adjust your environment to support passwordless socket based connections to these two database engines. You'll also need to manually create a database named `positioning_test` in each.
+The PostgreSQL and MySQL environments are configured under `test/support/database.yml`. You can edit this file, or preferably adjust your environment to support password-less socket based connections to these two database engines. You'll also need to manually create a database named `positioning_test` in each.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/lib/positioning/advisory_lock.rb

@@ -0,0 +1,82 @@
+require "fileutils"
+require "openssl"
+
+module Positioning
+  class AdvisoryLock
+    Adapter = Struct.new(:initialise, :aquire, :release, keyword_init: true)
+
+    attr_reader :base_class
+
+    def initialize(base_class, column)
+      @base_class = base_class
+      @column = column.to_s
+
+      @adapters = {
+        "Mysql2" => Adapter.new(
+          initialise: -> {},
+          aquire: -> { connection.execute "SELECT GET_LOCK(#{connection.quote(lock_name)}, -1)" },
+          release: -> { connection.execute "SELECT RELEASE_LOCK(#{connection.quote(lock_name)})" }
+        ),
+        "PostgreSQL" => Adapter.new(
+          initialise: -> {},
+          aquire: -> { connection.execute "SELECT pg_advisory_lock(#{lock_name.hex & 0x7FFFFFFFFFFFFFFF})" },
+          release: -> { connection.execute "SELECT pg_advisory_unlock(#{lock_name.hex & 0x7FFFFFFFFFFFFFFF})" }
+        ),
+        "SQLite" => Adapter.new(
+          initialise: -> {
+            FileUtils.mkdir_p "#{Dir.pwd}/tmp"
+            filename = "#{Dir.pwd}/tmp/#{lock_name}.lock"
+            @file ||= File.open filename, File::RDWR | File::CREAT, 0o644
+          },
+          aquire: -> {
+            @file.flock File::LOCK_EX
+          },
+          release: -> {
+            @file.flock File::LOCK_UN
+          }
+        )
+      }
+
+      @adapters.default = Adapter.new(initialise: -> {}, aquire: -> {}, release: -> {})
+
+      adapter.initialise.call
+    end
+
+    def aquire(record)
+      adapter.aquire.call
+    end
+
+    def release(record)
+      adapter.release.call
+    end
+
+    alias_method :before_create, :aquire
+    alias_method :before_update, :aquire
+    alias_method :before_destroy, :aquire
+    alias_method :after_commit, :release
+    alias_method :after_rollback, :release
+
+    private
+
+    def connection
+      base_class.connection
+    end
+
+    def adapter_name
+      connection.adapter_name
+    end
+
+    def adapter
+      @adapters[adapter_name]
+    end
+
+    def lock_name
+      lock_name = ["positioning"]
+      lock_name << connection.current_database if connection.respond_to?(:current_database)
+      lock_name << base_class.table_name
+      lock_name << @column
+
+      OpenSSL::Digest::MD5.hexdigest(lock_name.join("."))[0...32]
+    end
+  end
+end

data/lib/positioning/version.rb

@@ -1,3 +1,3 @@
 module Positioning
-  VERSION = "0.1.7"
+  VERSION = "0.2.0"
 end

data/lib/positioning.rb

@@ -1,4 +1,5 @@
 require_relative "positioning/version"
+require_relative "positioning/advisory_lock"
 require_relative "positioning/mechanisms"
 
 require "active_support/concern"
@@ -42,9 +43,18 @@ module Positioning
             super(position)
           end
 
+          advisory_lock = AdvisoryLock.new(base_class, column)
+
+          before_create advisory_lock
+          before_update advisory_lock
+          before_destroy advisory_lock
+
           before_create { Mechanisms.new(self, column).create_position }
           before_update { Mechanisms.new(self, column).update_position }
           after_destroy { Mechanisms.new(self, column).destroy_position }
+
+          after_commit advisory_lock
+          after_rollback advisory_lock
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: positioning
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.2.0
 platform: ruby
 authors:
 - Brendon Muir
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-05 00:00:00.000000000 Z
+date: 2024-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -122,6 +122,7 @@ files:
 - README.md
 - Rakefile
 - lib/positioning.rb
+- lib/positioning/advisory_lock.rb
 - lib/positioning/mechanisms.rb
 - lib/positioning/version.rb
 - positioning.gemspec