positioning 0.2.6 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0ee169113edb44c11902cb1bd27fdb5f156d1c4ca4ff2a8e75b250d71bc3d52
-  data.tar.gz: 8d7ff6671fd40a3f08c33dd0c8070c427132919123925ed1d9fa28a43ca32e28
+  metadata.gz: 98446468efcfe543a72a5bf354b5e8c8408951dfc15072968df64500dc9e0275
+  data.tar.gz: a814a905f38b39064d8871a883b3bb4d68b2c446f0cec33d93f4c37671fcc33c
 SHA512:
-  metadata.gz: 8d2faaf09b6173c3d4c8d2a052f3377bdecfc3594a9fad426043296f8e2bc880519d528774e5481a5361414a32ee06082a6f5de55f6e15f0cf82718a6f87bda9
-  data.tar.gz: f2230cf14ee341c776f617eb1eb592013d907efbf18db02ea570f6d210363b46dd5b40be7b901a82ceef3b609f1e3a6e5fcd4a443f7350aca1150734a7ee1984
+  metadata.gz: 339a65265898c0b0e7b0e1758e708f57b4ee49d3b8fad1e93489058e6cbc047022e8d0cd42fcbe7793dad1a52dc04784e4122ce9e53d4360988f77f296f45c9f
+  data.tar.gz: 5443a095efe22bb69a079d51ae3bea37b78bd7035a3f0e07580c45006bbff98d44af7aeb17771622a4d33e98f8d0b3b957929a0b6a84ff54d3696684c3534ff2

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.4.0] - 2024-10-12
+
+- BREAKING CHANGE: Advisory Lock has been removed. If you explicitly define `advisory_lock: false` in your `positioned` call, you'll need to remove this.
+- CAUTION: The Advisory Lock replacement is row locking. Where `belongs_to` associations exist, we lock the associated record(s), and that limits the locking scope down to the record's current scope, and potentially the scope it belonged to before a change in scope. If there are no `belongs_to` associations then the records that belong to the current (and potentially new) scope are locked, or all the records in the table are locked if there is no scope. Please report any deadlock issues.
+
+## [0.3.0] - 2024-10-12
+
+- POSSIBLY BREAKING: Clear all position columns on a duplicate created with `dup`.
+
 ## [0.2.6] - 2024-08-21
 
 - Implement list healing so that existing lists can be fixed up when implementing `positioned` or if the list somehow gets corrupted.

data/README.md

