mongo 1.1.5 → 1.3.0

data/lib/mongo/connection.rb

@@ -1,7 +1,7 @@
 # encoding: UTF-8
 
 # --
-# Copyright (C) 2008-2010 10gen Inc.
+# Copyright (C) 2008-2011 10gen Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -35,7 +35,7 @@ module Mongo
     STANDARD_HEADER_SIZE = 16
     RESPONSE_HEADER_SIZE = 20
 
-    attr_reader :logger, :size, :auths, :primary, :safe, :primary_pool, :host_to_try
+    attr_reader :logger, :size, :auths, :primary, :safe, :primary_pool, :host_to_try, :pool_size
 
     # Counter for generating unique request ids.
     @@current_request_id = 0
@@ -55,18 +55,21 @@ module Mongo
     # @param [String, Hash] host.
     # @param [Integer] port specify a port number here if only one host is being specified.
     #
-    # @option options [Boolean, Hash] :safe (false) Set the default safe-mode options
+    # @option opts [Boolean, Hash] :safe (false) Set the default safe-mode options
     #   propogated to DB objects instantiated off of this Connection. This
     #   default can be overridden upon instantiation of any DB by explicity setting a :safe value
     #   on initialization.
-    # @option options [Boolean] :slave_ok (false) Must be set to +true+ when connecting
+    # @option opts [Boolean] :slave_ok (false) Must be set to +true+ when connecting
     #   to a single, slave node.
-    # @option options [Logger, #debug] :logger (nil) Logger instance to receive driver operation log.
-    # @option options [Integer] :pool_size (1) The maximum number of socket connections allowed per
+    # @option opts [Logger, #debug] :logger (nil) A Logger instance for debugging driver ops. Note that
+    #   logging negatively impacts performance; therefore, it should not be used for high-performance apps.
+    # @option opts [Integer] :pool_size (1) The maximum number of socket connections allowed per
     #   connection pool. Note: this setting is relevant only for multi-threaded applications.
-    # @option options [Float] :timeout (5.0) When all of the connections a pool are checked out,
+    # @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
@@ -86,16 +89,16 @@ module Mongo
     #   driver fails to connect to a replica set with that name.
     #
     # @core connections
-    def initialize(host=nil, port=nil, options={})
+    def initialize(host=nil, port=nil, opts={})
       @host_to_try = format_pair(host, port)
 
       # Host and port of current master.
       @host = @port = nil
 
       # slave_ok can be true only if one node is specified
-      @slave_ok = options[:slave_ok]
+      @slave_ok = opts[:slave_ok]
 
-      setup(options)
+      setup(opts)
     end
 
     # DEPRECATED
@@ -109,9 +112,9 @@ module Mongo
     # @param nodes [Array] An array of arrays, each of which specifies a host and port.
     # @param opts [Hash] Any of the available options that can be passed to Connection.new.
     #
-    # @option options [String] :rs_name (nil) The name of the replica set to connect to. An exception will be
+    # @option opts [String] :rs_name (nil) The name of the replica set to connect to. An exception will be
     #   raised if unable to connect to a replica set with this name.
-    # @option options [Boolean] :read_secondary (false) When true, this connection object will pick a random slave
+    # @option opts [Boolean] :read_secondary (false) When true, this connection object will pick a random slave
     #   to send reads to.
     #
     # @example
@@ -138,20 +141,38 @@ module Mongo
     #
     # @param opts Any of the options available for Connection.new
     #
-    # @return [Mongo::Connection]
-    def self.from_uri(uri, opts={})
-      nodes, auths = Mongo::URIParser.parse(uri)
-      opts.merge!({:auths => auths})
-      if nodes.length == 1
-        Connection.new(nodes[0][0], nodes[0][1], opts)
-      elsif nodes.length > 1
-        nodes << opts
-        ReplSetConnection.new(*nodes)
+    # @return [Mongo::Connection, Mongo::ReplSetConnection]
+    def self.from_uri(string, extra_opts={})
+      uri = URIParser.new(string)
+      opts = uri.connection_options
+      opts.merge!(extra_opts)
+
+      if uri.nodes.length == 1
+        opts.merge!({:auths => uri.auths})
+        Connection.new(uri.nodes[0][0], uri.nodes[0][1], opts)
+      elsif uri.nodes.length > 1
+        nodes = uri.nodes.clone
+        nodes_with_opts = nodes << opts
+        ReplSetConnection.new(*nodes_with_opts)
       else
         raise MongoArgumentError, "No nodes specified. Please ensure that you've provided at least one node."
       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.
     #
@@ -184,10 +205,11 @@ module Mongo
     #
     # @raise [AuthenticationError] raises an exception if any one
     #   authentication fails.
-    def apply_saved_authentication
+    def apply_saved_authentication(opts={})
       return false if @auths.empty?
       @auths.each do |auth|
-        self[auth['db_name']].authenticate(auth['username'], auth['password'], false)
+        self[auth['db_name']].issue_authentication(auth['username'], auth['password'], false,
+          :socket => opts[:socket])
       end
       true
     end
@@ -237,6 +259,14 @@ module Mongo
       true
     end
 
