mongo 1.0 → 1.1.5

data/lib/mongo/connection.rb

@@ -1,3 +1,5 @@
+# encoding: UTF-8
+
 # --
 # Copyright (C) 2008-2010 10gen Inc.
 #
@@ -22,6 +24,9 @@ module Mongo
 
   # Instantiates and manages connections to MongoDB.
   class Connection
+    TCPSocket = ::TCPSocket
+    Mutex = ::Mutex
+    ConditionVariable = ::ConditionVariable
 
     # Abort connections if a ConnectionError is raised.
     Thread.abort_on_exception = true
@@ -30,34 +35,38 @@ module Mongo
     STANDARD_HEADER_SIZE = 16
     RESPONSE_HEADER_SIZE = 20
 
-    MONGODB_URI_MATCHER = /(([.\w\d]+):([\w\d]+)@)?([.\w\d]+)(:([\w\d]+))?(\/([-\d\w]+))?/
-    MONGODB_URI_SPEC = "mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/database]"
-
-    attr_reader :logger, :size, :host, :port, :nodes, :auths, :sockets, :checked_out
+    attr_reader :logger, :size, :auths, :primary, :safe, :primary_pool, :host_to_try
 
     # Counter for generating unique request ids.
     @@current_request_id = 0
 
-    # Create a connection to MongoDB. Specify either one or a pair of servers,
-    # along with a maximum connection pool size and timeout.
+    # Create a connection to single MongoDB instance.
     #
-    # If connecting to just one server, you may specify whether connection to slave is permitted.
+    # You may specify whether connection to slave is permitted.
     # In all cases, the default host is "localhost" and the default port is 27017.
     #
-    # To specify a pair, use Connection.paired.
+    # If you're connecting to a replica set, you'll need to use ReplSetConnection.new instead.
     #
-    # Note that there are a few issues when using connection pooling with Ruby 1.9 on Windows. These
-    # should be resolved in the next release.
+    # Once connected to a replica set, you can find out which nodes are primary, secondary, and
+    # arbiters with the corresponding accessors: Connection#primary, Connection#secondaries, and
+    # Connection#arbiters. This is useful if your application needs to connect manually to nodes other
+    # than the primary.
     #
     # @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
+    #   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
     #   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 that can be opened to the database.
-    # @option options [Float] :timeout (5.0) When all of the connections to the pool are checked out,
+    # @option options [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,
     #   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).
     #
     # @example localhost, 27017
     #   Connection.new
@@ -71,71 +80,55 @@ module Mongo
     # @example localhost, 3000, where this node may be a slave
     #   Connection.new("localhost", 3000, :slave_ok => true)
     #
-    # @see http://www.mongodb.org/display/DOCS/Replica+Pairs+in+Ruby Replica pairs in Ruby
+    # @see http://api.mongodb.org/ruby/current/file.REPLICA_SETS.html Replica sets in Ruby
+    #
+    # @raise [ReplicaSetConnectionError] This is raised if a replica set name is specified and the
+    #   driver fails to connect to a replica set with that name.
     #
     # @core connections
     def initialize(host=nil, port=nil, options={})
-      @auths        = []
-
-      if block_given?
-        @nodes = yield self
-      else
-        @nodes = format_pair(host, port)
-      end
+      @host_to_try = format_pair(host, port)
 
       # Host and port of current master.
       @host = @port = nil
 
-      # Lock for request ids.
-      @id_lock = Mutex.new
-
-      # Pool size and timeout.
-      @size      = options[:pool_size] || 1
-      @timeout   = options[:timeout]   || 5.0
-
-      # Mutex for synchronizing pool access
-      @connection_mutex = Mutex.new
-      @safe_mutex = Mutex.new
-
-      # Condition variable for signal and wait
-      @queue = ConditionVariable.new
-
-      @sockets      = []
-      @checked_out  = []
-
       # slave_ok can be true only if one node is specified
