Merge pull request rails#54525 from jonathanhefner/add-rotation_coordinator-prepend

Add `{MessageEncryptors,MessageVerifiers}#prepend`

Author: jonathanhefner

activesupport/lib/active_support/message_encryptors.rb

@@ -26,6 +26,9 @@ class MessageEncryptors < Messages::RotationCoordinator
     # as the first rotation and <tt>transitional = true</tt>. Then, after all
     # servers have been updated, perform a second rolling deploy with
     # <tt>transitional = false</tt>.
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#transitional
 
     ##
     # :singleton-method: new
@@ -43,6 +46,9 @@ class MessageEncryptors < Messages::RotationCoordinator
     #   end
     #
     #   encryptors.rotate(base: "...")
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#initialize
 
     ##
     # :method: []
@@ -51,12 +57,18 @@ class MessageEncryptors < Messages::RotationCoordinator
     # Returns a MessageEncryptor configured with a secret derived from the
     # given +salt+, and options from #rotate. MessageEncryptor instances will
     # be memoized, so the same +salt+ will return the same instance.
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#[]
 
     ##
     # :method: []=
     # :call-seq: []=(salt, encryptor)
     #
     # Overrides a MessageEncryptor instance associated with a given +salt+.
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#[]=
 
     ##
     # :method: rotate
@@ -106,18 +118,55 @@ class MessageEncryptors < Messages::RotationCoordinator
     #
     #   # Uses `serializer: Marshal, url_safe: false`.
     #   encryptors[:baz]
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#rotate
+
+    ##
+    # :method: prepend
+    # :call-seq:
+    #   prepend(**options)
+    #   prepend(&block)
+    #
+    # Just like #rotate, but prepends the given options or block to the list of
+    # option sets.
+    #
+    # This can be useful when you have an already-configured +MessageEncryptors+
+    # instance, but you want to override the way messages are encrypted.
+    #
+    #   module ThirdParty
+    #     ENCRYPTORS = ActiveSupport::MessageEncryptors.new { ... }.
+    #       rotate(serializer: Marshal, url_safe: true).
+    #       rotate(serializer: Marshal, url_safe: false)
+    #   end
+    #
+    #   ThirdParty.ENCRYPTORS.prepend(serializer: JSON, url_safe: true)
+    #
+    #   # Uses `serializer: JSON, url_safe: true`.
+    #   # Falls back to `serializer: Marshal, url_safe: true` or
+    #   # `serializer: Marshal, url_safe: false`.
+    #   ThirdParty.ENCRYPTORS[:foo]
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#prepend
 
     ##
     # :method: rotate_defaults
     # :call-seq: rotate_defaults
     #
     # Invokes #rotate with the default options.
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#rotate_defaults
 
     ##
     # :method: clear_rotations
     # :call-seq: clear_rotations
     #
     # Clears the list of option sets.
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#clear_rotations
 
     ##
     # :method: on_rotation
@@ -129,6 +178,9 @@ class MessageEncryptors < Messages::RotationCoordinator
     # For example, this callback could log each time it is called, and thus
     # indicate whether old option sets are still in use or can be removed from
     # rotation.
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#on_rotation
 
     ##
     private

activesupport/lib/active_support/message_verifiers.rb

@@ -26,6 +26,9 @@ class MessageVerifiers < Messages::RotationCoordinator
     # as the first rotation and <tt>transitional = true</tt>. Then, after all
     # servers have been updated, perform a second rolling deploy with
     # <tt>transitional = false</tt>.
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#transitional
 
     ##
     # :singleton-method: new
@@ -42,6 +45,9 @@ class MessageVerifiers < Messages::RotationCoordinator
     #   end
     #
     #   verifiers.rotate(base: "...")
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#initialize
 
     ##
     # :method: []
@@ -50,12 +56,18 @@ class MessageVerifiers < Messages::RotationCoordinator
     # Returns a MessageVerifier configured with a secret derived from the
     # given +salt+, and options from #rotate. MessageVerifier instances will
     # be memoized, so the same +salt+ will return the same instance.
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#[]
 
     ##
     # :method: []=
     # :call-seq: []=(salt, verifier)
     #
     # Overrides a MessageVerifier instance associated with a given +salt+.
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#[]=
 
     ##
     # :method: rotate
@@ -104,18 +116,55 @@ class MessageVerifiers < Messages::RotationCoordinator
     #
     #   # Uses `serializer: Marshal, url_safe: false`.
     #   verifiers[:baz]
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#rotate
+
+    ##
+    # :method: prepend
+    # :call-seq:
+    #   prepend(**options)
+    #   prepend(&block)
+    #
+    # Just like #rotate, but prepends the given options or block to the list of
+    # option sets.
+    #
+    # This can be useful when you have an already-configured +MessageVerifiers+
+    # instance, but you want to override the way messages are signed.
+    #
+    #   module ThirdParty
+    #     VERIFIERS = ActiveSupport::MessageVerifiers.new { ... }.
+    #       rotate(serializer: Marshal, url_safe: true).
+    #       rotate(serializer: Marshal, url_safe: false)
+    #   end
+    #
+    #   ThirdParty.VERIFIERS.prepend(serializer: JSON, url_safe: true)
+    #
+    #   # Uses `serializer: JSON, url_safe: true`.
+    #   # Falls back to `serializer: Marshal, url_safe: true` or
+    #   # `serializer: Marshal, url_safe: false`.
+    #   ThirdParty.VERIFIERS[:foo]
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#prepend
 
     ##
     # :method: rotate_defaults
     # :call-seq: rotate_defaults
     #
     # Invokes #rotate with the default options.
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#rotate_defaults
 
     ##
     # :method: clear_rotations
     # :call-seq: clear_rotations
     #
     # Clears the list of option sets.
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#clear_rotations
 
     ##
     # :method: on_rotation
@@ -127,6 +176,9 @@ class MessageVerifiers < Messages::RotationCoordinator
     # For example, this callback could log each time it is called, and thus
     # indicate whether old option sets are still in use or can be removed from
     # rotation.
+    #
+    #--
+    # Implemented by ActiveSupport::Messages::RotationCoordinator#on_rotation
 
     ##
     private

activesupport/lib/active_support/messages/rotation_coordinator.rb

@@ -32,6 +32,15 @@ def rotate(**options, &block)
         self
       end
 
+      def prepend(**options, &block)
+        raise ArgumentError, "Options cannot be specified when using a block" if block && !options.empty?
+        changing_configuration!
+
+        @rotate_options.unshift(block || options)
+
+        self
+      end
+
       def rotate_defaults
         rotate()
       end

activesupport/test/rotation_coordinator_tests.rb

@@ -34,6 +34,17 @@ module RotationCoordinatorTests
       assert_nil roundtrip("message", codec, obsolete_codec)
     end
 
+    test "prioritizes prepended rotations" do
+      @coordinator.prepend(digest: "MD5")
+      codec = @coordinator["salt"]
+
+      old_codec = (make_coordinator.rotate(digest: "MD5"))["salt"]
+      assert_equal "message", roundtrip("message", codec, old_codec)
+
+      new_codec = (make_coordinator.rotate_defaults)["salt"]
+      assert_equal "message", roundtrip("message", new_codec, codec)
+    end
+
     test "raises when building a codec and no rotations are configured" do
       assert_raises { make_coordinator["salt"] }
     end