mongoid 8.1.5 → 9.0.0

data/lib/mongoid/reloadable.rb

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 
 module Mongoid
-
   # This module handles reloading behavior of documents.
   module Reloadable
-
     # Reloads the +Document+ attributes from the database. If the document has
     # not been saved then an error will get raised if the configuration option
     # was set. This can reload root documents or embedded documents.
@@ -17,28 +15,53 @@ module Mongoid
     # @return [ Document ] The document, reloaded.
     def reload
       reloaded = _reload
-      if Mongoid.raise_not_found_error && (reloaded.nil? || reloaded.empty?)
-        shard_keys = atomic_selector.with_indifferent_access.slice(*shard_key_fields, :_id)
-        raise Errors::DocumentNotFound.new(self.class, _id, shard_keys)
-      end
+      check_for_deleted_document!(reloaded)
+
+      reset_object!(reloaded)
+
+      run_callbacks(:find) unless _find_callbacks.empty?
+      run_callbacks(:initialize) unless _initialize_callbacks.empty?
+      self
+    end
+
+    private
 
+    # Resets the current object using the given attributes.
+    #
+    # @param [ Hash ] attributes The attributes to use to replace the current
+    #   attributes hash.
+    def reset_object!(attributes)
       reset_atomic_updates!
 
-      @attributes = reloaded
+      @attributes = attributes
       @attributes_before_type_cast = @attributes.dup
       @changed_attributes = {}
       @previous_changes = {}
       @previous_attributes = {}
       @previously_new_record = false
+
       reset_readonly
       apply_defaults
       reload_relations
-      run_callbacks(:find) unless _find_callbacks.empty?
-      run_callbacks(:initialize) unless _initialize_callbacks.empty?
-      self
     end
 
-    private
+    # Checks to see if the given attributes argument indicates that the object
+    # has been deleted. If the attributes are nil or an empty Hash, then
+    # we assume it has been deleted.
+    #
+    # If Mongoid.raise_not_found_error is false, this will do nothing.
+    #
+    # @param [ Hash | nil ] attributes The attributes hash retrieved from
+    #   the database
+    #
+    # @raise [ Errors::DocumentNotFound ] If the document was deleted.
+    def check_for_deleted_document!(attributes)
+      return unless Mongoid.raise_not_found_error
+      return unless attributes.nil? || attributes.empty?
+
+      shard_keys = atomic_selector.with_indifferent_access.slice(*shard_key_fields, :_id)
+      raise Errors::DocumentNotFound.new(self.class, _id, shard_keys)
+    end
 
     # Reload the document, determining if it's embedded or not and what
     # behavior to use.
@@ -68,25 +91,10 @@ module Mongoid
     #
     # @return [ Hash ] The reloaded attributes.
     def reload_embedded_document
-      extract_embedded_attributes({}.merge(
-        collection(_root).find(_root.atomic_selector, session: _session).read(mode: :primary).first
-      ))
-    end
-
-    # Extract only the desired embedded document from the attributes.
-    #
-    # @example Extract the embedded document.
-    #   document.extract_embedded_attributes(attributes)
-    #
-    # @param [ Hash ] attributes The document in the db.
-    #
-    # @return [ Hash | nil ] The document's extracted attributes or nil if the
-    #   document doesn't exist.
-    def extract_embedded_attributes(attributes)
-      atomic_position.split(".").inject(attributes) do |attrs, part|
-        attrs = attrs[part =~ /\d/ ? part.to_i : part]
-        attrs
-      end
+      Mongoid::Attributes::Embedded.traverse(
+        collection(_root).find(_root.atomic_selector, session: _session).read(mode: :primary).first,
+        atomic_position
+      )
     end
   end
 end

data/lib/mongoid/scopable.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
 
@@ -158,26 +159,27 @@ module Mongoid
         queryable.scoped(options)
       end
 
-      # Get the criteria without the default scoping applied.
+      # Get the criteria without any scoping applied.
       #
       # @example Get the unscoped criteria.
       #   Band.unscoped
       #
-      # @example Yield to block with no default scoping.
+      # @example Yield to block with no scoping.
       #   Band.unscoped do
       #     Band.where(name: "Depeche Mode")
       #   end
       #
