activesupport 7.0.8 → 7.1.1

data/lib/active_support/message_verifier.rb

@@ -4,77 +4,73 @@ require "openssl"
 require "base64"
 require "active_support/core_ext/object/blank"
 require "active_support/security_utils"
-require "active_support/messages/metadata"
+require "active_support/messages/codec"
 require "active_support/messages/rotator"
 
 module ActiveSupport
+  # = Active Support Message Verifier
+  #
   # +MessageVerifier+ makes it easy to generate and verify messages which are
   # signed to prevent tampering.
   #
+  # In a \Rails application, you can use +Rails.application.message_verifier+
+  # to manage unique instances of verifiers for each use case.
+  # {Learn more}[link:classes/Rails/Application.html#method-i-message_verifier].
+  #
   # This is useful for cases like remember-me tokens and auto-unsubscribe links
   # where the session store isn't suitable or available.
   #
-  # Remember Me:
-  #   cookies[:remember_me] = @verifier.generate([@user.id, 2.weeks.from_now])
+  # First, generate a signed message:
+  #   cookies[:remember_me] = Rails.application.message_verifier(:remember_me).generate([@user.id, 2.weeks.from_now])
   #
-  # In the authentication filter:
+  # Later verify that message:
   #
-  #   id, time = @verifier.verify(cookies[:remember_me])
-  #   if Time.now < time
+  #   id, time = Rails.application.message_verifier(:remember_me).verify(cookies[:remember_me])
+  #   if time.future?
   #     self.current_user = User.find(id)
   #   end
   #
-  # By default it uses Marshal to serialize the message. If you want to use
-  # another serialization method, you can set the serializer in the options
-  # hash upon initialization:
-  #
-  #   @verifier = ActiveSupport::MessageVerifier.new('s3Krit', serializer: YAML)
-  #
-  # +MessageVerifier+ creates HMAC signatures using SHA1 hash algorithm by default.
-  # If you want to use a different hash algorithm, you can change it by providing
-  # +:digest+ key as an option while initializing the verifier:
+  # === Confine messages to a specific purpose
   #
-  #   @verifier = ActiveSupport::MessageVerifier.new('s3Krit', digest: 'SHA256')
+  # It's not recommended to use the same verifier for different purposes in your application.
+  # Doing so could allow a malicious actor to re-use a signed message to perform an unauthorized
+  # action.
+  # You can reduce this risk by confining signed messages to a specific +:purpose+.
   #
-  # === Confining messages to a specific purpose
-  #
-  # By default any message can be used throughout your app. But they can also be
-  # confined to a specific +:purpose+.
-  #
-  #   token = @verifier.generate("this is the chair", purpose: :login)
+  #   token = @verifier.generate("signed message", purpose: :login)
   #
   # Then that same purpose must be passed when verifying to get the data back out:
   #
-  #   @verifier.verified(token, purpose: :login)    # => "this is the chair"
+  #   @verifier.verified(token, purpose: :login)    # => "signed message"
   #   @verifier.verified(token, purpose: :shipping) # => nil
   #   @verifier.verified(token)                     # => nil
   #
-  #   @verifier.verify(token, purpose: :login)      # => "this is the chair"
-  #   @verifier.verify(token, purpose: :shipping)   # => ActiveSupport::MessageVerifier::InvalidSignature
-  #   @verifier.verify(token)                       # => ActiveSupport::MessageVerifier::InvalidSignature
+  #   @verifier.verify(token, purpose: :login)      # => "signed message"
+  #   @verifier.verify(token, purpose: :shipping)   # => raises ActiveSupport::MessageVerifier::InvalidSignature
+  #   @verifier.verify(token)                       # => raises ActiveSupport::MessageVerifier::InvalidSignature
   #
   # Likewise, if a message has no purpose it won't be returned when verifying with
   # a specific purpose.
   #
-  #   token = @verifier.generate("the conversation is lively")
-  #   @verifier.verified(token, purpose: :scare_tactics) # => nil
-  #   @verifier.verified(token)                          # => "the conversation is lively"
+  #   token = @verifier.generate("signed message")
+  #   @verifier.verified(token, purpose: :redirect) # => nil
+  #   @verifier.verified(token)                     # => "signed message"
   #
