mongo 1.1.1 → 1.1.2

data/lib/mongo.rb

@@ -3,7 +3,7 @@
 $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 
 module Mongo
-  VERSION = "1.1.1"
+  VERSION = "1.1.2"
 end
 
 module Mongo

data/lib/mongo/collection.rb

@@ -14,20 +14,27 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# ++
 
 module Mongo
 
   # A named collection of documents in a database.
   class Collection
 
-    attr_reader :db, :name, :pk_factory, :hint
+    attr_reader :db, :name, :pk_factory, :hint, :safe
 
     # Initialize a collection object.
     #
     # @param [DB] db a MongoDB database instance.
     # @param [String, Symbol] name the name of the collection.
     #
+    # @option options [:create_pk] :pk (BSON::ObjectId) A primary key factory to use
+    #   other than the default BSON::ObjectId.
+    #
+    # @option options [Boolean, Hash] :safe (false) Set the default safe-mode options
+    #   for insert, update, and remove method called on this Collection instance. If no
+    #   value is provided, the default value set on this instance's DB will be used. This
+    #   default can be overridden for any invocation of insert, update, or remove.
+    #
     # @raise [InvalidNSName]
     #   if collection name is empty, contains '$', or starts or ends with '.'
     #
@@ -37,7 +44,7 @@ module Mongo
     # @return [Collection]
     #
     # @core collections constructor_details
-    def initialize(db, name, pk_factory=nil)
+    def initialize(db, name, options={})
       case name
       when Symbol, String
       else
@@ -56,10 +63,21 @@ module Mongo
         raise Mongo::InvalidNSName, "collection names must not start or end with '.'"
       end
 
+      if options.respond_to?(:create_pk) || !options.is_a?(Hash)
+        warn "The method for specifying a primary key factory on a Collection has changed.\n" +
+          "Please specify it as an option (e.g., :pk => PkFactory)."
+        pk_factory = options
+      else
+        pk_factory = nil
+      end
+
       @db, @name  = db, name
       @connection = @db.connection
       @logger     = @connection.logger
-      @pk_factory = pk_factory || BSON::ObjectId
+      unless pk_factory
+        @safe       = options.has_key?(:safe) ? options[:safe] : @db.safe
+      end
+      @pk_factory = pk_factory || options[:pk] || BSON::ObjectId
       @hint = nil
     end
 
@@ -108,7 +126,10 @@ module Mongo
     #
     # @param [Hash] selector
     #   a document specifying elements which must be present for a
-    #   document to be included in the result set.
+    #   document to be included in the result set. Note that in rare cases,
+    #   (e.g., with $near queries), the order of keys will matter. To preserve
+    #   key order on a selector, use an instance of BSON::OrderedHash (only applies
+    #   to Ruby 1.8).
     #
     # @option opts [Array, Hash] :fields field names that should be returned in the result
     #   set ("_id" will always be included). By limiting results to a certain subset of fields,
@@ -120,12 +141,12 @@ module Mongo
     # @option opts [Array]   :sort an array of [key, direction] pairs to sort by. Direction should
     #   be specified as Mongo::ASCENDING (or :ascending / :asc) or Mongo::DESCENDING (or :descending / :desc)
     # @option opts [String, Array, OrderedHash] :hint hint for query optimizer, usually not necessary if using MongoDB > 1.1
-    # @option opts [Boolean] :snapshot ('false') if true, snapshot mode will be used for this query.
+    # @option opts [Boolean] :snapshot (false) if true, snapshot mode will be used for this query.
     #   Snapshot mode assures no duplicates are returned, or objects missed, which were preset at both the start and
     #   end of the query's execution. For details see http://www.mongodb.org/display/DOCS/How+to+do+Snapshotting+in+the+Mongo+Database
     # @option opts [Boolean] :batch_size (100) the number of documents to returned by the database per GETMORE operation. A value of 0
     #   will let the database server decide how many results to returns. This option can be ignored for most use cases.
-    # @option opts [Boolean] :timeout ('true') when +true+, the returned cursor will be subject to
+    # @option opts [Boolean] :timeout (true) when +true+, the returned cursor will be subject to
     #   the normal cursor timeout behavior of the mongod process. When +false+, the returned cursor will never timeout. Note
     #   that disabling timeout will only work when #find is invoked with a block. This is to prevent any inadvertant failure to
     #   close the cursor, as the cursor is explicitly closed when block code finishes.
@@ -144,13 +165,12 @@ module Mongo
       limit  = opts.delete(:limit) || 0
       sort   = opts.delete(:sort)
       hint   = opts.delete(:hint)
-      snapshot = opts.delete(:snapshot)
+      snapshot   = opts.delete(:snapshot)
       batch_size = opts.delete(:batch_size)
