mongo 2.12.0.rc0 → 2.12.1

data/lib/mongo/srv/result.rb

@@ -13,7 +13,6 @@
 # limitations under the License.
 
 module Mongo
-
   module Srv
 
     # SRV record lookup result.

data/lib/mongo/uri.rb

@@ -216,7 +216,7 @@ module Mongo
     #   URI.get(string)
     #
     # @param [ String ] string The URI to parse.
-    # @param [ Hash ] options The options.
+    # @param [ Hash ] opts The options.
     #
     # @option options [ Logger ] :logger A custom logger to use.
     #

data/lib/mongo/uri/srv_protocol.rb

@@ -17,7 +17,7 @@ module Mongo
   class URI
 
     # Parser for a URI using the mongodb+srv protocol, which specifies a DNS to query for SRV records.
-    # The driver will query the DNS server for SRV records on {hostname}.{domainname},
+    # The driver will query the DNS server for SRV records on <hostname>.<domainname>,
     # prefixed with _mongodb._tcp
     # The SRV records can then be used as the seedlist for a Mongo::Client.
     # The driver also queries for a TXT record providing default connection string options.

data/lib/mongo/version.rb

@@ -17,5 +17,5 @@ module Mongo
   # The current version of the driver.
   #
   # @since 2.0.0
-  VERSION = '2.12.0.rc0'.freeze
+  VERSION = '2.12.1'.freeze
 end

data/mongo.gemspec

@@ -8,7 +8,6 @@ Gem::Specification.new do |s|
   s.platform          = Gem::Platform::RUBY
 
   s.authors           = ['Tyler Brock', 'Emily Stolfo', 'Durran Jordan']
-  s.email             = 'mongodb-dev@googlegroups.com'
   s.homepage          = 'https://docs.mongodb.com/ruby-driver/'
   s.summary           = 'Ruby driver for MongoDB'
   s.description       = 'A Ruby driver for MongoDB'
@@ -19,7 +18,6 @@ Gem::Specification.new do |s|
     '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/',
-    'mailing_list_uri' => 'https://groups.google.com/group/mongodb-user',
     'source_code_uri' => 'https://github.com/mongodb/mongo-ruby-driver',
   }
 

data/spec/README.md

@@ -272,22 +272,72 @@ To run the test suite against such a server, run:
 ## Kerberos
 
 The Kerberos-related functionality is packaged in a separate gem,
-`mongo_kerberos`. The driver test suite includes a number of unit tests that
-are skipped by default. To run them as part of the test suite, use the
-provided gemfile as follows:
+`mongo_kerberos`. To run any of the Kerberos tests, a special gemfile must
+be used that references `mongo_kerberos`:
 
     export BUNDLE_GEMFILE=gemfiles/mongo_kerberos.gemfile
     bundle install
-    export KERBEROS=1
+
+Ensure that BUNDLE_GEMFILE is set in the environment for both the
+`bundle install` invocation and the `rake` / `rspec` invocation.
+
+### Unit Tests
+
+The driver test suite includes a number of Kerberos-related unit tests that
+are skipped by default. To run them as part of the test suite, set the
+`MONGO_RUBY_DRIVER_KERBEROS` environment variable to `1`, `yes` or `true`
+as follows:
+
+    export MONGO_RUBY_DRIVER_KERBEROS=1
     rake
 
 Note that running the full test suite requires a MongoDB deployment. It is
 possible to run just the Kerberos-related unit tests without provisioning a
-MongoDB deployment; consult .evergreen/run-tests-kerberos-unit.sh for the
-full list of relevant test files.
+MongoDB deployment; consult the `.evergreen/run-tests-kerberos-unit.sh` file
+for the full list of relevant test files.
+
+### Integration Tests
+
+The driver test suite includes a number of Kerberos-related integration tests
+in the `spec/kerberos` directory. These require a provisioned Kerberos
+deployment and appropriately configured MongoDB deployment. One such deployment
+is provided internally by MongoDB and is used in the driver's Evergreen
+configuration; it is also possible to provision a test deployment locally.
+
+The following additional environment variables must be set to run the
+Kerberos integration tests:
+
+- `MONGO_RUBY_DRIVER_KERBEROS_INTEGRATION=1`
+- `SASL_HOST`: the host name of the MongoDB server that is configured to
+use Kerberos. Note that this is NOT the Kerberos domain controller (KDC).
+- `SASL_PORT`: the port number that the Kerberized MongoDB server is
+listenin on.
+- `SASL_USER`: the username to provide to MongoDB for authentication.
+- `SASL_PASS`: the password to provide to MongoDB for authentication.
+- `SASL_DB`: the database that stores the user used for authentication. This
+is the "auth soure" in MongoDB parlance. Normally this should be `$external`.
+- `PRINCIPAL`: the Kerberos principal to use for authentication, in the
+form of `username@realm`. Note that the realm is commonly uppercased.
+- `KERBEROS_DB`: the database that the user has access to.
+- `KEYTAB_BASE64`: Base64 encoded keytab for the user. Used instead of the
+password.
+
+There are several steps that must be taken in order to set up Kerberos on
+the client side before it is usable by the driver for authentication against
+a Kerberized server. Consult the `.evergreen/run-tests-kerberos-integration.sh`
+file for details.
 
 ## Client-Side Encryption
 
