mongoid 9.0.11 → 9.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6976a4808058209fda8554306590eeb5fd44759d8c228d02bca544acbe5c200
-  data.tar.gz: e0dcd20719682c2a425d9ed17c1459376b6956311f9ec439c74843a4cefb8502
+  metadata.gz: 030d90a4693fc5b3ccb72a7069ce6dc912089351df98fd04ead3595a414433a0
+  data.tar.gz: 10362c8758cb9ec1e535b9940eab11088261e7cf4831b8a07bfffb6be231e8df
 SHA512:
-  metadata.gz: 64ee6ee13a326ed9fae0e6b6dc08fa28ba0608a75342993b873023e4f87076160f6a8997e3edd53a273da4716c92d5aabc6b49f0931a489d2074d92f8de912d7
-  data.tar.gz: 491ecfb05581a08609bc41aedd39600f143a15f681405400c813402be95e11ed24d4be7363ac8079da9bc022d7d5b22ad3c53e534d41ee66a10977751a44b954
+  metadata.gz: 8e5d6bfa84e64cd80f756e55d6fe846f10b5a820c79881b26a54c305f08fb02ef98d27990d7b51b595342844b38c11e04b6e9be911cd3306748c023d226bf9a2
+  data.tar.gz: 5a92a5485360f68cea7bbfa48259f0441f0df723d634926230c80b78784e6f8719083b3fef9d81537223b0da8f2b96563c8d267c4bbe9a372c592b781163fe45

data/lib/config/locales/en.yml

@@ -140,6 +140,32 @@ en:
             A collation option is only supported if the query is executed on a MongoDB server
             with version >= 3.4."
           resolution: "Remove the collation option from the query."
+        in_memory_regexp_timeout:
+          message: "Evaluating this query in memory exceeded the %{limit} second
+            limit that applies to conditions containing a regular expression."
+          summary: "Mongoid evaluates some conditions in the calling thread
+            rather than sending them to the server: queries against an embedded
+            association, removing documents from an association by condition,
+            and Document#_matches?. A regular expression in such a condition
+            runs locally. Mongoid limits the total time one in-memory
+            evaluation may spend matching, because both the cost of a single
+            match and the number of matches performed grow with the condition,
+            and a pattern built from end-user input can be made to consume an
+            unbounded amount of CPU. The limit is cumulative over the whole
+            evaluation rather than per match. Where the Ruby in use offers no
+            per-Regexp timeout the limit is enforced as wall clock over the
+            whole in-memory evaluation, so there it can be exceeded by a large
+            scan even when the pattern itself is cheap."
+          resolution: "Check whether the pattern in this query comes from user
+            input; if it does, validate it before querying. If the query is
+            legitimate and simply large, raise
+            Mongoid::Config.in_memory_regexp_time_limit, or set it to nil to
+            remove the limit entirely. The limit in force is the smaller of
+            that setting and any global Regexp.timeout the application has set,
+            so check both. On JRuby, and on MRI before 3.2, there is no
+            per-Regexp timeout, so what the limit bounds there is the elapsed
+            time of the whole in-memory evaluation rather than the time spent
+            matching."
         invalid_around_callback:
           message: "An around callback must contain a yield in its definition."
           summary: "The block needs to be yielded to for around callbacks to function as intended."
@@ -213,6 +239,13 @@ en:
             Mongoid does not support."
           resolution: "Valid field operators are: %{valid_operators}.
             Ensure you are using one of these operators."
+        invalid_encryption_schema:
+          message: "The encryption schema for %{namespace} is invalid."
+          summary: "Two models writing to %{namespace} describe %{path}
+            differently. The encryption schema has one entry per namespace,
+            so the two descriptions cannot both be used."
+          resolution: "Make the models agree on the encryption options of the
+            conflicting field, or store them in different collections."
         invalid_estimated_count_criteria:
           message: "Invalid criteria for estimated_count."
           summary: "Estimated count is strictly a collection-level operation and cannot be called