-      @slave_ok = options[:slave_ok] && @nodes.length == 1
-      @logger   = options[:logger] || nil
-      @options  = options
+      @slave_ok = options[:slave_ok]
 
-      should_connect = options[:connect].nil? ? true : options[:connect]
-      connect_to_master if should_connect
+      setup(options)
     end
 
-    # Initialize a paired connection to MongoDB.
+    # DEPRECATED
     #
-    # @param nodes [Array] An array of arrays, each of which specified a host and port.
-    # @param opts Takes the same options as Connection.new
+    # Initialize a connection to a MongoDB replica set using an array of seed nodes.
     #
-    # @example
-    #   Connection.paired([["db1.example.com", 27017],
-    #                   ["db2.example.com", 27017]])
+    # The seed nodes specified will be used on the initial connection to the replica set, but note
+    # that this list of nodes will be replced by the list of canonical nodes returned by running the
+    # is_master command on the replica set.
+    #
+    # @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
+    #   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
+    #   to send reads to.
     #
     # @example
-    #   Connection.paired([["db1.example.com", 27017],
-    #                   ["db2.example.com", 27017]],
-    #                   :pool_size => 20, :timeout => 5)
+    #   Connection.multi([["db1.example.com", 27017], ["db2.example.com", 27017]])
+    #
+    # @example This connection will read from a random secondary node.
+    #   Connection.multi([["db1.example.com", 27017], ["db2.example.com", 27017], ["db3.example.com", 27017]],
+    #                   :read_secondary => true)
     #
     # @return [Mongo::Connection]
-    def self.paired(nodes, opts={})
-      unless nodes.length == 2 && nodes.all? {|n| n.is_a? Array}
-        raise MongoArgumentError, "Connection.paired requires that exactly two nodes be specified."
-      end
-      # Block returns an array, the first element being an array of nodes and the second an array
-      # of authorizations for the database.
-      new(nil, nil, opts) do |con|
-        [con.pair_val_to_connection(nodes[0]), con.pair_val_to_connection(nodes[1])]
-      end
+    #
+    # @deprecated
+    def self.multi(nodes, opts={})
+      warn "Connection.multi is now deprecated. Please use ReplSetConnection.new instead."
+
+      nodes << opts
+      ReplSetConnection.new(*nodes)
     end
 
     # Initialize a connection to MongoDB using the MongoDB URI spec:
@@ -147,11 +140,43 @@ module Mongo
     #
     # @return [Mongo::Connection]
     def self.from_uri(uri, opts={})
-      new(nil, nil, opts) do |con|
-        con.parse_uri(uri)
+      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)
+      else
+        raise MongoArgumentError, "No nodes specified. Please ensure that you've provided at least one node."
       end
     end
 
+    # Fsync, then lock the mongod process against writes. Use this to get
+    # the datafiles in a state safe for snapshotting, backing up, etc.
+    #
+    # @return [BSON::OrderedHash] the command response
+    def lock!
+      cmd = BSON::OrderedHash.new
+      cmd[:fsync] = 1
+      cmd[:lock]  = true
+      self['admin'].command(cmd)
+    end
+
+    # Is this database locked against writes?
+    #
+    # @return [Boolean]
+    def locked?
+      self['admin']['$cmd.sys.inprog'].find_one['fsyncLock'] == 1
+    end
+
+    # Unlock a previously fsync-locked mongod process.
+    #
+    # @return [BSON::OrderedHash] command response
+    def unlock!
+      self['admin']['$cmd.sys.unlock'].find_one
+    end
+
     # Apply each of the saved database authentications.
     #
     # @return [Boolean] returns true if authentications exist and succeeed, false
@@ -172,6 +197,9 @@ module Mongo
     # specificed in the list of auths. This method is called automatically
     # by DB#authenticate.
     #
+    # Note: this method will not actually issue an authentication command. To do that,
+    # either run Connection#apply_saved_authentication or DB#authenticate.
+    #
     # @param [String] db_name
     # @param [String] username
     # @param [String] password
