mongoid 8.1.9 → 9.0.0

data/lib/mongoid/clients/sessions.rb

@@ -1,64 +1,25 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Clients
 
-    # Encapsulates behavior for getting a session from the client of a model class or instance,
-    # setting the session on the current thread, and yielding to a block.
-    # The session will be closed after the block completes or raises an error.
+    # Encapsulates behavior for using sessions and transactions.
     module Sessions
 
-      # Execute a block within the context of a session.
+      # Add class method mixin functionality.
       #
-      # @example Execute some operations in the context of a session.
-      #   band.with_session(causal_consistency: true) do
-      #     band.records << Record.create
-      #     band.name = 'FKA Twigs'
-      #     band.save
-      #     band.reload
-      #   end
-      #
-      # @param [ Hash ] options The session options. Please see the driver
-      #   documentation for the available session options.
-      #
-      # @note You cannot do any operations in the block using models or objects
-      #   that use a different client; the block will execute all operations
-      #   in the context of the implicit session and operations on any models using
-      #   another client will fail. For example, if you set a client using store_in on a
-      #   particular model and execute an operation on it in the session context block,
-      #   that operation can't use the block's session and an error will be raised.
-      #   An error will also be raised if sessions are nested.
-      #
-      # @raise [ Errors::InvalidSessionUse ] If an operation is attempted on a model using another
-      #   client from which the session was started or if sessions are nested.
-      #
-      # @return [ Object ] The result of calling the block.
-      #
-      # @yieldparam [ Mongo::Session ] The session being used for the block.
-      def with_session(options = {})
-        if Threaded.get_session
-          raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_nesting)
-        end
-        session = persistence_context.client.start_session(options)
-        Threaded.set_session(session)
-        yield(session)
-      rescue Mongo::Error::InvalidSession => ex
-        if Mongo::Error::SessionsNotSupported === ex
-          raise Mongoid::Errors::InvalidSessionUse.new(:sessions_not_supported)
-        end
-        raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_use)
-      ensure
-        Threaded.clear_session
-      end
-
-      private
-
-      def _session
-        Threaded.get_session
+      # @todo Replace with ActiveSupport::Concern
+      def self.included(base)
+        base.include(ClassMethods)
       end
 
       module ClassMethods
 
+        # Actions that can be used to trigger transactional callbacks.
+        # @api private
+        CALLBACK_ACTIONS = [:create, :destroy, :update]
+
         # Execute a block within the context of a session.
         #
         # @example Execute some operations in the context of a session.
@@ -72,14 +33,6 @@ module Mongoid
         # @param [ Hash ] options The session options. Please see the driver
         #   documentation for the available session options.
         #
-        # @note You cannot do any operations in the block using models or objects
-        #   that use a different client; the block will execute all operations
-        #   in the context of the implicit session and operations on any models using
-        #   another client will fail. For example, if you set a client using store_in on a
-        #   particular model and execute an operation on it in the session context block,
-        #   that operation can't use the block's session and an error will be raised.
-        #   You also cannot nest sessions.
-        #
         # @raise [ Errors::InvalidSessionUse ] If an operation is attempted on a model using another
         #   client from which the session was started or if sessions are nested.
         #
@@ -87,25 +40,253 @@ module Mongoid
         #
         # @yieldparam [ Mongo::Session ] The session being used for the block.
         def with_session(options = {})
-          if Threaded.get_session
-            raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_nesting)
+          if Threaded.get_session(client: persistence_context.client)
+            raise Mongoid::Errors::InvalidSessionNesting.new
           end
           session = persistence_context.client.start_session(options)
-          Threaded.set_session(session)
+          Threaded.set_session(session, client: persistence_context.client)
           yield(session)
         rescue Mongo::Error::InvalidSession => ex
           if Mongo::Error::SessionsNotSupported === ex
