mongo 1.12.5 → 2.0.0.beta

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

data/lib/mongo/protocol/query.rb

@@ -0,0 +1,147 @@
+# 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 Query message.
+    #
+    # This is a client request message that is sent to the server in order
+    # to retrieve documents matching provided query.
+    #
+    # Users may also provide additional options such as a projection, to
+    # select a subset of the fields, a number to skip or a limit on the
+    # number of returned documents.
+    #
+    # There are a variety of flags that can be used to adjust cursor
+    # parameters or the desired consistancy and integrity the results.
+    #
+    # @api semipublic
+    class Query < Message
+
+      # Creates a new Query message
+      #
+      # @example Find all users named Tyler.
+      #   Query.new('xgen', 'users', {:name => 'Tyler'})
+      #
+      # @example Find all users named Tyler skipping 5 and returning 10.
+      #   Query.new('xgen', 'users', {:name => 'Tyler'}, :skip => 5,
+      #                                                  :limit => 10)
+      #
+      # @example Find all users with slave ok bit set
+      #   Query.new('xgen', 'users', {:name => 'Tyler'}, :flags => [:slave_ok])
+      #
+      # @example Find all user ids.
+      #   Query.new('xgen', 'users', {}, :fields => {:id => 1})
+      #
+      # @param database [String, Symbol] The database to query.
+      # @param collection [String, Symbol] The collection to query.
+      # @param selector [Hash] The query selector.
+      # @param options [Hash] The additional query options.
+      #
+      # @option options :project [Hash] The projection.
+      # @option options :skip [Integer] The number of documents to skip.
+      # @option options :limit [Integer] The number of documents to return.
+      # @option options :flags [Array] The flags for the query message.
+      #
+      #   Supported flags: +:tailable_cursor+, +:slave_ok+, +:oplog_replay+,
+      #   +:no_cursor_timeout+, +:await_data+, +:exhaust+, +:partial+
+      def initialize(database, collection, selector, options = {})
+        @namespace   = "#{database}.#{collection}"
+        @selector    = selector
+        @project     = options[:project]
+        @skip        = options[:skip]  || 0
+        @limit       = options[:limit] || 0
+        @flags       = options[:flags] || []
+      end
+
+      # The log message for a query operation.
+      #
+      # @example Get the log message.
+      #   query.log_message
+      #
+      # @return [ String ] The log message
+      #
+      # @since 2.0.0
+      def log_message
+        fields = []
+        fields << ["%s |", "QUERY"]
+        fields << ["namespace=%s", namespace]
+        fields << ["selector=%s", selector.inspect]
+        fields << ["flags=%s", flags.inspect]
+        fields << ["limit=%s", limit.inspect]
+        fields << ["skip=%s", skip.inspect]
+        fields << ["project=%s", project.inspect]
+        f, v = fields.transpose
+        f.join(" ") % v
+      end
+
+      # Query messages require replies from the database.
+      #
+      # @example Does the message require a reply?
+      #   message.replyable?
+      #
+      # @return [ true ] Always true for queries.
+      #
+      # @since 2.0.0
+      def replyable?
+        true
+      end
+
+      private
+
+      # The operation code required to specify a Query message.
+      # @return [Fixnum] the operation code.
+      def op_code
+        2004
+      end
+
+      # Available flags for a Query message.
+      FLAGS = [
+        :reserved,
+        :tailable_cursor,
+        :slave_ok,
+        :oplog_replay,
+        :no_cursor_timeout,
+        :await_data,
+        :exhaust,
+        :partial
+      ]
+
+      # @!attribute
+      # @return [Array<Symbol>] The flags for this query message.
+      field :flags, BitVector.new(FLAGS)
+
+      # @!attribute
+      # @return [String] The namespace for this query message.
+      field :namespace, CString
+
+      # @!attribute
+      # @return [Integer] The number of documents to skip.
+      field :skip, Int32
+
+      # @!attribute
+      # @return [Integer] The number of documents to return.
+      field :limit, Int32
+
+      # @!attribute
+      # @return [Hash] The query selector.
+      field :selector, Document
+
+      # @!attribute
+      # @return [Hash] The projection.
+      field :project, Document
+    end
+  end
+end