spree_core 5.6.1 → 6.0.0.beta2

data/lib/spree/validators.rb

@@ -0,0 +1,74 @@
+module Spree
+  # Registry of extra validator classes run against a model on top of its own
+  # validations. Addresses are the one model that ships with it, because
+  # address rules are regional and business-specific — phone formats, VAT
+  # numbers, address verification — and a host needs to add and remove them
+  # without reopening the model.
+  #
+  #   Spree.validators.addresses.register(MyStore::PostBoxValidator)
+  #   Spree.validators.addresses.unregister(Spree::Addresses::PhoneValidator)
+  #
+  # Register from `config.to_prepare` (not an initializer) when the validator
+  # is your own class: the set holds classes, so a reloadable constant
+  # registered once at boot would go stale on the next reload.
+  #
+  # For rules that veto a whole flow rather than shape a record, use a
+  # workflow :validate hook instead (see Spree::Hooks).
+  class Validators
+    # One named set of validator classes. Subclasses Array so the historical
+    # `Spree.validators.addresses` — which was a plain array of classes, and
+    # which hosts may already read, map or push onto — keeps behaving exactly
+    # as it did; register/unregister are the documented API on top.
+    class Set < Array
+      def initialize(entries = [])
+        super()
+        replace(entries)
+      end
+
+      # @param validator [Class, String] class responding to the
+      #   ActiveModel::Validator contract
+      # @return [Class] the registered validator
+      def register(validator)
+        resolved = resolve(validator)
+        push(resolved) unless include?(resolved)
+        resolved
+      end
+
+      # @param validator [Class, String]
+      # @return [Class, nil] the removed validator, nil when not registered
+      def unregister(validator)
+        delete(resolve(validator))
+      end
+
+      def replace(entries)
+        super(Array(entries).map { |entry| resolve(entry) })
+      end
+
+      private
+
+      def resolve(validator)
+        validator.is_a?(String) || validator.is_a?(Symbol) ? validator.to_s.constantize : validator
+      end
+    end
+
+    def initialize
+      @sets = Hash.new { |sets, name| sets[name] = Set.new }
+    end
+
+    def [](name)
+      @sets[name.to_sym]
+    end
+
+    def []=(name, entries)
+      @sets[name.to_sym] = Set.new(entries)
+    end
+
+    def addresses
+      self[:addresses]
+    end
+
+    def addresses=(entries)
+      self[:addresses] = entries
+    end
+  end
+end

data/lib/spree/workflow.rb