-  #   @verifier.verify(token, purpose: :scare_tactics)   # => ActiveSupport::MessageVerifier::InvalidSignature
-  #   @verifier.verify(token)                            # => "the conversation is lively"
+  #   @verifier.verify(token, purpose: :redirect)   # => raises ActiveSupport::MessageVerifier::InvalidSignature
+  #   @verifier.verify(token)                       # => "signed message"
   #
-  # === Making messages expire
+  # === Expiring messages
   #
   # By default messages last forever and verifying one year from now will still
   # return the original value. But messages can be set to expire at a given
   # time with +:expires_in+ or +:expires_at+.
   #
-  #   @verifier.generate("parcel", expires_in: 1.month)
-  #   @verifier.generate("doowad", expires_at: Time.now.end_of_year)
+  #   @verifier.generate("signed message", expires_in: 1.month)
+  #   @verifier.generate("signed message", expires_at: Time.now.end_of_year)
   #
-  # Then the messages can be verified and returned up to the expire time.
+  # Messages can then be verified and returned until expiry.
   # Thereafter, the +verified+ method returns +nil+ while +verify+ raises
-  # <tt>ActiveSupport::MessageVerifier::InvalidSignature</tt>.
+  # +ActiveSupport::MessageVerifier::InvalidSignature+.
   #
   # === Rotating keys
   #
@@ -92,52 +88,98 @@ module ActiveSupport
   # Then gradually rotate the old values out by adding them as fallbacks. Any message
   # generated with the old values will then work until the rotation is removed.
   #
-  #   verifier.rotate old_secret          # Fallback to an old secret instead of @secret.
-  #   verifier.rotate digest: "SHA256"    # Fallback to an old digest instead of SHA512.
-  #   verifier.rotate serializer: Marshal # Fallback to an old serializer instead of JSON.
+  #   verifier.rotate(old_secret)          # Fallback to an old secret instead of @secret.
+  #   verifier.rotate(digest: "SHA256")    # Fallback to an old digest instead of SHA512.
+  #   verifier.rotate(serializer: Marshal) # Fallback to an old serializer instead of JSON.
   #
   # Though the above would most likely be combined into one rotation:
   #
-  #   verifier.rotate old_secret, digest: "SHA256", serializer: Marshal
-  class MessageVerifier
-    prepend Messages::Rotator::Verifier
+  #   verifier.rotate(old_secret, digest: "SHA256", serializer: Marshal)
+  class MessageVerifier < Messages::Codec
+    prepend Messages::Rotator
 
     class InvalidSignature < StandardError; end
 
     SEPARATOR = "--" # :nodoc:
     SEPARATOR_LENGTH = SEPARATOR.length # :nodoc:
 
-    def initialize(secret, digest: nil, serializer: nil)
+    # Initialize a new MessageVerifier with a secret for the signature.
+    #
+    # ==== Options
+    #
+    # [+:digest+]
+    #   Digest used for signing. The default is <tt>"SHA1"</tt>. See
+    #   +OpenSSL::Digest+ for alternatives.
+    #
+    # [+:serializer+]
+    #   The serializer used to serialize message data. You can specify any
+    #   object that responds to +dump+ and +load+, or you can choose from
+    #   several preconfigured serializers: +:marshal+, +:json_allow_marshal+,
+    #   +:json+, +:message_pack_allow_marshal+, +:message_pack+.
+    #
+    #   The preconfigured serializers include a fallback mechanism to support
+    #   multiple deserialization formats. For example, the +:marshal+ serializer
+    #   will serialize using +Marshal+, but can deserialize using +Marshal+,
+    #   ActiveSupport::JSON, or ActiveSupport::MessagePack. This makes it easy
+    #   to migrate between serializers.
+    #
+    #   The +:marshal+, +:json_allow_marshal+, and +:message_pack_allow_marshal+
+    #   serializers support deserializing using +Marshal+, but the others do
+    #   not. Beware that +Marshal+ is a potential vector for deserialization
+    #   attacks in cases where a message signing secret has been leaked. <em>If
+    #   possible, choose a serializer that does not support +Marshal+.</em>
+    #
+    #   The +:message_pack+ and +:message_pack_allow_marshal+ serializers use
+    #   ActiveSupport::MessagePack, which can roundtrip some Ruby types that are
+    #   not supported by JSON, and may provide improved performance. However,
+    #   these require the +msgpack+ gem.
+    #
+    #   When using \Rails, the default depends on +config.active_support.message_serializer+.
+    #   Otherwise, the default is +:marshal+.
+    #
+    # [+:url_safe+]
+    #   By default, MessageVerifier generates RFC 4648 compliant strings which are
+    #   not URL-safe. In other words, they can contain "+" and "/". If you want to
+    #   generate URL-safe strings (in compliance with "Base 64 Encoding with URL
+    #   and Filename Safe Alphabet" in RFC 4648), you can pass +true+.
+    #
+    # [+:force_legacy_metadata_serializer+]
+    #   Whether to use the legacy metadata serializer, which serializes the
+    #   message first, then wraps it in an envelope which is also serialized. This
+    #   was the default in \Rails 7.0 and below.
+    #
+    #   If you don't pass a truthy value, the default is set using
+    #   +config.active_support.use_message_serializer_for_metadata+.
+    def initialize(secret, **options)
       raise ArgumentError, "Secret should not be nil." unless secret
