mongo 2.5.3 → 2.6.0

data/lib/mongo/protocol/update.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/retryable.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2015 MongoDB, Inc.
+# Copyright (C) 2015-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -30,6 +30,7 @@ module Mongo
     #
     # @note This only retries read operations on socket errors.
     #
+    # @param [ Mongo::Session ] session The session that the operation is being run on.
     # @param [ Proc ] block The block to execute.
     #
     # @yieldparam [ Server ] server The server to which the write should be sent.
@@ -37,18 +38,18 @@ module Mongo
     # @return [ Result ] The result of the operation.
     #
     # @since 2.1.0
-    def read_with_retry
+    def read_with_retry(session = nil)
       attempt = 0
       begin
         attempt += 1
         yield
       rescue Error::SocketError, Error::SocketTimeoutError => e
-        raise(e) if attempt > cluster.max_read_retries
+        raise(e) if attempt > cluster.max_read_retries || (session && session.in_transaction?)
         log_retry(e)
         cluster.scan!
         retry
       rescue Error::OperationFailure => e
-        if cluster.sharded? && e.retryable?
+        if cluster.sharded? && e.retryable? && !(session && session.in_transaction?)
           raise(e) if attempt > cluster.max_read_retries
           log_retry(e)
           sleep(cluster.read_retry_interval)
@@ -93,28 +94,32 @@ module Mongo
     # @note This only retries operations on not master failures, since it is
     #   the only case we can be sure a partial write did not already occur.
     #
+    # @param [ true | false ] ending_transaction True if the write operation is abortTransaction or
+    #   commitTransaction, false otherwise.
     # @param [ Proc ] block The block to execute.
     #
     # @return [ Result ] The result of the operation.
     #
     # @since 2.1.0
-    def write_with_retry(session, write_concern, &block)
-      unless retry_write_allowed?(session, write_concern)
-        return legacy_write_with_retry(&block)
+    def write_with_retry(session, write_concern, ending_transaction = false, &block)
+      unless retry_write_allowed?(session, write_concern) || ending_transaction
+        return legacy_write_with_retry(nil, session, &block)
       end
 
       server = cluster.next_primary
-      unless server.retry_writes?
-        return legacy_write_with_retry(server, &block)
+
+      unless server.retry_writes? || ending_transaction
+        return legacy_write_with_retry(server, session, &block)
       end
 
       begin
-        txn_num = session.next_txn_num
+        txn_num = session.in_transaction? ? session.txn_num : session.next_txn_num
         yield(server, txn_num)
       rescue Error::SocketError, Error::SocketTimeoutError => e
+        raise e if session.in_transaction? && !ending_transaction
         retry_write(e, txn_num, &block)
       rescue Error::OperationFailure => e
-        raise e unless e.write_retryable?
+        raise e if (session.in_transaction? && !ending_transaction) || !e.write_retryable?
         retry_write(e, txn_num, &block)
       end
     end
@@ -123,7 +128,7 @@ module Mongo
 
     def retry_write_allowed?(session, write_concern)
       session && session.retry_writes? &&
-          (write_concern.nil? || write_concern.acknowledged?)
+          (write_concern.nil? || write_concern.acknowledged?) or false
     end
 
     def retry_write(original_error, txn_num, &block)
@@ -143,7 +148,10 @@ module Mongo
       raise original_error
     end
 
-    def legacy_write_with_retry(server = nil)
+    def legacy_write_with_retry(server = nil, session = nil)
+      # This is the pre-session retry logic, and is not subject to
+      # current retryable write specifications.
+      # In particular it does not retry on SocketError and SocketTimeoutError.
       attempt = 0
       begin
         attempt += 1
@@ -151,7 +159,7 @@ module Mongo
       rescue Error::OperationFailure => e
         server = nil
         raise(e) if attempt > Cluster::MAX_WRITE_RETRIES
-        if e.write_retryable?
+        if e.write_retryable? && !(session && session.in_transaction?)
           log_retry(e)
           cluster.scan!
           retry