@@ -214,9 +242,9 @@ module Mongo
     #
     # @return [Hash]
     def database_info
-      doc = self['admin'].command({:listDatabases => 1}, false, true)
-      returning({}) do |info|
-        doc['databases'].each { |db| info[db['name']] = db['sizeOnDisk'].to_i }
+      doc = self['admin'].command({:listDatabases => 1})
+      doc['databases'].each_with_object({}) do |db, info|
+        info[db['name']] = db['sizeOnDisk'].to_i
       end
     end
 
@@ -236,7 +264,7 @@ module Mongo
     #
     # @core databases db-instance_method
     def db(db_name, options={})
-      DB.new(db_name, self, options.merge(:logger => @logger))
+      DB.new(db_name, self, options)
     end
 
     # Shortcut for returning a database. Use DB#db to accept options.
@@ -247,7 +275,7 @@ module Mongo
     #
     # @core databases []-instance_method
     def [](db_name)
-      DB.new(db_name, self, :logger => @logger)
+      DB.new(db_name, self, :safe => @safe)
     end
 
     # Drop a database.
@@ -266,7 +294,7 @@ module Mongo
     # @param [String] username username for authentication against from_db (>=1.3.x).
     # @param [String] password password for authentication against from_db (>=1.3.x).
     def copy_database(from, to, from_host="localhost", username=nil, password=nil)
-      oh = OrderedHash.new
+      oh = BSON::OrderedHash.new
       oh[:copydb]   = 1
       oh[:fromhost] = from_host
       oh[:fromdb]   = from
@@ -275,33 +303,22 @@ module Mongo
         unless username && password
           raise MongoArgumentError, "Both username and password must be supplied for authentication."
         end
-        nonce_cmd = OrderedHash.new
+        nonce_cmd = BSON::OrderedHash.new
         nonce_cmd[:copydbgetnonce] = 1
         nonce_cmd[:fromhost] = from_host
-        result = self["admin"].command(nonce_cmd, true, true)
+        result = self["admin"].command(nonce_cmd)
         oh[:nonce] = result["nonce"]
         oh[:username] = username
         oh[:key] = Mongo::Support.auth_key(username, password, oh[:nonce])
       end
-      self["admin"].command(oh, true, true)
+      self["admin"].command(oh)
     end
 
-    # Increment and return the next available request id.
-    #
-    # return [Integer]
-    def get_request_id
-      request_id = ''
-      @id_lock.synchronize do
-        request_id = @@current_request_id += 1
-      end
-      request_id
-    end
-
-    # Get the build information for the current connection.
+        # Get the build information for the current connection.
     #
     # @return [Hash]
     def server_info
-      self["admin"].command({:buildinfo => 1}, false, true)
+      self["admin"].command({:buildinfo => 1})
     end
 
     # Get the build version of the current server.
@@ -319,24 +336,20 @@ module Mongo
       @slave_ok
     end
 
-
-    ## Connections and pooling ##
-
     # Send a message to MongoDB, adding the necessary headers.
     #
     # @param [Integer] operation a MongoDB opcode.
     # @param [BSON::ByteBuffer] message a message to send to the database.
-    # @param [String] log_message text version of +message+ for logging.
     #
-    # @return [True]
+    # @return [Integer] number of bytes sent
     def send_message(operation, message, log_message=nil)
-      @logger.debug("  MONGODB #{log_message || message}") if @logger
       begin
-        packed_message = add_message_headers(operation, message).to_s
-        socket = checkout
+        add_message_headers(message, operation)
+        packed_message = message.to_s
+        socket = checkout_writer
         send_message_on_socket(packed_message, socket)
       ensure
-        checkin(socket)
+        checkin_writer(socket)
       end
     end
 
@@ -346,55 +359,62 @@ module Mongo
     # @param [Integer] operation a MongoDB opcode.
     # @param [BSON::ByteBuffer] message a message to send to the database.
     # @param [String] db_name the name of the database. used on call to get_last_error.