+      super(**options)
       @secret = secret
-      @digest = digest&.to_s || "SHA1"
-      @serializer = serializer || Marshal
+      @digest = options[:digest]&.to_s || "SHA1"
     end
 
     # Checks if a signed message could have been generated by signing an object
     # with the +MessageVerifier+'s secret.
     #
-    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
-    #   signed_message = verifier.generate 'a private message'
+    #   verifier = ActiveSupport::MessageVerifier.new("secret")
+    #   signed_message = verifier.generate("signed message")
     #   verifier.valid_message?(signed_message) # => true
     #
     #   tampered_message = signed_message.chop # editing the message invalidates the signature
     #   verifier.valid_message?(tampered_message) # => false
-    def valid_message?(signed_message)
-      data, digest = get_data_and_digest_from(signed_message)
-      digest_matches_data?(digest, data)
+    def valid_message?(message)
+      !!catch_and_ignore(:invalid_message_format) { extract_encoded(message) }
     end
 
     # Decodes the signed message using the +MessageVerifier+'s secret.
     #
-    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
+    #   verifier = ActiveSupport::MessageVerifier.new("secret")
     #
-    #   signed_message = verifier.generate 'a private message'
-    #   verifier.verified(signed_message) # => 'a private message'
+    #   signed_message = verifier.generate("signed message")
+    #   verifier.verified(signed_message) # => "signed message"
     #
     # Returns +nil+ if the message was not signed with the same secret.
     #
-    #   other_verifier = ActiveSupport::MessageVerifier.new 'd1ff3r3nt-s3Krit'
+    #   other_verifier = ActiveSupport::MessageVerifier.new("different_secret")
     #   other_verifier.verified(signed_message) # => nil
     #
     # Returns +nil+ if the message is not Base64-encoded.
@@ -149,33 +191,68 @@ module ActiveSupport
     #
     #   incompatible_message = "test--dad7b06c94abba8d46a15fafaef56c327665d5ff"
     #   verifier.verified(incompatible_message) # => TypeError: incompatible marshal file format
-    def verified(signed_message, purpose: nil, **)
-      data, digest = get_data_and_digest_from(signed_message)
-      if digest_matches_data?(digest, data)
-        begin
-          message = Messages::Metadata.verify(decode(data), purpose)
-          @serializer.load(message) if message
-        rescue ArgumentError => argument_error
-          return if argument_error.message.include?("invalid base64")
-          raise
+    #
+    # ==== Options
+    #
+    # [+:purpose+]
+    #   The purpose that the message was generated with. If the purpose does not
+    #   match, +verified+ will return +nil+.
+    #
+    #     message = verifier.generate("hello", purpose: "greeting")
+    #     verifier.verified(message, purpose: "greeting") # => "hello"
+    #     verifier.verified(message, purpose: "chatting") # => nil
+    #     verifier.verified(message)                      # => nil
+    #
+    #     message = verifier.generate("bye")
+    #     verifier.verified(message)                      # => "bye"
+    #     verifier.verified(message, purpose: "greeting") # => nil
+    #
+    def verified(message, **options)
+      catch_and_ignore :invalid_message_format do
+        catch_and_raise :invalid_message_serialization do
+          catch_and_ignore :invalid_message_content do
+            read_message(message, **options)
+          end
         end
       end
     end
 
     # Decodes the signed message using the +MessageVerifier+'s secret.
     #