data/lib/mongo/server.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server/connectable.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2015-2017 MongoDB, Inc.
+# Copyright (C) 2015-2018 MongoDB, Inc.
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server/connection.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -135,7 +135,7 @@ module Mongo
       # @param [ Array<Message> ] messages The messages to dispatch.
       # @param [ Integer ] operation_id The operation id to link messages.
       #
-      # @return [ Protocol::Message ] The reply if needed.
+      # @return [ Protocol::Message | nil ] The reply if needed.
       #
       # @since 2.0.0
       def dispatch(messages, operation_id = nil)
@@ -237,14 +237,26 @@ module Mongo
           min_wire_version = response[Description::MIN_WIRE_VERSION] || Description::LEGACY_WIRE_VERSION
           max_wire_version = response[Description::MAX_WIRE_VERSION] || Description::LEGACY_WIRE_VERSION
           features = Description::Features.new(min_wire_version..max_wire_version)
-          @auth_mechanism = (features.scram_sha_1_enabled? || @server.features.scram_sha_1_enabled?) ? :scram : :mongodb_cr
+
+          if response["ok"] == 1
+            @auth_mechanism = if response['saslSupportedMechs']
+                                if response['saslSupportedMechs'].include?(Mongo::Auth::SCRAM::SCRAM_SHA_256_MECHANISM)
+                                  :scram256
+                                else
+                                  :scram
+                                end
+                              elsif features.scram_sha_1_enabled? || @server.features.scram_sha_1_enabled?
+                                :scram
+                              else
+                                :mongodb_cr
+                              end
+          end
         end
       end
 
       def authenticate!
         if options[:user] || options[:auth_mech]
           user = Auth::User.new(Options::Redacted.new(:auth_mech => default_mechanism, :client_key => @client_key).merge(options))
- 
           @server.handle_auth_failure! do
             reply = Auth.get(user).login(self)
             @client_key ||= user.send(:client_key) if user.mechanism == :scram

data/lib/mongo/server/connection_pool.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server/connection_pool/queue.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server/context.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the 'License');
 # you may not use this file except in compliance with the License.

data/lib/mongo/server/description.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the 'License');
 # you may not use this file except in compliance with the License.
@@ -461,6 +461,18 @@ module Mongo
         @passives ||= (config[PASSIVES] || []).map { |s| s.downcase }
       end
 
+      # Get the address of the primary host.
+      #
+      # @example Get the address of the primary.
+      #   description.primary_host
+      #
+      # @return [ String | nil ] The address of the primary.
+      #
+      # @since 2.6.0
+      def primary_host
+        config[PRIMARY_HOST] && config[PRIMARY_HOST].downcase
+      end
+
       # Will return true if the server is a primary.
       #
       # @example Is the server a primary?
@@ -471,7 +483,7 @@ module Mongo
       # @since 2.0.0
       def primary?
         !!config[PRIMARY] &&
-          (config[PRIMARY_HOST].nil? || config[PRIMARY_HOST] == address.to_s) &&
+          (primary_host.nil? || primary_host == address.to_s) &&
             !replica_set_name.nil?
       end
 

data/lib/mongo/server/description/features.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the 'License');
 # you may not use this file except in compliance with the License.
