mongo 2.17.3 → 2.18.0.beta1

data/lib/mongo/session.rb

@@ -35,12 +35,23 @@ module Mongo
 
     # Initialize a Session.
     #
-    # @note Applications should use Client#start_session to begin a session.
+    # A session can be explicit or implicit. Lifetime of explicit sessions is
+    # managed by the application - applications explicitry create such sessions
+    # and explicitly end them. Implicit sessions are created automatically by
+    # the driver when sending operations to servers that support sessions
+    # (3.6+), and their lifetime is managed by the driver.
+    #
+    # When an implicit session is created, it cannot have a server session
+    # associated with it. The server session will be checked out of the
+    # session pool when an operation using this session is actually executed.
+    # When an explicit session is created, it must reference a server session
+    # that is already allocated.
     #
-    # @example
-    #   Session.new(server_session, client, options)
+    # @note Applications should use Client#start_session to begin a session.
+    #   This constructor is for internal driver use only.
     #
-    # @param [ ServerSession ] server_session The server session this session is associated with.
+    # @param [ ServerSession | nil ] server_session The server session this session is associated with.
+    #   If the :implicit option is true, this must be nil.
     # @param [ Client ] client The client through which this session is created.
     # @param [ Hash ] options The options for this session.
     #
@@ -50,7 +61,9 @@ module Mongo
     #   to start_transaction by default, can contain any of the options that
     #   start_transaction accepts.
     # @option options [ true|false ] :implicit For internal driver use only -
-    #   specifies whether the session is implicit.
+    #   specifies whether the session is implicit. If this is true, the server_session
+    #   will be nil. This is done so that the server session is only checked
+    #   out after the connection is checked out.
     # @option options [ Hash ] :read_preference The read preference options hash,
     #   with the following optional keys:
     #   - *:mode* -- the read preference as a string or symbol; valid values are
@@ -66,11 +79,21 @@ module Mongo
         raise ArgumentError, ':causal_consistency and :snapshot options cannot be both set on a session'
       end
 
+      if options[:implicit]
+        unless server_session.nil?
+          raise ArgumentError, 'Implicit session cannot reference server session during construction'
+        end
+      else
+        if server_session.nil?
+          raise ArgumentError, 'Explicit session must reference server session during construction'
+        end
+      end
+
       @server_session = server_session
       options = options.dup
 
       @client = client.use(:admin)
-      @options = options.freeze
+      @options = options.dup.freeze
       @cluster_time = nil
       @state = NO_TRANSACTION_STATE
     end
@@ -160,11 +183,11 @@ 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.
+    #   and with sharded clusters, replica sets, or load-balanced topologies.
     #
     # @since 2.5.0
     def retry_writes?
-      !!client.options[:retry_writes] && (cluster.replica_set? || cluster.sharded?)
+      !!client.options[:retry_writes] && (cluster.replica_set? || cluster.sharded? || cluster.load_balanced?)
     end
 
     # Get the read preference the session will use in the currently
@@ -194,23 +217,33 @@ module Mongo
     #
     # @since 2.5.0
     def ended?
-      @server_session.nil?
+      !!@ended
     end
 
-    # Get the server session id of this session, if the session was not ended.
-    # If the session was ended, returns nil.
-    #
-    # @example Get the session id.
-    #   session.session_id
+    # Get the server session id of this session, if the session has not been
+    # ended. If the session had been ended, raises Error::SessionEnded.
     #
     # @return [ BSON::Document ] The server session id.
     #
+    # @raise [ Error::SessionEnded ] If the session had been ended.
+    #
     # @since 2.5.0
     def session_id
       if ended?
         raise Error::SessionEnded
       end
 
+      # An explicit session will always have a session_id, because during
+      # construction a server session must be provided. An implicit session
+      # will not have a session_id until materialized, thus calls to
+      # session_id might fail. An application should not have an opportunity
+      # to experience this failure because an implicit session shouldn't be
+      # accessible to applications due to its lifetime being constrained to
+      # operation execution, which is done entirely by the driver.
+      unless materialized?
+        raise Error::SessionNotMaterialized
+      end
+
       @server_session.session_id
     end
 
