spree_core 6.0.0.rc7 → 6.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 820fa04cc9e7d880ff2a324afaf5fa2dce0f197c809b7d0af3aa59b69b65f8b6
-  data.tar.gz: be3a6fac21d4524551c479cd02b8256f34ee9957e838f382bd37555fa40e9689
+  metadata.gz: 2407d5fb2d24d9dd893a8c9dae11cfd8aba5a4b1d621a82938a2cb7009581936
+  data.tar.gz: f3384773e3442f383e979f60d58b7b06672a72065cd8d117a114ef49827fda5e
 SHA512:
-  metadata.gz: 8941ff574c4ba3455b1e67d90d500a61180d2567e6c5f5fa74e3db43aefb62d79d720753565a0ef4c29a6628f9e02a92385b6af7345548c8074815f6d212fa17
-  data.tar.gz: 9e0ac49d08274a0cc82a1aea9fb8ea74bfb093b49d276401e62e34ef57b0fee0e30b3f814d465718d2d758ab855d35a36f16b31b281245a377e7d6ced174af9f
+  metadata.gz: ebc83d9db9ebc13afea53ae0b184789f32a81121dcd9608461d93fb7e2e62b020cef774e69de3404fc0d23adb62df13f770281eacd6fd4671e5c0f5328ecae5b
+  data.tar.gz: 99ecc2439e9a73c1f805898c35e48079cd573b947110951c1a8349b26934e7ea8023b55a53cfdf1b3af94a5013290c52e5a097e4e5dff61d1249af8ca3327fb7

data/app/jobs/spree/maintenance_tasks/run_job.rb