@@ -25,6 +25,8 @@ module Mongo
         #
         # @since 2.0.0
         MAPPINGS = {
+          :transactions => 7,
+          :scram_sha_256 => 7,
           :array_filters => 6,
           :op_msg => 6,
           :sessions => 6,
@@ -53,19 +55,18 @@ module Mongo
         # The wire protocol versions that this version of the driver supports.
         #
         # @since 2.0.0
-        DRIVER_WIRE_VERSIONS = (2..6).freeze
+        DRIVER_WIRE_VERSIONS = (2..7).freeze
 
         # Create the methods for each mapping to tell if they are supported.
         #
         # @since 2.0.0
         MAPPINGS.each do |name, version|
-
-          # Determine whether or not the feature is enabled.
+          # Determine whether or not the feature is supported.
           #
           # @example Is a feature enabled?
           #   features.list_collections_enabled?
           #
-          # @return [ true, false ] If the feature is enabled.
+          # @return [ true, false ] Whether the feature is supported.
           #
           # @since 2.0.0
           define_method("#{name}_enabled?") do
@@ -91,14 +92,14 @@ module Mongo
           @address = address
         end
 
-        # Check that there is an overlap between the driver supported wire version range
-        #   and the server wire version range.
+        # Check that there is an overlap between the driver supported wire
+        #   version range and the server wire version range.
         #
         # @example Verify the wire version overlap.
         #   features.check_driver_support!
         #
-        # @raise [ Error::UnsupportedFeatures ] If the wire version range is not covered
-        #   by the driver.
+        # @raise [ Error::UnsupportedFeatures ] If the wire version range is
+        #   not covered by the driver.
         #
         # @since 2.5.1
         def check_driver_support!

data/lib/mongo/server/description/inspector.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2015 MongoDB, Inc.
+# Copyright (C) 2015-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the 'License');
 # you may not use this file except in compliance with the License.

data/lib/mongo/server/description/inspector/description_changed.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the 'License');
 # you may not use this file except in compliance with the License.

data/lib/mongo/server/description/inspector/member_discovered.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2015 MongoDB, Inc.
+# Copyright (C) 2015-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the 'License');
 # you may not use this file except in compliance with the License.

data/lib/mongo/server/description/inspector/primary_elected.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2015 MongoDB, Inc.
+# Copyright (C) 2015-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the 'License');
 # you may not use this file except in compliance with the License.

data/lib/mongo/server/description/inspector/standalone_discovered.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2015 MongoDB, Inc.
+# Copyright (C) 2015-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the 'License');
 # you may not use this file except in compliance with the License.

data/lib/mongo/server/monitor.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB Inc.
+# Copyright (C) 2014-2018 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -63,9 +63,19 @@ module Mongo
       # of the connection.
       def_delegators :connection, :compressor
 
-      # Force the monitor to immediately do a check of its server.
+      # Perform a check of the server with throttling, and update
+      # the server's description.
       #
-      # @example Force a scan.
+      # If the server was checked less than MIN_SCAN_FREQUENCY seconds
+      # ago, sleep until MIN_SCAN_FREQUENCY seconds have passed since the last
+      # check. Then perform the check which involves running isMaster
+      # on the server being monitored and updating the server description
+      # as a result.
+      #
+      # @note If the system clock is set to a time in the past, this method
+      #   can sleep for a very long time.
+      #
+      # @example Run a scan.
       #   monitor.scan!
       #
       # @return [ Description ] The updated description.
@@ -179,6 +189,8 @@ module Mongo
         end
       end
 
+      # @note If the system clock is set to a time in the past, this method
+      #   can sleep for a very long time.
       def throttle_scan_frequency!
         if @last_scan
           difference = (Time.now - @last_scan)

data/lib/mongo/server/monitor/connection.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2015 MongoDB, Inc.
+# Copyright (C) 2015-2018 MongoDB, Inc.
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server_selector.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server_selector/nearest.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server_selector/primary.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server_selector/primary_preferred.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server_selector/secondary.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server_selector/secondary_preferred.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server_selector/selectable.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2017 MongoDB, Inc.
+# Copyright (C) 2014-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -102,7 +102,12 @@ module Mongo
           servers = candidates(cluster)
           if servers && !servers.compact.empty?
             server = servers.first
-            server.check_driver_support!
+            # HACK: all servers in a topology must satisfy wire protocol
+            # constraints. There is probably a better implementation than
+            # checking all servers here
+            cluster.servers.each do |a_server|
+              a_server.check_driver_support!
+            end
             return server
           end
           cluster.scan!

data/lib/mongo/session.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2017 MongoDB, Inc.
+# Copyright (C) 2017-2018 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -23,6 +23,7 @@ module Mongo
   # @since 2.5.0
   class Session
     extend Forwardable
+    include Retryable
 
     # Get the options for this session.
     #
@@ -32,7 +33,7 @@ module Mongo
     # Get the cluster through which this session was created.
     #
     # @since 2.5.1