@@ -220,11 +253,11 @@ module Mongo
     # @api private
     attr_reader :pinned_server
 
-    # @return [ Object | nil ] The service id that this session is pinned to,
+    # @return [ Integer | nil ] The connection global id that this session is pinned to,
     #   if any.
     #
     # @api private
-    attr_reader :pinned_service_id
+    attr_reader :pinned_connection_global_id
 
     # @return [ BSON::Document | nil ] Recovery token for the sharded
     #   transaction being executed on this session, if any.
@@ -325,10 +358,13 @@ module Mongo
           rescue Mongo::Error, Error::AuthError
           end
         end
-        @client.cluster.session_pool.checkin(@server_session)
+        if @server_session
+          @client.cluster.session_pool.checkin(@server_session)
+        end
       end
     ensure
       @server_session = nil
+      @ended = true
     end
 
     # Executes the provided block in a transaction, retrying as necessary.
@@ -591,8 +627,12 @@ module Mongo
           if write_concern && !write_concern.is_a?(WriteConcern::Base)
             write_concern = WriteConcern.get(write_concern)
           end
-          write_with_retry(self, write_concern, true) do |server, txn_num, is_retry|
-            if is_retry
+
+          context = Operation::Context.new(client: @client, session: self)
+          write_with_retry(write_concern, ending_transaction: true,
+            context: context,
+          ) do |connection, txn_num, context|
+            if context.retry?
               if write_concern
                 wco = write_concern.options.merge(w: :majority)
                 wco[:wtimeout] ||= 10000
@@ -608,7 +648,7 @@ module Mongo
               txn_num: txn_num,
               write_concern: write_concern,
             }
-            Operation::Command.new(spec).execute(server, context: Operation::Context.new(client: @client, session: self))
+            Operation::Command.new(spec).execute_with_connection(connection, context: context)
           end
         end
       ensure
@@ -649,14 +689,17 @@ module Mongo
       begin
         unless starting_transaction?
           @aborting_transaction = true
-          write_with_retry(self, txn_options[:write_concern], true) do |server, txn_num|
+          context = Operation::Context.new(client: @client, session: self)
+          write_with_retry(txn_options[:write_concern],
+            ending_transaction: true, context: context,
+          ) do |connection, txn_num, context|
             begin
               Operation::Command.new(
                 selector: { abortTransaction: 1 },
                 db_name: 'admin',
                 session: self,
                 txn_num: txn_num
-              ).execute(server, context: Operation::Context.new(client: @client, session: self))
+              ).execute_with_connection(connection, context: context)
             ensure
               unpin
             end
@@ -730,27 +773,32 @@ module Mongo
       @pinned_server = server
     end
 
-    # Pins this session to the specified service.
+    # Pins this session to the specified connection.
     #
-    # @param [ Object ] service_id The service id to pin this session to.
+    # @param [ Integer ] connection_global_id The global id of connection to pin
+    # this session to.
     #
     # @api private
-    def pin_to_service(service_id)
-      if service_id.nil?
-        raise ArgumentError, 'Cannot pin to a nil service id'
+    def pin_to_connection(connection_global_id)
+      if connection_global_id.nil?
+        raise ArgumentError, 'Cannot pin to a nil connection id'
       end
-      @pinned_service_id = service_id
+      @pinned_connection_global_id = connection_global_id
     end
 
-    # Unpins this session from the pinned server, if the session was pinned.
+    # Unpins this session from the pinned server or connection,
+    # if the session was pinned.
+    #
+    # @param [ Connection | nil ] connection Connection to unpin from.
     #
     # @api private
-    def unpin
+    def unpin(connection = nil)
       @pinned_server = nil
-      @pinned_service_id = nil
+      @pinned_connection_global_id = nil
+      connection.unpin unless connection.nil?
     end
 
-    # Unpins this session from the pinned server, if the session was pinned
+    # Unpins this session from the pinned server or connection, if the session was pinned
     # and the specified exception instance and the session's transaction state
     # require it to be unpinned.
     #
@@ -758,19 +806,20 @@ module Mongo
     # (both client- and server-side generated ones).
     #
     # @param [ Error ] error The exception instance to process.
+    # @param [ Connection | nil ] connection Connection to unpin from.
     #
     # @api private