-      # @note This will force the default scope to be removed, but will not
-      #   remove scopes declared with ``.with_scope``. This will be changed
-      #   in Mongoid 9.
+      # @note This will force the default scope, as well as any scope applied
+      #   using ``.with_scope``, to be removed.
       #
       # @return [ Criteria | Object ] The unscoped criteria or result of the
       #   block.
       def unscoped
         if block_given?
           without_default_scope do
-            yield(self)
+            with_scope(nil) do
+              yield(self)
+            end
           end
         else
           queryable.unscoped
@@ -210,11 +212,7 @@ module Mongoid
         begin
           yield criteria
         ensure
-          if Mongoid.broken_scoping
-            Threaded.set_current_scope(nil, self)
-          else
-            Threaded.set_current_scope(previous, self)
-          end
+          Threaded.set_current_scope(previous, self)
         end
       end
 
@@ -240,7 +238,7 @@ module Mongoid
       # @api private
       #
       # @example Warn or raise error if name exists.
-      #   Model.valid_scope_name?("test")
+      #   Model.check_scope_name("test")
       #
       # @param [ String | Symbol ] name The name of the scope.
       #
@@ -291,17 +289,15 @@ module Mongoid
       # @return [ Method ] The defined method.
       def define_scope_method(name)
         singleton_class.class_eval do
-          ruby2_keywords(
-            define_method(name) do |*args|
-              scoping = _declared_scopes[name]
-              scope = instance_exec(*args, &scoping[:scope])
-              extension = scoping[:extension]
-              to_merge = scope || queryable
-              criteria = to_merge.empty_and_chainable? ? to_merge : with_default_scope.merge(to_merge)
-              criteria.extend(extension)
-              criteria
-            end
-          )
+          define_method(name) do |*args, **kwargs|
+            scoping = _declared_scopes[name]
+            scope = instance_exec(*args, **kwargs, &scoping[:scope])
+            extension = scoping[:extension]
+            to_merge = scope || queryable
+            criteria = to_merge.empty_and_chainable? ? to_merge : with_default_scope.merge(to_merge)
+            criteria.extend(extension)
+            criteria
+          end
         end
       end
 