+      timeout    = (opts.delete(:timeout) == false) ? false : true
 
-      if opts[:timeout] == false && !block_given?
-        raise ArgumentError, "Timeout can be set to false only when #find is invoked with a block."
-      else
-        timeout = opts.delete(:timeout) || false
+      if timeout == false && !block_given?
+        raise ArgumentError, "Collection#find must be invoked with a block when timeout is disabled."
       end
 
       if hint
@@ -166,7 +186,7 @@ module Mongo
 
       if block_given?
         yield cursor
-        cursor.close()
+        cursor.close
         nil
       else
         cursor
@@ -242,8 +262,10 @@ module Mongo
     # @option opts [Boolean, Hash] :safe (+false+)
     #   run the operation in safe mode, which run a getlasterror command on the
     #   database to report any assertion. In addition, a hash can be provided to
-    #   run an fsync and/or wait for replication of the insert (>= 1.5.1). See the options
-    #   for DB#error.
+    #   run an fsync and/or wait for replication of the insert (>= 1.5.1). Safe
+    #   options provided here will override any safe options set on this collection,
+    #   its database object, or the current connection. See the options on
+    #   for DB#get_last_error.
     #
     # @see DB#remove for options that can be passed to :safe.
     #
@@ -251,7 +273,8 @@ module Mongo
     def insert(doc_or_docs, options={})
       doc_or_docs = [doc_or_docs] unless doc_or_docs.is_a?(Array)
       doc_or_docs.collect! { |doc| @pk_factory.create_pk(doc) }
-      result = insert_documents(doc_or_docs, @name, true, options[:safe])
+      safe = options.has_key?(:safe) ? options[:safe] : @safe
+      result = insert_documents(doc_or_docs, @name, true, safe)
       result.size > 1 ? result : result.first
     end
     alias_method :<<, :insert
@@ -262,10 +285,11 @@ module Mongo
     #   If specified, only matching documents will be removed.
     #
     # @option opts [Boolean, Hash] :safe (+false+)
-    #   run the operation in safe mode, which run a getlasterror command on the
+    #   run the operation in safe mode, which will run a getlasterror command on the
     #   database to report any assertion. In addition, a hash can be provided to
-    #   run an fsync and/or wait for replication of the remove (>= 1.5.1). See the options
-    #   for DB#get_last_error.
+    #   run an fsync and/or wait for replication of the remove (>= 1.5.1). Safe
+    #   options provided here will override any safe options set on this collection,
+    #   its database, or the current connection. See the options for DB#get_last_error for more details.
     #
     # @example remove all documents from the 'users' collection:
     #   users.remove
@@ -284,14 +308,15 @@ module Mongo
     # @core remove remove-instance_method
     def remove(selector={}, opts={})
       # Initial byte is 0.
+      safe = opts.has_key?(:safe) ? opts[:safe] : @safe
       message = BSON::ByteBuffer.new("\0\0\0\0")
       BSON::BSON_RUBY.serialize_cstr(message, "#{@db.name}.#{@name}")
       message.put_int(0)
       message.put_binary(BSON::BSON_CODER.serialize(selector, false, true).to_s)
 
       @logger.debug("MONGODB #{@db.name}['#{@name}'].remove(#{selector.inspect})") if @logger
-      if opts[:safe]
-        @connection.send_message_with_safe_check(Mongo::Constants::OP_DELETE, message, @db.name, nil, opts[:safe])
+      if safe
+        @connection.send_message_with_safe_check(Mongo::Constants::OP_DELETE, message, @db.name, nil, safe)
         # the return value of send_message_with_safe_check isn't actually meaningful --
         # only the fact that it didn't raise an error is -- so just return true
         true
@@ -317,11 +342,14 @@ module Mongo
     # @option opts [Boolean] :safe (+false+) 
     #   If true, check that the save succeeded. OperationFailure
     #   will be raised on an error. Note that a safe check requires an extra
-    #   round-trip to the database.
+    #   round-trip to the database. Safe options provided here will override any safe
+    #   options set on this collection, its database object, or the current collection.
+    #   See the options for DB#get_last_error for details.
     #
     # @core update update-instance_method
     def update(selector, document, options={})
       # Initial byte is 0.
+      safe = options.has_key?(:safe) ? options[:safe] : @safe
       message = BSON::ByteBuffer.new("\0\0\0\0")
       BSON::BSON_RUBY.serialize_cstr(message, "#{@db.name}.#{@name}")
       update_options  = 0
@@ -331,8 +359,8 @@ module Mongo
       message.put_binary(BSON::BSON_CODER.serialize(selector, false, true).to_s)
       message.put_binary(BSON::BSON_CODER.serialize(document, false, true).to_s)
       @logger.debug("MONGODB #{@db.name}['#{@name}'].update(#{selector.inspect}, #{document.inspect})") if @logger