-    def unpin_maybe(error)
+    def unpin_maybe(error, connection = nil)
       if !within_states?(Session::NO_TRANSACTION_STATE) &&
         error.label?('TransientTransactionError')
       then
-        unpin
+        unpin(connection)
       end
 
       if committing_transaction? &&
         error.label?('UnknownTransactionCommitResult')
       then
-        unpin
+        unpin(connection)
       end
     end
 
@@ -1007,6 +1056,33 @@ module Mongo
       end
     end
 
+    # If not already set, populate a session objects's server_session by
+    # checking out a session from the session pool.
+    #
+    # @return [ Session ] Self.
+    #
+    # @api private
+    def materialize_if_needed
+      if ended?
+        raise Error::SessionEnded
+      end
+
+      return unless implicit? && !@server_session
+
+      @server_session = cluster.session_pool.checkout
+
+      self
+    end
+
+    # @api private
+    def materialized?
+      if ended?
+        raise Error::SessionEnded
+      end
+
+      !@server_session.nil?
+    end
+
     # Increment and return the next transaction number.
     #
     # @example Get the next transaction number.

data/lib/mongo/socket/ocsp_verifier.rb

@@ -238,6 +238,10 @@ module Mongo
         end
 
         resp = resp.find_response(cert_id)
+        unless resp
+          @resp_errors << "OCSP response from #{report_uri(original_uri, uri)} did not include information about the requested certificate"
+          return false
+        end
         # TODO make a new class instead of patching the stdlib one?
         resp.instance_variable_set('@uri', uri)
         resp.instance_variable_set('@original_uri', original_uri)
@@ -245,11 +249,6 @@ module Mongo
           attr_reader :uri, :original_uri
         end
 
-        unless resp
-          @resp_errors << "OCSP response from #{report_uri(original_uri, uri)} did not include information about the requested certificate"
-          return false
-        end
-
         unless resp.check_validity
           @resp_errors << "OCSP response from #{report_uri(original_uri, uri)} was invalid: this_update was in the future or next_update time has passed"
           return false

data/lib/mongo/socket/tcp.rb

@@ -46,6 +46,9 @@ module Mongo
       # @since 2.0.0
       # @api private
       def initialize(host, port, timeout, family, options = {})
+        if family.nil?
+          raise ArgumentError, 'family must be specified'
+        end
         super(timeout, options)
         @host, @port = host, port
         @family = family

data/lib/mongo/srv/resolver.rb

@@ -29,6 +29,16 @@ module Mongo
       #   before querying SRV records.
       RECORD_PREFIX = '_mongodb._tcp.'.freeze
 
+      # Generates the record prefix with a custom SRV service name if it is
+      # provided.
+      #
+      # @option srv_service_name [ String | nil ] The SRV service name to use
+      #   in the record prefix.
+      # @return [ String ] The generated record prefix.
+      def record_prefix(srv_service_name=nil)
+        return srv_service_name ? "_#{srv_service_name}._tcp." : RECORD_PREFIX
+      end
+
       # Creates a new Resolver.
       #
       # @option opts [ Float ] :timeout The timeout, in seconds, to use for
@@ -51,13 +61,18 @@ module Mongo
         options[:timeout] || Monitor::DEFAULT_TIMEOUT
       end
 
-      # Obtains all of the SRV records for a given hostname.
+      # Obtains all of the SRV records for a given hostname. If a srv_max_hosts
+      # is specified and it is greater than 0, return maximum srv_max_hosts records.
       #
       # In the event that a record with a mismatched domain is found or no
       # records are found, if the :raise_on_invalid option is true,
       # an exception will be raised, otherwise a warning will be logged.
       #
       # @param [ String ] hostname The hostname whose records should be obtained.
+      # @param [ String | nil ] srv_service_name The SRV service name for the DNS query.
+      #   If nil, 'mongodb' is used.
+      # @param [ Integer | nil ] srv_max_hosts The maximum number of records to return.
+      #   If this value is nil, return all of the records.
       #
       # @raise [ Mongo::Error::MismatchedDomain ] If the :raise_in_invalid
       #   Resolver option is true and a record with a domain name that does