@@ -515,6 +548,38 @@ en:
             environment, Mongoid cannot load its configuration."
           resolution: "Please ensure an environment is set in one of the
             listed locations. The environment must be explicitly set."
+        no_encryption_schema:
+          message: "The encryption schema of client %{client} does not cover
+            %{namespace}."
+          summary: "%{klass} declares encrypted fields, directly or through
+            an embedded model, but the namespace it resolved to, %{namespace},
+            is not part of the automatic encryption schema of client
+            %{client}. The encryption schema is built once, when the client
+            is created, and is keyed by namespace, so a database name that is
+            only known later - a callable :database option,
+            Model.with(database:), Mongoid.override_database - is not in it.
+            The same happens when an embedded model with encrypted fields was
+            not yet loaded when the client was created. Routing the model to a
+            client that has no auto_encryption_options has the same effect.
+            Mongoid refuses the operation because the driver would store the
+            declared fields in plaintext without reporting an error."
+          resolution: "Give the model a namespace that is known when the
+            client is created, and a client configured with
+            auto_encryption_options. Load all models, including embedded
+            ones, before the first client is created, for example by
+            preloading them at boot. If the model has to live in a database
+            chosen at runtime, configure one client per database, each with
+            its own auto_encryption_options, and select between them with
+            Model.with(client:) instead of switching the database."
+        no_encryption_schema_field:
+          message: "The encryption schema of client %{client} does not cover
+            the field %{field} of %{namespace}."
+          summary: "The namespace %{namespace} is in the automatic encryption
+            schema of client %{client}, but its entry does not encrypt
+            %{field}, which %{klass} declares as encrypted. Mongoid refuses
+            the operation rather than storing the field in plaintext."
+          resolution: "Regenerate the schema map of the client, or add
+            %{field} to the schema entry for %{namespace}."
         no_map_reduce_output:
           message: "No output location was specified for the map/reduce
             operation."

data/lib/mongoid/association/depending.rb

@@ -12,11 +12,15 @@ module Mongoid
       included do
         class_attribute :dependents
 
+        # Note the leading underscore: without it, ActiveSupport's
+        # class_attribute would generate a helper method for this attribute
+        # that collides with one it generates for :dependents.
+        #
         # @api private
-        class_attribute :dependents_owner
+        class_attribute :_dependents_owner
 
         self.dependents = []
-        self.dependents_owner = self
+        self._dependents_owner = self
       end
 
       class_methods do
@@ -57,9 +61,9 @@ module Mongoid
       def self.define_dependency!(association)
         validate!(association)
         association.inverse_class.tap do |klass|
-          if klass.dependents_owner != klass
+          if klass._dependents_owner != klass
             klass.dependents = []
-            klass.dependents_owner = klass
+            klass._dependents_owner = klass
           end
 
           if association.dependent && !klass.dependents.include?(association)

data/lib/mongoid/association/embedded/batchable.rb

@@ -138,6 +138,14 @@ module Mongoid
             _base.collect_children.each do |child|
               child.delayed_atomic_sets.clear
             end
+
+            # If the base document is itself inserted wholesale via a $set of
+            # its atomic path, that $set already contains these documents, and
+            # a nested $set under the same path would conflict with it. The
+            # cleanup above has already cleared the delayed sets the assigned
+            # children recorded, so skipping the recording here is safe.
+            return if _base.settable?
+
             _base.delayed_atomic_sets[path] = sets
           end
         end

data/lib/mongoid/association/nested/many.rb

@@ -174,7 +174,7 @@ module Mongoid
         # @param [ Hash ] attrs The single document attributes to process.
         def update_nested_relation(parent, id, attrs)
           first = existing.first
-          converted = first ? convert_id(first.class, id) : id
+          converted = convert_id(first ? first.class : association.klass, id)
 
           if existing.where(_id: converted).exists?
             # document exists in association
