moped 1.0.0.beta → 1.0.0.rc

data/lib/moped/errors.rb

@@ -8,35 +8,70 @@ module Moped
     # Generic error class for exceptions related to connection failures.
     class ConnectionFailure < StandardError; end
 
-    # Tag applied to unhandled exceptions on a node.
-    module SocketError end
+    # Raised when providing an invalid string from an object id.
+    class InvalidObjectId < StandardError
+
+      # Create the new error.
+      #
+      # @example Create the new error.
+      #   InvalidObjectId.new("test")
+      #
+      # @param [ String ] string The provided id.
+      #
+      # @since 1.0.0
+      def initialize(string)
+        super("'#{string}' is not a valid object id.")
+      end
+    end
 
     # Generic error class for exceptions generated on the remote MongoDB
     # server.
     class MongoError < StandardError
-      # @return the command that generated the error
-      attr_reader :command
 
-      # @return [Hash] the details about the error
-      attr_reader :details
+      # @attribute [r] details The details about the error.
+      # @attribute [r] command The command that generated the error.
+      attr_reader :details, :command
 
       # Create a new operation failure exception.
       #
-      # @param command the command that generated the error
-      # @param [Hash] details the details about the error
+      # @example Create the new error.
+      #   MongoError.new(command, details)
+      #
+      # @param [ Object ] command The command that generated the error.
+      # @param [ Hash ] details The details about the error.
+      #
+      # @since 1.0.0
       def initialize(command, details)
-        @command = command
-        @details = details
-
-        super build_message
+        @command, @details = command, details
+        super(build_message)
       end
 
       private
 
+      # Build the error message.
+      #
+      # @api private
+      #
+      # @example Build the message.
+      #   error.build_message
+      #
+      # @return [ String ] The message.
+      #
+      # @since 1.0.0
       def build_message
         "The operation: #{command.inspect}\n#{error_message}"
       end
 
+      # Get the error message.
+      #
+      # @api private
+      #
+      # @example Get the error message.
+      #   error.error_message
+      #
+      # @return [ String ] The message.
+      #
+      # @since 1.0.0
       def error_message
         err = details["err"] || details["errmsg"] || details["$err"]
 
@@ -49,6 +84,9 @@ module Moped
       end
     end
 
+    # Exception raised when authentication fails.
+    class AuthenticationFailure < MongoError; end
+
     # Exception class for exceptions generated as a direct result of an
     # operation, such as a failed insert or an invalid command.
     class OperationFailure < MongoError; end
@@ -56,21 +94,13 @@ module Moped
     # Exception raised on invalid queries.
     class QueryFailure < MongoError; end
 
-    # Exception raised when authentication fails.
-    class AuthenticationFailure < MongoError; end
-
-    # Raised when providing an invalid string from an object id.
-    class InvalidObjectId < StandardError
-      def initialize(string)
-        super("'#{string}' is not a valid object id.")
-      end
-    end
-
     # @api private
     #
     # Internal exception raised by Node#ensure_primary and captured by
     # Cluster#with_primary.
     class ReplicaSetReconfigured < StandardError; end
 
+    # Tag applied to unhandled exceptions on a node.
+    module SocketError; end
   end
 end

data/lib/moped/indexes.rb

@@ -1,39 +1,31 @@
 module Moped
+
+  # Defines behaviour around indexes.
   class Indexes
     include Enumerable
 
-    private
-
-    attr_reader :database
-    attr_reader :collection_name
-    attr_reader :namespace
-
-    def initialize(database, collection_name)
-      @database = database
-      @collection_name = collection_name
-      @namespace = "#{database.name}.#{collection_name}"
-    end
-
-    public
+    # @attribute [r] collection_name The collection name.
+    # @attribute [r] database The database.
+    # @attribute [r] namespace The index namespace.
+    attr_reader :collection_name, :database, :namespace
 
     # Retrive an index by its definition.
     #
-    # @param [Hash] key an index key definition
-    # @return [Hash, nil] the index with the provided key, or nil.
-    #
-    # @example
+    # @example Get the index.
     #   session[:users].indexes[id: 1]
     #   # => {"v"=>1, "key"=>{"_id"=>1}, "ns"=>"moped_test.users", "name"=>"_id_" }
