Add Message{Encryptors,Verifiers}#transitional

This commit adds a `transitional` attribute to
`ActiveSupport::MessageEncryptors` and `ActiveSupport::MessageVerifiers`.
Setting `transitional = true` will swap the first two rotations when
building a message encryptor / verifier.  For example, with the
following configuration, message verifiers will generate messages using
`serializer: Marshal, url_safe: true`, and will able to verify messages
that were generated using any of the three option sets:

  ```ruby
  verifiers = ActiveSupport::MessageVerifiers.new { ... }
  verifiers.rotate(serializer: JSON, url_safe: true)
  verifiers.rotate(serializer: Marshal, url_safe: true)
  verifiers.rotate(serializer: Marshal, url_safe: false)
  verifiers.transitional = true
  ```

This can be useful when performing a rolling deploy of an application,
wherein servers that have not yet been updated must still be able to
verify messages from updated servers.  In particular, as it can be
applied to the default rotations of `Rails.application.message_verifiers`.

Author: jonathanhefner

activesupport/lib/active_support/message_encryptors.rb

@@ -4,6 +4,29 @@
 
 module ActiveSupport
   class MessageEncryptors < Messages::RotationCoordinator
+    ##
+    # :attr_accessor: transitional
+    #
+    # If true, the first two rotation option sets are swapped when building
+    # message encryptors. For example, with the following configuration, message
+    # encryptors will encrypt messages using <tt>serializer: Marshal, url_safe: true</tt>,
+    # and will able to decrypt messages that were encrypted using any of the
+    # three option sets:
+    #
+    #   encryptors = ActiveSupport::MessageEncryptors.new { ... }
+    #   encryptors.rotate(serializer: JSON, url_safe: true)
+    #   encryptors.rotate(serializer: Marshal, url_safe: true)
+    #   encryptors.rotate(serializer: Marshal, url_safe: false)
+    #   encryptors.transitional = true
+    #
+    # This can be useful when performing a rolling deploy of an application,
+    # wherein servers that have not yet been updated must still be able to
+    # decrypt messages from updated servers. In such a scenario, first perform a
+    # rolling deploy with the new rotation (e.g. <tt>serializer: JSON, url_safe: true</tt>)
+    # 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>.
+
     ##
     # :method: initialize
     # :call-seq: initialize(&secret_generator)

activesupport/lib/active_support/message_verifiers.rb

@@ -4,6 +4,29 @@
 
 module ActiveSupport
   class MessageVerifiers < Messages::RotationCoordinator
+    ##
+    # :attr_accessor: transitional
+    #
+    # If true, the first two rotation option sets are swapped when building
+    # message verifiers. For example, with the following configuration, message
+    # verifiers will generate messages using <tt>serializer: Marshal, url_safe: true</tt>,
+    # and will able to verify messages that were generated using any of the
+    # three option sets:
+    #
+    #   verifiers = ActiveSupport::MessageVerifiers.new { ... }
+    #   verifiers.rotate(serializer: JSON, url_safe: true)
+    #   verifiers.rotate(serializer: Marshal, url_safe: true)
+    #   verifiers.rotate(serializer: Marshal, url_safe: false)
+    #   verifiers.transitional = true
+    #
+    # This can be useful when performing a rolling deploy of an application,
+    # wherein servers that have not yet been updated must still be able to
+    # verify messages from updated servers. In such a scenario, first perform a
+    # rolling deploy with the new rotation (e.g. <tt>serializer: JSON, url_safe: true</tt>)
+    # 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>.
+
     ##
     # :method: initialize
     # :call-seq: initialize(&secret_generator)

activesupport/lib/active_support/messages/rotation_coordinator.rb

@@ -5,6 +5,8 @@
 module ActiveSupport
   module Messages
     class RotationCoordinator # :nodoc:
+      attr_accessor :transitional
+
       def initialize(&secret_generator)
         raise ArgumentError, "A secret generator block is required" unless secret_generator
         @secret_generator = secret_generator
@@ -63,7 +65,14 @@ def changing_configuration!
 
         def build_with_rotations(salt)
           raise "No options have been configured" if @rotate_options.empty?
-          @rotate_options.map { |options| build(salt, **options, on_rotation: @on_rotation) }.reduce(&:fall_back_to)
+
+          if transitional
+            rotate_options = [@rotate_options[1], @rotate_options[0], *@rotate_options[2..]].compact
+          else
+            rotate_options = @rotate_options
+          end
+
+          rotate_options.map { |options| build(salt, **options, on_rotation: @on_rotation) }.reduce(&:fall_back_to)
         end
 
         def build(salt, secret_generator:, secret_generator_options:, **options)

activesupport/test/rotation_coordinator_tests.rb

@@ -34,6 +34,37 @@ module RotationCoordinatorTests
       assert_nil roundtrip("message", codec, obsolete_codec)
     end
 
+    test "#transitional swaps the first two rotations when enabled" do
+      coordinator = make_coordinator.rotate(digest: "SHA1")
+      coordinator.rotate(digest: "MD5")
+      coordinator.rotate(digest: "MD4")
+      coordinator.transitional = true
+
+      codec = coordinator["salt"]
+      sha1_codec = (make_coordinator.rotate(digest: "SHA1"))["salt"]
+      md5_codec = (make_coordinator.rotate(digest: "MD5"))["salt"]
+      md4_codec = (make_coordinator.rotate(digest: "MD4"))["salt"]
+
+      assert_equal "message", roundtrip("message", codec, md5_codec)
+      assert_nil roundtrip("message", codec, sha1_codec)
+
+      assert_equal "message", roundtrip("message", sha1_codec, codec)
+      assert_equal "message", roundtrip("message", md5_codec, codec)
+      assert_equal "message", roundtrip("message", md4_codec, codec)
+    end
+
+    test "#transitional works with a single rotation" do
+      @coordinator.transitional = true
+
+      assert_nothing_raised do
+        codec = @coordinator["salt"]
+        assert_equal "message", roundtrip("message", codec)
+
+        different_codec = (make_coordinator.rotate(digest: "MD5"))["salt"]
+        assert_nil roundtrip("message", different_codec, codec)
+      end
+    end
+
     test "can clear rotations" do
       @coordinator.clear_rotations.rotate(digest: "MD5")
       codec = @coordinator["salt"]