-    attr_reader :cluster
+    attr_reader :client
 
     # The cluster time for this session.
     #
@@ -44,6 +45,11 @@ module Mongo
     # @since 2.5.0
     attr_reader :operation_time
 
+    # The options for the transaction currently being executed on the session.
+    #
+    # @since 2.6.0
+    attr_reader :txn_options
+
     # Error message indicating that the session was retrieved from a client with a different cluster than that of the
     # client through which it is currently being used.
     #
@@ -62,21 +68,62 @@ module Mongo
     # @since 2.5.0
     SESSIONS_NOT_SUPPORTED = 'Sessions are not supported by the connected servers.'.freeze
 
+    # The state of a session in which the last operation was not related to any transaction or no
+    # operations have yet occurred.
+    #
+    # @since 2.6.0
+    NO_TRANSACTION_STATE = :no_transaction
+
+    # The state of a session in which a user has initiated a transaction but no operations within
+    # the transactions have occurred yet.
+    #
+    # @since 2.6.0
+    STARTING_TRANSACTION_STATE = :starting_transaction
+
+    # The state of a session in which a transaction has been started and at least one operation has
+    # occurred, but the transaction has not yet been committed or aborted.
+    #
+    # @since 2.6.0
+    TRANSACTION_IN_PROGRESS_STATE = :transaction_in_progress
+
+    # The state of a session in which the last operation executed was a transaction commit.
+    #
+    # @since 2.6.0
+    TRANSACTION_COMMITTED_STATE = :transaction_committed
+
+    # The state of a session in which the last operation executed was a transaction abort.
+    #
+    # @since 2.6.0
+    TRANSACTION_ABORTED_STATE = :transaction_aborted
+
+    UNLABELED_WRITE_CONCERN_CODES = [
+      79,  # UnknownReplWriteConcern
+      100, # CannotSatisfyWriteConcern,
+    ].freeze
+
     # Initialize a Session.
     #
     # @example
-    #   Session.new(server_session, cluster, options)
+    #   Session.new(server_session, client, options)
     #
     # @param [ ServerSession ] server_session The server session this session is associated with.
-    # @param [ Cluster ] cluster The cluster through which this session is created.
+    # @param [ Client ] client The client through which this session is created.
     # @param [ Hash ] options The options for this session.
     #
     # @since 2.5.0
-    def initialize(server_session, cluster, options = {})
+    def initialize(server_session, client, options = {})
       @server_session = server_session
-      @cluster = cluster
+
+      # Because the read preference will need to be inserted into a command as a string, we convert
+      # it from a symbol immediately upon receiving it.
+      if options[:read_preference] && options[:read_preference][:mode]
+        options[:read_preference][:mode] = options[:read_preference][:mode].to_s
+      end
+
+      @client = client.use(:admin)
       @options = options.dup.freeze
       @cluster_time = nil
+      @state = NO_TRANSACTION_STATE
     end
 
     # Get a formatted string for use in inspection.
@@ -100,8 +147,9 @@ module Mongo
     #
     # @since 2.5.0
     def end_session
-      if !ended? && @cluster
-        @cluster.session_pool.checkin(@server_session)
+      if !ended? && @client
+        abort_transaction if within_states?(TRANSACTION_IN_PROGRESS_STATE) rescue Mongo::Error
+        @client.cluster.session_pool.checkin(@server_session)
       end
     ensure
       @server_session = nil
@@ -119,6 +167,20 @@ module Mongo
       @server_session.nil?
     end
 
+    # Add the autocommit field to a command document if applicable.
+    #
+    # @example
+    #   session.add_autocommit!(cmd)
+    #
+    # @return [ Hash, BSON::Document ] The command document.
+    #
+    # @since 2.6.0
+    def add_autocommit!(command)
+      command.tap do |c|
+        c[:autocommit] = false if in_transaction?
+      end
+    end
+
     # Add this session's id to a command document.
     #
     # @example
@@ -131,6 +193,115 @@ module Mongo
       command.merge!(lsid: session_id)
     end
 
