mongoid 9.0.1 → 9.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f756ccb6822c09519cb0e833a2d3bd2edf5b5a0abf3f3c29205a756682e5d954
-  data.tar.gz: 7d44016955b7e2e90d2dc07b2142cc6c79bacfb83831705f26fdafc773e17e7c
+  metadata.gz: 421d53636b0e90abcfa52bf637229588d434ff73f14574b1d316b72009f7236b
+  data.tar.gz: fafa07a7cc9b17de0abbb140ca3d021e3041bfe00b67a424c81f6c15018e607d
 SHA512:
-  metadata.gz: e69bc7c2b6031330346265b5c6cdc8d11909fd1204e32727845e3220c6f105dde407006635f31491df9857597711f610a688818dfaa3bc32f27525e2574ce29d
-  data.tar.gz: 259996128cd10553af4972c6b40f5a8ac537158eeaa1cd012bbc9e6d90d67ad745def51fbd47bafaffe9330324967695e45787732446b305d5bdd13338b94075
+  metadata.gz: d4f2011d1f85178a8693d653518f06e7ad55c1363958e3577f80d040e3986b595bdcaade0e71696ff762e008c195ee23b4579458708bb9e916f7ddfa8e3b9352
+  data.tar.gz: 8b981e1bc4e904085ecedfe459d31c91d06ed353ba0ceef3d67865ea195f31a36539284246b54537fc5af8b54eafcf1a60415eb88c4850d7cdf3af378d449206

data/lib/config/locales/en.yml

@@ -680,6 +680,22 @@ en:
           resolution: "The _type field is a reserved one used by Mongoid to determine the
             class for instantiating an object. Please don't save data in this field or ensure
             that any values in this field correspond to valid models."
+        unrecognized_model_alias:
+          message: "Cannot find any model with type %{model_alias}"
+          summary: "A document is trying to load a polymorphic association, but the data refers to a type of object that can't be resolved (%{model_alias}). It might be that you've renamed the target class."
+          resolution: "Register the old name as an alias on the refactored target object, using `identify_as`. This will allow Mongoid to find the target type even if the name no longer matches what was stored in the database."
+        unrecognized_resolver:
+          message: "The model resolver %{resolver} was referenced, but never registered."
+          summary: "A polymorphic association has been configured to use a resolver
+            named %{resolver}, but that resolver has not yet been registered. This
+            might be a typo. Currently registered resolvers are: %{resolvers}."
+          resolution: "Register custom resolvers with
+            `Mongoid::ModelResolver.register_resolver` before attempting to query
+            a polymorphic association."
+        unregistered_class:
+          message: "The class %{klass} is not registered with the resolver %{resolver}."
+          summary: "A polymorphic association using the resolver %{resolver} has tried to link to a model of type %{klass}, but the resolver has no knowledge of any such model. This can happen if the association is configured to use a different resolver than the target mode."
+          resolution: "Make sure the target model is registered with the same resolver as the polymorphic association, using `identify_as`."
         unsaved_document:
           message: "Attempted to save %{document} before the parent %{base}."
           summary: "You cannot call create or create! through the

data/lib/mongoid/association/accessors.rb

@@ -42,7 +42,8 @@ module Mongoid
       #
       # @return [ Proxy ] The association.
       def create_relation(object, association, selected_fields = nil)
-        type = @attributes[association.inverse_type]
+        key = @attributes[association.inverse_type]
+        type = key ? association.resolver.model_for(key) : nil
         target = if t = association.build(self, object, type, selected_fields)
           association.create_relation(self, t)
         else
@@ -116,7 +117,11 @@ module Mongoid
         # during binding or when cascading callbacks. Whenever we retrieve
         # associations within the codebase, we use without_autobuild.
         if !without_autobuild? && association.embedded? && attribute_missing?(field_name)
-          raise Mongoid::Errors::AttributeNotLoaded.new(self.class, field_name)
+          # We always allow accessing the parent document of an embedded one.
+          try_get_parent = association.is_a?(
+                             Mongoid::Association::Embedded::EmbeddedIn
+                           ) && field_name == association.key
+          raise Mongoid::Errors::AttributeNotLoaded.new(self.class, field_name) unless try_get_parent
         end
 
         if !reload && (value = ivar(name)) != false

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

@@ -53,12 +53,25 @@ module Mongoid
           @attributes = attributes.with_indifferent_access
           @association = association
           @options = options
