mongo 1.12.5 → 2.0.0

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

data/lib/mongo/protocol/reply.rb

@@ -0,0 +1,72 @@
+# 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
+
+    # The MongoDB wire protocol message representing a reply
+    #
+    # @example
+    #   socket = TCPSocket.new('localhost', 27017)
+    #   query = Protocol::Query.new('xgen', 'users', {:name => 'Tyler'})
+    #   socket.write(query)
+    #   reply = Protocol::Reply::deserialize(socket)
+    #
+    # @api semipublic
+    class Reply < Message
+
+      private
+
+      # The operation code required to specify a Reply message.
+      # @return [Fixnum] the operation code.
+      def op_code
+        1
+      end
+
+      # Available flags for a Reply message.
+      FLAGS = [
+        :cursor_not_found,
+        :query_failure,
+        :shard_config_stale,
+        :await_capable
+      ]
+
+      public
+
+      # @!attribute
+      # @return [Array<Symbol>] The flags for this reply.
+      #
+      #   Supported flags: +:cursor_not_found+, +:query_failure+,
+      #   +:shard_config_stale+, +:await_capable+
+      field :flags, BitVector.new(FLAGS)
+
+      # @!attribute
+      # @return [Fixnum] The cursor id for this response. Will be zero
+      #   if there are no additional results.
+      field :cursor_id, Int64
+
+      # @!attribute
+      # @return [Fixnum] The starting position of the cursor for this Reply.
+      field :starting_from, Int32
+
+      # @!attribute
+      # @return [Fixnum] Number of documents in this Reply.
+      field :number_returned, Int32
+
+      # @!attribute
+      # @return [Array<Hash>] The documents in this Reply.
+      field :documents, Document, :@number_returned
+    end
+  end
+end

data/lib/mongo/protocol/serializers.rb