@@ -66,8 +81,8 @@ module Mongo
       #   option is true and no records are found.
       #
       # @return [ Mongo::Srv::Result ] SRV lookup result.
-      def get_records(hostname)
-        query_name = RECORD_PREFIX + hostname
+      def get_records(hostname, srv_service_name=nil, srv_max_hosts=nil)
+        query_name = record_prefix(srv_service_name) + hostname
         resources = @resolver.getresources(query_name, Resolv::DNS::Resource::IN::SRV)
 
         # Collect all of the records into a Result object, raising an error
@@ -97,6 +112,12 @@ module Mongo
           end
         end
 
+        # if srv_max_hosts is in [1, #addresses)
+        if (1...result.address_strs.length).include? srv_max_hosts
+          sampled_records = resources.shuffle.first(srv_max_hosts)
+          result = Srv::Result.new(hostname)
+          sampled_records.each { |record| result.add_record(record) }
+        end
         result
       end
 

data/lib/mongo/uri/options_mapper.rb

@@ -269,6 +269,8 @@ module Mongo
       uri_option 'directConnection', :direct_connection, type: :bool
       uri_option 'connect', :connect, type: :symbol
       uri_option 'loadBalanced', :load_balanced, type: :bool
+      uri_option 'srvMaxHosts', :srv_max_hosts, type: :integer
+      uri_option 'srvServiceName', :srv_service_name
 
       # Auth Options
       uri_option 'authSource', :auth_source

data/lib/mongo/uri/srv_protocol.rb

@@ -147,7 +147,7 @@ module Mongo
         validate_srv_hostname(hostname)
         @query_hostname = hostname
 
-        @srv_result = resolver.get_records(hostname)
+        @srv_result = resolver.get_records(hostname, uri_options[:srv_service_name], uri_options[:srv_max_hosts])
         if srv_result.empty?
           raise Error::NoSRVRecords.new(NO_SRV_RECORDS % hostname)
         end

data/lib/mongo/uri.rb

@@ -538,6 +538,26 @@ module Mongo
           raise_invalid_error_no_fmt!("loadBalanced=true cannot be used with replicaSet option")
         end
       end
+
+      unless self.is_a?(URI::SRVProtocol)
+        if uri_options[:srv_max_hosts]
+          raise_invalid_error_no_fmt!("srvMaxHosts cannot be used on non-SRV URI")
+        end
+
+        if uri_options[:srv_service_name]
+          raise_invalid_error_no_fmt!("srvServiceName cannot be used on non-SRV URI")
+        end
+      end
+
+      if uri_options[:srv_max_hosts] && uri_options[:srv_max_hosts] > 0
+        if uri_options[:replica_set]
+          raise_invalid_error_no_fmt!("srvMaxHosts > 0 cannot be used with replicaSet option")
+        end
+
+        if options[:load_balanced]
+          raise_invalid_error_no_fmt!("srvMaxHosts > 0 cannot be used with loadBalanced=true")
+        end
+      end
     end
   end
 end

data/lib/mongo/version.rb

@@ -20,5 +20,5 @@ module Mongo
   # The current version of the driver.
   #
   # @since 2.0.0
-  VERSION = '2.17.3'.freeze
+  VERSION = '2.18.0.beta1'.freeze
 end

data/lib/mongo.rb

@@ -75,8 +75,28 @@ require 'mongo/uri'
 require 'mongo/version'
 require 'mongo/write_concern'
 require 'mongo/utils'
+require 'mongo/config'
 
 module Mongo
+
+  class << self
+    extend Forwardable
+
+    # Delegate the given option along with its = and ? methods to the given
+    # object.
+    #
+    # @param [ Object ] obj The object to delegate to.
+    # @param [ Symbol ] opt The method to delegate.
+    def self.delegate_option(obj, opt)
+      def_delegators obj, opt, "#{opt}=", "#{opt}?"
+    end
+
+    # Take all the public instance methods from the Config singleton and allow
+    # them to be accessed through the Mongo module directly.
+    def_delegators Config, :options=
+    delegate_option Config, :validate_update_replace
+  end
+
   # Clears the driver's OCSP response cache.
   module_function def clear_ocsp_cache
     Socket::OcspCache.clear