data/lib/mongoid/search_indexable.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Mongoid
+  # Encapsulates behavior around managing search indexes. This feature
+  # is only supported when connected to an Atlas cluster.
+  module SearchIndexable
+    extend ActiveSupport::Concern
+
+    # Represents the status of the indexes returned by a search_indexes
+    # call.
+    #
+    # @api private
+    class Status
+      # @return [ Array<Hash> ] the raw index documents
+      attr_reader :indexes
+
+      # Create a new Status object.
+      #
+      # @param [ Array<Hash> ] indexes the raw index documents
+      def initialize(indexes)
+        @indexes = indexes
+      end
+
+      # Returns the subset of indexes that have status == 'READY'
+      #
+      # @return [ Array<Hash> ] index documents for "ready" indices
+      def ready
+        indexes.select { |i| i['status'] == 'READY' }
+      end
+
+      # Returns the subset of indexes that have status == 'PENDING'
+      #
+      # @return [ Array<Hash> ] index documents for "pending" indices
+      def pending
+        indexes.select { |i| i['status'] == 'PENDING' }
+      end
+
+      # Returns the subset of indexes that are marked 'queryable'
+      #
+      # @return [ Array<Hash> ] index documents for 'queryable' indices
+      def queryable
+        indexes.select { |i| i['queryable'] }
+      end
+
+      # Returns true if all the given indexes are 'ready' and 'queryable'.
+      #
+      # @return [ true | false ] ready status of all indexes
+      def ready?
+        indexes.all? { |i| i['status'] == 'READY' && i['queryable'] }
+      end
+    end
+
+    included do
+      cattr_accessor :search_index_specs
+      self.search_index_specs = []
+    end
+
+    # Implementations for the feature's class-level methods.
+    module ClassMethods
+      # Request the creation of all registered search indices. Note
+      # that the search indexes are created asynchronously, and may take
+      # several minutes to be fully available.
+      #
+      # @return [ Array<String> ] The names of the search indexes.
+      def create_search_indexes
+        return if search_index_specs.empty?
+
+        collection.search_indexes.create_many(search_index_specs)
+      end
+
+      # Waits for the named search indexes to be created.
+      #
+      # @param [ Array<String> ] names the list of index names to wait for
+      # @param [ Integer ] interval the number of seconds to wait before
+      #   polling again (only used when a progress callback is given).
+      #
+      # @yield [ SearchIndexable::Status ] the status object
+      def wait_for_search_indexes(names, interval: 5)
+        loop do
+          status = Status.new(get_indexes(names))
+          yield status if block_given?
+          break if status.ready?
+
+          sleep interval
+        end
+      end
+
+      # A convenience method for querying the search indexes available on the
+      # current model's collection.
+      #
+      # @param [ Hash ] options the options to pass through to the search
+      #   index query.
+      #
+      # @option options [ String ] :id The id of the specific index to query (optional)
+      # @option options [ String ] :name The name of the specific index to query (optional)
+      # @option options [ Hash ] :aggregate The options hash to pass to the
+      #    aggregate command (optional)
+      def search_indexes(options = {})
+        collection.search_indexes(options)
+      end
+
+      # Removes the search index specified by the given name or id. Either
+      # name OR id must be given, but not both.
+      #
+      # @param [ String | nil ] name the name of the index to remove
+      # @param [ String | nil ] id the id of the index to remove
+      def remove_search_index(name: nil, id: nil)
+        logger.info(
+          "MONGOID: Removing search index '#{name || id}' " \
+          "on collection '#{collection.name}'."
+        )
+
+        collection.search_indexes.drop_one(name: name, id: id)
+      end
+
+      # Request the removal of all registered search indexes. Note
+      # that the search indexes are removed asynchronously, and may take
+      # several minutes to be fully deleted.
+      #
+      # @note It would be nice if this could remove ONLY the search indexes
+      # that have been declared on the model, but because the model may not
+      # name the index, we can't guarantee that we'll know the name or id of
+      # the corresponding indexes. It is not unreasonable to assume, though,
+      # that the intention is for the model to declare, one-to-one, all
+      # desired search indexes, so removing all search indexes ought to suffice.
+      # If a specific index or set of indexes needs to be removed instead,
+      # consider using search_indexes.each with remove_search_index.
+      def remove_search_indexes
+        search_indexes.each do |spec|
+          remove_search_index id: spec['id']
+        end
+      end
+
+      # Adds an index definition for the provided single or compound keys.
+      #
+      # @example Create a basic index.
+      #   class Person
+      #     include Mongoid::Document
+      #     field :name, type: String
+      #     search_index({ ... })
+      #     search_index :name_of_index, { ... }
+      #   end
+      #
+      # @param [ Symbol | String | Hash ] name_or_defn Either the name of the index to
+      #    define, or the index definition.
+      # @param [ Hash ] defn The search index definition.
+      def search_index(name_or_defn, defn = nil)
+        name = name_or_defn
+        name, defn = nil, name if name.is_a?(Hash)
+
+        spec = { definition: defn }.tap { |s| s[:name] = name.to_s if name }
+        search_index_specs.push(spec)
+      end
+
+      private
+
+      # Retrieves the index records for the indexes with the given names.
+      #
+      # @param [ Array<String> ] names the index names to query
+      #
+      # @return [ Array<Hash> ] the raw index documents
+      def get_indexes(names)
+        collection.search_indexes.select { |i| names.include?(i['name']) }
+      end
+    end
+  end
+end

data/lib/mongoid/selectable.rb

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

data/lib/mongoid/serializable.rb

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

data/lib/mongoid/shardable.rb

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

data/lib/mongoid/stateful.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
 
-  # This module contains the behavior for getting the various states a
-  # document can transition through.
+  # Mixin module included into Mongoid::Document which adds behavior for
+  # getting the various lifecycle states a document can transition through.
   module Stateful
 
     attr_writer :destroyed, :flagged_for_destroy, :previously_new_record
 
+    # Sets whether the document has been persisted to the database.
+    #
+    # @param [ true | false ] new_value The value to set.
+    #
+    # @return [ true | false ] The set value.
     def new_record=(new_value)
       @new_record ||= false
       if @new_record && !new_value
@@ -16,7 +22,7 @@ module Mongoid
       @new_record = new_value
     end
 
-    # Returns true if the +Document+ has not been persisted to the database,
+    # Returns true if the document has not been persisted to the database,
     # false if it has. This is determined by the variable @new_record
     # and NOT if the object has an id.
     #