@@ -186,19 +186,48 @@ module Mongoid
             end
           elsif association.embedded?
             raise Errors::DocumentNotFound.new(association.klass, id)
-          elsif association.is_a?(Association::Referenced::HasAndBelongsToMany) || Mongoid.allow_reparenting_via_nested_attributes?
-            Mongoid::Warnings.warn_reparenting_via_nested_attributes if Mongoid.allow_reparenting_via_nested_attributes?
+          elsif destroyable?(attrs)
+            # A destroy of a document that is not in the association is
+            # ignored, rather than reaching for it outside the association.
+            nil
+          elsif Mongoid.allow_reparenting_via_nested_attributes?
+            Mongoid::Warnings.warn_reparenting_via_nested_attributes
 
             # push existing document to association
             doc = association.klass.unscoped.find(converted)
+            # find returns nil instead of raising when
+            # Mongoid.raise_not_found_error is false; a missing document
+            # must still be an error here, consistent with the other
+            # not-found branches.
+            raise Errors::DocumentNotFound.new(association.klass, id) if doc.nil?
+
             update_document(doc, attrs)
-            existing.push(doc) unless destroyable?(attrs)
+            existing.push(doc)
           else
-            raise Errors::DocumentNotFound.new(association.klass, { _id: id, association.foreign_key => parent.id })
+            raise Errors::DocumentNotFound.new(association.klass, not_found_params(parent, id))
           end
 
           parent.children_may_have_changed!
         end
+
+        # The params to report when an id in the nested attributes could not
+        # be resolved within the association.
+        #
+        # @api private
+        #
+        # @param [ Document ] parent The parent document.
+        # @param [ String | BSON::ObjectId ] id of the related document.
+        #
+        # @return [ Hash | Object ] The params for the not found error.
+        def not_found_params(parent, id)
+          if association.is_a?(Association::Referenced::HasAndBelongsToMany)
+            # A many-to-many association has no foreign key on the child, so
+            # the id is only ever resolved within the association itself.
+            id
+          else
+            { _id: id, association.foreign_key => parent.id }
+          end
+        end
       end
     end
   end

data/lib/mongoid/association/nested/nested_buildable.rb

@@ -58,12 +58,26 @@ module Mongoid
         # @example Convert the id.
         #   builder.convert_id(Person, "4d371b444835d98b8b000010")
         #
+        # Ids arriving from a form are always scalars. A Hash or an Array
+        # here means the parameters were crafted, and letting one through
+        # would turn the id into a query operator, so they are rejected.
+        #
         # @param [ Class ] klass The class we're trying to convert for.
         # @param [ String ] id The id, usually coming from the form.
         #
         # @return [ BSON::ObjectId | String | Object ] The converted id.
+        #
+        # @raise [ Errors::DocumentNotFound ] if the id is not a scalar, or
+        #   cannot be converted to the type the class uses for its ids.
+        #   The BSON::Error rescue is defensive: a value that reaches
+        #   BSON::ObjectId.mongoize and raises there must not surface as an
+        #   unhandled BSON error in the caller.
         def convert_id(klass, id)
+          raise Errors::DocumentNotFound.new(klass, id) if id.is_a?(::Hash) || id.is_a?(::Array)
+
           klass.using_object_ids? ? BSON::ObjectId.mongoize(id) : id
+        rescue BSON::Error
+          raise Errors::DocumentNotFound.new(klass, id)
         end
 
         private

data/lib/mongoid/association/referenced/has_many/proxy.rb

@@ -534,12 +534,111 @@ module Mongoid
           # @return [ Integer ] The number of documents deleted.
           def remove_all(conditions = nil, method = :delete_all)
             selector = conditions || {}
