spree_core 6.0.0.beta3 → 6.0.0.rc1

data/lib/spree/core/preferences/preferable.rb

@@ -1,36 +1,17 @@
-# Preferable allows defining preference accessor methods.
+# Typed model preferences, each a Rails store accessor on the `preferences`
+# JSON column — `secret_preferences` for a `:password` one (see
+# {Spree::SecretPreferences}). Included by `Spree::Base`.
 #
-# A class including Preferable must implement #preferences which should return
-# an object responding to .fetch(key), []=(key, val), and .delete(key).
-#
-# The generated writer method performs typecasting before assignment into the
-# preferences object.
-#
-# Examples:
-#
-#   # Spree::Base includes Preferable and defines preferences as a serialized
-#   # column.
 #   class Settings < Spree::Base
 #     preference :color,       :string,  default: 'red'
 #     preference :temperature, :integer, default: 21
 #   end
 #
 #   s = Settings.new
-#   s.preferred_color # => 'red'
-#   s.preferred_temperature # => 21
-#
-#   s.preferred_color = 'blue'
-#   s.preferred_color # => 'blue'
-#
-#   # Typecasting is performed on assignment
-#   s.preferred_temperature = '24'
-#   s.preferred_temperature # => 24
-#
-#   # Modifications have been made to the .preferences hash
-#   s.preferences #=> {color: 'blue', temperature: 24}
-#
-#   # Save the changes. All handled by activerecord
-#   s.save!
+#   s.preferred_color                # => 'red'
+#   s.preferred_temperature = '24'   # cast on assignment
+#   s.preferred_temperature          # => 24
+#   s.preferences                    # => { 'color' => 'red', 'temperature' => 24 }
 
 require 'spree/core/preferences/preferable_class_methods'
 
@@ -38,47 +19,56 @@ module Spree::Preferences::Preferable
   extend ActiveSupport::Concern
 
   included do
-    serialize :preferences, type: Hash, coder: YAML if defined?(serialize)
+    serialize :preferences, coder: Spree::Metadata::HashSerializer
     extend Spree::Preferences::PreferableClassMethods
   end
 
+  # JSON keeps decimals and times as strings; the declared type turns them
+  # back into a BigDecimal and a time. Anything else, or a string that does
+  # not parse, comes back as stored.
+  #
+  # @param value [Object] a value as JSON stores it
+  # @param type [Symbol] the preference's declared type
+  # @return [Object]
+  def self.restore_value(value, type)
+    return value unless value.is_a?(String)
+
+    case type
+    when :decimal then BigDecimal(value, exception: false) || value
+    when :datetime then Time.zone.iso8601(value)
+    else value
+    end
+  rescue ArgumentError
+    value
+  end
+
   def get_preference(name)
     has_preference! name
-    send self.class.preference_getter_method(name)
+    public_send(:"preferred_#{name}")
   end
 
   def set_preference(name, value)
     has_preference! name
-    send self.class.preference_setter_method(name), value
+    public_send(:"preferred_#{name}=", value)
   end
 
   def preference_type(name)
-    has_preference! name
-    send self.class.preference_type_getter_method(name)
+    preference_definition(name)[:type]
   end
 
   def preference_default(name)
-    has_preference! name
-    send self.class.preference_default_getter_method(name)
+    instance_exec(&preference_definition(name)[:default])
   end
 
   def preference_deprecated(name)
-    has_preference! name
-    send(self.class.preference_deprecated_getter_method(name))
+    preference_definition(name)[:deprecated]
   end
 
   # Whether this preference is written by Spree rather than supplied by the
   # operator — a webhook secret a provider issues, say. Kept out of the
   # schema, so nothing offers it as a field to fill in.
   def preference_internal(name)
-    has_preference! name
-    getter = self.class.preference_internal_getter_method(name)
-    # A preference declared before this option existed has no such reader.
-    # Treated as not internal rather than raising, so one old declaration
-    # cannot take a whole class's preference schema down with it.
-    return false unless respond_to?(getter)
-
-    send(getter)
+    preference_definition(name)[:internal]
   end
 
   # The fixed set this preference's value must come from, when it has one.
