organizations 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cee8b956413b0859d592b794078046a1f5ed95fea6fd391e8b3a6aee83dbc14d
-  data.tar.gz: 3f0ef38dd0d343ffbba6c7f9a28f1943f55f2610d90b77b36306908b79d18e64
+  metadata.gz: e3c621c2b6bb7bd32be611858d49af9cb12cf9fa80bc0309d1227eafc819f8d8
+  data.tar.gz: c6028a9e424ab92432c44ae45bcba367d2a70eab56e3901314b1d5ff9b9b102f
 SHA512:
-  metadata.gz: fa931ef4f5a12370ae4f86ceb15bc9d601a35ef042db467cc9c4c4ff125022f16760fbfe1c9a140c0a3001862b61386d7a2529e1e2074be2b98576760983747f
-  data.tar.gz: a33b77589dc25b53c5a0783899d4056ac8a0fcb73e578f089eb3fece8565a3ae9c2f098c3c64babf43e752907807064ad3e78a0855b1e5a858631749bcce8461
+  metadata.gz: 267e7126501538f4461616e2be708f1b3696a016b428135337193dc8eaf24532a446a9c651b1989610862025298cbb4b9ab38b7f1d901b0fcb3f49f68d28ec56
+  data.tar.gz: 98d2dbd1b5369c247c6b8147c7472f0b53e74aa25c0c000b8458834ddff6e81f0ec6f3e599611f2ba8ef10b2dd88ddb5775fe15816cef13d57fb48a393ddce6a

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [0.8.1] - 2026-10-25
+
+**The joins take the lock order of the destroys.** A patch release with one fix. No migration is needed.
+
+### Fixed
+
+- **A join could deadlock with a deletion on PostgreSQL.** 0.8.0 made every destroy lock the user row, then the organization rows, then their child rows. Several joins locked their own row first, and the organization row (or a user row) only later, when they wrote. So a join and a deletion could each hold a row that the other waited for. PostgreSQL then aborted one of them with `ActiveRecord::Deadlocked`. These paths now take a guard on the user rows that their writes name (in id order), then lock the organization row, then their own row:
+  - `Invitation#accept!` (the accepting user and the inviter). Before, an acceptance deadlocked with the inviter's account deletion or with a destroy of the organization.
+  - `Invitation#revoke!` (no user row). Before, the revoke of an invitation with grants deadlocked with a destroy of its organization or with the inviter's account deletion.
+  - `JoinRequest#approve!` and the automatic approval after a verified email (the requester and the decider). Before, an approval deadlocked with the requester's account deletion.
+  - `JoinRequest#verify_email_code!` (the requester). Before, the check of an emailed code deadlocked with a destroy of the organization, which deletes the domain before the request. The requester's guard comes first, so the automatic approval inside a host transaction asks for no user row while it holds the organization row.
+  - `JoinCode#redeem!` (the redeeming user). Before, a redemption deadlocked with the account deletion of the code's creator or with a destroy of the organization.
+- **The user guard is a key share lock** (`FOR KEY SHARE` on PostgreSQL, a shared lock on MySQL, nothing on SQLite). It conflicts with the deletion's `FOR UPDATE`, and with nothing else: an update of the user and the foreign key checks of other writers pass. So `reject!` (which names its decider), `withdraw!`, `resend!` and a grant on a pending invitation (which names its granter) keep their single row lock and do not wait for the guards.
+- **An acceptance from a stale copy locks the current inviter.** A reissue of an expired invitation (`send_invite_to!`) names the new inviter. A loaded copy can still name the old one. The acceptance reads the row again under its lock. When the row names other ids than the ones locked, the acceptance releases its locks (a savepoint) and tries again with the current ids, up to three times. Then it raises `Invitation::InvitationChanged`, an `InvitationError`. `accept_pending_organization_invitation!` returns it as the failure `:invitation_changed` and keeps the session token. The engine's accept action answers with the localized message: HTML goes back to the invitation page, JSON gets a 409. Before, the acceptance could insert a membership that named an unlocked inviter, and deadlock with an ownership transfer to that inviter.
+- Inside a host transaction, the order holds only when the locks that the host took earlier in that transaction keep it too.
+- README: "Row-level locking" states the one lock order. The steps of the ownership transfer now start with the new owner's row, as the code has done since 0.7.0.
+
 ## [0.8.0] - 2026-10-24
 
 **Hand a personal organization over, and keep organizations that hold records with a retention period.** An invoicing app on the fleet built both by hand and runs them in production. This release moves them into the gem, with their tests. Both are opt-in, and no migration is needed.

