Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Serialize payment settlement on the owner's row lock
Damian Legawiec347dc2dd4c0a
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex d63997bf83..a00ee64163 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -359,6 +359,12 @@ Five changes close the gap:same settlement through `settle_payment!`, plus the one veto point the syncpath lacked (`validate` before money is recorded — the webhook pathdeliberately has none, money that moved cannot be rejected).+ `settle_payment!` itself takes the owner's row lock around the local+ settlement — the completed? guard alone is check-then-act, and two+ concurrent settlements would each record a capture event. The lock never+ spans gateway I/O (Stripe memoizes the intent and charge before settling;+ the webhook path's outer lock nests reentrantly), which is the difference+ between this and the controller-level with_order_lock it replaced.- **`create_payment_profile` left its save callback and became an explicitcall.** No subscriber replaced it — a first attempt proved why: the cardnumber never persists, so profile creation only works on the in-memorydiff --git a/spree/api/app/controllers/spree/api/v3/store/carts/payment_sessions_controller.rb b/spree/api/app/controllers/spree/api/v3/store/carts/payment_sessions_controller.rbindex 9cda3cde65..0d0fef27e6 100644--- a/spree/api/app/controllers/spree/api/v3/store/carts/payment_sessions_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/store/carts/payment_sessions_controller.rb@@ -58,9 +58,11 @@ module Spree# Deliberately not wrapped in with_order_lock: the workflow verifies# the session with the gateway from an external_step, and holding a# row lock across that round trip is what the boundary exists to- # prevent. The race against the webhook is settled inside — both- # paths go through PaymentSession#settle_payment!, and a replay on- # a completed session is an idempotent success.+ # prevent. Concurrency is enforced where the invariant lives —+ # PaymentSession#settle_payment! takes the owner's row lock around+ # the local settlement, so a confirm racing the webhook (or a+ # double-submitted confirm) records the capture exactly once, and a+ # replay on a completed session is an idempotent success.def completeresult = Spree.payment_session_complete_workflow.call(payment_session: @payment_session.reload,diff --git a/spree/core/app/models/spree/payment_session.rb b/spree/core/app/models/spree/payment_session.rbindex 956aa32e06..f2063d53ab 100644--- a/spree/core/app/models/spree/payment_session.rb+++ b/spree/core/app/models/spree/payment_session.rb@@ -109,12 +109,22 @@ module Spree# captured; false means authorized only, so the payment pends# @param metadata [Hash] gateway-specific metadata for payment creation# @return [Spree::Payment, nil]+ # Serialized on the owner's row: the storefront confirm and the gateway+ # webhook can race, and the completed? guard alone is check-then-act — two+ # concurrent settlements would each record a capture event, doubling+ # captured_amount. The lock wraps only the local settlement, never gateway+ # I/O (callers fetch what they need from the provider first), and nests as+ # a no-op inside HandleWebhook's own owner lock.def settle_payment!(captured:, metadata: {})- settled_payment = find_or_create_payment!(metadata)- return settled_payment if settled_payment.blank? || settled_payment.completed?+ owner.with_lock do+ settled_payment = find_or_create_payment!(metadata)- settled_payment.confirm!(captured: captured)- settled_payment+ if settled_payment.present? && !settled_payment.completed?+ settled_payment.confirm!(captured: captured)+ end++ settled_payment+ endend# @return [Spree::Cart, Spree::Order, nil]diff --git a/spree/core/spec/models/spree/payment_session_spec.rb b/spree/core/spec/models/spree/payment_session_spec.rbindex 7dccac85b6..e36768c131 100644--- a/spree/core/spec/models/spree/payment_session_spec.rb+++ b/spree/core/spec/models/spree/payment_session_spec.rb@@ -192,6 +192,15 @@ RSpec.describe Spree::PaymentSession, type: :model donot_to change { first_settlement.reload.capture_events.count }endend++ # The storefront confirm and the gateway webhook can race; the completed?+ # guard alone is check-then-act, so settlement must hold the owner's row+ # lock for the capture event to be recorded exactly once.+ it 'settles under the owner row lock' do+ expect(payment_session.owner).to receive(:with_lock).and_call_original++ payment_session.settle_payment!(captured: true)+ endenddescribe '#amount_in_cents' do