+    #
+    # @param [ Hash ] key The index definition.
+    #
+    # @return [ Hash, nil ] The index with the provided key, or nil.
+    #
+    # @since 1.0.0
     def [](key)
       database[:"system.indexes"].find(ns: namespace, key: key).one
     end
 
     # Create an index unless it already exists.
     #
-    # @param [Hash] key the index spec
-    # @param [Hash] options the options for the index.
-    # @see http://www.mongodb.org/display/DOCS/Indexes#Indexes-CreationOptions
-    #
     # @example Without options
     #   session[:users].indexes.create(name: 1)
     #   session[:users].indexes[name: 1]
@@ -51,18 +43,23 @@ module Moped
     #     "ns"=>"moped_test.users",
     #     "dropDups"=>true,
     #     "name"=>"location_2d_name_1"}
+    #
+    # @param [ Hash ] key The index spec.
+    # @param [ Hash ] options The options for the index.
+    #
+    # @return [ Hash ] The index spec.
+    #
+    # @see http://www.mongodb.org/display/DOCS/Indexes#Indexes-CreationOptions
+    #
+    # @since 1.0.0
     def create(key, options = {})
       spec = options.merge(ns: namespace, key: key)
       spec[:name] ||= key.to_a.join("_")
-
       database[:"system.indexes"].insert(spec)
     end
 
     # Drop an index, or all indexes.
     #
-    # @param [Hash] key the index's key
-    # @return [Boolean] whether the indexes were dropped.
-    #
     # @example Drop all indexes
     #   session[:users].indexes.count # => 3
     #   # Does not drop the _id index
@@ -72,6 +69,12 @@ module Moped
     # @example Drop a particular index
     #   session[:users].indexes.drop(name: 1)
     #   session[:users].indexes[name: 1] # => nil
+    #
+    # @param [ Hash ] key The index's key.
+    #
+    # @return [ Boolean ] Whether the indexes were dropped.
+    #
+    # @since 1.0.0
     def drop(key = nil)
       if key
         index = self[key] or return false
@@ -79,15 +82,38 @@ module Moped
       else
         name = "*"
       end
-
       result = database.command deleteIndexes: collection_name, index: name
       result["ok"] == 1
     end
 
-    # @yield [Hash] each index for the collection.
+    # Iterate over each of the indexes for the collection.
+    #
+    # @example Iterate over the indexes.
+    #   indexes.each do |spec|
+    #     #...
+    #   end
+    #
+    # @return [ Enumerator ] The enumerator.
+    #
+    # @since 1.0.0
+    #
+    # @yield [ Hash ] Each index for the collection.
     def each(&block)
       database[:"system.indexes"].find(ns: namespace).each(&block)
     end
 
+    # Initialize the indexes.
+    #
+    # @example Create the new indexes.
+    #   Indexes.new(database, :artists)
+    #
+    # @param [ Database ] database The database.
+    # @param [ String, Symbol ] collection_name The name of the collection.
+    #
+    # @since 1.0.0
+    def initialize(database, collection_name)
+      @database, @collection_name = database, collection_name
+      @namespace = "#{database.name}.#{collection_name}"
+    end
   end
 end

data/lib/moped/logging.rb

@@ -1,25 +1,58 @@
 module Moped
+
+  # Contains behaviour for logging.
   module Logging
+
+    # Get the logger.
+    #
+    # @example Get the logger.
+    #   Logging.logger
+    #
+    # @return [ Logger ] The logger.
+    #
+    # @since 1.0.0
     def logger
       return @logger if defined?(@logger)
-
       @logger = rails_logger || default_logger
     end
 
+    # Get the rails logger.
+    #
+    # @example Get the rails logger.
+    #   Logging.rails_logger
+    #
+    # @return [ Logger ] The Rails logger.
+    #
+    # @since 1.0.0
     def rails_logger
       defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
     end
 