data/README.md

@@ -722,6 +722,10 @@ invitation.grant!(record, capabilities: %i[read])
 # Actions
 invitation.accept!              # Accept (auto-infers Current.user)
 invitation.accept!(user)        # Accept with explicit user
+# accept! raises Organizations::InvitationExpired, Organizations::InvitationAlreadyAccepted,
+# Invitation::EmailMismatch, Invitation::CannotAcceptAsOwner, or Invitation::InvitationChanged:
+# a reissue named another inviter at each of three tries to lock the rows. Nothing is
+# written then, and the person can try again (organizations.errors.invitation_changed).
 invitation.resend!(resent_by: current_user)   # Send invitation email again
 invitation.revoke!(revoked_by: current_user)  # Delete it, so the link stops working
 ```
@@ -1325,6 +1329,8 @@ else
 end
 ```
 
+The reasons: `:missing_user`, `:missing_token`, `:invitation_not_found`, `:invitation_expired`, `:email_mismatch`, `:already_accepted_without_membership` and `:invitation_changed`. `:invitation_changed` means that a reissue changed the invitation during the acceptance (`Invitation::InvitationChanged`). Nothing was written, and the session keeps the token, so the person can try again. The engine's accept action answers it with the localized message (`organizations.errors.invitation_changed`): HTML goes back to the invitation page, JSON gets a 409 with `{ "error": message }`.
+
 Configure redirects in your initializer:
 
 ```ruby
@@ -1604,7 +1610,7 @@ What the gem guarantees:
 
 - It checks the complete owned set before it deletes anything. One blocker blocks the whole deletion.
 - The organization deletion and the user deletion are one transaction, with its own savepoint, also inside a transaction of yours. A host `before_destroy` veto on the organization, or any later failure, rolls back everything, and the veto message is on `user.errors`.
-- Before its first write, `user.destroy` locks the user row, then the row of every organization in which it writes (memberships, sent invitations and their grants, join requests and the other records it nullifies), in id order. An organization's destroy also locks its row before its cascades, so the two cannot deadlock. A concurrent join or organization creation for that user, a join, transfer or destroy in one of those organizations, and an ownership transfer to that user (`transfer_ownership_to!` locks the new owner's row) wait for the deletion, or finish first and are seen by it. The guard reads the database under its locks, not the query cache.
+- Before its first write, `user.destroy` locks the user row, then the row of every organization in which it writes (memberships, sent invitations and their grants, join requests and the other records it nullifies), in id order. An organization's destroy also locks its row before its cascades, so the two cannot deadlock. The joins take the same order (see "Row-level locking"). A concurrent join or organization creation for that user, a join, transfer or destroy in one of those organizations, and an ownership transfer to that user (`transfer_ownership_to!` locks the new owner's row) wait for the deletion, or finish first and are seen by it. The guard reads the database under its locks, not the query cache.
 - The user's other memberships are deleted (`dependent: :destroy`), as before. Invitations they sent, join requests they decided, join codes they created and allowlist entries they claimed keep the record and lose the user reference.
 
 ### Organizations that must be kept
@@ -2705,7 +2711,9 @@ These constraints prevent duplicate data at the database level:
 
 ### Row-level locking
 
-The gem uses `SELECT ... FOR UPDATE` (row-level locks) to prevent race conditions:
+The gem uses `SELECT ... FOR UPDATE` (row-level locks) to prevent race conditions.
+
+The gem takes its row locks in one order: the user rows that a write names (in id order), then the organization row, then the rows of the organization. A user's deletion locks its user row `FOR UPDATE`. The joins take a key share guard on their user rows (`FOR KEY SHARE` on PostgreSQL): only a deletion of those users waits for it, and ordinary updates and foreign key checks pass. A user's deletion, an organization's destroy, an invitation acceptance or revoke, a join request approval, the check of an emailed code and a join code redemption all keep this order. So they wait for each other, and do not deadlock on PostgreSQL. Inside your own transaction, the order holds only when your earlier locks in that transaction keep it too. Keep the same order in your own code that writes in an organization.
 
 **Invitation acceptance:**
 ```ruby
@@ -2713,11 +2721,14 @@ The gem uses `SELECT ... FOR UPDATE` (row-level locks) to prevent race condition
 invitation.accept!
 
 # Internally:
