moped 1.0.0.beta → 1.0.0.rc

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011-2012 Bernerd Schaefer
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,6 +1,17 @@
+Moped [![Build Status](https://secure.travis-ci.org/mongoid/moped.png?branch=master&.png)](http://travis-ci.org/mongoid/moped)
+========
+
 Moped is a MongoDB driver for Ruby, which exposes a simple, elegant, and fast
 API.
 
+Compatibility
+-------------
+
+Moped is tested against MRI 1.9.2, 1.9.3, 2.0.0, and JRuby (1.9).
+
+Usage
+-----
+
 ```ruby
 session = Moped::Session.new %w[127.0.0.1:27017]
 session.use "echo_test"
@@ -473,11 +484,3 @@ failover. We've decided that, for now, it's not worth making the replica set
 code thread-safe.
 
 **TL;DR**: use one `Moped::Session` instance per thread.
-
-# Compatibility
-
-Moped is tested against MRI 1.9.2, 1.9.3, 2.0.0, and JRuby (1.9).
-
-<img src="https://secure.travis-ci.org/mongoid/moped.png?branch=master&.png"/>
-
-[Build History](http://travis-ci.org/mongoid/moped)

data/lib/moped/bson.rb

@@ -21,5 +21,22 @@ module Moped
     FLOAT_PACK = 'E'.freeze
 
     START_LENGTH = [0].pack(INT32_PACK).freeze
+
+    class << self
+
+      # Create a new object id from the provided string.
+      #
+      # @example Create a new object id.
+      #   Moped::BSON::ObjectId("4faf83c7dbf89b7b29000001")
+      #
+      # @param [ String ] string The string to use.
+      #
+      # @return [ ObjectId ] The object id.
+      #
+      # @since 1.0.0
+      def ObjectId(string)
+        ObjectId.from_string(string)
+      end
+    end
   end
 end

data/lib/moped/bson/extensions/hash.rb

@@ -10,7 +10,7 @@ module Moped
             io.read 4
 
             while (buf = io.readbyte) != 0
-              key = io.gets(NULL_BYTE).chop!.force_encoding('utf-8')
+              key = io.gets(NULL_BYTE).chop!
 
               if native_class = Types::MAP[buf]
                 doc[key] = native_class.__bson_load__(io)
@@ -34,7 +34,7 @@ module Moped
           io << START_LENGTH
 
           each do |k, v|
-            v.__bson_dump__(io, k.to_s.encode('utf-8').force_encoding('binary'))
+            v.__bson_dump__(io, k.to_s)
           end
           io << EOD
 

data/lib/moped/bson/extensions/regexp.rb

@@ -5,7 +5,7 @@ module Moped
       module Regexp
         module ClassMethods
           def __bson_load__(io)
-            source = io.gets(NULL_BYTE).chop!.force_encoding('utf-8')
+            source = io.gets(NULL_BYTE).chop!
             options = 0
             while (option = io.getbyte) != 0
               case option
@@ -26,7 +26,7 @@ module Moped
           io << Types::REGEX
           io << key
           io << NULL_BYTE
-          io << source.force_encoding('binary')
+          io << source
           io << NULL_BYTE
 
           io << 'i'  if (options & ::Regexp::IGNORECASE) != 0

data/lib/moped/bson/extensions/symbol.rb

@@ -14,9 +14,19 @@ module Moped
           io << key
           io << NULL_BYTE
 
-          str = to_s.force_encoding('utf-8').force_encoding('binary')
-          io << [str.bytesize+1].pack(INT32_PACK)
-          io << str
+          begin
+            data = to_s.encode('utf-8')
+          rescue EncodingError
+            data = to_s.dup
+            data.force_encoding('utf-8')
+
+            raise unless data.valid_encoding?
+          end
+
+          data.force_encoding('binary')
+
+          io << [data.bytesize+1].pack(INT32_PACK)
+          io << data
           io << NULL_BYTE
         end
       end

data/lib/moped/cluster.rb

@@ -1,15 +1,37 @@
 module Moped
 
+  # The cluster represents a cluster of MongoDB server nodes, either a single
+  # node, a replica set, or a mongos server.
   class Cluster
 
-    # @return [Array<String>] the seeds the replica set was initialized with
+    # @attribute [r] seeds The seeds the cluster was initialized with.
     attr_reader :seeds
 
-    # @option options :down_interval number of seconds to wait before attempting
-    # to reconnect to a down node. (30)
+    # Get the authentication details for the cluster.
+    #
+    # @example Get the authentication details.
+    #   cluster.auth
+    #
+    # @return [ Hash ] the cached authentication credentials for this cluster.
+    #
+    # @since 1.0.0
+    def auth
+      @auth ||= {}
+    end
+
+    # Initialize the new cluster.
+    #
+    # @example Initialize the cluster.
+    #   Cluster.new([ "localhost:27017" ], down_interval: 20)
     #
+    # @param [ Hash ] options The cluster options.
+    #
+    # @option options :down_interval number of seconds to wait before attempting
+    #   to reconnect to a down node. (30)
     # @option options :refresh_interval number of seconds to cache information
-    # about a node. (300)
+    #   about a node. (300)
+    #
+    # @since 1.0.0
     def initialize(hosts, options)
       @options = {
         down_interval: 30,
@@ -20,13 +42,45 @@ module Moped
       @nodes = hosts.map { |host| Node.new(host) }
     end
 
+    # Returns the list of available nodes, refreshing 1) any nodes which were
+    # down and ready to be checked again and 2) any nodes whose information is
+    # out of date.
+    #
+    # @example Get the available nodes.
+    #   cluster.nodes
+    #
+    # @return [ Array<Node> ] the list of available nodes.
+    #
+    # @since 1.0.0
+    def nodes
+      # Find the nodes that were down but are ready to be refreshed, or those
+      # with stale connection information.
+      needs_refresh, available = @nodes.partition do |node|
+        (node.down? && node.down_at < (Time.new - @options[:down_interval])) ||
+          node.needs_refresh?(Time.new - @options[:refresh_interval])
+      end
+
+      # Refresh those nodes.
+      available.concat refresh(needs_refresh)
+
+      # Now return all the nodes that are available.
+      available.reject(&:down?)
+    end
+
     # Refreshes information for each of the nodes provided. The node list
     # defaults to the list of all known nodes.
     #
     # If a node is successfully refreshed, any newly discovered peers will also
     # be refreshed.
     #
-    # @return [Array<Node>] the available nodes
+    # @example Refresh the nodes.
+    #   cluster.refresh
+    #
+    # @param [ Array<Node> ] nodes_to_refresh The nodes to refresh.
+    #
+    # @return [ Array<Node> ] the available nodes
+    #
+    # @since 1.0.0
     def refresh(nodes_to_refresh = @nodes)
       refreshed_nodes = []
       seen = {}
@@ -46,43 +100,34 @@ module Moped
             refreshed_nodes << node unless refreshed_nodes.include?(node)
 
             # Now refresh any newly discovered peer nodes.
-            (node.peers - @nodes).each &refresh_node
+            (node.peers - @nodes).each(&refresh_node)
           rescue Errors::ConnectionFailure
             # We couldn't connect to the node, so don't do anything with it.
           end
         end
       end
 
-      nodes_to_refresh.each &refresh_node
-
+      nodes_to_refresh.each(&refresh_node)
       refreshed_nodes.to_a
     end
 
-    # Returns the list of available nodes, refreshing 1) any nodes which were
-    # down and ready to be checked again and 2) any nodes whose information is
-    # out of date.
-    #
-    # @return [Array<Node>] the list of available nodes.
-    def nodes
-      # Find the nodes that were down but are ready to be refreshed, or those
-      # with stale connection information.
-      needs_refresh, available = @nodes.partition do |node|
-        (node.down? && node.down_at < (Time.new - @options[:down_interval])) ||
-          node.needs_refresh?(Time.new - @options[:refresh_interval])
-      end
-
-      # Refresh those nodes.
-      available.concat refresh(needs_refresh)
-
-      # Now return all the nodes that are available.
-      available.reject &:down?
-    end
-
     # Yields the replica set's primary node to the provided block. This method
     # will retry the block in case of connection errors or replica set
     # reconfiguration.
     #
-    # @raises ConnectionFailure when no primary node can be found
+    # @example Yield the primary to the block.
+    #   cluster.with_primary do |node|
+    #     # ...
+    #   end
+    #
+    # @param [ true, false ] retry_on_failure Whether to retry if an error was
+    #   raised.
+    #
+    # @raises [ ConnectionFailure ] When no primary node can be found
+    #
+    # @return [ Object ] The result of the yield.
+    #
+    # @since 1.0.0
     def with_primary(retry_on_failure = true, &block)
       if node = nodes.find(&:primary?)
         begin
@@ -100,14 +145,29 @@ module Moped
         refresh
         with_primary(false, &block)
       else
-        raise Errors::ConnectionFailure, "Could not connect to a primary node for replica set #{inspect}"
+        raise(
+          Errors::ConnectionFailure,
+          "Could not connect to a primary node for replica set #{inspect}"
+        )
       end
     end
 
     # Yields a secondary node if available, otherwise the primary node. This
     # method will retry the block in case of connection errors.
     #
-    # @raises ConnectionError when no secondary or primary node can be found
+    # @example Yield the secondary to the block.
+    #   cluster.with_secondary do |node|
+    #     # ...
+    #   end
+    #
+    # @param [ true, false ] retry_on_failure Whether to retry if an error was
+    #   raised.
+    #
+    # @raises [ ConnectionFailure ] When no primary node can be found
+    #
+    # @return [ Object ] The result of the yield.
+    #
+    # @since 1.0.0
     def with_secondary(retry_on_failure = true, &block)
       available_nodes = nodes.shuffle!.partition(&:secondary?).flatten
 
@@ -126,20 +186,17 @@ module Moped
         refresh
         with_secondary(false, &block)
       else
-        raise Errors::ConnectionFailure, "Could not connect to any secondary or primary nodes for replica set #{inspect}"
+        raise(
+          Errors::ConnectionFailure,
+          "Could not connect to any secondary or primary nodes for replica set #{inspect}"
+        )
       end
     end
 
-    # @return [Hash] the cached authentication credentials for this cluster.
-    def auth
-      @auth ||= {}
-    end
-
     private
 
     def initialize_copy(_)
-      @nodes = @nodes.map &:dup
+      @nodes = @nodes.map(&:dup)
     end
-
   end
 end

data/lib/moped/collection.rb

@@ -9,54 +9,77 @@ module Moped
   #   users.find.to_a # => [{ name: "John" }]
   class Collection
 
-    # @return [Database] the database this collection belongs to
-    attr_reader :database
+    # @attribute [r] database The collection's database.
+    # @attribute [r] name The collection name.
+    attr_reader :database, :name
 
-    # @return [String, Symbol] the collection's name
-    attr_reader :name
+    # Drop the collection.
+    #
+    # @example Drop the collection.
+    #   collection.drop
+    #
+    # @return [ Hash ] The command information.
+    #
+    # @since 1.0.0
+    def drop
+      database.command(drop: name)
+    end
 
-    # @param [Database] database the database this collection belongs to
-    # @param [String, Symbol] name the collection's name
-    def initialize(database, name)
-      @database = database
-      @name     = name
+    # Build a query for this collection.
+    #
+    # @example Build a query based on the provided selector.
+    #   collection.find(name: "Placebo")
+    #
+    # @param [ Hash ] selector The query selector.
+    #
+    # @return [ Query ] The generated query.
+    #
+    # @since 1.0.0
+    def find(selector = {})
+      Query.new(self, selector)
     end
+    alias :where :find
 
     # Access information about this collection's indexes.
     #
-    # @return [Indexes]
+    # @example Get the index information.
+    #   collection.indexes
+    #
+    # @return [ Indexes ] The index information.
+    #
+    # @since 1.0.0
     def indexes
       Indexes.new(database, name)
     end
 
-    # Drop the collection.
-    def drop
-      database.command drop: name
-    end
-
-    # Build a query for this collection.
+    # Initialize the new collection.
     #
-    # @param [Hash] selector the selector
-    # @return [Moped::Query]
-    def find(selector = {})
-      Query.new self, selector
+    # @example Initialize the collection.
+    #   Collection.new(database, :artists)
+    #
+    # @param [ Database ] database The collection's database.
+    # @param [ String, Symbol] name The collection name.
+    #
+    # @since 1.0.0
+    def initialize(database, name)
+      @database, @name = database, name
     end
-    alias where find
 
     # Insert one or more documents into the collection.
     #
-    # @overload insert(document)
-    #   @example
-    #     db[:people].insert(name: "John")
-    #   @param [Hash] document the document to insert
+    # @example Insert a single document.
+    #   db[:people].insert(name: "John")
+    #
+    # @example Insert multiple documents in batch.
+    #   db[:people].insert([{name: "John"}, {name: "Joe"}])
     #
-    # @overload insert(documents)
-    #   @example
-    #     db[:people].insert([{name: "John"}, {name: "Joe"}])
-    #   @param [Array<Hash>] documents the documents to insert
+    # @param [ Hash, Array<Hash> ] documents The document(s) to insert.
+    #
+    # @return [ nil ] nil.
+    #
+    # @since 1.0.0
     def insert(documents)
-      documents = [documents] unless documents.is_a? Array
-
+      documents = [documents] unless documents.is_a?(Array)
       database.session.with(consistency: :strong) do |session|
         session.context.insert(database.name, name, documents)
       end