mongoid 7.2.1 → 9.0.0

data/lib/mongoid/clients/options.rb

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Clients
+
+    # Mixin module included into Mongoid::Document which gives
+    # the ability to manage the database context for persistence
+    # and query operations. For example, this includes saving
+    # documents to different collections, and reading documents
+    # from secondary instances.
     module Options
       extend ActiveSupport::Concern
 
@@ -13,14 +19,12 @@ module Mongoid
       #     m.save
       #   end
       #
-      # @param [ Hash, Mongoid::PersistenceContext ] options_or_context
+      # @param [ Hash | Mongoid::PersistenceContext ] options_or_context
       #   The storage options or a persistence context.
       #
       # @option options [ String | Symbol ] :collection The collection name.
       # @option options [ String | Symbol ] :database The database name.
       # @option options [ String | Symbol ] :client The client name.
-      #
-      # @since 6.0.0
       def with(options_or_context, &block)
         original_context = PersistenceContext.get(self)
         original_cluster = persistence_context.cluster
@@ -30,22 +34,80 @@ module Mongoid
         clear_persistence_context(original_cluster, original_context)
       end
 
+      # Get the collection for the document's current persistence context.
+      #
+      # @example Get the collection for the current persistence context.
+      #   document.collection
+      #
+      # @param [ Object ] parent The parent object whose collection name is used
+      #   instead of the current persistence context's collection name.
+      #
+      # @return [ Mongo::Collection ] The collection for the current persistence
+      #   context.
       def collection(parent = nil)
         persistence_context.collection(parent)
       end
 
+      # Get the collection name for the document's current persistence context.
+      #
+      # @example Get the collection name for the current persistence context.
+      #   document.collection_name
+      #
+      # @return [ String ] The collection name for the current persistence
+      #   context.
       def collection_name
         persistence_context.collection_name
       end
 
+      # Get the database client for the document's current persistence context.
+      #
+      # @example Get the client for the current persistence context.
+      #   document.mongo_client
+      #
+      # @return [ Mongo::Client ] The client for the current persistence
+      #   context.
       def mongo_client
         persistence_context.client
       end
 
+      # Get the document's current persistence context.
+      #
+      # @note For embedded documents, the persistence context of the
+      #   root parent document is returned.
+      #
+      # @example Get the current persistence context.
+      #   document.persistence_context
+      #
+      # @return [ Mongoid::PersistenceContext ] The current persistence
+      #   context.
       def persistence_context
-        PersistenceContext.get(self) ||
+        if embedded? && !_root?
+          _root.persistence_context
+        else
+          PersistenceContext.get(self) ||
             PersistenceContext.get(self.class) ||
-            PersistenceContext.new(self.class)
+            PersistenceContext.new(self.class, storage_options)
+        end
+      end
+
+      # Returns whether a persistence context is set for the document
+      # or the document's class.
+      #
+      # @note For embedded documents, the persistence context of the
+      #   root parent document is used.
+      #
+      # @example Get the current persistence context.
+      #   document.persistence_context?
+      #
+      # @return [ true | false ] Whether a persistence context is set.
+      def persistence_context?
+        if embedded? && !_root?
+          _root.persistence_context?
+        else
+          remembered_storage_options&.any? ||
+            PersistenceContext.get(self).present? ||
+            PersistenceContext.get(self.class).present?
+        end
       end
 
       private
@@ -60,22 +122,62 @@ module Mongoid
 
       module ClassMethods
 
+        # Get the database client name for the current persistence context
+        # of the document class.
+        #
+        # @example Get the client name for the current persistence context.
+        #   Model.client_name
+        #
+        # @return [ String ] The database client name for the current
+        #   persistence context.
         def client_name
           persistence_context.client_name
         end
 
+        # Get the collection name for the current persistence context of the
+        # document class.
+        #
+        # @example Get the collection name for the current persistence context.
+        #   Model.collection_name
+        #
+        # @return [ String ] The collection name for the current persistence
+        #   context.
         def collection_name
           persistence_context.collection_name
         end
 