-# 1. Lock invitation row
-# 2. Check accepted_at is nil
-# 3. Create membership
-# 4. Set accepted_at
-# 5. Release lock
+# 1. Take the key share guard on the accepting user and the inviter
+# 2. Lock organization row
+# 3. Lock invitation row (when it now names another inviter, release the
+#    locks and start again with the current one, up to three times)
+# 4. Check accepted_at is nil
+# 5. Create membership
+# 6. Set accepted_at
+# 7. Release locks
 # Second request sees accepted_at is set, returns existing membership
 ```
 
@@ -2726,13 +2737,14 @@ invitation.accept!
 org.transfer_ownership_to!(new_owner)
 
 # Internally:
-# 1. Lock organization row
-# 2. Lock old owner's membership
-# 3. Lock new owner's membership
-# 4. Verify new owner is a member
-# 5. Demote old owner to admin
-# 6. Promote new owner to owner
-# 7. Release locks
+# 1. Lock the new owner's user row
+# 2. Lock organization row
+# 3. Lock old owner's membership
+# 4. Lock new owner's membership
+# 5. Verify new owner is a member
+# 6. Demote old owner to admin
+# 7. Promote new owner to owner
+# 8. Release locks
 ```
 
 **Last admin/owner protection:**

data/app/controllers/organizations/public_invitations_controller.rb

@@ -66,18 +66,13 @@ module Organizations
 
     def respond_invitation_acceptance_failure(failure)
       case failure.failure_reason
-      when :email_mismatch
-        return respond_invitation_email_mismatch
-      when :invitation_expired
-        return respond_invitation_expired
+      when :email_mismatch then respond_invitation_email_mismatch
+      when :invitation_expired then respond_invitation_expired
+      when :invitation_changed then respond_invitation_changed(failure.invitation || @invitation)
+      else
+        respond_invitation_error(html_path: main_app.root_path, alert: "Unable to accept this invitation.",
+                                 json_error: "Acceptance failed", status: 422)
       end
-
-      respond_invitation_error(
-        html_path: main_app.root_path,
-        alert: "Unable to accept this invitation.",
-        json_error: "Acceptance failed",
-        status: 422
-      )
     end
 
     def respond_invitation_email_mismatch
@@ -98,6 +93,14 @@ module Organizations
       )
     end
 
+    # A reissue changed the invitation during the acceptance, and nothing was
+    # written. Send the person back to it (its current link) to try again.
+    def respond_invitation_changed(invitation)
+      message = Organizations.t(:"errors.invitation_changed", organization: invitation.organization)
+      respond_invitation_error(html_path: invitation_path(invitation.token), alert: message, json_error: message,
+                               status: 409)
+    end
+
     def respond_invitation_acceptance_success(result)
       after_path = redirect_path_after_invitation_accepted(result.invitation, user: current_user)
       payload, status = invitation_acceptance_json_response(result)

data/config/locales/en.yml

@@ -72,6 +72,7 @@ en:
       # — Invitations —
       invitation_expired: "This invitation has expired"
       invitation_already_accepted: "This invitation has already been accepted"
+      invitation_changed: "This invitation changed while it was being accepted. Try again."
       invitation_cannot_resend_accepted: "Cannot resend an accepted invitation"
       invitation_email_mismatch: "This invitation was sent to a different email address"
       invitation_accept_as_owner: "Cannot accept invitation as owner. Invite as admin, then use transfer_ownership_to! after joining."

data/config/locales/es.yml

@@ -54,6 +54,7 @@ es:
 
       invitation_expired: "Esta invitación ha caducado"
       invitation_already_accepted: "Esta invitación ya ha sido aceptada"
+      invitation_changed: "Esta invitación cambió mientras se aceptaba. Inténtalo de nuevo."
       invitation_cannot_resend_accepted: "No se puede reenviar una invitación ya aceptada"
       invitation_email_mismatch: "Esta invitación se envió a otra dirección de email"
       invitation_accept_as_owner: "No se puede aceptar una invitación como propietario. Invita como administrador y transfiere la propiedad después."

data/lib/organizations/controller_helpers.rb

@@ -290,6 +290,14 @@ module Organizations
           return_failure: return_failure,
           invitation: invitation
         )
+      rescue Organizations::Invitation::InvitationChanged
+        # A reissue changed the invitation at each try to lock it. Nothing
+        # was written, and the person can try again: keep the session token.
+        return invitation_acceptance_failure(
+          :invitation_changed,
+          return_failure: return_failure,
+          invitation: invitation
+        )
       rescue Organizations::InvitationAlreadyAccepted
         # Check if user is actually a member
         membership = Organizations::Membership.find_by(

data/lib/organizations/invitation_acceptance_failure.rb

@@ -10,6 +10,7 @@ module Organizations
       invitation_expired
       email_mismatch
       already_accepted_without_membership
+      invitation_changed
     ].freeze
 
     attr_reader :reason, :invitation

