mongoid 8.0.3 → 8.1.0

data/lib/mongoid/deprecable.rb

@@ -24,7 +24,7 @@ module Mongoid
     #   #=> Mongoid.logger.warn("meow is deprecated and will be removed from Mongoid 8.0 (eat :catnip instead)")
     #
     # @param [ Module ] target_module The parent which contains the method.
-    # @param [ Symbol | Hash<Symbol, [ Symbol | String ]> ] method_descriptors
+    # @param [ [ Symbol | Hash<Symbol, [ Symbol | String ]> ]... ] *method_descriptors
     #   The methods to deprecate, with optional replacement instructions.
     def deprecate(target_module, *method_descriptors)
       Mongoid::Deprecation.deprecate_methods(target_module, *method_descriptors)

data/lib/mongoid/document.rb

@@ -101,7 +101,7 @@ module Mongoid
     #
     # @return [ Document ] A new document.
     def initialize(attrs = nil, &block)
-      construct_document(attrs, execute_callbacks: true, &block)
+      construct_document(attrs, &block)
     end
 
     # Return the model name of the document.
@@ -208,13 +208,22 @@ module Mongoid
     # Does the construction of a document.
     #
     # @param [ Hash ] attrs The attributes to set up the document with.
-    # @param [ true | false ] execute_callbacks Flag specifies whether callbacks
-    #   should be run.
+    # @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, execute_callbacks: true)
+    def construct_document(attrs = nil, options = {})
+      execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
+
       @__parent = nil
       _building do
         @new_record = true
@@ -281,6 +290,20 @@ module Mongoid
 
     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
+      #   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.
       #
@@ -295,7 +318,7 @@ module Mongoid
       #
       # @return [ Document ] A new document.
       def instantiate(attrs = nil, selected_fields = nil, &block)
-        instantiate_document(attrs, selected_fields, execute_callbacks: true, &block)
+        instantiate_document(attrs, selected_fields, &block)
       end
 
       # Instantiate the document.
@@ -303,13 +326,20 @@ module Mongoid
       # @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.
+      # @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.
+      #
       # @api private
-      def instantiate_document(attrs = nil, selected_fields = nil, execute_callbacks: true)
+      def instantiate_document(attrs = nil, selected_fields = nil, options = {})
+        execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
         attributes = if Mongoid.legacy_attributes
           attrs
         else
@@ -340,15 +370,22 @@ module Mongoid
       # Allocates and constructs a document.
       #
       # @param [ Hash ] attrs The attributes to set up the document with.
-      # @param [ true | false ] execute_callbacks Flag specifies whether callbacks
-      #   should be run.
+      # @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, execute_callbacks: true)
-        doc = allocate
-        doc.send(:construct_document, attrs, execute_callbacks: execute_callbacks)
+      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.