-          @class_name = options[:class_name] ? options[:class_name].constantize : association.klass
+          @class_name = class_from(options[:class_name])
           @destroy = @attributes.delete(:_destroy)
         end
 
         private
 
+        # Coerces the argument into a class, or defaults to the association's class.
+        #
+        # @param [ String | Mongoid::Document | nil ] name_or_class the value to coerce
+        #
+        # @return [ Mongoid::Document ] the resulting class
+        def class_from(name_or_class)
+          case name_or_class
+          when nil, false then association.klass
+          when String then name_or_class.constantize
+          else name_or_class
+          end
+        end
+
         # Extracts and converts the id to the expected type.
         #
         # @return [ BSON::ObjectId | String | Object | nil ] The converted id,

data/lib/mongoid/association/referenced/belongs_to/binding.rb

@@ -23,7 +23,13 @@ module Mongoid
             binding do
               check_polymorphic_inverses!(_target)
               bind_foreign_key(_base, record_id(_target))
-              bind_polymorphic_inverse_type(_base, _target.class.name)
+
+              # set the inverse type (e.g. "#{name}_type") for new polymorphic associations
+              if _association.inverse_type && !_base.frozen?
+                key = _association.resolver.default_key_for(_target)
+                bind_polymorphic_inverse_type(_base, key)
+              end
+
               if inverse = _association.inverse(_target)
                 if set_base_association
                   if _base.referenced_many?

data/lib/mongoid/association/referenced/belongs_to/buildable.rb

@@ -33,7 +33,7 @@ module Mongoid
           end
 
           def query_criteria(object, type)
-            cls = type ? type.constantize : relation_class
+            cls = type ? (type.is_a?(String) ? type.constantize : type) : relation_class
             crit = cls.criteria
             crit = crit.apply_scope(scope)
             crit.where(primary_key => object)

data/lib/mongoid/association/referenced/belongs_to.rb

@@ -103,6 +103,21 @@ module Mongoid
           @polymorphic ||= !!@options[:polymorphic]
         end
 
+        # Returns the object responsible for converting polymorphic type references into
+        # class objects, and vice versa. This is obtained via the `:polymorphic` option
+        # that was given when the association was defined.
+        #
+        # See Mongoid::ModelResolver.resolver for how the `:polymorphic` option is 
+        # interpreted here.
+        #
+        # @raise KeyError if no such resolver has been registered under the given
+        #   identifier.
+        #
+        # @return [ nil | Mongoid::ModelResolver ] the resolver to use
+        def resolver
+          @resolver ||= Mongoid::ModelResolver.resolver(@options[:polymorphic])
+        end
+
         # The name of the field used to store the type of polymorphic association.
         #
         # @return [ String ] The field used to store the type of polymorphic association.

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

@@ -6,6 +6,7 @@ require 'mongoid/association/referenced/has_many/buildable'
 require 'mongoid/association/referenced/has_many/proxy'
 require 'mongoid/association/referenced/has_many/enumerable'
 require 'mongoid/association/referenced/has_many/eager'
+require 'mongoid/association/referenced/with_polymorphic_criteria'
 
 module Mongoid
   module Association
@@ -15,6 +16,7 @@ module Mongoid
       class HasMany
         include Relatable
         include Buildable
+        include WithPolymorphicCriteria
 
         # The options available for this type of association, in addition to the
         # common ones.
@@ -131,6 +133,12 @@ module Mongoid
         # @param [ Class ] object_class The object class.
         #
         # @return [ Mongoid::Criteria ] The criteria object.
+        #
+        # @deprecated in 9.0.x
+        #
+        # It appears as if this method is an artifact left over from a refactoring that renamed it
+        # `with_polymorphic_criterion`, and made it private. Regardless, this method isn't referenced
+        # anywhere else, and is unlikely to be useful to external clients. We should remove it.
         def add_polymorphic_criterion(criteria, object_class)
           if polymorphic?
             criteria.where(type => object_class.name)
@@ -138,6 +146,7 @@ module Mongoid
             criteria
           end
         end
+        Mongoid.deprecate(self, :add_polymorphic_criterion)
 
         # Is this association polymorphic?
         #
@@ -222,14 +231,6 @@ module Mongoid
           with_ordering(crit)
         end
 
-        def with_polymorphic_criterion(criteria, base)
-          if polymorphic?
-            criteria.where(type => base.class.name)
-          else
-            criteria
-          end
-        end
-
         def with_ordering(criteria)
           if order
             criteria.order_by(order)