data/lib/mongoid/stringified_symbol.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
-# A class which sends values to the database as Strings but returns them to the user as Symbols.
 module Mongoid
+
+  # A class which sends values to the database as Strings but returns
+  # them to the user as Symbols.
   class StringifiedSymbol
 
     class << self
@@ -9,7 +12,7 @@ module Mongoid
       # Convert the object from its mongo friendly ruby type to this type.
       #
       # @example Demongoize the object.
-      #   Mongoid::StringifiedSymbol.demongoize(object)
+      #   Mongoid::StringifiedSymbol.demongoize('hedgehog')
       #
       # @param [ Object ] object The object to demongoize.
       #
@@ -24,15 +27,15 @@ module Mongoid
         end
       end
 
-      # Turn the object from the ruby type we deal with to a Mongo friendly
-      # type.
+      # Turn the object from the Ruby type into the type
+      # type used for MongoDB persistence.
       #
       # @example Mongoize the object.
-      #   Mongoid::StringifiedSymbol.mongoize("123.11")
+      #   Mongoid::StringifiedSymbol.mongoize(:hedgehog)
       #
       # @param [ Object ] object The object to mongoize.
       #
-      # @return [ Symbol ] The object mongoized.
+      # @return [ String ] The object mongoized.
       #
       # @api private
       def mongoize(object)
@@ -43,6 +46,16 @@ module Mongoid
          end
       end
 
+      # Turn the object from the Ruby type into the type
+      # type used in MQL queries.
+      #
+      # @example Evolve the object.
+      #   Mongoid::StringifiedSymbol.evolve(:hedgehog)
+      #
+      # @param [ Object ] object The object to evolve.
+      #
+      # @return [ String ] The object evolved.
+      #
       # @api private
       def evolve(object)
         mongoize(object)

data/lib/mongoid/tasks/database.rake

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 namespace :db do
   namespace :mongoid do
     task :load_models do
+      ::Mongoid.load_models
     end
 
     desc "Create collections for Mongoid models"
@@ -15,6 +17,12 @@ namespace :db do
       ::Mongoid::Tasks::Database.create_indexes
     end
 
+    desc "Create search indexes specified in Mongoid models"
+    task :create_search_indexes => [:environment, :load_models] do
+      wait = Mongoid::Utils.truthy_string?(ENV['WAIT_FOR_SEARCH_INDEXES'] || '1')
+      ::Mongoid::Tasks::Database.create_search_indexes(wait: wait)
+    end
+
     desc "Remove indexes that exist in the database but are not specified in Mongoid models"
     task :remove_undefined_indexes => [:environment, :load_models] do
       ::Mongoid::Tasks::Database.remove_undefined_indexes
@@ -25,6 +33,11 @@ namespace :db do
       ::Mongoid::Tasks::Database.remove_indexes
     end
 
+    desc "Remove search indexes specified in Mongoid models"
+    task :remove_search_indexes => [:environment, :load_models] do
+      ::Mongoid::Tasks::Database.remove_search_indexes
+    end
+
     desc "Shard collections with shard keys specified in Mongoid models"
     task :shard_collections => [:environment, :load_models] do
       ::Mongoid::Tasks::Database.shard_collections

data/lib/mongoid/tasks/database.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Tasks
+
+    # Utility module to manage database collections, indexes, sharding, etc.
+    # Invoked from Rake tasks.
     module Database
       extend self
 
@@ -22,6 +26,9 @@ module Mongoid
           else
             logger.info("MONGOID: collection options ignored on: #{model}, please define in the root model.")
           end
+        rescue Exception
+          logger.error "error while creating collection for #{model}"
+          raise
         end
       end
 
@@ -49,6 +56,26 @@ module Mongoid
         end.compact
       end
 
