Deprecate writing to Base#attributes

The Base class defines an `attr_accessor :attributes` that is marked
with `# :nodoc:`. Technically, this means that any interaction with
`Base#attributes` or `Base#attributes=` is not part of the public
interface, and is free to be changed or removed without breaking the
public API.

However, given the project's age and the long-term period of time with
minimal changes to the public interface, this PR proposes that there be
a public deprecation of **writing** to the Hash instance returned by the
`Base#attributes` method.

The migration to `ActiveModel::Attributes` proposed in [#410][] will
involve changes to the `Base#attributes` method (due to
[ActiveModel::Attributes#attributes][]). Reading from the value returned
by `ActiveModel::Attributes#attributes` will remain the same, but
writing to that value will have no affect since the value is a Hash copy
created by [ActiveModel::AttributeSet#to_hash][], and not the Hash
instance used internally.

Once deprecated and part of a release cycle, the
`ActiveResource::ReadOnlyHash` class can be removed, and the Active
Model migration's backwards compatibility burden can be reduced.

[#410]: #410
[ActiveModel::Attributes#attributes]: https://edgeapi.rubyonrails.org/classes/ActiveModel/Attributes.html#method-i-attributes
[ActiveModel::AttributeSet#to_hash]: https://github.com/rails/rails/blob/v8.1.1/activemodel/lib/active_model/attribute_set.rb#L36-L39

Author: seanpdoyle

lib/active_resource.rb

@@ -42,6 +42,7 @@ module ActiveResource
   autoload :CustomMethods
   autoload :Formats
   autoload :HttpMock
+  autoload :ReadOnlyHash
   autoload :Rescuable
   autoload :Schema
   autoload :Serialization

lib/active_resource/base.rb

@@ -1276,9 +1276,13 @@ def split_options(options = {})
         end
     end
 
-    attr_accessor :attributes # :nodoc:
+    attr_writer :attributes # :nodoc:
     attr_accessor :prefix_options # :nodoc:
 
+    def attributes # :nodoc:
+      ReadOnlyHash.new(@attributes)
+    end
+
     # If no schema has been defined for the class (see
     # <tt>ActiveResource::schema=</tt>), the default automatic schema is
     # generated from the current instance's attributes
@@ -1385,7 +1389,7 @@ def id
 
     # Sets the <tt>\id</tt> attribute of the resource.
     def id=(id)
-      attributes[self.class.primary_key] = id
+      @attributes[self.class.primary_key] = id
     end
 
     # Test for equality. Resource are equal if and only if +other+ is the same object or
@@ -1842,7 +1846,7 @@ def method_missing(method_symbol, *arguments) # :nodoc:
         if method_name =~ /(=|\?)$/
           case $1
           when "="
-            attributes[$`] = arguments.first
+            @attributes[$`] = arguments.first
           when "?"
             attributes[$`]
           end

lib/active_resource/read_only_hash.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ActiveResource
+  class ReadOnlyHash < DelegateClass(Hash) # :nodoc:
+    MESSAGE = "Writing the attributes hash is deprecated. Set attributes directly on the instance instead."
+
+    def []=(key, value)
+      ActiveResource.deprecator.warn(MESSAGE)
+      super
+    end
+    alias_method :store, :[]=
+
+    def update(*other_hashes)
+      ActiveResource.deprecator.warn(MESSAGE)
+      super
+    end
+    alias_method :merge!, :update
+
+    def is_a?(other)
+      __getobj__.is_a?(other)
+    end
+  end
+end

test/cases/base_test.rb

@@ -1743,4 +1743,28 @@ def test_paths_without_format
   ensure
     ActiveResource::Base.include_format_in_path = true
   end
+
+  def test_deprecate_attributes_store
+    [ :[]=, :store ].each do |store|
+      person = Person.find(1)
+
+      assert_deprecated("Writing the attributes hash is deprecated. Set attributes directly on the instance instead.", ActiveResource.deprecator) do
+        person.attributes.send(store, "name", "changed")
+      end
+
+      assert_equal "changed", person.name
+    end
+  end
+
+  def test_deprecate_attributes_update
+    [ :update, :merge! ].each do |update|
+      person = Person.find(1)
+
+      assert_deprecated("Writing the attributes hash is deprecated. Set attributes directly on the instance instead.", ActiveResource.deprecator) do
+        person.attributes.send(update, "name" => "changed")
+      end
+
+      assert_equal "changed", person.name
+    end
+  end
 end