+    # Get the default logger.
+    #
+    # @example Get the default logger.
+    #   Logging.default_logger
+    #
+    # @return [ Logger ] The default logger.
+    #
+    # @since 1.0.0
     def default_logger
       Logger.new(STDOUT).tap do |logger|
         logger.level = Logger::INFO
       end
     end
 
+    # Set the logger.
+    #
+    # @example Set the logger.
+    #   Logging.logger = logger
+    #
+    # @return [ Logger ] The logger.
+    #
+    # @since 1.0.0
     def logger=(logger)
       @logger = logger
     end
   end
-
   extend Logging
 end

data/lib/moped/node.rb

@@ -1,139 +1,111 @@
 module Moped
-  class Node
-
-    attr_reader :address
-    attr_reader :resolved_address
-    attr_reader :ip_address
-    attr_reader :port
 
-    attr_reader :peers
-    attr_reader :timeout
+  # Represents a client to a node in a server cluster.
+  #
+  # @api private
+  class Node
 
-    def initialize(address)
-      @address = address
+    # @attribute [r] address The address of the node.
+    # @attribute [r] down_at The time the server node went down.
+    # @attribute [r] ip_address The node's ip.
+    # @attribute [r] peers Other peers in the replica set.
+    # @attribute [r] port The connection port.
+    # @attribute [r] resolved_address The host/port pair.
+    # @attribute [r] timeout The connection timeout.
+    attr_reader :address, :down_at, :ip_address, :peers, :port, :resolved_address, :timeout
 
-      host, port = address.split(":")
-      @ip_address = ::Socket.getaddrinfo(host, nil, ::Socket::AF_INET, ::Socket::SOCK_STREAM).first[3]
-      @port = port.to_i
-      @resolved_address = "#{@ip_address}:#{@port}"
+    # Is this node equal to another?
+    #
+    # @example Is the node equal to another.
+    #   node == other
+    #
+    # @param [ Node ] other The other node.
+    #
+    # @return [ true, false ] If the addresses are equal.
+    #
+    # @since 1.0.0
+    def ==(other)
+      resolved_address == other.resolved_address
+    end
+    alias :eql? :==
 
-      @timeout = 5
+    # Apply the authentication details to this node.
+    #
+    # @example Apply authentication.
+    #   node.apply_auth([ :db, "user", "pass" ])
+    #
+    # @param [ Array<String> ] credentials The db, username, and password.
+    #
+    # @return [ Node ] The authenticated node.
+    #
+    # @since 1.0.0
+    def apply_auth(credentials)
+      unless auth == credentials
+        logouts = auth.keys - credentials.keys
+        logouts.each { |database| logout(database) }
+        credentials.each do |database, (username, password)|
+          login(database, username, password) unless auth[database] == [username, password]
+        end
+      end
+      self
     end
 
+    # Execute a command against a database.
+    #
+    # @example Execute a command.
+    #   node.command(database, { ping: 1 })
+    #
+    # @param [ Database ] database The database to run the command on.
+    # @param [ Hash ] cmd The command to execute.
+    # @options [ Hash ] options The command options.
+    #
+    # @raise [ OperationFailure ] If the command failed.
+    #
+    # @return [ Hash ] The result of the command.
+    #
+    # @since 1.0.0
     def command(database, cmd, options = {})
       operation = Protocol::Command.new(database, cmd, options)
 
       process(operation) do |reply|
         result = reply.documents[0]
-
         raise Errors::OperationFailure.new(
           operation, result
         ) if result["ok"] != 1 || result["err"] || result["errmsg"]
-
         result
       end
     end
 