@@ -0,0 +1,321 @@
+module Spree
+  module MaintenanceTasks
+    # Executes one Spree::MaintenanceTaskRun on Active Job Continuations
+    # (docs/plans/6.0-maintenance-tasks.md).
+    #
+    # Three things can stop a run mid-collection, and all three resolve to the
+    # same checkpoint: the worker is shutting down (Continuations re-queue the
+    # job), the execution has used its time slice (the runner re-queues
+    # itself so no single task holds a worker), or an operator asked to
+    # cancel (the Cancel service writes the request, the runner observes it
+    # here). The run row's cursor is written before each checkpoint, so
+    # whichever path fires, the next execution restarts from the same record.
+    class RunJob < ::Spree::BaseJob
+      include ActiveJob::Continuable
+
+      queue_as Spree.queues.maintenance_tasks
+
+      # A run that fails is recorded as failed; it must not be replayed by the
+      # backend behind the operator's back. Running it again is an explicit
+      # action.
+      #
+      # `inline` is a run executing in the caller's own process — the
+      # upgrade walk and the command line. It holds no worker, so it is not
+      # sliced: handing the remainder to a worker would let the caller report
+      # a step done that has not finished, on a deploy where no worker runs.
+      def perform(run_id, inline: false)
+        # Outside the steps on purpose — runs on every execution, resumes
+        # included.
+        @run = Spree::MaintenanceTaskRun.find_by(id: run_id)
+        return if @run.nil?
+        # `cancelling` counts as active: a job re-queued after its worker
+        # stopped is the only execution that will ever answer it.
+        return unless @run.active?
+
+        @task_class = @run.task_class
+        return unfindable_task if @task_class.nil?
+
+        @inline = inline
+        @execution_started_at = Time.current
+        @time_running_before = @run.time_running.to_f
+        prepare
+        return if @halted
+
+        check_operator_request
+        return if @halted
+        return refuse_duplicate if duplicate_run?
+
+        step :start
+        # Seeded from the row rather than from the continuation: the row
+        # survives a dropped job, which a re-queued execution then picks up
+        # with no continuation at all.
+        step :process_collection, start: @run.cursor
+        step :finish
+      rescue SignalException => e
+        # Ctrl-C or a deploy stopping an inline run. No job was queued for it,
+        # so nothing would ever come back to a run left `running`, and it
+        # would block every later run of its task.
+        record_error(e) if @inline && run&.reload&.active?
+        raise
+      end
+
+      private
+
+      attr_reader :run, :task
+
+      def start
+        return if run.running?
+
+        started = write_status('running', from: %w[enqueued interrupted],
+                                          started_at: run.started_at || Time.current,
+                                          job_id: job_id,
+                                          tick_total: run.tick_total || safe_count)
+        # An operator cancelled the run after the check above.
+        return check_operator_request unless started
+
+        publish('started')
+      rescue StandardError => e
+        record_error(e)
+      end
+
+      # Outside the steps, so an error here would never reach the rescues
+      # below: a run whose arguments no longer fit its task (a deploy removed
+      # a parameter) would stay queued forever, or be resumed by Continuations
+      # without end. Recorded as a failure instead.
+      def prepare
+        @task = @task_class.new(@run.arguments.presence || {})
+        @task.run = @run
+        resume_after_time_slice
+      rescue StandardError => e
+        record_error(e)
+      end
+
+      # One run per task is checked when a run is created, but two requests
+      # can both pass that check before either is saved. The older run wins,
+      # so the outcome does not depend on which worker picks a job up first.
+      def duplicate_run?
+        return false unless run.enqueued?
+
+        run.class.active.where(task_name: run.task_name).where(run.class.arel_table[:id].lt(run.id)).exists?
+      end
+
+      def refuse_duplicate
+        close_run('cancelled', 'Spree::MaintenanceTasks::AlreadyRunning',
+                  "#{run.task_api_type} was already running, so this run did not start")
+        publish('cancelled')
+      end
+
+      # Continuations skip `start` once it has completed, so an execution
+      # picking up after its time slice would otherwise keep reporting
+      # `interrupted` while it works — and the Cancel service would treat it as
+      # idle. Conditional, so a cancel written while the job sat
+      # in the queue is not overwritten.
+      def resume_after_time_slice
+        return unless run.interrupted?
+
+        run.class.where(id: run.id, status: 'interrupted').update_all(status: 'running', updated_at: Time.current)
+        run.reload
+      end
+
+      # The collection walk. Batches are fetched by cursor rather than by
+      # offset so a resumed execution reads nothing it has already processed.
+      def process_collection(step)
+        return if @halted
+
+        if task.no_collection?
+          process_single
+          return
+        end
+
+        loop do
+          break if @halted
+
+          items = next_batch(step.cursor)
+          break if items.empty?
+
+          process_batch(items)
+          break if @halted
+
+          # One cursor value, the last id seen, written to the row and to the
+          # continuation. Persisted before the checkpoint — an interruption
+          # between these two lines must not lose the batch already applied.
+          cursor = items.last.id.to_s
+          persist_progress(cursor: cursor, count: items.size)
+          step.set!(cursor)
+
+          check_operator_request
+          check_time_slice(step)
+        end
+      rescue StandardError => e
+        # Not discard_on: Continuations resume errors raised after progress,
+        # so a discard handler would never see them and the run would loop.
+        record_error(e)
+      end
+
+      # The callback runs before the row is written so a task can summarise in
+      # `after_complete` — tallying there and persisting first would silently
+      # drop whatever it recorded.
+      def finish
+        return if @halted
+
+        task.after_complete
+        return check_operator_request unless write_status('succeeded', from: 'running',
+                                                                       ended_at: Time.current,
+                                                                       tallies: merged_tallies)
+
+        publish('succeeded')
+      rescue StandardError => e
+        record_error(e)
+      end
+
+      # A no_collection task is one unit of work: no cursor, no partial
+      # progress, and an error fails the whole run.
+      def process_single
+        task.process
+        persist_progress(cursor: nil, count: 1)
+      rescue StandardError => e
+        record_error(e)
+      end
+
+      def process_batch(items)
+        items.each { |item| task.process(item) }
+      end
+
+      # Cursor-paged rather than find_each: the cursor has to survive between
+      # executions, which an in-memory batch enumerator cannot do.
+      def next_batch(cursor)
+        scope = task.collection
+        scope = scope.where(scope.arel_table[scope.primary_key].gt(cursor)) if cursor.present?
+        scope.limit(task.class.batch_size).to_a
+      end
+
+      # update_columns rather than update!: progress is written on every batch
+      # and carries no validation of its own.
+      def persist_progress(cursor:, count:)
+        run.update_columns(
+          cursor: cursor,
+          tick_count: run.tick_count + count,
+          tallies: merged_tallies,
+          time_running: accumulated_time,
+          updated_at: Time.current
+        )
+      end
+
+      # Cancel is a request written to the row by the Cancel service; the
+      # runner is the only writer of the resulting state, so a killed worker
+      # can never leave `cancelled` on a run that is still moving.
+      #
+      # Read once per batch rather than on a timer: a primary-key read costs
+      # nothing beside the batch of writes it follows, and a time-based
+      # throttle would make a fast task ignore a cancel altogether — the
+      # batches would all land inside one interval.
+      def check_operator_request
+        requested = run.class.where(id: run.id).pick(:status)
+        return unless requested.in?(%w[cancelling cancelled])
+
+        write_status('cancelled', from: requested, ended_at: Time.current, time_running: accumulated_time)
+        publish('cancelled')
+        @halted = true
+      end
+
+      # The control services write to the same row this job holds in memory,
+      # so the write only lands while the row is still in the status the
+      # runner expects. Otherwise an operator's cancel, written
+      # between the runner's read and its write, would be overwritten.
+      #
+      # @return [Boolean] whether the row was in an expected status
+      def write_status(status, from:, **attributes)
+        written = run.class.where(id: run.id, status: from).
+                  update_all(status: status, updated_at: Time.current, **attributes)
+        run.reload
+        written.positive?
+      end
+
+      def check_time_slice(step)
+        return if @inline
+        return if Time.current - @execution_started_at < Spree::MaintenanceTask::MAX_RUN_TIME
+
+        return check_operator_request unless write_status('interrupted', from: 'running',
+                                                                         time_running: accumulated_time)
+
+        publish('interrupted')
+        # Raises Continuation::Interrupt, which inherits Exception and is
+        # never caught by the rescues above.
+        interrupt!(reason: :run_time_limit)
+      end
+
+      # Recording a failure must never fail. This is the last thing standing
+      # between a crashed task and a run stuck in `running` forever, so it
+      # writes columns directly rather than going through validations that
+      # could reject the very state that describes the problem.
+      def record_error(error)
+        run.reload
+        run.update_columns(
+          status: 'errored',
+          ended_at: Time.current,
+          time_running: accumulated_time,
+          tallies: merged_tallies,
+          error_class: error.class.name,
+          error_message: error.message.to_s.truncate(1000),
+          error_backtrace: cleaned_backtrace(error),
+          updated_at: Time.current
+        )
+        publish('errored')
+        Rails.error.report(error, handled: true)
+        @halted = true
+      end
+
+      def cleaned_backtrace(error)
+        return nil if error.backtrace.blank?
+
+        Rails.backtrace_cleaner.clean(error.backtrace).first(50).join("\n")
+      end
+
+      # The task was removed from the registry between enqueue and execution —
+      # a deploy that dropped it. Recorded rather than raised: retrying cannot
+      # bring the class back.
+      def unfindable_task
+        close_run('errored', 'Spree::MaintenanceTasks::TaskNotRegistered',
+                  "#{run.task_name} is not a registered maintenance task")
+      end
+
+      # Ends a run that never started work, so there is nothing to tally.
+      def close_run(status, error_class, error_message)
+        run.update_columns(status: status, ended_at: Time.current, error_class: error_class,
+                           error_message: error_message, updated_at: Time.current)
+      end
+
+      # Summed, not replaced: a task instance counts only what the current
+      # execution did, so an interrupted run that merged would report its last
+      # slice as the whole total. Baselined at the first checkpoint of each
+      # execution so repeated writes within one execution stay accurate.
+      def merged_tallies
+        @tally_baseline ||= (run.tallies || {}).dup
+        return @tally_baseline.dup if task.nil?
+
+        task.tallies.each_with_object(@tally_baseline.dup) do |(key, value), result|
+          result[key] = result.fetch(key, 0) + value
+        end
+      end
+
+      # From the total this execution started with, never the row's current
+      # value: progress rewrites the row every batch, so adding elapsed time
+      # to it would count the same seconds again on each write.
+      def accumulated_time
+        return run.time_running if @execution_started_at.nil?
+
+        @time_running_before + (Time.current - @execution_started_at)
+      end
+
+      def safe_count
+        task.count
+      rescue StandardError
+        nil
+      end
+
+      def publish(event)
+        run.publish_event("maintenance_task_run.#{event}")
+      end
+    end
+  end
+end

