mongo 1.8.6 → 2.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5bdb78ad2291ea3ecb387526ccdbd162ffd51687
-  data.tar.gz: 6b3ec42fadc3f0beea953a08fe07a2d2ff206cba
+SHA256:
+  metadata.gz: abc1ceb1549c601a0b9d34ae3df301219e1de84ebdda6747734b9228395fa860
+  data.tar.gz: b5dc267b2fc65cfaef33a3e0966edd9b90fb35c414e996d2bd778d0c43ff9cc3
 SHA512:
-  metadata.gz: 83bb86f711779590a47d0d8d83fea4d844cd8ebdcde6617109c9172dd9d6961688d3faf03c1c7d0c0601575ed1a253522aecc2b26f2e81fb7980079ca3dff9fd
-  data.tar.gz: 880a70826f29e9e60fff3d26ede30390da593e78ad095f635743ffec711ce22af34da2d89318fd48f7825e2583bbec02da80c78899d4388386a76c769ee1e80e
+  metadata.gz: 7688c5325d3a4746ba6c2975dbdaf4aaf15929d49d467ff27cc3ec9a437ea1e34913436307c0ee845f3f8c53d9fdfdbfd6037fa71aa6479a33e165a3111651d8
+  data.tar.gz: 910a844b6907a24914990a4697e74ceff60bddfc160464f43f83f0a7fd94eb10eb8a098afc696f35eee68603c26213432dba5ae573e3cc71f8a0fd464ae89d2a