-    # @param [String] log_message text version of +message+ for logging.
+    # @param [Hash] last_error_params parameters to be sent to getLastError. See DB#error for
+    #   available options.
     #
-    # @return [Array]
-    #   An array whose indexes include [0] documents returned, [1] number of document received,
-    #   and [3] a cursor_id.
-    def send_message_with_safe_check(operation, message, db_name, log_message=nil)
-      message_with_headers = add_message_headers(operation, message)
-      message_with_check   = last_error_message(db_name)
-      @logger.debug("  MONGODB #{log_message || message}") if @logger
+    # @see DB#get_last_error for valid last error params.
+    #
+    # @return [Hash] The document returned by the call to getlasterror.
+    def send_message_with_safe_check(operation, message, db_name, log_message=nil, last_error_params=false)
+      docs = num_received = cursor_id = ''
+      add_message_headers(message, operation)
+
+      last_error_message = BSON::ByteBuffer.new
+      build_last_error_message(last_error_message, db_name, last_error_params)
+      last_error_id = add_message_headers(last_error_message, Mongo::Constants::OP_QUERY)
+
+      packed_message = message.append!(last_error_message).to_s
       begin
-        sock = checkout
-        packed_message = message_with_headers.append!(message_with_check).to_s
-        docs = num_received = cursor_id = ''
-        @safe_mutex.synchronize do
+        sock = checkout_writer
+        @safe_mutexes[sock].synchronize do
           send_message_on_socket(packed_message, sock)
-          docs, num_received, cursor_id = receive(sock)
+          docs, num_received, cursor_id = receive(sock, last_error_id)
         end
       ensure
-        checkin(sock)
+        checkin_writer(sock)
       end
-      if num_received == 1 && error = docs[0]['err']
-        raise Mongo::OperationFailure, error
+
+      if num_received == 1 && (error = docs[0]['err'] || docs[0]['errmsg'])
+        close if error == "not master"
+        error = "wtimeout" if error == "timeout"
+        raise Mongo::OperationFailure, docs[0]['code'].to_s + ': ' + error
       end
-      [docs, num_received, cursor_id]
+
+      docs[0]
     end
 
     # Sends a message to the database and waits for the response.
     #
     # @param [Integer] operation a MongoDB opcode.
     # @param [BSON::ByteBuffer] message a message to send to the database.
-    # @param [String] log_message text version of +message+ for logging.
     # @param [Socket] socket a socket to use in lieu of checking out a new one.
     #
     # @return [Array]
     #   An array whose indexes include [0] documents returned, [1] number of document received,
     #   and [3] a cursor_id.
-    def receive_message(operation, message, log_message=nil, socket=nil)
-      packed_message = add_message_headers(operation, message).to_s
-      @logger.debug("  MONGODB #{log_message || message}") if @logger
+    def receive_message(operation, message, log_message=nil, socket=nil, command=false)
+      request_id = add_message_headers(message, operation)
+      packed_message = message.to_s
       begin
-        sock = socket || checkout
+        sock = socket || (command ? checkout_writer : checkout_reader)
 
         result = ''
-        @safe_mutex.synchronize do
+        @safe_mutexes[sock].synchronize do
           send_message_on_socket(packed_message, sock)
-          result = receive(sock)
+          result = receive(sock, request_id)
         end
       ensure
-        checkin(sock)
+        command ? checkin_writer(sock) : checkin_reader(sock)
       end
       result
     end
@@ -402,282 +422,305 @@ module Mongo
     # Create a new socket and attempt to connect to master.
     # If successful, sets host and port to master and returns the socket.
     #
+    # If connecting to a replica set, this method will replace the
+    # initially-provided seed list with any nodes known to the set.
+    #
     # @raise [ConnectionFailure] if unable to connect to any host or port.