data/app/jobs/spree/seller_transfers/execute_pending_due_job.rb

@@ -1,6 +1,7 @@
 module Spree
   module SellerTransfers
-    # Hands every seller holding an unconfirmed earning to a job of their own.
+    # Hands every seller holding an unconfirmed earning or reversal to a job of
+    # their own.
     #
     # The transfer level's counterpart to {Spree::SellerPayouts::SweepDueJob},
     # and deliberately a separate schedule rather than something the settlement
@@ -39,17 +40,18 @@ module Spree
       # @param store [Spree::Store]
       # @return [ActiveRecord::Relation<Spree::Seller>]
       def sellers_awaiting_provider(store)
-        scope = store.sellers.approved.
-                where(id: Spree::SellerTransfer.for_store(store).awaiting_provider.select(:seller_id))
+        transfers = Spree::SellerTransfer.for_store(store)
+        sending = store.sellers.approved.where(id: transfers.awaiting_provider.select(:seller_id))
 
         # A seller the provider will not accept yet keeps their earnings
         # unconfirmed, and the job would return at once. Skipped rather than
         # enqueued, because a marketplace's half-onboarded sellers are a
         # standing population and this runs often — and nothing is lost by it:
         # finishing onboarding runs the job for them directly.
-        return scope unless store.payout_provider_class.requires_payout_account?
+        sending = sending.where.not(payouts_enabled_at: nil) if store.payout_provider_class.requires_payout_account?
 