+NOTE: Client-side encryption tests require an enterprise build of MongoDB
+server version 4.2 or higher. These builds of the MongoDB server come packaged with
+mongocryptd, a daemon that is spawned by the driver during automatic encryption.
+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
+
 Install libmongocrypt on your machine:
 
 Option 1: Download a pre-built binary
@@ -357,12 +407,6 @@ https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying.html
 
 In one terminal, launch MongoDB:
 
-NOTE: You must be running MongoDB 4.2 or higher. All auto-encryption features
-require an enterprise build of MongoDB, but you can still run
-explicit encryption tests using the community edition of MongoDB.
-
-Download different versions of MongoDB here: https://www.mongodb.com/download-center/enterprise
-
 ```
 mkdir /tmp/mdb
 mongod --dbpath /tmp/mdb --setParameter enableTestCommands=1
@@ -374,6 +418,22 @@ environment variable to the full path to the .so/.dll/.dylib
 LIBMONGOCRYPT_PATH=/path/to/your/libmongocrypt/nocrypto/libmongocrypt.so bundle exec rake
 ```
 
+If you would like to run the client-side encryption tests on a replica set or
+sharded cluster, be aware that the driver will try to spawn the mongocryptd daemon on
+port 27020 by default. If port 27020 is already in use by a mongod or mongos
+process, spawning mongocryptd will fail, causing the tests to fail as well.
+
+To avoid this problem, set the MONGO_RUBY_DRIVER_MONGOCRYPTD_PORT environment
+variable to the port at which you would like the driver to spawn mongocryptd.
+For example, to always have the mongocryptd process listen on port 27090:
+
+```
+export MONGO_RUBY_DRIVER_MONGOCRYPTD_PORT=27090
+```
+
+Keep in mind that this will only impact the behavior of the Ruby Driver test suite,
+not the behavior of the driver itself.
+
 ## Compression
 
 To test compression, set the `compressors` URI option:
@@ -487,3 +547,37 @@ with color, use the `-R` option:
 
     rake 2>&1 | tee rake.log
     less -R rake.log
+
+## Debugging
+
+The test suite is configured to use [Byebug](https://github.com/deivid-rodriguez/byebug)
+for debugging on MRI and [ruby-debug](https://github.com/jruby/jruby/wiki/UsingTheJRubyDebugger)
+on JRuby.
+
+### MRI
+
+Call `byebug` anywhere in the test suite to break into Byebug.
+
+### JRuby
+
+To debug on JRuby, the test suite must be started with the `--debug` argument
+to `jruby`. This can be achieved by starting the test suite as follows:
+
+    jruby --debug -S rspec [rspec args...]
+
+Call `debugger` anywhere in the test suite to break into the debugger.
+
+### Docker
+
+By default, when the test suite is running in a CI environment the debuggers
+are not loaded. The Docker runner emulates the CI environment, therefore
+to debug in Docker the debugger must be explicitly loaded first. To break
+into the debugger on MRI, call:
+
+    require 'byebug'
+    byebug
+
+To break into the debugger on JRuby, call:
+
+    require 'ruby-debug'
+    debugger

data/spec/integration/client_construction_spec.rb

@@ -152,16 +152,40 @@ describe 'Client construction' do
       {
         key_vault_client: key_vault_client,
         key_vault_namespace: key_vault_namespace,
-        kms_providers: kms_providers
+        kms_providers: kms_providers,
+        # Spawn mongocryptd on non-default port for sharded cluster tests
+        extra_options: extra_options,
       }
     end
 
-    context 'with default key vault client' do
-      let(:key_vault_client) { nil }
+    let(:client) do
+      ClientRegistry.instance.new_local_client([SpecConfig.instance.addresses.first], options)
+    end
+
+    context 'with AWS kms providers with empty string credentials' do
+      let(:auto_encryption_options) do
+        {
+          key_vault_namespace: key_vault_namespace,
+          kms_providers: {
+            aws: {
+              access_key_id: '',
+              secret_access_key: '',
+            }
+          },
+          # Spawn mongocryptd on non-default port for sharded cluster tests
+          extra_options: extra_options,
+        }
+      end
 
-      let(:client) do
-        ClientRegistry.instance.new_local_client([SpecConfig.instance.addresses.first], options)
+      it 'raises an exception' do
+        expect do
+          client
+        end.to raise_error(ArgumentError, /The aws access_key_id option must be a String with at least one character; it is currently an empty string/)
       end
+    end
+
+    context 'with default key vault client' do
+      let(:key_vault_client) { nil }
 
       it 'creates a working key vault client' do
         key_vault_client = client.encrypter.key_vault_client

data/spec/integration/client_side_encryption/auto_encryption_bulk_writes_spec.rb

@@ -18,6 +18,8 @@ describe 'Bulk writes with auto-encryption enabled' do
           kms_providers: kms_providers,
           key_vault_namespace: key_vault_namespace,
           schema_map: { "auto_encryption.users" => schema_map },
+          # Spawn mongocryptd on non-default port for sharded cluster tests
+          extra_options: extra_options,
         },
         database: 'auto_encryption'
       ),