@@ -0,0 +1,335 @@
+require 'spree/service_module'
+require 'spree/hooks'
+
+module Spree
+  # Workflow — Tier 2 of the services doctrine
+  # (docs/plans/6.0-service-workflows.md): named steps inside a plain
+  # #perform method, the ActiveJob::Continuable shape.
+  #
+  #   class Spree::Orders::Cancel < Spree::Workflow
+  #     hooks :after_cancel
+  #     attr_reader :cancellation          # derived state hook handlers may read
+  #
+  #     # @param order [Spree::Order] the order to cancel
+  #     def perform(order:, canceler: nil, reason: 'other')
+  #       super
+  #
+  #       step :ensure_cancellable
+  #       ApplicationRecord.transaction do
+  #         step :record_cancellation
+  #         run_hooks :after_cancel
+  #       end
+  #       external_step :settle_payments
+  #       order.publish_event('order.canceled')
+  #       success(order.reload)
+  #     rescue ActiveRecord::RecordInvalid
+  #       failure(order)
+  #     end
+  #   end
+  #
+  # The #perform signature IS the argument contract: Ruby itself raises on
+  # missing or unknown keywords, YARD documents it. A bare `super` first
+  # assigns every parameter — defaults applied — to an instance variable
+  # with a public reader, so step bodies and hook handlers read plain
+  # methods. Everything else is ordinary Rails: plain transactions and
+  # locks, plain `if`, plain `rescue`, `publish_event` for announcements.
+  #
+  # The workflow vocabulary is five words. `step :name` runs the method of
+  # that name (instrumented as 'step.spree_workflow'); `on_flow_failure:`
+  # names its undo, armed when the surrounding transaction commits and run
+  # in reverse when a later step fails; `with:` delegates the step to a
+  # collaborator resolved from the lambda, its keyword arguments sliced
+  # from this workflow's readers. `external_step` marks gateway/network
+  # I/O and refuses to run inside a database transaction. `run_hooks`
+  # dispatches a declared extension point (see .hooks) with the workflow
+  # instance. `failure(...)` aborts the flow from anywhere — it raises
+  # internally, so an open plain transaction rolls back naturally — and
+  # `halt!(value)` is its successful twin (outside transactions only).
+  class Workflow
+    prepend Spree::ServiceModule::Base
+
+    class ContractError < StandardError; end
+
+    # Internal control flow — Exception, not StandardError (the ActiveJob
+    # Continuation::Interrupt precedent), so a plain `rescue` inside
+    # #perform can't swallow it.
+    class FailureSignal < Exception # rubocop:disable Lint/InheritException
+      attr_reader :result
+
+      def initialize(result)
+        @result = result
+        super('workflow failure')
+      end
+    end
+
+    class Halted < Exception # rubocop:disable Lint/InheritException
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+        super('workflow halted')
+      end
+    end
+
+    # failure(...) must abort the flow, but the prepended ServiceModule
+    # helper sits ahead of this class in the lookup chain — this module
+    # sits ahead of both, builds the Result via super and raises it.
+    module ControlFlow
+      def failure(value = nil, error = nil)
+        raise FailureSignal.new(super)
+      end
+    end
+    prepend ControlFlow
+
+    # ActiveModel::Errors asks its base for these when turning a symbolic
+    # error into a message — a workflow is not a model, but it answers the
+    # same three questions so `errors.add(:field, :symbol)` resolves against
+    # the workflow's own i18n scope.
+    extend ActiveModel::Naming
+    extend ActiveModel::Translation
+
+    class << self
+      attr_reader :declared_hooks
+
+      # Anonymous test doubles have no name to derive a model name from.
+      def model_name
+        @model_name ||= ActiveModel::Name.new(self, nil, name || 'Workflow')
+      end
+
+      # A subclass inherits the parent's declared hooks but dispatches them
+      # under its OWN key — Spree::Orders::AddItem fires
+      # 'orders.add_item.validate', not the cart key — so it registers
+      # itself too, otherwise Spree.hooks.validate! rejects registrations
+      # against a twin's perfectly valid hook.
+      def inherited(subclass)
+        super
+        inherited_hooks = (declared_hooks || []).dup
+        subclass.instance_variable_set(:@declared_hooks, inherited_hooks)
+        Spree.hooks.register_workflow(subclass.workflow_key, subclass.name) if inherited_hooks.any? && subclass.name
+      end
+
+      # Dotted identity used for hook keys and instrumentation; derived
+      # from the class name (Spree::Carts::AddItem => 'carts.add_item')
+      # unless set explicitly.
+      def workflow_key(value = nil)
+        @workflow_key = value.to_s if value
+        @workflow_key ||= name.delete_prefix('Spree::').split('::').map(&:underscore).join('.')
+      end
+
+      # Declares the extension points this workflow dispatches via
+      # run_hooks. Class-level so Spree.hooks.validate! can fail boot on
+      # registrations against hooks that don't exist.
+      def hooks(*names)
+        @declared_hooks = (declared_hooks || []) | names.map(&:to_sym)
+        Spree.hooks.register_workflow(workflow_key, self.name)
+      end
+
+      # Public readers for #perform's parameters, memoized per class. An
+      # author-defined method of the same name wins.
+      #
+      # Note for workflow authors: inside #perform, a parameter name is a
+      # local variable and shadows the reader, so a step that reassigns the
+      # ivar (`@product = ...`) is invisible to `success(product)` further
+      # down. Name derived state differently from the parameter that seeded
+      # it — Carts::AddItem takes `variant` and exposes `line_item`.
+      def define_argument_readers(names)
+        @argument_readers ||= {}
+        names.each do |name|
+          next if @argument_readers[name]
+
+          @argument_readers[name] = true
+          next if method_defined?(name) || private_method_defined?(name)
+
+          define_method(name) { instance_variable_get(:"@#{name}") }
+        end
+      end
+    end
+
+    # Bare `super` from the subclass's #perform lands here with the
+    # parameter values as currently bound — defaults applied — and turns
+    # each into an ivar + public reader.
+    def perform(**arguments)
+      arguments.each { |name, value| instance_variable_set(:"@#{name}", value) }
+      self.class.define_argument_readers(arguments.keys)
+    end
+
+    def call(**kwargs)
+      @undo_stack = []
+      @outer_transaction_depth = ApplicationRecord.connection.open_transactions
+
+      ActiveSupport::Notifications.instrument(
+        'perform.spree_workflow', workflow: self.class.workflow_key
+      ) do |payload|
+        outcome = perform(**kwargs)
+        result = outcome.is_a?(Spree::ServiceModule::Result) ? outcome : success(outcome)
+        payload[:outcome] = result.success? ? 'success' : 'failure'
+        result
+      rescue Halted => halted
+        payload[:outcome] = 'success'
+        success(halted.value)
+      rescue FailureSignal => signal
+        payload[:outcome] = 'failure'
+        run_undo_stack!
+        signal.result
+      rescue StandardError
+        payload[:outcome] = 'error'
+        run_undo_stack!
+        raise
+      end
+    end
+
+    # Successful early exit from anywhere — the caller receives
+    # success(value). Not from inside a transaction the workflow itself
+    # opened: there is nothing committed to halt with (use failure to
+    # roll back). A transaction the caller wrapped around the whole run
+    # is theirs to commit and doesn't count.
+    def halt!(value)
+      raise ContractError, 'halt! cannot be called inside a database transaction' if in_workflow_transaction?
+
+      raise Halted.new(value)
+    end
+
+    # Rejections a handler collected, rendered by the API through the same
+    # path as model validation errors — an extension veto and a failed
+    # `validates` produce the same 422 shape.
+    #
+    # @return [ActiveModel::Errors]
+    def errors
+      @errors ||= ActiveModel::Errors.new(self)
+    end
+
+    delegate :model_name, to: :class
+
+    # ActiveModel::Errors reads attribute values off its base when
+    # interpolating a message; a workflow's "attributes" are its argument
+    # readers, and an error on an attribute the workflow doesn't expose
+    # (:base, or a field name belonging to the record) must not raise.
+    def read_attribute_for_validation(attribute)
+      respond_to?(attribute) ? public_send(attribute) : nil
+    end
+
+    # Vetoes the flow from a hook handler — the extension-facing twin of
+    # failure(...). Same mechanics (raises, unwinds the undo stack, rolls
+    # back an open transaction); the distinct name keeps "an extension
+    # rejected this" legible against "this step failed" at the call site.
+    # Public because handlers call it on the dispatched instance.
+    #
+    # Preferred form is argument-less, after adding symbolic errors:
+    #
+    #   workflow.errors.add(:quantity, :purchase_limit_exceeded, message: '…')
+    #   workflow.reject!
+    #
+    # @param message [String, Symbol, nil] the rejection. Prefer a symbol: it
+    #   lands in `errors.details` as a code the dashboard translates itself.
+    #   Spree's copy lives outside the scopes Rails resolves a bare symbol
+    #   against, so pass the text alongside it as `message:`.
+    # @param value [Object, nil] subject of the failure Result
+    # @param options [Hash] forwarded to `errors.add` — `message:` for the
+    #   resolved text, plus any interpolation values
+    def reject!(message = nil, value = nil, **options)
+      errors.add(:base, message, **options) if message.present?
+      failure(value, errors)
+    end
+
+    private
+
+    def step(name, with: nil, on_flow_failure: nil, external: false)
+      outcome = ActiveSupport::Notifications.instrument(
+        'step.spree_workflow', workflow: self.class.workflow_key, step: name, external: external
+      ) do |payload|
+        result = with ? call_collaborator(instance_exec(&with)) : send(name)
+        payload[:outcome] = result.is_a?(Spree::ServiceModule::Result) && result.failure? ? 'failure' : 'success'
+        result
+      end
+
+      raise FailureSignal.new(outcome) if outcome.is_a?(Spree::ServiceModule::Result) && outcome.failure?
+
+      arm_undo(on_flow_failure) if on_flow_failure
+      outcome
+    end
+
+    # Gateway/network I/O — must never share a database transaction the
+    # workflow opened (a caller-level wrapping transaction is the caller's
+    # responsibility). Marks the notification payload `external: true` so
+    # tracing subscribers render it as an outbound (client) call.
+    def external_step(name, **options)
+      raise ContractError, "external_step #{name} must not run inside a database transaction" if in_workflow_transaction?
+
+      step(name, external: true, **options)
+    end
+
+    # Dispatches every handler registered for this extension point with
+    # the workflow instance — argument readers plus whatever the workflow
+    # exposes via attr_reader are the handler's contract.
+    #
+    # @return [Hash] the deep-merged hashes handlers returned. Context hooks
+    #   consume it (`context = run_hooks(:set_pricing_context)`); lifecycle
+    #   hooks ignore it and validate handlers abort via #reject! instead.
+    def run_hooks(name)
+      unless self.class.declared_hooks&.include?(name.to_sym)
+        raise ContractError, "#{self.class.name} does not declare hook :#{name} — add `hooks :#{name}` to the class"
+      end
+
+      key = "#{self.class.workflow_key}.#{name}"
+      ActiveSupport::Notifications.instrument(
+        'hooks.spree_workflow',
+        workflow: self.class.workflow_key, hook: name.to_sym, handler_count: Spree.hooks.handler_count(key)
+      ) do
+        Spree.hooks.dispatch(key, self)
+      end
+    end
+
+    # Undo methods arm when the workflow-opened transaction around their
+    # step commits — inside a rolled-back transaction the rollback already
+    # was the undo.
+    def arm_undo(name)
+      if in_workflow_transaction?
+        ApplicationRecord.current_transaction.after_commit { @undo_stack << name.to_sym }
+      else
+        @undo_stack << name.to_sym
+      end
+    end
+
+    def run_undo_stack!
+      return if @undo_stack.nil?
+
+      @undo_stack.reverse_each do |undo|
+        send(undo)
+      rescue StandardError => e
+        Rails.error.report(e, context: { workflow: self.class.workflow_key }, source: 'spree.workflow')
+      end
+      @undo_stack = []
+    end
+
+    # A transaction opened during this run (fixture wrappers and
+    # caller-level transactions sit at or below the baseline).
+    def in_workflow_transaction?
+      ApplicationRecord.connection.open_transactions > (@outer_transaction_depth || 0)
+    end
+
+    # Calls a with: collaborator, slicing its keyword arguments from this
+    # workflow's readers. Workflow collaborators declare their contract on
+    # #perform; ServiceModule collaborators on the #call the author wrote
+    # (behind the prepended wrappers).
+    def call_collaborator(callable)
+      wanted = collaborator_keywords(callable)
+      arguments = wanted.select { |name| respond_to?(name) }.index_with { |name| public_send(name) }
+      callable.call(**arguments)
+    end
+
+    def collaborator_keywords(callable)
+      target =
+        if callable.is_a?(Class) && callable < Spree::Workflow
+          callable.instance_method(:perform)
+        elsif callable.respond_to?(:new)
+          method = callable.instance_method(:call)
+          method = method.super_method while [Spree::ServiceModule::Base, ControlFlow].include?(method.owner) && method.super_method
+          method
+        else
+          callable.method(:call)
+        end
+
+      target.parameters.filter_map { |type, name| name if [:key, :keyreq].include?(type) }
+    end
+  end
+end