-            raise Mongoid::Errors::InvalidSessionUse.new(:sessions_not_supported)
+            raise Mongoid::Errors::SessionsNotSupported.new
+          else
+            raise ex
+          end
+        rescue Mongo::Error::OperationFailure => ex
+          if (ex.code == 40415 && ex.server_message =~ /startTransaction/) ||
+             (ex.code == 20 && ex.server_message =~ /Transaction/)
+            raise Mongoid::Errors::TransactionsNotSupported.new
+          else
+            raise ex
           end
-          raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_use)
+        rescue *transactions_not_supported_exceptions
+          raise Mongoid::Errors::TransactionsNotSupported
         ensure
-          Threaded.clear_session
+          Threaded.clear_session(client: persistence_context.client)
+        end
+
+        # Executes a block within the context of a transaction.
+        #
+        # If the block does not raise an error, the transaction is committed.
+        # If an error is raised, the transaction is aborted. The error is passed on
+        # except for the `Mongoid::Errors::Rollback`. This error is not passed on,
+        # so you can raise is if you want to deliberately rollback the transaction.
+        #
+        # @param [ Hash ] options The transaction options. Please see the driver
+        #   documentation for the available session options.
+        # @param [ Hash ] session_options The session options. A MongoDB
+        #   transaction must be started inside a session, therefore a session will
+        #   be started. Please see the driver documentation for the available session options.
+        #
+        # @raise [ Mongoid::Errors::InvalidTransactionNesting ] If the transaction is
+        #   opened on a client that already has an open transaction.
+        # @raise [ Mongoid::Errors::TransactionsNotSupported ] If MongoDB deployment
+        #   the client is connected to does not support transactions.
+        # @raise [ Mongoid::Errors::TransactionError ] If there is an error raised
+        #   by MongoDB deployment or MongoDB driver.
+        #
+        # @yield Provided block will be executed inside a transaction.
+        def transaction(options = {}, session_options: {})
+          with_session(session_options) do |session|
+            begin
+              session.start_transaction(options)
+              yield
+              commit_transaction(session)
+            rescue *transactions_not_supported_exceptions
+              raise Mongoid::Errors::TransactionsNotSupported
+            rescue Mongoid::Errors::Rollback
+              abort_transaction(session)
+            rescue Mongoid::Errors::InvalidSessionNesting
+              # Session should be ended here.
+              raise Mongoid::Errors::InvalidTransactionNesting.new
+            rescue Mongo::Error::InvalidSession, Mongo::Error::InvalidTransactionOperation => e
+              abort_transaction(session)
+              raise Mongoid::Errors::TransactionError(e)
+            rescue StandardError => e
+              abort_transaction(session)
+              raise e
+            end
+          end
+        end
+
+        # Sets up a callback is called after a commit of a transaction.
+        # The callback is called only if the document is created, updated, or destroyed
+        # in the transaction.
+        #
+        # See +ActiveSupport::Callbacks::ClassMethods::set_callback+ for more
+        # information about method parameters and possible options.
+        def after_commit(*args, &block)
+          set_options_for_callbacks!(args)
+          set_callback(:commit, :after, *args, &block)
+        end
+
+        # Shortcut for +after_commit :hook, on: [ :create, :update ]+
+        def after_save_commit(*args, &block)
+          set_options_for_callbacks!(args, on: [ :create, :update ])
+          set_callback(:commit, :after, *args, &block)
+        end
+
+        # Shortcut for +after_commit :hook, on: :create+.
+        def after_create_commit(*args, &block)
+          set_options_for_callbacks!(args, on: :create)
+          set_callback(:commit, :after, *args, &block)
+        end
+
+        # Shortcut for +after_commit :hook, on: :update+.
+        def after_update_commit(*args, &block)
+          set_options_for_callbacks!(args, on: :update)
+          set_callback(:commit, :after, *args, &block)
+        end
+
+        # Shortcut for +after_commit :hook, on: :destroy+.
+        def after_destroy_commit(*args, &block)
+          set_options_for_callbacks!(args, on: :destroy)
+          set_callback(:commit, :after, *args, &block)
+        end
+
+        # This callback is called after a create, update, or destroy are rolled back.
+        #
+        # Please check the documentation of +after_commit+ for options.
+        def after_rollback(*args, &block)
+          set_options_for_callbacks!(args)
+          set_callback(:rollback, :after, *args, &block)
         end
 
         private
 
