mongo 1.3.1 → 1.4.0

data/lib/mongo/db.rb

@@ -63,7 +63,7 @@ module Mongo
     # @option opts [Boolean] :strict (False) If true, collections must exist to be accessed and must
     #   not exist to be created. See DB#collection and DB#create_collection.
     #
-    # @option opts [Object, #create_pk(doc)] :pk (Mongo::ObjectId) A primary key factory object,
+    # @option opts [Object, #create_pk(doc)] :pk (BSON::ObjectId) A primary key factory object,
     #   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).
@@ -82,6 +82,12 @@ module Mongo
       @strict     = opts[:strict]
       @pk_factory = opts[:pk]
       @safe       = opts.fetch(:safe, @connection.safe)
+      if value = opts[:read]
+        Mongo::Support.validate_read_preference(value)
+      else
+        value = @connection.read_preference
+      end
+      @read_preference = value.is_a?(Hash) ? value.dup : value
       @cache_time = opts[:cache_time] || 300 #5 minutes.
     end
 
@@ -121,13 +127,14 @@ module Mongo
       auth['user'] = username
       auth['nonce'] = nonce
       auth['key'] = Mongo::Support.auth_key(username, password, nonce)
-      if ok?(self.command(auth, :check_response => false, :socket => opts[:socket]))
+      if ok?(doc = self.command(auth, :check_response => false, :socket => opts[:socket]))
         if save_auth
           @connection.add_auth(@name, username, password)
         end
         true
       else
-        raise(Mongo::AuthenticationError, "Failed to authenticate user '#{username}' on db '#{self.name}'")
+        message = "Failed to authenticate user '#{username}' on db '#{self.name}'"
+        raise Mongo::AuthenticationError.new(message, doc['code'], doc)
       end
     end
 
@@ -269,7 +276,8 @@ module Mongo
     #
     # @return [Mongo::Collection]
     def create_collection(name, opts={})
-      if collection_names.include?(name.to_s)
+      name = name.to_s
+      if collection_names.include?(name)
         if strict?
           raise MongoDBError, "Collection #{name} already exists. " +
             "Currently in strict mode."
@@ -503,7 +511,13 @@ module Mongo
       if result.nil?
         raise OperationFailure, "Database command '#{selector.keys.first}' failed: returned null."
       elsif (check_response && !ok?(result))
-        raise OperationFailure, "Database command '#{selector.keys.first}' failed: #{result.inspect}"
+        message = "Database command '#{selector.keys.first}' failed: ("
+        message << result.map do |key, value|
+          "#{key}: '#{value}'"
+        end.join('; ')
+        message << ').'
+        code = result['code'] || result['assertionCode']
+        raise OperationFailure.new(message, code, result)
       else
         result
       end
@@ -608,6 +622,13 @@ module Mongo
       doc
     end
 
+    # The value of the read preference. This will be
+    # either +:primary+, +:secondary+, or an object
+    # representing the tags to be read from.
+    def read_preference
+      @read_preference
+    end
+
     private
 
     def system_command_collection

data/lib/mongo/exceptions.rb

@@ -22,7 +22,20 @@ module Mongo
   class MongoRubyError < StandardError; end
 
   # Raised when MongoDB itself has returned an error.
-  class MongoDBError < RuntimeError; end
+  class MongoDBError < RuntimeError
+
+     # @return The entire failed command's response object, if available.
+     attr_reader :result
+
+     # @return The failed command's error code, if availab.e
+     attr_reader :error_code
+
+     def initialize(message=nil, error_code=nil, result=nil)
+       @error_code = error_code
+       @result = result
+       super(message)
+     end
+  end
 
   # Raised when configuration options cause connections, queries, etc., to fail.
   class ConfigurationError < MongoRubyError; end
@@ -48,6 +61,9 @@ module Mongo
   # Raised on failures in connection to the database server.
   class ConnectionTimeoutError < MongoRubyError; end
 
+  # Raised when no tags in a read preference maps to a given connection.
+  class NodeWithTagsNotFound < MongoRubyError; end
+
   # Raised when a connection operation fails.
   class ConnectionFailure < MongoDBError; end
 

data/lib/mongo/gridfs/grid.rb

@@ -63,7 +63,7 @@ module Mongo
     # @option opts [Boolean] :safe (false) When safe mode is enabled, the chunks sent to the server
     #   will be validated using an md5 hash. If validation fails, an exception will be raised.
     #