data/lib/tasks/backfill_actor_types.rake

@@ -0,0 +1,35 @@
+namespace :spree do
+  namespace :upgrade do
+    desc <<~DESC
+      Names the admin user class on every "who did this" row written before
+      those associations became polymorphic (Spree 6.0). Rows with an actor id
+      and no actor type could only ever have pointed at an admin user, so the
+      type is filled in and the transitional reader stops being needed.
+
+      Runs over whatever each model declares with `acted_by`, so the 6.1
+      conversion of the remaining associations reuses this task unchanged.
+      Idempotent: a row that already carries a type is skipped.
+    DESC
+    task backfill_actor_types: :environment do
+      actor_type = Spree.admin_user_class.to_s
+      total = 0
+
+      Spree::ActedBy.models.each do |model|
+        model.acted_by_associations.each do |name|
+          count = model.
+                  where.not(:"#{name}_id" => nil).
+                  where(:"#{name}_type" => nil).
+                  in_batches.
+                  sum { |batch| batch.update_all(:"#{name}_type" => actor_type) }
+
+          next if count.zero?
+
+          total += count
+          puts "  #{model.table_name}.#{name}: #{count} row(s) set to #{actor_type}."
+        end
+      end
+
+      puts total.zero? ? '  Nothing to backfill.' : "  Backfilled #{total} actor reference(s)."
+    end
+  end
+end