@@ -87,14 +77,8 @@ module Spree::Preferences::Preferable
   #
   # @return [Array, nil]
   def preference_choices(name)
-    has_preference! name
-    getter = self.class.preference_choices_getter_method(name)
-    # A preference declared before this option existed has no such reader.
-    # Treated as unconstrained rather than raising, so one old declaration
-    # cannot take a whole class's preference schema down with it.
-    return unless respond_to?(getter)
-
-    send(getter)
+    choices = preference_definition(name)[:choices]
+    choices.respond_to?(:call) ? choices.call : choices
   end
 
   def has_preference!(name)
@@ -102,57 +86,125 @@ module Spree::Preferences::Preferable
   end
 
   def has_preference?(name)
-    respond_to? self.class.preference_getter_method(name)
+    self.class.preference_definitions.key?(name.to_sym)
   end
 
   def defined_preferences
-    # Only real `preference`-macro definitions carry a `_default` getter —
-    # the name grep alone would also catch `preferred_*` association writers
-    # (e.g. Order#preferred_stock_location=).
-    methods.grep(/\Apreferred_.*=\Z/).filter_map do |pref_method|
-      name = pref_method.to_s.gsub(/\Apreferred_|=\Z/, '').to_sym
-      name if respond_to?(self.class.preference_default_getter_method(name))
-    end
+    self.class.preference_definitions.keys
+  end
+
+  def default_preferences
+    defined_preferences.index_with { |name| preference_default(name) }
+  end
+
+  # Every preference value, secrets included — what `preferences` alone held
+  # before secrets moved to their own column. Declared preferences read
+  # through their `preferred_*` reader, so a default applies and decimals and
+  # times come back typed rather than in the string form JSON stores.
+  #
+  # @return [ActiveSupport::HashWithIndifferentAccess]
+  def preference_values
+    (preferences || {}).to_h.with_indifferent_access.merge(defined_preferences.index_with { |name| get_preference(name) })
   end
 
-  def deprecated_preferences
-    defined_preferences.each_with_object([]) do |pref_name, array|
-      deprecated_message = preference_deprecated(pref_name)
-      array << { name: pref_name, message: deprecated_message } unless deprecated_message.nil?
+  # The stored value of a preference, before its default applies. A secret
+  # found in `preferences` wins over the encrypted column: it is either a
+  # newer value assigned as part of a whole hash, waiting for the save that
+  # moves it across, or one the upgrade has not moved yet — the writer always
+  # removes that copy, so it is never stale.
+  #
+  # @param name [Symbol, String]
+  # @return [Object] the stored value, or the block's result when nothing is stored
+  def stored_preference(name)
+    if secret_preference?(name)
+      (preferences || {}).fetch(name) { (secret_preferences || {}).fetch(name) { return yield } }
+    else
+      (preferences || {}).fetch(name) { yield }
     end
   end
 
-  def default_preferences
-    Hash[
-      defined_preferences.map do |preference|
-        [preference, preference_default(preference)]
-      end
-    ]
+  # Fills in the declared default of every preference this record has no
+  # stored value for, so a preference added to the class after the row was
+  # saved never reads as missing and the raw `preferences` hash always holds
+  # every value. Secrets are left out: their defaults are read through the
+  # `preferred_*` reader, never copied into storage.
+  #
+  # Filling in a default is not a change to a stored record: a loaded record
+  # stays clean, so `with_lock` still accepts it, and the defaults are written
+  # with its next real save.
+  def backfill_default_preferences
+    secrets = self.class.secret_preference_names
+    missing = defined_preferences.reject { |name| preferences.key?(name) || secrets.include?(name) }
+    return if missing.empty?
+
+    already_changed = attribute_changed?(:preferences)
+    self.preferences = preferences.merge(missing.index_with { |name| stored_default(name) })
+    clear_attribute_change(:preferences) if persisted? && !already_changed
   end
 