-    def kill_cursors(cursor_ids)
-      process Protocol::KillCursors.new(cursor_ids)
-    end
-
-    def get_more(database, collection, cursor_id, limit)
-      process Protocol::GetMore.new(database, collection, cursor_id, limit)
-    end
-
-    def remove(database, collection, selector, options = {})
-      process Protocol::Delete.new(database, collection, selector, options)
-    end
-
-    def update(database, collection, selector, change, options = {})
-      process Protocol::Update.new(database, collection, selector, change, options)
-    end
-
-    def insert(database, collection, documents)
-      process Protocol::Insert.new(database, collection, documents)
-    end
-
-    def query(database, collection, selector, options = {})
-      operation = Protocol::Query.new(database, collection, selector, options)
-
-      process operation do |reply|
-        if reply.flags.include? :query_failure
-          raise Errors::QueryFailure.new(operation, reply.documents.first)
-        end
-
-        reply
-      end
-    end
-
-    # @return [true/false] whether the node needs to be refreshed.
-    def needs_refresh?(time)
-      !@refreshed_at || @refreshed_at < time
-    end
-
-    def primary?
-      @primary
-    end
-
-    def secondary?
-      @secondary
-    end
-
-    # Refresh information about the node, such as it's status in the replica
-    # set and it's known peers.
+    # Is the node down?
     #
-    # Returns nothing.
-    # Raises Errors::ConnectionFailure if the node cannot be reached
-    # Raises Errors::ReplicaSetReconfigured if the node is no longer a primary node and
-    #   refresh was called within an +#ensure_primary+ block.
-    def refresh
-      info = command "admin", ismaster: 1
-
-      @refreshed_at = Time.now
-      primary = true if info["ismaster"]
-      secondary = true if info["secondary"]
-
-      peers = []
-      peers.push info["primary"] if info["primary"]
-      peers.concat info["hosts"] if info["hosts"]
-      peers.concat info["passives"] if info["passives"]
-      peers.concat info["arbiters"] if info["arbiters"]
-
-      @peers = peers.map { |peer| Node.new(peer) }
-      @primary, @secondary = primary, secondary
-
-      if !primary && Threaded.executing?(:ensure_primary)
-        raise Errors::ReplicaSetReconfigured, "#{inspect} is no longer the primary node."
-      end
-    end
-
-    attr_reader :down_at
-
+    # @example Is the node down?
+    #   node.down?
+    #
+    # @return [ Time, nil ] The time the node went down, or nil if up.
+    #
+    # @since 1.0.0
     def down?
       @down_at
     end
 
-    # Set a flag on the node for the duration of provided block so that an
-    # exception is raised if the node is no longer the primary node.
-    #
-    # Returns nothing.
-    def ensure_primary
-      Threaded.begin :ensure_primary
-      yield
-    ensure
-      Threaded.end :ensure_primary
-    end
-
     # Yields the block if a connection can be established, retrying when a
     # connection error is raised.
     #
-    # @raises ConnectionFailure when a connection cannot be established.
+    # @example Ensure we are connection.
+    #   node.ensure_connected do
+    #     #...
+    #   end
+    #
+    # @raises [ ConnectionFailure ] When a connection cannot be established.
+    #
+    # @return [ nil ] nil.
+    #
+    # @since 1.0.0
     def ensure_connected
       # Don't run the reconnection login if we're already inside an
       # +ensure_connected+ block.
-      return yield if Threaded.executing? :connection
-      Threaded.begin :connection
-
+      return yield if Threaded.executing?(:connection)
+      Threaded.begin(:connection)
       retry_on_failure = true
 
       begin
@@ -167,44 +139,261 @@ module Moped
         raise $!.extend(Errors::SocketError)
       end
     ensure
-      Threaded.end :connection
+      Threaded.end(:connection)
     end
 
-    def pipeline
-      Threaded.begin :pipeline
+    # Set a flag on the node for the duration of provided block so that an
+    # exception is raised if the node is no longer the primary node.
+    #
+    # @example Ensure this node is primary.
+    #   node.ensure_primary do
+    #     #...
+    #   end
+    #
+    # @return [ nil ] nil.
+    #
+    # @since 1.0.0
+    def ensure_primary
+      Threaded.begin(:ensure_primary)
+      yield
+    ensure
+      Threaded.end(:ensure_primary)
+    end
 