-    def connect_to_master
-      close
-      @host = @port = nil
-      for node_pair in @nodes
-        host, port = *node_pair
-        begin
-          socket = TCPSocket.new(host, port)
-          socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
-
-          # If we're connected to master, set the @host and @port
-          result = self['admin'].command({:ismaster => 1}, false, false, socket)
-          if result['ok'] == 1 && ((is_master = result['ismaster'] == 1) || @slave_ok)
-            @host, @port = host, port
-            apply_saved_authentication
-          end
+    def connect
+      reset_connection
 
-          # Note: slave_ok can be true only when connecting to a single node.
-          if @nodes.length == 1 && !is_master && !@slave_ok
-            raise ConfigurationError, "Trying to connect directly to slave; " +
-              "if this is what you want, specify :slave_ok => true."
-          end
+      config = check_is_master(@host_to_try)
+      if is_primary?(config)
+        set_primary(@host_to_try)
+      end
 
-          break if is_master || @slave_ok
-        rescue SocketError, SystemCallError, IOError => ex
-          socket.close if socket
-          close
-          false
-        end
+      if !connected?
+        raise ConnectionFailure, "Failed to connect to a master node at #{@host_to_try[0]}:#{@host_to_try[1]}"
       end
-      raise ConnectionFailure, "failed to connect to any given host:port" unless socket
     end
 
-    # Are we connected to MongoDB? This is determined by checking whether
-    # host and port have values, since they're set to nil on calls to #close.
+    def connecting?
+      @nodes_to_try.length > 0
+    end
+
+    # It's possible that we defined connected as all nodes being connected???
+    # NOTE: Do check if this needs to be more stringent.
+    # Probably not since if any node raises a connection failure, all nodes will be closed.
     def connected?
-      @host && @port
+      @primary_pool && @primary_pool.host && @primary_pool.port
     end
 
     # Close the connection to the database.
     def close
-      @sockets.each do |sock|
-        sock.close
-      end
-      @host = @port = nil
-      @sockets.clear
-      @checked_out.clear
+      @primary_pool.close if @primary_pool
+      @primary_pool = nil
     end
 
-    ## Configuration helper methods
+    # Checkout a socket for reading (i.e., a secondary node).
+    # Note: this is overridden in ReplSetConnection.
+    def checkout_reader
+      connect unless connected?
+      @primary_pool.checkout
+    end
 
-    # Returns an array of host-port pairs.
-    #
-    # @private
-    def format_pair(pair_or_host, port)
-      case pair_or_host
-        when String
-          [[pair_or_host, port ? port.to_i : DEFAULT_PORT]]
-        when nil
-          [['localhost', DEFAULT_PORT]]
-      end
+    # Checkout a socket for writing (i.e., a primary node).
+    # Note: this is overridden in ReplSetConnection.
+    def checkout_writer
+      connect unless connected?
+      @primary_pool.checkout
     end
 
-    # Convert an argument containing a host name string and a
-    # port number integer into a [host, port] pair array.
-    #
-    # @private
-    def pair_val_to_connection(a)
-      case a
-      when nil
-        ['localhost', DEFAULT_PORT]
-      when String
-        [a, DEFAULT_PORT]
-      when Integer
-        ['localhost', a]
-      when Array
-        a
+    # Checkin a socket used for reading.
+    # Note: this is overridden in ReplSetConnection.
+    def checkin_reader(socket)
+      if @primary_pool
+        @primary_pool.checkin(socket)
       end
     end
 
-    # Parse a MongoDB URI. This method is used by Connection.from_uri.
-    # Returns an array of nodes and an array of db authorizations, if applicable.
-    #
-    # @private
-    def parse_uri(string)
-      if string =~ /^mongodb:\/\//
-        string = string[10..-1]
-      else
-        raise MongoArgumentError, "MongoDB URI must match this spec: #{MONGODB_URI_SPEC}"
+    # Checkin a socket used for writing.
+    # Note: this is overridden in ReplSetConnection.
+    def checkin_writer(socket)
+      if @primary_pool
+        @primary_pool.checkin(socket)
       end
+    end
 