-        scope.where.not(payouts_enabled_at: nil)
+        # Money owed back is pursued whatever the seller's standing.
+        sending.or(store.sellers.where(id: transfers.reversals_awaiting_provider.select(:seller_id)))
       end
     end
   end

data/app/jobs/spree/seller_transfers/execute_pending_job.rb

@@ -14,6 +14,9 @@ module Spree
     # seller who was payable all along would never see a refused earning tried
     # again, since nothing about them ever changes to prompt it.
     #
+    # Reversals are retried the same way: a provider that pulls money back can
+    # refuse too, and one cannot be pulled back before its earning was sent.
+    #
     # It takes the retryable rows — never sent, or refused outright. A transfer
     # whose outcome the provider could not report is left alone: asking again
     # is precisely how the same money moves twice, and only a person can say
@@ -24,30 +27,47 @@ module Spree
       # @param seller_id [Integer]
       def perform(seller_id)
         seller = Spree::Seller.find_by(id: seller_id)
-        return if seller.nil? || !seller.payouts_enabled?
+        return if seller.nil?
 
         Spree::Current.store = seller.store
+        send_earnings(seller) if seller.payouts_enabled?
+
+        # Never through `transfer!`: a reversal's amount is negative, and the
+        # amount sent is its absolute value, so it would pay the seller the
+        # money it exists to take back. Through the provider that made the
+        # earning, which is not necessarily the store's current one. And for
+        # every seller, payable or not — a seller suspended after a wave of
+        # refunds is exactly the one whose money must come back.
+        seller.seller_transfers.reversals_awaiting_provider.includes(:reversed_from, :order).find_each do |reversal|
+          execute(reversal) { reversal.payout_provider_instance.reverse!(reversal) }
+        end
+      end
+
+      private
+
+      # Before the reversals, so a reversal waiting on its earning finds it sent.
+      def send_earnings(seller)
         provider = seller.store.payout_provider_instance
 
-        # Earnings only — see the scope. A reversal is retryable the same way
-        # when its own provider call is refused, but sending one through
-        # `transfer!` would pay the seller the amount it exists to take back:
-        # the row is negative and the amount sent is its absolute value.
         seller.seller_transfers.awaiting_provider.find_each do |transfer|
-          provider.transfer!(transfer)
-        rescue Spree::Core::AmbiguousGatewayError => e
-          # The money may already have moved, so this row must not be offered
-          # again: left retryable, the next run would send it a second time,
-          # and an idempotency key stops that only while the provider still
-          # holds its record.
-          transfer.update!(status: 'unresolved')
-          Rails.error.report(e, handled: true, context: { seller_transfer_id: transfer.id }, source: 'spree.core')
-        rescue StandardError => e
-          # A refusal — the money did not move. One seller's stuck earning must
-          # not stop the rest, and the row stays retryable for the next run.
-          Rails.error.report(e, handled: true, context: { seller_transfer_id: transfer.id }, source: 'spree.core')
+          execute(transfer) { provider.transfer!(transfer) }
         end
       end
+
+      def execute(transfer)
+        yield
+      rescue Spree::Core::AmbiguousGatewayError => e
+        # The money may already have moved, so this row must not be offered
+        # again: left retryable, the next run would move it a second time,
+        # and an idempotency key stops that only while the provider still
+        # holds its record.
+        transfer.update!(status: 'unresolved')
+        Rails.error.report(e, handled: true, context: { seller_transfer_id: transfer.id }, source: 'spree.core')
+      rescue StandardError => e
+        # A refusal — the money did not move. One stuck row must not stop the
+        # rest, and it stays retryable for the next run.
+        Rails.error.report(e, handled: true, context: { seller_transfer_id: transfer.id }, source: 'spree.core')
+      end
     end
   end
 end

