mongoid 7.2.1 → 9.0.0

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

data/lib/mongoid/tasks/encryption.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module Mongoid
+  module Tasks
+    # This module contains helper methods for data encryption.
+    module Encryption
+      extend self
+
+      # Create a data encryption key for the given kms provider using the
+      # auto_encryption_options from the client's configuration.
+      #
+      # @param [ String | nil ] kms_provider_name The name of the kms provider
+      #   to use. If not provided, the first provider in the client's
+      #   auto_encryption_options will be used.
+      # @param [ String | nil ] client_name The name of the client to take
+      #   auto_encryption_options from. If not provided, the default client
+      #   will be used.
+      # @param [ String | nil ] key_alt_name The alternate name of the key.
+      #
+      # @return [ Hash ] A hash containing the key id as :key_id,
+      #   kms provider name as :kms_provider, and key vault namespace as
+      #   :key_vault_namespace.
+      def create_data_key(client_name: nil, kms_provider_name: nil, key_alt_name: nil)
+        kms_provider_name, kms_providers, key_vault_namespace = prepare_arguments(
+          kms_provider_name,
+          client_name
+        )
+        key_vault_client = Mongoid::Clients.default.with(database: key_vault_namespace.split('.').first)
+        client_encryption = Mongo::ClientEncryption.new(
+          key_vault_client,
+          key_vault_namespace: key_vault_namespace,
+          kms_providers: kms_providers
+        )
+        client_encryption_opts = {}.tap do |opts|
+          opts[:key_alt_names] = [key_alt_name] if key_alt_name
+        end
+        data_key_id = client_encryption.create_data_key(kms_provider_name, client_encryption_opts)
+        {
+          key_id: Base64.strict_encode64(data_key_id.data),
+          kms_provider: kms_provider_name,
+          key_vault_namespace: key_vault_namespace,
+          key_alt_name: key_alt_name
+        }.compact
+      end
+
+      private
+
+      # Prepare arguments needed to create a data key from the client's
+      # auto_encryption_options.
+      #
+      # @param [ String | nil ] kms_provider_name The name of the kms provider.
+      # @param [ String | nil ] client_name The name of the client.
+      #
+      # @return [ Array<String, Hash, String> ] An array containing the
+      #   normalized kms provider name, the kms providers hash, and the key
+      #   vault namespace.
+      def prepare_arguments(kms_provider_name, client_name)
+        client = (client_name || 'default').to_s
+        client_options = Mongoid.clients[client]
+        unless client_options.is_a?(Hash)
+          raise Errors::NoClientConfig.new(client)
+        end
+        auto_encryption_options = client_options.dig(:options, :auto_encryption_options)
+        unless auto_encryption_options.is_a?(Hash)
+          raise Errors::InvalidAutoEncryptionConfiguration.new(client)
+        end
+        key_vault_namespace = auto_encryption_options[:key_vault_namespace]
+        unless key_vault_namespace.is_a?(String)
+          raise Errors::InvalidAutoEncryptionConfiguration.new(client)
+        end
+        kms_providers = auto_encryption_options[:kms_providers]
+        unless kms_providers.is_a?(Hash)
+          raise Errors::InvalidAutoEncryptionConfiguration.new(client)
+        end
+        valid_kms_provider_name = get_kms_provider_name(kms_provider_name, kms_providers)
+        unless kms_providers.key?(valid_kms_provider_name)
+          raise Errors::InvalidAutoEncryptionConfiguration.new(client, valid_kms_provider_name)
+        end
+
+        [valid_kms_provider_name, kms_providers, key_vault_namespace]
+      end
+
+      # Get kms provider name to use for creating a data key.
+      #
+      # If kms_provider_name is provided, it will be used. Otherwise, if there
+      # is only one kms provider, that provider will be used. Otherwise, an
+      # error will be raised.
+      #
+      # @param [ String | nil ] kms_provider_name The name of the kms provider
+      #   as provided by the user.
+      # @param [ Hash ] kms_providers The kms providers hash from the client's
+      #   auto_encryption_options.
+      #
+      # @return [ String ] The kms provider name to use for creating a data
+      #   key.
+      def get_kms_provider_name(kms_provider_name, kms_providers)
+        if kms_provider_name
+          kms_provider_name
+        elsif kms_providers.keys.length == 1
+          kms_providers.keys.first
+        else
+          raise ArgumentError, 'kms_provider_name must be provided when there are multiple kms providers'
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/threaded/lifecycle.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Threaded
@@ -26,8 +26,6 @@ module Mongoid
       #   end
       #
       # @return [ Object ] The yielded value.
