moped 0.0.0.beta → 1.0.0.alpha

data/lib/moped/protocol/commands/authenticate.rb

@@ -0,0 +1,54 @@
+module Moped
+  module Protocol
+    module Commands
+
+      # Implementation of the authentication command for Mongo. See:
+      # http://www.mongodb.org/display/DOCS/Implementing+Authentication+in+a+Driver
+      # for details.
+      #
+      # @example
+      #   socket.write Command.new :admin, getnonce: 1
+      #   reply = Reply.deserialize socket
+      #   socket.write Authenticate.new :admin, "username", "password",
+      #     reply.documents[0]["nonce"]
+      #   Reply.deserialize(socket).documents[0]["ok"] # => 1.0
+      class Authenticate < Command
+
+        # Create a new authentication command.
+        #
+        # @param [String] database the database to authenticate against
+        # @param [String] username
+        # @param [String] password
+        # @param [String] nonce the nonce returned from running the getnonce
+        # command.
+        def initialize(database, username, password, nonce)
+          super database, build_auth_command(username, password, nonce)
+        end
+
+        # @param [String] username
+        # @param [String] password
+        # @param [String] nonce
+        # @return [String] the mongo digest of the username, password, and
+        # nonce.
+        def digest(username, password, nonce)
+          Digest::MD5.hexdigest(
+            nonce + username + Digest::MD5.hexdigest(username + ":mongo:" + password)
+          )
+        end
+
+        # @param [String] username
+        # @param [String] password
+        # @param [String] nonce
+        def build_auth_command(username, password, nonce)
+          {
+            authenticate: 1,
+            user: username,
+            nonce: nonce,
+            key: digest(username, password, nonce)
+          }
+        end
+
+      end
+    end
+  end
+end

data/lib/moped/protocol/delete.rb

@@ -0,0 +1,92 @@
+module Moped
+  module Protocol
+
+    # The Protocol class for deleting documents from a collection.
+    #
+    # @example Delete all people named John
+    #   delete = Delete.new "moped", "people", { name: "John" }
+    #
+    # @example Delete the first person named John
+    #   delete = Delete.new "moped", "people", { name: "John" },
+    #     flags: [:remove_first]
+    #
+    # @example Setting the request id
+    #   delete = Delete.new "moped", "people", { name: "John" },
+    #     request_id: 123
+    class Delete
+      include Message
+
+      # @attribute
+      # @return [Number] the length of the message
+      int32 :length
+
+      # @attribute
+      # @return [Number] the request id of the message
+      int32 :request_id
+
+      int32 :response_to
+
+      # @attribute
+      # @return [Number] the operation code of this message
+      int32 :op_code
+
+      int32    :reserved # reserved for future use
+
+      # @attribute
+      # @return [String] the full collection name
+      cstring  :full_collection_name
+
+      # @attribute
+      # @param [Array] the flags for the message
+      # @return [Array] the flags for the message
+      flags    :flags, remove_first: 2 ** 0
+
+      # @attribute
+      # @return [Hash] the query to use when deleting documents
+      document :selector
+
+      # @return [String, Symbol] the database to delete from
+      attr_reader :database
+
+      # @return [String, Symbol] the collection to delete from
+      attr_reader :collection
+
+      # Create a new delete command. The +database+ and +collection+ arguments
+      # are joined together to set the +full_collection_name+.
+      #
+      # @example
+      #   Delete.new "moped", "users", { condition: true },
+      #     flags: [:remove_first],
+      #     request_id: 123
+      #
+      # @param [String, Symbol] database the database to delete from
+      # @param [String, Symbol] collection the collection to delete from
+      # @param [Hash] selector the selector for which documents to delete
+      # @param [Hash] options additional options
+      # @option options [Number] :request_id the command's request id
+      # @option options [Array] :flags the flags for insertion. Supported
+      #   flags: +:remove_first+
+      def initialize(database, collection, selector, options = {})
+        @database   = database
+        @collection = collection
+
+        @full_collection_name = "#{database}.#{collection}"
+        @selector             = selector
+        @request_id           = options[:request_id]
+        @flags                = options[:flags]
+      end
+
+      # @return [Number] OP_DELETE operation code (2006)
+      def op_code
+        2006
+      end
+
+      def log_inspect
+        type = "DELETE"
+
+        "%-12s database=%s collection=%s selector=%s flags=%s" % [type, database, collection, selector.inspect, flags.inspect]
+      end
+
+    end
+  end
+end

data/lib/moped/protocol/get_more.rb