-    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
-    #   signed_message = verifier.generate 'a private message'
+    #   verifier = ActiveSupport::MessageVerifier.new("secret")
+    #   signed_message = verifier.generate("signed message")
     #
-    #   verifier.verify(signed_message) # => 'a private message'
+    #   verifier.verify(signed_message) # => "signed message"
     #
     # Raises +InvalidSignature+ if the message was not signed with the same
     # secret or was not Base64-encoded.
     #
-    #   other_verifier = ActiveSupport::MessageVerifier.new 'd1ff3r3nt-s3Krit'
+    #   other_verifier = ActiveSupport::MessageVerifier.new("different_secret")
     #   other_verifier.verify(signed_message) # => ActiveSupport::MessageVerifier::InvalidSignature
-    def verify(*args, **options)
-      verified(*args, **options) || raise(InvalidSignature)
+    #
+    # ==== Options
+    #
+    # [+:purpose+]
+    #   The purpose that the message was generated with. If the purpose does not
+    #   match, +verify+ will raise ActiveSupport::MessageVerifier::InvalidSignature.
+    #
+    #     message = verifier.generate("hello", purpose: "greeting")
+    #     verifier.verify(message, purpose: "greeting") # => "hello"
+    #     verifier.verify(message, purpose: "chatting") # => raises InvalidSignature
+    #     verifier.verify(message)                      # => raises InvalidSignature
+    #
+    #     message = verifier.generate("bye")
+    #     verifier.verify(message)                      # => "bye"
+    #     verifier.verify(message, purpose: "greeting") # => raises InvalidSignature
+    #
+    def verify(message, **options)
+      catch_and_raise :invalid_message_format, as: InvalidSignature do
+        catch_and_raise :invalid_message_serialization do
+          catch_and_raise :invalid_message_content, as: InvalidSignature do
+            read_message(message, **options)
+          end
+        end
+      end
     end
 
     # Generates a signed message for the provided value.
@@ -183,20 +260,72 @@ module ActiveSupport
     # The message is signed with the +MessageVerifier+'s secret.
     # Returns Base64-encoded message joined with the generated signature.
     #
-    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
-    #   verifier.generate 'a private message' # => "BAhJIhRwcml2YXRlLW1lc3NhZ2UGOgZFVA==--e2d724331ebdee96a10fb99b089508d1c72bd772"
-    def generate(value, expires_at: nil, expires_in: nil, purpose: nil)
-      data = encode(Messages::Metadata.wrap(@serializer.dump(value), expires_at: expires_at, expires_in: expires_in, purpose: purpose))
-      "#{data}#{SEPARATOR}#{generate_digest(data)}"
+    #   verifier = ActiveSupport::MessageVerifier.new("secret")
+    #   verifier.generate("signed message") # => "BAhJIhNzaWduZWQgbWVzc2FnZQY6BkVU--f67d5f27c3ee0b8483cebf2103757455e947493b"
+    #
+    # ==== Options
+    #
+    # [+:expires_at+]
+    #   The datetime at which the message expires. After this datetime,
+    #   verification of the message will fail.
+    #
+    #     message = verifier.generate("hello", expires_at: Time.now.tomorrow)
+    #     verifier.verified(message) # => "hello"
+    #     # 24 hours later...
+    #     verifier.verified(message) # => nil
+    #     verifier.verify(message)   # => raises ActiveSupport::MessageVerifier::InvalidSignature
+    #
+    # [+:expires_in+]
+    #   The duration for which the message is valid. After this duration has
+    #   elapsed, verification of the message will fail.
+    #
+    #     message = verifier.generate("hello", expires_in: 24.hours)
+    #     verifier.verified(message) # => "hello"
+    #     # 24 hours later...
+    #     verifier.verified(message) # => nil
+    #     verifier.verify(message)   # => raises ActiveSupport::MessageVerifier::InvalidSignature
+    #
+    # [+:purpose+]
+    #   The purpose of the message. If specified, the same purpose must be
+    #   specified when verifying the message; otherwise, verification will fail.
+    #   (See #verified and #verify.)
+    def generate(value, **options)
+      create_message(value, **options)
+    end
+
+    def create_message(value, **options) # :nodoc:
+      sign_encoded(encode(serialize_with_metadata(value, **options)))
+    end
+
+    def read_message(message, **options) # :nodoc:
+      deserialize_with_metadata(decode(extract_encoded(message)), **options)
+    end
+
+    def inspect # :nodoc:
+      "#<#{self.class.name}:#{'%#016x' % (object_id << 1)}>"
     end
 
     private
