mongoid 7.2.1 → 9.0.0

data/lib/mongoid/document.rb

@@ -1,26 +1,24 @@
 # frozen_string_literal: true
-# encoding: utf-8
-
-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
+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
@@ -40,8 +38,6 @@ module Mongoid
     # that should be used instead.
     # When ruby driver 2.3.0 is released and Mongoid can be updated
     # to require >= 2.3.0, the BSON constant can be used.
-    #
-    # @since 6.0.0
     ILLEGAL_KEY = /(\A[$])|(\.)/.freeze
 
     # Freezes the internal attributes of the document.
@@ -50,8 +46,6 @@ module Mongoid
     #   document.freeze
     #
     # @return [ Document ] The document.
-    #
-    # @since 2.0.0
     def freeze
       as_attributes.freeze and self
     end
@@ -61,9 +55,7 @@ module Mongoid
     # @example Check if frozen
     #   document.frozen?
     #
-    # @return [ true, false ] True if frozen, else false.
-    #
-    # @since 2.0.0
+    # @return [ true | false ] True if frozen, else false.
     def frozen?
       attributes.frozen?
     end
@@ -78,8 +70,6 @@ module Mongoid
     #   document.hash
     #
     # @return [ Integer ] The hash of the document's identity.
-    #
-    # @since 1.0.0
     def hash
       identity.hash
     end
@@ -92,10 +82,8 @@ module Mongoid
     #   document.identity
     #
     # @return [ Array ] An array containing [document.class, document._id]
-    #
-    # @since 3.0.0
     def identity
-      [ self.class, self._id ]
+      [ self.class, _id ]
     end
 
     # Instantiate a new +Document+, setting the Document's attributes if
@@ -106,28 +94,13 @@ 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.
     #
     # @return [ Document ] A new document.
-    #
-    # @since 1.0.0
-    def initialize(attrs = nil)
-      @__parent = nil
-      _building do
-        @new_record = true
-        @attributes ||= {}
-        apply_pre_processed_defaults
-        apply_default_scoping
-        process_attributes(attrs) do
-          yield(self) if block_given?
-        end
-        apply_post_processed_defaults
-        # @todo: #2586: Need to have access to parent document in these
-        #   callbacks.
-        run_callbacks(:initialize) unless _initialize_callbacks.empty?
-      end
+    def initialize(attrs = nil, &block)
+      construct_document(attrs, &block)
     end
 
     # Return the model name of the document.
@@ -136,8 +109,6 @@ module Mongoid
     #   document.model_name
     #
     # @return [ String ] The model name.
-    #
-    # @since 3.0.16
     def model_name
       self.class.model_name
     end
@@ -148,22 +119,8 @@ module Mongoid
     #   document.to_key
     #
     # @return [ String ] The id of the document or nil if new.
-    #
-    # @since 2.4.0
     def to_key
-      (persisted? || destroyed?) ? [ id.to_s ] : nil
-    end
-
-    # Return an array with this +Document+ only in it.
-    #
-    # @example Return the document in an array.
-    #   document.to_a
-    #
-    # @return [ Array<Document> ] An array with the document as its only item.
-    #
-    # @since 1.0.0
-    def to_a
-      [ self ]
+      (persisted? || destroyed?) ? [ _id.to_s ] : nil
     end
 
     # Return a hash of the entire document hierarchy from this document and
@@ -174,40 +131,10 @@ module Mongoid
     #   person.as_document
     #
     # @return [ Hash ] A hash of all attributes in the hierarchy.
-    #
-    # @since 1.0.0
     def as_document
       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 Whether to include fields with
-    #   nil values in the json document.
-    #
-    # @return [ Hash ] The document as json.
-    #
-    # @since 5.1.0
-    def as_json(options = nil)
-      rv = super
-      if options && options[:compact]
-        rv = rv.compact
-      end
-      rv
-    end
-
     # Returns an instance of the specified class with the attributes,
     # errors, and embedded documents of the current document.
     #
@@ -219,44 +146,100 @@ module Mongoid
     # @param [ Class ] klass The class to become.
     #
     # @return [ Document ] An instance of the specified class.
-    #
-    # @since 2.0.0
     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.
+    #
+    # @param [ Hash ] attrs The attributes to set up the document with.
+    # @param [ Hash ] options The options to use.
+    #
+    # @option options [ true | false ] :execute_callbacks Flag specifies
+    #   whether callbacks should be run.
+    #
+    # @return [ Document ] A new document.
+    #
+    # @note A Ruby 2.x bug prevents the options hash from being keyword
+    #   arguments. Once we drop support for Ruby 2.x, we can reimplement
+    #   the options hash as keyword arguments.
+    #   See https://bugs.ruby-lang.org/issues/15753
+    #
+    # @api private
+    def construct_document(attrs = nil, options = {})
+      execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
+
+      self._parent = nil
+      _building do
+        prepare_to_process_attributes
+
+        process_attributes(attrs) do
+          yield(self) if block_given?
+        end
+        @attributes_before_type_cast = @attributes.merge(attributes_before_type_cast)
+
+        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.
-    #
-    # @since 2.2.0
     def logger
       Mongoid.logger
     end
