MONGOID-5530 Add transaction method (#5508)

Author: comandeo-mongo

lib/config/locales/en.yml

@@ -357,9 +357,9 @@ en:
             in the session block share the same driver client. For example, a model may have a different
             client specified in its 'store_in' options.\n\n"
         invalid_session_nesting:
-          message: "A session was started while another session was being used."
-          summary: "Sessions cannot be nested. Only one session can be used in a thread at once."
-          resolution: "Only use one session at a time; sessions cannot be nested."
+          message: "A session was started while another session was being used on this client."
+          summary: "Sessions cannot be nested. Only one session can be used in a thread per client."
+          resolution: "Only use one session per client at a time; sessions cannot be nested."
         invalid_storage_options:
           message: "Invalid options passed to %{klass}.store_in: %{options}."
           summary: "The :store_in macro takes only a hash of parameters with
@@ -381,6 +381,10 @@ en:
             for Date, DateTime, and Time objects. When this is a String it needs
             to be valid for Time.parse. Other objects must be valid to pass to
             Time.local."
+        invalid_transaction_nesting:
+          message: "A transaction was started while another transaction was being used on this client."
+          summary: "Transactions cannot be nested. Only one transaction can be used in a thread per client."
+          resolution: "Only use one transaction per client at a time; transactions cannot be nested."
         inverse_not_found:
           message: "When adding a(n) %{klass} to %{base}#%{name}, Mongoid could
             not determine the inverse foreign key to set. The attempted key was
@@ -617,6 +621,19 @@ en:
             accepts_nested_attributes_for :%{association}, limit: %{limit}.
             Consider raising this limit or making sure no more are sent than
             the set value."
+        transactions_not_supported:
+          message: "Transactions are not supported by the connected server(s)."
+          summary: "A session was attempted to be used with a MongoDB server version
+            that doesn't support transactions. Transactions are supported in MongoDB
+            server versions 3.6 and higher."
+          resolution: "Verify that all servers in your deployment are at least
+            version 3.6 or don't attempt to use transactions with older server versions."
+        transaction_error:
+          message: "Transaction failed with the following error: %{error}."
+          summary: "The transaction failed because MongoDB server or MongoDB driver
+            raised an unexpected error."
+          resolution: "Consult with Ruby driver documentation
+            and MongoDB documentation."
         unknown_attribute:
           message: "Attempted to set a value for '%{name}' which is not
             allowed on the model %{klass}."

lib/mongoid/clients/options.rb

@@ -40,13 +40,21 @@ def mongo_client
       end
 
       def persistence_context
-        PersistenceContext.get(self) ||
-            PersistenceContext.get(self.class) ||
-            PersistenceContext.new(self.class)
+        if embedded? && !_root?
+          _root.persistence_context
+        else
+          PersistenceContext.get(self) ||
+              PersistenceContext.get(self.class) ||
+              PersistenceContext.new(self.class)
+        end
       end
 
       def persistence_context?
-        !!(PersistenceContext.get(self) || PersistenceContext.get(self.class))
+        if embedded? && !_root?
+          _root.persistence_context?
+        else
+          !!(PersistenceContext.get(self) || PersistenceContext.get(self.class))
+        end
       end
 
       private

lib/mongoid/clients/sessions.rb

@@ -3,58 +3,11 @@
 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.
-      #
-      # @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
+      def self.included(base)
+        base.include(ClassMethods)
       end
 
       module ClassMethods
@@ -72,40 +25,83 @@ module ClassMethods
         # @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.
         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/)
+          then
+            raise Mongoid::Errors::TransactionsNotSupported.new
+          else
+            raise ex
           end
-          raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_use)
         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
+              session.commit_transaction
+            rescue Mongoid::Errors::Rollback
+              session.abort_transaction
+            rescue Mongoid::Errors::InvalidSessionNesting
+              # Session should be ended here.
+              raise Mongoid::Errors::InvalidTransactionNesting.new
+            rescue Mongo::Error::InvalidSession, Mongo::Error::InvalidTransactionOperation => e
+              session.abort_transaction
+              raise Mongoid::Errors::TransactionError(e)
+            rescue StandardError => e
+              session.abort_transaction
+              raise e
+            end
+          end
         end
 
         private
 
         def _session
-          Threaded.get_session
+          Threaded.get_session(client: persistence_context.client)
         end
       end
     end

lib/mongoid/errors.rb

@@ -37,10 +37,11 @@
 require "mongoid/errors/invalid_relation"
 require "mongoid/errors/invalid_relation_option"
 require "mongoid/errors/invalid_scope"
-require "mongoid/errors/invalid_session_use"
+require "mongoid/errors/invalid_session_nesting"
 require "mongoid/errors/invalid_set_polymorphic_relation"
 require "mongoid/errors/invalid_storage_options"
 require "mongoid/errors/invalid_time"
+require "mongoid/errors/invalid_transaction_nesting"
 require "mongoid/errors/inverse_not_found"
 require "mongoid/errors/mixed_relations"
 require "mongoid/errors/mixed_client_configuration"
@@ -56,8 +57,12 @@
 require "mongoid/errors/no_client_hosts"
 require "mongoid/errors/readonly_attribute"
 require "mongoid/errors/readonly_document"
+require "mongoid/errors/rollback"
+require "mongoid/errors/sessions_not_supported"
 require "mongoid/errors/scope_overwrite"
 require "mongoid/errors/too_many_nested_attribute_records"
+require "mongoid/errors/transaction_error"
+require "mongoid/errors/transactions_not_supported"
 require "mongoid/errors/unknown_attribute"
 require "mongoid/errors/unknown_model"
 require "mongoid/errors/unsaved_document"

lib/mongoid/errors/invalid_session_nesting.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when a session is attempted to be used with a model whose client already
+    # has an opened session.
+    class InvalidSessionNesting < MongoidError
+
+      # Create the error.
+      def initialize
+        super(compose_message('invalid_session_nesting'))
+      end
+    end
+  end
+end

lib/mongoid/errors/invalid_session_use.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when a transaction is attempted to be used with a model whose client already
+    # has an opened transaction.
+    class InvalidTransactionNesting < MongoidError
+
+      # Create the error.
+      def initialize
+        super(compose_message('invalid_transaction_nesting'))
+      end
+    end
+  end
+end

lib/mongoid/errors/invalid_transaction_nesting.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error should be raised to deliberately rollback a transaction without
+    # passing on an exception.
+    # Normally, raising an exception inside a Mongoid transaction causes rolling
+    # the MongoDB transaction back, and the exception is passed on.
+    # If Mongoid::Error::Rollback exception is raised, then the MongoDB
+    # transaction will be rolled back, without passing on the exception.
+    class Rollback < MongoidError; end
+  end
+end

lib/mongoid/errors/rollback.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when a session is attempted to be used with a model whose client cannot use it since
+    # the mongodb deployment doesn't support sessions.
+    class SessionsNotSupported < MongoidError
+
+      # Create the error.
+      def initialize
+        super('sessions_not_supported')
+      end
+    end
+  end
+end

lib/mongoid/errors/sessions_not_supported.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    class TransactionError < MongoidError
+
+      # This error is raised when a transaction failed because of an unexpected
+      # error.
+      #
+      # @param [ StandardError ] error Error that caused the transaction failure.
+      def initialize(error)
+        super(
+          compose_message(
+            'transaction_error',
+            { error: "#{error.class}: #{error.message}" }
+          )
+        )
+      end
+    end
+  end
+end