mongoid 8.1.5 → 9.0.0

data/lib/mongoid/deprecation.rb

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
 
   # Utility class for logging deprecation warnings.
   class Deprecation < ::ActiveSupport::Deprecation
 
-    @gem_name = 'Mongoid'
+    def initialize
+      # Per change policy, deprecations will be removed in the next major version.
+      deprecation_horizon = "#{Mongoid::VERSION.split('.').first.to_i + 1}.0".freeze
+      gem_name = 'Mongoid'
+      super(deprecation_horizon, gem_name)
+    end
 
-    # Per change policy, deprecations will be removed in the next major version.
-    @deprecation_horizon = "#{Mongoid::VERSION.split('.').first.to_i + 1}.0".freeze
 
     # Overrides default ActiveSupport::Deprecation behavior
     # to use Mongoid's logger.
     #
-    # @return Array<Proc> The deprecation behavior.
+    # @return [ Array<Proc> ] The deprecation behavior.
     def behavior
       @behavior ||= Array(->(*args) {
         logger = Mongoid.logger

data/lib/mongoid/document.rb

@@ -1,25 +1,24 @@
 # frozen_string_literal: true
 
-require "mongoid/positional"
-require "mongoid/evolvable"
-require "mongoid/extensions"
-require "mongoid/errors"
-require "mongoid/threaded"
-require "mongoid/atomic"
-require "mongoid/attributes"
-require "mongoid/contextual"
-require "mongoid/copyable"
-require "mongoid/equality"
-require "mongoid/criteria"
-require "mongoid/factory"
-require "mongoid/fields"
-require "mongoid/timestamps"
-require "mongoid/association"
-require "mongoid/composable"
-require "mongoid/touchable"
+require 'mongoid/positional'
+require 'mongoid/evolvable'
+require 'mongoid/extensions'
+require 'mongoid/errors'
+require 'mongoid/threaded'
+require 'mongoid/atomic'
+require 'mongoid/attributes'
+require 'mongoid/contextual'
+require 'mongoid/copyable'
+require 'mongoid/equality'
+require 'mongoid/criteria'
+require 'mongoid/factory'
+require 'mongoid/fields'
+require 'mongoid/timestamps'
+require 'mongoid/association'
+require 'mongoid/composable'
+require 'mongoid/touchable'
 
 module Mongoid
-
   # This is the base module for all domain objects that need to be persisted to
   # the database as documents.
   module Document
@@ -84,7 +83,7 @@ module Mongoid
     #
     # @return [ Array ] An array containing [document.class, document._id]
     def identity
-      [ self.class, self._id ]
+      [ self.class, _id ]
     end
 
     # Instantiate a new +Document+, setting the Document's attributes if
@@ -95,7 +94,7 @@ module Mongoid
     # otherwise it will be set to a fresh +BSON::ObjectId+ string.
     #
     # @example Create a new document.
-    #   Person.new(:title => "Sir")
+    #   Person.new(:title => 'Sir')
     #
     # @param [ Hash ] attrs The attributes to set up the document with.
     #
@@ -136,33 +135,6 @@ module Mongoid
       BSON::Document.new(as_attributes)
     end
 
-    # Calls #as_json on the document with additional, Mongoid-specific options.
-    #
-    # @note Rails 6 changes return value of as_json for non-primitive types
-    #   such as BSON::ObjectId. In Rails <= 5, as_json returned these as
-    #   instances of the class. In Rails 6, these are returned serialized to
-    #   primitive types (e.g. {"$oid"=>"5bcfc40bde340b37feda98e9"}).
-    #   See https://github.com/rails/rails/commit/2e5cb980a448e7f4ab00df6e9ad4c1cc456616aa
-    #   for more information.
-    #
-    # @example Get the document as json.
-    #   document.as_json(compact: true)
-    #
-    # @param [ Hash ] options The options.
-    #
-    # @option options [ true | false ] :compact (Deprecated) Whether to include fields
-    #   with nil values in the json document.
-    #
-    # @return [ Hash ] The document as json.
-    def as_json(options = nil)
-      rv = super
-      if options && options[:compact]
-        Mongoid::Warnings.warn_as_json_compact_deprecated
-        rv = rv.compact
-      end
-      rv
-    end
-
     # Returns an instance of the specified class with the attributes,
     # errors, and embedded documents of the current document.
     #
@@ -175,34 +147,52 @@ module Mongoid
     #
     # @return [ Document ] An instance of the specified class.
     def becomes(klass)
-      unless klass.include?(Mongoid::Document)
-        raise ArgumentError, "A class which includes Mongoid::Document is expected"
-      end
+      mongoid_document_check!(klass)
 
       became = klass.new(clone_document)
-      became._id = _id
-      became.instance_variable_set(:@changed_attributes, changed_attributes)
-      new_errors = ActiveModel::Errors.new(became)
-      new_errors.copy!(errors)
-      became.instance_variable_set(:@errors, new_errors)
-      became.instance_variable_set(:@new_record, new_record?)
-      became.instance_variable_set(:@destroyed, destroyed?)
-      became.changed_attributes[klass.discriminator_key] = self.class.discriminator_value
-      became[klass.discriminator_key] = klass.discriminator_value
-
-      # mark embedded docs as persisted
-      embedded_relations.each_pair do |name, meta|
-        without_autobuild do
-          relation = became.__send__(name)
-          Array.wrap(relation).each do |r|
-            r.instance_variable_set(:@new_record, new_record?)
-          end
-        end
-      end
+      became.internal_state = internal_state
 
       became
     end
 
+    # Sets the internal state of this document. Used only by #becomes to
+    # help initialize a retyped document.
+    #
+    # @param [ Hash ] state The map of internal state values.
+    #
+    # @api private
+    def internal_state=(state)
+      self._id = state[:id]
+      @changed_attributes = state[:changed_attributes]
+      @errors = ActiveModel::Errors.new(self).tap { |e| e.copy!(state[:errors]) }
+      @new_record = state[:new_record]
+      @destroyed = state[:destroyed]
+
+      update_discriminator(state[:discriminator_key_was])
+
+      mark_persisted_state_for_embedded_documents(state[:new_record])
+    end
+
+    # Handles the setup and execution of callbacks, if callbacks are to
+    # be executed; otherwise, adds the appropriate callbacks to the pending
+    # callbacks list.
+    #
+    # @param execute_callbacks [ true | false ] Whether callbacks should be
+    #   executed or not.
+    #
+    # @api private
+    def _handle_callbacks_after_instantiation(execute_callbacks)
+      if execute_callbacks
+        apply_defaults
+        yield self if block_given?
+        run_callbacks(:find) unless _find_callbacks.empty?
+        run_callbacks(:initialize) unless _initialize_callbacks.empty?
+      else
+        yield self if block_given?
+        self.pending_callbacks += %i[ apply_defaults find initialize ]
+      end
+    end
+
     private
 
     # Does the construction of a document.
@@ -224,28 +214,29 @@ module Mongoid
     def construct_document(attrs = nil, options = {})
       execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
 
-      @__parent = nil
+      self._parent = nil
       _building do
-        @new_record = true
-        @attributes ||= {}
-        apply_pre_processed_defaults
-        apply_default_scoping
+        prepare_to_process_attributes
+
         process_attributes(attrs) do
           yield(self) if block_given?
         end
         @attributes_before_type_cast = @attributes.merge(attributes_before_type_cast)
 
-        if execute_callbacks
-          apply_post_processed_defaults
-          run_callbacks(:initialize) unless _initialize_callbacks.empty?
-        else
-          pending_callbacks << :apply_post_processed_defaults
-          pending_callbacks << :initialize
-        end
+        resolve_post_construction_callbacks(execute_callbacks)
       end
       self
     end
 
+    # Initializes the object state prior to attribute processing; this is
+    # called only from #construct_document.
+    def prepare_to_process_attributes
+      @new_record = true
+      @attributes ||= {}
+      apply_pre_processed_defaults
+      apply_default_scoping
+    end
+
     # Returns the logger
     #
     # @return [ Logger ] The configured logger or a default Logger instance.
@@ -260,7 +251,7 @@ module Mongoid
     #
     # @return [ String ] The model key.
     def model_key
-      @model_cache_key ||= self.class.model_name.cache_key
+      @model_key ||= self.class.model_name.cache_key
     end
 
     # Returns a hash of the attributes.
@@ -273,28 +264,103 @@ module Mongoid
     # @return [ Hash ] The attributes hash.
     def as_attributes
       return attributes if frozen?
+
       embedded_relations.each_pair do |name, meta|
         without_autobuild do
-          relation, stored = send(name), meta.store_as
-          if attributes.key?(stored) || !relation.blank?
-            if !relation.nil?
-              attributes[stored] = relation.send(:as_attributes)
-            else
-              attributes.delete(stored)
-            end
-          end
+          add_attributes_for_relation(name, meta)
         end
       end
+
       attributes
     end
 
-    module ClassMethods
+    # Adds the attributes for the given relation to the document's attributes.
+    #
+    # @param name [ String | Symbol ] the name of the relation to add
+    # @param meta [ Mongoid::Assocation::Relatable ] the relation object
+    def add_attributes_for_relation(name, meta)
+      relation, stored = send(name), meta.store_as
+      return unless attributes.key?(stored) || !relation.blank?
 
+      if relation.nil?
+        attributes.delete(stored)
+      else
+        attributes[stored] = relation.send(:as_attributes)
+      end
+    end
+
+    # Checks that the given argument is an instance of `Mongoid::Document`.
+    #
+    # @param klass [ Class ] The class to test.
+    #
+    # @raise [ ArgumentError ] if the class does not include
+    #   Mongoid::Document.
+    def mongoid_document_check!(klass)
+      return if klass.include?(Mongoid::Document)
+
+      raise ArgumentError, 'A class which includes Mongoid::Document is expected'
+    end
+
+    # Constructs a hash representing the internal state of this object,
+    # suitable for passing to #internal_state=.
+    #
+    # @return [ Hash ] the map of internal state values
+    def internal_state
+      {
+        id: _id,
+        changed_attributes: changed_attributes,
+        errors: errors,
+        new_record: new_record?,
+        destroyed: destroyed?,
+        discriminator_key_was: self.class.discriminator_value
+      }
+    end
+
+    # Updates the value of the discriminator_key for this object, setting its
+    # previous value to `key_was`.
+    #
+    # @param key_was [ String ] the previous value of the discriminator key.
+    def update_discriminator(key_was)
+      changed_attributes[self.class.discriminator_key] = key_was
+      self[self.class.discriminator_key] = self.class.discriminator_value
+    end
+
+    # Marks all embedded documents with the given "new_record" state.
+    #
+    # @param [ true | false ] new_record  whether or not the embedded records
+    #   should be flagged as new records or not.
+    def mark_persisted_state_for_embedded_documents(new_record)
+      embedded_relations.each_pair do |name, _meta|
+        without_autobuild do
+          relation = __send__(name)
+          Array.wrap(relation).each do |r|
+            r.instance_variable_set(:@new_record, new_record)
+          end
+        end
+      end
+    end
+
+    # Either executes or enqueues the post-construction callbacks.
+    #
+    # @param [ true | false ] execute_callbacks whether the callbacks
+    #   should be executed (true) or enqueued (false)
+    def resolve_post_construction_callbacks(execute_callbacks)
+      if execute_callbacks
+        apply_post_processed_defaults
+        run_callbacks(:initialize) unless _initialize_callbacks.empty?
+      else
+        pending_callbacks << :apply_post_processed_defaults
+        pending_callbacks << :initialize
+      end
+    end
+
+    # Class-level methods for Document objects.
+    module ClassMethods
       # Indicate whether callbacks should be invoked by default or not,
       # within the block. Callbacks may always be explicitly invoked by passing
       # `execute_callbacks: true` where available.
       #
-      # @params execute_callbacks [ true | false ] Whether callbacks should be
+      # @param [ true | false ] execute_callbacks Whether callbacks should be
       #   suppressed or not.
       def with_callbacks(execute_callbacks)
         saved, Threaded.execute_callbacks =
@@ -308,13 +374,11 @@ module Mongoid
       # the attributes have already been typecast.
       #
       # @example Create the document.
-      #   Person.instantiate(:title => "Sir", :age => 30)
+      #   Person.instantiate(:title => 'Sir', :age => 30)
       #
       # @param [ Hash ] attrs The hash of attributes to instantiate with.
       # @param [ Integer ] selected_fields The selected fields from the
       #   criteria.
-      # @param [ true | false ] execute_callbacks Flag specifies whether callbacks
-      #   should be run.
       #
       # @return [ Document ] A new document.
       def instantiate(attrs = nil, selected_fields = nil, &block)
@@ -331,6 +395,9 @@ module Mongoid
       # @option options [ true | false ] :execute_callbacks Flag specifies
       #   whether callbacks should be run.
       #
+      # @yield [ Mongoid::Document ] If a block is given, yields the newly
+      #   instantiated document to it.
+      #
       # @return [ Document ] A new document.
       #
       # @note A Ruby 2.x bug prevents the options hash from being keyword
@@ -338,32 +405,18 @@ module Mongoid
       #   the options hash as keyword arguments.
       #
       # @api private
-      def instantiate_document(attrs = nil, selected_fields = nil, options = {})
+      def instantiate_document(attrs = nil, selected_fields = nil, options = {}, &block)
         execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
-        attributes = if Mongoid.legacy_attributes
-          attrs
-        else
-          attrs&.to_h
-        end || {}
+        attributes = attrs&.to_h || {}
 
         doc = allocate
         doc.__selected_fields = selected_fields
         doc.instance_variable_set(:@attributes, attributes)
-        # TODO: remove the to_h when the legacy_attributes flag is removed.
-        # The to_h ensures that we don't accidentally make attributes_before_type_cast
-        # a BSON::Document.
-        doc.instance_variable_set(:@attributes_before_type_cast, attributes&.to_h.dup)
-
-        if execute_callbacks
-          doc.apply_defaults
-          yield(doc) if block_given?
-          doc.run_callbacks(:find) unless doc._find_callbacks.empty?
-          doc.run_callbacks(:initialize) unless doc._initialize_callbacks.empty?
-        else
-          yield(doc) if block_given?
-          doc.pending_callbacks += [:apply_defaults, :find, :initialize]
-        end
+        doc.instance_variable_set(:@attributes_before_type_cast, attributes.dup)
+
+        doc._handle_callbacks_after_instantiation(execute_callbacks, &block)
 
+        doc.remember_storage_options!
         doc
       end
 
@@ -395,7 +448,7 @@ module Mongoid
       #
       # @return [ Array<Class> ] All subclasses of the current document.
       def _types
-        @_type ||= (descendants + [ self ]).uniq.map(&:discriminator_value)
+        @_types ||= (descendants + [ self ]).uniq.map(&:discriminator_value)
       end
 
       # Clear the @_type cache. This is generally called when changing the discriminator
@@ -406,7 +459,7 @@ module Mongoid
       #
       # @api private
       def _mongoid_clear_types
-        @_type = nil
+        @_types = nil
         superclass._mongoid_clear_types if hereditary?
       end
 

data/lib/mongoid/encryptable.rb

@@ -0,0 +1,53 @@
+# rubocop:todo all
+module Mongoid
+  # This module is used to extend Mongoid::Document
+  # to add encryption functionality.
+  module Encryptable
+    extend ActiveSupport::Concern
+
+    included do
+      # @return [Hash] The encryption metadata for the model.
+      class_attribute :encrypt_metadata
+      self.encrypt_metadata = {}
+    end
+
+    module ClassMethods
+      # Set the encryption metadata for the model. Parameters set here will be
+      # used to encrypt the fields of the model, unless overridden on the
+      # field itself.
+      #
+      # @param [ Hash ] options The encryption metadata.
+      # @option options [ String ] :key_id The base64-encoded UUID of the key
+      #   used to encrypt fields. Mutually exclusive with :key_name_field option.
+      # @option options [ String ] :key_name_field The name of the field that
+      #   contains the key alt name to use for encryption. Mutually exclusive
+      #   with :key_id option.
+      # @option options [ true | false ] :deterministic Whether the encryption
+      # is deterministic or not.
+      def encrypt_with(options = {})
+        self.encrypt_metadata = options
+      end
+
+      # Whether the model is encrypted. It means that either the encrypt_with
+      # method was called on the model, or at least one of the fields
+      # is encrypted.
+      #
+      # @return [ true | false ] Whether the model is encrypted.
+      def encrypted?
+        !encrypt_metadata.empty? || fields.any? { |_, field| field.is_a?(Mongoid::Fields::Encrypted) }
+      end
+
+      # Override the key_id for the model.
+      #
+      # This method is solely for testing purposes and should not be used in
+      # the application code. The schema_map is generated very early in the
+      # application lifecycle, and overriding the key_id after that will not
+      # have any effect.
+      #
+      # @api private
+      def set_key_id(key_id)
+        self.encrypt_metadata[:key_id] = key_id
+      end
+    end
+  end
+end

data/lib/mongoid/equality.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
 
@@ -34,22 +35,6 @@ module Mongoid
           attributes["_id"] == other.attributes["_id"]
     end
 
-    # Performs class equality checking.
-    #
-    # @example Compare the classes.
-    #   document === other
-    #
-    # @param [ Document | Object ] other The other object to compare with.
-    #
-    # @return [ true | false ] True if the classes are equal, false if not.
-    def ===(other)
-      if Mongoid.legacy_triple_equals
-        other.class == Class ? self.class === other : self == other
-      else
-        super
-      end
-    end
-
     # Delegates to ==. Used when needing checks in hashes.
     #
     # @example Perform equality checking.
@@ -72,11 +57,7 @@ module Mongoid
       #
       # @return [ true | false ] True if the classes are equal, false if not.
       def ===(other)
-        if Mongoid.legacy_triple_equals
-          other.class == Class ? self <= other : other.is_a?(self)
-        else
-          other.is_a?(self)
-        end
+        other.is_a?(self)
       end
     end
   end

data/lib/mongoid/errors/ambiguous_relationship.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Errors

data/lib/mongoid/errors/attribute_not_loaded.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module Mongoid
+  module Errors
+
+    # Raised when attempting to read or write an attribute which has
+    # not been loaded. This can occur when using `.only` or `.without`
+    # query projection methods.
+    #
+    # @example Getting a field which has not been loaded.
+    #   Band.only(:name).first.label
+    #   #=> raises Mongoid::Errors::AttributeNotLoaded
+    #
+    # @example Setting a field which has not been loaded.
+    #   Band.without(:label).first.label = 'Sub Pop Records'
+    #   #=> raises Mongoid::Errors::AttributeNotLoaded
+    class AttributeNotLoaded < MongoidError
+
+      # Create the new error.
+      #
+      # @example Instantiate the error.
+      #   AttributeNotLoaded.new(Person, "title")
+      #
+      # @param [ Class ] klass The model class.
+      # @param [ String | Symbol ] name The name of the attribute.
+      def initialize(klass, name)
+        super(
+          compose_message("attribute_not_loaded", { klass: klass.name, name: name })
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/callback.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Errors

data/lib/mongoid/errors/create_collection_failure.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Errors

data/lib/mongoid/errors/criteria_argument_required.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Errors

data/lib/mongoid/errors/delete_restriction.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Errors

data/lib/mongoid/errors/document_not_destroyed.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Errors

data/lib/mongoid/errors/document_not_found.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Errors

data/lib/mongoid/errors/drop_collection_failure.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Errors

data/lib/mongoid/errors/empty_config_file.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Errors

data/lib/mongoid/errors/immutable_attribute.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Errors

data/lib/mongoid/errors/in_memory_collation_not_supported.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Errors

data/lib/mongoid/errors/invalid_async_query_executor.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Errors