+    # Add the startTransaction field to a command document if applicable.
+    #
+    # @example
+    #   session.add_start_transaction!(cmd)
+    #
+    # @return [ Hash, BSON::Document ] The command document.
+    #
+    # @since 2.6.0
+    def add_start_transaction!(command)
+      command.tap do |c|
+        c[:startTransaction] = true if starting_transaction?
+      end
+    end
+
+    # Add the transaction number to a command document if applicable.
+    #
+    # @example
+    #   session.add_txn_num!(cmd)
+    #
+    # @return [ Hash, BSON::Document ] The command document.
+    #
+    # @since 2.6.0
+    def add_txn_num!(command)
+      command.tap do |c|
+        c[:txnNumber] = BSON::Int64.new(@server_session.txn_num) if in_transaction?
+      end
+    end
+
+    # Add the transactions options if applicable.
+    #
+    # @example
+    #   session.add_txn_opts!(cmd)
+    #
+    # @return [ Hash, BSON::Document ] The command document.
+    #
+    # @since 2.6.0
+    def add_txn_opts!(command, read)
+      command.tap do |c|
+        # The read preference should be added for all read operations.
+        c['$readPreference'] = txn_read_pref if read && txn_read_pref
+
+        # The read concern should be added to any command that starts a transaction.
+        if starting_transaction? && txn_read_concern
+          c[:readConcern] ||= {}
+          c[:readConcern].merge!(txn_read_concern)
+        end
+
+        # We need to send the read concern level as a string rather than a symbol.
+        if c[:readConcern] && c[:readConcern][:level]
+          c[:readConcern][:level] = c[:readConcern][:level].to_s
+        end
+
+        # The write concern should be added to any abortTransaction or commitTransaction command.
+        if (c[:abortTransaction] || c[:commitTransaction]) && txn_write_concern
+          c[:writeConcern] = txn_write_concern
+        end
+
+        # A non-numeric write concern w value needs to be sent as a string rather than a symbol.
+        if c[:writeConcern] && c[:writeConcern][:w] && c[:writeConcern][:w].is_a?(Symbol)
+          c[:writeConcern][:w] = c[:writeConcern][:w].to_s
+        end
+      end
+    end
+
+    # Remove the read concern and/or write concern from the command if not applicable.
+    #
+    # @example
+    #   session.suppress_read_write_concern!(cmd)
+    #
+    # @return [ Hash, BSON::Document ] The command document.
+    #
+    # @since 2.6.0
+    def suppress_read_write_concern!(command)
+      command.tap do |c|
+        next unless in_transaction?
+
+        c.delete(:readConcern) unless starting_transaction?
+        c.delete(:writeConcern) unless c[:commitTransaction] || c[:abortTransaction]
+      end
+    end
+
+    # Ensure that the read preference of a command primary.
+    #
+    # @example
+    #   session.validate_read_pref!(command)
+    #
+    # @raise [ Mongo::Error::InvalidTransactionOperation ] If the read preference of the command is
+    # not primary.
+    #
+    # @since 2.6.0
+    def validate_read_pref!(command)
+      return unless in_transaction? && non_primary_readpref?(command)
+
+      raise Mongo::Error::InvalidTransactionOperation.new(
+        Mongo::Error::InvalidTransactionOperation::INVALID_READ_PREFERENCE)
+    end
+
+    # Update the state of the session due to a (non-commit and non-abort) operation being run.
+    #
+    # @since 2.6.0
+    def update_state!
+      case @state
+      when STARTING_TRANSACTION_STATE
+        @state = TRANSACTION_IN_PROGRESS_STATE
+      when TRANSACTION_COMMITTED_STATE, TRANSACTION_ABORTED_STATE
+        @state = NO_TRANSACTION_STATE
+      end
+    end
+
     # Validate the session.
     #
     # @example
@@ -203,7 +374,7 @@ module Mongo
         @operation_time = new_operation_time
       end
     end
-    
+
     # Will writes executed with this session be retried.
     #
     # @example Will writes be retried.
@@ -211,8 +382,8 @@ module Mongo
     #
     # @return [ true, false ] If writes will be retried.
     #