data/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing to the MongoDB Ruby Driver
+
+Thank you for your interest in contributing to the MongoDB Ruby driver.
+
+We are building this software together and appreciate and encourage
+contributions from the community.
+
+Pull Requests
+-------------
+
+Pull requests should be made against the `master` branch and
+include relevant tests, if applicable. The Ruby driver team will backport
+the changes to the stable branches, if needed.
+
+JIRA Tickets
+------------
+
+The Ruby driver team uses [MongoDB JIRA](https://jira.mongodb.org/browse/RUBY)
+to schedule and track work.
+
+A JIRA ticket is not required when submitting a pull request, but is
+appreciated especially for non-trivial changes.

data/LICENSE

@@ -175,7 +175,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   Copyright (C) 2008-2013 10gen, Inc.
+   Copyright (C) 2009-2020 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/README.md

@@ -1,342 +1,101 @@
-[![Build Status][travis-img]][travis-url] [![Jenkins Status][jenkins-img]][jenkins-url] [![Code Climate][codeclimate-img]][codeclimate-url]
+MongoDB Ruby Driver
+[![Gem Version][rubygems-img]][rubygems-url]
+[![Inline docs][inch-img]][inch-url]
+================================================================
 
-[travis-img]: https://secure.travis-ci.org/mongodb/mongo-ruby-driver.png
-[travis-url]: http://travis-ci.org/mongodb/mongo-ruby-driver
-[codeclimate-img]: https://codeclimate.com/github/mongodb/mongo-ruby-driver.png
-[codeclimate-url]: https://codeclimate.com/github/mongodb/mongo-ruby-driver
-[jenkins-img]: https://jenkins.10gen.com/job/mongo-ruby-driver/badge/icon
-[jenkins-url]: https://jenkins.10gen.com/job/mongo-ruby-driver/
-[api-url]: http://api.mongodb.org/ruby/current
+The officially supported Ruby driver for [MongoDB](https://www.mongodb.org/).
 
-# Documentation
+The Ruby driver supports Ruby 2.3-3.0 and JRuby 9.2.
 
-This API documentation is available online at [http://api.mongodb.org/ruby](http://api.mongodb.org/ruby)
-for all releases of the MongoDB Ruby driver.  Please reference the exact version of the documentation
-that matches the release of the Ruby driver that you are using.  Note that the
-[Ruby Language Center for MongoDB](http://www.mongodb.org/display/DOCS/Ruby+Language+Center)
-has a link to API Documentation for the current release.
 
-If you have the source, you can generate the matching documentation  by typing
+Documentation
+-------------
 
-    $ rake docs
+High level documentation and usage examples are located
+[here](http://docs.mongodb.org/ecosystem/drivers/ruby/).
 
-Once generated, the API documentation can be found in the docs/ folder.
+API documentation for the most recent release can be found
+[here](https://docs.mongodb.com/ruby-driver/current/api/).
+To build API documentation for the master branch, check out the
+repository locally and run `rake docs`.
 
-# Introduction
 
-This is the 10gen-supported Ruby driver for [MongoDB](http://www.mongodb.org).
+Support
+-------
 
-For the api reference please see the [API][api-url]
+Commercial support for the driver is available through the
+[MongoDB Support Portal](https://support.mongodb.com/).
 
-The [wiki](https://github.com/mongodb/mongo-ruby-driver/wiki) has other articles of interest, including:
+For questions, discussions or general technical support, please visit the
+[MongoDB Community Forum](https://developer.mongodb.com/community/forums/tags/c/drivers-odms-connectors/7/ruby-driver).
 
-1. [A tutorial](https://github.com/mongodb/mongo-ruby-driver/wiki/Tutorial).
-2. [Replica Sets in Ruby](https://github.com/mongodb/mongo-ruby-driver/wiki/Replica-Sets).
-3. [Write Concern in Ruby](https://github.com/mongodb/mongo-ruby-driver/wiki/Write-Concern).
-4. [Tailable Cursors in Ruby](https://github.com/mongodb/mongo-ruby-driver/wiki/Tailable-Cursors).
-5. [Read Preference in Ruby](https://github.com/mongodb/mongo-ruby-driver/wiki/Read-Preference).
-6. [GridFS in Ruby](https://github.com/mongodb/mongo-ruby-driver/wiki/GridFS).
-7. [Frequently Asked Questions](https://github.com/mongodb/mongo-ruby-driver/wiki/FAQ).
-8. [History](https://github.com/mongodb/mongo-ruby-driver/wiki/History).
-9. [Release plan](https://github.com/mongodb/mongo-ruby-driver/wiki/Releases).
-10. [Credits](https://github.com/mongodb/mongo-ruby-driver/wiki/Credits).
+Please see [Technical Support](https://docs.mongodb.com/manual/support/) page
+in the documentation for other support resources.
 
-Here's a quick code sample. Again, see the [MongoDB Ruby Tutorial](https://github.com/mongodb/mongo-ruby-driver/wiki/Tutorial) for much more:
 
-```ruby
-require 'rubygems'
-require 'mongo'
+Bugs & Feature Requests
+-----------------------
 
-include Mongo
+To report a bug in the driver or request a feature specific to the Ruby driver:
 
-@client = MongoClient.new('localhost', 27017)
-@db     = @client['sample-db']
-@coll   = @db['test']
+1. Visit [our issue tracker](https://jira.mongodb.org/) and login
+(or create an account if you do not have one already).
+2. Navigate to the [RUBY project](https://jira.mongodb.org/browse/RUBY).
+3. Click 'Create Issue' and fill out all of the applicable form fields.
 
-@coll.remove
+When creating an issue, please keep in mind that all information in JIRA
+for the RUBY project, as well as the core server (the SERVER project),
+is publicly visible.
 
-3.times do |i|
-  @coll.insert({'a' => i+1})
-end
+**PLEASE DO:**
 
-puts "There are #{@coll.count} records. Here they are:"
-@coll.find.each { |doc| puts doc.inspect }
-```
+- Provide as much information as possible about the issue.
+- Provide detailed steps for reproducing the issue.
+- Provide any applicable code snippets, stack traces and log data.
+  Do not include any sensitive data or server logs.
+- Specify version numbers of the driver and MongoDB server.
 
-# Installation
+**PLEASE DO NOT:**
 
-### Ruby Versions
+- Provide any sensitive data or server logs.
+- Report potential security issues publicly (see 'Security Issues' below).
 
-The driver works and is consistently tested on Ruby 1.8.7 and 1.9.3 as well as JRuby 1.6.x and 1.7.x.
 
-Note that if you're on 1.8.7, be sure that you're using a patchlevel >= 249. There are some IO bugs in earlier versions.
+Security Issues
+---------------
 
-### Gems
+If you have identified a potential security-related issue in the Ruby driver
+(or any other MongoDB product), please report it by following the
+[instructions here](http://docs.mongodb.org/manual/tutorial/create-a-vulnerability-report).
 
-    $ gem update --system
-    $ gem install mongo
 
-For a significant performance boost, you'll want to install the C extension:
+Product Feature Requests
+------------------------
 
-    $ gem install bson_ext
+To request a feature which is not specific to the Ruby driver, or which
+affects more than the driver alone (for example, a feature which requires
+MongoDB server support), please submit your idea through the
+[MongoDB Feedback Forum](https://feedback.mongodb.com/forums/924286-drivers).
 
-Note that bson_ext isn't used with JRuby. Instead, we use some native Java extensions are bundled with the bson gem. If you ever need to modify these extensions, you can recompile with the following rake task:
 
-    $ rake compile:jbson
+Running Tests
+-------------
 
-### From the GitHub source
+Please refer to [spec/README.md](spec/README.md) for instructions on how
+to run the driver's test suite.
 
-The source code is available at http://github.com/mongodb/mongo-ruby-driver.
-You can either clone the git repository or download a tarball or zip file.
-Once you have the source, you can use it from wherever you downloaded it or
-you can install it as a gem from the source by typing:
 
-    $ rake install
+Release History
+---------------
 
-# Examples
+Full release notes and release history are available [on the GitHub releases
+page](https://github.com/mongodb/mongo-ruby-driver/releases).
 
-For extensive examples, see the [MongoDB Ruby Tutorial](https://github.com/mongodb/mongo-ruby-driver/wiki/Tutorial).
 
-# GridFS
+License
+-------
 
-The Ruby driver include two abstractions for storing large files: Grid and GridFileSystem.
-
-The Grid class is a Ruby implementation of MongoDB's GridFS file storage
-specification. GridFileSystem is essentially the same, but provides a more filesystem-like API and assumes that filenames are unique.
-
-An instance of both classes represents an individual file store. See the API reference for details.
-
-Examples:
-
-```ruby
-# Write a file on disk to the Grid
-file = File.open('image.jpg')
-grid = Mongo::Grid.new(db)
-id   = grid.put(file)
-
-# Retrieve the file
-file = grid.get(id)
-file.read
-
-# Get all the file's metata
-file.filename
-file.content_type
-file.metadata
-```
-
-# Notes
-
-## Thread Safety
-
-The driver is thread-safe.
-
-## Connection Pooling
-
-The driver implements connection pooling. By default, only one
-socket connection will be opened to MongoDB. However, if you're running a
-multi-threaded application, you can specify a maximum pool size and a maximum
-timeout for waiting for old connections to be released to the pool.
-
-To set up a pooled connection to a single MongoDB instance:
-
-```ruby
-  @client = MongoClient.new("localhost", 27017, :pool_size => 5, :timeout => 5)
-```
-
-Though the pooling architecture will undoubtedly evolve, it currently owes much credit
-to the connection pooling implementations in ActiveRecord and PyMongo.
-
-## Forking
-
-Certain Ruby application servers work by forking, and it has long been necessary to
-re-establish the child process's connection to the database after fork. But with the release
-of v1.3.0, the Ruby driver detects forking and reconnects automatically.
-
-## Environment variable `MONGODB_URI`
-
-`Mongo::MongoClient.from_uri`, `Mongo::MongoClient.new` and `Mongo::MongoReplicaSetClient.new` will use <code>ENV["MONGODB_URI"]</code> if no other args are provided.
-
-The URI must fit this specification:
-
-    mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]
-
-If the type of connection (direct or replica set) should be determined entirely from <code>ENV["MONGODB_URI"]</code>, you may want to use `Mongo::MongoClient.from_uri` because it will return either `Mongo::MongoClient` or a `Mongo::MongoReplicaSetClient` depending on how many hosts are specified. Trying to use `Mongo::MongoClient.new` with multiple hosts in <code>ENV["MONGODB_URI"]</code> will raise an exception.
-
-## String Encoding
-
-The BSON ("Binary JSON") format used to communicate with Mongo requires that
-strings be UTF-8 (http://en.wikipedia.org/wiki/UTF-8).
-
-Ruby 1.9 has built-in character encoding support. All strings sent to Mongo
-and received from Mongo are converted to UTF-8 when necessary, and strings
-read from Mongo will have their character encodings set to UTF-8.
-
-When used with Ruby 1.8, the bytes in each string are written to and read from
-Mongo as is. If the string is ASCII, all is well, because ASCII is a subset of
-UTF-8. If the string is not ASCII, it may not be a well-formed UTF-8
-string.
-
-## Primary Keys
-
-The `_id` field is a primary key. It is treated specially by the database, and
-its use makes many operations more efficient. The value of an _id may be of
-any type. The database itself inserts an _id value if none is specified when
-a record is inserted.
-
-### Primary Key Factories
-
-A primary key factory is a class you supply to a DB object that knows how to
-generate _id values. If you want to control _id values or even their types,
-using a PK factory lets you do so.
-
-You can tell the Ruby Mongo driver how to create primary keys by passing in
-the :pk option to the MongoClient#db method.
-
-```ruby
-include Mongo
-db = MongoClient.new('localhost', 27017).db('dbname', :pk => MyPKFactory.new)
-```
-
-A primary key factory object must respond to :create_pk, which should
-take a hash and return a hash which merges the original hash with any
-primary key fields the factory wishes to inject.
-
-NOTE: if the object already has a primary key, the factory should not
-inject a new key; this means that the object may already exist in the
-database.  The idea here is that whenever a record is inserted, the
-:pk object's +create_pk+ method will be called and the new hash
-returned will be inserted.
-
-Here is a sample primary key factory, taken from the tests:
-```ruby
-class TestPKFactory
-  def create_pk(doc)
-    doc['_id'] ||= BSON::ObjectId.new
-    doc
-  end
-end
-```
-Here's a slightly more sophisticated one that handles both symbol and string
-keys. This is the PKFactory that comes with the MongoRecord code (an
-ActiveRecord-like framework for non-Rails apps) and the AR Mongo adapter code
-(for Rails):
-```ruby
-class PKFactory
-  def create_pk(doc)
-    return doc if doc[:_id]
-    doc.delete(:_id)      # in case it exists but the value is nil
-    doc['_id'] ||= BSON::ObjectId.new
-    doc
-  end
-end
-```
-
-A database's PK factory object may be set either when a DB object is created
-or immediately after you obtain it, but only once. The only reason it is
-changeable at all is so that libraries such as MongoRecord that use this
-driver can set the PK factory after obtaining the database but before using it
-for the first time.
-
-## The DB Class
-
-### Strict mode
-
-_**NOTE:** Support for strict mode has been deprecated and will be removed in version 2.0 of the driver._
-
-Each database has an optional strict mode. If strict mode is on, then asking
-for a collection that does not exist will raise an error, as will asking to
-create a collection that already exists. Note that both these operations are
-completely harmless; strict mode is a programmer convenience only.
-
-To turn on strict mode, either pass in :strict => true when obtaining a DB
-object or call the `:strict=` method:
-
-```ruby
-db = MongoClient.new('localhost', 27017).db('dbname', :strict => true)
-# I'm feeling lax
-db.strict = false
-# No, I'm not!
-db.strict = true
-```
-
-The method DB#strict? returns the current value of that flag.
-
-## Cursors
-
-Notes:
-
-* Cursors are enumerable (and have a #to_a method).
-
-* The query doesn't get run until you actually attempt to retrieve data from a
-  cursor.
-
-* Cursors will timeout on the server after 10 minutes. If you need to keep a cursor
-  open for more than 10 minutes, specify `:timeout => false` when you create the cursor.
-
-## Socket timeouts
-
-The Ruby driver support timeouts on socket read operations. To enable them, set the
-`:op_timeout` option when you create a `Mongo::MongoClient` object.
-
-If implementing higher-level timeouts, using tools like `Rack::Timeout`, it's very important
-to call `Mongo::MongoClient#close` to prevent the subsequent operation from receiving the previous
-request.
-
-# Testing
-
-Before running the tests, make sure you install all test dependencies by running:
-
-    $ gem install bundler; bundle install
-
-To run all default test suites (without the BSON extensions) just type:
-
-    $ rake test
-
-If you want to run the default test suite using the BSON extensions:
-
-    $ rake test:ext
-
-These will run both unit and functional tests. To run these tests alone:
-
-    $ rake test:unit
-    $ rake test:functional
-
-To run any individual rake tasks with the BSON extension disabled, just pass BSON_EXT_DISABLED=true to the task:
-
-    $ rake test:unit BSON_EXT_DISABLED=true
-
-If you want to test replica set, you can run the following task:
-
-    $ rake test:replica_set
-
-To run a single test at the top level, add -Itest since we no longer modify LOAD_PATH:
-
-    $ ruby -Itest -Ilib test/bson/bson_test.rb
-
-To run a single test from the test directory, add -I. since we no longer modify LOAD_PATH:
-
-    $ ruby -I. -I../lib bson/bson_test.rb
-
-To run a single test from its subdirectory, add -I.. since we no longer modify LOAD_PATH:
-
-    $ ruby -I.. -I../../lib bson_test.rb
-
-To fix the following error on Mac OS X - "/.../lib/bson_ext/cbson.bundle: [BUG] Segmentation fault":
-
-    $ rake compile
-
-# Release Notes
-
-See [history](https://github.com/mongodb/mongo-ruby-driver/wiki/History).
-
-
-# Credits
-
-See [credits](https://github.com/mongodb/mongo-ruby-driver/wiki/Credits).
-
-# License
-
- Copyright (C) 2008-2013 10gen Inc.
+ Copyright (C) 2009-2020 MongoDB, Inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -349,3 +108,8 @@ See [credits](https://github.com/mongodb/mongo-ruby-driver/wiki/Credits).
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
+
+[rubygems-img]: https://badge.fury.io/rb/mongo.svg
+[rubygems-url]: http://badge.fury.io/rb/mongo
+[inch-img]: http://inch-ci.org/github/mongodb/mongo-ruby-driver.svg?branch=master
+[inch-url]: http://inch-ci.org/github/mongodb/mongo-ruby-driver