activerecord 6.1.7 → 7.2.0

data/lib/active_record/attribute_methods/serialization.rb

@@ -2,6 +2,7 @@
 
 module ActiveRecord
   module AttributeMethods
+    # = Active Record Attribute Methods \Serialization
     module Serialization
       extend ActiveSupport::Concern
 
@@ -15,16 +16,18 @@ module ActiveRecord
         end
       end
 
+      included do
+        class_attribute :default_column_serializer, instance_accessor: false, default: Coders::YAMLColumn
+      end
+
       module ClassMethods
-        # If you have an attribute that needs to be saved to the database as an
-        # object, and retrieved as the same object, then specify the name of that
-        # attribute using this method and it will be handled automatically. The
-        # serialization is done through YAML. If +class_name+ is specified, the
-        # serialized object must be of that class on assignment and retrieval.
-        # Otherwise SerializationTypeMismatch will be raised.
+        # If you have an attribute that needs to be saved to the database as a
+        # serialized object, and retrieved by deserializing into the same object,
+        # then specify the name of that attribute using this method and serialization
+        # will be handled automatically.
         #
-        # Empty objects as <tt>{}</tt>, in the case of +Hash+, or <tt>[]</tt>, in the case of
-        # +Array+, will always be persisted as null.
+        # The serialization format may be YAML, JSON, or any custom format using a
+        # custom coder class.
         #
         # Keep in mind that database adapters handle certain serialization tasks
         # for you. For instance: +json+ and +jsonb+ types in PostgreSQL will be
@@ -37,57 +40,191 @@ module ActiveRecord
         #
         # ==== Parameters
         #
-        # * +attr_name+ - The field name that should be serialized.
-        # * +class_name_or_coder+ - Optional, a coder object, which responds to +.load+ and +.dump+
-        #   or a class name that the object type should be equal to.
+        # * +attr_name+ - The name of the attribute to serialize.
+        # * +coder+ The serializer implementation to use, e.g. +JSON+.
+        #   * The attribute value will be serialized
+        #     using the coder's <tt>dump(value)</tt> method, and will be
+        #     deserialized using the coder's <tt>load(string)</tt> method. The
+        #     +dump+ method may return +nil+ to serialize the value as +NULL+.
+        # * +type+ - Optional. What the type of the serialized object should be.
+        #   * Attempting to serialize another type will raise an
+        #     ActiveRecord::SerializationTypeMismatch error.
+        #   * If the column is +NULL+ or starting from a new record, the default value
+        #     will set to +type.new+
+        # * +yaml+ - Optional. Yaml specific options. The allowed config is:
+        #   * +:permitted_classes+ - +Array+ with the permitted classes.
+        #   * +:unsafe_load+ - Unsafely load YAML blobs, allow YAML to load any class.
         #
         # ==== Options
         #
-        # +default+ The default value to use when no value is provided. If this option
-        # is not passed, the previous default value (if any) will be used.
-        # Otherwise, the default will be +nil+.
+        # * +:default+ - The default value to use when no value is provided. If
+        #   this option is not passed, the previous default value (if any) will
+        #   be used. Otherwise, the default will be +nil+.
+        #
+        # ==== Choosing a serializer
+        #
+        # While any serialization format can be used, it is recommended to carefully
+        # evaluate the properties of a serializer before using it, as migrating to
+        # another format later on can be difficult.
+        #
+        # ===== Avoid accepting arbitrary types
+        #
+        # When serializing data in a column, it is heavily recommended to make sure
+        # only expected types will be serialized. For instance some serializer like
+        # +Marshal+ or +YAML+ are capable of serializing almost any Ruby object.
+        #
+        # This can lead to unexpected types being serialized, and it is important
+        # that type serialization remains backward and forward compatible as long
+        # as some database records still contain these serialized types.
+        #
+        #   class Address
+        #     def initialize(line, city, country)
+        #       @line, @city, @country = line, city, country
+        #     end
+        #   end
+        #
+        # In the above example, if any of the +Address+ attributes is renamed,
+        # instances that were persisted before the change will be loaded with the
+        # old attributes. This problem is even worse when the serialized type comes
+        # from a dependency which doesn't expect to be serialized this way and may
+        # change its internal representation without notice.
+        #
+        # As such, it is heavily recommended to instead convert these objects into
+        # primitives of the serialization format, for example:
+        #
+        #   class Address
+        #     attr_reader :line, :city, :country
         #
-        # ==== Example
+        #     def self.load(payload)
+        #       data = YAML.safe_load(payload)
+        #       new(data["line"], data["city"], data["country"])
+        #     end
+        #
+        #     def self.dump(address)
+        #       YAML.safe_dump(
+        #         "line" => address.line,
+        #         "city" => address.city,
+        #         "country" => address.country,
+        #       )
+        #     end
+        #
+        #     def initialize(line, city, country)
+        #       @line, @city, @country = line, city, country
+        #     end
+        #   end
         #