+    def authenticate_pools
+      @primary_pool.authenticate_existing
+    end
+
+    def logout_pools(db)
+      @primary_pool.logout_existing(db)
+    end
+
     # Return a hash with all database names
     # and their respective sizes on disk.
     #
@@ -259,12 +289,13 @@ module Mongo
     # See DB#new for valid options hash parameters.
     #
     # @param [String] db_name a valid database name.
+    # @param [Hash] opts options to be passed to the DB constructor.
     #
     # @return [Mongo::DB]
     #
     # @core databases db-instance_method
-    def db(db_name, options={})
-      DB.new(db_name, self, options)
+    def db(db_name, opts={})
+      DB.new(db_name, self, opts)
     end
 
     # Shortcut for returning a database. Use DB#db to accept options.
@@ -314,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]
@@ -406,7 +446,13 @@ module Mongo
       request_id = add_message_headers(message, operation)
       packed_message = message.to_s
       begin
-        sock = socket || (command ? checkout_writer : checkout_reader)
+        if socket
+          sock = socket
+          checkin = false
+        else
+          sock = (command ? checkout_writer : checkout_reader)
+          checkin = true
+        end
 
         result = ''
         @safe_mutexes[sock].synchronize do
@@ -414,7 +460,9 @@ module Mongo
           result = receive(sock, request_id)
         end
       ensure
-        command ? checkin_writer(sock) : checkin_reader(sock)
+        if checkin
+          command ? checkin_writer(sock) : checkin_reader(sock)
+        end
       end
       result
     end
@@ -427,17 +475,26 @@ 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 is_primary?(config)
+      if config
+        if config['ismaster'] == 1 || config['ismaster'] == true
+          @read_primary = true
+        elsif @slave_ok
+          @read_primary = false
+        end
+
         set_primary(@host_to_try)
       end
 
-      if !connected?
+      if connected?
+        BSON::BSON_CODER.update_max_bson_size(self)
+      else
         raise ConnectionFailure, "Failed to connect to a master node at #{@host_to_try[0]}:#{@host_to_try[1]}"
       end
     end
+    alias :reconnect :connect
 
     def connecting?
       @nodes_to_try.length > 0
@@ -450,10 +507,45 @@ 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.
+    #
+    # @return [Boolean]
+    def read_primary?
+      @read_primary
+    end
+    alias :primary? :read_primary?
+
     # Close the connection to the database.
     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.
+    # Use the 4MB default when the server doesn't report this.
+    #
+    # @return [Integer]
+    def max_bson_size
+      config = self['admin'].command({:ismaster => 1})
+      config['maxBsonObjectSize'] || Mongo::DEFAULT_MAX_BSON_SIZE
     end
 
     # Checkout a socket for reading (i.e., a secondary node).
@@ -486,26 +578,37 @@ module Mongo
       end
     end
 
+    # Execute the block and log the operation described by name
+    # and payload.
+    # TODO: Not sure if this should take a block.
+    def instrument(name, payload = {}, &blk)
+      res = yield
+      log_operation(name, payload)
+      res
+    end
+
     protected
 
     # Generic initialization code.
-    # @protected
-    def setup(options)
+    def setup(opts)
       # Authentication objects
-      @auths = options.fetch(:auths, [])
+      @auths = opts.fetch(:auths, [])
 
       # Lock for request ids.
       @id_lock = Mutex.new
 
       # Pool size and timeout.
-      @pool_size = options[:pool_size] || 1
-      @timeout   = options[:timeout]   || 5.0
+      @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
 
       # Global safe option. This is false by default.
-      @safe = options[:safe] || false
+      @safe = opts[:safe] || false
 
       # Create a mutex when a new key, in this case a socket,
       # is added to the hash.
@@ -518,9 +621,14 @@ module Mongo
       @primary      = nil
       @primary_pool = nil
 
-      @logger   = options[:logger] || nil
+      @logger = opts[:logger] || nil
 
-      should_connect = options.fetch(:connect, true)
+      if @logger
+        @logger.debug("MongoDB logging. Please note that logging negatively impacts performance " +
+        "and should be disabled for high-performance production apps.")
+      end
+
+      should_connect = opts.fetch(:connect, true)
       connect if should_connect
     end
 
@@ -540,6 +648,18 @@ module Mongo
       end
     end
 
+    ## Logging methods
+
+    def log_operation(name, payload)
+      return unless @logger
+      msg = "#{payload[:database]}['#{payload[:collection]}'].#{name}("
+      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[:order]})"  if payload[:order]
+      @logger.debug "MONGODB #{msg}"
+    end
+
     private
 
     ## Methods for establishing a connection:
@@ -549,17 +669,6 @@ module Mongo
     # TODO: evaluate whether this method is actually necessary
     def reset_connection
       close
-      @primary = nil
-    end
-
-    # Primary is defined as either a master node or a slave if
-    # :slave_ok has been set to +true+.
-    #
-    # If a primary node is discovered, we set the the @host and @port and
-    # apply any saved authentication.
-    # TODO: simplify
-    def is_primary?(config)
-      config && (config['ismaster'] == 1 || config['ismaster'] == true) || @slave_ok
     end
 
     def check_is_master(node)