-    # @return [Mongo::ObjectId] the file's id.
+    # @return [BSON::ObjectId] the file's id.
     def put(data, opts={})
       opts     = opts.dup
       filename = opts[:filename]

data/lib/mongo/repl_set_connection.rb

@@ -16,11 +16,15 @@
 # limitations under the License.
 # ++
 
+require 'sync'
+
 module Mongo
 
   # Instantiates and manages connections to a MongoDB replica set.
   class ReplSetConnection < Connection
-    attr_reader :nodes, :secondaries, :arbiters, :read_pool, :secondary_pools
+    attr_reader :nodes, :secondaries, :arbiters, :secondary_pools,
+      :replica_set_name, :read_pool, :seeds, :tags_to_pools,
+      :refresh_interval, :refresh_mode
 
     # Create a connection to a MongoDB replica set.
     #
@@ -38,14 +42,30 @@ module Mongo
     #   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] :read_secondary(false) If true, a random secondary node will be chosen,
-    #   and all reads will be directed to that node.
-    # @option options [Logger, #debug] :logger (nil) Logger instance to receive driver operation log.
+    # @option options [:primary, :secondary] :read (:primary) The default read preference for Mongo::DB
+    #   objects created from this connection object. If +:secondary+ is chosen, reads will be sent
+    #   to one of the closest available secondary nodes. If a secondary node cannot be located, the
+    #   read will be sent to the primary.
+    # @option options [Logger] :logger (nil) Logger instance to receive driver operation log.
     # @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,
+    # @option options [Float] :pool_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.
+    # @option opts [Float] :op_timeout (nil) The number of seconds to wait for a read operation to time out.
+    #   Disabled by default.
+    # @option opts [Float] :connect_timeout (nil) The number of seconds to wait before timing out a
+    #   connection attempt.
+    # @option opts [Boolean] :ssl (false) If true, create the connection to the server using SSL.
+    # @option opts [Boolean] :refresh_mode (:sync) Set this to :async to enable a background thread that
+    #   periodically updates the state of the connection. If, for example, you initially connect while a secondary
+    #   is down, this will reconnect to that secondary behind the scenes to
+    #   prevent you from having to reconnect manually. If set to :sync, refresh will happen
+    #   synchronously. If +false+, no automatic refresh will occur unless there's a connection failure.
+    # @option opts [Integer] :refresh_interval (90) If :refresh_mode is enabled, this is the number of seconds
+    #   between calls to check the replica set's state.
+    # @option opts [Boolean] :require_primary (true) If true, require a primary node for the connection
+    #   to succeed. Otherwise, connection will succeed as long as there's at least one secondary node.
     #
     # @example Connect to a replica set and provide two seed nodes. Note that the number of seed nodes does
     #   not have to be equal to the number of replica set members. The purpose of seed nodes is to permit
@@ -63,6 +83,8 @@ module Mongo
     # @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.
     def initialize(*args)
+      extend Sync_m
+
       if args.last.is_a?(Hash)
         opts = args.pop
       else
@@ -70,70 +92,146 @@ module Mongo
       end
 
       unless args.length > 0
-        raise MongoArgumentError, "A ReplSetConnection requires at least one node."
+        raise MongoArgumentError, "A ReplSetConnection requires at least one seed node."
       end
 
-      # Get seed nodes
-      @nodes = args
+      # The list of seed nodes
+      @seeds = args
 
-      # Replica set name
-      @replica_set = opts[:rs_name]
+      # TODO: get rid of this
+      @nodes = @seeds.dup
 
-      # Cache the various node types when connecting to a replica set.
-      @secondaries = []
-      @arbiters    = []
+      # The members of the replica set, stored as instances of Mongo::Node.
+      @members = []
+
+      # Connection pool for primary node
+      @primary      = nil
+      @primary_pool = nil
 
       # Connection pools for each secondary node
+      @secondaries = []
       @secondary_pools = []
+
+      # The secondary pool to which we'll be sending reads.
+      # This may be identical to the primary pool.
       @read_pool = nil
 
+      # A list of arbiter addresses (for client information only)
+      @arbiters = []
+
+      # Refresh
+      @refresh_mode = opts.fetch(:refresh_mode, :sync)
+      @refresh_interval = opts[:refresh_interval] || 90
+
+      if ![:sync, :async, false].include?(@refresh_mode)
+        raise MongoArgumentError,
+          "Refresh mode must be one of :sync, :async, or false."
+      end
+
       # Are we allowing reads from secondaries?