-        #   # Serialize a preferences attribute.
         #   class User < ActiveRecord::Base
-        #     serialize :preferences
+        #     serialize :address, coder: Address
         #   end
         #
-        #   # Serialize preferences using JSON as coder.
+        # This pattern allows to be more deliberate about what is serialized, and
+        # to evolve the format in a backward compatible way.
+        #
+        # ===== Ensure serialization stability
+        #
+        # Some serialization methods may accept some types they don't support by
+        # silently casting them to other types. This can cause bugs when the
+        # data is deserialized.
+        #
+        # For instance the +JSON+ serializer provided in the standard library will
+        # silently cast unsupported types to +String+:
+        #
+        #   >> JSON.parse(JSON.dump(Struct.new(:foo)))
+        #   => "#<Class:0x000000013090b4c0>"
+        #
+        # ==== Examples
+        #
+        # ===== Serialize the +preferences+ attribute using YAML
+        #
         #   class User < ActiveRecord::Base
-        #     serialize :preferences, JSON
+        #     serialize :preferences, coder: YAML
         #   end
         #
-        #   # Serialize preferences as Hash using YAML coder.
+        # ===== Serialize the +preferences+ attribute using JSON
+        #
         #   class User < ActiveRecord::Base
-        #     serialize :preferences, Hash
+        #     serialize :preferences, coder: JSON
         #   end
-        def serialize(attr_name, class_name_or_coder = Object, **options)
-          # When ::JSON is used, force it to go through the Active Support JSON encoder
-          # to ensure special objects (e.g. Active Record models) are dumped correctly
-          # using the #as_json hook.
-          coder = if class_name_or_coder == ::JSON
-            Coders::JSON
-          elsif [:load, :dump].all? { |x| class_name_or_coder.respond_to?(x) }
-            class_name_or_coder
-          else
-            Coders::YAMLColumn.new(attr_name, class_name_or_coder)
+        #
+        # ===== Serialize the +preferences+ +Hash+ using YAML
+        #
+        #   class User < ActiveRecord::Base
+        #     serialize :preferences, type: Hash, coder: YAML
+        #   end
+        #
+        # ===== Serializes +preferences+ to YAML, permitting select classes
+        #
+        #   class User < ActiveRecord::Base
+        #     serialize :preferences, coder: YAML, yaml: { permitted_classes: [Symbol, Time] }
+        #   end
+        #
+        # ===== Serialize the +preferences+ attribute using a custom coder
+        #
+        #   class Rot13JSON
+        #     def self.rot13(string)
+        #       string.tr("a-zA-Z", "n-za-mN-ZA-M")
+        #     end
+        #
+        #     # Serializes an attribute value to a string that will be stored in the database.
+        #     def self.dump(value)
+        #       rot13(ActiveSupport::JSON.dump(value))
+        #     end
+        #
+        #     # Deserializes a string from the database to an attribute value.
+        #     def self.load(string)
+        #       ActiveSupport::JSON.load(rot13(string))
+        #     end
+        #   end
+        #
+        #   class User < ActiveRecord::Base
+        #     serialize :preferences, coder: Rot13JSON
+        #   end
+        #
+        def serialize(attr_name, coder: nil, type: Object, yaml: {}, **options)
+          coder ||= default_column_serializer
+          unless coder
+            raise ArgumentError, <<~MSG.squish
+              missing keyword: :coder
+
+              If no default coder is configured, a coder must be provided to `serialize`.
+            MSG
           end
 
-          decorate_attribute_type(attr_name.to_s, **options) do |cast_type|
-            if type_incompatible_with_serialize?(cast_type, class_name_or_coder)
+          column_serializer = build_column_serializer(attr_name, coder, type, yaml)
+
+          attribute(attr_name, **options)
+
+          decorate_attributes([attr_name]) do |attr_name, cast_type|
+            if type_incompatible_with_serialize?(cast_type, coder, type)
               raise ColumnNotSerializableError.new(attr_name, cast_type)
             end
 
-            Type::Serialized.new(cast_type, coder)
+            cast_type = cast_type.subtype if Type::Serialized === cast_type
+            Type::Serialized.new(cast_type, column_serializer)
           end
         end
 
         private