-  def preferences_of_type(type)
-    defined_preferences.find_all { |preference| preference_type(preference) == type.to_sym }
+  # Names of the preferences the last save changed, secrets included.
+  #
+  # @return [Array<Symbol>]
+  def previously_changed_preference_names
+    defined_preferences.select { |name| public_send(:"saved_change_to_preferred_#{name}?") }
   end
 
-  def clear_preferences
-    preferences.keys.each { |pref| preferences.delete pref }
+  private
+
+  def preference_definition(name)
+    has_preference! name
+    self.class.preference_definitions[name.to_sym]
   end
 
-  def restore_preferences_for(preference_keys)
-    preference_keys.each { |pref| preferences[pref] = preference_default(pref) }
+  # A declared default in the form JSON stores, as the writer would store it,
+  # so a decimal default reads back as a BigDecimal and setting the same
+  # amount is not a change.
+  def stored_default(name)
+    default = preference_default(name)
+    type = preference_type(name)
+    return default if default.nil? || %i[decimal datetime].exclude?(type)
+
+    convert_preference_value(default, type, nullable: true).as_json
   end
 
-  def preference_change(name, changes_or_previous_changes)
-    preference_changes = changes_or_previous_changes.with_indifferent_access.fetch('preferences', [{}, {}])
-    before_preferences = preference_changes[0] || {}
-    after_preferences = preference_changes[1] || {}
+  # Only a class that stores secrets can declare one, so the names say it all.
+  def secret_preference?(name)
+    self.class.secret_preference_names.include?(name.to_sym)
+  end
 
-    return if before_preferences[name] == after_preferences[name]
+  def cast_preference(name, value)
+    definition = preference_definition(name)
+    parse_on_set = definition[:parse_on_set]
+    if parse_on_set.is_a?(Proc)
+      # Procs that accept more than one arg opt into receiving the owning
+      # record so they can scope (e.g. `normalize_id_preference` rejecting
+      # cross-store IDs). `arity.abs > 1` covers both the `(value, owner)` and
+      # `(value, owner = nil)` shapes.
+      value = parse_on_set.arity.abs > 1 ? parse_on_set.call(value, self) : parse_on_set.call(value)
+    end
+    value = convert_preference_value(value, definition[:type], nullable: definition[:nullable])
+    # Decimals and times are kept in the string form JSON stores, so a record
+    # read back from the database and one just written compare equal and
+    # setting the same value is not a change. The reader restores them.
+    value = value.as_json if %i[decimal datetime].include?(definition[:type])
 
-    [before_preferences[name], after_preferences[name]]
+    Spree::Deprecation.warn("`#{name}` is deprecated. #{definition[:deprecated]}") if definition[:deprecated]
+    value
   end
 
-  private
+  # Assigns a new hash rather than calling the store accessor's writer, which
+  # skips writing nil to a missing key — leaving the default in force when nil
+  # was meant. Rails still sees no change when the value is the one stored.
+  def write_preference(name, value)
+    if secret_preference?(name)
+      # A copy assigned as part of a whole hash would otherwise outlive the
+      # value written here and be moved over it on save.
+      self.preferences = preferences.except(name) if preferences&.key?(name)
+      self.secret_preferences = (secret_preferences || {}).with_indifferent_access.merge(name => value)
+    else
+      self.preferences = (preferences || {}).with_indifferent_access.merge(name => value)
+    end
+  end
 
   def convert_preference_value(value, type, nullable: false)
     case type
@@ -195,6 +247,8 @@ module Spree::Preferences::Preferable
       case value.class.to_s
       when 'Hash'
         value
+      when 'ActionController::Parameters'
+        value.to_h
       when 'String'
         # only works with hashes whose keys are strings
         JSON.parse value.gsub('=>', ':')
@@ -221,7 +275,7 @@ module Spree::Preferences::Preferable
         value.to_time
       end
     # Kept as the `yyyy-MM-dd` string it arrived as rather than coerced to a