@@ -0,0 +1,79 @@
+module Moped
+  module Protocol
+
+    # The Protocol class for retrieving more documents from a cursor.
+    #
+    # @example Get more results using database default limit
+    #   insert = GetMore.new "moped", "people", 29301021, 0
+    #
+    # @example Get more results using custom limit
+    #   insert = Insert.new "moped", "people", 29301021, 10
+    #
+    # @example Setting the request id
+    #   insert = Insert.new "moped", "people", 29301021, 10,
+    #     request_id: 123
+    class GetMore
+      include Message
+
+      # @attribute
+      # @return [Number] the length of the message
+      int32 :length
+
+      # @attribute
+      # @return [Number] the request id of the message
+      int32 :request_id
+
+      int32 :response_to
+
+      # @attribute
+      # @return [Number] the operation code of this message
+      int32 :op_code
+
+      int32    :reserved # reserved for future use
+
+      # @attribute
+      # @return [String] the namespaced collection name
+      cstring  :full_collection_name
+
+      # @attribute
+      # @return [Number] the number of documents to return
+      int32    :limit
+
+      # @attribute
+      # @return [Number] the id of the cursor to get more documents from
+      int64    :cursor_id
+
+      # @return [Number] OP_GETMORE operation code (2005)
+      def op_code
+        2005
+      end
+
+      # @return [String, Symbol] the database this insert targets
+      attr_reader :database
+
+      # @return [String, Symbol] the collection this insert targets
+      attr_reader :collection
+
+      # Create a new +GetMore+ command. The +database+ and +collection+ arguments
+      # are joined together to set the +full_collection_name+.
+      #
+      # @example
+      #   GetMore.new "moped", "users", 29301021, 10, request_id: 123
+      def initialize(database, collection, cursor_id, limit, options = {})
+        @database   = database
+        @collection = collection
+
+        @full_collection_name = "#{database}.#{collection}"
+        @cursor_id            = cursor_id
+        @limit                = limit
+        @request_id           = options[:request_id]
+      end
+
+      def log_inspect
+        type = "GET_MORE"
+
+        "%-12s database=%s collection=%s limit=%s cursor_id=%s" % [type, database, collection, limit, cursor_id]
+      end
+    end
+  end
+end

data/lib/moped/protocol/insert.rb

@@ -0,0 +1,92 @@
+module Moped
+  module Protocol
+
+    # The Protocol class for inserting documents into a collection.
+    #
+    # @example
+    #   insert = Insert.new "moped", "people", [{ name: "John" }]
+    #
+    # @example Continuing after an error on batch insert
+    #   insert = Insert.new "moped", "people",
+    #     [{ unique_field: 1 }, { unique_field: 1 }, { unique_field: 2 }],
+    #     flags: [:continue_on_error]
+    #
+    # @example Setting the request id
+    #   insert = Insert.new "moped", "people", [{ name: "John" }],
+    #     request_id: 123
+    class Insert
+      include Message
+
+      # @attribute
+      # @return [Number] the length of the message
+      int32 :length
+
+      # @attribute
+      # @return [Number] the request id of the message
+      int32 :request_id
+
+      int32 :response_to
+
+      # @attribute
+      # @return [Number] the operation code of this message
+      int32 :op_code
+
+      # @attribute
+      # The flags for the query. Supported flags are: +:continue_on_error+.
+      #
+      # @param  [Array] flags the flags for this message
+      # @return [Array] the flags for this message
+      flags    :flags, continue_on_error: 2 ** 0
+
+      # @attribute
+      # @return [String] the namespaced collection name
+      cstring  :full_collection_name
+
+      # @attribute
+      # @return [Array<Hash>] the documents to insert
+      document :documents, type: :array
+
+      # @return [Number] OP_INSERT operation code (2002)
+      def op_code
+        2002
+      end
+
+      # @return [String, Symbol] the database this insert targets
+      attr_reader :database
+
+      # @return [String, Symbol] the collection this insert targets
+      attr_reader :collection
+
+      # Create a new insert command. The +database+ and +collection+ arguments
+      # are joined together to set the +full_collection_name+.
+      #
+      # @example
+      #   Insert.new "moped", "users", [{ name: "John" }],
+      #     flags: [:continue_on_error],
+      #     request_id: 123
+      #
+      # @param [String, Symbol] database the database to insert into
+      # @param [String, Symbol] collection the collection to insert into
+      # @param [Array<Hash>] documents the documents to insert
+      # @param [Hash] options additional options
+      # @option options [Number] :request_id the command's request id
+      # @option options [Array] :flags the flags for insertion. Supported
+      #   flags: +:continue_on_error+
+      def initialize(database, collection, documents, options = {})
+        @database = database
+        @collection = collection
+
+        @full_collection_name = "#{database}.#{collection}"
+        @documents            = documents
+        @request_id           = options[:request_id]
+        @flags                = options[:flags]
+      end
+
+      def log_inspect
+        type = "INSERT"
+
+        "%-12s database=%s collection=%s documents=%s flags=%s" % [type, database, collection, documents.inspect, flags.inspect]
+      end
+    end
+  end
+end