data/lib/mongoid/errors/create_collection_failure.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # Raised when an attempt to create a collection failed.
+    class CreateCollectionFailure < MongoidError
+
+      # Instantiate the create collection error.
+      #
+      # @param [ String ] collection_name The name of the collection that
+      #   Mongoid failed to create.
+      # @param [ Hash ] collection_options The options that were used when
+      #   tried to create the collection.
+      # @param [ Mongo::Error::OperationFailure ] error The error raised when
+      #   tried to create the collection.
+      #
+      # @api private
+      def initialize(collection_name, collection_options, error)
+        super(
+            compose_message(
+                "create_collection_failure",
+                {
+                  collection_name: collection_name,
+                  collection_options: collection_options,
+                  error: "#{error.class}: #{error.message}"
+                }
+            )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/drop_collection_failure.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # Raised when an attempt to drop a collection failed.
+    class DropCollectionFailure < MongoidError
+
+      # Instantiate the drop collection error.
+      #
+      # @param [ String ] collection_name The name of the collection that
+      #   Mongoid failed to drop.
+      #
+      # @api private
+      def initialize(collection_name, collection_options, error)
+        super(
+            compose_message(
+                "drop_collection_failure",
+                {
+                  collection_name: collection_name
+                }
+            )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/immutable_attribute.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when attempting the change the value of an
+    # immutable attribute. For example, the _id attribute is immutable,
+    # and attempting to change it on a document that has already been
+    # persisted will result in this error.
+    class ImmutableAttribute < MongoidError
+
+      # Create the new error.
+      #
+      # @example Create the new error.
+      #   ImmutableAttribute.new(:_id, "1234")
+      #
+      # @param [ Symbol | String ] name The name of the attribute.
+      # @param [ Object ] value The attempted set value.
+      def initialize(name, value)
+        super(
+          compose_message("immutable_attribute", { name: name, value: value })
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/invalid_async_query_executor.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when a bad async query executor option is attempted
+    # to be set.
+    class InvalidQueryExecutor < MongoidError
+
+      # Create the new error.
+      #
+      # @param [ Symbol | String ] executor The attempted async query executor.
+      #
+      # @api private
+      def initialize(executor)
+        super(
+          compose_message(
+            "invalid_async_query_executor",
+            { executor: executor, options: [:immediate, :global_thread_pool] }
+          )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/invalid_global_executor_concurrency.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when a bad global executor concurrency option is attempted
+    # to be set.
+    class InvalidGlobalExecutorConcurrency < MongoidError
+
+      # Create the new error.
+      #
+      # @api private
+      def initialize
+        super(
+          compose_message(
+            "invalid_global_executor_concurrency"
+          )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/invalid_storage_parent.rb

@@ -4,6 +4,8 @@ module Mongoid
   module Errors
 
     # Raised when calling store_in in a sub-class of Mongoid::Document
+    #
+    # @deprecated
     class InvalidStorageParent < MongoidError
 
       # Create the new error.

data/lib/mongoid/errors.rb

@@ -3,11 +3,14 @@
 require "mongoid/errors/mongoid_error"
 require "mongoid/errors/ambiguous_relationship"
 require "mongoid/errors/callback"
+require "mongoid/errors/create_collection_failure"
 require "mongoid/errors/criteria_argument_required"
 require "mongoid/errors/document_not_destroyed"
 require "mongoid/errors/document_not_found"
 require "mongoid/errors/empty_config_file"
+require "mongoid/errors/immutable_attribute"
 require "mongoid/errors/in_memory_collation_not_supported"
+require "mongoid/errors/invalid_async_query_executor"
 require "mongoid/errors/invalid_collection"
 require "mongoid/errors/invalid_config_file"
 require "mongoid/errors/invalid_config_option"
@@ -16,6 +19,7 @@ require "mongoid/errors/invalid_field"
 require "mongoid/errors/invalid_field_option"
 require "mongoid/errors/invalid_field_type"
 require "mongoid/errors/invalid_find"
+require "mongoid/errors/invalid_global_executor_concurrency"
 require "mongoid/errors/invalid_includes"
 require "mongoid/errors/invalid_index"
 require "mongoid/errors/invalid_options"
@@ -35,7 +39,6 @@ require "mongoid/errors/invalid_scope"
 require "mongoid/errors/invalid_session_use"
 require "mongoid/errors/invalid_set_polymorphic_relation"
 require "mongoid/errors/invalid_storage_options"
-require "mongoid/errors/invalid_storage_parent"
 require "mongoid/errors/invalid_time"
 require "mongoid/errors/inverse_not_found"
 require "mongoid/errors/mixed_relations"

data/lib/mongoid/extensions/object.rb

@@ -91,7 +91,7 @@ module Mongoid
       #   object.do_or_do_not(:use, "The Force")
       #
       # @param [ String | Symbol ] name The method name.
-      # @param [ Array ] args The arguments.
+      # @param [ Object... ] *args The arguments.
       #
       # @return [ Object | nil ] The result of the method call or nil if the
       #   method does not exist.
@@ -190,7 +190,7 @@ module Mongoid
       #   object.you_must(:use, "The Force")
       #
       # @param [ String | Symbol ] name The method name.
-      # @param [ Array ] args The arguments.
+      # @param [ Object... ] *args The arguments.
       #
       # @return [ Object | nil ] The result of the method call or nil if the
       #   method does not exist. Nil if the object is frozen.

data/lib/mongoid/extensions/time.rb

@@ -34,6 +34,8 @@ module Mongoid
         #   ::Time.configured
         #
         # @return [ Time ] The configured time.
+        #
+        # @deprecated
         def configured
           Mongoid.use_activesupport_time_zone? ? (::Time.zone || ::Time) : ::Time
         end

data/lib/mongoid/factory.rb

@@ -25,27 +25,40 @@ module Mongoid
     #
     # @return [ Document ] The instantiated document.
     def build(klass, attributes = nil)
-      execute_build(klass, attributes, execute_callbacks: true)
+      # A bug in Ruby 2.x (including 2.7.7) causes the attributes hash to be
+      # interpreted as keyword arguments, because execute_build accepts
+      # a keyword argument. Forcing an empty set of keyword arguments works
+      # around the bug. Once Ruby 2.x support is dropped, this hack can be
+      # removed.
+      # See https://bugs.ruby-lang.org/issues/15753
+      execute_build(klass, attributes)
     end
 
     # Execute the build.
     #
     # @param [ Class ] klass The class to instantiate from if _type is not present.
     # @param [ Hash ] attributes The document attributes.
-    # @param [ true | false ] execute_callbacks Flag specifies whether callbacks
-    #   should be run.
+    # @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 ] The instantiated document.
     #
     # @api private
-    def execute_build(klass, attributes = nil, execute_callbacks: true)
+    def execute_build(klass, attributes = nil, options = {})
       attributes ||= {}
       dvalue = attributes[klass.discriminator_key] || attributes[klass.discriminator_key.to_sym]
       type = klass.get_discriminator_mapping(dvalue)
       if type
-        type.construct_document(attributes, execute_callbacks: execute_callbacks)
+        type.construct_document(attributes, options)
       else
-        klass.construct_document(attributes, execute_callbacks: execute_callbacks)
+        klass.construct_document(attributes, options)
       end
     end
 
@@ -76,7 +89,7 @@ module Mongoid
     #
     # @return [ Document ] The instantiated document.
     def from_db(klass, attributes = nil, criteria = nil, selected_fields = nil)
-      execute_from_db(klass, attributes, criteria, selected_fields, execute_callbacks: true)
+      execute_from_db(klass, attributes, criteria, selected_fields)
     end
 
     # Execute from_db.
@@ -97,7 +110,7 @@ module Mongoid
     # @return [ Document ] The instantiated document.
     #
     # @api private
-    def execute_from_db(klass, attributes = nil, criteria = nil, selected_fields = nil, execute_callbacks: true)
+    def execute_from_db(klass, attributes = nil, criteria = nil, selected_fields = nil, execute_callbacks: Threaded.execute_callbacks?)
       if criteria
         selected_fields ||= criteria.options[:fields]
       end

data/lib/mongoid/fields/localized.rb

@@ -31,6 +31,16 @@ module Mongoid
         true
       end
 
+      # Is the localized field enforcing values to be present?
+      #
+      # @example Is the localized field enforcing values to be present?
+      #   field.localize_present?
+      #
+      # @return [ true | false ] If the field enforces present.
+      def localize_present?
+        options[:localize] == :present
+      end
+
       # Convert the provided string into a hash for the locale.
       #
       # @example Serialize the value.

data/lib/mongoid/fields/standard.rb

@@ -97,6 +97,16 @@ module Mongoid
         false
       end
 
+      # Is the localized field enforcing values to be present?
+      #
+      # @example Is the localized field enforcing values to be present?
+      #   field.localize_present?
+      #
+      # @return [ true | false ] If the field enforces present.
+      def localize_present?
+        false
+      end
+
       # Get the metadata for the field if its a foreign key.
       #
       # @example Get the metadata.

data/lib/mongoid/fields.rb

@@ -538,6 +538,8 @@ module Mongoid
       #   Model.add_defaults(field)
       #
       # @param [ Field ] field The field to add for.
+      #
+      # @api private
       def add_defaults(field)
         default, name = field.default_val, field.name.to_s
         remove_defaults(name)
@@ -557,6 +559,8 @@ module Mongoid
       #
       # @param [ Symbol ] name The name of the field.
       # @param [ Hash ] options The hash of options.
+      #
+      # @api private
       def add_field(name, options = {})
         aliased = options[:as]
         aliased_fields[aliased.to_s] = name if aliased
@@ -584,6 +588,8 @@ module Mongoid
       #   # => "called"
       #
       # @param [ Field ] field the field to process
+      #
+      # @api private
       def process_options(field)
         field_options = field.options
 
@@ -606,6 +612,8 @@ module Mongoid
       # @param [ Symbol ] name The name of the field.
       # @param [ Symbol ] meth The name of the accessor.
       # @param [ Hash ] options The options.
+      #
+      # @api private
       def create_accessors(name, meth, options = {})
         field = fields[name]
 
@@ -629,6 +637,8 @@ module Mongoid
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
       # @param [ Field ] field The field.
+      #
+      # @api private
       def create_field_getter(name, meth, field)
         generated_methods.module_eval do
           re_define_method(meth) do
@@ -651,6 +661,8 @@ module Mongoid
       #
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
+      #
+      # @api private
       def create_field_getter_before_type_cast(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_before_type_cast") do
@@ -671,6 +683,8 @@ module Mongoid
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
       # @param [ Field ] field The field.
+      #
+      # @api private
       def create_field_setter(name, meth, field)
         generated_methods.module_eval do
           re_define_method("#{meth}=") do |value|
@@ -690,6 +704,8 @@ module Mongoid
       #
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
+      #
+      # @api private
       def create_field_check(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}?") do
@@ -706,6 +722,8 @@ module Mongoid
       #
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
+      #
+      # @api private
       def create_translations_getter(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_translations") do
@@ -724,6 +742,8 @@ module Mongoid
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
       # @param [ Field ] field The field.
+      #
+      # @api private
       def create_translations_setter(name, meth, field)
         generated_methods.module_eval do
           re_define_method("#{meth}_translations=") do |value|
@@ -743,6 +763,8 @@ module Mongoid
       #   Person.generated_methods
       #
       # @return [ Module ] The module of generated methods.
+      #
+      # @api private
       def generated_methods
         @generated_methods ||= begin
           mod = Module.new
@@ -757,21 +779,49 @@ module Mongoid
       #   Model.remove_defaults(name)
       #
       # @param [ String ] name The field name.
+      #
+      # @api private
       def remove_defaults(name)
         pre_processed_defaults.delete_one(name)
         post_processed_defaults.delete_one(name)
       end
 
+      # Create a field for the given name and options.
+      #
+      # @param [ Symbol ] name The name of the field.
+      # @param [ Hash ] options The hash of options.
+      #
+      # @return [ Field ] The created field.
+      #
+      # @api private
       def field_for(name, options)
         opts = options.merge(klass: self)
-        type_mapping = TYPE_MAPPINGS[options[:type]]
-        opts[:type] = type_mapping || unmapped_type(options)
-        if !opts[:type].is_a?(Class)
-          raise Errors::InvalidFieldType.new(self, name, options[:type])
+        opts[:type] = retrieve_and_validate_type(name, options[:type])
+        return Fields::Localized.new(name, opts) if options[:localize]
+        return Fields::ForeignKey.new(name, opts) if options[:identity]
+        Fields::Standard.new(name, opts)
+      end
+
+      # Get the class for the given type.
+      #
+      # @param [ Symbol ] name The name of the field.
+      # @param [ Symbol | Class ] type The type of the field.
+      #
+      # @return [ Class ] The type of the field.
+      #
+      # @raises [ Mongoid::Errors::InvalidFieldType ] if given an invalid field
+      #   type.
+      #
+      # @api private
+      def retrieve_and_validate_type(name, type)
+        type_mapping = TYPE_MAPPINGS[type]
+        result = type_mapping || unmapped_type(type)
+        if !result.is_a?(Class)
+          raise Errors::InvalidFieldType.new(self, name, type)
         else
-          if INVALID_BSON_CLASSES.include?(opts[:type])
-            warn_message = "Using #{opts[:type]} as the field type is not supported. "
-            if opts[:type] == BSON::Decimal128
+          if INVALID_BSON_CLASSES.include?(result)
+            warn_message = "Using #{result} as the field type is not supported. "
+            if result == BSON::Decimal128
               warn_message += "In BSON <= 4, the BSON::Decimal128 type will work as expected for both storing and querying, but will return a BigDecimal on query in BSON 5+."
             else
               warn_message += "Saving values of this type to the database will work as expected, however, querying them will return a value of the native Ruby Integer type."
@@ -779,16 +829,22 @@ module Mongoid
             Mongoid.logger.warn(warn_message)
           end
         end
-        return Fields::Localized.new(name, opts) if options[:localize]
-        return Fields::ForeignKey.new(name, opts) if options[:identity]
-        Fields::Standard.new(name, opts)
+        result
       end
 
-      def unmapped_type(options)
-        if "Boolean" == options[:type].to_s
+      # Returns the type of the field if the type was not in the TYPE_MAPPINGS
+      # hash.
+      #
+      # @param [ Symbol | Class ] type The type of the field.
+      #
+      # @return [ Class ] The type of the field.
+      #
+      # @api private
+      def unmapped_type(type)
+        if "Boolean" == type.to_s
           Mongoid::Boolean
         else
-          options[:type] || Object
+          type || Object
         end
       end
     end