data/lib/tasks/backfill_custom_field_definition_stores.rake

@@ -0,0 +1,82 @@
+namespace :spree do
+  namespace :upgrade do
+    desc <<~DESC
+      Assigns the default store and the persisted filter_key to custom field
+      definitions that predate their store binding (Spree 6.0). Idempotent —
+      rows that already carry both are skipped.
+
+      The migration backfills and then enforces NOT NULL, so this is a safety
+      net rather than the primary path: it covers installs whose migration ran
+      before any store existed, leaving definitions unowned and the constraint
+      unapplied.
+
+      A definition whose namespace/key pair flattens to a filter_key another
+      row in the same store already owns is reported and skipped — only one of
+      them can be addressed as a sort or filter param. Rename one and re-run.
+    DESC
+    task backfill_custom_field_definition_stores: :environment do
+      store = Spree::Store.default
+      abort '  No default store found — create a store first.' if store.nil?
+
+      assigned = Spree::CustomFieldDefinition.where(store_id: nil).update_all(store_id: store.id)
+      puts "  Assigned #{assigned} custom field definition(s) to store #{store.name} (#{store.id})."
+
+      backfilled = 0
+      skipped = []
+
+      Spree::CustomFieldDefinition.where(filter_key: nil).find_each do |definition|
+        # `valid?` fires the callback that derives filter_key from namespace and
+        # key; the save skips validation so unrelated legacy data — a field type
+        # an extension no longer registers, say — cannot block the backfill.
+        definition.valid?
+
+        taken = Spree::CustomFieldDefinition.
+                where(store_id: definition.store_id, resource_type: definition.resource_type,
+                      filter_key: definition.filter_key).
+                where.not(id: definition.id).
+                exists?
+
+        if taken
+          skipped << definition
+          next
+        end
+
+        definition.save!(validate: false)
+        backfilled += 1
+      end
+
+      puts "  Backfilled filter_key on #{backfilled} definition(s)."
+
+      if skipped.any?
+        puts "  Skipped #{skipped.size} definition(s) whose filter_key is already taken in their store:"
+        skipped.each do |definition|
+          puts "    #{definition.id}: #{definition.namespace}.#{definition.key} (#{definition.resource_type}) " \
+               "would be #{definition.filter_key}"
+        end
+        puts '  Rename one of each colliding pair and re-run this task.'
+      end
+
+      # The migration applies these itself and only skips them when it found
+      # rows it could not fill. Leaving them off is what this task exists to
+      # put right: without them the unique indexes constrain nothing, because
+      # SQL treats NULLs as distinct.
+      table = Spree::CustomFieldDefinition.table_name
+      connection = ActiveRecord::Base.connection
+
+      %i[store_id filter_key].each do |column|
+        next unless connection.column_exists?(table, column)
+        next if connection.columns(table).find { |c| c.name == column.to_s }&.null == false
+
+        if Spree::CustomFieldDefinition.where(column => nil).exists?
+          puts "  #{column} is still NULL on some definitions — leaving it nullable until they are resolved."
+          next
+        end
+
+        connection.change_column_null(table, column, false)
+        puts "  Enforced NOT NULL on #{column}."
+      end
+
+      Spree::CustomFieldDefinition.reset_column_information
+    end
+  end
+end