-    # Time. Preferences are YAML-serialized, and what a date *means* depends on
+    # Time. Preferences are stored as JSON, and what a date *means* depends on
     # the store's timezone, which this method has no access to: coercing here
     # would freeze the value against the server's zone and move the operator's
     # deadline by hours. The reader owns that (see

data/lib/spree/core/preferences/preferable_class_methods.rb

@@ -1,169 +1,104 @@
 module Spree::Preferences
   module PreferableClassMethods
-    # Declaration order, so an admin form can present preferences the way
-    # their author grouped them — credentials before the optional settings
-    # that depend on them. `defined_preferences` reads Ruby's own `methods`,
-    # whose order is an implementation detail, so it cannot answer this.
-    def declared_preference_order
-      @declared_preference_order ||= begin
-        inherited = superclass.respond_to?(:declared_preference_order) ? superclass.declared_preference_order : []
-        inherited.dup
+    # Bumped by every declaration anywhere, so a class's cached view of its
+    # preferences is rebuilt when an ancestor gains one after the class was
+    # loaded — a decorator adding a secret to Spree::PaymentMethod, say.
+    @declarations = 0
+
+    class << self
+      attr_accessor :declarations
+    end
+
+    # Every preference the class declares, inherited ones included, in
+    # declaration order — so an admin form can present them the way their
+    # author grouped them.
+    #
+    # @return [Hash{Symbol => Hash}] name => `{ type:, default:, deprecated:, internal:, choices:, nullable:, parse_on_set: }`
+    def preference_definitions
+      preference_declarations_cache[:definitions] ||= begin
+        inherited = superclass.respond_to?(:preference_definitions) ? superclass.preference_definitions : {}
+        inherited.merge(own_preference_definitions).freeze
       end
     end
 
+    # Each declared preference's type, known from the declarations alone —
+    # without building a record.
+    #
+    # @return [Hash{Symbol => Symbol}]
+    def declared_preference_types
+      preference_declarations_cache[:types] ||= preference_definitions.transform_values { |definition| definition[:type] }.freeze
+    end
+
+    # Names of the `:password` preferences, which a model including
+    # {Spree::SecretPreferences} stores encrypted in `secret_preferences`.
+    #
+    # @return [Array<Symbol>]
+    def secret_preference_names
+      preference_declarations_cache[:secrets] ||= declared_preference_types.filter_map { |name, type| name if type == :password }.freeze
+    end
+
+    # Declares a typed preference with a `preferred_<name>` reader and writer
+    # and a `prefers_<name>?` query. On a model, the value lives in the
+    # `preferences` column (`secret_preferences` for a `:password` one) as a
+    # Rails store accessor, which brings the change methods with it:
+    # `preferred_<name>_changed?`, `_change`, `_was`,
+    # `saved_change_to_preferred_<name>?` and `preferred_<name>_before_last_save`.
     def preference(name, type, *args)
-      declared_preference_order << name.to_sym unless declared_preference_order.include?(name.to_sym)
+      name = name.to_sym
+      secret = type == :password
+      if secret && !include?(Spree::SecretPreferences)
+        raise ArgumentError, "#{self.name} declares the secret preference `#{name}` but cannot encrypt it. " \
+                             'Include Spree::SecretPreferences and add a `secret_preferences` text column to its table.'
+      end
+
       options = args.extract_options!
       options.assert_valid_keys(:default, :deprecated, :in, :internal, :nullable, :parse_on_set)
       default = options[:default]
       default = -> { options[:default] } unless default.is_a?(Proc)