data/mongo.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |s|
   s.platform          = Gem::Platform::RUBY
 
   s.authors           = ['Tyler Brock', 'Emily Stolfo', 'Durran Jordan']
-  s.homepage          = 'https://docs.mongodb.com/ruby-driver/'
+  s.homepage          = 'https://mongodb.com/docs/ruby-driver/'
   s.summary           = 'Ruby driver for MongoDB'
   s.description       = 'A Ruby driver for MongoDB'
   s.license           = 'Apache-2.0'
@@ -16,8 +16,8 @@ Gem::Specification.new do |s|
   s.metadata = {
     'bug_tracker_uri' => 'https://jira.mongodb.org/projects/RUBY',
     'changelog_uri' => 'https://github.com/mongodb/mongo-ruby-driver/releases',
-    'documentation_uri' => 'https://docs.mongodb.com/ruby-driver/',
-    'homepage_uri' => 'https://docs.mongodb.com/ruby-driver/',
+    'documentation_uri' => 'https://mongodb.com/docs/ruby-driver/',
+    'homepage_uri' => 'https://mongodb.com/docs/ruby-driver/',
     'source_code_uri' => 'https://github.com/mongodb/mongo-ruby-driver',
   }
 
@@ -38,5 +38,11 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version = ">= 2.5"
 
-  s.add_dependency 'bson', '>=4.8.2', '<5.0.0'
+  # For testing driver against bson master we need to depend on bson < 6.0.0
+  # but in release version we want to depend on bson < 5.0.0.
+  if %w(1 yes true).include?(ENV['MONGO_RUBY_DRIVER_BSON_MASTER'])
+    s.add_dependency 'bson', '>=4.13.0', '<6.0.0'
+  else
+    s.add_dependency 'bson', '>=4.14.1', '<5.0.0'
+  end
 end

data/spec/README.md

@@ -408,7 +408,7 @@ The client-side encryption tests require the mongocryptd binary to be in the
 system path.
 
 Download enterprise versions of MongoDB here: https://www.mongodb.com/download-center/enterprise
-Read more about installing mongocryptd here: https://docs.mongodb.com/manual/reference/security-client-side-encryption-appendix/#mongocryptd
+Read more about installing mongocryptd here: https://mongodb.com/docs/manual/reference/security-client-side-encryption-appendix/#mongocryptd
 
 Install libmongocrypt on your machine:
 
@@ -513,9 +513,9 @@ To test compression, set the `compressors` URI option:
     MONGODB_URI="mongodb://localhost:27017/?compressors=zlib" rake
 
 Note that as of this writing, the driver supports