@@ -568,7 +677,7 @@ module Mongo
         socket = TCPSocket.new(host, port)
         socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
 
-        config = self['admin'].command({:ismaster => 1}, :sock => socket)
+        config = self['admin'].command({:ismaster => 1}, :socket => socket)
       rescue OperationFailure, SocketError, SystemCallError, IOError => ex
         close
       ensure
@@ -578,16 +687,13 @@ module Mongo
       config
     end
 
-    # Set the specified node as primary, and
-    # apply any saved authentication credentials.
+    # Set the specified node as primary.
     def set_primary(node)
       host, port = *node
       @primary = [host, port]
       @primary_pool = Pool.new(self, host, port, :size => @pool_size, :timeout => @timeout)
-      apply_saved_authentication
     end
 
-
     ## Low-level connection methods.
 
     def receive(sock, expected_response)
@@ -673,7 +779,7 @@ module Mongo
     #
     # Note: this method modifies message by reference.
     #
-    # @returns [Integer] the request id used in the header
+    # @return [Integer] the request id used in the header
     def add_message_headers(message, operation)
       headers = [
         # Message size.
@@ -731,19 +837,37 @@ module Mongo
     # Requires length and an available socket.
     def receive_message_on_socket(length, socket)
       begin
-        message = socket.read(length)
-        raise ConnectionFailure, "connection closed" unless 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

@@ -1,6 +1,6 @@
 # encoding: UTF-8
 
-# Copyright (C) 2008-2010 10gen Inc.
+# Copyright (C) 2008-2011 10gen Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -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.
     #
@@ -33,26 +33,29 @@ module Mongo
     # @return [Cursor]
     #
     # @core cursors constructor_details
-    def initialize(collection, options={})
+    def initialize(collection, opts={})
+      @cursor_id  = nil
+
       @db         = collection.db
       @collection = collection
       @connection = @db.connection
       @logger     = @connection.logger
 
-      @selector   = options[:selector] || {}
-      @fields     = convert_fields_for_query(options[:fields])
-      @skip       = options[:skip]     || 0
-      @limit      = options[:limit]    || 0
-      @order      = options[:order]
-      @hint       = options[:hint]
-      @snapshot   = options[:snapshot]
-      @timeout    = options.has_key?(:timeout) ? options[:timeout] : true
-      @explain    = options[:explain]
-      @socket     = options[:socket]
-      @tailable   = options[:tailable] || false
+      @selector   = opts[:selector] || {}
+      @fields     = convert_fields_for_query(opts[:fields])
+      @skip       = opts[:skip]     || 0
+      @limit      = opts[:limit]    || 0
+      @order      = opts[:order]
+      @hint       = opts[:hint]
+      @snapshot   = opts[:snapshot]
+      @timeout    = opts.fetch(:timeout, true)
+      @explain    = opts[:explain]
+      @socket     = opts[:socket]
+      @tailable   = opts[:tailable] || false
       @closed       = false
       @query_run    = false
-      batch_size(options[:batch_size] || 0)
+      @transformer = opts[:transformer]
+      batch_size(opts[:batch_size] || 0)
 
       @full_collection_name = "#{@collection.db.name}.#{@collection.name}"
       @cache        = []
@@ -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,
@@ -373,18 +381,21 @@ module Mongo
     end
 
     # Run query the first time we request an object from the wire
+    # TODO: should we be calling instrument_payload even if logging
+    # is disabled?
     def send_initial_query
       if @query_run
         false
       else
         message = construct_query_message
-        @logger.debug query_log_message if @logger
-        results, @n_received, @cursor_id = @connection.receive_message(
-          Mongo::Constants::OP_QUERY, message, nil, @socket, @command)
-        @returned += @n_received
-        @cache += results
-        @query_run = true
-        close_cursor_if_query_complete
+        @connection.instrument(:find, instrument_payload) do
+          results, @n_received, @cursor_id = @connection.receive_message(
+            Mongo::Constants::OP_QUERY, message, nil, @socket, @command)
+          @returned += @n_received
+          @cache += results
+          @query_run = true
+          close_cursor_if_query_complete
+        end
         true
       end
     end
@@ -401,10 +412,13 @@ module Mongo
       message
     end
 
-    def query_log_message
-      "#{@db.name}['#{@collection.name}'].find(#{@selector.inspect}, #{@fields ? @fields.inspect : '{}'})" +
-      "#{@skip != 0 ? ('.skip(' + @skip.to_s + ')') : ''}#{@limit != 0 ? ('.limit(' + @limit.to_s + ')') : ''}" +
-      "#{@order ? ('.sort(' + @order.inspect + ')') : ''}"
+    def instrument_payload
+      log = { :database => @db.name, :collection => @collection.name, :selector => selector }
+      log[:fields] = @fields  if @fields
+      log[:skip] = @skip  if @skip && (@skip > 0)
+      log[:limit] = @limit  if @limit && (@limit > 0)
+      log[:order] = @order  if @order
+      log
     end
 
     def construct_query_spec