mongo 1.2.4 → 1.3.0.rc0

data/README.md

@@ -10,6 +10,7 @@ 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](http://api.mongodb.org/ruby/current/file.TUTORIAL.html)
@@ -141,32 +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
-
-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
-          # Reset all connection objects. How you do this depends on where
-          # you keep your connection object. In any case, call the #connect
-          # method on the connection object. For example:
-          # CONN.connect
-          #
-          # If you're using MongoMapper:
-          # MongoMapper.connection.connect
-        end
-      end
-    end
+## Forking
 
-In Unicorn, add this to your unicorn.rb file:
-
-    after_fork do |server, worker|
-      # Handle reconnection
-    end
-
-The above code should be put into a Rails initializer or similar 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
 
@@ -271,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

@@ -77,41 +77,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,7 +146,7 @@ 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/1.0_UPGRADE.md,docs/RELEASES.md"
 end
 
 namespace :bamboo do

data/docs/HISTORY.md

@@ -1,5 +1,24 @@
 # MongoDB Ruby Driver History
 
+### 1.3.0.rc0
+2011-3-29
+
+* Add option to set timeouts on socket read calls. Use
+  the :op_timeout option when creating a new connection.
+* 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 (FooBarWidget)
+* 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 (jnunemaker)
+* Automated reconnection on fork
+* Added Cursor#next alias for Cursor#next_document
+* Audit tests after enabling warnings (wpiekutowski)
+* Various bug fixes thanks to FooBarWidget, Datanoise, Malitogeek
+
 ### 1.2.4
 2011-2-23
 

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.

data/lib/mongo.rb

@@ -19,7 +19,7 @@
 $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 
 module Mongo
-  VERSION = "1.2.4"
+  VERSION = "1.3.0.rc0"
 end
 
 module Mongo
@@ -76,4 +76,22 @@ if RUBY_PLATFORM =~ /java/
 end
 require 'mongo/gridfs/grid_file_system'
 
-
+# Use SystemTimer on Ruby 1.8
+if !defined?(RUBY_ENGINE) || (RUBY_ENGINE == 'ruby' && RUBY_VERSION < '1.9.0')
+  begin
+    require 'system_timer'
+    if SystemTimer.method(:timeout).arity.abs != 2
+      raise LoadError
+    end
+    Mongo::TimeoutHandler = SystemTimer
+  rescue LoadError
+    warn "Could not load SystemTimer >= v1.2.0. Falling back to timeout.rb. " +
+         "SystemTimer is STRONGLY recommended for timeouts in Ruby 1.8.7. " +
+         "See http://ph7spot.com/blog/system-timer-1-2-release for details."
+    require 'timeout'
+    Mongo::TimeoutHandler = Timeout
+  end
+else
+  require 'timeout'
+  Mongo::TimeoutHandler = Timeout
+end

data/lib/mongo/collection.rb

@@ -157,6 +157,8 @@ module Mongo
     #   the normal cursor timeout behavior of the mongod process. When +false+, the returned cursor will never timeout. Note
     #   that disabling timeout will only work when #find is invoked with a block. This is to prevent any inadvertant failure to
     #   close the cursor, as the cursor is explicitly closed when block code finishes.
+    # @option opts [Block] :transformer (nil) a block for tranforming returned documents.
+    #   This is normally used by object mappers to convert each returned document to an instance of a class.
     #
     # @raise [ArgumentError]
     #   if timeout is set to false and find is not invoked in a block
@@ -175,6 +177,7 @@ module Mongo
       snapshot   = opts.delete(:snapshot)
       batch_size = opts.delete(:batch_size)
       timeout    = (opts.delete(:timeout) == false) ? false : true
+      transformer = opts.delete(:transformer)
 
       if timeout == false && !block_given?
         raise ArgumentError, "Collection#find must be invoked with a block when timeout is disabled."
@@ -188,8 +191,18 @@ module Mongo
 
       raise RuntimeError, "Unknown options [#{opts.inspect}]" unless opts.empty?
 
-      cursor = Cursor.new(self, :selector => selector, :fields => fields, :skip => skip, :limit => limit,
-        :order => sort, :hint => hint, :snapshot => snapshot, :timeout => timeout, :batch_size => batch_size)
+      cursor = Cursor.new(self, {
+        :selector    => selector, 
+        :fields      => fields, 
+        :skip        => skip, 
+        :limit       => limit,
+        :order       => sort, 
+        :hint        => hint, 
+        :snapshot    => snapshot, 
+        :timeout     => timeout, 
+        :batch_size  => batch_size,
+        :transformer => transformer,
+      })
 
       if block_given?
         yield cursor

data/lib/mongo/connection.rb

@@ -68,6 +68,8 @@ module Mongo
     # @option opts [Float] :timeout (5.0) When all of the connections a pool are checked out,
     #   this is the number of seconds to wait for a new connection to be released before throwing an exception.
     #   Note: this setting is relevant only for multi-threaded applications (which in Ruby are rare).
+    # @option opts [Float] :op_timeout (nil) The number of seconds to wait for a read operation to time out.
+    #   Disabled by default.
     #
     # @example localhost, 27017
     #   Connection.new
@@ -157,6 +159,20 @@ module Mongo
       end
     end
 
+    # The host name used for this connection.
+    #
+    # @return [String]
+    def host
+      @primary_pool.host
+    end
+
+    # The port used for this connection.
+    #
+    # @return [Integer]
+    def port
+      @primary_pool.port
+    end
+
     # Fsync, then lock the mongod process against writes. Use this to get
     # the datafiles in a state safe for snapshotting, backing up, etc.
     #
@@ -329,13 +345,22 @@ module Mongo
       self["admin"].command(oh)
     end
 
-        # Get the build information for the current connection.
+    # Checks if a server is alive. This command will return immediately 
+    # even if the server is in a lock.
+    #
+    # @return [Hash]
+    def ping
+      self["admin"].command({:ping => 1})
+    end
+
+    # Get the build information for the current connection.
     #
     # @return [Hash]
     def server_info
       self["admin"].command({:buildinfo => 1})
     end
 
+
     # Get the build version of the current server.
     #
     # @return [Mongo::ServerVersion]
@@ -450,7 +475,7 @@ module Mongo
     #
     # @raise [ConnectionFailure] if unable to connect to any host or port.
     def connect
-      reset_connection
+      close
 
       config = check_is_master(@host_to_try)
       if config
@@ -482,6 +507,22 @@ module Mongo
       @primary_pool && @primary_pool.host && @primary_pool.port
     end
 
+    # Determine if the connection is active. In a normal case the *server_info* operation
+    # will be performed without issues, but if the connection was dropped by the server or
+    # for some reason the sockets are unsynchronized, a ConnectionFailure will be raised and
+    # the return will be false.
+    #
+    # @return [Boolean]
+    def active?
+      return false unless connected?
+
+      ping
+      true
+
+      rescue ConnectionFailure
+      false
+    end
+
     # Determine whether we're reading from a primary node. If false,
     # this connection connects to a secondary node and @slave_ok is true.
     #
@@ -495,6 +536,7 @@ module Mongo
     def close
       @primary_pool.close if @primary_pool
       @primary_pool = nil
+      @primary = nil
     end
 
     # Returns the maximum BSON object size as returned by the core server.
@@ -559,6 +601,9 @@ module Mongo
       @pool_size = opts[:pool_size] || 1
       @timeout   = opts[:timeout]   || 5.0
 
+      # Timeout on socket read operation.
+      @op_timeout = opts[:op_timeout] || nil
+
       # Mutex for synchronizing pool access
       @connection_mutex = Mutex.new
 
@@ -611,7 +656,7 @@ module Mongo
       msg += payload.values_at(:selector, :document, :documents, :fields ).compact.map(&:inspect).join(', ') + ")"
       msg += ".skip(#{payload[:skip]})"  if payload[:skip]
       msg += ".limit(#{payload[:limit]})"  if payload[:limit]
-      msg += ".sort(#{payload[:sort]})"  if payload[:sort]
+      msg += ".sort(#{payload[:order]})"  if payload[:order]
       @logger.debug "MONGODB #{msg}"
     end
 
@@ -624,7 +669,6 @@ module Mongo
     # TODO: evaluate whether this method is actually necessary
     def reset_connection
       close
-      @primary = nil
     end
 
     def check_is_master(node)
@@ -793,20 +837,37 @@ module Mongo
     # Requires length and an available socket.
     def receive_message_on_socket(length, socket)
       begin
-        message = new_binary_string
-        socket.read(length, message)
-        raise ConnectionFailure, "connection closed" unless message && message.length > 0
-        if message.length < length
-          chunk = new_binary_string
-          while message.length < length
-            socket.read(length - message.length, chunk)
-            raise ConnectionFailure, "connection closed" unless chunk.length > 0
-            message << chunk
+        if @op_timeout
+          message = nil
+          Mongo::TimeoutHandler.timeout(@op_timeout, OperationTimeout) do
+            message = receive_data(length, socket)
           end
+        else
+          message = receive_data(length, socket)
         end
         rescue => ex
           close
-          raise ConnectionFailure, "Operation failed with the following exception: #{ex}"
+
+          if ex.class == OperationTimeout
+            raise OperationTimeout, "Timed out waiting on socket read."
+          else
+            raise ConnectionFailure, "Operation failed with the following exception: #{ex}"
+          end
+      end
+      message
+    end
+
+    def receive_data(length, socket)
+      message = new_binary_string
+      socket.read(length, message)
+      raise ConnectionFailure, "connection closed" unless message && message.length > 0
+      if message.length < length
+        chunk = new_binary_string
+        while message.length < length
+          socket.read(length - message.length, chunk)
+          raise ConnectionFailure, "connection closed" unless chunk.length > 0
+          message << chunk
+        end
       end
       message
     end

data/lib/mongo/cursor.rb

@@ -23,7 +23,7 @@ module Mongo
 
     attr_reader :collection, :selector, :fields,
       :order, :hint, :snapshot, :timeout,
-      :full_collection_name
+      :full_collection_name, :transformer
 
     # Create a new cursor.
     #
@@ -34,6 +34,8 @@ module Mongo
     #
     # @core cursors constructor_details
     def initialize(collection, opts={})
+      @cursor_id  = nil
+
       @db         = collection.db
       @collection = collection
       @connection = @db.connection
@@ -52,6 +54,7 @@ module Mongo
       @tailable   = opts[:tailable] || false
       @closed       = false
       @query_run    = false
+      @transformer = opts[:transformer]
       batch_size(opts[:batch_size] || 0)
 
       @full_collection_name = "#{@collection.db.name}.#{@collection.name}"
@@ -86,8 +89,13 @@ module Mongo
         raise OperationFailure, err
       end
 
-      doc
+      if @transformer.nil?
+        doc
+      else
+        @transformer.call(doc) if doc
+      end
     end
+    alias :next :next_document
 
     # Reset this cursor on the server. Cursor options, such as the
     # query string and the values for skip and limit, are preserved.
@@ -307,8 +315,8 @@ module Mongo
     def query_options_hash
       { :selector => @selector,
         :fields   => @fields,
-        :skip     => @skip_num,
-        :limit    => @limit_num,
+        :skip     => @skip,
+        :limit    => @limit,
         :order    => @order,
         :hint     => @hint,
         :snapshot => @snapshot,