data/lib/tasks/backfill_import_export_tenancy.rake

@@ -0,0 +1,93 @@
+namespace :spree do
+  namespace :upgrade do
+    desc <<~DESC
+      Fills in store_id (and seller_id where one applies) on every import
+      (Spree 6.0). Idempotent — rows that already carry a store_id are skipped,
+      so an interrupted run resumes for free.
+
+      An import used to carry a polymorphic `owner` that was either a Store or
+      a Seller, never both. A seller-owned row therefore had no store on it at
+      all, which is why a marketplace operator's list could not include the
+      imports their own sellers ran. Both axes now live on the row, matching
+      Spree::Export: store_id is always present, and seller_id is null for the
+      operator's own imports.
+
+      Rows owned by a store keep that store and stay first-party. Rows owned by
+      a seller take that seller, and their store is read from the seller.
+      Anything left without a store — an import whose owner was deleted out
+      from under it — goes to the default store, since a row with no store is
+      invisible to every scoped query and would otherwise be unreachable.
+
+      Exports need no data step: they have always carried store_id, and the
+      seller_id column this release adds is new for everyone (the association
+      shipped in 5.6 with no column behind it, so nothing was ever written).
+    DESC
+    task backfill_import_export_tenancy: :environment do
+      imports_table = Spree::Import.table_name
+      sellers_table = Spree::Seller.table_name
+      stores_table = Spree::Store.table_name
+
+      pending = Spree::Import.where(store_id: nil).count
+      if pending.zero?
+        puts '  Every import already carries a store — nothing to do.'
+        next
+      end
+
+      puts "  #{pending} import(s) to place."
+
+      # Set-based updates rather than row-by-row: both answers are already a
+      # single join away, and an installation that seeded a catalog by CSV can
+      # have a lot of these.
+      # The EXISTS guard matters as much here as on the seller branch below: a
+      # store that has since been deleted leaves a dangling id, and writing it
+      # would make store_id non-NULL without pointing anywhere — which the
+      # orphan sweep at the end then skips, leaving the row invisible to every
+      # scoped query with no second chance to place it.
+      from_stores = Spree::Import.connection.update(<<~SQL.squish)
+        UPDATE #{imports_table}
+        SET store_id = owner_id
+        WHERE store_id IS NULL
+          AND owner_type = 'Spree::Store'
+          AND EXISTS (
+            SELECT 1 FROM #{stores_table}
+            WHERE #{stores_table}.id = #{imports_table}.owner_id
+          )
+      SQL
+
+      # A seller's import takes the seller, and its store comes from that
+      # seller — the same derivation `Import#store` used to do at read time.
+      from_sellers = Spree::Import.connection.update(<<~SQL.squish)
+        UPDATE #{imports_table}
+        SET seller_id = owner_id,
+            store_id = (
+              SELECT store_id FROM #{sellers_table}
+              WHERE #{sellers_table}.id = #{imports_table}.owner_id
+            )
+        WHERE store_id IS NULL
+          AND owner_type = 'Spree::Seller'
+          AND EXISTS (
+            SELECT 1 FROM #{sellers_table}
+            WHERE #{sellers_table}.id = #{imports_table}.owner_id
+          )
+      SQL
+
+      puts "  #{from_stores} placed from a store owner."
+      puts "  #{from_sellers} placed from a seller owner."
+
+      orphaned = Spree::Import.where(store_id: nil)
+      if orphaned.exists?
+        store = Spree::Store.default
+        if store.nil?
+          puts "  #{orphaned.count} import(s) have no resolvable owner and there is no default store to place them in."
+          puts '  Create a store and re-run, or delete these rows.'
+        else
+          count = orphaned.update_all(store_id: store.id)
+          puts "  #{count} orphaned import(s) placed in the default store (#{store.name})."
+        end
+      end
+
+      remaining = Spree::Import.where(store_id: nil).count
+      puts remaining.zero? ? '  Done — every import carries a store.' : "  #{remaining} import(s) still unplaced."
+    end
+  end
+end

data/lib/tasks/backfill_library_media_placements.rake

@@ -0,0 +1,29 @@
+namespace :spree do
+  namespace :upgrade do
+    desc <<~DESC
+      Places existing category and collection images in the media library
+      (Spree 6.0). Idempotent — reconciliation skips slots that already have
+      their placement, so re-running is safe.
+
+      Before the library, a file uploaded to a category's image slot existed
+      only as an ActiveStorage attachment — in storage but invisible to the
+      library and unusable anywhere else. New uploads reconcile on save; this
+      walks the records that predate that.
+    DESC
+    task backfill_library_media_placements: :environment do
+      [Spree::Category, Spree::Collection].each do |model|
+        placed = 0
+
+        model.find_each do |record|
+          next unless record.library_media_slots.any? { |slot| record.public_send(slot).attached? }
+
+          before = record.media.count
+          record.sync_library_media!
+          placed += record.media.count - before
+        end
+
+        puts "  Placed #{placed} #{model.name.demodulize.downcase} image(s) in the library."
+      end
+    end
+  end
+end