positioning 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fa6907a0507b7978c58578596c4e6ca16b7e334eb98b3fa42cba47a0d0b89b5
-  data.tar.gz: ed8f3126f69cb0f8780244a05d48e46abd0b64468ad47838f0d5827b4fa943ff
+  metadata.gz: ea25e9b2c25e0268da3078ed8b9d9d992aa4d4e67020f5ae317e2cdf9fa5fd10
+  data.tar.gz: ac3996e32d7b6936a9d97d486bd63cab73c371eed718bec034bb420c262f36c1
 SHA512:
-  metadata.gz: 5d35b26bf717252dc30d828b2fff2b5b36c82ccd5b33d5480798cc57e38bacf9434120d2a478d448998c368286272a9dc2604cb8d3ebd071da0a55c8fa4ad5ba
-  data.tar.gz: 3b9c21bb1a3fe42c0799ffe6e991b29f7c17fd4efec8ff3b159afa41cd8a6b8b1e975e47c8e69e22dfd673352b105f2c55d85887a07d90e528b2cd0c54b3a318
+  metadata.gz: 2f0fd43a324b0629b689658b26ecec629e8103823c2a275ee24c303c2583a91b09e9599a09d5759e5236ce9cc888e7320bff5c04771ab60b2c697340bbbf1b41
+  data.tar.gz: b752f5801180797144f8bce5ea5437495769d95522fc67213a89d953ca71fd4212c4ff08240b42c30d554d847fa56611cf84e743869d682a1d52276fec074ae6

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [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.
+- Added the RelativePosition Struct and documentation to make it easier to supply relative positions via form helpers.
+
 ## [0.1.6] - 2024-03-05
 
 - Allow the position to be passed as a JSON object so that we can pass in complex positions from the browser more easily.

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.
@@ -82,11 +82,13 @@ If you don't provide a position when creating a record, your record will be adde
 
 To assign a specific position when creating or updating a record you can simply declare a specific value for the database column tracking the position of records (by default this is `position`). The valid options for this column are:
 
-* A specific integer value. Values are automatically clamped to between `1` and the next available position at the end of the list (inclusive). You should use explicit position values as a last resort, instead you can use:
-* `:first` places the record at the start of the list.
-* `:last` places the record at the end of the list.
-* `nil` also places the record at the end of the list.
-* `before:` and `after:` allow you to define the position relative to other records in the list. You can define the relative record by its primary key (usually `id`) or by providing the record itself. You can also provide `nil` in which case the item will be placed at the start or end of the list (see below).
+* A specific integer value as an `Integer` or a `String`. Values are automatically clamped to between `1` and the next available position at the end of the list (inclusive). You should use explicit position values as a last resort, instead you can use:
+* `:first` or `"first"` places the record at the start of the list.
+* `:last` or `"last"` places the record at the end of the list.
+* `nil` and `""` also places the record at the end of the list.
+* `before:` and `after:` allow you to define the position relative to other records in the list. You can define the relative record by its primary key (usually `id`) or by providing the record itself. You can also provide `nil` or `""` in which case the item will be placed at the start or end of the list (see below).
+
+**You can provide the position value as a JSON string and it will be decoded first. This could be useful if you have no other way to provide `before:` or `after:` as a hash (e.g. `"{\"after\":33}"`). See below for a technique to provide `before:` and `after:` using form helpers.**
 
 Position parameters can be strings or symbols, so you can provide them from the browser.
 
@@ -149,6 +151,42 @@ other_item.id # => 11
 item.update position: {after: 11}
 ```
 
+##### Relative Positioning in Forms
+
+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 both scalar and nested Strong Parameters for the `position` column like so:
+
+```ruby
+def item_params
+  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 initialise the `position` column with a value supplied by incoming parameters:
+
+```ruby
+def new
+  item.position = { before: params[:before] }
+end
+```
+
+You can now just pass the `before` parameter (the `id` of the item you want to add this record before) via the URL to the `new` action. For example: `items/new?before=22`.
+
+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:
+
+```
+  <% if item.new_record? %>
+    <%= form.fields :position, model: Positioning::RelativePosition.new(item.position_before_type_cast) do |fields| %>
+      <%= fields.hidden_field :before %>
+    <% end %>
+  <% end %>
+```
+
+The key part here is `Positioning::RelativePosition.new(item.position_before_type_cast)`. `Positioning::RelativePosition` is a `Struct` that can take `before` and `after` as parameters. You should only provide one or the other. Because `position` is an `Integer` column, the hash structure is obliterated when it is assigned but we can still access it with `position_before_type_cast`. Remember to adjust the method if your position column has a different name (e.g. `category_position_before_type_cast`). The `Struct` provides the correct methods for `fields` to display the nested value.
+
 #### Destroying
 
 When a record is destroyed, the positions of relative items in the scope will be shuffled to close the gap left by the destroyed record. If we detect that records are being destroyed via a scope dependency (e.g. `has_many :items, dependent: :destroy`) then we skip closing the gaps because all records in the scope will eventually be destroyed anyway.
@@ -187,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.6"
+  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"
@@ -7,46 +8,59 @@ require "active_support/lazy_load_hooks"
 module Positioning
   class Error < StandardError; end
 
-  extend ActiveSupport::Concern
+  RelativePosition = Struct.new(:before, :after, keyword_init: true)
 
-  class_methods do
-    def positioning_columns
-      @positioning_columns ||= {}
-    end
+  module Behaviour
+    extend ActiveSupport::Concern
 
-    def positioned(on: [], column: :position)
-      unless base_class?
-        raise Error.new "can't be called on an abstract class or STI subclass."
+    class_methods do
+      def positioning_columns
+        @positioning_columns ||= {}
       end
 
-      column = column.to_sym
+      def positioned(on: [], column: :position)
+        unless base_class?
+          raise Error.new "can't be called on an abstract class or STI subclass."
+        end
 
-      if positioning_columns.key? column
-        raise Error.new "The column `#{column}` has already been used by the scope `#{positioning_columns[column]}`."
-      else
-        positioning_columns[column] = Array.wrap(on).map do |scope_component|
-          scope_component = scope_component.to_s
-          reflection = reflections[scope_component]
+        column = column.to_sym
 
-          (reflection && reflection.belongs_to?) ? reflection.foreign_key : scope_component
-        end
+        if positioning_columns.key? column
+          raise Error.new "The column `#{column}` has already been used by the scope `#{positioning_columns[column]}`."
+        else
+          positioning_columns[column] = Array.wrap(on).map do |scope_component|
+            scope_component = scope_component.to_s
+            reflection = reflections[scope_component]
 
-        define_method(:"prior_#{column}") { Mechanisms.new(self, column).prior }
-        define_method(:"subsequent_#{column}") { Mechanisms.new(self, column).subsequent }
+            (reflection && reflection.belongs_to?) ? reflection.foreign_key : scope_component
+          end
 
-        redefine_method(:"#{column}=") do |position|
-          send :"#{column}_will_change!"
-          super(position)
-        end
+          define_method(:"prior_#{column}") { Mechanisms.new(self, column).prior }
+          define_method(:"subsequent_#{column}") { Mechanisms.new(self, column).subsequent }
+
+          redefine_method(:"#{column}=") do |position|
+            send :"#{column}_will_change!"
+            super(position)
+          end
 
-        before_create { Mechanisms.new(self, column).create_position }
-        before_update { Mechanisms.new(self, column).update_position }
-        after_destroy { Mechanisms.new(self, column).destroy_position }
+          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
   end
 end
 
 ActiveSupport.on_load :active_record do
-  ActiveRecord::Base.send :include, Positioning
+  ActiveRecord::Base.send :include, Positioning::Behaviour
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: positioning
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  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