-    # @note Retryable writes are only available on server versions at least 3.6 and with
-    #   sharded clusters or replica sets.
+    # @note Retryable writes are only available on server versions at least 3.6
+    #   and with sharded clusters or replica sets.
     #
     # @since 2.5.0
     def retry_writes?
@@ -243,6 +414,18 @@ module Mongo
       @server_session.next_txn_num if @server_session
     end
 
+    # Get the current transaction number.
+    #
+    # @example Get the current transaction number.
+    #   session.txn_num
+    #
+    # @return [ Integer ] The current transaction number.
+    #
+    # @since 2.6.0
+    def txn_num
+      @server_session && @server_session.txn_num
+    end
+
     # Is this session an implicit one (not user-created).
     #
     # @example Is the session implicit?
@@ -267,8 +450,202 @@ module Mongo
       @explicit ||= !implicit?
     end
 
+    # Start a new transaction.
+    #
+    # Note that the transaction will not be started on the server until an operation is performed
+    # after start_transaction is called.
+    #
+    # @example Start a new transaction
+    #   session.start_transaction(options)
+    #
+    # @raise [ InvalidTransactionOperation ] If a transaction is already in progress or if the
+    #   write concern is unacknowledged.
+    #
+    # @since 2.6.0
+    def start_transaction(options = nil)
+      check_if_ended!
+
+      if within_states?(STARTING_TRANSACTION_STATE, TRANSACTION_IN_PROGRESS_STATE)
+        raise Mongo::Error::InvalidTransactionOperation.new(
+          Mongo::Error::InvalidTransactionOperation::TRANSACTION_ALREADY_IN_PROGRESS)
+      end
+
+      next_txn_num
+      @txn_options = options || @options[:default_transaction_options] || {}
+
+      if txn_write_concern && WriteConcern.send(:unacknowledged?, txn_write_concern)
+        raise Mongo::Error::InvalidTransactionOperation.new(
+          Mongo::Error::InvalidTransactionOperation::UNACKNOWLEDGED_WRITE_CONCERN)
+      end
+
+      @state = STARTING_TRANSACTION_STATE
+    end
+
+    # Commit the currently active transaction on the session.
+    #
+    # @example Commits the transaction.
+    #   session.commit_transaction
+    #
+    # @raise [ InvalidTransactionOperation ] If a transaction was just aborted and no new one was
+    #   started.
+    #
+    # @since 2.6.0
+    def commit_transaction
+      check_if_ended!
+      check_if_no_transaction!
+
+      if within_states?(TRANSACTION_ABORTED_STATE)
+        raise Mongo::Error::InvalidTransactionOperation.new(
+          Mongo::Error::InvalidTransactionOperation.cannot_call_after_msg(
+            :abortTransaction, :commitTransaction))
+      end
+
+      begin
+        # If commitTransaction is called twice, we need to run the same commit operation again, so
+        # we revert the session to the previous state.
+        if within_states?(TRANSACTION_COMMITTED_STATE)
+          @state = @last_commit_skipped ? STARTING_TRANSACTION_STATE : TRANSACTION_IN_PROGRESS_STATE
+        end
+
+        if starting_transaction?
+          @last_commit_skipped = true
+        else
+          @last_commit_skipped = false
+
+          write_with_retry(self, txn_options[:write_concern], true) do |server, txn_num|
+            Operation::Command.new(
+              selector: { commitTransaction: 1 },
+              db_name: 'admin',
+              session: self,
+              txn_num: txn_num
+            ).execute(server)
+          end
+        end
+      rescue Mongo::Error::NoServerAvailable, Mongo::Error::SocketError => e
+        e.send(:add_label, Mongo::Error::UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL)
+        raise e
+      rescue Mongo::Error::OperationFailure => e
+        err_doc = e.instance_variable_get(:@result).send(:first_document)
+
+        if e.write_retryable? || (err_doc['writeConcernError'] &&
+            !UNLABELED_WRITE_CONCERN_CODES.include?(err_doc['writeConcernError']['code']))
+          e.send(:add_label, Mongo::Error::UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL)
+        end
+
+        raise e
+      ensure
+        @state = TRANSACTION_COMMITTED_STATE
+      end
+    end
+
+    # Abort the currently active transaction without making any changes to the database.
+    #
+    # @example Abort the transaction.
+    #   session.abort_transaction
+    #
+    # @raise [ Mongo::Error::InvalidTransactionOperation ] If a transaction was just committed or
+    #   aborted and no new one was started.
+    #
+    # @since 2.6.0
+    def abort_transaction
+      check_if_ended!
+      check_if_no_transaction!
+
+      if within_states?(TRANSACTION_COMMITTED_STATE)
+        raise Mongo::Error::InvalidTransactionOperation.new(
+          Mongo::Error::InvalidTransactionOperation.cannot_call_after_msg(
+            :commitTransaction, :abortTransaction))
+      end
+
+      if within_states?(TRANSACTION_ABORTED_STATE)
+        raise Mongo::Error::InvalidTransactionOperation.new(
+          Mongo::Error::InvalidTransactionOperation.cannot_call_twice_msg(:abortTransaction))
+      end
+
+      begin
+        unless starting_transaction?
+          write_with_retry(self, txn_options[:write_concern], true) do |server, txn_num|
+            Operation::Command.new(
+              selector: { abortTransaction: 1 },
+              db_name: 'admin',
+              session: self,
+              txn_num: txn_num
+            ).execute(server)
+          end
+        end
+
+        @state = TRANSACTION_ABORTED_STATE
+      rescue Mongo::Error::InvalidTransactionOperation
+        raise
+      rescue Mongo::Error
+        @state = TRANSACTION_ABORTED_STATE
+      end
+    end
+
+    # Whether or not the session is currently in a transaction.
+    #
+    # @example Is the session in a transaction?
+    #   session.in_transaction?
+    #
+    # @return [ true | false ] Whether or not the session in a transaction.
+    #
+    # @since 2.6.0
+    def in_transaction?
+      within_states?(STARTING_TRANSACTION_STATE, TRANSACTION_IN_PROGRESS_STATE)
+    end
+
+    # Get the read preference document the session will use in the currently active transaction.
+    #
+    # @example Get the transaction's read preference
+    #   session.txn_read_pref
+    #
+    # @return [ Hash ] The read preference document of the transaction.
+    #
+    # @since 2.6.0
+    def txn_read_pref
+      rp = (txn_options && txn_options[:read_preference] && txn_options[:read_preference].dup) ||
+        (@client.read_preference && @client.read_preference.dup)
+      rp[:mode] = rp[:mode].to_s if rp
+      rp
+    end
+
+    def cluster
+      @client.cluster
+    end
+
     private
 