-      def encode(data)
-        ::Base64.strict_encode64(data)
+      def sign_encoded(encoded)
+        digest = generate_digest(encoded)
+        encoded << SEPARATOR << digest
       end
 
-      def decode(data)
-        ::Base64.strict_decode64(data)
+      def extract_encoded(signed)
+        if signed.nil? || !signed.valid_encoding?
+          throw :invalid_message_format, "invalid message string"
+        end
+
+        if separator_index = separator_index_for(signed)
+          encoded = signed[0, separator_index]
+          digest = signed[separator_index + SEPARATOR_LENGTH, digest_length_in_hex]
+        end
+
+        unless digest_matches_data?(digest, encoded)
+          throw :invalid_message_format, "mismatched digest"
+        end
+
+        encoded
       end
 
       def generate_digest(data)
@@ -211,23 +340,13 @@ module ActiveSupport
         @digest_length_in_hex ||= OpenSSL::Digest.new(@digest).digest_length * 2
       end
 
-      def separator_index_for(signed_message)
-        index = signed_message.length - digest_length_in_hex - SEPARATOR_LENGTH
-        return if index.negative? || signed_message[index, SEPARATOR_LENGTH] != SEPARATOR
-
-        index
+      def separator_at?(signed_message, index)
+        signed_message[index, SEPARATOR_LENGTH] == SEPARATOR
       end
 
-      def get_data_and_digest_from(signed_message)
-        return if signed_message.nil? || !signed_message.valid_encoding? || signed_message.empty?
-
-        separator_index = separator_index_for(signed_message)
-        return if separator_index.nil?
-
-        data = signed_message[0...separator_index]
-        digest = signed_message[separator_index + SEPARATOR_LENGTH..-1]
-
-        [data, digest]
+      def separator_index_for(signed_message)
+        index = signed_message.length - digest_length_in_hex - SEPARATOR_LENGTH
+        index unless index.negative? || !separator_at?(signed_message, index)
       end
 
       def digest_matches_data?(digest, data)