@@ -267,94 +250,205 @@ module Mongoid
     #   model.model_key
     #
     # @return [ String ] The model key.
-    #
-    # @since 2.4.0
     def model_key
-      @model_cache_key ||= self.class.model_name.cache_key
+      @model_key ||= self.class.model_name.cache_key
     end
 
-    # Implement this for calls to flatten on array.
+    # Returns a hash of the attributes.
     #
-    # @example Get the document as an array.
-    #   document.to_ary
+    # Note this method modifies the attributes hash that already exists on the
+    # class and returns it. This means that the hash returned by this method
+    # refers to the same hash as calling #attributes on the instance. See
+    # MONGOID-4476 for an explanation on how this is used.
     #
-    # @return [ nil ] Always nil.
+    # @return [ Hash ] The attributes hash.
+    def as_attributes
+      return attributes if frozen?
+
+      embedded_relations.each_pair do |name, meta|
+        without_autobuild do
+          add_attributes_for_relation(name, meta)
+        end
+      end
+
+      attributes
+    end
+
+    # Adds the attributes for the given relation to the document's attributes.
     #
-    # @since 2.1.0
-    def to_ary
-      nil
+    # @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
 
-    private
+    # 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)
 
-    def as_attributes
-      return attributes if frozen?
-      embedded_relations.each_pair do |name, meta|
+      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, 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
+          relation = __send__(name)
+          Array.wrap(relation).each do |r|
+            r.instance_variable_set(:@new_record, new_record)
           end
         end
       end
-      attributes
     end
 
-    module ClassMethods
+    # 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
 
-      # 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.
+    # 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.
       #
-      # @since 2.0.0.rc.4
-      def ===(other)
-        other.class == Class ? self <= other : other.is_a?(self)
+      # @param [ true | false ] execute_callbacks Whether callbacks should be
+      #   suppressed or not.
+      def with_callbacks(execute_callbacks)
+        saved, Threaded.execute_callbacks =
+          Threaded.execute_callbacks?, execute_callbacks
+        yield
+      ensure
+        Threaded.execute_callbacks = saved
       end
 
       # Instantiate a new object, only when loaded from the database or when
       # 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.
       #
       # @return [ Document ] A new document.
+      def instantiate(attrs = nil, selected_fields = nil, &block)
+        instantiate_document(attrs, selected_fields, &block)
+      end
+
+      # Instantiate the document.
+      #
+      # @param [ Hash ] attrs The hash of attributes to instantiate with.
+      # @param [ Integer ] selected_fields The selected fields from the
+      #   criteria.
+      # @param [ Hash ] options The options to use.
+      #
+      # @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.
       #
-      # @since 1.0.0
-      def instantiate(attrs = nil, selected_fields = nil)
-        attributes = attrs || {}
+      # @note A Ruby 2.x bug prevents the options hash from being keyword
+      #   arguments. Once we drop support for Ruby 2.x, we can reimplement
+      #   the options hash as keyword arguments.
+      #
+      # @api private
+      def instantiate_document(attrs = nil, selected_fields = nil, options = {}, &block)
+        execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
+        attributes = attrs&.to_h || {}
+
         doc = allocate
         doc.__selected_fields = selected_fields
         doc.instance_variable_set(:@attributes, attributes)
-        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?
+        doc.instance_variable_set(:@attributes_before_type_cast, attributes.dup)
+
+        doc._handle_callbacks_after_instantiation(execute_callbacks, &block)
+
+        doc.remember_storage_options!
         doc
       end
 
+      # Allocates and constructs a document.
+      #
+      # @param [ Hash ] attrs The attributes to set up the document with.
+      # @param [ Hash ] options The options to use.
+      #
+      # @option options [ true | false ] :execute_callbacks Flag specifies
+      #   whether callbacks should be run.
+      #
+      # @note A Ruby 2.x bug prevents the options hash from being keyword
+      #   arguments. Once we drop support for Ruby 2.x, we can reimplement
+      #   the options hash as keyword arguments.
+      #   See https://bugs.ruby-lang.org/issues/15753
+      #
+      # @return [ Document ] A new document.
+      #
+      # @api private
+      def construct_document(attrs = nil, options = {})
+        execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
+        with_callbacks(execute_callbacks) { new(attrs) }
+      end
+
       # Returns all types to query for when using this class as the base.
       #
       # @example Get the types.
       #   document._types
       #
       # @return [ Array<Class> ] All subclasses of the current document.
-      #
-      # @since 1.0.0
       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
@@ -365,15 +459,13 @@ module Mongoid
       #
       # @api private
       def _mongoid_clear_types
-        @_type = nil
+        @_types = nil
         superclass._mongoid_clear_types if hereditary?
       end
 
       # Set the i18n scope to overwrite ActiveModel.
       #
       # @return [ Symbol ] :mongoid
-      #
-      # @since 2.0.0
       def i18n_scope
         :mongoid
       end
@@ -384,8 +476,6 @@ module Mongoid
       #   Person.logger
       #
       # @return [ Logger ] The configured logger or a default Logger instance.
-      #
-      # @since 2.2.0
       def logger
         Mongoid.logger
       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