@@ -31,8 +33,8 @@ describe 'Bulk writes with auto-encryption enabled' do
   before do
     authorized_client.use('auto_encryption')['users'].drop
 
-    authorized_client.use('admin')['datakeys'].drop
-    authorized_client.use('admin')['datakeys'].insert_one(data_key)
+    key_vault_collection.drop
+    key_vault_collection.insert_one(data_key)
   end
 
   let(:command_succeeded_events) do
@@ -49,7 +51,7 @@ describe 'Bulk writes with auto-encryption enabled' do
     end
 
     it 'executes an encrypted bulk write' do
-      documents = authorized_client.use(:auto_encryption)[:users].find
+      documents = authorized_client.use('auto_encryption')['users'].find
       ssns = documents.map { |doc| doc['ssn'] }
       expect(ssns).to all(be_ciphertext)
     end
@@ -295,7 +297,7 @@ describe 'Bulk writes with auto-encryption enabled' do
 
   context '#insert_many' do
     let(:perform_bulk_write) do
-      client[:users].insert_many(documents)
+      client['users'].insert_many(documents)
     end
 
     let(:command_name) { 'insert' }

data/spec/integration/client_side_encryption/auto_encryption_command_monitoring_spec.rb

@@ -23,6 +23,8 @@ describe 'Auto Encryption' do
           kms_providers: kms_providers,
           key_vault_namespace: key_vault_namespace,
           schema_map: { "auto_encryption.users" => schema_map },
+          # Spawn mongocryptd on non-default port for sharded cluster tests
+          extra_options: extra_options,
         },
         database: db_name
       ),
@@ -32,11 +34,11 @@ describe 'Auto Encryption' do
   end
 
   before(:each) do
-    authorized_client.use(key_vault_db)[key_vault_coll].drop
-    authorized_client.use(key_vault_db)[key_vault_coll].insert_one(data_key)
+    key_vault_collection.drop
+    key_vault_collection.insert_one(data_key)
 
-    encryption_client[:users].drop
-    result = encryption_client[:users].insert_one(ssn: ssn, age: 23)
+    encryption_client['users'].drop
+    result = encryption_client['users'].insert_one(ssn: ssn, age: 23)
   end
 
   let(:started_event) do
@@ -68,7 +70,7 @@ describe 'Auto Encryption' do
     let(:command_name) { 'aggregate' }
 
     before do
-      encryption_client[:users].aggregate([{ '$match' => { 'ssn' => ssn } }]).first
+      encryption_client['users'].aggregate([{ '$match' => { 'ssn' => ssn } }]).first
     end
 
     it 'has encrypted data in command monitoring' do
@@ -88,7 +90,7 @@ describe 'Auto Encryption' do
     let(:command_name) { 'count' }
 
     before do
-      encryption_client[:users].count(ssn: ssn)
+      encryption_client['users'].count(ssn: ssn)
     end
 
     it 'has encrypted data in command monitoring' do
@@ -104,7 +106,7 @@ describe 'Auto Encryption' do
     let(:command_name) { 'distinct' }
 
     before do
-      encryption_client[:users].distinct(:ssn)
+      encryption_client['users'].distinct(:ssn)
     end
 
     it 'has encrypted data in command monitoring' do