data/lib/active_support/message_verifiers.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "active_support/messages/rotation_coordinator"
+
+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)
+    #
+    # Initializes a new instance. +secret_generator+ must accept a salt, and
+    # return a suitable secret (string). +secret_generator+ may also accept
+    # arbitrary kwargs. If #rotate is called with any options matching those
+    # kwargs, those options will be passed to +secret_generator+ instead of to
+    # the message verifier.
+    #
+    #   verifiers = ActiveSupport::MessageVerifiers.new do |salt, base:|
+    #     MySecretGenerator.new(base).generate(salt)
+    #   end
+    #
+    #   verifiers.rotate(base: "...")
+
+    ##
+    # :method: []
+    # :call-seq: [](salt)
+    #
+    # 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.
+
+    ##
+    # :method: []=
+    # :call-seq: []=(salt, verifier)
+    #
+    # Overrides a MessageVerifier instance associated with a given +salt+.
+
+    ##
+    # :method: rotate
+    # :call-seq: rotate(**options)
+    #
+    # Adds +options+ to the list of option sets. Messages will be signed using
+    # the first set in the list. When verifying, however, each set will be
+    # tried, in order, until one succeeds.
+    #
+    # Notably, the +:secret_generator+ option can specify a different secret
+    # generator than the one initially specified. The secret generator must
+    # respond to +call+, accept a salt, and return a suitable secret (string).
+    # The secret generator may also accept arbitrary kwargs.
+    #
+    # If any options match the kwargs of the operative secret generator, those
+    # options will be passed to the secret generator instead of to the message
+    # verifier.
+    #
+    # For fine-grained per-salt rotations, a block form is supported. The block
+    # will receive the salt, and should return an appropriate options Hash. The
+    # block may also return +nil+ to indicate that the rotation does not apply
+    # to the given salt. For example:
+    #
+    #   verifiers = ActiveSupport::MessageVerifiers.new { ... }
+    #
+    #   verifiers.rotate do |salt|
+    #     case salt
+    #     when :foo
+    #       { serializer: JSON, url_safe: true }
+    #     when :bar
+    #       { serializer: Marshal, url_safe: true }
+    #     end
+    #   end
+    #
+    #   verifiers.rotate(serializer: Marshal, url_safe: false)
+    #
+    #   # Uses `serializer: JSON, url_safe: true`.
+    #   # Falls back to `serializer: Marshal, url_safe: false`.
+    #   verifiers[:foo]
+    #
+    #   # Uses `serializer: Marshal, url_safe: true`.
+    #   # Falls back to `serializer: Marshal, url_safe: false`.
+    #   verifiers[:bar]
+    #
+    #   # Uses `serializer: Marshal, url_safe: false`.
+    #   verifiers[:baz]
+
+    ##
+    # :method: rotate_defaults
+    # :call-seq: rotate_defaults
+    #
+    # Invokes #rotate with the default options.
+
+    ##
+    # :method: clear_rotations
+    # :call-seq: clear_rotations
+    #
+    # Clears the list of option sets.
+
+    ##
+    # :method: on_rotation
+    # :call-seq: on_rotation(&callback)
+    #
+    # Sets a callback to invoke when a message is verified using an option set
+    # other than the first.
+    #
+    # 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.
+
+    ##
+    private
+      def build(salt, secret_generator:, secret_generator_options:, **options)
+        MessageVerifier.new(secret_generator.call(salt, **secret_generator_options), **options)
+      end
+  end
+end

data/lib/active_support/messages/codec.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/class/attribute"
+require_relative "metadata"
+require_relative "serializer_with_fallback"
+
+module ActiveSupport
+  module Messages # :nodoc:
+    class Codec # :nodoc:
+      include Metadata
+
+      class_attribute :default_serializer, default: :marshal,
+        instance_accessor: false, instance_predicate: false
+
+      def initialize(**options)
+        @serializer = options[:serializer] || self.class.default_serializer
+        @serializer = SerializerWithFallback[@serializer] if @serializer.is_a?(Symbol)
+        @url_safe = options[:url_safe]
+        @force_legacy_metadata_serializer = options[:force_legacy_metadata_serializer]
+      end
+
+      private
+        attr_reader :serializer
+
+        def encode(data, url_safe: @url_safe)
+          url_safe ? ::Base64.urlsafe_encode64(data, padding: false) : ::Base64.strict_encode64(data)
+        end
+
+        def decode(encoded, url_safe: @url_safe)
+          url_safe ? ::Base64.urlsafe_decode64(encoded) : ::Base64.strict_decode64(encoded)
+        rescue ArgumentError => error
+          throw :invalid_message_format, error
+        end
+
+        def serialize(data)
+          serializer.dump(data)
+        end
+
+        def deserialize(serialized)
+          serializer.load(serialized)
+        rescue StandardError => error
+          throw :invalid_message_serialization, error
+        end
+
+        def catch_and_ignore(throwable, &block)
+          catch throwable do
+            return block.call
+          end
+          nil
+        end
+
+        def catch_and_raise(throwable, as: nil, &block)
+          error = catch throwable do
+            return block.call
+          end
+          error = as.new(error.to_s) if as
+          raise error
+        end
+
+        def use_message_serializer_for_metadata?
+          !@force_legacy_metadata_serializer && super
+        end
+    end
+  end
+end