-      @read_secondary = opts.fetch(:read_secondary, false)
-      @slave_okay = false
+      if opts[:read_secondary]
+        warn ":read_secondary options has now been deprecated and will " +
+          "be removed in driver v2.0. Use the :read option instead."
+        @read_secondary = opts.fetch(:read_secondary, false)
+        @read = :secondary
+      else
+        @read = opts.fetch(:read, :primary)
+        Mongo::Support.validate_read_preference(@read)
+      end
+
+      @connected = false
+
+      # Store the refresher thread
+      @refresh_thread = nil
+
+      # Maps
+      @sockets_to_pools = {}
+      @tags_to_pools = {}
+
+      # Replica set name
+      if opts[:rs_name]
+        warn ":rs_name option has been deprecated and will be removed in v2.0. " +
+          "Please use :name instead."
+        @replica_set_name = opts[:rs_name]
+      else
+        @replica_set_name = opts[:name]
+      end
+
+      # Require a primary node to connect?
+      @require_primary = opts.fetch(:require_primary, true)
 
       setup(opts)
     end
 
-    # 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 inspect
+      "<Mongo::ReplSetConnection:0x#{self.object_id.to_s(16)} @seeds=#{@seeds} " +
+        "@connected=#{@connected}>"
+    end
+
+    # Initiate a connection to the replica set.
     def connect
-      close
-      @nodes_to_try = @nodes.clone
+      log(:info, "Connecting...")
+      sync_synchronize(:EX) do
+        return if @connected
+        manager = PoolManager.new(self, @seeds)
+        manager.connect
 
-      while connecting?
-        node   = @nodes_to_try.shift
-        config = check_is_master(node)
+        update_config(manager)
+        initiate_refresh_mode
 
-        if is_primary?(config)
-          set_primary(node)
+        if @require_primary && @primary.nil? #TODO: in v2.0, we'll let this be optional and do a lazy connect.
+          raise ConnectionFailure, "Failed to connect to primary node."
+        elsif !@read_pool
+          raise ConnectionFailure, "Failed to connect to any node."
         else
-          set_auxillary(node, config)
+          @connected = true
         end
       end
+    end
 
-      pick_secondary_for_read if @read_secondary
+    # Note: this method must be called from within
+    # an exclusive lock.
+    def update_config(manager)
+      @arbiters = manager.arbiters.nil? ? [] : manager.arbiters.dup
+      @primary = manager.primary.nil? ? nil : manager.primary.dup
+      @secondaries = manager.secondaries.dup
+      @hosts = manager.hosts.dup
+
+      @primary_pool = manager.primary_pool
+      @read_pool    = manager.read_pool
+      @secondary_pools = manager.secondary_pools
+      @tags_to_pools   = manager.tags_to_pools
+      @seeds = manager.seeds
+      @manager = manager
+      @nodes = manager.nodes
+      @max_bson_size = manager.max_bson_size
+    end
 
-      if connected?
-        BSON::BSON_CODER.update_max_bson_size(self)
-      else
-        if @secondary_pools.empty?
-          close # close any existing pools and sockets
-          raise ConnectionFailure, "Failed to connect any given host:port"
-        else
-          close # close any existing pools and sockets
-          raise ConnectionFailure, "Failed to connect to primary node."
-        end
+    # Refresh the current replica set configuration.
+    def refresh(opts={})
+      return false if !connected?
+
+      # Return if another thread is already in the process of refreshing.
+      return if sync_exclusive?
+
+      sync_synchronize(:EX) do
+        log(:info, "Refreshing...")
+        @background_manager ||= PoolManager.new(self, @seeds)
+        @background_manager.connect
+        update_config(@background_manager)
       end
+
+      return true
     end
-    alias :reconnect :connect
 
+    def connected?
+      !@primary_pool.nil? || !@read_pool.nil?
+    end
+
+    # @deprecated
     def connecting?
-      @nodes_to_try.length > 0
+      warn "ReplSetConnection#connecting? is deprecated and will be removed in v2.0."
+      false
     end
 
     # The replica set primary's host name.
@@ -150,27 +248,59 @@ module Mongo
       super
     end
 
+    def nodes
+      warn "ReplSetConnection#nodes is DEPRECATED and will be removed in v2.0. " +
+        "Please use ReplSetConnection#seeds instead."
+      @seeds
+    end
+
     # Determine whether we're reading from a primary node. If false,
     # this connection connects to a secondary node and @read_secondaries is true.
     #
     # @return [Boolean]
     def read_primary?