-      #
-      # @since 2.2.0
       def _assigning
         Threaded.begin_execution(ASSIGN)
         yield
@@ -40,9 +38,7 @@ module Mongoid
       # @example Is the current thread in assigning mode?
       #   proxy._assigning?
       #
-      # @return [ true, false ] If the thread is assigning.
-      #
-      # @since 2.1.0
+      # @return [ true | false ] If the thread is assigning.
       def _assigning?
         Threaded.executing?(ASSIGN)
       end
@@ -55,8 +51,6 @@ module Mongoid
       #   end
       #
       # @return [ Object ] The return value of the block.
-      #
-      # @since 2.1.0
       def _binding
         Threaded.begin_execution(BIND)
         yield
@@ -69,9 +63,7 @@ module Mongoid
       # @example Is the current thread in binding mode?
       #   proxy.binding?
       #
-      # @return [ true, false ] If the thread is binding.
-      #
-      # @since 2.1.0
+      # @return [ true | false ] If the thread is binding.
       def _binding?
         Threaded.executing?(BIND)
       end
@@ -84,8 +76,6 @@ module Mongoid
       #   end
       #
       # @return [ Object ] The return value of the block.
-      #
-      # @since 2.1.0
       def _building
         Threaded.begin_execution(BUILD)
         yield
@@ -98,9 +88,7 @@ module Mongoid
       # @example Is the current thread in building mode?
       #   proxy._building?
       #
-      # @return [ true, false ] If the thread is building.
-      #
-      # @since 2.1.0
+      # @return [ true | false ] If the thread is building.
       def _building?
         Threaded.executing?(BUILD)
       end
@@ -110,9 +98,7 @@ module Mongoid
       # @example Is the current thread in creating mode?
       #   proxy.creating?
       #
-      # @return [ true, false ] If the thread is creating.
-      #
-      # @since 2.1.0
+      # @return [ true | false ] If the thread is creating.
       def _creating?
         Threaded.executing?(CREATE)
       end
@@ -125,8 +111,6 @@ module Mongoid
       #   end
       #
       # @return [ Object ] The return value of the block.
-      #
-      # @since 2.3.2
       def _loading
         Threaded.begin_execution(LOAD)
         yield
@@ -139,9 +123,7 @@ module Mongoid
       # @example Is the current thread in loading mode?
       #   proxy._loading?
       #
-      # @return [ true, false ] If the thread is loading.
-      #
-      # @since 2.3.2
+      # @return [ true | false ] If the thread is loading.
       def _loading?
         Threaded.executing?(LOAD)
       end
@@ -156,8 +138,6 @@ module Mongoid
         #   end
         #
         # @return [ Object ] The return value of the block.
-        #
-        # @since 2.1.0
         def _creating
           Threaded.begin_execution(CREATE)
           yield

data/lib/mongoid/threaded.rb

@@ -1,38 +1,39 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
-require "mongoid/threaded/lifecycle"
+require 'mongoid/threaded/lifecycle'
 
 module Mongoid
-
   # This module contains logic for easy access to objects that have a lifecycle
   # on the current thread.
   module Threaded
-
-    DATABASE_OVERRIDE_KEY = "[mongoid]:db-override"
+    DATABASE_OVERRIDE_KEY = '[mongoid]:db-override'
 
     # Constant for the key to store clients.
-    #
-    # @since 5.0.0
-    CLIENTS_KEY = "[mongoid]:clients"
+    CLIENTS_KEY = '[mongoid]:clients'
 
     # The key to override the client.
-    #
-    # @since 5.0.0
-    CLIENT_OVERRIDE_KEY = "[mongoid]:client-override"
+    CLIENT_OVERRIDE_KEY = '[mongoid]:client-override'
 
     # The key for the current thread's scope stack.
-    #
-    # @since 2.0.0
-    CURRENT_SCOPE_KEY = "[mongoid]:current-scope"
+    CURRENT_SCOPE_KEY = '[mongoid]:current-scope'
 