@@ -0,0 +1,180 @@
+# 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
+
+    # Container for various serialization strategies
+    #
+    # Each strategy must have a serialization method named +serailize+
+    # and a deserialization method named +deserialize+
+    #
+    # Serialize methods must take buffer and value arguements and
+    # serialize the value into the buffer
+    #
+    # Deserialize methods must take an IO stream argument and
+    # deserialize the value from the stream of bytes
+    #
+    # @api private
+    module Serializers
+
+      private
+
+      ZERO = 0.freeze
+      NULL = 0.chr.freeze
+      INT32_PACK = 'l<'.freeze
+      INT64_PACK = 'q<'.freeze
+      HEADER_PACK = 'l<l<l<l<'.freeze
+
+      # MongoDB wire protocol serialization strategy for message headers.
+      #
+      # Serializes and de-serializes four 32-bit integers consisting
+      # of the length of the message, the request id, the response id,
+      # and the op code for the operation.
+      module Header
+
+        # Serializes the header value into the buffer
+        #
+        # @param buffer [String] Buffer to receive the serialized value.
+        # @param value [String] Header value to be serialized.
+        # @return [String] Buffer with serialized value.
+        def self.serialize(buffer, value)
+          buffer << value.pack(HEADER_PACK)
+        end
+
+        # Deserializes the header value from the IO stream
+        #
+        # @param io [IO] IO stream containing the message header.
+        # @return [Array<Fixnum>] Array consisting of the deserialized
+        #   length, request id, response id, and op code.
+        def self.deserialize(io)
+          io.read(16).unpack(HEADER_PACK)
+        end
+      end
+
+      # MongoDB wire protocol serialization strategy for C style strings.
+      #
+      # Serializes and de-serializes C style strings (null terminated).
+      module CString
+
+        # Serializes a C style string into the buffer
+        #
+        # @param buffer [String] Buffer to receive the serialized CString.
+        # @param value [String] The string to be serialized.
+        # @return [String] Buffer with serialized value.
+        def self.serialize(buffer, value)
+          buffer << value
+          buffer << NULL
+        end
+      end
+
+      # MongoDB wire protocol serialization strategy for 32-bit Zero.
+      #
+      # Serializes and de-serializes one 32-bit Zero.
+      module Zero
+
+        # Serializes a 32-bit Zero into the buffer
+        #
+        # @param buffer [String] Buffer to receive the serialized Zero.
+        # @param value [Fixnum] Ignored value.
+        # @return [String] Buffer with serialized value.
+        def self.serialize(buffer, value)
+          buffer << [ZERO].pack(INT32_PACK)
+        end
+      end
+
+      # MongoDB wire protocol serialization strategy for 32-bit integers.
+      #
+      # Serializes and de-serializes one 32-bit integer.
+      module Int32
+
+        # Serializes a fixnum to a 4-byte 32-bit integer
+        #
+        # @param buffer [String] Buffer to receive the serialized Int32.
+        # @param value [Fixnum] 32-bit integer to be serialized.
+        # @return [String] Buffer with serialized value.
+        def self.serialize(buffer, value)
+          buffer << [value].pack(INT32_PACK)
+        end
+
+        # Deserializes a 32-bit Fixnum from the IO stream
+        #
+        # @param io [IO] IO stream containing the 32-bit integer
+        # @return [Fixnum] Deserialized Int32
+        def self.deserialize(io)
+          io.read(4).unpack(INT32_PACK).first
+        end
+      end
+
+      # MongoDB wire protocol serialization strategy for 64-bit integers.
+      #
+      # Serializes and de-serializes one 64-bit integer.
+      module Int64
+
+        # Serializes a fixnum to an 8-byte 64-bit integer
+        #
+        # @param buffer [String] Buffer to receive the serialized Int64.
+        # @param value [Fixnum] 64-bit integer to be serialized.
+        # @return [String] Buffer with serialized value.
+        def self.serialize(buffer, value)
+          buffer << [value].pack(INT64_PACK)
+        end
+
+        # Deserializes a 64-bit Fixnum from the IO stream
+        #
+        # @param io [IO] IO stream containing the 64-bit integer.
+        # @return [Fixnum] Deserialized Int64.
+        def self.deserialize(io)
+          io.read(8).unpack(INT64_PACK).first
+        end
+      end
+
+      # MongoDB wire protocol serialization strategy for a BSON Document.
+      #
+      # Serializes and de-serializes a single document.
+      module Document
+
+        # Serializes a document into the buffer
+        #
+        # @param buffer [String] Buffer to receive the BSON encoded document.
+        # @param value [Hash] Document to serialize as BSON.
+        # @return [String] Buffer with serialized value.
+        def self.serialize(buffer, value, max_bson_size = nil)
+          start_size = buffer.size
+          value.to_bson(buffer)
+          if max_bson_size && buffer.size - start_size > max_bson_size
+            raise Error::MaxBSONSize.new(max_bson_size)
+          end
+        end
+
+        # Deserializes a document from the IO stream
+        #
+        # @param io [IO] IO stream containing the BSON encoded document.
+        # @return [Hash] The decoded BSON document.
+        def self.deserialize(io)
+          BSON::Document.from_bson(io)
+        end
+
+        # Whether there can be a size limit on this type after serialization.
+        #
+        # @return [ true ] Documents can be size limited upon serialization.
+        #
+        # @since 2.0.0
+        def self.size_limited?
+          true
+        end
+      end
+    end
+  end
+end

data/lib/mongo/protocol/update.rb

@@ -0,0 +1,111 @@
+# 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 Update message.
+    #
+    # This is a client request message that is sent to the server in order
+    # to update documents matching the provided query.
+    #
+    # The default is to update a single document. In order to update many at
+    # a time users should set the +:multi_update+ flag for the update.
+    #
+    # If an upsert (update or insert) is desired, users can set the +:upsert+
+    # flag in order to indicate they would like to insert the merged selector
+    # and update if no document matching the update query currently exists.
+    #
+    # @api semipublic
+    class Update < Message
+
+      # Creates a new Update message
+      #
+      # @example Update single document
+      #   Update.new('xgen', 'users', {:name => 'Tyler'}, {:name => 'Bob'})
+      #
+      # @example Perform a multi update
+      #   Update.new('xgen', 'users',
+      #     {:age => 20}, {:age => 21}, :flags => [:multi_update])
+      #
+      # @example Perform an upsert
+      #   Update.new('xgen', 'users', {:name => 'Tyler'}, :flags => [:upsert])
+      #
+      # @param database [String, Symbol]  The database to update.
+      # @param collection [String, Symbol] The collection to update.
+      # @param selector [Hash] The update selector.
+      # @param update [Hash] The update to perform.
+      # @param options [Hash] The additional query options.
+      #
+      # @option options :flags [Array] The flags for the update message.
+      #
+      #   Supported flags: +:upsert+, +:multi_update+
+      def initialize(database, collection, selector, update, options = {})
+        @namespace   = "#{database}.#{collection}"
+        @selector    = selector
+        @update      = update
+        @flags       = options[:flags] || []
+      end
+
+      # The log message for an update operation.
+      #
+      # @example Get the log message.
+      #   update.log_message
+      #
+      # @return [ String ] The log message
+      #
+      # @since 2.0.0
+      def log_message
+        fields = []
+        fields << ["%s |", "UPDATE"]
+        fields << ["namespace=%s", namespace]
+        fields << ["selector=%s", selector.inspect]
+        fields << ["udpdate=%s", update.inspect]
+        fields << ["flags=%s", flags.inspect]
+        f, v = fields.transpose
+        f.join(" ") % v
+      end
+
+      private
+
+      # The operation code required to specify an Update message.
+      # @return [Fixnum] the operation code.
+      def op_code
+        2001
+      end
+
+      # Available flags for an Update message.
+      FLAGS = [:upsert, :multi_update]
+
+      # Field representing Zero encoded as an Int32.
+      field :zero, Zero
+
+      # @!attribute
+      # @return [String] The namespace for this Update message.
+      field :namespace, CString
+
+      # @!attribute
+      # @return [Array<Symbol>] The flags for this Update message.
+      field :flags, BitVector.new(FLAGS)
+
+      # @!attribute
+      # @return [Hash] The selector for this Update message.
+      field :selector, Document
+
+      # @!attribute
+      # @return [Hash] The update for this Delete message.
+      field :update, Document
+    end
+  end
+end

