mongo 1.12.5 → 2.0.0

data/lib/mongo/protocol/bit_vector.rb

@@ -0,0 +1,61 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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
+  module Protocol
+    module Serializers
+      # Class used to define a bitvector for a MongoDB wire protocol message.
+      #
+      # Defines serialization strategy upon initialization.
+      #
+      # @api private
+      class BitVector
+
+        # Initializes a BitVector with a layout
+        #
+        # @param layout [Array<Symbol>] the array of fields in the bit vector
+        def initialize(layout)
+          @masks = {}
+          layout.each_with_index do |field, index|
+            @masks[field] = 2**index
+          end
+        end
+
+        # Serializes vector by encoding each symbol according to its mask
+        #
+        # @param buffer [IO] Buffer to receive the serialized vector
+        # @param value [Array<Symbol>] Array of flags to encode
+        # @return [IO] Buffer that received the serialized vector
+        def serialize(buffer, value)
+          bits = 0
+          value.each { |flag| bits |= @masks[flag] }
+          buffer << [bits].pack(INT32_PACK)
+        end
+
+        # Deserializes vector by decoding the symbol according to its mask
+        #
+        # @param io [IO] Stream containing the vector to be deserialized
+        # @return [Array<Symbol>] Flags contained in the vector
+        def deserialize(io)
+          vector = io.read(4).unpack(INT32_PACK).first
+          flags = []
+          @masks.each do |flag, mask|
+            flags << flag if mask & vector != 0
+          end
+          flags
+        end
+      end
+    end
+  end
+end

data/lib/mongo/protocol/delete.rb

@@ -0,0 +1,94 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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
+  module Protocol
+
+    # MongoDB Wire protocol Delete message.
+    #
+    # This is a client request message that is sent to the server in order
+    # to delete selected documents in the specified namespace.
+    #
+    # The operation, by default, operates on many documents. Setting
+    # the +:single_remove+ flag allows for a single matching document
+    # to be removed.
+    #
+    # @api semipublic
+    class Delete < Message
+
+      # Creates a new Delete message
+      #
+      # @example Remove all users named Tyler.
+      #   Query.new('xgen', 'users', {:name => 'Tyler'})
+      #
+      # @param database [String, Symbol] The database to remove from.
+      # @param collection [String, Symbol] The collection to remove from.
+      # @param selector [Hash] The query used to select doc(s) to remove.
+      # @param options [Hash] The additional delete options.
+      #
+      # @option options :flags [Array] The flags for the delete message.
+      #
+      #   Supported flags: +:single_remove+
+      def initialize(database, collection, selector, options = {})
+        @namespace = "#{database}.#{collection}"
+        @selector  = selector
+        @flags     = options[:flags] || []
+      end
+
+      # The log message for a delete operation.
+      #
+      # @example Get the log message.
+      #   delete.log_message
+      #
+      # @return [ String ] The log message
+      #
+      # @since 2.0.0
+      def log_message
+        fields = []
+        fields << ["%s |", "DELETE"]
+        fields << ["namespace=%s", namespace]
+        fields << ["selector=%s", selector.inspect]
+        fields << ["flags=%s", flags.inspect]
+        f, v = fields.transpose
+        f.join(" ") % v
+      end
+
+      private
+
+      # The operation code required to specify a Delete message.
+      # @return [Fixnum] the operation code.
+      def op_code
+        2006
+      end
+
+      # Available flags for a Delete message.
+      FLAGS = [:single_remove]
+
+      # Field representing Zero encoded as an Int32.
+      field :zero, Zero
+
+      # @!attribute
+      # @return [String] The namespace for this Delete message.
+      field :namespace, CString
+
+      # @!attribute
+      # @return [Array<Symbol>] The flags for this Delete message.
+      field :flags, BitVector.new(FLAGS)
+
+      # @!attribute
+      # @return [Hash] The selector for this Delete message.
+      field :selector, Document
+    end
+  end
+end

data/lib/mongo/protocol/get_more.rb