data/lib/moped/protocol/kill_cursors.rb

@@ -0,0 +1,61 @@
+module Moped
+  module Protocol
+
+    # The Protocol class for killing active cursors.
+    #
+    # @example
+    #   command = KillCursors.new [123, 124, 125]
+    #
+    # @example Setting the request id
+    #   command = KillCursors.new [123, 124, 125], request_id: 456
+    class KillCursors
+      include Message
+
+      # @attribute
+      # @return [Number] the length of the message
+      int32 :length
+
+      # @attribute
+      # @return [Number] the request id of the message
+      int32 :request_id
+
+      int32 :response_to
+
+      # @attribute
+      # @return [Number] the operation code of this message
+      int32 :op_code
+
+      int32    :reserved # reserved for future use
+
+      # @attribute
+      # @return [Number] the number of cursor ids
+      int32    :number_of_cursor_ids
+
+      # @attribute
+      # @return [Array] the cursor ids to kill
+      int64    :cursor_ids, type: :array
+
+      # @return [Number] OP_KILL_CURSORS operation code (2007)
+      def op_code
+        2007
+      end
+
+      # Create a new command to kill cursors.
+      #
+      # @param [Array] cursor_ids an array of cursor ids to kill
+      # @param [Hash] options additional options
+      # @option options [Number] :request_id the command's request id
+      def initialize(cursor_ids, options = {})
+        @cursor_ids           = cursor_ids
+        @number_of_cursor_ids = cursor_ids.length
+        @request_id           = options[:request_id]
+      end
+
+      def log_inspect
+        type = "KILL_CURSORS"
+
+        "%-12s cursor_ids=%s" % [type, cursor_ids.inspect]
+      end
+    end
+  end
+end

data/lib/moped/protocol/message.rb

