mongo 0.18.3 → 0.19

data/lib/mongo/connection.rb

@@ -1,5 +1,5 @@
 # --
-# Copyright (C) 2008-2009 10gen Inc.
+# Copyright (C) 2008-2010 10gen Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -30,7 +30,10 @@ module Mongo
     STANDARD_HEADER_SIZE = 16
     RESPONSE_HEADER_SIZE = 20
 
-    attr_reader :logger, :size, :host, :port, :nodes, :sockets, :checked_out
+    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
 
     # Counter for generating unique request ids.
     @@current_request_id = 0
@@ -74,19 +77,26 @@ module Mongo
     # @example localhost, 3000, where this node may be a slave
     #   Connection.new("localhost", 3000, :slave_ok => true)
     #
-    # @example A pair of servers. The driver will always talk to master.
-    #   # On connection errors, Mongo::ConnectionFailure will be raised.
+    # @example DEPRECATED. To initialize a paired connection, use Connection.paired instead.
     #   Connection.new({:left  => ["db1.example.com", 27017],
     #                  :right => ["db2.example.com", 27017]})
     #
-    # @example A pair of servers with connection pooling enabled. Note the nil param placeholder for port.
+    # @example DEPRECATED. To initialize a paired connection, use Connection.paired instead.
     #   Connection.new({:left  => ["db1.example.com", 27017],
     #                   :right => ["db2.example.com", 27017]}, nil,
     #                   :pool_size => 20, :timeout => 5)
     #
     # @see http://www.mongodb.org/display/DOCS/Replica+Pairs+in+Ruby Replica pairs in Ruby
+    #
+    # @core connections
     def initialize(pair_or_host=nil, port=nil, options={})
-      @nodes = format_pair(pair_or_host, port)
+      @auths        = []
+
+      if block_given?
+        @nodes = yield self
+      else
+        @nodes = format_pair(pair_or_host, port)
+      end
 
       # Host and port of current master.
       @host = @port = nil
@@ -121,12 +131,109 @@ module Mongo
       connect_to_master if should_connect
     end
 
+    # Initialize a paired connection to MongoDB.
+    #
+    # @param nodes [Array] An array of arrays, each of which specified a host and port.
+    # @param opts Takes the same options as Connection.new
+    #
+    # @example
+    #   Connection.new([["db1.example.com", 27017],
+    #                   ["db2.example.com", 27017]])
+    #
+    # @example
+    #   Connection.new([["db1.example.com", 27017],
+    #                   ["db2.example.com", 27017]],
+    #                   :pool_size => 20, :timeout => 5)
+    #
+    # @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
+    end
+
+    # Initialize a connection to MongoDB using the MongoDB URI spec:
+    #
+    # @param uri [String]
+    #   A string of the format mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/database]
+    #
+    # @param opts Any of the options available for Connection.new
+    #
+    # @return [Mongo::Connection]
+    def self.from_uri(uri, opts={})
+      new(nil, nil, opts) do |con|
+        con.parse_uri(uri)
+      end
+    end
+
+    # Apply each of the saved database authentications.
+    #
+    # @return [Boolean] returns true if authentications exist and succeeed, false
+    #   if none exists.
+    #
+    # @raise [AuthenticationError] raises an exception if any one
+    #   authentication fails.
+    def apply_saved_authentication
+      return false if @auths.empty?
+      @auths.each do |auth|
+        self[auth['db_name']].authenticate(auth['username'], auth['password'], false)
+      end
+      true
+    end
+
+    # Save an authentication to this connection. When connecting,
+    # the connection will attempt to re-authenticate on every db
+    # specificed in the list of auths. This method is called automatically
+    # by DB#authenticate.
+    #
+    # @param [String] db_name
+    # @param [String] username
+    # @param [String] password
+    #
+    # @return [Hash] a hash representing the authentication just added.
+    def add_auth(db_name, username, password)
+      remove_auth(db_name)
+      auth = {}
+      auth['db_name']  = db_name
+      auth['username'] = username
+      auth['password'] = password
+      @auths << auth
+      auth
+    end
+
+    # Remove a saved authentication for this connection.
+    #
+    # @param [String] db_name
+    #
+    # @return [Boolean]
+    def remove_auth(db_name)
+      return unless @auths
+      if @auths.reject! { |a| a['db_name'] == db_name }
+        true
+      else
+        false
+      end
+    end
+
+    # Remove all authenication information stored in this connection.
+    #
+    # @return [true] this operation return true because it always succeeds.
+    def clear_auths
+      @auths = []
+      true
+    end
+
     # Return a hash with all database names
     # and their respective sizes on disk.
     #
     # @return [Hash]
     def database_info