@@ -185,6 +185,10 @@ other_item.id # => 11
 item.update position: {after: 11}
 ```
 
+##### Duplicating (`dup`)
+
+When you call `dup` on an instance in the list, all position columns on the duplicate will be set to `nil` so that when this duplicate is saved it will be added either to the end of the current scopes (if unchanged) or to the end of any new scopes. Of course you can then override the position of the duplicate before you save it if necessary.
+
 ##### 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.
@@ -261,49 +265,12 @@ It's important to note that in the examples above, `other_item` must already bel
 
 ## 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.
+The queries that this gem runs (especially those that seek the next position integer available) are vulnerable to race conditions. To this end, we lock the scope records to ensure that our model callbacks that determine and assign positions run sequentially. Previously we used an Advisory Lock for this purpose but this was difficult to test and a bit overkill in most situations. Where a scope doesn't exist, we lock all the records in the table.
 
-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
+**Please Note SQLite Users:** Row locking isn't supported by SQLite. Since writes are non-concurrent by default, the worst you'll probably see are errors about the database being locked under high load.
 
 If you have any concerns or improvements please file a GitHub issue.
 
-### Opting out of Advisory Lock
-
-There are cases where Advisory Lock may be unwanted or unnecessary, for instance, if you already lock the parent record in **every** operation that will touch the database on the positioned item, **everywhere** in your application.
-
-Example of such scenario in your application:
-
-```ruby
-list = List.create(name: "List")
-
-list.with_lock do
-  item_a = list.items.create(name: "Item A")
-  item_b = list.items.create(name: "Item B")
-  item_c = list.items.create(name: "Item C")
-
-  item_c.update(position: {before: item_a})
-
-  item_a.destroy
-end
-```
-
-Therefore, making sure you already have another mechanism to avoid race conditions, you can opt out of Advisory Lock by setting `advisory_lock` to `false` when declaring positioning:
-
-```ruby
-belongs_to :list
-positioned on: :list, advisory_lock: false
-```
-
 ## 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.

data/lib/positioning/healer.rb

@@ -7,19 +7,36 @@ module Positioning
     end
 
     def heal
-      if positioning_columns.present?
-        @model.select(*positioning_columns).distinct.each do |scope_record|
-          sequence @model.where(scope_record.slice(*positioning_columns))
+      if scope_columns.present?
+        @model.select(*scope_columns).distinct.each do |scope_record|
+          @model.transaction do
+            if scope_associations.present?
+              scope_associations.each do |scope_association|
+                scope_record.send(scope_association).lock!
+              end
+            else
+              @model.where(scope_record.slice(*scope_columns)).lock!
+            end
+
+            sequence @model.where(scope_record.slice(*scope_columns))
+          end
         end
       else
-        sequence @model
+        @model.transaction do
+          @model.all.lock!
+          sequence @model
+        end
       end
     end
 
     private
 
-    def positioning_columns
-      @model.positioning_columns[@column]
+    def scope_columns
+      @model.positioning_columns[@column][:scope_columns]
+    end
+
+    def scope_associations
+      @model.positioning_columns[@column][:scope_associations]
     end
 
     def sequence(scope)

data/lib/positioning/mechanisms.rb

@@ -14,6 +14,8 @@ module Positioning
     end
 
     def create_position
+      lock_positioning_scope!
+
       solidify_position
 
       expand(positioning_scope, position..)
@@ -22,6 +24,8 @@ module Positioning
     def update_position
       return unless positioning_scope_changed? || position_changed?
 
+      lock_positioning_scope!
+
       clear_position if positioning_scope_changed? && !position_changed?
 
       solidify_position
@@ -39,6 +43,8 @@ module Positioning
 
     def destroy_position
       unless destroyed_via_positioning_scope?
+        lock_positioning_scope!
+
         move_out_of_the_way
         contract(positioning_scope, (position_was + 1)..)
       end
@@ -50,16 +56,28 @@ module Positioning
       @positioned.class.base_class
     end
 
+    def with_connection
+      if base_class.respond_to? :with_connection
+        base_class.with_connection do |connection|
+          yield connection
+        end
+      else
+        yield base_class.connection
+      end
+    end
+
     def primary_key
       base_class.primary_key
     end
 
     def quoted_column
-      base_class.connection.quote_table_name_for_assignment base_class.table_name, @column
+      with_connection do |connection|
+        connection.quote_table_name_for_assignment base_class.table_name, @column
+      end
     end
 
     def record_scope
-      base_class.where(primary_key => [@positioned.id])
+      base_class.where primary_key => [@positioned.id]
     end
 
     def position
@@ -158,16 +176,32 @@ module Positioning
       (positioning_scope.maximum(@column) || 0) + (in_positioning_scope? ? 0 : 1)
     end
 
-    def positioning_columns
-      base_class.positioning_columns[@column]
+    def scope_columns
+      base_class.positioning_columns[@column][:scope_columns]
+    end
+
+    def scope_associations
+      base_class.positioning_columns[@column][:scope_associations]
     end
 
     def positioning_scope
-      base_class.where @positioned.slice(*positioning_columns)
+      base_class.where @positioned.slice(*scope_columns)
+    end
+
+    def lock_positioning_scope!
+      if scope_associations.present?
+        scope_associations.each do |scope_association|
+          record_scope.first.send(scope_association).lock! if @positioned.persisted? && positioning_scope_changed?
+          @positioned.send(scope_association).lock!
+        end
+      else
+        positioning_scope_was.lock! if @positioned.persisted? && positioning_scope_changed?
+        positioning_scope.lock!
+      end
     end
 
     def positioning_scope_was
-      base_class.where record_scope.first.slice(*positioning_columns)
+      base_class.where record_scope.first.slice(*scope_columns)
     end
 
     def in_positioning_scope?
@@ -175,14 +209,14 @@ module Positioning
     end
 
     def positioning_scope_changed?
-      positioning_columns.any? do |scope_component|
-        @positioned.attribute_changed?(scope_component)
+      scope_columns.any? do |scope_column|
+        @positioned.attribute_changed?(scope_column)
       end
     end
 
     def destroyed_via_positioning_scope?
-      @positioned.destroyed_by_association && positioning_columns.any? do |scope_component|
-        @positioned.destroyed_by_association.foreign_key == scope_component
+      @positioned.destroyed_by_association && scope_columns.any? do |scope_column|
+        @positioned.destroyed_by_association.foreign_key == scope_column
       end
     end
   end

data/lib/positioning/version.rb

@@ -1,3 +1,3 @@
 module Positioning
-  VERSION = "0.2.6"
+  VERSION = "0.4.0"
 end

data/lib/positioning.rb

@@ -1,5 +1,4 @@
 require_relative "positioning/version"
-require_relative "positioning/advisory_lock"
 require_relative "positioning/mechanisms"
 require_relative "positioning/healer"
 
@@ -19,7 +18,7 @@ module Positioning
         @positioning_columns ||= {}
       end
 
-      def positioned(on: [], column: :position, advisory_lock: true)
+      def positioned(on: [], column: :position)
         unless base_class?
           raise Error.new "can't be called on an abstract class or STI subclass."
         end
@@ -29,11 +28,18 @@ module Positioning
         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|
+          positioning_columns[column] = {scope_columns: [], scope_associations: []}
+
+          Array.wrap(on).each do |scope_component|
             scope_component = scope_component.to_s
             reflection = reflections[scope_component]
 
-            (reflection && reflection.belongs_to?) ? reflection.foreign_key : scope_component
+            if reflection&.belongs_to?
+              positioning_columns[column][:scope_columns] << reflection.foreign_key
+              positioning_columns[column][:scope_associations] << reflection.name
+            else
+              positioning_columns[column][:scope_columns] << scope_component
+            end
           end
 
           define_method(:"prior_#{column}") { Mechanisms.new(self, column).prior }
@@ -44,27 +50,24 @@ module Positioning
             super(position)
           end
 
-          advisory_locker = AdvisoryLock.new(base_class, column, advisory_lock)
-
-          before_create { advisory_locker.acquire }
-          before_update { advisory_locker.acquire }
-          before_destroy { advisory_locker.acquire }
-
           before_create { Mechanisms.new(self, column).create_position }
           before_update { Mechanisms.new(self, column).update_position }
           before_destroy { Mechanisms.new(self, column).destroy_position }
 
-          after_commit { advisory_locker.release }
-          after_rollback { advisory_locker.release }
-
           define_singleton_method(:"heal_#{column}_column!") do |order = column|
-            advisory_locker.acquire do
-              Healer.new(self, column, order).heal
-            end
+            Healer.new(self, column, order).heal
           end
         end
       end
     end
+
+    def initialize_dup(other)
+      super
+
+      self.class.positioning_columns.keys.each do |positioning_column|
+        send :"#{positioning_column}=", nil
+      end
+    end
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: positioning
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.4.0
 platform: ruby
 authors:
 - Brendon Muir
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-21 00:00:00.000000000 Z
+date: 2024-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -122,7 +122,6 @@ files:
 - README.md
 - Rakefile
 - lib/positioning.rb
-- lib/positioning/advisory_lock.rb
 - lib/positioning/healer.rb
 - lib/positioning/mechanisms.rb
 - lib/positioning/version.rb

data/lib/positioning/advisory_lock.rb

@@ -1,82 +0,0 @@
-require "fileutils"
-require "openssl"
-
-module Positioning
-  class AdvisoryLock
-    Adapter = Struct.new(:initialise, :acquire, :release, keyword_init: true)
-
-    attr_reader :base_class
-
-    def initialize(base_class, column, enabled)
-      @base_class = base_class
-      @column = column.to_s
-      @enabled = enabled
-
-      @adapters = {
-        "mysql2" => Adapter.new(
-          initialise: -> {},
-          acquire: -> { connection.execute "SELECT GET_LOCK(#{connection.quote(lock_name)}, -1)" },
-          release: -> { connection.execute "SELECT RELEASE_LOCK(#{connection.quote(lock_name)})" }
-        ),
-        "postgresql" => Adapter.new(
-          initialise: -> {},
-          acquire: -> { connection.execute "SELECT pg_advisory_lock(#{lock_name.hex & 0x7FFFFFFFFFFFFFFF})" },
-          release: -> { connection.execute "SELECT pg_advisory_unlock(#{lock_name.hex & 0x7FFFFFFFFFFFFFFF})" }
-        ),
-        "sqlite3" => 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
-          },
-          acquire: -> {
-            @file.flock File::LOCK_EX
-          },
-          release: -> {
-            @file.flock File::LOCK_UN
-          }
-        )
-      }
-
-      @adapters.default = Adapter.new(initialise: -> {}, acquire: -> {}, release: -> {})
-
-      adapter.initialise.call if @enabled
-    end
-
-    def acquire
-      adapter.acquire.call if @enabled
-
-      if block_given?
-        yield
-        adapter.release.call if @enabled
-      end
-    end
-
-    def release
-      adapter.release.call if @enabled
-    end
-
-    private
-
-    def connection
-      base_class.connection
-    end
-
-    def adapter_name
-      base_class.connection_db_config.adapter
-    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