-[ztsd](https://docs.mongodb.com/manual/reference/glossary/#term-zstd),
-[snappy](https://docs.mongodb.com/manual/reference/glossary/#term-snappy)
-and [zlib](https://docs.mongodb.com/manual/reference/glossary/#term-zlib)
+[ztsd](https://mongodb.com/docs/manual/reference/glossary/#term-zstd),
+[snappy](https://mongodb.com/docs/manual/reference/glossary/#term-snappy)
+and [zlib](https://mongodb.com/docs/manual/reference/glossary/#term-zlib)
 compression.
 
 Servers 4.2+ enable zlib by default; to test older servers, explicitly enable
@@ -530,7 +530,7 @@ To specify server API parameters, use the `SERVER_API` environment variable.
 The server API parameters cannot be specified via URI options.
 
 Both YAML and JSON syntaxes are accepted:
-    
+
     SERVER_API='{version: "1", strict: true}' rake
 
     SERVER_API='{"version":"1","strict":true}' rake

data/spec/integration/aws_lambda_examples_spec.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+require "spec_helper"
+
+describe "AWS Lambda examples in Ruby" do
+
+  it "shares the client" do
+    # Start AWS Lambda Example 1
+
+    # Require the driver library.
+    require "mongo"
+
+    # Create a Mongo::Client instance.
+    # CRITICAL: You must create the client instance outside the handler
+    # so that the client can be reused across function invocations.
+    client = Mongo::Client.new(ENV.fetch("MONGODB_URI"))
+
+    def lambda_handler(event:, context:)
+      # Use the client to return the name of the configured database.
+      client.database.name
+    end
+
+    # End AWS Lambda Example 1
+
+    client.close
+  end
+
+  context "when using AWS IAM authentication" do
+    require_auth 'aws-assume-role'
+
+    it "connects to the deployment" do
+      allow(ENV).to receive(:fetch).and_call_original
+      allow(ENV).to receive(:fetch).with("MONGODB_HOST").and_return(SpecConfig.instance.addresses.first)
+      allow(ENV).to receive(:fetch).with("AWS_ACCESS_KEY_ID").and_return(ENV.fetch("MONGO_RUBY_DRIVER_AWS_AUTH_ACCESS_KEY_ID"))
+      allow(ENV).to receive(:fetch).with("AWS_SECRET_ACCESS_KEY").and_return(ENV.fetch("MONGO_RUBY_DRIVER_AWS_AUTH_SECRET_ACCESS_KEY"))
+      allow(ENV).to receive(:fetch).with("AWS_SESSION_TOKEN").and_return(ENV.fetch("MONGO_RUBY_DRIVER_AWS_AUTH_SESSION_TOKEN"))
+      allow(ENV).to receive(:fetch).with("MONGODB_DATABASE").and_return("test")
+
+      # Start AWS Lambda Example 2
+
+      # Require the driver library.
+      require "mongo"
+
+      # Create a Mongo::Client instance using AWS IAM authentication.
+      # CRITICAL: You must create the client instance outside the handler
+      # so that the client can be reused across function invocations.
+      client = Mongo::Client.new([ENV.fetch("MONGODB_HOST")],
+                                 auth_mech: :aws,
+                                 user: ENV.fetch("AWS_ACCESS_KEY_ID"),
+                                 password: ENV.fetch("AWS_SECRET_ACCESS_KEY"),
+                                 auth_mech_properties: {
+                                   aws_session_token: ENV.fetch("AWS_SESSION_TOKEN"),
+                                 },
+                                 database: ENV.fetch("MONGODB_DATABASE"))
+
+      def lambda_handler(event:, context:)
+        # Use the client to return the name of the configured database.
+        client.database.name
+      end
+
+      # End AWS Lambda Example 2
+
+      client.close
+    end
+  end
+
+end

data/spec/integration/bulk_write_error_message_spec.rb

@@ -38,4 +38,36 @@ describe 'BulkWriteError message' do
       end
     end
   end
+
+  context 'a bulk write with validation errors' do
+
+    let(:collection_name) { 'bulk_write_error_validation_message_spec' }
+
+    let(:collection) do
+      client[:collection_name].drop
+      client[:collection_name,
+      {
+        'validator' => {
+          'x' => { '$type' => 'string' },
+        }
+      }].create
+      client[:collection_name]
+    end
+
+    it 'reports code name, code, message, and details' do
+      begin
+        collection.insert_one({_id:1, x:"1"})
+        collection.insert_many([
+          {_id: 1, x:"1"},
+          {_id: 2, x:1},
+        ], ordered: false)
+        fail('Should have raised')
+      rescue Mongo::Error::BulkWriteError => e
+        e.message.should =~ %r,\AMultiple errors: \[11000\]: (insertDocument :: caused by :: 11000 )?E11000 duplicate key error (collection|index):.*\; \[121\]: Document failed validation( -- .*)?,
+        # The duplicate key error should not print details because it's not a
+        # WriteError or a WriteConcernError
+        e.message.scan(/ -- /).length.should be <= 1
+      end
+    end
+  end
 end

data/spec/integration/bulk_write_spec.rb

@@ -18,22 +18,6 @@ describe 'Bulk writes' do
         authorized_collection.bulk_write(operations)
       end.not_to raise_error
     end
-
-    context 'in transaction' do
-      require_transaction_support
-      min_server_version "4.4"
-
-      it 'succeeds' do
-        authorized_collection.create
-        expect do
-          authorized_collection.client.start_session do |session|
-            session.with_transaction do
-              authorized_collection.bulk_write(operations, { session: session })
-            end
-          end
-        end.not_to raise_error
-      end
-    end
   end
 
   context 'when bulk write needs to be split' do