-      if options[:safe]
-        @connection.send_message_with_safe_check(Mongo::Constants::OP_UPDATE, message, @db.name, nil, options[:safe])
+      if safe
+        @connection.send_message_with_safe_check(Mongo::Constants::OP_UPDATE, message, @db.name, nil, safe)
       else
         @connection.send_message(Mongo::Constants::OP_UPDATE, message, nil)
       end
@@ -355,10 +383,10 @@ module Mongo
     # @option opts [Boolean] :unique (false) if true, this index will enforce a uniqueness constraint.
     # @option opts [Boolean] :background (false) indicate that the index should be built in the background. This
     #   feature is only available in MongoDB >= 1.3.2.
-    # @option opts [Boolean] :dropDups If creating a unique index on a collection with pre-existing records,
+    # @option opts [Boolean] :drop_dups (nil) If creating a unique index on a collection with pre-existing records,
     #   this option will keep the first document the database indexes and drop all subsequent with duplicate values.
-    # @option opts [Integer] :min specify the minimum longitude and latitude for a geo index.
-    # @option opts [Integer] :max specify the maximum longitude and latitude for a geo index.
+    # @option opts [Integer] :min (nil) specify the minimum longitude and latitude for a geo index.
+    # @option opts [Integer] :max (nil) specify the maximum longitude and latitude for a geo index.
     #
     # @example Creating a compound index:
     #   @posts.create_index([['subject', Mongo::ASCENDING], ['created_at', Mongo::DESCENDING]])
@@ -378,7 +406,7 @@ module Mongo
     #
     # @core indexes create_index-instance_method
     def create_index(spec, opts={})
-      opts.assert_valid_keys(:min, :max, :name, :background, :unique, :dropDups)
+      opts[:dropDups] = opts.delete(:drop_dups) if opts[:drop_dups]
       field_spec = BSON::OrderedHash.new
       if spec.is_a?(String) || spec.is_a?(Symbol)
         field_spec[spec.to_s] = 1
@@ -404,10 +432,17 @@ module Mongo
         :key    => field_spec
       }
       selector.merge!(opts)
-      begin
-        response = insert_documents([selector], Mongo::DB::SYSTEM_INDEX_COLLECTION, false, true)
-      rescue Mongo::OperationFailure
-        raise Mongo::OperationFailure, "Failed to create index #{selector.inspect} with the following errors: #{response}"
+
+      insert_documents([selector], Mongo::DB::SYSTEM_INDEX_COLLECTION, false, false)
+      response = @db.get_last_error
+
+      if response['err']
+        if response['code'] == 11000 && selector[:dropDups]
+          # NOP. If the user is intentionally dropping dups, we can ignore duplicate key errors.
+        else
+          raise Mongo::OperationFailure, "Failed to create index #{selector.inspect} with the following error: " +
+           "#{response['err']}"
+        end
       end
       name
     end

data/lib/mongo/connection.rb

@@ -38,7 +38,8 @@ module Mongo
     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, :primary, :secondaries, :arbiters
+    attr_reader :logger, :size, :host, :port, :nodes, :auths, :sockets, :checked_out, :primary, :secondaries, :arbiters,
+      :safe
 
     # Counter for generating unique request ids.
     @@current_request_id = 0
@@ -61,9 +62,15 @@ 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
+    #   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 [String] :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 [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,
@@ -83,6 +90,9 @@ module Mongo
     #
     # @see http://www.mongodb.org/display/DOCS/Replica+Pairs+in+Ruby Replica pairs 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        = []
@@ -96,6 +106,9 @@ module Mongo
       # Host and port of current master.
       @host = @port = nil
 
+      # Replica set name
+      @replica_set_name = options[:name]
+
       # Lock for request ids.
       @id_lock = Mutex.new
 
@@ -106,6 +119,9 @@ module Mongo
       # 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 }
@@ -293,7 +309,7 @@ module Mongo
     #
     # @core databases db-instance_method
     def db(db_name, options={})
-      DB.new(db_name, self)
+      DB.new(db_name, self, options)
     end
 
     # Shortcut for returning a database. Use DB#db to accept options.
@@ -304,7 +320,7 @@ module Mongo
     #
     # @core databases []-instance_method
     def [](db_name)
-      DB.new(db_name, self)
+      DB.new(db_name, self, :safe => @safe)
     end
 
     # Drop a database.
@@ -424,6 +440,7 @@ module Mongo
         checkin(sock)
       end
       if num_received == 1 && (error = docs[0]['err'] || docs[0]['errmsg'])
+        close if error == "not master"
         raise Mongo::OperationFailure, error
       end
       [docs, num_received, cursor_id]
