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.

Make the ledger survive a failure and a repeat

Damian Legawiec994acf37f47e
diff --git a/spree/core/app/models/spree/seller_transfer.rb b/spree/core/app/models/spree/seller_transfer.rb
index 9bfc626c30..4098824f3f 100644
--- a/spree/core/app/models/spree/seller_transfer.rb
+++ b/spree/core/app/models/spree/seller_transfer.rb
@@ -33,6 +33,9 @@ module Spree
# a re-run sweep can never batch the same earning twice.
belongs_to :payout, class_name: 'Spree::SellerPayout', optional: true, inverse_of: :transfers
belongs_to :reversed_from, class_name: 'Spree::SellerTransfer', optional: true, inverse_of: :reversals
+ # What caused a reversal. Nil on an earning, and the reversal's natural
+ # key: one clawback per refund, enforced by a unique index.
+ belongs_to :refund, class_name: 'Spree::Refund', optional: true
has_many :reversals, class_name: 'Spree::SellerTransfer', foreign_key: :reversed_from_id,
inverse_of: :reversed_from, dependent: :nullify
diff --git a/spree/core/app/subscribers/spree/seller_transfer_reversal_subscriber.rb b/spree/core/app/subscribers/spree/seller_transfer_reversal_subscriber.rb
index 73e42302fa..9a2932389e 100644
--- a/spree/core/app/subscribers/spree/seller_transfer_reversal_subscriber.rb
+++ b/spree/core/app/subscribers/spree/seller_transfer_reversal_subscriber.rb
@@ -20,7 +20,7 @@ module Spree
order = refund.order
return if order.nil? || order.seller_id.blank?
- Spree.seller_transfer_reverse_workflow.call(order: order, amount: refund.amount)
+ Spree.seller_transfer_reverse_workflow.call(order: order, amount: refund.amount, refund: refund)
end
end
end
diff --git a/spree/core/app/workflows/spree/seller_payouts/complete.rb b/spree/core/app/workflows/spree/seller_payouts/complete.rb
index 395748d396..458b254484 100644
--- a/spree/core/app/workflows/spree/seller_payouts/complete.rb
+++ b/spree/core/app/workflows/spree/seller_payouts/complete.rb
@@ -31,16 +31,27 @@ module Spree
private
- # A webhook can arrive twice, and an operator can double-click.
+ # A webhook can arrive twice, and an operator can double-click. The cheap
+ # read catches the ordinary case; the write below catches the race.
def replay_completed
- halt!(seller_payout) if seller_payout.completed?
+ halt!(seller_payout) if seller_payout.reload.completed?
end
+ # Compare-and-swap on the terminal write, because an operator marking a
+ # bank transfer sent can race the provider's own webhook saying the same
+ # thing. Both would pass the read above, both would write `completed`,
+ # and the completion event — public API a subscriber may act on — would
+ # fire twice for one settlement.
def mark_completed
- attributes = { status: 'completed' }
+ attributes = { status: 'completed', updated_at: Time.current }
attributes[:reference] = reference if reference.present?
- seller_payout.update!(attributes)
+ claimed = Spree::SellerPayout.where(id: seller_payout.id, status: %w[pending processing]).
+ update_all(attributes)
+
+ halt!(seller_payout.reload) if claimed.zero?
+
+ seller_payout.reload
end
end
end
diff --git a/spree/core/app/workflows/spree/seller_payouts/sweep.rb b/spree/core/app/workflows/spree/seller_payouts/sweep.rb
index e0e3c85bab..ceb97ce0e2 100644
--- a/spree/core/app/workflows/spree/seller_payouts/sweep.rb
+++ b/spree/core/app/workflows/spree/seller_payouts/sweep.rb
@@ -88,18 +88,42 @@ module Spree
# lie, so this payout takes only what it actually claimed.
restate_amount if claimed != @transfers.size
end
+
+ # The threshold was checked against what this sweep hoped to claim. If
+ # a concurrent one took some of it the figure has changed, and a
+ # restated payout can even come to nothing — which must not be sent: a
+ # provider asked to move zero either errors or moves nothing, and
+ # either way it is not a settlement.
+ discard_empty_payout if @payout.amount <= 0
end
def restate_amount
@payout.update!(amount: @payout.transfers.sum(:amount))
end
+ # Nothing was claimed, so there is nothing to release and nothing to
+ # record. The earnings this sweep meant to take are already in the payout
+ # that won them.
+ def discard_empty_payout
+ @payout.transfers.update_all(payout_id: nil, updated_at: Time.current)
+ @payout.destroy!
+ halt!(seller)
+ end
+
def execute_payout
provider.pay!(payout)
rescue StandardError => e
- # The transfers stay stamped deliberately: retrying means re-sending
- # this payout, never sweeping the same earnings into a second one.
- payout.update!(status: 'failed')
+ # Releasing the transfers is what makes a failure recoverable. A payout
+ # is created by the sweep and by nothing else, so transfers left
+ # stamped to a failed one are unreachable: the next sweep skips them
+ # (`unsettled` means unstamped) while the balance still reports them
+ # owed, and the seller is never paid. Released, they simply fall into
+ # the next sweep — which is the retry.
+ payout.transaction do
+ payout.transfers.update_all(payout_id: nil, updated_at: Time.current)
+ payout.update!(status: 'failed', amount: 0)
+ end
+
Rails.error.report(e, handled: true, context: { seller_payout_id: payout.id }, source: 'spree.core')
failure(payout, e.message)
end
diff --git a/spree/core/app/workflows/spree/seller_transfers/reverse.rb b/spree/core/app/workflows/spree/seller_transfers/reverse.rb
index 6dc909ee96..ac6d01ea92 100644
--- a/spree/core/app/workflows/spree/seller_transfers/reverse.rb
+++ b/spree/core/app/workflows/spree/seller_transfers/reverse.rb
@@ -18,13 +18,15 @@ module Spree
# @param order [Spree::Order] the seller order being refunded
# @param amount [BigDecimal, Numeric] how much of the earning to take
# back; capped at what is left of it
+ # @param refund [Spree::Refund, nil] what caused the clawback. The
+ # reversal's natural key, so a redelivered event reverses once.
# @return [Spree::ServiceModule::Result] value is the reversal, or the
# order when there was nothing to reverse
- def perform(order:, amount:)
+ def perform(order:, amount:, refund: nil)
super
step :find_earning
- step :bound_amount
+ step :replay_existing
run_hooks :validate
step :build_reversal
@@ -43,25 +45,46 @@ module Spree
halt!(order) if @earning.nil?
end
- # Never more than is left of the earning, however many times an order is
- # refunded: a marketplace cannot claw back more than it credited.
- def bound_amount
- @bounded = [amount.to_d.abs, @earning.reversible_amount].min
- halt!(order) if @bounded <= 0
+ # An event can be delivered twice, and a job can retry.
+ def replay_existing
+ return if refund.nil?
+
+ existing = Spree::SellerTransfer.reversals_only.find_by(refund_id: refund.id)
+ halt!(existing) if existing.present?
end
+ # Bounded and written under the earning's own lock, so two refunds
+ # landing together cannot each read the same untouched earning and each
+ # take the whole of it. The unique index on `refund_id` covers the other
+ # race — the same refund arriving twice — and resolves to the row that
+ # won rather than failing the caller.
def build_reversal
- @reversal = Spree::SellerTransfer.create!(
- seller: @earning.seller,
- order: order,
- reversed_from: @earning,
- # Negative, so what a seller has earned is the plain sum of the rows.
- amount: -@bounded,
- currency: @earning.currency,
- kind: 'refund_reversal',
- provider: @earning.provider,
- status: 'pending'
- )
+ @reversal = write_reversal
+ halt!(order) if @reversal.nil?
+ rescue ActiveRecord::RecordNotUnique
+ halt!(Spree::SellerTransfer.reversals_only.find_by!(refund_id: refund.id))
+ end
+
+ # Nil when there is nothing left to take back, which the caller turns
+ # into a halt outside the transaction — `halt!` refuses to run inside one.
+ def write_reversal
+ @earning.with_lock do
+ bounded = [amount.to_d.abs, @earning.reversible_amount].min
+ next nil if bounded <= 0
+
+ Spree::SellerTransfer.create!(
+ seller: @earning.seller,
+ order: order,
+ reversed_from: @earning,
+ refund: refund,
+ # Negative, so what a seller has earned is the plain sum of the rows.
+ amount: -bounded,
+ currency: @earning.currency,
+ kind: 'refund_reversal',
+ provider: @earning.provider,
+ status: 'pending'
+ )
+ end
end
def execute_reversal
diff --git a/spree/core/db/migrate/20260822000001_create_spree_seller_transfers.rb b/spree/core/db/migrate/20260822000001_create_spree_seller_transfers.rb
index 314da562fe..e540c89127 100644
--- a/spree/core/db/migrate/20260822000001_create_spree_seller_transfers.rb
+++ b/spree/core/db/migrate/20260822000001_create_spree_seller_transfers.rb
@@ -9,6 +9,9 @@ class CreateSpreeSellerTransfers < ActiveRecord::Migration[8.1]
t.references :payout, index: true
# The earning this row reverses, when a refund gave money back.
t.references :reversed_from, index: true
+ # Which refund caused it. The reversal's natural key — see the index
+ # below.
+ t.references :refund, index: false
t.decimal :amount, precision: 10, scale: 2, null: false, default: 0
t.string :currency, null: false
@@ -34,9 +37,17 @@ class CreateSpreeSellerTransfers < ActiveRecord::Migration[8.1]
add_index :spree_seller_transfers, [:seller_id, :currency, :status]
add_index :spree_seller_transfers, [:seller_id, :created_at]
+ # One reversal per refund. An order can be refunded many times, so the
+ # order cannot be the key here — but a single refund must claw back once
+ # however many times its event is delivered, and two refunds arriving
+ # together must not each read the same untouched earning and both take the
+ # whole of it.
+ add_index :spree_seller_transfers, :refund_id, unique: true,
+ name: 'index_seller_transfers_on_refund'
+
# A re-fired fulfillment event must find the existing row rather than
# credit the seller twice. Reversals are deliberately outside the
- # constraint: an order can be refunded more than once.
+ # order constraint: an order can be refunded more than once.
if connection.supports_partial_index?
add_index :spree_seller_transfers, :order_id, unique: true,
where: "kind = 'earning'",
diff --git a/spree/core/spec/workflows/spree/seller_payouts/complete_spec.rb b/spree/core/spec/workflows/spree/seller_payouts/complete_spec.rb
new file mode 100644
index 0000000000..37c2ffedc3
--- /dev/null
+++ b/spree/core/spec/workflows/spree/seller_payouts/complete_spec.rb
@@ -0,0 +1,57 @@
+require 'spec_helper'
+
+RSpec.describe Spree::SellerPayouts::Complete do
+ let(:store) { @default_store }
+ let(:seller) { create(:seller, :approved, store: store) }
+ let(:payout) { create(:seller_payout, seller: seller, amount: 40) }
+
+ describe 'recording that the money landed' do
+ it 'completes the settlement' do
+ expect(described_class.call(seller_payout: payout)).to be_success
+ expect(payout.reload).to be_completed
+ end
+
+ it "keeps the provider's own reference for it" do
+ described_class.call(seller_payout: payout, reference: 'BACS-9912')
+
+ expect(payout.reload.reference).to eq('BACS-9912')
+ end
+
+ it 'debits the balance, which is what completing means' do
+ create(:seller_transfer, :completed, seller: seller, amount: 40, payout: payout)
+
+ expect { described_class.call(seller_payout: payout) }.
+ to change { seller.balance('USD') }.from(40).to(0)
+ end
+ end
+
+ # An operator marking a bank transfer sent can race the provider's own
+ # webhook saying the same thing. Both pass a plain read of the status.
+ describe 'when it is recorded twice' do
+ it 'announces the settlement once' do
+ described_class.call(seller_payout: payout)
+
+ expect_any_instance_of(Spree::SellerPayout).not_to receive(:publish_event)
+
+ described_class.call(seller_payout: payout)
+ end
+
+ it 'announces it once even when both callers read it as unsettled' do
+ stale = Spree::SellerPayout.find(payout.id)
+ described_class.call(seller_payout: payout)
+
+ # `stale` still believes the payout is pending, which is exactly what a
+ # racing webhook holds.
+ expect_any_instance_of(Spree::SellerPayout).not_to receive(:publish_event)
+
+ described_class.call(seller_payout: stale)
+ end
+
+ it "does not let a blank second caller wipe the first one's reference" do
+ described_class.call(seller_payout: payout, reference: 'BACS-9912')
+ described_class.call(seller_payout: Spree::SellerPayout.find(payout.id))
+
+ expect(payout.reload.reference).to eq('BACS-9912')
+ end
+ end
+end
diff --git a/spree/core/spec/workflows/spree/seller_payouts/sweep_spec.rb b/spree/core/spec/workflows/spree/seller_payouts/sweep_spec.rb
index 634e6c034b..02026be252 100644
--- a/spree/core/spec/workflows/spree/seller_payouts/sweep_spec.rb
+++ b/spree/core/spec/workflows/spree/seller_payouts/sweep_spec.rb
@@ -109,4 +109,65 @@ RSpec.describe Spree::SellerPayouts::Sweep do
expect(seller.balance('USD')).to eq(0)
end
end
+
+ # A payout is created by the sweep and by nothing else, so earnings left
+ # stamped to a failed one would be unreachable — skipped by every later
+ # sweep while the balance still says the seller is owed them.
+ describe 'when the provider will not pay' do
+ before do
+ allow_any_instance_of(Spree::PayoutProvider::System).to receive(:pay!).and_raise(StandardError, 'gateway down')
+ end
+
+ it 'reports the failure' do
+ earn(40)
+
+ expect(described_class.call(seller: seller, currency: 'USD')).to be_failure
+ end
+
+ it 'releases the earnings so the next sweep is the retry' do
+ earn(40)
+ described_class.call(seller: seller, currency: 'USD')
+
+ expect(seller.seller_transfers.unsettled.sum(:amount)).to eq(40)
+ end
+
+ it 'still owes the seller their money' do
+ earn(40)
+ described_class.call(seller: seller, currency: 'USD')
+
+ expect(seller.balance('USD')).to eq(40)
+ end
+
+ it 'settles them on the next run' do
+ earn(40)
+ described_class.call(seller: seller, currency: 'USD')
+ allow_any_instance_of(Spree::PayoutProvider::System).to receive(:pay!).and_call_original
+
+ expect(described_class.call(seller: seller.reload, currency: 'USD').value.amount).to eq(40)
+ end
+ end
+
+ # A concurrent sweep can claim rows this one counted, leaving it holding
+ # nothing. Asking a provider to move zero is not a settlement.
+ describe 'when another sweep claimed everything first' do
+ let(:workflow) { described_class.new }
+
+ before do
+ earn(40)
+ # The other sweep wins the race: it takes the rows between this one
+ # counting them and claiming them.
+ allow(Spree::SellerTransfer).to receive(:where).and_return(Spree::SellerTransfer.none)
+ end
+
+ it 'sends nothing' do
+ expect_any_instance_of(Spree::PayoutProvider::System).not_to receive(:pay!)
+
+ described_class.call(seller: seller, currency: 'USD')
+ end
+
+ it 'keeps no empty settlement behind' do
+ expect { described_class.call(seller: seller, currency: 'USD') }.
+ not_to change { Spree::SellerPayout.count }
+ end
+ end
end
diff --git a/spree/core/spec/workflows/spree/seller_transfers/reverse_spec.rb b/spree/core/spec/workflows/spree/seller_transfers/reverse_spec.rb
index e5fee89344..f520520bb5 100644
--- a/spree/core/spec/workflows/spree/seller_transfers/reverse_spec.rb
+++ b/spree/core/spec/workflows/spree/seller_transfers/reverse_spec.rb
@@ -56,6 +56,59 @@ RSpec.describe Spree::SellerTransfers::Reverse do
end
end
+ # A subscriber job retries on error, so the same refund can be handled more
+ # than once. Without a key tying a reversal to its cause, each attempt would
+ # take the money back again.
+ describe 'when the same refund arrives twice' do
+ let(:refund) { create(:refund, amount: 30) }
+
+ it 'takes the money back once' do
+ earn(80)
+ described_class.call(order: order, amount: 30, refund: refund)
+
+ expect { described_class.call(order: order, amount: 30, refund: refund) }.
+ not_to change { Spree::SellerTransfer.count }
+
+ expect(seller.balance('USD')).to eq(50)
+ end
+
+ it 'answers with the reversal that was already written' do
+ earn(80)
+ first = described_class.call(order: order, amount: 30, refund: refund).value
+
+ expect(described_class.call(order: order, amount: 30, refund: refund).value).to eq(first)
+ end
+
+ # The read guard is not enough on its own — two deliveries can pass it
+ # together — so the database has the last word.
+ it 'refuses a second row even when the read guard is bypassed' do
+ earning = earn(80)
+
+ expect do
+ Spree::SellerTransfer.create!(
+ seller: seller, order: order, reversed_from: earning, refund: refund,
+ amount: -30, currency: 'USD', kind: 'refund_reversal', provider: 'system', status: 'pending'
+ )
+ Spree::SellerTransfer.create!(
+ seller: seller, order: order, reversed_from: earning, refund: refund,
+ amount: -30, currency: 'USD', kind: 'refund_reversal', provider: 'system', status: 'pending'
+ )
+ end.to raise_error(ActiveRecord::RecordNotUnique)
+ end
+ end
+
+ describe 'when two different refunds land on one order' do
+ it 'never takes back more than was credited between them' do
+ earn(80)
+
+ described_class.call(order: order, amount: 60, refund: create(:refund, amount: 30))
+ described_class.call(order: order, amount: 60, refund: create(:refund, amount: 30))
+
+ expect(seller.balance('USD')).to eq(0)
+ expect(Spree::SellerTransfer.reversals_only.sum(:amount)).to eq(-80)
+ end
+ end
+
# A settlement that has happened is never rewritten: the reversal is simply
# unsettled, so the next sweep nets it off what comes after.
describe 'when the earning was already settled' do