mongo 1.1.5 → 1.3.0

data/README.md

@@ -10,9 +10,10 @@ This documentation includes other articles of interest, include:
 4. [GridFS in Ruby](http://api.mongodb.org/ruby/current/file.GridFS.html).
 5. [Frequently Asked Questions](http://api.mongodb.org/ruby/current/file.FAQ.html).
 6. [History](http://api.mongodb.org/ruby/current/file.HISTORY.html).
+6. [Release plan](http://api.mongodb.org/ruby/current/file.RELEASES.html).
 7. [Credits](http://api.mongodb.org/ruby/current/file.CREDITS.html).
 
-Here's a quick code sample. Again, see the [MongoDB Ruby Tutorial](file.TUTORIAL.html)
+Here's a quick code sample. Again, see the [MongoDB Ruby Tutorial](http://api.mongodb.org/ruby/current/file.TUTORIAL.html)
 for much more:
 
     require 'rubygems'
@@ -129,7 +130,7 @@ The driver is thread-safe.
 
 ## Connection Pooling
 
-As of v0.18, the driver implements connection pooling. By default, only one
+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.
@@ -141,20 +142,11 @@ To set up a pooled connection to a single MongoDB instance:
 Though the pooling architecture will undoubtedly evolve, it currently owes much credit
 to the connection pooling implementations in ActiveRecord and PyMongo.
 
-## Using with Phusion Passenger and Unicorn
+## Forking
 
-When Passenger and Unicorn are in smart spawning mode you need to be sure that child
-processes will create a new connection to the database. In Passenger, this can be handled like so:
-
-    if defined?(PhusionPassenger)
-      PhusionPassenger.on_event(:starting_worker_process) do |forked|
-        if forked
-          # Create new connection here
-        end
-      end
-    end
-
-The above code should be put into a Rails initializer or other initialization script.
+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.
 
 ## String Encoding
 
@@ -259,6 +251,14 @@ Notes:
 * 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::Connection` object.
+
+If implementing higher-level timeouts, using tools like `Rack::Timeout`, it's very important
+to call `Mongo::Connection#close` to prevent the subsequent operation from receiving the previous
+request.
 
 # Testing
 

data/Rakefile

@@ -5,10 +5,6 @@ require 'fileutils'
 require 'rake'
 require 'rake/testtask'
 require 'rake/gempackagetask'
-begin
-  require 'rake/contrib/rubyforgepublisher'
-rescue LoadError
-end
 require 'rbconfig'
 include Config
 ENV['TEST_MODE'] = 'TRUE'
@@ -26,7 +22,7 @@ namespace :build do
     jar_dir   = File.join(java_dir, 'jar')
 
     jruby_jar = File.join(jar_dir, 'jruby.jar')
-    mongo_jar = File.join(jar_dir, 'mongo-2.2.jar')
+    mongo_jar = File.join(jar_dir, 'mongo-2.4.jar')
     bson_jar = File.join(jar_dir, 'bson-2.2.jar')
 
     src_base   = File.join(java_dir, 'src')
@@ -77,41 +73,49 @@ namespace :test do
   Rake::TestTask.new(:rs) do |t|
     t.test_files = FileList['test/replica_sets/*_test.rb']
     t.verbose    = true
+    t.ruby_opts << '-w'
   end
 
   Rake::TestTask.new(:unit) do |t|
     t.test_files = FileList['test/unit/*_test.rb']
     t.verbose    = true
+    t.ruby_opts << '-w'
   end
 
   Rake::TestTask.new(:functional) do |t|
     t.test_files = FileList['test/*_test.rb']
     t.verbose    = true
+    t.ruby_opts << '-w'
   end
 
   Rake::TestTask.new(:pooled_threading) do |t|
     t.test_files = FileList['test/threading/*_test.rb']
     t.verbose    = true
+    t.ruby_opts << '-w'
   end
 
   Rake::TestTask.new(:auto_reconnect) do |t|
     t.test_files = FileList['test/auxillary/autoreconnect_test.rb']
     t.verbose    = true
+    t.ruby_opts << '-w'
   end
 
   Rake::TestTask.new(:authentication) do |t|
     t.test_files = FileList['test/auxillary/authentication_test.rb']
     t.verbose    = true
+    t.ruby_opts << '-w'
   end
 
   Rake::TestTask.new(:new_features) do |t|
     t.test_files = FileList['test/auxillary/1.4_features.rb']
     t.verbose    = true
+    t.ruby_opts << '-w'
   end
 
   Rake::TestTask.new(:bson) do |t|
     t.test_files = FileList['test/bson/*_test.rb']
     t.verbose    = true
+    t.ruby_opts << '-w'
   end
 
   task :drop_databases do |t|
@@ -138,16 +142,24 @@ task :ydoc do
   require File.join(File.dirname(__FILE__), 'lib', 'mongo')
   out = File.join('ydoc', Mongo::VERSION)
   FileUtils.rm_rf('ydoc')
-  system "yardoc lib/**/*.rb lib/mongo/**/*.rb lib/bson/**/*.rb -e yard/yard_ext.rb -p yard/templates -o #{out} --title MongoRuby-#{Mongo::VERSION} --files docs/TUTORIAL.md,docs/GridFS.md,docs/FAQ.md,docs/REPLICA_SETS.md,docs/WRITE_CONCERN.md,docs/HISTORY.md,docs/CREDITS.md,docs/1.0_UPGRADE.md"
+  system "yardoc lib/**/*.rb lib/mongo/**/*.rb lib/bson/**/*.rb -e yard/yard_ext.rb -p yard/templates -o #{out} --title MongoRuby-#{Mongo::VERSION} --files docs/TUTORIAL.md,docs/GridFS.md,docs/FAQ.md,docs/REPLICA_SETS.md,docs/WRITE_CONCERN.md,docs/HISTORY.md,docs/CREDITS.md,docs/RELEASES.md"
 end
 
 namespace :bamboo do
+  task :ci_reporter do
+    begin
+      require 'ci/reporter/rake/test_unit'
+    rescue LoadError
+      warn "Warning: Unable to load ci_reporter gem."
+    end
+  end
+
   namespace :test do
-    task :ruby do
+    task :ruby => [:ci_reporter, "ci:setup:testunit"] do
       Rake::Task['test:ruby'].invoke
     end
 
-    task :c do
+    task :c => [:ci_reporter, "ci:setup:testunit"] do
       Rake::Task['gem:install_extensions'].invoke
       Rake::Task['test:c'].invoke
     end
@@ -158,21 +170,30 @@ namespace :gem do
 
   desc "Install the gem locally"
   task :install do
-    sh "gem build bson.gemspec"
-    sh "gem install --no-rdoc --no-ri bson-*.gem"
+    `gem build bson.gemspec`
+    `gem install --no-rdoc --no-ri bson-*.gem`
 
-    sh "gem build mongo.gemspec"
-    sh "gem install --no-rdoc --no-ri mongo-*.gem"
+    `gem build mongo.gemspec`
+    `gem install --no-rdoc --no-ri mongo-*.gem`
 
-    sh "rm mongo-*.gem"
-    sh "rm bson-*.gem"
+    `rm mongo-*.gem`
+    `rm bson-*.gem`
   end
 
   desc "Install the optional c extensions"
   task :install_extensions do
-    sh "gem build bson_ext.gemspec"
-    sh "gem install --no-rdoc --no-ri bson_ext-*.gem"
-    sh "rm bson_ext-*.gem"
+    `gem uninstall bson_ext`
+    `gem build bson_ext.gemspec`
+    `gem install --no-rdoc --no-ri bson_ext-*.gem`
+    `rm bson_ext-*.gem`
+  end
+
+  desc "Build all gems"
+  task :build_all do
+    `gem build mongo.gemspec`
+    `gem build bson.gemspec`
+    `gem build bson.java.gemspec`
+    `gem build bson_ext.gemspec`
   end
 
 end

data/docs/FAQ.md

@@ -110,3 +110,7 @@ Without further investigation, it's impossible to know exactly what has caused t
 Because of the indeterminacy involved, the MongoDB drivers will not retry operations on connection failure. How connection failures should be handled is entirely dependent on the application. Therefore, we leave it to the application developers to make the best decision in this case.
 
 The drivers will reconnect on the subsequent operation.
+
+#### I ocassionally get an error saying that responses are out of order. What's happening?
+
+See (this JIRA issue)[http://jira.mongodb.org/browse/RUBY-221].

data/docs/HISTORY.md

@@ -1,5 +1,64 @@
 # MongoDB Ruby Driver History
 
+### 1.3.0
+2011-4-04
+
+* Add option to set timeouts on socket read calls using the
+  Mongo::Connection :op_timeout option.
+* Add StringIO methods to GridIO objects
+* Support for BSON timestamp type with BSON::Timestamp
+* Change the BSON binary subtype from 2 to 0
+* Remove private method Connection#reset_conection
+  and deprecate public method ReplSetConnection#reset_connection
+* ByteBuffer#== and OrderedHash#dup (Hongli Lai)
+* Better check for UTF8 validity in Ruby 1.9
+* Added previously removed Connection#host and Connection#port
+* Added transformers to allow Mongo::Cursor to allow instantiated objects (John Nunemaker)
+* Automated reconnection on fork
+* Added Cursor#next alias for Cursor#next_document
+* Audit tests after enabling warnings (Wojciech Piekutowski)
+* Various bug fixes thanks to Datanoise, Hongli Lai, and Mauro Pompilio
+
+### 1.2.4
+2011-2-23
+
+* Fix the exception message shown when there's an IOError (Mauro Pompilio)
+* Another update to map-reduce docs for v1.8. Note that if you use the new
+  output option {:out => {:inline => true}}, then you must also specify
+  :raw => true.
+
+### 1.2.3
+2011-2-22
+
+* Update docs for map-reduce command
+* Minor doc fix
+
+### 1.2.2
+2011-2-15
+
+* Improved replica set failover for edge case.
+* Fix for REE on OSX (Hongli Lai)
+
+### 1.2.1
+2011-1-18
+
+* Enable authentication with connection pooling.
+* Allow custom logging with Connection#instrument (CodeMonkeySteve)
+* Minor fixes and doc improvements.
+
+### 1.2.0
+2011-1-18
+
+* Some minor improvements. See commit history.
+
+### 1.2.rc0
+2011-1-5
+
+Lots of cleanup and minor bug fixes.
+* Issues resolved: http://jira.mongodb.org/browse/RUBY/fixforversion/10222
+* Updated Java BSON to Java driver 2.4.
+* Platform gem for JRuby bson.
+
 ### 1.1.5
 2010-12-15
 

data/docs/RELEASES.md

@@ -0,0 +1,33 @@
+# MongoDB Ruby Driver Release Plan
+
+This is a description of a formalized release plan that will take effect
+with version 1.3.0.
+
+## Semantic versioning
+
+The most significant difference is that releases will now adhere to the conventions of
+[semantic versioning](http://semver.org). In particular, we will strictly abide by the
+following release rules:
+
+1. Patch versions of the driver (Z in x.y.Z) will be released only when backward-compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior.
+
+2. Minor versions (Y in x.Y.z) will be released if new, backward-compatible functionality is introduced to the public API.
+
+3. Major versions (X in X.y.z) will be incremented if any backward-incompatibl changes are introduced to the public API.
+
+This policy will clearly indicate to users when an upgrade may affect their code. As a side effect, version numbers will climb more quickly than before.
+
+
+## Release checklist
+
+Before each relese to Rubygems.org, the following steps will be taken:
+
+1. All driver tests will be run on Linux, OS X, and Windows via continuous integration system.
+
+2. HISTORY file will document all significant commits.
+
+3. Version number will be incremented per the semantic version spec described above.
+
+4. Appropriate branches and tags will be created in Git repository, as necessary.
+
+5. Docs will be updated to the latest version of the driver and posted [online](http://api.mongodb.org/ruby/current/index.html).

data/docs/REPLICA_SETS.md

@@ -6,12 +6,13 @@ Here follow a few considerations for those using the MongoDB Ruby driver with [r
 
 First, make sure that you've configured and initialized a replica set.
 
-Use `ReplSetConnection.new` to connect to a replica set:
+Use `ReplSetConnection.new` to connect to a replica set. This method, which accepts a variable number of arugments,
+takes a list of seed nodes followed by any connection options. You'll want to specify at least two seed nodes. This gives
+the driver more chances to connect in the event that any one seed node is offline. Once the driver connects, it will
+cache the replica set topology as reported by the given seed node and use that information if a failover is later required.
 
     @connection = ReplSetConnection.new(['n1.mydb.net', 27017], ['n2.mydb.net', 27017], ['n3.mydb.net', 27017])
 
-The driver will attempt to connect to a master node and, when found, will replace all seed nodes with known members of the replica set.
-
 ### Read slaves
 
 If you want to read from a seconday node, you can pass :read_secondary => true to ReplSetConnection#new.
@@ -38,18 +39,14 @@ every half second and time out after thirty seconds.
 
     # Ensure retry upon failure
     def rescue_connection_failure(max_retries=60)
-        success = false
-        retries = 0
-        while !success
-          begin
-            yield
-            success = true
-          rescue Mongo::ConnectionFailure => ex
-            retries += 1
-            raise ex if retries >= max_retries
-            sleep(0.5)
-          end
-        end
+      retries = 0
+      begin
+        yield
+      rescue Mongo::ConnectionFailure => ex
+        retries += 1
+        raise ex if retries > max_retries
+        sleep(0.5)
+        retry
       end
     end
 
@@ -67,7 +64,7 @@ The Ruby driver (>= 1.1.5) includes unit tests for verifying replica set behavio
     rake test:rs
 
 The suite will set up a five-node replica set by itself and ensure that driver behaves correctly even in the face
-of individual node failures. Node that the `mongod` executable must be in the search path for this to work.
+of individual node failures. Note that the `mongod` executable must be in the search path for this to work.
 
 ### Further Reading