data/lib/mongo/protocol.rb

@@ -0,0 +1,15 @@
+# Wire Protocol Base
+require 'mongo/protocol/serializers'
+require 'mongo/protocol/bit_vector'
+require 'mongo/protocol/message'
+
+# Client Requests
+require 'mongo/protocol/delete'
+require 'mongo/protocol/get_more'
+require 'mongo/protocol/insert'
+require 'mongo/protocol/kill_cursors'
+require 'mongo/protocol/query'
+require 'mongo/protocol/update'
+
+# Server Responses
+require 'mongo/protocol/reply'

data/lib/mongo/server/connectable.rb

@@ -0,0 +1,110 @@
+# Copyright (C) 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
+  class Server
+
+    # This provides common behaviour for connection objects.
+    #
+    # @since 2.0.0
+    module Connectable
+      include Loggable
+
+      # The default time in seconds to timeout a connection attempt.
+      #
+      # @since 2.0.0
+      TIMEOUT = 5.freeze
+
+      # @return [ Mongo::Address ] address The address to connect to.
+      attr_reader :address
+
+      # @return [ Hash ] options The passed in options.
+      attr_reader :options
+
+      # @return [ Integer ] pid The process id when the connection was created.
+      attr_reader :pid
+
+      # Determine if the connection is currently connected.
+      #
+      # @example Is the connection connected?
+      #   connection.connected?
+      #
+      # @return [ true, false ] If connected.
+      #
+      # @since 2.0.0
+      def connected?
+        !!@socket && @socket.alive?
+      end
+
+      # Dispatch the provided messages to the connection. If the last message
+      # requires a response a reply will be returned.
+      #
+      # @example Dispatch the messages.
+      #   connection.dispatch([ insert, command ])
+      #
+      # @note This method is named dispatch since 'send' is a core Ruby method on
+      #   all objects.
+      #
+      # @param [ Array<Message> ] messages The messages to dispatch.
+      #
+      # @return [ Protocol::Reply ] The reply if needed.
+      #
+      # @since 2.0.0
+      def dispatch(messages)
+        log_debug(messages) do |msgs|
+          write(msgs)
+          msgs.last.replyable? ? read : nil
+        end
+      end
+
+      # Get the connection timeout.
+      #
+      # @example Get the connection timeout.
+      #   connection.timeout
+      #
+      # @return [ Float ] The connection timeout in seconds.
+      #
+      # @since 2.0.0
+      def timeout
+        @timeout ||= options[:socket_timeout] || TIMEOUT
+      end
+
+      private
+
+      attr_reader :socket, :ssl_options
+
+      def ensure_connected
+        ensure_same_process!
+        connect! if socket.nil? || !socket.alive?
+        begin
+          yield socket
+        rescue Error::SocketError, Error::SocketTimeoutError => e
+          disconnect!
+          raise e
+        end
+      end
+
+      def ensure_same_process!
+        if pid != Process.pid
+          disconnect!
+          @pid = Process.pid
+        end
+      end
+
+      def read
+        ensure_connected{ |socket| Protocol::Reply.deserialize(socket) }
+      end
+    end
+  end
+end