@@ -0,0 +1,320 @@
+module Moped
+  module Protocol
+
+    # The base class for building all messages needed to implement the Mongo
+    # Wire Protocol. It provides a minimal DSL for defining typed fields for
+    # serialization and deserialization over the wire.
+    #
+    # @example
+    #
+    #   class KillCursors < Moped::Protocol::Message
+    #     # header fields
+    #     int32 :length
+    #     int32 :request_id
+    #     int32 :response_to
+    #     int32 :op_code
+    #
+    #     # message fields
+    #     int32 :reserved
+    #     int32 :number_of_cursors
+    #     int64 :cursor_ids, type: :array
+    #
+    #     # Customize field reader
+    #     def number_of_cursors
+    #       cursor_ids.length
+    #     end
+    #   end
+    #
+    # Note that all messages *must* implement the header fields required by the
+    # Mongo Wire Protocol, namely:
+    #
+    #   int32 :length
+    #   int32 :request_id
+    #   int32 :response_to
+    #   int32 :op_code
+    #
+    module Message
+
+      class << self
+
+        # Extends the including class with +ClassMethods+.
+        #
+        # @param [Class] subclass the inheriting class
+        def included(base)
+          super
+
+          base.extend ClassMethods
+        end
+
+        private :included
+      end
+
+      # Provides a DSL for defining struct-like fields for building messages
+      # for the Mongo Wire.
+      #
+      # @example
+      #   class Command
+      #     extend Message::ClassMethods
+      #
+      #     int32 :length
+      #   end
+      #
+      #   Command.fields # => [:length]
+      #   command = Command.new
+      #   command.length = 12
+      #   command.serialize_length("") # => "\f\x00\x00\x00"
+      module ClassMethods
+
+        # @return [Array] the fields defined for this message
+        def fields
+          @fields ||= []
+        end
+
+        # Declare a null terminated string field.
+        #
+        # @example
+        #   class Query < Message
+        #     cstring :collection
+        #   end
+        #
+        # @param [String] name the name of this field
+        def cstring(name)
+          attr_accessor name
+
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def serialize_#{name}(buffer)
+              buffer << #{name}
+              buffer << 0
+            end
+          RUBY
+
+          fields << name
+        end
+
+        # Declare a BSON Document field.
+        #
+        # @example
+        #   class Update < Message
+        #     document :selector
+        #   end
+        #
+        # @example optional document field
+        #   class Query < Message
+        #     document :selector
+        #     document :fields, optional: true
+        #   end
+        #
+        # @example array of documents
+        #   class Reply < Message
+        #     document :documents, type: :array
+        #   end
+        #
+        # @param [String] name the name of this field
+        # @param [Hash] options the options for this field
+        # @option options [:array] :type specify an array of documents
+        # @option options [Boolean] :optional specify this field as optional
+        def document(name, options = {})
+          attr_accessor name
+
+          if options[:optional]
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def serialize_#{name}(buffer)
+                BSON::Document.serialize(#{name}, buffer) if #{name}
+              end
+            RUBY
+          elsif options[:type] == :array
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def serialize_#{name}(buffer)
+                #{name}.each do |document|
+                  BSON::Document.serialize(document, buffer)
+                end
+              end
+            RUBY
+          else
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def serialize_#{name}(buffer)
+                BSON::Document.serialize(#{name}, buffer)
+              end
+            RUBY
+          end
+
+          fields << name
+        end
+
+        # Declare a flag field (32 bit signed integer)
+        #
+        # @example
+        #   class Update < Message
+        #     flags :flags, upsert: 2 ** 0,
+        #                   multi:  2 ** 1
+        #   end
+        #
+        # @param [String] name the name of this field
+        # @param [Hash{Symbol => Number}] flags the flags for this flag field
+        def flags(name, flag_map = {})
+          attr_writer name
+
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{name}
+              @#{name} ||= []
+            end
+
+            def #{name}=(flags)
+              if flags.is_a? Numeric
+                @#{name} = #{name}_from_int(flags)
+              else
+                @#{name} = flags
+              end
+            end
+
+            def #{name}_as_int
+              bits = 0
+              flags = self.#{name}
+              #{flag_map.map { |flag, value| "bits |= #{value} if flags.include? #{flag.inspect}" }.join "\n"}
+              bits
+            end
+
+            def #{name}_from_int(bits)
+              flags = []
+              #{flag_map.map { |flag, value| "flags << #{flag.inspect} if #{value} & bits == #{value}" }.join "\n"}
+              flags
+            end
+
+            def serialize_#{name}(buffer)
+              buffer << [#{name}_as_int].pack('l<')
+            end
+
+            def deserialize_#{name}(buffer)
+              bits, = buffer.read(4).unpack('l<')
+
+              self.#{name} = bits
+            end
+          RUBY
+
+          fields << name
+        end
+
+        # Declare a 32 bit signed integer field.
+        #
+        # @example
+        #   class Query < Message
+        #     int32 :length
+        #   end
+        #
+        # @param [String] name the name of this field
+        def int32(name)
+          attr_writer name
+
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{name}
+              @#{name} ||= 0
+            end
+
+            def serialize_#{name}(buffer)
+              buffer << [#{name}].pack('l<')
+            end
+
+            def deserialize_#{name}(buffer)
+              self.#{name}, = buffer.read(4).unpack('l<')
+            end
+          RUBY
+
+          fields << name
+        end
+
+        # Declare a 64 bit signed integer field.
+        #
+        # @example
+        #   class Query < Message
+        #     int64 :cursor_id
+        #   end
+        #
+        # @example with array type
+        #   class KillCursors < Message
+        #     int64 :cursor_ids, type: :array
+        #   end
+        #
+        # @param [String] name the name of this field
+        # @param [Hash] options the options for this field
+        # @option options [:array] :type specify an array of 64 bit ints
+        def int64(name, options = {})
+          attr_writer name
+
+          if options[:type] == :array
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def #{name}
+                @#{name} ||= []
+              end
+
+              def serialize_#{name}(buffer)
+                buffer << #{name}.pack('q*<')
+              end
+
+              def deserialize_#{name}(buffer)
+                raise NotImplementedError
+              end
+            RUBY
+          else
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def #{name}
+                @#{name} ||= 0
+              end
+
+              def serialize_#{name}(buffer)
+                buffer << [#{name}].pack('q<')
+              end
+
+              def deserialize_#{name}(buffer)
+                self.#{name}, = buffer.read(8).unpack('q<')
+              end
+            RUBY
+          end
+
+          fields << name
+        end
+
+        private
+
+        # This ensures that subclasses of the primary wire message classes have
+        # identical fields.
+        def inherited(subclass)
+          super
+
+          subclass.fields.replace fields
+        end
+
+      end
+
+      # Serializes the message and all of its fields to a new buffer or to the
+      # provided buffer.
+      #
+      # @param [String] buffer a buffer to serialize to
+      # @return [String] the result of serliazing this message
+      def serialize(buffer = "")
+        buffer.tap do
+          start = buffer.length
+
+          self.class.fields.each do |field|
+            __send__ :"serialize_#{field}", buffer
+          end
+
+          self.length = buffer.length - start
+
+          buffer[start, 4] = serialize_length("")
+        end
+      end
+
+      alias to_s serialize
+
+      # @return [String] the nicely formatted version of the message
+      def inspect
+        fields = self.class.fields.map do |field|
+          "@#{field}=" + __send__(field).inspect
+        end
+        "#<#{self.class.name}\n" <<
+        "  #{fields * "\n  "}>"
+      end
+
+    end
+  end
+end