+        # Driver version 2.20 introduced a new exception for reporting that
+        # transactions are not supported. Prior to that, the condition was
+        # discovered by the rescue clause falling through to a different
+        # exception.
+        #
+        # This method ensures that Mongoid continues to work with older driver
+        # versions, by only returning the new exception.
+        #
+        # Once support is removed for all versions prior to 2.20.0, we can
+        # replace this method.
+        def transactions_not_supported_exceptions
+          return nil unless defined? Mongo::Error::TransactionsNotSupported
+
+          Mongo::Error::TransactionsNotSupported
+        end
+
+        # @return [ Mongo::Session ] Session for the current client.
         def _session
-          Threaded.get_session
+          Threaded.get_session(client: persistence_context.client)
+        end
+
+        # This method should be used to detect whether a persistence operation
+        # is executed inside transaction or not.
+        #
+        # Currently this method is used to detect when +after_commit+ callbacks
+        # should be triggered. If we introduce implicit transactions and
+        # therefore do not need to handle two different ways of triggering callbacks,
+        # we may want to remove this method.
+        #
+        # @return [ true | false ] Whether there is a session for the current
+        #   client, and there is a transaction in progress for this session.
+        def in_transaction?
+          _session&.in_transaction? || false
+        end
+
+        # Commits the active transaction on the session, and calls
+        # after_commit callbacks on modified documents.
+        #
+        # @param [ Mongo::Session ] session Session on which
+        #   a transaction is started.
+        def commit_transaction(session)
+          session.commit_transaction
+          Threaded.clear_modified_documents(session).each do |doc|
+            doc.run_after_callbacks(:commit)
+          end
+        end
+
+        # Aborts the active transaction on the session, and calls
+        # after_rollback callbacks on modified documents.
+        #
+        # @param [ Mongo::Session ] session Session on which
+        #   a transaction is started.
+        def abort_transaction(session)
+          session.abort_transaction
+          Threaded.clear_modified_documents(session).each do |doc|
+            doc.run_after_callbacks(:rollback)
+          end
+        end
+
+        # Transforms custom options for after_commit and after_rollback callbacks
+        # into options for +set_callback+.
+        def set_options_for_callbacks!(args)
+          options = args.extract_options!
+          args << options
+
+          if options[:on]
+            fire_on = Array(options[:on])
+            assert_valid_transaction_action(fire_on)
+            options[:if] = [
+              -> { transaction_include_any_action?(fire_on) },
+              *options[:if]
+            ]
+          end
+        end
+
+        # Asserts that the given actions are valid for after_commit
+        # and after_rollback callbacks.
+        #
+        # @param [ Array<Symbol> ] actions Actions to be checked.
+        # @raise [ ArgumentError ] If any of the actions is not valid.
+        def assert_valid_transaction_action(actions)
+          if (actions - CALLBACK_ACTIONS).any?
+            raise ArgumentError, ":on conditions for after_commit and after_rollback callbacks have to be one of #{CALLBACK_ACTIONS}"
+          end
+        end
+
+        def transaction_include_any_action?(actions)
+          actions.any? do |action|
+            case action
+            when :create
+              persisted? && previously_new_record?
+            when :update
+              !(previously_new_record? || destroyed?)
+            when :destroy
+              destroyed?
+            end
+          end
+        end
+      end
+
+      private
+
+      # If at least one session is active, this ensures that the
+      # current model's client is compatible with one of them.
+      #
+      # "Compatible" is defined to mean: the same client was used
+      # to open one of the active sessions.
+      #
+      # Currently emits a warning.
+      def ensure_client_compatibility!
+        # short circuit: if no sessions are active, there's nothing
+        # to check.
+        return unless Threaded.sessions.any?
+
+        # at this point, we know that at least one session is currently
+        # active. let's see if one of them was started with the model's
+        # client...
+        session = Threaded.get_session(client: persistence_context.client)
+
+        # if not, then we have a case of the programmer trying to use
+        # a model within a transaction, where the model is not itself
+        # controlled by that transaction. this is potentially a bug, so
+        # let's tell them about it.
+        if session.nil?
+          # This is hacky; we're hijacking Mongoid::Errors::MongoidError in
+          # order to get the spiffy error message translation. If we later
+          # decide to raise an error instead of just writing a message, we can
+          # subclass MongoidError and raise that exception here.
+          message = Errors::MongoidError.new.compose_message(
+            'client_session_mismatch',
+            model: self.class.name
+          )
+          logger.info(message)
         end
       end
     end