+      # Submit requests for the search indexes to be created. This will happen
+      # asynchronously. If "wait" is true, the method will block while it
+      # waits for the indexes to be created.
+      #
+      # @param [ Array<Mongoid::Document> ] models the models to build search
+      #   indexes for.
+      # @param [ true | false ] wait whether to wait for the indexes to be
+      #   built.
+      def create_search_indexes(models = ::Mongoid.models, wait: true)
+        searchable = models.select { |m| m.search_index_specs.any? }
+
+        # queue up the search index creation requests
+        index_names_by_model = searchable.each_with_object({}) do |model, obj|
+          logger.info("MONGOID: Creating search indexes on #{model}...")
+          obj[model] = model.create_search_indexes
+        end
+
+        wait_for_search_indexes(index_names_by_model) if wait
+      end
+
       # Return the list of indexes by model that exist in the database but aren't
       # specified on the models.
       #
@@ -121,6 +148,17 @@ module Mongoid
         end.compact
       end
 
+      # Remove all search indexes from the given models.
+      #
+      # @params [ Array<Mongoid::Document> ] models the models to remove
+      #   search indexes from.
+      def remove_search_indexes(models = ::Mongoid.models)
+        models.each do |model|
+          next if model.embedded?
+          model.remove_search_indexes
+        end
+      end
+
       # Shard collections for models that declare shard keys.
       #
       # Returns the model classes that have had their collections sharded,
@@ -209,6 +247,31 @@ module Mongoid
       def logger
         Mongoid.logger
       end
+
+      # Waits for the search indexes to be built on the given models.
+      #
+      # @param [ Hash<Mongoid::Document, Array<String>> ] models a mapping of
+      #   index names for each model
+      def wait_for_search_indexes(models)
+        logger.info('MONGOID: Waiting for search indexes to be created')
+        logger.info('MONGOID: Press ctrl-c to skip the wait and let the indexes be created in the background')
+
+        models.each do |model, names|
+          model.wait_for_search_indexes(names) do |status|
+            if status.ready?
+              puts
+              logger.info("MONGOID: Search indexes on #{model} are READY")
+            else
+              print '.'
+              $stdout.flush
+            end
+          end
+        end
+      rescue Interrupt
+        # ignore ctrl-C here; we assume it is meant only to skip
+        # the wait, and that subsequent tasks ought to continue.
+        logger.info('MONGOID: Skipping the wait for search indexes; they will be created in the background')
+      end
     end
   end
 end

data/lib/mongoid/tasks/encryption.rake

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+def parse_data_key_options(argv = ARGV)
+  # The only way to use OptionParser to parse custom options in rake is
+  # to pass an empty argument ("--") before specifying them, e.g.:
+  #
+  #    rake db:mongoid:encryption:create_data_key -- --client default
+  #
+  # Otherwise, rake complains about an unknown option. Thus, we can tell
+  # if the argument list is valid for us to parse by detecting this empty
+  # argument.
+  #
+  # (This works around an issue in the tests, where the specs are loading
+  # the tasks directly to test them, but the option parser is then picking
+  # up rspec command-line arguments and raising an exception).
+  return {} unless argv.include?('--')
+
+  {}.tap do |options|
+    parser = OptionParser.new do |opts|
+      opts.on('-c', '--client CLIENT', 'Name of the client to use') do |v|
+        options[:client_name] = v
+      end
+      opts.on('-p', '--provider PROVIDER', 'KMS provider to use') do |v|
+        options[:kms_provider_name] = v
+      end
+      opts.on('-n', '--key-alt-name KEY_ALT_NAME', 'Alternate name for the key') do |v|
+        options[:key_alt_name] = v
+      end
+    end
+    # rubocop:disable Lint/EmptyBlock
+    parser.parse!(parser.order!(argv) {})
+    # rubocop:enable Lint/EmptyBlock
+  end
+end
+
+namespace :db do
+  namespace :mongoid do
+    namespace :encryption do
+      desc 'Create encryption key'
+      task create_data_key: [ :environment ] do
+        options = parse_data_key_options
+        result = Mongoid::Tasks::Encryption.create_data_key(
+          client_name: options[:client_name],
+          kms_provider_name: options[:kms_provider_name],
+          key_alt_name: options[:key_alt_name]
+        )
+        output = [].tap do |lines|
+          lines << "Created data key with id: '#{result[:key_id]}'"
+          lines << "with key alt name: '#{result[:key_alt_name]}'" if result[:key_alt_name]
+          lines << "for kms provider: '#{result[:kms_provider]}'"
+          lines << "in key vault: '#{result[:key_vault_namespace]}'."
+        end
+        puts output.join(' ')
+      end
+    end
+  end
+end