-            removed = klass.send(method, selector.merge!(criteria.selector))
+            selector.merge!(criteria.selector)
+
+            # Scanning before the delete means scanning only what is already in
+            # memory, so it is only done where there is a pattern whose cost has
+            # to be bounded. Everywhere else the delete comes first and the scan
+            # sees the survivors, which is what this association has always
+            # done.
+            #
+            # The limit is read once and carried into whichever branch is taken.
+            # Letting the branch below ask again would read it a second time,
+            # across a server round trip, and a limit that had become positive
+            # in the meantime would put a deadline on the delete_if -- a query,
+            # and an unbind of every match -- which is the arrangement this
+            # branch exists to avoid.
+            limit = Matcher::RegexpBudget.limit_for(selector)
+            return remove_all_bounded(selector, method, limit) if limit
+
+            removed = klass.send(method, selector)
+
+            # No scope around this. The scan runs after the delete, so the
+            # association this loads comes back holding only what the delete did
+            # not match, and there is no pattern here to bound in any case.
+            # Opening a scope would save _matches? from deciding once per
+            # document -- 0.48us against 1.74us for the match itself -- but a
+            # scope with nothing to bound suppresses that decision for
+            # everything nested inside it, and loading the association runs
+            # find callbacks. A pattern in a selector one of those evaluates
+            # would go unguarded, which costs more than the saving is worth on a
+            # path that has just made two round trips.
             _target.delete_if do |doc|
               doc._matches?(selector).tap do |b|
                 unbind_one(doc) if b
               end
             end
+
+            removed
+          end
+
+          # Deletes all related documents matching a selector that carries a
+          # regular expression, with the whole scan under one regexp budget.
+          #
+          # The scan runs before anything is deleted, so a budget that runs out
+          # leaves both the database and the association untouched rather than
+          # reporting a failure for a delete that has already happened. It also
+          # means the budget is closed by the time the association is mutated,
+          # so where the budget is enforced with Timeout there is no window for
+          # the exception to land in the middle of an unbind.
+          #
+          # @param [ Hash ] selector The selector to delete with.
+          # @param [ Symbol ] method The deletion method to call.
+          # @param [ Float ] limit The seconds the scan may spend, as read by
+          #   the caller when it chose this path.
+          #
+          # @return [ Integer ] The number of documents deleted.
+          def remove_all_bounded(selector, method, limit)
+            # Only what the association already holds. Iterating it instead
+            # would load the whole association before the delete, and for a
+            # broad pattern that is every document the association has: /.*/ is
+            # both the cheapest pattern an attacker can supply and the one that
+            # matches everything, so bounding the cost of the matching would
+            # have been paid for with an unbounded amount of memory. Nothing is
+            # missed by not loading, because the server evaluates the same
+            # selector for the delete itself.
+            #
+            # It also means the scan runs no query, so no deadline of ours can
+            # land on one. Where the budget is enforced with Timeout, covering
+            # a query would report a slow network as a regexp timeout and could
+            # deliver the asynchronous exception inside the driver's socket
+            # read.
+            documents = _target.in_memory
+
+            matching = Matcher::RegexpBudget.open_with(limit) do
+              documents.select { |doc| doc._matches?(selector) }
+            end
+
+            removed = klass.send(method, selector)
+
+            # The ids are already known to be in memory, so the loaded and added
+            # documents can be dropped directly. Enumerable#delete would look
+            # each one up by id and stop at the first hash that has it, which
+            # removes the wrong instance when both hashes hold one for the same
+            # id. Enumerable#delete_if drops it from both, as this does, but
+            # only after load_all!, which is the load this scan exists to avoid.
+            #
+            # Which documents get unbound has always depended on which ones
+            # happened to be in memory, and scanning only what is in memory
+            # keeps that. It matters for has_and_belongs_to_many, whose
+            # unbind_one pulls the id out of the foreign key array on _base and
+            # marks it dirty; the scan used to run after the delete, against an
+            # association that a cold proxy had just reloaded as holding only
+            # the survivors, so nothing matched and nothing was unbound.
+            #
+            # TODO: unbinding should not depend on what was in memory. Every
+            # matched document leaves the association, so every one of them
+            # should be unbound, which would also stop _base's foreign key
+            # array from keeping ids that no longer resolve. That is a
+            # behaviour change for has_and_belongs_to_many and belongs in a
+            # ticket of its own, with a release note; it should not ride along
+            # on this one.
+            matching.each do |doc|
+              unbind_one(doc)
+              _target._loaded.delete(doc._id)
+              _target._added.delete(doc._id)
+            end
+
             removed
           end
 