-      nodes = []
-      auths = []
-      specs = string.split(',')
-      specs.each do |spec|
-        matches  = MONGODB_URI_MATCHER.match(spec)
-        if !matches
-          raise MongoArgumentError, "MongoDB URI must match this spec: #{MONGODB_URI_SPEC}"
-        end
+    protected
 
-        uname = matches[2]
-        pwd   = matches[3]
-        host  = matches[4]
-        port  = matches[6] || DEFAULT_PORT
-        if !(port.to_s =~ /^\d+$/)
-          raise MongoArgumentError, "Invalid port #{port}; port must be specified as digits."
-        end
-        port  = port.to_i
-        db    = matches[8]
-
-        if (uname || pwd || db) && !(uname && pwd && db)
-          raise MongoArgumentError, "MongoDB URI must include all three of username, password, " +
-            "and db if any one of these is specified."
-        else
-          add_auth(db, uname, pwd)
-        end
+    # Generic initialization code.
+    # @protected
+    def setup(options)
+      # Authentication objects
+      @auths = options.fetch(:auths, [])
 
-        nodes << [host, port]
-      end
+      # Lock for request ids.
+      @id_lock = Mutex.new
+
+      # Pool size and timeout.
+      @pool_size = options[:pool_size] || 1
+      @timeout   = options[:timeout]   || 5.0
+
+      # Mutex for synchronizing pool access
+      @connection_mutex = Mutex.new
+
+      # Global safe option. This is false by default.
+      @safe = options[:safe] || false
+
+      # Create a mutex when a new key, in this case a socket,
+      # is added to the hash.
+      @safe_mutexes = Hash.new { |h, k| h[k] = Mutex.new }
+
+      # Condition variable for signal and wait
+      @queue = ConditionVariable.new
+
+      # Connection pool for primay node
+      @primary      = nil
+      @primary_pool = nil
+
+      @logger   = options[:logger] || nil
 
-      nodes
+      should_connect = options.fetch(:connect, true)
+      connect if should_connect
     end
 
-    private
+    ## Configuration helper methods
 
-    # Return a socket to the pool.
-    def checkin(socket)
-      @connection_mutex.synchronize do
-        @checked_out.delete(socket)
-        @queue.signal
+    # Returns a host-port pair.
+    #
+    # @return [Array]
+    #
+    # @private
+    def format_pair(host, port)
+      case host
+        when String
+          [host, port ? port.to_i : DEFAULT_PORT]
+        when nil
+          ['localhost', DEFAULT_PORT]
       end
-      true
     end
 
-    # Adds a new socket to the pool and checks it out.
+    private
+
+    ## Methods for establishing a connection:
+
+    # If a ConnectionFailure is raised, this method will be called
+    # to close the connection and reset connection values.
+    # 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+.
     #
-    # This method is called exclusively from #checkout;
-    # therefore, it runs within a mutex.
-    def checkout_new_socket
+    # 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)
       begin
-      socket = TCPSocket.new(@host, @port)
-      socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
-      rescue => ex
-        raise ConnectionFailure, "Failed to connect socket: #{ex}"
-      end
-      @sockets << socket
-      @checked_out << socket
-      socket
-    end
-
-    # Checks out the first available socket from the pool.
-    #
-    # This method is called exclusively from #checkout;
-    # therefore, it runs within a mutex.
-    def checkout_existing_socket
-      socket = (@sockets - @checked_out).first
-      @checked_out << socket
-      socket
-    end
-
-    # Check out an existing socket or create a new socket if the maximum
-    # pool size has not been exceeded. Otherwise, wait for the next
-    # available socket.
-    def checkout
-      connect_to_master if !connected?
-      start_time = Time.now
-      loop do
-        if (Time.now - start_time) > @timeout
-            raise ConnectionTimeoutError, "could not obtain connection within " +
-              "#{@timeout} seconds. The max pool size is currently #{@size}; " +
-              "consider increasing the pool size or timeout."
-        end
+        host, port = *node
+        socket = TCPSocket.new(host, port)
+        socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
 