-      !@read_pool
+      sync_synchronize(:SH) do
+        @read_pool == @primary_pool
+      end
     end
     alias :primary? :read_primary?
 
+    def read_preference
+      @read
+    end
+
     # Close the connection to the database.
     def close
-      super
-      @read_pool = nil
-      @secondary_pools.each do |pool|
-        pool.close
+      sync_synchronize(:EX) do
+        @connected = false
+        super
+
+        if @refresh_thread
+          @refresh_thread.kill
+          @refresh_thread = nil
+        end
+
+        if @nodes
+          @nodes.each do |member|
+            member.close
+          end
+        end
+
+        @nodes = []
+        @read_pool = nil
+
+        if @secondary_pools
+          @secondary_pools.each do |pool|
+            pool.close
+          end
+        end
+
+        @secondaries     = []
+        @secondary_pools = []
+        @arbiters        = []
+        @tags_to_pools.clear
+        @sockets_to_pools.clear
       end
-      @secondaries     = []
-      @secondary_pools = []
-      @arbiters        = []
-      @nodes_tried  = []
-      @nodes_to_try = []
     end
 
     # If a ConnectionFailure is raised, this method will be called
@@ -178,15 +308,19 @@ module Mongo
     # @deprecated
     def reset_connection
       close
-      warn "ReplSetConnection#reset_connection is now deprecated. " +
+      warn "ReplSetConnection#reset_connection is now deprecated and will be removed in v2.0. " +
         "Use ReplSetConnection#close instead."
     end
 
-    # Is it okay to connect to a slave?
+    # Returns +true+ if it's okay to read from a secondary node.
+    # Since this is a replica set, this must always be true.
     #
-    # @return [Boolean]
+    # This method exist primarily so that Cursor objects will
+    # generate query messages with a slaveOkay value of +true+.
+    #
+    # @return [Boolean] +true+
     def slave_ok?
-      @read_secondary || @slave_ok
+      true
     end
 
     def authenticate_pools
@@ -205,138 +339,121 @@ module Mongo
 
     private
 
-    def check_is_master(node)
-      begin
-        host, port = *node
-        socket = TCPSocket.new(host, port)
-        socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
-
-        config = self['admin'].command({:ismaster => 1}, :socket => socket)
-
-        check_set_name(config, socket)
-      rescue OperationFailure, SocketError, SystemCallError, IOError => ex
-        # It's necessary to rescue here. The #connect method will keep trying
-        # until it has no more nodes to try and raise a ConnectionFailure if
-        # it can't connect to a primary.
-      ensure
-        socket.close if socket
-        @nodes_tried << node
-
-        if config
-          nodes = []
-          nodes += config['hosts'] if config['hosts']
-          nodes += config['arbiters'] if config['arbiters']
-          nodes += config['passives'] if config['passives']
-          update_node_list(nodes)
-
-          if config['msg'] && @logger
-            @logger.warn("MONGODB #{config['msg']}")
+    def initiate_refresh_mode
+      if @refresh_mode == :async
+        return if @refresh_thread && @refresh_thread.alive?
+        @refresh_thread = Thread.new do
+          while true do
+            sleep(@refresh_interval)
+            refresh
           end
         end
       end
 
-      config
-    end
-
-    # Primary, when connecting to a replica can, can only be a true primary node.
-    # (And not a slave, which is possible when connecting with the standard
-    # Connection class.
-    def is_primary?(config)
-      config && (config['ismaster'] == 1 || config['ismaster'] == true)
+      @last_refresh = Time.now
     end
 
-    # Pick a node randomly from the set of possible secondaries.
-    def pick_secondary_for_read
-      if (size = @secondary_pools.size) > 0
-        @read_pool = @secondary_pools[rand(size)]
-      end
-    end
+    # Checkout a socket for reading (i.e., a secondary node).
+    # Note that @read_pool might point to the primary pool
+    # if no read pool has been defined.
+    def checkout_reader
+      connect unless connected?
+      socket = get_socket_from_pool(@read_pool)
 
-    # Make sure that we're connected to the expected replica set.
-    def check_set_name(config, socket)
-      if @replica_set
-        config = self['admin'].command({:replSetGetStatus => 1},
-                   :socket => socket, :check_response => false)
-
-        if !Mongo::Support.ok?(config)
-          raise ReplicaSetConnectionError, config['errmsg']
-        elsif config['set'] != @replica_set
-          raise ReplicaSetConnectionError,
-            "Attempting to connect to replica set '#{config['set']}' but expected '#{@replica_set}'"
-        end
+      if !socket
+        refresh
+        socket = get_socket_from_pool(@primary_pool)
       end