+    def within_states?(*states)
+      states.include?(@state)
+    end
+
+    def starting_transaction?
+      within_states?(STARTING_TRANSACTION_STATE)
+    end
+
+    def check_if_no_transaction!
+      return unless within_states?(NO_TRANSACTION_STATE)
+
+      raise Mongo::Error::InvalidTransactionOperation.new(
+        Mongo::Error::InvalidTransactionOperation::NO_TRANSACTION_STARTED)
+    end
+
+    def txn_read_concern
+      txn_options && txn_options[:read_concern] || @client.read_concern
+    end
+
+    def txn_write_concern
+      (txn_options && txn_options[:write_concern]) ||
+        (@client.write_concern && @client.write_concern.options)
+    end
+
+    def non_primary_readpref?(command)
+      return false unless command['$readPreference']
+
+      mode = command['$readPreference']['mode'] || command['$readPreference'][:mode]
+      mode && mode != 'primary'
+    end
+
     def causal_consistency_doc(read_concern)
       if operation_time && causal_consistency?
         (read_concern || {}).merge(:afterClusterTime => operation_time)
@@ -306,7 +683,7 @@ module Mongo
     end
 
     def check_matching_cluster!(cluster)
-      if @cluster != cluster
+      if @client.cluster != cluster
         raise Mongo::Error::InvalidSession.new(MISMATCHED_CLUSTER_ERROR_MSG)
       end
     end