-    AUTOSAVES_KEY = "[mongoid]:autosaves"
-    VALIDATIONS_KEY = "[mongoid]:validations"
+    AUTOSAVES_KEY = '[mongoid]:autosaves'
+    VALIDATIONS_KEY = '[mongoid]:validations'
 
     STACK_KEYS = Hash.new do |hash, key|
       hash[key] = "[mongoid]:#{key}-stack"
     end
 
+    # The key for the current thread's sessions.
+    SESSIONS_KEY = '[mongoid]:sessions'
+
+    # The key for storing documents modified inside transactions.
+    MODIFIED_DOCUMENTS_KEY = '[mongoid]:modified-documents'
+
+    # The key storing the default value for whether or not callbacks are
+    # executed on documents.
+    EXECUTE_CALLBACKS = '[mongoid]:execute-callbacks'
+
     extend self
 
     # Begin entry into a named thread local stack.
@@ -43,8 +44,6 @@ module Mongoid
     # @param [ String ] name The name of the stack
     #
     # @return [ true ] True.
-    #
-    # @since 2.4.0
     def begin_execution(name)
       stack(name).push(true)
     end
@@ -54,9 +53,7 @@ module Mongoid
     # @example Get the global database override.
     #   Threaded.database_override
     #
-    # @return [ String, Symbol ] The override.
-    #
-    # @since 3.0.0
+    # @return [ String | Symbol ] The override.
     def database_override
       Thread.current[DATABASE_OVERRIDE_KEY]
     end
@@ -66,11 +63,9 @@ module Mongoid
     # @example Set the global database override.
     #   Threaded.database_override = :testing
     #
-    # @param [ String, Symbol ] name The global override name.
+    # @param [ String | Symbol ] name The global override name.
     #
-    # @return [ String, Symbol ] The override.
-    #
-    # @since 3.0.0
+    # @return [ String | Symbol ] The override.
     def database_override=(name)
       Thread.current[DATABASE_OVERRIDE_KEY] = name
     end
@@ -83,8 +78,6 @@ module Mongoid
     # @param [ Symbol ] name The name of the stack
     #
     # @return [ true ] If the stack is being executed.
-    #
-    # @since 2.4.0
     def executing?(name)
       !stack(name).empty?
     end
@@ -97,8 +90,6 @@ module Mongoid
     # @param [ Symbol ] name The name of the stack
     #
     # @return [ true ] True.
-    #
-    # @since 2.4.0
     def exit_execution(name)
       stack(name).pop
     end
@@ -111,8 +102,6 @@ module Mongoid
     # @param [ Symbol ] name The name of the stack
     #
     # @return [ Array ] The stack.
-    #
-    # @since 2.4.0
     def stack(name)
       Thread.current[STACK_KEYS[name]] ||= []
     end
@@ -123,8 +112,6 @@ module Mongoid
     #   Threaded.begin_autosave(doc)
     #
     # @param [ Document ] document The document to autosave.
-    #
-    # @since 3.0.0
     def begin_autosave(document)
       autosaves_for(document.class).push(document._id)
     end
@@ -135,8 +122,6 @@ module Mongoid
     #   Threaded.begin_validate(doc)
     #
     # @param [ Document ] document The document to validate.
-    #
-    # @since 2.1.9
     def begin_validate(document)
       validations_for(document.class).push(document._id)
     end
@@ -147,8 +132,6 @@ module Mongoid
     #   Threaded.exit_autosave(doc)
     #
     # @param [ Document ] document The document to autosave.
-    #
-    # @since 3.0.0
     def exit_autosave(document)
       autosaves_for(document.class).delete_one(document._id)
     end
@@ -159,8 +142,6 @@ module Mongoid
     #   Threaded.exit_validate(doc)
     #
     # @param [ Document ] document The document to validate.
-    #
-    # @since 2.1.9
     def exit_validate(document)
       validations_for(document.class).delete_one(document._id)
     end
@@ -194,9 +175,7 @@ module Mongoid
     # @example Get the global client override.
     #   Threaded.client_override
     #
-    # @return [ String, Symbol ] The override.
-    #
-    # @since 5.0.0
+    # @return [ String | Symbol ] The override.
     def client_override
       Thread.current[CLIENT_OVERRIDE_KEY]
     end