data/lib/mongoid/clients/storage_options.rb

@@ -1,12 +1,48 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Clients
+
+    # Mixin module included into Mongoid::Document which adds
+    # the ability to set the collection in which to store the
+    # document by default.
     module StorageOptions
       extend ActiveSupport::Concern
 
       included do
-        class_attribute :storage_options, instance_writer: false, default: storage_options_defaults
+        class_attribute :storage_options, instance_accessor: false, default: storage_options_defaults
+      end
+
+      # Remembers the storage options that were active when the current object
+      # was instantiated/created.
+      #
+      # @return [ Hash | nil ] the storage options that have been cached for
+      #   this object instance (or nil if no storage options have been
+      #   cached).
+      #
+      # @api private
+      attr_accessor :remembered_storage_options
+
+      # The storage options that apply to this record, consisting of both
+      # the class-level declared storage options (e.g. store_in) merged with
+      # any remembered storage options.
+      #
+      # @return [ Hash ] the storage options for the record
+      #
+      # @api private
+      def storage_options
+        self.class.storage_options.merge(remembered_storage_options || {})
+      end
+
+      # Saves the storage options from the current persistence context.
+      #
+      # @api private
+      def remember_storage_options!
+        return if Mongoid.legacy_persistence_context_behavior
+
+        opts = persistence_context.requested_storage_options
+        self.remembered_storage_options = opts if opts
       end
 
       module ClassMethods

data/lib/mongoid/clients/validators/storage.rb

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

data/lib/mongoid/clients/validators.rb

@@ -1,3 +1,4 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require "mongoid/clients/validators/storage"

data/lib/mongoid/clients.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require "mongoid/clients/factory"
 require "mongoid/clients/validators"
@@ -7,6 +8,10 @@ require "mongoid/clients/options"
 require "mongoid/clients/sessions"
 
 module Mongoid
+
+  # Mixin module included into Mongoid::Document which adds
+  # database client connection functionality. Also contains
+  # singleton class methods related to managing database clients.
   module Clients
     extend ActiveSupport::Concern
     include StorageOptions
@@ -42,12 +47,24 @@ module Mongoid
       #
       # @return [ true ] True.
       def disconnect
-        clients.values.each do |client|
-          client.close
-        end
+        clients.each_value(&:close)
+        true
       end
 
-      # Get a client with the provided name.
+      # Reconnect all active clients.
+      #
+      # @example Reconnect all active clients.
+      #   Mongoid::Clients.reconnect
+      #
+      # @return [ true ] True.
+      def reconnect
+        clients.each_value(&:reconnect)
+        true
+      end
+
+      # Get a stored client with the provided name. If no client exists
+      # with the given name, a new one will be created, stored, and
+      # returned.
       #
       # @example Get a client with the name.
       #   Mongoid::Clients.with_name(:replica)
@@ -59,14 +76,29 @@ module Mongoid
         name_as_symbol = name.to_sym
         return clients[name_as_symbol] if clients[name_as_symbol]
         CREATE_LOCK.synchronize do
+          if (key_vault_client = Mongoid.clients.dig(name_as_symbol, :options, :auto_encryption_options, :key_vault_client))
+            clients[key_vault_client.to_sym] ||= Clients::Factory.create(key_vault_client)
+          end
           clients[name_as_symbol] ||= Clients::Factory.create(name)
         end
       end
 