data/lib/organizations/models/invitation.rb

@@ -124,6 +124,12 @@ module Organizations
     # Error raised when trying to accept an invitation with owner role
     class CannotAcceptAsOwner < Organizations::InvitationError; end
 
+    # The invitation named another inviter at each of ACCEPT_LOCK_ATTEMPTS
+    # tries to lock its rows (it was reissued meanwhile).
+    class InvitationChanged < Organizations::InvitationError; end
+
+    ACCEPT_LOCK_ATTEMPTS = 3
+
     # Accept the invitation and create membership
     # Uses row-level locking to prevent race conditions
     # @param user [User, nil] The user accepting (uses Current.user if not provided)
@@ -149,8 +155,7 @@ module Organizations
       membership = nil
 
       ActiveRecord::Base.transaction do
-        # Lock the invitation row to prevent race conditions
-        lock!
+        lock_rows_for_acceptance!(accepting_user)
 
         # Re-check status after acquiring lock
         if accepted?
@@ -231,6 +236,10 @@ module Organizations
     # @raise [Organizations::NotAuthorized] if the role ranks above revoked_by's own
     def revoke!(revoked_by: nil)
       ActiveRecord::Base.transaction do
+        # The organization row first (RowLocks), as an organization destroy
+        # and the inviter's deletion lock it before this invitation and its
+        # grants.
+        RowLocks.lock_organization!(organization_id)
         lock!
         authorize_management!(revoked_by)
         destroy!
@@ -257,6 +266,31 @@ module Organizations
 
     private
 
+    # The gem's lock order (RowLocks): the users that the membership names
+    # (the accepting user and the inviter), then the organization row, then
+    # the invitation row. A deletion of the inviter or of the organization
+    # takes the same order, so it waits for this acceptance, or this one for
+    # it. This copy can name a stale inviter: a reissue of the expired row
+    # (send_invite_to!) names the new one. The row lock reads the row again.
+    # When it names other ids than the ones locked, the savepoint rolls back,
+    # which releases its locks, and the next attempt locks the current ids.
+    def lock_rows_for_acceptance!(accepting_user)
+      ACCEPT_LOCK_ATTEMPTS.times do
+        locked = [invited_by_id, organization_id]
+        held = ActiveRecord::Base.transaction(requires_new: true) do
+          RowLocks.lock_users!(accepting_user.id, invited_by_id)
+          RowLocks.lock_organization!(organization_id)
+          lock!
+          raise ActiveRecord::Rollback unless [invited_by_id, organization_id] == locked
+
+          true
+        end
+        return if held
+      end
+
+      raise InvitationChanged, Organizations.t(:"errors.invitation_changed", organization: organization)
+    end
+
     # The invitation's grants become the membership's (a grant on the same
     # resource takes the invitation's capabilities). The inviter was
     # checked when the invitation was sent.

data/lib/organizations/models/join_code.rb

@@ -152,10 +152,7 @@ module Organizations
       outcome = nil
 
       ActiveRecord::Base.transaction do
-        # Lock the code row: uses_count accounting and the max_uses cap must
-        # be race-safe (two concurrent redemptions of a max_uses: 1 code must
-        # yield exactly one success).
-        lock!
+        lock_rows_for_redemption!(user)
         ensure_redeemable!
 
         # Already a member — idempotent no-op that does NOT consume a use.
@@ -188,6 +185,18 @@ module Organizations
 
     private
 
+    # The gem's lock order (RowLocks): the redeeming user, then the
+    # organization row, then the code row. The deletion of the code's
+    # creator and an organization destroy take the organization row before
+    # the code row. The code row lock makes the uses_count accounting and
+    # the max_uses cap race-safe (two concurrent redemptions of a max_uses: 1
+    # code must yield exactly one success).
+    def lock_rows_for_redemption!(user)
+      RowLocks.lock_users!(user.id)
+      RowLocks.lock_organization!(organization_id)
+      lock!
+    end
+
     def ensure_redeemable!
       raise JoinCodeInvalid, Organizations.t(:"errors.join_code_invalid") if revoked? || expired?
       raise JoinCodeExhausted, Organizations.t(:"errors.join_code_exhausted") if exhausted?

data/lib/organizations/models/join_request.rb

@@ -180,7 +180,7 @@ module Organizations
       failure = nil
 
       ActiveRecord::Base.transaction do
-        lock!
+        lock_rows_for_verification!
         ensure_open!
         ensure_active_challenge!
         # The domain or roster entry may have been removed, revoked or