data/lib/mongoid/association/referenced/has_one/buildable.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 # rubocop:todo all
 
+require 'mongoid/association/referenced/with_polymorphic_criteria'
+
 module Mongoid
   module Association
     module Referenced
@@ -8,6 +10,7 @@ module Mongoid
 
         # The Builder behavior for has_one associations.
         module Buildable
+          include WithPolymorphicCriteria
 
           # This method either takes an _id or an object and queries for the
           # inverse side using the id or sets the object after clearing the
@@ -57,14 +60,6 @@ module Mongoid
             query_criteria(object, base).take
           end
 
-          def with_polymorphic_criterion(criteria, base)
-            if polymorphic?
-              criteria.where(type => base.class.name)
-            else
-              criteria
-            end
-          end
-
           def query?(object)
             object && !object.is_a?(Mongoid::Document)
           end

data/lib/mongoid/association/referenced/with_polymorphic_criteria.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Association
+    module Referenced
+      # Implements the `with_polymorphic_criteria` shared behavior.
+      #
+      # @api private
+      module WithPolymorphicCriteria
+        # If the receiver represents a polymorphic association, applies
+        # the polymorphic search criteria to the given `criteria` object.
+        #
+        # @param [ Mongoid::Criteria ] criteria the criteria to append to
+        #   if receiver is polymorphic.
+        # @param [ Mongoid::Document ] base the document to use when resolving
+        #   the polymorphic type keys.
+        #
+        # @return [ Mongoid::Criteria] the resulting criteria, which may be
+        #   the same as the input.
+        def with_polymorphic_criterion(criteria, base)
+          if polymorphic?
+            # 1. get the resolver for the inverse association
+            resolver = klass.reflect_on_association(as).resolver
+
+            # 2. look up the list of keys from the resolver, given base
+            keys = resolver.keys_for(base)
+
+            # 3. use equality if there is just one key, `in` if there are multiple
+            if keys.many?
+              criteria.where(type => { :$in => keys })
+            else
+              criteria.where(type => keys.first)
+            end
+          else
+            criteria
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/attributes/nested.rb

@@ -60,7 +60,8 @@ module Mongoid
             re_define_method(meth) do |attrs|
               _assigning do
                 if association.polymorphic? and association.inverse_type
-                  options = options.merge!(:class_name => self.send(association.inverse_type))
+                  klass = association.resolver.model_for(send(association.inverse_type))
+                  options = options.merge!(:class_name => klass)
                 end
                 association.nested_builder(attrs, options).build(self)
               end

data/lib/mongoid/clients/options.rb

@@ -86,7 +86,7 @@ module Mongoid
         else
           PersistenceContext.get(self) ||
             PersistenceContext.get(self.class) ||
-            PersistenceContext.new(self.class, storage_options)
+            PersistenceContext.new(self.class, default_storage_options)
         end
       end
 
@@ -112,6 +112,19 @@ module Mongoid
 
       private
 
+      def default_storage_options
+        # Nothing is overridden, we use either the default storage_options
+        # or storage_options defined for the document class.
+        return storage_options if Threaded.client_override.nil? && Threaded.database_override.nil?
+
+        storage_options.tap do |opts|
+          # Globally overridden client replaces client defined for the document class.
+          opts[:client] = Threaded.client_override unless Threaded.client_override.nil?
+          # Globally overridden database replaces database defined for the document class.
+          opts[:database] = Threaded.database_override unless Threaded.database_override.nil?
+        end
+      end
+
       def set_persistence_context(options_or_context)
         PersistenceContext.set(self, options_or_context)
       end

data/lib/mongoid/clients/sessions.rb

@@ -62,6 +62,7 @@ module Mongoid
         rescue *transactions_not_supported_exceptions
           raise Mongoid::Errors::TransactionsNotSupported
         ensure
+          Threaded.clear_modified_documents(session)
           Threaded.clear_session(client: persistence_context.client)
         end
 
@@ -89,21 +90,22 @@ module Mongoid
         def transaction(options = {}, session_options: {})
           with_session(session_options) do |session|
             begin
-              session.start_transaction(options)
-              yield
-              commit_transaction(session)
+              session.with_transaction(options) do
+                yield
+              end
+              run_commit_callbacks(session)
             rescue *transactions_not_supported_exceptions
               raise Mongoid::Errors::TransactionsNotSupported
             rescue Mongoid::Errors::Rollback