+      # Store a client with the provided name.
+      #
+      # @example Set a client.
+      #   Mongoid::Clients.set(:analytics, my_client)
+      #
+      # @param [ String | Symbol ] name The name of the client to set.
+      # @param [ Mongo::Client ] client The client to set.
+      #
+      # @return [ Mongo::Client ] The set client.
       def set(name, client)
         clients[name.to_sym] = client
       end
 
+      # Returns the stored clients indexed by name.
+      #
+      # @return [ Hash<Symbol, Mongo::Client> ] The index of clients.
       def clients
         @clients ||= {}
       end

data/lib/mongoid/collection_configurable.rb

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

data/lib/mongoid/composable.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require "mongoid/changeable"
 require "mongoid/collection_configurable"
+require "mongoid/encryptable"
 require "mongoid/findable"
 require "mongoid/indexable"
 require "mongoid/inspectable"
@@ -10,6 +12,7 @@ require "mongoid/matcher"
 require "mongoid/matchable"
 require "mongoid/persistable"
 require "mongoid/reloadable"
+require 'mongoid/search_indexable'
 require "mongoid/selectable"
 require "mongoid/scopable"
 require "mongoid/serializable"
@@ -48,6 +51,7 @@ module Mongoid
     include Association
     include Reloadable
     include Scopable
+    include SearchIndexable
     include Selectable
     include Serializable
     include Shardable
@@ -59,6 +63,7 @@ module Mongoid
     include Interceptable
     include Copyable
     include Equality
+    include Encryptable
 
     MODULES = [
       Atomic,

data/lib/mongoid/config/defaults.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Config
@@ -10,51 +11,30 @@ module Mongoid
       # Note that this method will load the *new* functionality introduced in
       # the given Mongoid version.
       #
-      # @param [ String | Float ] The version number as X.y.
+      # @param [ String | Float ] version The version number as X.y.
       #
       # raises [ ArgumentError ] if an invalid version is given.
       def load_defaults(version)
-        # Note that for 7.x, since all of the feature flag defaults have been
-        # flipped to the new functionality, all of the settings for those
-        # versions are to give old functionality. Because of this, it is
-        # possible to recurse to later version to get all of the options to
-        # turn off. Note that this won't be true when adding feature flags to
-        # 9.x, since the default will be the old functionality until the next
-        # major version is released. More likely, the recursion will have to go
-        # in the other direction (towards earlier versions).
-
         case version.to_s
-        when "7.3"
-          # flags introduced in 7.4 - old functionality
-          self.broken_aggregables = true
-          self.broken_alias_handling = true
-          self.broken_and = true
-          self.broken_scoping = true
-          self.broken_updates = true
-          self.compare_time_by_ms = false
-          self.legacy_pluck_distinct = true
-          self.legacy_triple_equals = true
-          self.object_id_as_json_oid = true
-
-          load_defaults "7.4"
-        when "7.4"
-          # flags introduced in 7.5 - old functionality
-          self.legacy_attributes = true
-          self.overwrite_chained_operators = true
-
-          load_defaults "7.5"
-        when "7.5"
-          # flags introduced in 8.0 - old functionality
-          self.map_big_decimal_to_decimal128 = false
+        when /^[0-7]\./
+          raise ArgumentError, "Version no longer supported: #{version}"
         when "8.0"
-          # All flag defaults currently reflect 8.0 behavior.
+          self.legacy_readonly = true
+
+          load_defaults "8.1"
         when "8.1"
-          # flags introduced in 8.1 - new functionality
-          self.legacy_readonly = false
+          self.immutable_ids = false
+          self.legacy_persistence_context_behavior = true
+          self.around_callbacks_for_embeds = true
+          self.prevent_multiple_calls_of_embedded_callbacks = false
+
+          load_defaults "9.0"
+        when "9.0"
+          # All flag defaults currently reflect 9.0 behavior.
         else
           raise ArgumentError, "Unknown version: #{version}"
         end
       end
     end
   end
-end
+end