-          def type_incompatible_with_serialize?(type, class_name)
-            type.is_a?(ActiveRecord::Type::Json) && class_name == ::JSON ||
-              type.respond_to?(:type_cast_array, true) && class_name == ::Array
+          def build_column_serializer(attr_name, coder, type, yaml = nil)
+            # When ::JSON is used, force it to go through the Active Support JSON encoder
+            # to ensure special objects (e.g. Active Record models) are dumped correctly
+            # using the #as_json hook.
+            coder = Coders::JSON if coder == ::JSON
+
+            if coder == ::YAML || coder == Coders::YAMLColumn
+              Coders::YAMLColumn.new(attr_name, type, **(yaml || {}))
+            elsif coder.respond_to?(:new) && !coder.respond_to?(:load)
+              coder.new(attr_name, type)
+            elsif type && type != Object
+              Coders::ColumnSerializer.new(attr_name, coder, type)
+            else
+              coder
+            end
+          end
+
+          def type_incompatible_with_serialize?(cast_type, coder, type)
+            cast_type.is_a?(ActiveRecord::Type::Json) && coder == ::JSON ||
+              cast_type.respond_to?(:type_cast_array, true) && type == ::Array
           end
       end
     end

data/lib/active_record/attribute_methods/time_zone_conversion.rb

@@ -25,6 +25,8 @@ module ActiveRecord
             rescue ArgumentError
               nil
             end
+          elsif value.respond_to?(:infinite?) && value.infinite?
+            value
           else
             map_avoiding_infinite_recursion(super) { |v| cast(v) }
           end
@@ -36,7 +38,7 @@ module ActiveRecord
 
             if value.acts_like?(:time)
               value.in_time_zone
-            elsif value.is_a?(::Float)
+            elsif value.respond_to?(:infinite?) && value.infinite?
               value
             else
               map_avoiding_infinite_recursion(value) { |v| convert_time_to_time_zone(v) }
@@ -61,21 +63,21 @@ module ActiveRecord
       extend ActiveSupport::Concern
 
       included do
-        mattr_accessor :time_zone_aware_attributes, instance_writer: false, default: false
-
+        class_attribute :time_zone_aware_attributes, instance_writer: false, default: false
         class_attribute :skip_time_zone_conversion_for_attributes, instance_writer: false, default: []
         class_attribute :time_zone_aware_types, instance_writer: false, default: [ :datetime, :time ]
       end
 
       module ClassMethods # :nodoc:
-        def define_attribute(name, cast_type, **)
-          if create_time_zone_conversion_attribute?(name, cast_type)
-            cast_type = TimeZoneConverter.new(cast_type)
+        private
+          def hook_attribute_type(name, cast_type)
+            if create_time_zone_conversion_attribute?(name, cast_type)
+              cast_type = TimeZoneConverter.new(cast_type)
+            end
+
+            super
           end
-          super
-        end
 
-        private
           def create_time_zone_conversion_attribute?(name, cast_type)
             enabled_for_column = time_zone_aware_attributes &&
               !skip_time_zone_conversion_for_attributes.include?(name.to_sym)

data/lib/active_record/attribute_methods/write.rb

@@ -2,30 +2,32 @@
 
 module ActiveRecord
   module AttributeMethods
+    # = Active Record Attribute Methods \Write
     module Write
       extend ActiveSupport::Concern
 
       included do
-        attribute_method_suffix "="
+        attribute_method_suffix "=", parameters: "value"
       end
 
       module ClassMethods # :nodoc:
         private
-          def define_method_attribute=(name, owner:)
+          def define_method_attribute=(canonical_name, owner:, as: canonical_name)
             ActiveModel::AttributeMethods::AttrNames.define_attribute_accessor_method(
-              owner, name, writer: true,
+              owner, canonical_name, writer: true,
             ) do |temp_method_name, attr_name_expr|
-              owner <<
-                "def #{temp_method_name}(value)" <<
-                "  _write_attribute(#{attr_name_expr}, value)" <<
-                "end"
+              owner.define_cached_method(temp_method_name, as: "#{as}=", namespace: :active_record) do |batch|
+                batch <<
+                  "def #{temp_method_name}(value)" <<
+                  "  _write_attribute(#{attr_name_expr}, value)" <<
+                  "end"
+              end
             end
           end
       end
 
-      # Updates the attribute identified by <tt>attr_name</tt> with the
-      # specified +value+. Empty strings for Integer and Float columns are
-      # turned into +nil+.
+      # Updates the attribute identified by +attr_name+ using the specified
+      # +value+. The attribute value will be type cast upon being read.
       def write_attribute(attr_name, value)
         name = attr_name.to_s
         name = self.class.attribute_aliases[name] || name
@@ -42,11 +44,6 @@ module ActiveRecord
 
       alias :attribute= :_write_attribute
       private :attribute=
-
-      private
-        def write_attribute_without_type_cast(attr_name, value)
-          @attributes.write_cast_value(attr_name, value)
-        end
     end
   end
 end