-        @connection_mutex.synchronize do
-          socket = if @checked_out.size < @sockets.size
-                     checkout_existing_socket
-                   elsif @sockets.size < @size
-                     checkout_new_socket
-                   end
+        config = self['admin'].command({:ismaster => 1}, :sock => socket)
+      rescue OperationFailure, SocketError, SystemCallError, IOError => ex
+        close
+      ensure
+        socket.close if socket
+      end
 
-          return socket if socket
+      config
+    end
 
-          # Otherwise, wait
-          if @logger
-            @logger.warn "Waiting for available connection; #{@checked_out.size} of #{@size} connections checked out."
-          end
-          @queue.wait(@connection_mutex)
-        end
-      end
+    # Set the specified node as primary, and
+    # apply any saved authentication credentials.
+    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
 
-    def receive(sock)
-      receive_header(sock)
+
+    ## Low-level connection methods.
+
+    def receive(sock, expected_response)
+      begin
+      receive_header(sock, expected_response)
       number_received, cursor_id = receive_response_header(sock)
       read_documents(number_received, cursor_id, sock)
+      rescue Mongo::ConnectionFailure => ex
+        close
+        raise ex
+      end
     end
 
-    def receive_header(sock)
-      header = BSON::ByteBuffer.new
-      header.put_array(receive_message_on_socket(16, sock).unpack("C*"))
+    def receive_header(sock, expected_response)
+      header = receive_message_on_socket(16, sock)
+      size, request_id, response_to = header.unpack('VVV')
+      if expected_response != response_to
+        raise Mongo::ConnectionFailure, "Expected response #{expected_response} but got #{response_to}"
+      end
+
       unless header.size == STANDARD_HEADER_SIZE
         raise "Short read for DB response header: " +
           "expected #{STANDARD_HEADER_SIZE} bytes, saw #{header.size}"
       end
-      header.rewind
-      size        = header.get_int
-      request_id  = header.get_int
-      response_to = header.get_int
-      op          = header.get_int
+      nil
     end
 
     def receive_response_header(sock)
-      header_buf = BSON::ByteBuffer.new
-      header_buf.put_array(receive_message_on_socket(RESPONSE_HEADER_SIZE, sock).unpack("C*"))
+      header_buf = receive_message_on_socket(RESPONSE_HEADER_SIZE, sock)
       if header_buf.length != RESPONSE_HEADER_SIZE
         raise "Short read for DB response header; " +
           "expected #{RESPONSE_HEADER_SIZE} bytes, saw #{header_buf.length}"
       end
-      header_buf.rewind
-      result_flags     = header_buf.get_int
-      cursor_id        = header_buf.get_long
-      starting_from    = header_buf.get_int
-      number_remaining = header_buf.get_int
+      flags, cursor_id_a, cursor_id_b, starting_from, number_remaining = header_buf.unpack('VVVVV')
+      check_response_flags(flags)
+      cursor_id = (cursor_id_b << 32) + cursor_id_a
       [number_remaining, cursor_id]
     end
 
+    def check_response_flags(flags)
+      if flags & Mongo::Constants::REPLY_CURSOR_NOT_FOUND != 0
+        raise Mongo::OperationFailure, "Query response returned CURSOR_NOT_FOUND. " +
+          "Either an invalid cursor was specified, or the cursor may have timed out on the server."
+      elsif flags & Mongo::Constants::REPLY_QUERY_FAILURE != 0
+        # Getting odd failures when a exception is raised here.
+      end
+    end
+
     def read_documents(number_received, cursor_id, sock)
       docs = []
       number_remaining = number_received
       while number_remaining > 0 do
-        buf = BSON::ByteBuffer.new
-        buf.put_array(receive_message_on_socket(4, sock).unpack("C*"))
-        buf.rewind
-        size = buf.get_int
-        buf.put_array(receive_message_on_socket(size - 4, sock).unpack("C*"), 4)
+        buf = receive_message_on_socket(4, sock)
+        size = buf.unpack('V')[0]
+        buf << receive_message_on_socket(size - 4, sock)
         number_remaining -= 1