-      deprecated = options[:deprecated]
-      internal = options[:internal]
-      # The fixed set a value must come from. Turns a text box into a picker
-      # in every admin form, and is what the inclusion validation would have
-      # told the operator only after a failed save.
-      choices = options[:in]
-      nullable = options[:nullable]
-      parse_on_set = options[:parse_on_set]
-
-      # cache_key will be nil for new objects, then if we check if there
-      # is a pending preference before going to default
-      define_method preference_getter_method(name) do
-        # Rows persisted before the model gained preferences can load with a
-        # NULL column — treat that as "no stored preferences".
-        (preferences || {}).fetch(name) do
-          default.call
-        end
-      end
-
-      define_method preference_setter_method(name) do |value|
-        if parse_on_set.is_a?(Proc)
-          # Procs that accept more than one arg opt into receiving the
-          # owning record so they can scope (e.g. `normalize_id_preference`
-          # rejecting cross-store IDs). `arity.abs > 1` covers both the
-          # `(value, owner)` and `(value, owner = nil)` shapes.
-          value = parse_on_set.arity.abs > 1 ? parse_on_set.call(value, self) : parse_on_set.call(value)
-        end
-        value = convert_preference_value(value, type, nullable: nullable)
-        self.preferences = {} if preferences.nil?
-        preferences[name] = value
-
-        Spree::Deprecation.warn("`#{name}` is deprecated. #{deprecated}") if deprecated
-
-        # If this is an activerecord object, we need to inform
-        # ActiveRecord::Dirty that this value has changed, since this is an
-        # in-place update to the preferences hash.
-        preferences_will_change! if respond_to?(:preferences_will_change!)
-      end
-
-      define_method preference_default_getter_method(name), &default
-
-      define_method preference_type_getter_method(name) do
-        type
-      end
-
-      define_method preference_deprecated_getter_method(name) do
-        deprecated
-      end
-
-      # Whether this preference is the system's to write rather than the
-      # operator's to supply — a value a provider hands back to us, not one
-      # anybody could know in advance.
-      define_method preference_internal_getter_method(name) do
-        internal
-      end
-
-      define_method preference_choices_getter_method(name) do
-        choices.respond_to?(:call) ? choices.call : choices
-      end
-
-      define_method prefers_query_method(name) do
-        preferences.fetch(name).to_b
-      end
-
-      define_method preference_change_method(name) do
-        preference_change(name, changes) if respond_to?(:changes)
-      end
-
-      define_method preference_was_method(name) do
-        return unless respond_to?(:changes)
-
-        preference_change(name, changes)&.first || get_preference(name)
-      end
-
-      define_method preference_changed_method(name) do
-        respond_to?(:changes) && preference_change(name, changes).present?
-      end
-
-      define_method preference_previous_change_method(name) do
-        preference_change(name, previous_changes) if respond_to?(:previous_changes)
+      own_preference_definitions[name] = {
+        type: type,
+        default: default,
+        deprecated: options[:deprecated],
+        # Whether the system writes the value rather than the operator — a
+        # value a provider hands back, kept out of every admin form.
+        internal: options[:internal],
+        # The fixed set a value must come from; turns a text box into a picker.
+        choices: options[:in],
+        nullable: options[:nullable],
+        parse_on_set: options[:parse_on_set]
+      }
+      PreferableClassMethods.declarations += 1
+
+      store_accessor(secret ? :secret_preferences : :preferences, name, prefix: :preferred)
+
+      # Overrides the store accessor's reader and writer, which treat a missing
+      # key as nil; here a missing key means the declared default.
+      define_method(:"preferred_#{name}") do
+        Spree::Preferences::Preferable.restore_value(stored_preference(name) { stored_default(name) }, type)
       end
 
-      define_method preference_previous_was_method(name) do
-        return unless respond_to?(:previous_changes)
-
-        preference_change(name, previous_changes)&.first
+      define_method(:"preferred_#{name}=") do |value|
+        write_preference(name, cast_preference(name, value))
       end
 
-      define_method preference_previous_changed_method(name) do
-        respond_to?(:previous_changes) && preference_change(name, previous_changes).present?
+      define_method(:"prefers_#{name}?") do
+        stored_preference(name) { raise KeyError, "key not found: #{name.inspect}" }.to_b
       end
     end
 