@@ -120,7 +122,7 @@ describe 'Auto Encryption' do
     let(:command_name) { 'delete' }
 
     before do
-      encryption_client[:users].delete_one(ssn: ssn)
+      encryption_client['users'].delete_one(ssn: ssn)
     end
 
     it 'has encrypted data in command monitoring' do
@@ -136,7 +138,7 @@ describe 'Auto Encryption' do
     let(:command_name) { 'delete' }
 
     before do
-      encryption_client[:users].delete_many(ssn: ssn)
+      encryption_client['users'].delete_many(ssn: ssn)
     end
 
     it 'has encrypted data in command monitoring' do
@@ -152,7 +154,7 @@ describe 'Auto Encryption' do
     let(:command_name) { 'find' }
 
     before do
-      encryption_client[:users].find(ssn: ssn).first
+      encryption_client['users'].find(ssn: ssn).first
     end
 
     it 'has encrypted data in command monitoring' do
@@ -170,7 +172,7 @@ describe 'Auto Encryption' do
     let(:command_name) { 'findAndModify' }
 
     before do
-      encryption_client[:users].find_one_and_delete(ssn: ssn)
+      encryption_client['users'].find_one_and_delete(ssn: ssn)
     end
 
     it 'has encrypted data in command monitoring' do
@@ -188,7 +190,7 @@ describe 'Auto Encryption' do
     let(:command_name) { 'findAndModify' }
 
     before do
-      encryption_client[:users].find_one_and_replace(
+      encryption_client['users'].find_one_and_replace(
         { ssn: ssn },
         { ssn: '555-555-5555' }
       )
@@ -210,7 +212,7 @@ describe 'Auto Encryption' do
     let(:command_name) { 'findAndModify' }
 
     before do
-      encryption_client[:users].find_one_and_update(
+      encryption_client['users'].find_one_and_update(
         { ssn: ssn },
         { ssn: '555-555-5555' }
       )
@@ -233,7 +235,7 @@ describe 'Auto Encryption' do
     let(:command_name) { 'insert' }
 
     before do
-      encryption_client[:users].insert_one(ssn: ssn)
+      encryption_client['users'].insert_one(ssn: ssn)
     end
 
     it 'has encrypted data in command monitoring' do
@@ -249,7 +251,7 @@ describe 'Auto Encryption' do
     let(:command_name) { 'update' }
 
     before do
-      encryption_client[:users].replace_one(
+      encryption_client['users'].replace_one(
         { ssn: ssn },
         { ssn: '555-555-5555' }
       )
@@ -269,7 +271,7 @@ describe 'Auto Encryption' do
     let(:command_name) { 'update' }
 
     before do
-      encryption_client[:users].update_one({ ssn: ssn }, { ssn: '555-555-5555' })
+      encryption_client['users'].update_one({ ssn: ssn }, { ssn: '555-555-5555' })
     end
 
     it 'has encrypted data in command monitoring' do
@@ -287,7 +289,7 @@ describe 'Auto Encryption' do
 
     before do
       # update_many does not support replacement-style updates
-      encryption_client[:users].update_many({ ssn: ssn }, { "$inc" => { :age => 1 } })
+      encryption_client['users'].update_many({ ssn: ssn }, { "$inc" => { :age => 1 } })
     end
 
     it 'has encrypted data in command monitoring' do

data/spec/integration/client_side_encryption/auto_encryption_mongocryptd_spawn_spec.rb

@@ -31,8 +31,8 @@ describe 'Auto Encryption' do
     let(:cluster) { double("Cluster") }
 
     before do
-      authorized_client.use(:admin)[:datakeys].drop
-      authorized_client.use(:admin)[:datakeys].insert_one(data_key)
+      key_vault_collection.drop
+      key_vault_collection.insert_one(data_key)
 
       allow(server_selector).to receive(:name)
       allow(server_selector).to receive(:server_selection_timeout)
@@ -54,14 +54,15 @@ describe 'Auto Encryption' do
             'documents' => kind_of(Array),
             'jsonSchema' => kind_of(Hash),
             'isRemoteSchema' => false,
-          )
+          ),
+          { execution_options: { deserialize_as_bson: true } },
         )
         .and_raise(Mongo::Error::NoServerAvailable.new(server_selector, cluster))
     end
 
     it 'raises an exception when trying to perform auto encryption' do
       expect do
-        client[:users].insert_one(ssn: ssn)
+        client['users'].insert_one(ssn: ssn)
       end.to raise_error(
         Mongo::Error::MongocryptdSpawnError,
         /Failed to spawn mongocryptd at the path "echo hello world" with arguments/