-        buf.rewind
         docs << BSON::BSON_CODER.deserialize(buf)
       end
       [docs, number_received, cursor_id]
     end
 
-    def last_error_message(db_name)
-      message = BSON::ByteBuffer.new
+    # Constructs a getlasterror message. This method is used exclusively by
+    # Connection#send_message_with_safe_check.
+    #
+    # Because it modifies message by reference, we don't need to return it.
+    def build_last_error_message(message, db_name, opts)
       message.put_int(0)
       BSON::BSON_RUBY.serialize_cstr(message, "#{db_name}.$cmd")
       message.put_int(0)
       message.put_int(-1)
-      message.put_array(BSON::BSON_CODER.serialize({:getlasterror => 1}, false).unpack("C*"))
-      add_message_headers(Mongo::Constants::OP_QUERY, message)
+      cmd = BSON::OrderedHash.new
+      cmd[:getlasterror] = 1
+      if opts.is_a?(Hash)
+        opts.assert_valid_keys(:w, :wtimeout, :fsync)
+        cmd.merge!(opts)
+      end
+      message.put_binary(BSON::BSON_CODER.serialize(cmd, false).to_s)
+      nil
     end
 
     # Prepares a message for transmission to MongoDB by
     # constructing a valid message header.
-    def add_message_headers(operation, message)
-      headers = BSON::ByteBuffer.new
+    #
+    # Note: this method modifies message by reference.
+    #
+    # @returns [Integer] the request id used in the header
+    def add_message_headers(message, operation)
+      headers = [
+        # Message size.
+        16 + message.size,
 
-      # Message size.
-      headers.put_int(16 + message.size)
+        # Unique request id.
+        request_id = get_request_id,
 
-      # Unique request id.
-      headers.put_int(get_request_id)
+        # Response id.
+        0,
 
-      # Response id.
-      headers.put_int(0)
+        # Opcode.
+        operation
+      ].pack('VVVV')
 
-      # Opcode.
-      headers.put_int(operation)
       message.prepend!(headers)
+
+      request_id
+    end
+
+    # Increment and return the next available request id.
+    #
+    # return [Integer]
+    def get_request_id
+      request_id = ''
+      @id_lock.synchronize do
+        request_id = @@current_request_id += 1
+      end
+      request_id
     end
 
     # Low-level method for sending a message on a socket.
     # Requires a packed message and an available socket,
+    #
+    # @return [Integer] number of bytes sent
     def send_message_on_socket(packed_message, socket)
       begin
-      socket.send(packed_message, 0)
+      total_bytes_sent = socket.send(packed_message, 0)
+      if total_bytes_sent != packed_message.size
+        packed_message.slice!(0, total_bytes_sent)
+        while packed_message.size > 0
+          byte_sent = socket.send(packed_message, 0)
+          total_bytes_sent += byte_sent
+          packed_message.slice!(0, byte_sent)
+        end
+      end
+      total_bytes_sent
       rescue => ex
         close
         raise ConnectionFailure, "Operation failed with the following exception: #{ex}"
@@ -687,12 +730,16 @@ module Mongo
     # Low-level method for receiving data from socket.
     # Requires length and an available socket.
     def receive_message_on_socket(length, socket)
-      message = ""
       begin
-        while message.length < length do
-          chunk = socket.recv(length - message.length)
-          raise ConnectionFailure, "connection closed" unless chunk.length > 0
-          message += chunk
+        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
+          end
         end
         rescue => ex
           close
@@ -700,5 +747,17 @@ module Mongo
       end
       message
     end
+
+    if defined?(Encoding)
+      BINARY_ENCODING = Encoding.find("binary")
+
+      def new_binary_string
+        "".force_encoding(BINARY_ENCODING)
+      end
+    else
+      def new_binary_string
+        ""
+      end
+    end
   end
 end