@@ -319,11 +319,30 @@ module Organizations
 
     private
 
+    # The gem's lock order (RowLocks): the requester, then the organization
+    # row, then this request. An organization destroy deletes the domains
+    # and allowlist entries before this request, and the check locks one of
+    # them after this request. The automatic approval takes the requester's
+    # guard again: inside a host transaction, this one already holds it, so
+    # the approval does not ask for a user row while it holds the
+    # organization row.
+    def lock_rows_for_verification!
+      RowLocks.lock_users!(user_id)
+      RowLocks.lock_organization!(organization_id)
+      lock!
+    end
+
     def perform_approval!(decided_by:, recheck_instruments:)
       membership = nil
       reused_existing = false
 
       ActiveRecord::Base.transaction do
+        # The gem's lock order (RowLocks): the requester and the decider,
+        # then the organization row, then this request. The requester's
+        # deletion locks the requester, then the organization, and deletes
+        # this request.
+        RowLocks.lock_users!(user_id, decided_by&.id)
+        RowLocks.lock_organization!(organization_id)
         lock!
 
         return approved_membership! if approved? # idempotent re-approval

data/lib/organizations/row_locks.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Organizations
+  # The one lock order of the gem: the user rows (in id order), then the
+  # organization row, then the rows of the organization. A user's deletion
+  # locks the user row, then the row of every organization in which it
+  # writes. An organization's destroy locks its row before its cascades. A
+  # path that writes in an organization takes the same order, or it can
+  # deadlock with them on PostgreSQL.
+  #
+  # The user rows are the ones that the path's writes reference: a row that
+  # names a user takes a key share lock on it when it is written, which
+  # waits for a deletion of that user. Lock them first, so that the wait
+  # comes before the organization row and not after it.
+  #
+  # The user guard is a key share lock (FOR KEY SHARE on PostgreSQL). It
+  # conflicts with the deletion's FOR UPDATE, which is its purpose, and with
+  # nothing else: an ordinary update of the user and the foreign key check
+  # of another writer pass. A FOR UPDATE guard would block those writers,
+  # and a writer that holds a row this path waits for would then close a
+  # cycle (a reject! that sets decided_by_id, a grant that names its
+  # granter).
+  #
+  # Inside a host transaction the order holds only when the host's earlier
+  # locks in that transaction keep it too.
+  #
+  # @api private
+  module RowLocks
+    module_function
+
+    # Take the key share guard on these users' rows, in id order. Nil ids
+    # and users that are gone are skipped.
+    # @param ids [Array<Object>]
+    def lock_users!(*ids)
+      ids = ids.flatten.compact.uniq
+      return if ids.empty?
+
+      user_class = Organizations.user_class
+      key = user_class.primary_key
+      user_class.unscoped.where(key => ids).order(key).lock(key_share_clause(user_class.connection)).pluck(key)
+    end
+
+    # PostgreSQL has a lock that only a delete or a key change conflicts
+    # with. MySQL has a shared lock. SQLite has no row locks: Rails drops
+    # the clause there.
+    def key_share_clause(connection)
+      adapter = connection.adapter_name.downcase
+      return "FOR KEY SHARE" if adapter.include?("postg")
+      return "LOCK IN SHARE MODE" if adapter.include?("mysql") || adapter.include?("trilogy")
+
+      true
+    end
+
+    # Lock the organization row. A destroyed organization is skipped: the
+    # caller's own row lock then finds its row gone.
+    # @param id [Object]
+    def lock_organization!(id)
+      Organizations::Organization.unscoped.where(id: id).lock.pick(:id)
+    end
+  end
+end

data/lib/organizations/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Organizations
-  VERSION = "0.8.0"
+  VERSION = "0.8.1"
 end

data/lib/organizations.rb

@@ -126,6 +126,7 @@ module Organizations
   autoload :GrantAccess, "organizations/grant_access"
   autoload :Grantable, "organizations/grantable"
   autoload :AccountDeletionPlan, "organizations/account_deletion_plan"
+  autoload :RowLocks, "organizations/row_locks"
 
   # Alias for README compatibility: `include Organizations::Controller`
   Controller = ControllerHelpers

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: organizations
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-10-24 00:00:00.000000000 Z
+date: 2026-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -180,6 +180,7 @@ files:
 - lib/organizations/public_email_domains.rb
 - lib/organizations/resource.rb
 - lib/organizations/roles.rb
+- lib/organizations/row_locks.rb
 - lib/organizations/test_helpers.rb
 - lib/organizations/version.rb
 - lib/organizations/view_helpers.rb