-      doc = self['admin'].command(:listDatabases => 1)
+      doc = self['admin'].command({:listDatabases => 1}, false, true)
       returning({}) do |info|
         doc['databases'].each { |db| info[db['name']] = db['sizeOnDisk'].to_i }
       end
@@ -145,6 +252,8 @@ module Mongo
     # @param [String] db_name a valid database name.
     #
     # @return [Mongo::DB]
+    #
+    # @core databases db-instance_method
     def db(db_name, options={})
       DB.new(db_name, self, options.merge(:logger => @logger))
     end
@@ -154,6 +263,8 @@ module Mongo
     # @param [String] db_name a valid database name.
     #
     # @return [Mongo::DB]
+    #
+    # @core databases []-instance_method
     def [](db_name)
       DB.new(db_name, self, :logger => @logger)
     end
@@ -177,7 +288,7 @@ module Mongo
       oh[:fromhost] = from_host
       oh[:fromdb]   = from
       oh[:todb]     = to
-      self["admin"].command(oh)
+      self["admin"].command(oh, false, true)
     end
 
     # Increment and return the next available request id.
@@ -195,7 +306,7 @@ module Mongo
     #
     # @return [Hash]
     def server_info
-      db("admin").command({:buildinfo => 1}, {:admin => true, :check_response => true})
+      self["admin"].command({:buildinfo => 1}, false, true)
     end
 
     # Get the build version of the current server.
@@ -310,6 +421,7 @@ module Mongo
           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
 
           # Note: slave_ok can be true only when connecting to a single node.
@@ -321,6 +433,7 @@ module Mongo
           break if is_master || @slave_ok
         rescue SocketError, SystemCallError, IOError => ex
           socket.close if socket
+          close
           false
         end
       end
@@ -343,6 +456,86 @@ module Mongo
       @checked_out.clear
     end
 
+    ## Configuration helper methods
+
+    # 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 Hash
+         warn "Initializing a paired connection with Connection.new is deprecated. Use Connection.pair instead."
+         connections = []
+         connections << pair_val_to_connection(pair_or_host[:left])
+         connections << pair_val_to_connection(pair_or_host[:right])
+         connections
+        when nil
+          [['localhost', DEFAULT_PORT]]
+      end
+    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
+      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}"
+      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
+
+        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
+
+        nodes << [host, port]
+      end
+
+      nodes
+    end
+
     private
 
     # Return a socket to the pool.
@@ -513,43 +706,10 @@ module Mongo
           message += chunk
         end
         rescue => ex
+          close
           raise ConnectionFailure, "Operation failed with the following exception: #{ex}"
       end
       message
     end
-
-
-    ## Private helper methods
-
-    # Returns an array of host-port pairs.
-    def format_pair(pair_or_host, port)
-      case pair_or_host
-        when String
-          [[pair_or_host, port ? port.to_i : DEFAULT_PORT]]
-        when Hash
-         connections = []
-         connections << pair_val_to_connection(pair_or_host[:left])
-         connections << pair_val_to_connection(pair_or_host[:right])
-         connections
-        when nil
-          [['localhost', DEFAULT_PORT]]
-      end
-    end
-
-    # Turns an array containing a host name string and a
-    # port number integer into a [host, port] pair array.
-    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
-      end
-    end
-
   end
 end

data/lib/mongo/cursor.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2008-2009 10gen Inc.
+# Copyright (C) 2008-2010 10gen Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -29,6 +29,8 @@ module Mongo
     # similar methods. Application developers shouldn't have to create cursors manually.
     #
     # @return [Cursor]
+    #
+    # @core cursors constructor_details
     def initialize(collection, options={})
       @db         = collection.db
       @collection = collection
@@ -76,12 +78,6 @@ module Mongo
       doc
     end
 
-    # @deprecated use Cursor#next_document instead.
-    def next_object
-      warn "Cursor#next_object is deprecated; please use Cursor#next_document instead."
-      next_document
-    end
-
     # Get the size of the result set for this query.
     #
     # @return [Integer] the number of objects in the result set for this query. Does
@@ -131,6 +127,8 @@ module Mongo
     # @return [Integer] the current number_to_return if no parameter is given.
     #
     # @raise [InvalidOperation] if this cursor has already been used.
+    #
+    # @core limit limit-instance_method
     def limit(number_to_return=nil)
       return @limit unless number_to_return
       check_modifiable
@@ -200,6 +198,8 @@ module Mongo
     # Get the explain plan for this cursor.
     #
     # @return [Hash] a document containing the explain plan for this cursor.
+    #
+    # @core explain explain-instance_method
     def explain
       c = Cursor.new(@collection, query_options_hash.merge(:limit => -@limit.abs, :explain => true))
       explanation = c.next_document