@@ -457,7 +474,7 @@ 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 update the
+    # 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.
@@ -585,8 +602,6 @@ module Mongo
     #
     # If a primary node is discovered, we set the the @host and @port and
     # apply any saved authentication.
-    #
-    # TODO: use the 'primary', and 'seconday' fields if we're in a replica set
     def is_primary?(config)
       config && (config['ismaster'] == 1 || config['ismaster'] == true) || @slave_ok
     end
@@ -599,8 +614,9 @@ module Mongo
 
         config = self['admin'].command({:ismaster => 1}, :sock => socket)
 
+        check_set_name(config, socket)
       rescue OperationFailure, SocketError, SystemCallError, IOError => ex
-        close
+        close unless connected?
       ensure
         @nodes_tried << node
         if config
@@ -616,6 +632,21 @@ module Mongo
       config
     end
 
+    # Make sure that we're connected to the expected replica set.
+    def check_set_name(config, socket)
+      if @replica_set_name
+        config = self['admin'].command({:replSetGetStatus => 1},
+                   :sock => socket, :check_response => false)
+
+        if !Mongo::Support.ok?(config)
+          raise ReplicaSetConnectionError, config['errmsg']
+        elsif config['set'] != @replica_set_name
+          raise ReplicaSetConnectionError,
+            "Attempting to connect to replica set '#{config['set']}' but expected '#{@replica_set_name}'"
+        end
+      end
+    end
+
     # Set the specified node as primary, and
     # apply any saved authentication credentials.
     def set_primary(node)
@@ -743,7 +774,7 @@ module Mongo
       response_to = header.get_int
       op          = header.get_int
     end
-    
+
     def receive_and_discard_header(sock)
       bytes_read = receive_and_discard_message_on_socket(16, sock)
       unless bytes_read == STANDARD_HEADER_SIZE

data/lib/mongo/cursor.rb

@@ -46,7 +46,7 @@ module Mongo
       @order      = options[:order]
       @hint       = options[:hint]
       @snapshot   = options[:snapshot]
-      @timeout    = options[:timeout]  || true
+      @timeout    = options.has_key?(:timeout) ? options[:timeout] : true
       @explain    = options[:explain]
       @socket     = options[:socket]
       @tailable   = options[:tailable] || false

data/lib/mongo/db.rb

@@ -45,8 +45,8 @@ module Mongo
     # Returns the value of the +strict+ flag.
     def strict?; @strict; end
 
-    # The name of the database.
-    attr_reader :name
+    # The name of the database and the local safe option.
+    attr_reader :name, :safe
 
     # The Mongo::Connection instance connecting to the MongoDB server.
     attr_reader :connection
@@ -65,12 +65,19 @@ module Mongo
     #   fields the factory wishes to inject. (NOTE: if the object already has a primary key,
     #   the factory should not inject a new key).
     #
+    # @option options [Boolean, Hash] :safe (false) Set the default safe-mode options
+    #   propogated to Collection objects instantiated off of this DB. If no
+    #   value is provided, the default value set on this instance's Connection object will be used. This
+    #   default can be overridden upon instantiation of any collection by explicity setting a :safe value
+    #   on initialization
+    #
     # @core databases constructor_details
     def initialize(db_name, connection, options={})
       @name       = Mongo::Support.validate_db_name(db_name)
       @connection = connection
       @strict     = options[:strict]
       @pk_factory = options[:pk]
+      @safe       = options.has_key?(:safe) ? options[:safe] : @connection.safe
     end
 
     # Authenticate with the given username and password. Note that mongod
@@ -248,20 +255,26 @@ module Mongo
       oh = BSON::OrderedHash.new
       oh[:create] = name
       doc = command(oh.merge(options || {}))
-      return Collection.new(self, name, @pk_factory) if ok?(doc)
+      return Collection.new(self, name, :pk => @pk_factory) if ok?(doc)
       raise MongoDBError, "Error creating collection: #{doc.inspect}"
     end
 
     # Get a collection by name.
     #
     # @param [String] name the collection name.
+    # @param [Hash] options any valid options that can me passed to Collection#new.
     #
     # @raise [MongoDBError] if collection does not already exist and we're in +strict+ mode.
     #
     # @return [Mongo::Collection]
-    def collection(name)
-      return Collection.new(self, name, @pk_factory) if !strict? || collection_names.include?(name)
-      raise Mongo::MongoDBError, "Collection #{name} doesn't exist. Currently in strict mode."
+    def collection(name, options={})
+      if strict? && !collection_names.include?(name)
+        raise Mongo::MongoDBError, "Collection #{name} doesn't exist. Currently in strict mode."
+      else
+        options[:safe] = options.has_key?(:safe) ? options[:safe] : @safe
+        options.merge!(:pk => @pk_factory) unless options[:pk]
+        Collection.new(self, name, options)
+      end
     end
     alias_method :[], :collection