+        # Get the database name for the current persistence context of the
+        # document class.
+        #
+        # @example Get the database name for the current persistence context.
+        #   Model.database_name
+        #
+        # @return [ String ] The database name for the current persistence
+        #   context.
         def database_name
           persistence_context.database_name
         end
 
+        # Get the collection for the current persistence context of the
+        # document class.
+        #
+        # @example Get the collection for the current persistence context.
+        #   Model.collection
+        #
+        # @return [ Mongo::Collection ] The collection for the current
+        #   persistence context.
         def collection
           persistence_context.collection
         end
 
+        # Get the client for the current persistence context of the
+        # document class.
+        #
+        # @example Get the client for the current persistence context.
+        #   Model.mongo_client
+        #
+        # @return [ Mongo::Client ] The client for the current persistence
+        #   context.
         def mongo_client
           persistence_context.client
         end
@@ -92,8 +194,6 @@ module Mongoid
         # @option options [ String | Symbol ] :collection The collection name.
         # @option options [ String | Symbol ] :database The database name.
         # @option options [ String | Symbol ] :client The client name.
-        #
-        # @since 6.0.0
         def with(options, &block)
           original_context = PersistenceContext.get(self)
           original_cluster = persistence_context.cluster
@@ -103,6 +203,15 @@ module Mongoid
           PersistenceContext.clear(self, original_cluster, original_context)
         end
 
+        # Get the current persistence context of the document class.
+        # If a persistence context is not set, a new one will be
+        # initialized and returned.
+        #
+        # @example Get the current persistence context.
+        #   Model.persistence_context
+        #
+        # @return [ Mongoid::PersistenceContent ] The current persistence
+        #   context.
         def persistence_context
           PersistenceContext.get(self) || PersistenceContext.new(self)
         end

data/lib/mongoid/clients/sessions.rb

@@ -1,75 +1,25 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# 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.
-    #
-    # @since 6.4.0
+    # 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.
-      #
-      # @since 6.4.0
-      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
-          # Driver 2.13.0+
-          defined?(Mongo::Error::SessionsNotSupported) &&
-            Mongo::Error::SessionsNotSupported === ex ||
-          # Legacy drivers
-          ex.message == Mongo::Session::SESSIONS_NOT_SUPPORTED
-        then
-          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.
@@ -83,48 +33,260 @@ 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.
         #
         # @return [ Object ] The result of calling the block.
         #
         # @yieldparam [ Mongo::Session ] The session being used for the block.
-        #
-        # @since 6.4.0
         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
-            # Driver 2.13.0+
-            defined?(Mongo::Error::SessionsNotSupported) &&
-              Mongo::Error::SessionsNotSupported === ex ||
-            # Legacy drivers
-            ex.message == Mongo::Session::SESSIONS_NOT_SUPPORTED
-          then
-            raise Mongoid::Errors::InvalidSessionUse.new(:sessions_not_supported)
+          if Mongo::Error::SessionsNotSupported === ex
+            raise Mongoid::Errors::SessionsNotSupported.new
+          else
+            raise ex
           end
-          raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_use)
+        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
+        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,16 +1,48 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# 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_accessor: false, default: storage_options_defaults
+      end
 
-        cattr_accessor :storage_options, instance_writer: false do
-          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
@@ -48,19 +80,15 @@ module Mongoid
         # @option options [ String | Symbol ] :client The client name.
         #
         # @return [ Class ] The model class.
-        #
-        # @since 3.0.0
         def store_in(options)
           Validators::Storage.validate(self, options)
-          storage_options.merge!(options)
+          self.storage_options = self.storage_options.merge(options)
         end
 
         # Reset the store_in options
         #
         # @example Reset the store_in options
         #   Model.reset_storage_options!
-        #
-        # @since 4.0.0
         def reset_storage_options!
           self.storage_options = storage_options_defaults.dup
           PersistenceContext.clear(self)
@@ -72,8 +100,6 @@ module Mongoid
         #   Model.storage_options_defaults
         #
         # @return [ Hash ] Default storage options.
-        #
-        # @since 4.0.0
         def storage_options_defaults
           {
             collection: name.collectionize.to_sym,