data/lib/mongo/db.rb

@@ -1,5 +1,5 @@
 # --
-# Copyright (C) 2008-2009 10gen Inc.
+# Copyright (C) 2008-2010 10gen Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -62,6 +62,8 @@ module Mongo
     #   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).
+    #
+    # @core databases constructor_details
     def initialize(db_name, connection, options={})
       @name       = validate_db_name(db_name)
       @connection = connection
@@ -74,9 +76,16 @@ module Mongo
     #
     # @param [String] username
     # @param [String] password
+    # @param [Boolean] save_auth
+    #   Save this authentication to the connection object using Connection#add_auth. This
+    #   will ensure that the authentication will be applied on database reconnect.
     #
     # @return [Boolean]
-    def authenticate(username, password)
+    #
+    # @raise [AuthenticationError]
+    #
+    # @core authenticate authenticate-instance_method
+    def authenticate(username, password, save_auth=true)
       doc = command(:getnonce => 1)
       raise "error retrieving nonce: #{doc}" unless ok?(doc)
       nonce = doc['nonce']
@@ -86,18 +95,60 @@ module Mongo
       auth['user'] = username
       auth['nonce'] = nonce
       auth['key'] = Digest::MD5.hexdigest("#{nonce}#{username}#{hash_password(username, password)}")
-      ok?(command(auth))
+      if ok?(command(auth))
+        if save_auth
+          @connection.add_auth(@name, username, password)
+        end
+        true
+      else
+        raise(Mongo::AuthenticationError, "Failed to authenticate user '#{username}' on db '#{self.name}'")
+      end
+    end
+
+    # Adds a user to this database for use with authentication. If the user already
+    # exists in the system, the password will be updated.
+    #
+    # @param [String] username
+    # @param [String] password
+    #
+    # @return [Hash] an object representing the user.
+    def add_user(username, password)
+      users = self[SYSTEM_USER_COLLECTION]
+      user  = users.find_one({:user => username}) || {:user => username}
+      user['pwd'] = hash_password(username, password)
+      users.save(user)
+      return user
+    end
+
+    # Remove the given user from this database. Returns false if the user
+    # doesn't exist in the system.
+    #
+    # @param [String] username
+    #
+    # @return [Boolean]
+    def remove_user(username)
+      if self[SYSTEM_USER_COLLECTION].find_one({:user => username})
+        self[SYSTEM_USER_COLLECTION].remove({:user => username}, :safe => true)
+      else
+        return false
+      end
     end
 
-    # Deauthorizes use for this database for this connection.
+    # Deauthorizes use for this database for this connection. Also removes
+    # any saved authorization in the connection class associated with this
+    # database.
     #
     # @raise [MongoDBError] if logging out fails.
     #
     # @return [Boolean]
     def logout
       doc = command(:logout => 1)
-      return true if ok?(doc)
-      raise MongoDBError, "error logging out: #{doc.inspect}"
+      if ok?(doc)
+        @connection.remove_auth(@name)
+        true
+      else
+        raise MongoDBError, "error logging out: #{doc.inspect}"
+      end
     end
 
     # Get an array of collection names in this database.
@@ -170,12 +221,6 @@ module Mongo
       raise MongoDBError, "Error creating collection: #{doc.inspect}"
     end
 
-    # @deprecated all the admin methods are now included in the DB class.
-    def admin
-      warn "DB#admin has been DEPRECATED. All the admin functions are now available in the DB class itself."
-      Admin.new(self)
-    end
-
     # Get a collection by name.
     #
     # @param [String] name the collection name.
@@ -386,6 +431,8 @@ module Mongo
     # @param [Socket] sock a socket to use. This is mainly for internal use.
     #
     # @return [Hash]
+    #
+    # @core commands command_instance-method
     def command(selector, admin=false, check_response=false, sock=nil)
       raise MongoArgumentError, "command must be given a selector" unless selector.is_a?(Hash) && !selector.empty?
       if selector.class.eql?(Hash) && selector.keys.length > 1
@@ -402,12 +449,6 @@ module Mongo
       end
     end
 
-    # @deprecated please use DB#command instead.
-    def db_command(*args)
-      warn "DB#db_command has been DEPRECATED. Please use DB#command instead."
-      command(args[0], args[1])
-    end
-
     # A shortcut returning db plus dot plus collection name.
     #
     # @param [String] collection_name
@@ -439,6 +480,8 @@ module Mongo
     # get the results using DB#profiling_info.
     #
     # @return [Symbol] :off, :slow_only, or :all
+    #
+    # @core profiling profiling_level-instance_method
     def profiling_level
       oh = OrderedHash.new
       oh[:profile] = -1