@@ -0,0 +1,99 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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
+  module Protocol
+
+    # MongoDB Wire protocol GetMore message.
+    #
+    # This is a client request message that is sent to the server in order
+    # to retrieve additional documents from a cursor that has already been
+    # instantiated.
+    #
+    # The operation requires that you specify the database and collection
+    # name as well as the cursor id because cursors are scoped to a namespace.
+    #
+    # @api semipublic
+    class GetMore < Message
+
+      # Creates a new GetMore message
+      #
+      # @example Get 15 additional documents from cursor 123 in 'xgen.users'.
+      #   GetMore.new('xgen', 'users', 15, 123)
+      #
+      # @param database [String, Symbol] The database to query.
+      # @param collection [String, Symbol] The collection to query.
+      # @param number_to_return [Integer] The number of documents to return.
+      # @param cursor_id [Integer] The cursor id returned in a reply.
+      def initialize(database, collection, number_to_return, cursor_id)
+        @namespace = "#{database}.#{collection}"
+        @number_to_return = number_to_return
+        @cursor_id = cursor_id
+      end
+
+      # The log message for a get more operation.
+      #
+      # @example Get the log message.
+      #   get_more.log_message
+      #
+      # @return [ String ] The log message
+      #
+      # @since 2.0.0
+      def log_message
+        fields = []
+        fields << ["%s |", "GETMORE"]
+        fields << ["namespace=%s", namespace]
+        fields << ["number_to_return=%s", number_to_return]
+        fields << ["cursor_id=%s", cursor_id]
+        f, v = fields.transpose
+        f.join(" ") % v
+      end
+
+      # Get more messages require replies from the database.
+      #
+      # @example Does the message require a reply?
+      #   message.replyable?
+      #
+      # @return [ true ] Always true for get more.
+      #
+      # @since 2.0.0
+      def replyable?
+        true
+      end
+
+      private
+
+      # The operation code required to specify a GetMore message.
+      # @return [Fixnum] the operation code.
+      def op_code
+        2005
+      end
+
+      # Field representing Zero encoded as an Int32
+      field :zero, Zero
+
+      # @!attribute
+      # @return [String] The namespace for this GetMore message.
+      field :namespace, CString
+
+      # @!attribute
+      # @return [Fixnum] The number to return for this GetMore message.
+      field :number_to_return, Int32
+
+      # @!attribute
+      # @return [Fixnum] The cursor id to get more documents from.
+      field :cursor_id, Int64
+    end
+  end
+end

data/lib/mongo/protocol/insert.rb

@@ -0,0 +1,99 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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
+  module Protocol
+
+    # MongoDB Wire protocol Insert message.
+    #
+    # This is a client request message that is sent to the server in order
+    # to insert documents within a namespace.
+    #
+    # The operation only has one flag +:continue_on_error+ which the user
+    # can use to instruct the database server to continue processing a bulk
+    # insertion if one happens to fail (e.g. due to duplicate IDs). This makes
+    # builk insert behave similarly to a seires of single inserts, except
+    # lastError will be set if any insert fails, not just the last one.
+    #
+    # If multiple errors occur, only the most recent will be reported by the
+    # getLastError mechanism.
+    #
+    # @api semipublic
+    class Insert < Message
+
+      # Creates a new Insert message
+      #
+      # @example Insert a user document
+      #   Insert.new('xgen', 'users', [{:name => 'Tyler'}])
+      #
+      # @example Insert serveral user documents and continue on errors
+      #   Insert.new('xgen', 'users', users, :flags => [:continue_on_error])
+      #
+      # @param database [String, Symbol]  The database to insert into.
+      # @param collection [String, Symbol] The collection to insert into.
+      # @param documents [Array<Hash>] The documents to insert.
+      # @param options [Hash] Additional options for the insertion.
+      #
+      # @option options :flags [Array] The flags for the insertion message.
+      #
+      #   Supported flags: +:continue_on_error+
+      def initialize(database, collection, documents, options = {})
+        @namespace = "#{database}.#{collection}"
+        @documents = documents
+        @flags = options[:flags] || []
+      end
+
+      # The log message for a insert operation.
+      #
+      # @example Get the log message.
+      #   insert.log_message
+      #
+      # @return [ String ] The log message
+      #
+      # @since 2.0.0
+      def log_message
+        fields = []
+        fields << ["%s |", "INSERT"]
+        fields << ["namespace=%s", namespace]
+        fields << ["documents=%s", documents.inspect]
+        fields << ["flags=%s", flags.inspect]
+        f, v = fields.transpose
+        f.join(" ") % v
+      end
+
+      private
+
+      # The operation code required to specify an Insert message.
+      # @return [Fixnum] the operation code.
+      def op_code
+        2002
+      end
+
+      # Available flags for an Insert message.
+      FLAGS = [:continue_on_error]
+
+      # @!attribute
+      # @return [Array<Symbol>] The flags for this Insert message.
+      field :flags, BitVector.new(FLAGS)
+
+      # @!attribute
+      # @return [String] The namespace for this Insert message.
+      field :namespace, CString
+
+      # @!attribute
+      # @return [Array<Hash>] The documents to insert.
+      field :documents, Document, true
+    end
+  end
+end