data/lib/mongoid/association/relatable.rb

@@ -172,6 +172,23 @@ module Mongoid
       end
       alias :klass :relation_class
 
+      # The class of the association target, or nil when the named class is
+      # not defined.
+      #
+      # An association may name a class that never gets defined. The
+      # association is then unusable, but its owner still has to be. Callers
+      # that walk every association of every model, rather than following the
+      # one the application asked for, use this instead of relation_class.
+      #
+      # @return [ Class | nil ] The association objects' class.
+      #
+      # @api private
+      def try_relation_class
+        relation_class
+      rescue NameError
+        nil
+      end
+
       # The class name of the object owning this association.
       #
       # @return [ String ] The owning objects' class name.

data/lib/mongoid/clients/factory.rb

@@ -91,6 +91,8 @@ module Mongoid
         return nil unless opts[:auto_encryption_options]
 
         opts[:auto_encryption_options].dup.tap do |auto_encryption_options|
+          Mongoid::Warnings.warn_bypass_auto_encryption if auto_encryption_options[:bypass_auto_encryption]
+
           if auto_encryption_options.key?(:schema_map)
             default_logger.warn(
               'The :schema_map is configured in the :auto_encryption_options for the client;' +

data/lib/mongoid/collection_configurable.rb

@@ -22,6 +22,14 @@ module Mongoid
       # @raise [ Errors::CreateCollectionFailure ] If collection creation failed.
       # @raise [ Errors::DropCollectionFailure ] If an attempt to drop collection failed.
       def create_collection(force: false)
+        Threaded.with_collection_management do
+          perform_create_collection(force: force)
+        end
+      end
+
+      private
+
+      def perform_create_collection(force:)
         if collection_name.empty?
           # This is most probably an anonymous class, we ignore them.
           return

data/lib/mongoid/config/encryption.rb

@@ -21,20 +21,51 @@ module Mongoid
       #
       # @return [ Hash ] The encryption schema map.
       def encryption_schema_map(default_database, models = ::Mongoid.models)
-        visited = Set.new
-        models.each_with_object({}) do |model, map|
-          next if visited.include?(model)
-          visited << model
+        # Subclasses share their parent's collection but are not registered in
+        # Mongoid.models, so they have to be added to the walk explicitly.
+        classes = models.flat_map { |model| [ model ] + model.descendants }.uniq
+
+        classes.each_with_object({}) do |model, map|
           next if model.embedded?
-          next unless model.encrypted?
+          next unless model.requires_encryption_schema?
 
           database = model.storage_options.fetch(:database) { default_database }
+          # A callable database name cannot be resolved here: the documented
+          # multi-tenant idiom has no correct value while the client is being
+          # built. Interpolating the callable would produce a key that never
+          # matches any namespace, so leave the model out of the map. Writes
+          # are refused later, by PersistenceContext, rather than silently
+          # going out unencrypted.
+          next if database.respond_to?(:call)
+
           key = "#{database}.#{model.collection_name}"
-          props = metadata_for(model).merge(properties_for(model, visited))
-          map[key] = props unless props.empty?
+          props = metadata_for(model).merge(properties_for(model, [ model ], key))
+          next if props.empty?
+
+          # The root of a collection schema describes the document, so it is
+          # always an object. Saying so matters when a nested schema carries
+          # encryptMetadata: mongocryptd rejects the schema otherwise.
+          entry = { 'bsonType' => 'object' }.merge(props)
+          map[key] = map.key?(key) ? merge_schema_entries(map[key], entry, key) : entry
         end
       end
 
+      # Collect the paths of the fields encrypted by the schema generated for
+      # a single model.
+      #
+      # @param [ Mongoid::Document ] model The model.
+      #
+      # @return [ Array<Array<String>> ] The property paths, outermost first.
+      #
+      # @api private
+      def encrypted_paths_for(model)
+        return model.instance_variable_get(:@encrypted_paths_for) if
+          model.instance_variable_defined?(:@encrypted_paths_for)
+
+        properties = properties_for(model, [ model ])['properties'] || {}
+        model.instance_variable_set(:@encrypted_paths_for, collect_encrypted_paths(properties, []))
+      end
+
       private
 
       # The algorithm to use for the deterministic encryption.
@@ -100,11 +131,14 @@ module Mongoid
       # are marked as encrypted.
       #
       # @param [ Mongoid::Document ] model The model to generate the properties for.
-      # @param [ Set<Mongoid::Document> ] visited The set of models that have already been visited.
+      # @param [ Array<Mongoid::Document> ] path The models the walk is already
+      #   inside of, outermost first.
+      # @param [ String | nil ] namespace The namespace the schema is built
+      #   for, used for error reporting.
       #
       # @return [ Hash ] The encryption properties.
-      def properties_for(model, visited)
-        result = properties_for_fields(model).merge(properties_for_relations(model, visited))
+      def properties_for(model, path, namespace = nil)
+        result = properties_for_fields(model).merge(properties_for_relations(model, path, namespace))
         if result.empty?
           {}
         else
@@ -141,26 +175,141 @@ module Mongoid
       # are configured to be encrypted.
       #
       # @param [ Mongoid::Document ] model The model to generate the properties for.
-      # @param [ Set<Mongoid::Document> ] visited The set of models that have already been visited.
+      # @param [ Array<Mongoid::Document> ] path The models the walk is already
+      #   inside of, outermost first.
+      # @param [ String | nil ] namespace The namespace the schema is built
+      #   for, used for error reporting.
       #
       # @return [ Hash ] The encryption properties.
-      def properties_for_relations(model, visited)
+      def properties_for_relations(model, path, namespace = nil)
         model.relations.each_with_object({}) do |(name, relation), props|
-          next if visited.include?(relation.relation_class)
+          # relation_class constantizes, and a polymorphic embedded_in has no
+          # class to resolve, so the relation type has to be checked first.
           next unless relation.is_a?(Association::Embedded::EmbedsOne)
-          next unless relation.relation_class.encrypted?
-
-          visited << relation.relation_class
-          metadata_for(
-            relation.relation_class
-          ).merge(
-            properties_for(relation.relation_class, visited)
-          ).tap do |properties|
-            props[name] = { 'bsonType' => 'object' }.merge(properties) unless properties.empty?
+
+          klass = relation.try_relation_class
+          # An association target does not have to be a Mongoid document, and
+          # the class it names does not have to exist.
+          next unless klass.respond_to?(:requires_encryption_schema?)
+
+          # Any subclass of the declared class can be assigned to the
+          # association, so its encrypted fields have to be mapped here too.
+          properties = ([ klass ] + klass.descendants).uniq.inject({}) do |merged, candidate|
+            # Stop at a model the walk is already inside of, or a self-embedding
+            # model never terminates. The path covers the current branch only:
+            # a model embedded by two parents, or twice by one parent, has to be
+            # emitted at every place it appears.
+            next merged if path.include?(candidate)
+            next merged unless candidate.respond_to?(:requires_encryption_schema?)
+            next merged unless candidate.requires_encryption_schema?
+
+            merge_schema_entries(
+              merged,
+              metadata_for(candidate).merge(
+                properties_for(candidate, path + [ candidate ], namespace)
+              ),
+              namespace
+            )
           end
+          props[name] = { 'bsonType' => 'object' }.merge(properties) unless properties.empty?
         end
       end
 
+      # Walk the schema properties and collect the path of every encrypted
+      # leaf.
+      #
+      # @param [ Hash ] properties The properties to walk.
+      # @param [ Array<String> ] path The properties the walk is already
+      #   inside of.
+      #
+      # @return [ Array<Array<String>> ] The property paths.
+      def collect_encrypted_paths(properties, path)
+        properties.each_with_object([]) do |(name, schema), paths|
+          if schema.key?('encrypt')
+            paths << (path + [ name ])
+          elsif schema['properties']
+            paths.concat(collect_encrypted_paths(schema['properties'], path + [ name ]))
+          end
+        end
+      end
+
+      # Merge two schema objects covering the same model or namespace.
+      #
+      # Every model writing to one namespace contributes an entry to the
+      # schema map. Those entries have to agree on everything they have in
+      # common, or the schema would silently encrypt a field differently for
+      # one model than for another.
+      #
+      # @param [ Hash ] left The first schema.
+      # @param [ Hash ] right The second schema.
+      # @param [ String | nil ] namespace The namespace the schema belongs to.
+      #
+      # @return [ Hash ] The merged schema.
+      def merge_schema_entries(left, right, namespace = nil)
+        left.merge(right) do |key, left_value, right_value|
+          case key
+          when 'bsonType'
+            left_value
+          when 'encryptMetadata'
+            merge_encrypt_metadata(left_value, right_value, namespace)
+          when 'properties'
+            merge_properties(left_value, right_value, namespace)
+          else
+            raise_invalid_encryption_schema(namespace, key)
+          end
+        end
+      end
+
+      # Merge two encryptMetadata objects.
+      #
+      # @param [ Hash ] left The first encryptMetadata object.
+      # @param [ Hash ] right The second encryptMetadata object.
+      # @param [ String | nil ] namespace The namespace the schema belongs to.
+      #
+      # @return [ Hash ] The merged encryptMetadata object.
+      def merge_encrypt_metadata(left, right, namespace)
+        left.merge(right) do |key, left_value, right_value|
+          unless left_value == right_value
+            raise_invalid_encryption_schema(namespace, "encryptMetadata.#{key}")
+          end
+
+          left_value
+        end
+      end
+
+      # Merge two properties objects.
+      #
+      # @param [ Hash ] left The first properties object.
+      # @param [ Hash ] right The second properties object.
+      # @param [ String | nil ] namespace The namespace the schema belongs to.
+      #
+      # @return [ Hash ] The merged properties object.
+      def merge_properties(left, right, namespace)
+        left.merge(right) do |name, left_value, right_value|
+          if left_value.key?('encrypt') && right_value.key?('encrypt')
+            unless left_value['encrypt'] == right_value['encrypt']
+              raise_invalid_encryption_schema(namespace, "properties.#{name}")
+            end
+
+            left_value
+          elsif left_value.key?('encrypt') || right_value.key?('encrypt')
+            raise_invalid_encryption_schema(namespace, "properties.#{name}")
+          else
+            merge_schema_entries(left_value, right_value, namespace)
+          end
+        end
+      end
+
+      # Raise an error for a schema conflicting with another one.
+      #
+      # @param [ String | nil ] namespace The namespace the schema belongs to.
+      # @param [ String ] path The conflicting path in the schema.
+      #
+      # @raise [ Errors::InvalidEncryptionSchema ] Always raised.
+      def raise_invalid_encryption_schema(namespace, path)
+        raise Errors::InvalidEncryptionSchema.new(namespace, path)
+      end
+
       # Get the BSON type identifier for the provided field according to the
       # https://www.mongodb.com/docs/manual/reference/bson-types/#std-label-bson-types
       #