+    # Execute a get more operation on the node.
+    #
+    # @example Execute a get more.
+    #   node.get_more(database, collection, 12345, -1)
+    #
+    # @param [ Database ] database The database to get more from.
+    # @param [ Collection ] collection The collection to get more from.
+    # @param [ Integer ] cursor_id The id of the cursor on the server.
+    # @param [ Integer ] limit The number of documents to limit.
+    #
+    # @return [ Message ] The result of the operation.
+    #
+    # @since 1.0.0
+    def get_more(database, collection, cursor_id, limit)
+      process(Protocol::GetMore.new(database, collection, cursor_id, limit))
+    end
+
+    # Get the hash identifier for the node.
+    #
+    # @example Get the hash identifier.
+    #   node.hash
+    #
+    # @return [ Integer ] The hash identifier.
+    #
+    # @since 1.0.0
+    def hash
+      [ ip_address, port ].hash
+    end
+
+    # Creat the new node.
+    #
+    # @example Create the new node.
+    #   Node.new("127.0.0.1:27017")
+    #
+    # @param [ String ] address The location of the server node.
+    #
+    # @since 1.0.0
+    def initialize(address)
+      @address = address
+
+      host, port = address.split(":")
+      @ip_address = ::Socket.getaddrinfo(host, nil, ::Socket::AF_INET, ::Socket::SOCK_STREAM).first[3]
+      @port = port.to_i
+      @resolved_address = "#{@ip_address}:#{@port}"
+
+      @timeout = 5
+      @down_at = nil
+      @refreshed_at = nil
+      @primary = nil
+      @secondary = nil
+    end
+
+    # Insert documents into the database.
+    #
+    # @example Insert documents.
+    #   node.insert(database, collection, [{ name: "Tool" }])
+    #
+    # @param [ Database ] database The database to insert to.
+    # @param [ Collection ] collection The collection to insert to.
+    # @param [ Array<Hash> ] documents The documents to insert.
+    #
+    # @return [ Message ] The result of the operation.
+    #
+    # @since 1.0.0
+    def insert(database, collection, documents)
+      process(Protocol::Insert.new(database, collection, documents))
+    end
+
+    # Kill all provided cursors on the node.
+    #
+    # @example Kill all the provided cursors.
+    #   node.kill_cursors([ 12345 ])
+    #
+    # @param [ Array<Integer> ] cursor_ids The cursor ids.
+    #
+    # @return [ Message ] The result of the operation.
+    #
+    # @since 1.0.0
+    def kill_cursors(cursor_ids)
+      process(Protocol::KillCursors.new(cursor_ids))
+    end
+
+    # Does the node need to be refreshed?
+    #
+    # @example Does the node require refreshing?
+    #   node.needs_refresh?(time)
+    #
+    # @param [ Time ] time The next referesh time.
+    #
+    # @return [ true, false] Whether the node needs to be refreshed.
+    #
+    # @since 1.0.0
+    def needs_refresh?(time)
+      !@refreshed_at || @refreshed_at < time
+    end
+
+    # Execute a pipeline of commands, for example a safe mode persist.
+    #
+    # @example Execute a pipeline.
+    #   node.pipeline do
+    #     #...
+    #   end
+    #
+    # @return [ nil ] nil.
+    #
+    # @since 1.0.0
+    def pipeline
+      Threaded.begin(:pipeline)
       begin
         yield
       ensure
-        Threaded.end :pipeline
+        Threaded.end(:pipeline)
       end
+      flush unless Threaded.executing?(:pipeline)
+    end
 
-      flush unless Threaded.executing? :pipeline
+    # Is the node the replica set primary?
+    #
+    # @example Is the node the primary?
+    #   node.primary?
+    #
+    # @return [ true, false ] If the node is the primary.
+    #
+    # @since 1.0.0
+    def primary?
+      @primary
     end
 
-    def apply_auth(credentials)
-      unless auth == credentials
-        logouts = auth.keys - credentials.keys
+    # Execute a query on the node.
+    #
+    # @example Execute a query.
+    #   node.query(database, collection, { name: "Tool" })
+    #
+    # @param [ Database ] database The database to query from.
+    # @param [ Collection ] collection The collection to query from.
+    # @param [ Hash ] selector The query selector.
+    # @param [ Hash ] options The query options.
+    #
+    # @raise [ QueryFailure ] If the query had an error.
+    #
+    # @return [ Message ] The result of the operation.
+    #
+    # @since 1.0.0
+    def query(database, collection, selector, options = {})
+      operation = Protocol::Query.new(database, collection, selector, options)
 