-    def preference_getter_method(name)
-      "preferred_#{name}".to_sym
-    end
-
-    def preference_setter_method(name)
-      "preferred_#{name}=".to_sym
-    end
-
-    def preference_default_getter_method(name)
-      "preferred_#{name}_default".to_sym
-    end
-
-    def preference_deprecated_getter_method(name)
-      "preferred_#{name}_deprecated".to_sym
-    end
-
-    def preference_internal_getter_method(name)
-      "preferred_#{name}_internal".to_sym
-    end
-
-    def preference_choices_getter_method(name)
-      "preferred_#{name}_choices".to_sym
-    end
-
-    def preference_type_getter_method(name)
-      "preferred_#{name}_type".to_sym
-    end
-
-    def prefers_query_method(name)
-      "prefers_#{name}?".to_sym
-    end
-
-    def preference_change_method(name)
-      "preferred_#{name}_change".to_sym
-    end
+    private
 
-    def preference_was_method(name)
-      "preferred_#{name}_was".to_sym
+    def own_preference_definitions
+      @own_preference_definitions ||= {}
     end
 
-    def preference_changed_method(name)
-      "preferred_#{name}_changed?".to_sym
-    end
-
-    def preference_previous_change_method(name)
-      "preferred_#{name}_previous_change".to_sym
-    end
-
-    def preference_previous_was_method(name)
-      "preferred_#{name}_previously_was".to_sym
-    end
-
-    def preference_previous_changed_method(name)
-      "preferred_#{name}_previously_changed?".to_sym
+    def preference_declarations_cache
+      generation = PreferableClassMethods.declarations
+      unless @preference_declarations_generation == generation
+        @preference_declarations_generation = generation
+        @preference_declarations_cache = {}
+      end
+      @preference_declarations_cache
     end
   end
 end

data/lib/spree/core/previews/import_preview.rb

@@ -0,0 +1,10 @@
+require_relative 'preview_data'
+
+# Preview Spree import emails at /rails/mailers/spree/import
+class Spree::ImportPreview < ActionMailer::Preview
+  include Spree::PreviewData::LocaleParam
+
+  def import_done
+    Spree::ImportMailer.import_done(Spree::Import.where.not(user_id: nil).last)
+  end
+end

data/lib/spree/core/tax/provider_error.rb

@@ -0,0 +1,37 @@
+module Spree
+  module Tax
+    # A tax engine did not produce tax for a sale. Providers raise one of the
+    # two subclasses below; core rescues this and refuses the sale rather than
+    # completing one whose tax nobody computed — charging nothing because nobody
+    # could be asked is the error a merchant discovers in a filing.
+    #
+    # Split because a customer can only act on one of them. Retrying an outage
+    # may work; retrying a postcode the engine rejects never will, and telling
+    # someone to try again is worse than telling them nothing.
+    #
+    # The parallel is {Spree::Pricing::PriceResolution::ProviderUnavailable},
+    # which refuses a sale whose prices could not be confirmed. Neither is for a
+    # provider a merchant switched off: that is configuration, not failure, and
+    # an unconfigured engine simply has no opinion and writes no rows.
+    class ProviderError < StandardError
+      # @return [String, nil] which engine failed, for the report
+      attr_reader :provider_key
+
+      def initialize(message = nil, provider_key: nil)
+        @provider_key = provider_key
+        super(message)
+      end
+    end
+
+    # The engine could not be asked — unreachable, timed out, or answering with
+    # a fault of its own. Nothing is known about the tax, and trying again
+    # later may well succeed, so the customer is told to retry.
+    class ProviderUnavailable < ProviderError; end
+
+    # The engine was asked and said no: an address it will not accept, a
+    # misconfigured company code, a request it rejects. The service is working,
+    # so retrying changes nothing — what the engine said is the useful part and
+    # core passes its message on rather than inventing one.
+    class CalculationRefused < ProviderError; end
+  end
+end

data/lib/spree/core/version.rb

@@ -1,5 +1,5 @@
 module Spree
-  VERSION = '6.0.0.beta3'.freeze
+  VERSION = '6.0.0.rc1'.freeze
 
   def self.version
     VERSION