-              abort_transaction(session)
+              run_abort_callbacks(session)
             rescue Mongoid::Errors::InvalidSessionNesting
               # Session should be ended here.
               raise Mongoid::Errors::InvalidTransactionNesting.new
             rescue Mongo::Error::InvalidSession, Mongo::Error::InvalidTransactionOperation => e
-              abort_transaction(session)
-              raise Mongoid::Errors::TransactionError(e)
+              run_abort_callbacks(session)
+              raise Mongoid::Errors::TransactionError.new(e)
             rescue StandardError => e
-              abort_transaction(session)
+              run_abort_callbacks(session)
               raise e
             end
           end
@@ -189,25 +191,21 @@ module Mongoid
           _session&.in_transaction? || false
         end
 
-        # Commits the active transaction on the session, and calls
-        # after_commit callbacks on modified documents.
+        # Runs after_commit callbacks on modified documents.
         #
         # @param [ Mongo::Session ] session Session on which
         #   a transaction is started.
-        def commit_transaction(session)
-          session.commit_transaction
+        def run_commit_callbacks(session)
           Threaded.clear_modified_documents(session).each do |doc|
             doc.run_after_callbacks(:commit)
           end
         end
 
-        # Aborts the active transaction on the session, and calls
-        # after_rollback callbacks on modified documents.
+        # Runs after_rollback callbacks on modified documents.
         #
         # @param [ Mongo::Session ] session Session on which
         #   a transaction is started.
-        def abort_transaction(session)
-          session.abort_transaction
+        def run_abort_callbacks(session)
           Threaded.clear_modified_documents(session).each do |doc|
             doc.run_after_callbacks(:rollback)
           end

data/lib/mongoid/composable.rb

@@ -5,6 +5,7 @@ require "mongoid/changeable"
 require "mongoid/collection_configurable"
 require "mongoid/encryptable"
 require "mongoid/findable"
+require 'mongoid/identifiable'
 require "mongoid/indexable"
 require "mongoid/inspectable"
 require "mongoid/interceptable"
@@ -44,6 +45,7 @@ module Mongoid
     include Attributes
     include Evolvable
     include Fields
+    include Identifiable
     include Indexable
     include Inspectable
     include Matchable

data/lib/mongoid/document.rb

@@ -17,6 +17,7 @@ require 'mongoid/timestamps'
 require 'mongoid/association'
 require 'mongoid/composable'
 require 'mongoid/touchable'
+require 'mongoid/model_resolver'
 
 module Mongoid
   # This is the base module for all domain objects that need to be persisted to
@@ -31,6 +32,7 @@ module Mongoid
 
     included do
       Mongoid.register_model(self)
+      Mongoid::ModelResolver.register(self)
     end
 
     # Regex for matching illegal BSON keys.