@@ -206,11 +185,9 @@ module Mongoid
     # @example Set the global client override.
     #   Threaded.client_override = :testing
     #
-    # @param [ String, Symbol ] name The global override name.
-    #
-    # @return [ String, Symbol ] The override.
+    # @param [ String | Symbol ] name The global override name.
     #
-    # @since 3.0.0
+    # @return [ String | Symbol ] The override.
     def client_override=(name)
       Thread.current[CLIENT_OVERRIDE_KEY] = name
     end
@@ -224,8 +201,6 @@ module Mongoid
     # @param [ Klass ] klass The class type of the scope.
     #
     # @return [ Criteria ] The scope.
-    #
-    # @since 5.0.0
     def current_scope(klass = nil)
       if klass && Thread.current[CURRENT_SCOPE_KEY].respond_to?(:keys)
         Thread.current[CURRENT_SCOPE_KEY][
@@ -244,8 +219,6 @@ module Mongoid
     # @param [ Criteria ] scope The current scope.
     #
     # @return [ Criteria ] The scope.
-    #
-    # @since 5.0.0
     def current_scope=(scope)
       Thread.current[CURRENT_SCOPE_KEY] = scope
     end
@@ -259,14 +232,9 @@ module Mongoid
     # @param [ Class ] klass The current model class.
     #
     # @return [ Criteria ] The scope.
-    #
-    # @since 5.0.1
     def set_current_scope(scope, klass)
       if scope.nil?
-        if Thread.current[CURRENT_SCOPE_KEY]
-          Thread.current[CURRENT_SCOPE_KEY].delete(klass)
-          Thread.current[CURRENT_SCOPE_KEY] = nil if Thread.current[CURRENT_SCOPE_KEY].empty?
-        end
+        unset_current_scope(klass)
       else
         Thread.current[CURRENT_SCOPE_KEY] ||= {}
         Thread.current[CURRENT_SCOPE_KEY][klass] = scope
@@ -292,9 +260,7 @@ module Mongoid
     #
     # @param [ Document ] document The document to check.
     #
-    # @return [ true, false ] If the document is autosaved.
-    #
-    # @since 2.1.9
+    # @return [ true | false ] If the document is autosaved.
     def autosaved?(document)
       autosaves_for(document.class).include?(document._id)
     end
@@ -306,9 +272,7 @@ module Mongoid
     #
     # @param [ Document ] document The document to check.
     #
-    # @return [ true, false ] If the document is validated.
-    #
-    # @since 2.1.9
+    # @return [ true | false ] If the document is validated.
     def validated?(document)
       validations_for(document.class).include?(document._id)
     end
@@ -319,8 +283,6 @@ module Mongoid
     #   Threaded.autosaves
     #
     # @return [ Hash ] The current autosaves.
-    #
-    # @since 3.0.0
     def autosaves
       Thread.current[AUTOSAVES_KEY] ||= {}
     end
@@ -331,8 +293,6 @@ module Mongoid
     #   Threaded.validations
     #
     # @return [ Hash ] The current validations.
-    #
-    # @since 2.1.9
     def validations
       Thread.current[VALIDATIONS_KEY] ||= {}
     end
@@ -345,11 +305,10 @@ module Mongoid
     # @param [ Class ] klass The class to check.
     #
     # @return [ Array ] The current autosaves.
-    #
-    # @since 3.0.0
     def autosaves_for(klass)
       autosaves[klass] ||= []
     end
+
     # Get all validations on the current thread for the class.
     #
     # @example Get all validations.
@@ -358,48 +317,128 @@ module Mongoid
     # @param [ Class ] klass The class to check.
     #
     # @return [ Array ] The current validations.
-    #
-    # @since 2.1.9
     def validations_for(klass)
       validations[klass] ||= []
     end
 
-    # Cache a session for this thread.
+    # Cache a session for this thread for a client.
     #
-    # @example Save a session for this thread.
-    #   Threaded.set_session(session)
+    # @note For backward compatibility it is allowed to call this method without
+    # specifying `client` parameter.
     #
     # @param [ Mongo::Session ] session The session to save.
-    #
-    # @since 6.4.0
-    def set_session(session)
-      Thread.current[:session] = session
+    # @param [ Mongo::Client | nil ] client The client to cache the session for.
+    def set_session(session, client: nil)
+      sessions[client] = session
     end
 
-    # Get the cached session for this thread.
+    # Get the cached session for this thread for a client.
     #
-    # @example Get the session for this thread.
-    #   Threaded.get_session
+    # @note For backward compatibility it is allowed to call this method without
+    # specifying `client` parameter.
     #
-    # @return [ Mongo::Session, nil ] The session cached on this thread or nil.
+    # @param [ Mongo::Client | nil ] client The client to cache the session for.
     #
-    # @since 6.4.0
-    def get_session
-      Thread.current[:session]
+    # @return [ Mongo::Session | nil ] The session cached on this thread or nil.
+    def get_session(client: nil)
+      sessions[client]
     end
 
-    # Clear the cached session for this thread.
+    # Clear the cached session for this thread for a client.
     #
-    # @example Clear this thread's session.
-    #   Threaded.clear_session
+    # @note For backward compatibility it is allowed to call this method without
+    # specifying `client` parameter.
+    #
+    # @param [ Mongo::Client | nil ] client The client to clear the session for.
     #
     # @return [ nil ]
+    def clear_session(client: nil)
+      sessions.delete(client)&.end_session
+    end
+
+    # Store a reference to the document that was modified inside a transaction
+    # associated with the session.
+    #
+    # @param [ Mongo::Session ] session Session in scope of which the document
+    #   was modified.
+    # @param [ Mongoid::Document ] document Mongoid document that was modified.
+    def add_modified_document(session, document)
+      return unless session&.in_transaction?
+
+      modified_documents[session] << document
+    end
+
+    # Clears the set of modified documents for the given session, and return the
+    # content of the set before the clearance.
+    # @param [ Mongo::Session ] session Session for which the modified documents
+    #   set should be cleared.
+    #
+    # @return [ Set<Mongoid::Document> ] Collection of modified documents before
+    #   it was cleared.
+    def clear_modified_documents(session)
+      modified_documents[session].dup
+    ensure
+      modified_documents[session].clear
+    end
+
+    # Queries whether document callbacks should be executed by default for the
+    # current thread.
+    #
+    # Unless otherwise indicated (by #execute_callbacks=), this will return
+    # true.
+    #
+    # @return [ true | false ] Whether or not document callbacks should be
+    #   executed by default.
+    def execute_callbacks?
+      if Thread.current.key?(EXECUTE_CALLBACKS)
+        Thread.current[EXECUTE_CALLBACKS]
+      else
+        true
+      end
+    end
+
+    # Indicates whether document callbacks should be invoked by default for
+    # the current thread. Individual documents may further override the
+    # callback behavior, but this will be used for the default behavior.
     #
-    # @since 6.4.0
-    def clear_session
-      session = get_session
-      session.end_session if session
-      Thread.current[:session] = nil
+    # @param flag [ true | false ] Whether or not document callbacks should be
+    #   executed by default.
+    def execute_callbacks=(flag)
+      Thread.current[EXECUTE_CALLBACKS] = flag
+    end
+
+    # Returns the thread store of sessions.
+    #
+    # @return [ Hash<Integer, Set> ] The sessions indexed by client object ID.
+    #
+    # @api private
+    def sessions
+      Thread.current[SESSIONS_KEY] ||= {}.compare_by_identity
+    end
+
+    # Returns the thread store of modified documents.
+    #
+    # @return [ Hash<Mongo::Session, Set<Mongoid::Document>> ] The modified
+    #   documents indexed by session.
+    #
+    # @api private
+    def modified_documents
+      Thread.current[MODIFIED_DOCUMENTS_KEY] ||= Hash.new do |h, k|
+        h[k] = Set.new
+      end
+    end
+
+    private
+
+    # Removes the given klass from the current scope, and tidies the current
+    # scope list.
+    #
+    # @param klass [ Class ] the class to remove from the current scope.
+    def unset_current_scope(klass)
+      return unless Thread.current[CURRENT_SCOPE_KEY]
+
+      Thread.current[CURRENT_SCOPE_KEY].delete(klass)
+      Thread.current[CURRENT_SCOPE_KEY] = nil if Thread.current[CURRENT_SCOPE_KEY].empty?
     end
   end
 end

data/lib/mongoid/timestamps/created/short.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Timestamps