-        logouts.each do |database|
-          logout database
+      process operation do |reply|
+        if reply.flags.include?(:query_failure)
+          raise Errors::QueryFailure.new(operation, reply.documents.first)
         end
+        reply
+      end
+    end
 
-        credentials.each do |database, (username, password)|
-          login(database, username, password) unless auth[database] == [username, password]
-        end
+    # Refresh information about the node, such as it's status in the replica
+    # set and it's known peers.
+    #
+    # @example Refresh the node.
+    #   node.refresh
+    #
+    # @raise [ ConnectionFailure ] If the node cannot be reached.
+
+    # @raise [ ReplicaSetReconfigured ] If the node is no longer a primary node and
+    #   refresh was called within an +#ensure_primary+ block.
+    #
+    # @return [ nil ] nil.
+    #
+    # @since 1.0.0
+    def refresh
+      info = command("admin", ismaster: 1)
+
+      @refreshed_at = Time.now
+      primary = true if info["ismaster"]
+      secondary = true if info["secondary"]
+
+      peers = []
+      peers.push(info["primary"]) if info["primary"]
+      peers.concat(info["hosts"]) if info["hosts"]
+      peers.concat(info["passives"]) if info["passives"]
+      peers.concat(info["arbiters"]) if info["arbiters"]
+
+      @peers = peers.map { |peer| Node.new(peer) }
+      @primary, @secondary = primary, secondary
+
+      if !primary && Threaded.executing?(:ensure_primary)
+        raise Errors::ReplicaSetReconfigured, "#{inspect} is no longer the primary node."
       end
+    end
 
-      self
+    # Execute a remove command for the provided selector.
+    #
+    # @example Remove documents.
+    #   node.remove(database, collection, { name: "Tool" })
+    #
+    # @param [ Database ] database The database to remove from.
+    # @param [ Collection ] collection The collection to remove from.
+    # @param [ Hash ] selector The query selector.
+    # @param [ Hash ] options The remove options.
+    #
+    # @return [ Message ] The result of the operation.
+    #
+    # @since 1.0.0
+    def remove(database, collection, selector, options = {})
+      process(Protocol::Delete.new(database, collection, selector, options))
     end
 
-    def ==(other)
-      resolved_address == other.resolved_address
+    # Is the node a replica set secondary?
+    #
+    # @example Is the node a secondary?
+    #   node.secondary?
+    #
+    # @return [ true, false ] If the node is a secondary.
+    #
+    # @since 1.0.0
+    def secondary?
+      @secondary
     end
-    alias eql? ==
 
-    def hash
-      [ip_address, port].hash
+    # Execute an update command for the provided selector.
+    #
+    # @example Update documents.
+    #   node.update(database, collection, { name: "Tool" }, { likes: 1000 })
+    #
+    # @param [ Database ] database The database to update.
+    # @param [ Collection ] collection The collection to update.
+    # @param [ Hash ] selector The query selector.
+    # @param [ Hash ] change The updates.
+    # @param [ Hash ] options The update options.
+    #
+    # @return [ Message ] The result of the operation.
+    #
+    # @since 1.0.0
+    def update(database, collection, selector, change, options = {})
+      process(Protocol::Update.new(database, collection, selector, change, options))
     end
 
     private
@@ -276,6 +465,8 @@ module Moped
       raise Errors::ConnectionFailure, "Timed out connection to Mongo on #{address}"
     rescue Errno::ECONNREFUSED
       raise Errors::ConnectionFailure, "Could not connect to Mongo on #{address}"
+    rescue Errno::ECONNRESET
+      raise Errors::ConnectionFailure, "Connection reset to Mongo on #{address}"
     end
 
     def process(operation, &callback)
@@ -329,6 +520,5 @@ module Moped
         logger.debug indent + last.log_inspect + runtime
       end
     end
-
   end
 end