data/lib/mongo/protocol/kill_cursors.rb

@@ -0,0 +1,74 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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
+  module Protocol
+
+    # MongoDB Wire protocol KillCursors message.
+    #
+    # This is a client request message that is sent to the server in order
+    # to kill a number of cursors.
+    #
+    # @api semipublic
+    class KillCursors < Message
+
+      # Creates a new KillCursors message
+      #
+      # @example Kill the cursor on the server with id 1.
+      #   KillCursors.new([1])
+      #
+      # @param cursor_ids [Array<Fixnum>] The cursor ids to kill.
+      # @param options [Hash] The additional kill cursors options.
+      def initialize(cursor_ids, options = {})
+        @cursor_ids = cursor_ids
+        @id_count   = @cursor_ids.size
+      end
+
+      # The log message for a kill cursors operation.
+      #
+      # @example Get the log message.
+      #   kill_cursors.log_message
+      #
+      # @return [ String ] The log message
+      #
+      # @since 2.0.0
+      def log_message
+        fields = []
+        fields << ["%s |", "KILLCURSORS"]
+        fields << ["cursor_ids=%s", cursor_ids.inspect]
+        f, v = fields.transpose
+        f.join(" ") % v
+      end
+
+      private
+
+      # The operation code required to specify +KillCursors+ message.
+      # @return [Fixnum] the operation code.
+      def op_code
+        2007
+      end
+
+      # Field representing Zero encoded as an Int32.
+      field :zero, Zero
+
+      # @!attribute
+      # @return [Fixnum] Count of the number of cursor ids.
+      field :id_count, Int32
+
+      # @!attribute
+      # @return [Array<Fixnum>] Cursors to kill.
+      field :cursor_ids, Int64, true
+    end
+  end
+end

data/lib/mongo/protocol/message.rb

