Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Serialize payment settlement on the owner's row lock

Damian Legawiec347dc2dd4c0a
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index 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 sync
path lacked (`validate` before money is recorded — the webhook path
deliberately 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 explicit
call.** No subscriber replaced it — a first attempt proved why: the card
number never persists, so profile creation only works on the in-memory
diff --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.rb
index 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 complete
result = 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.rb
index 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
+ end
end
# @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.rb
index 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 do
not_to change { first_settlement.reload.capture_events.count }
end
end
+
+ # 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)
+ end
end
describe '#amount_in_cents' do