data/lib/mongoid/errors/unrecognized_model_alias.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+    # Raised when a polymorphic association is queried, but the type of the
+    # association cannot be resolved. This usually happens when the data in
+    # the database references a type that no longer exists.
+    #
+    # For example, consider the following model:
+    #
+    #   class Manager
+    #     include Mongoid::Document
+    #     belongs_to :unit, polymorphic: true
+    #   end
+    #
+    # Imagine there is a document in the `managers` collection that looks
+    # something like this:
+    #
+    #   { _id: ..., unit_id: ..., unit_type: 'Department::Engineering' }
+    #
+    # If, at some point in your refactoring, you rename the `Department::Engineering`
+    # model to something else, Mongoid will no longer be able to resolve the
+    # type of this association, and asking for `manager.unit` will raise this
+    # exception.
+    #
+    # To fix this exception, you can add an alias to the model class so that it
+    # can still be found, even after renaming it:
+    #
+    #   module Engineering
+    #     class Department
+    #       include Mongoid::Document
+    #
+    #       identify_as 'Department::Engineering'
+    #
+    #       # ...
+    #     end
+    #   end
+    #
+    # Better practice would be to use unique strings instead of class names to
+    # identify these polymorphic types in the database (e.g. 'dept' instead of
+    # 'Department::Engineering').
+    class UnrecognizedModelAlias < MongoidError
+      def initialize(model_alias)
+        super(
+          compose_message(
+            'unrecognized_model_alias',
+            model_alias: model_alias.inspect
+          )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/unrecognized_resolver.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+    # Raised when a model resolver is referenced, but not registered.
+    #
+    #   class Manager
+    #     include Mongoid::Document
+    #     belongs_to :unit, polymorphic: :org
+    #   end
+    #
+    # If `:org` has not previously been registered as a model resolver,
+    # Mongoid will raise UnrecognizedResolver when it tries to resolve
+    # a manager's unit.
+    class UnrecognizedResolver < MongoidError
+      def initialize(resolver)
+        super(
+          compose_message(
+            'unrecognized_resolver',
+            resolver: resolver.inspect,
+            resolvers: [ :default, *Mongoid::ModelResolver.resolvers.keys ].inspect
+          )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/unregistered_class.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+    # Raised when Mongoid tries to query the identifier to use for a given
+    # class in a polymorphic association, but the class has not previously
+    # been registered by resolver that was used for the query.
+    #
+    # Here's an exammple:
+    #
+    #   class Department
+    #     include Mongoid::Document
+    #     has_many :managers, as: :unit
+    #   end
+    #
+    #   class Manager
+    #     include Mongoid::Document
+    #     belongs_to :unit, polymorphic: :org
+    #   end
+    #
+    # The Manager class is configured to use a custom resolver named `:org`
+    # when resolving the polymorphic `unit` association. However, the `Department`
+    # class is not registered with that resolver. When the program tries to
+    # associate a manager record with a department, it will not be able to find
+    # the required key in the `:org` resolver, and will fail with this exception.
+    #
+    # The solution is to make sure the `Department` class is properly registered
+    # with the `:org` resolver:
+    #
+    #   class Department
+    #     include Mongoid::Document
+    #     identify_as resolver: :org
+    #     has_many :managers, as: :unit
+    #   end
+    class UnregisteredClass < MongoidError
+      def initialize(klass, resolver)
+        super(
+          compose_message(
+            'unregistered_class',
+            klass: klass,
+            resolver: resolver.inspect
+          )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors.rb

@@ -69,6 +69,9 @@ require "mongoid/errors/transaction_error"
 require "mongoid/errors/transactions_not_supported"
 require "mongoid/errors/unknown_attribute"
 require "mongoid/errors/unknown_model"
+require 'mongoid/errors/unrecognized_model_alias'
+require 'mongoid/errors/unrecognized_resolver'
+require 'mongoid/errors/unregistered_class'
 require "mongoid/errors/unsaved_document"
 require "mongoid/errors/unsupported_javascript"
 require "mongoid/errors/validations"

data/lib/mongoid/identifiable.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'mongoid/model_resolver'
+
+module Mongoid
+  # Implements the "identify_as" interface (for specifying type aliases
+  # for document classes).
+  module Identifiable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Specifies aliases that may be used to identify this document
+      # class in polymorphic situations. By default, classes are identified
+      # by their class names, but alternative aliases may be used instead,
+      # if desired.
+      #
+      # @param [ Array<String | Symbol> ] aliases the list of aliases to
+      #   assign to this class.
+      # @param [ Mongoid::ModelResolver::Interface | Symbol | :default ] resolver the
+      #   resolver instance to use when registering the type. If :default, the default
+      #   `ModelResolver` instance will be used. If any other symbol, it must identify a
+      #   previously registered ModelResolver instance.
+      def identify_as(*aliases, resolver: :default)
+        Mongoid::ModelResolver.resolver(resolver).register(self, *aliases)
+      end
+    end
+  end
+end

data/lib/mongoid/matcher.rb

@@ -39,11 +39,25 @@ module Mongoid
     # from and behaves identically to association traversal for the purposes
     # of, for example, subsequent array element retrieval.
     #
-    # @param [ Document | Hash ] document The document to extract from.
+    # @param [ Document | Hash | String ] document The document to extract from.
     # @param [ String ] key The key path to extract.
     #
     # @return [ Object | Array ] Field value or values.
     module_function def extract_attribute(document, key)
+      # The matcher system will wind up sending atomic values to this as well,
+      # when attepting to match more complex types. If anything other than a
+      # Document or a Hash is given, we'll short-circuit the logic and just
+      # return an empty array.
+      return [] unless document.is_a?(Hash) || document.is_a?(Document)
+
+      # Performance optimization; if the key does not include a '.' character,
+      # it must reference an immediate attribute of the document.
+      unless key.include?('.')
+        hash = document.respond_to?(:attributes) ? document.attributes : document
+        key = find_exact_key(hash, key)
+        return key ? [ hash[key] ] : []
+      end
+
       if document.respond_to?(:as_attributes, true)
         # If a document has hash fields, as_attributes would keep those fields
         # as Hash instances which do not offer indifferent access.