-    end
 
-    # Determines what kind of node we have and caches its host
-    # and port so that users can easily connect manually.
-    def set_auxillary(node, config)
-      if config
-        if config['secondary']
-          host, port = *node
-          @secondaries << node unless @secondaries.include?(node)
-          @secondary_pools << Pool.new(self, host, port, :size => @pool_size, :timeout => @timeout)
-        elsif config['arbiterOnly']
-          @arbiters << node unless @arbiters.include?(node)
-        end
+      if socket
+        socket
+      else
+        raise ConnectionFailure.new("Could not connect to a node for reading.")
       end
     end
 
-    # Update the list of known nodes. Only applies to replica sets,
-    # where the response to the ismaster command will return a list
-    # of known hosts.
+    # Checkout a socket connected to a node with one of
+    # the provided tags. If no such node exists, raise
+    # an exception.
     #
-    # @param hosts [Array] a list of hosts, specified as string-encoded
-    #   host-port values. Example: ["myserver-1.org:27017", "myserver-1.org:27017"]
-    #
-    # @return [Array] the updated list of nodes
-    def update_node_list(hosts)
-      new_nodes = hosts.map do |host|
-        if !host.respond_to?(:split)
-          warn "Could not parse host #{host.inspect}."
-          next
+    # NOTE: will be available in driver release v2.0.
+    def checkout_tagged(tags)
+      sync_synchronize(:SH) do
+        tags.each do |k, v|
+          pool = @tags_to_pools[{k.to_s => v}]
+          if pool
+            socket = pool.checkout
+            @sockets_to_pools[socket] = pool
+            return socket
+          end
         end
-
-        host, port = host.split(':')
-        [host, port ? port.to_i : Connection::DEFAULT_PORT]
       end
 
-      # Replace the list of seed nodes with the canonical list.
-      @nodes = new_nodes.clone
-
-      @nodes_to_try = new_nodes - @nodes_tried
+      raise NodeWithTagsNotFound,
+        "Could not find a connection tagged with #{tags}."
     end
 
-    # Checkout a socket for reading (i.e., a secondary node).
-    def checkout_reader
+    # Checkout a socket for writing (i.e., a primary node).
+    def checkout_writer
       connect unless connected?
+      socket = get_socket_from_pool(@primary_pool)
+
+      if !socket
+        refresh
+        socket = get_socket_from_pool(@primary_pool)
+      end
 
-      if @read_pool
-        @read_pool.checkout
+      if socket
+        socket
       else
-        checkout_writer
+        raise ConnectionFailure.new("Could not connect to primary node.")
       end
     end
 
-    # Checkout a socket for writing (i.e., a primary node).
-    def checkout_writer
-      connect unless connected?
+    def get_socket_from_pool(pool)
+      begin
+        sync_synchronize(:SH) do
+          if pool
+            socket = pool.checkout
+            @sockets_to_pools[socket] = pool
+            socket
+          end
+        end
 
-      @primary_pool.checkout
+      rescue ConnectionFailure => ex
+        log(:info, "Failed to checkout from #{pool} with #{ex.class}; #{ex.message}")
+        return nil
+      end
     end
 
     # Checkin a socket used for reading.
     def checkin_reader(socket)
-      if @read_pool
-        @read_pool.checkin(socket)
-      else
-        checkin_writer(socket)
-      end
+      warn "ReplSetConnection#checkin_writer is deprecated and will be removed " +
+        "in driver v2.0. Use ReplSetConnection#checkin instead."
+      checkin(socket)
     end
 
     # Checkin a socket used for writing.
     def checkin_writer(socket)
-      if @primary_pool
-        @primary_pool.checkin(socket)
+      warn "ReplSetConnection#checkin_writer is deprecated and will be removed " +
+        "in driver v2.0. Use ReplSetConnection#checkin instead."
+      checkin(socket)
+    end
+
+    def checkin(socket)
+      sync_synchronize(:SH) do
+        if pool = @sockets_to_pools[socket]
+          pool.checkin(socket)
+        elsif socket
+          socket.close
+        end
+      end
+
+      # Refresh synchronously every @refresh_interval seconds
+      # if synchronous refresh mode is enabled.
+      if @refresh_mode == :sync &&
+        ((Time.now - @last_refresh) > @refresh_interval)
+        refresh
       end
     end
   end