@@ -0,0 +1,252 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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
+  module Protocol
+
+    # A base class providing functionality required by all messages in
+    # the MongoDB wire protocol. It provides a minimal DSL for defining typed
+    # fields to enable serialization and deserialization over the wire.
+    #
+    # @example
+    #   class WireProtocolMessage < Message
+    #
+    #     private
+    #
+    #     def op_code
+    #       1234
+    #     end
+    #
+    #     FLAGS = [:first_bit, :bit_two]
+    #
+    #     # payload
+    #     field :flags, BitVector.new(FLAGS)
+    #     field :namespace, CString
+    #     field :document, Document
+    #     field :documents, Document, true
+    #   end
+    #
+    # @abstract
+    # @api semiprivate
+    class Message
+      include Serializers
+
+      # Returns the request id for the message
+      #
+      # @return [Fixnum] The request id for this message
+      attr_reader :request_id
+
+      # The default for messages is not to require a reply after sending a
+      # message to the server.
+      #
+      # @example Does the message require a reply?
+      #   message.replyable?
+      #
+      # @return [ false ] The default is to not require a reply.
+      #
+      # @since 2.0.0
+      def replyable?
+        false
+      end
+
+      # Serializes message into bytes that can be sent on the wire
+      #
+      # @param buffer [String] buffer where the message should be inserted
+      # @return [String] buffer containing the serialized message
+      def serialize(buffer = ''.force_encoding('BINARY'), max_bson_size = nil)
+        start = buffer.bytesize
+        serialize_header(buffer)
+        serialize_fields(buffer, max_bson_size)
+        length = buffer.bytesize - start
+        buffer[start, 4] = Int32.serialize('', length)
+        buffer
+      end
+
+      alias_method :to_s, :serialize
+
+      # Deserializes messages from an IO stream
+      #
+      # @param io [IO] Stream containing a message
+      # @return [Message] Instance of a Message class
+      def self.deserialize(io)
+        deserialize_header(io)
+        message = allocate
+        fields.each do |field|
+          if field[:multi]
+            deserialize_array(message, io, field)
+          else
+            deserialize_field(message, io, field)
+          end
+        end
+        message
+      end
+
+      # Tests for equality between two wire protocol messages
+      # by comparing class and field values.
+      #
+      # @param other [Mongo::Protocol::Message] The wire protocol message.
+      # @return [true, false] The equality of the messages.
+      def ==(other)
+        return false if self.class != other.class
+        fields.all? do |field|
+          name = field[:name]
+          instance_variable_get(name) ==
+            other.instance_variable_get(name)
+        end
+      end
+      alias_method :eql?, :==
+
+      # Creates a hash from the values of the fields of a message.
+      #
+      # @return [ Fixnum ] The hash code for the message.
+      def hash
+        fields.map { |field| instance_variable_get(field[:name]) }.hash
+      end
+
+      private
+
+      @@request_id = 0
+      @@id_lock = Mutex.new
+
+      # A method for getting the fields for a message class
+      #
+      # @return [Integer] the fields for the message class
+      def fields
+        self.class.fields
+      end
+
+      # A class method for getting the fields for a message class
+      #
+      # @return [Integer] the fields for the message class
+      def self.fields
+        @fields ||= []
+      end
+
+      # Serializes message fields into a buffer
+      #
+      # @param buffer [String] buffer to receive the field
+      # @return [String] buffer with serialized field
+      def serialize_fields(buffer, max_bson_size = nil)
+        fields.each do |field|
+          value = instance_variable_get(field[:name])
+          if field[:multi]
+            value.each do |item|
+              if field[:type].respond_to?(:size_limited?)
+                field[:type].serialize(buffer, item, max_bson_size)
+              else
+                field[:type].serialize(buffer, item)
+              end
+            end
+          else
+            if field[:type].respond_to?(:size_limited?)
+              field[:type].serialize(buffer, value, max_bson_size)
+            else
+              field[:type].serialize(buffer, value)
+            end
+          end
+        end
+      end
+
+      # Generates a request id for a message
+      #
+      # @return [Fixnum] a request id used for sending a message to the
+      #   server. The server will put this id in the response_to field of
+      #   a reply.
+      def set_request_id
+        @@id_lock.synchronize do
+          @request_id = @@request_id += 1
+        end
+      end
+
+      # Serializes the header of the message consisting of 4 32bit integers
+      #
+      # The integers represent a message length placeholder (calculation of
+      # the actual length is deferred) the request id, the response to id,
+      # and the op code for the message
+      #
+      # Currently uses hardcoded 0 for request id and response to as their
+      # values are irrelevent to the server
+      #
+      # @param buffer [String] Buffer to receive the header
+      # @return [String] Serialized header
+      def serialize_header(buffer)
+        set_request_id
+        Header.serialize(buffer, [0, request_id, 0, op_code])
+      end
+
+      # Deserializes the header of the message
+      #
+      # @param io [IO] Stream containing the header.
+      # @return [Array<Fixnum>] Deserialized header.
+      def self.deserialize_header(io)
+        @length, @request_id, @response_to, @op_code = Header.deserialize(io)
+      end
+
+      # A method for declaring a message field
+      #
+      # @param name [String] Name of the field
+      # @param type [Module] Type specific serialization strategies
+      # @param multi [true, false, Symbol] Specify as +true+ to
+      #   serialize the field's value as an array of type +:type+ or as a
+      #   symbol describing the field having the number of items in the
+      #   array (used upon deserialization)
+      #
+      #     Note: In fields where multi is a symbol representing the field
+      #     containing number items in the repetition, the field containing
+      #     that information *must* be deserialized prior to deserializing
+      #     fields that use the number.
+      #
+      # @return [NilClass]
+      def self.field(name, type, multi = false)
+        fields << {
+          :name => "@#{name}".intern,
+          :type => type,
+          :multi => multi
+        }
+
+        attr_reader name
+      end
+
+      # Deserializes an array of fields in a message
+      #
+      # The number of items in the array must be described by a previously
+      # deserialized field specified in the class by the field dsl under
+      # the key +:multi+
+      #
+      # @param message [Message] Message to contain the deserialized array.
+      # @param io [IO] Stream containing the array to deserialize.
+      # @param field [Hash] Hash representing a field.
+      # @return [Message] Message with deserialized array.
+      def self.deserialize_array(message, io, field)
+        elements = []
+        count = message.instance_variable_get(field[:multi])
+        count.times { elements << field[:type].deserialize(io) }
+        message.instance_variable_set(field[:name], elements)
+      end
+
+      # Deserializes a single field in a message
+      #
+      # @param message [Message] Message to contain the deserialized field.
+      # @param io [IO] Stream containing the field to deserialize.
+      # @param field [Hash] Hash representing a field.
+      # @return [Message] Message with deserialized field.
+      def self.deserialize_field(message, io, field)
+        message.instance_variable_set(
+          field[:name],
+          field[:type].deserialize(io)
+        )
+      end
+    end
+  end
+end