data/app/maintenance_tasks/spree/maintenance_tasks/upgrade/backfill_order_markets.rb

@@ -0,0 +1,48 @@
+module Spree
+  module MaintenanceTasks
+    module Upgrade
+      # 5.6 → 6.0: market is mandatory on orders in Spree 6, and orders placed
+      # before markets existed carry NULLs. Each order takes its own store's
+      # default market, so the walk is per order rather than one UPDATE per
+      # store — that is what gives the run a cursor to resume from and a
+      # progress bar to watch on a catalog-sized table.
+      #
+      # Orders whose store has no default market are counted and left alone;
+      # there is nothing to assign, and failing the run would strand every
+      # other store's orders behind them.
+      class BackfillOrderMarkets < Spree::MaintenanceTask
+        supports_dry_run
+        collection_batch_size 500
+
+        def collection
+          Spree::Order.unscoped.where(market_id: nil).order(:id)
+        end
+
+        def process(order)
+          market_id = default_market_id_for(order.store_id)
+
+          if market_id.nil?
+            tally(:skipped_no_default_market)
+            return
+          end
+
+          return tally(:would_update) if dry_run?
+
+          order.update_columns(market_id: market_id, updated_at: Time.current)
+          tally(:updated)
+        end
+
+        private
+
+        # One lookup per store rather than per order: a backfill of this size
+        # walks the same handful of stores over and over.
+        def default_market_id_for(store_id)
+          @default_market_ids ||= {}
+          return @default_market_ids[store_id] if @default_market_ids.key?(store_id)
+
+          @default_market_ids[store_id] = Spree::Store.find_by(id: store_id)&.default_market&.id
+        end
+      end
+    end
+  end
+end

data/app/maintenance_tasks/spree/maintenance_tasks/upgrade/capture_methods.rb

@@ -0,0 +1,40 @@
+module Spree
+  module MaintenanceTasks
+    module Upgrade
+      # 5.6 → 6.0 conversion of the per-payment-method auto_capture boolean onto
+      # the capture_method vocabulary (docs/plans/6.0-store-scoped-configuration.md).
+      #
+      # A method that captured on authorization charges at checkout. One that
+      # did not only recorded "not at checkout" — the old column could not say
+      # whether dispatch or staff was meant to take the money, and the store's
+      # own setting is what decided. Leaving those rows empty is what makes them
+      # keep inheriting it, so only the true case is written here, and the
+      # collection is the true case alone: any other scope would never reach
+      # zero remaining.
+      class CaptureMethods < Spree::MaintenanceTask
+        supports_dry_run
+        collection_batch_size 5_000
+
+        def collection
+          Spree::PaymentMethod.unscoped.where(capture_method: nil, auto_capture: true).order(:id)
+        end
+
+        def process(payment_method)
+          return tally(:would_convert) if dry_run?
+
+          payment_method.update_columns(capture_method: 'checkout', updated_at: Time.current)
+          tally(:converted)
+        end
+
+        # Rows the conversion deliberately leaves alone, reported once so an
+        # operator can see they were considered rather than missed.
+        def after_complete
+          return if dry_run?
+
+          inheriting = Spree::PaymentMethod.unscoped.where(capture_method: nil, auto_capture: false).count
+          tally(:left_inheriting_store_setting, inheriting) if inheriting.positive?
+        end
+      end
+    end
+  end
+end

data/app/maintenance_tasks/spree/maintenance_tasks/upgrade/deliveries.rb

@@ -0,0 +1,15 @@
+module Spree
+  module MaintenanceTasks
+    module Upgrade
+      # Creates a delivery for every fulfillment that carries a 5.6 tracking
+      # number, moving carrier tracking onto its own record.
+      class Deliveries < RakeStep
+        runs_rake_task 'spree:migrate_deliveries'
+
+        attribute :batch_size, :integer, default: 1_000
+
+        passes_to_environment :batch_size, as: 'BATCH_SIZE'
+      end
+    end
+  end
+end

data/app/maintenance_tasks/spree/maintenance_tasks/upgrade/order_coupon_codes.rb

@@ -0,0 +1,15 @@
+module Spree
+  module MaintenanceTasks
+    module Upgrade
+      # Copies the coupon code a placed order was bought with onto the order
+      # itself.
+      class OrderCouponCodes < RakeStep
+        runs_rake_task 'spree:backfill_order_coupon_codes'
+
+        attribute :batch_size, :integer, default: 500
+
+        passes_to_environment :batch_size, as: 'BATCH_SIZE'
+      end
+    end
+  end
+end

data/app/maintenance_tasks/spree/maintenance_tasks/upgrade/promotion_option_value_rules.rb

@@ -0,0 +1,15 @@
+module Spree
+  module MaintenanceTasks
+    module Upgrade
+      # Rewrites Option Value promotion rules so they reference option values
+      # directly rather than the join rows they used to point at.
+      class PromotionOptionValueRules < RakeStep
+        runs_rake_task 'spree:upgrade:migrate_promotion_option_value_rules'
+
+        attribute :skip_failed_rows, :boolean, default: false
+
+        passes_to_environment :skip_failed_rows, as: 'SKIP_FAILED_ROWS'
+      end
+    end
+  end
+end

data/app/maintenance_tasks/spree/maintenance_tasks/upgrade/rake_step.rb

@@ -0,0 +1,83 @@
+module Spree
+  module MaintenanceTasks
+    module Upgrade
+      # Base for the one-pass upgrade steps that ask the operator for parameters
+      # (docs/plans/6.0-maintenance-tasks.md). The rake body stays the
+      # implementation; this class only maps its parameters onto the environment
+      # variables the body reads. A step without parameters runs through
+      # `UpgradeStep` and needs no class at all.
+      class RakeStep < Spree::MaintenanceTask
+        ENVIRONMENT_LOCK = Mutex.new
+
+        no_collection
+
+        class_attribute :rake_task_name, instance_writer: false
+        class_attribute :environment_parameters, instance_writer: false, default: {}.freeze
+
+        # @param name [String] the rake task this step runs
+        def self.runs_rake_task(name)
+          self.rake_task_name = name
+        end
+
+        # Declares a parameter the rake body reads from the environment.
+        #
+        # These bodies were written for a shell, so their answers arrive as
+        # environment variables. Mapping them to attributes records the answer
+        # on the run, and lets `ARGS` supply it when the step is run on its own.
+        #
+        # @param attribute_name [Symbol]
+        # @param as [String] the environment variable the body reads
+        def self.passes_to_environment(attribute_name, as:)
+          self.environment_parameters = environment_parameters.merge(attribute_name.to_sym => as).freeze
+        end
+
+        # The declared parameters an operator exported before running the
+        # upgrade walk, so the walk passes them on rather than letting each
+        # attribute's default overwrite them.
+        #
+        # @return [Hash{String => String}]
+        def self.arguments_from_environment
+          environment_parameters.each_with_object({}) do |(attribute_name, variable), arguments|
+            arguments[attribute_name.to_s] = ENV[variable] if ENV.key?(variable)
+          end
+        end
+
+        def process
+          with_environment { invoke_rake_task(self.class.rake_task_name) }
+        end
+
+        private
+
+        # Restored afterwards so one run never leaks its answers into the next.
+        # ENV is shared by the whole process, so two steps running at once in a
+        # threaded worker take turns rather than reading each other's answers.
+        def with_environment(&block)
+          return yield if self.class.environment_parameters.empty?
+
+          ENVIRONMENT_LOCK.synchronize { with_variables_set(&block) }
+        end
+
+        def with_variables_set
+          keys = self.class.environment_parameters.values
+          previous = ENV.to_h.slice(*keys)
+
+          self.class.environment_parameters.each do |attribute_name, variable|
+            ENV[variable] = environment_value(public_send(attribute_name))
+          end
+
+          yield
+        ensure
+          keys&.each { |key| ENV[key] = previous[key] }
+        end
+
+        def environment_value(value)
+          case value
+          when true then 'true'
+          when false, nil then nil
+          else value.to_s.presence
+          end
+        end
+      end
+    end
+  end
+end

data/app/maintenance_tasks/spree/maintenance_tasks/upgrade/returns.rb

@@ -0,0 +1,20 @@
+module Spree
+  module MaintenanceTasks
+    module Upgrade
+      # Moves return authorizations onto the 6.0 Return and Exchange models.
+      #
+      # Resumable by construction: the legacy number is copied onto the new
+      # record and uniquely indexed there, so what is still outstanding is a
+      # query rather than tracked state.
+      class Returns < RakeStep
+        runs_rake_task 'spree:upgrade:migrate_returns'
+
+        attribute :skip_failed_rows, :boolean, default: false
+        attribute :batch_size, :integer, default: 500
+
+        passes_to_environment :skip_failed_rows, as: 'SKIP_FAILED_ROWS'
+        passes_to_environment :batch_size, as: 'BATCH_SIZE'
+      end
+    end
+  end
+end