moped 0.0.0.beta → 1.0.0.alpha

data/lib/moped/protocol/query.rb

@@ -0,0 +1,131 @@
+module Moped
+  module Protocol
+    # The Protocol class for querying a collection.
+    #
+    # @example Find all users named John
+    #   Query.new "moped", "users", { name: "John" }
+    #
+    # @example Find all users named John skipping 5 and returning 10
+    #   Query.new "moped", "users", { name: "John" },
+    #     skip: 5, limit: 10
+    #
+    # @example Find all users on slave node
+    #   Query.new "moped", "users", {}, flags: [:slave_ok]
+    #
+    # @example Find all user ids
+    #   Query.new "moped", "users", {}, fields: { _id: 1 }
+    #
+    class Query
+      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: +:tailable+, +:slave_ok+,
+      # +:no_cursor_timeout+, +:await_data+, +:exhaust+.
+      #
+      # @param  [Array] flags the flags for this message
+      # @return [Array] the flags for this message
+      flags    :flags, tailable:          2 ** 1,
+                       slave_ok:          2 ** 2,
+                       no_cursor_timeout: 2 ** 4,
+                       await_data:        2 ** 5,
+                       exhaust:           2 ** 6
+
+      # @attribute
+      # @return [String] the namespaced collection name
+      cstring  :full_collection_name
+
+      # @attribute
+      # @return [Number] the number of documents to skip
+      int32    :skip
+
+      # @attribute
+      # @return [Number] the number of documents to return
+      int32    :limit
+
+      # @attribute
+      # @return [Hash] the selector for this query
+      document :selector
+
+      # @attribute
+      # @return [Hash, nil] the fields to include in the reply
+      document :fields, :optional => true
+
+      # @return [Number] OP_QUERY operation code (2004)
+      def op_code
+        2004
+      end
+
+      # @return [String, Symbol] the database to query
+      attr_reader :database
+
+      # @return [String, Symbol] the collection to query
+      attr_reader :collection
+
+      # Create a new query command.
+      #
+      # @example
+      #   Query.new "moped", "users", { name: "John" },
+      #     skip: 5,
+      #     limit: 10,
+      #     request_id: 12930,
+      #     fields: { _id: -1, name: 1 }
+      #
+      # @param [String, Symbol] database the database to insert into
+      # @param [String, Symbol] collection the collection to insert into
+      # @param [Hash] selector the query
+      # @param [Hash] options additional options
+      # @option options [Number] :request_id the command's request id
+      # @option options [Number] :skip the number of documents to skip
+      # @option options [Number] :limit the number of documents to return
+      # @option options [Hash] :fields the fields to return
+      # @option options [Array] :flags the flags for querying. Supported
+      #   flags: +:tailable+, +:slave_ok+, +:no_cursor_timeout+, +:await_data+,
+      #   +:exhaust+.
+      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]
+        @limit                = options[:limit]
+        @skip                 = options[:skip]
+        @fields               = options[:fields]
+      end
+
+      def log_inspect
+        type = "QUERY"
+
+        fields = []
+        fields << ["%-12s", type]
+        fields << ["database=%s", database]
+        fields << ["collection=%s", collection]
+        fields << ["selector=%s", selector.inspect]
+        fields << ["flags=%s", flags.inspect]
+        fields << ["limit=%s", limit.inspect]
+        fields << ["skip=%s", skip.inspect]
+        fields << ["fields=%s", self.fields.inspect]
+
+        f, v = fields.transpose
+
+        f.join(" ") % v
+      end
+
+    end
+  end
+end

data/lib/moped/protocol/reply.rb

@@ -0,0 +1,90 @@
+module Moped
+  module Protocol
+
+    # The Protocol class representing messages received from a mongo
+    # connection.
+    #
+    # @example
+    #   socket = TCPSocket.new "127.0.0.1", 27017
+    #   command = Moped::Protocol::Command.new "admin", buildinfo: 1
+    #   socket.write command.serialize
+    #   reply = Moped::Protocol::Reply.deserialize(socket)
+    #   reply.documents[0]["version"] # => "2.0.0"
+    class Reply
+      include Message
+
+      # @attribute
+      # @return [Number] the length of the message
+      int32 :length
+
+      # @attribute
+      # @return [Number] the request id of the message
+      int32 :request_id
+
+      # @attribute
+      # @return [Number] the id that generated the message
+      int32 :response_to
+
+      # @attribute
+      # @return [Number] the operation code of this message (always 1)
+      int32 :op_code
+
+      # @attribute
+      # @return [Array<Symbol>] the flags for this reply
+      flags    :flags, cursor_not_found:  2 ** 0,
+                       query_failure:     2 ** 1,
+                       await_capable:     2 ** 3
+
+      # @attribute
+      # @return [Number] the id of the cursor on the server
+      int64    :cursor_id
+
+      # @attribute
+      # @return [Number] the starting position within the cursor
+      int32    :offset
+
+      # @attribute
+      # @return [Number] the number of documents returned
+      int32    :count
+
+      # @attribute
+      # @return [Array] the returned documents
+      document :documents, type: :array
+
+      class << self
+
+        # Consumes a buffer, returning the deserialized Reply message.
+        #
+        # @example
+        #   socket = TCPSocket.new "localhost", 27017
+        #   socket.write Moped::Protocol::Command.new(:admin, ismaster: 1).serialize
+        #   reply = Moped::Protocol::Reply.deserialize(socket)
+        #   reply.documents[0]['ismaster'] # => 1
+        #
+        # @param [#read] buffer an IO or IO-like resource to deserialize the
+        # reply from.
+        # @return [Reply] the deserialized reply
+        def deserialize(buffer)
+          allocate.tap do |reply|
+            fields.each do |field|
+              reply.__send__ :"deserialize_#{field}", buffer
+            end
+          end
+        end
+      end
+
+      private
+
+      def deserialize_documents(buffer)
+        documents = []
+
+        count.times do
+          documents << BSON::Document.deserialize(buffer)
+        end
+
+        @documents = documents
+      end
+
+    end
+  end
+end

data/lib/moped/protocol/update.rb

@@ -0,0 +1,107 @@
+module Moped
+  module Protocol
+
+    # The Protocol class for updating documents in a collection.
+    #
+    # @example Rename a user
+    #   Update.new "moped", "users", { _id: "123" }, { name: "Bob" }
+    #
+    # @example Rename all users named John
+    #   Update.new "moped", "users", { name: "John" }, { name: "Bob" },
+    #     flags: [:multi]
+    #
+    # @example Upsert
+    #   Update.new "moped", "users", { name: "John" }, { name: "John" },
+    #     flags: [:upsert]
+    #
+    # @example Setting the request id
+    #   Update.new "moped", "users", {}, { name: "Bob" },
+    #     request_id: 123
+    class Update
+      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
+      # The flags for the update message. Supported flags are +:upsert+ and
+      # +:multi+.
+      # @param  [Array] flags the flags for this message
+      # @return [Array] the flags for this message
+      flags    :flags, upsert: 2 ** 0,
+                       multi:  2 ** 1
+
+      # @attribute
+      # @return [Hash] the selector for the update
+      document :selector
+
+      # @attribute
+      # @return [Hash] the updates to apply
+      document :update
+
+      # @return [Number] OP_UPDATE operation code (2001)
+      def op_code
+        2001
+      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 update command. The +database+ and +collection+ arguments
+      # are joined together to set the +full_collection_name+.
+      #
+      # @example
+      #   Update.new "moped", "users", { name: "John" }, { name: "Bob" },
+      #     flags: [:upsert],
+      #     request_id: 123
+      #
+      # @param [String, Symbol] database the database to insert into
+      # @param [String, Symbol] collection the collection to insert into
+      # @param [Hash] selector the selector
+      # @param [Hash] update the update to perform
+      # @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: +:upsert+, +:multi+.
+      def initialize(database, collection, selector, update, options = {})
+        @database = database
+        @collection = collection
+
+        @full_collection_name = "#{database}.#{collection}"
+        @selector             = selector
+        @update               = update
+        @request_id           = options[:request_id]
+        @flags                = options[:flags]
+      end
+
+      def log_inspect
+        type = "UPDATE"
+
+        "%-12s database=%s collection=%s selector=%s update=%s flags=%s" % [type, database, collection,
+                                                                            selector.inspect,
+                                                                            update.inspect,
+                                                                            flags.inspect]
+      end
+    end
+  end
+end

data/lib/moped/query.rb

@@ -0,0 +1,230 @@
+module Moped
+
+  # The +Query+ class encapsulates all of the logic related to building
+  # selectors for querying, updating, or removing documents in a collection.
+  #
+  # @example
+  #   people = db[:people]
+  #   people.find.entries # => [{id: 1}, {id: 2}, {id: 3}, {id: 4}, {id: 5}]
+  #   people.find.skip(2).first # => { id: 3 }
+  #   people.find.skip(2).update(name: "John")
+  #   people.find.skip(2).first # => { id: 3, name: "John" }
+  #
+  #   people.find(name: nil).update_all(name: "Unknown")
+  #   people.find.one # => { id: 5, name: "Unknown" }
+  #   people.find.first # => { id: 5, name: "Unknown" }
+  #   people.find.select(name: 0).first # => { id: 5 }
+  #   people.find(name: "Unknown").remove_all
+  #   people.find.count # => 1
+  class Query
+    include Enumerable
+
+    # @return [Collection] the query's collection
+    attr_reader :collection
+
+    # @return [Hash] the query's selector
+    attr_reader :selector
+
+    # @api private
+    attr_reader :operation
+
+    # @param [Collection] collection the query's collection
+    # @param [Hash] selector the query's selector
+    def initialize(collection, selector)
+      @collection = collection
+      @selector = selector
+
+      @operation = Protocol::Query.new(
+        collection.database.name,
+        collection.name,
+        selector
+      )
+    end
+
+    # Set the query's limit.
+    #
+    # @param [Numeric] limit
+    # @return [Query] self
+    def limit(limit)
+      operation.limit = limit
+      self
+    end
+
+    # Set the number of documents to skip.
+    #
+    # @param [Numeric] skip
+    # @return [Query] self
+    def skip(skip)
+      operation.skip = skip
+      self
+    end
+
+    # Set the sort order for the query.
+    #
+    # @example
+    #   db[:people].find.sort(name: 1, age: -1).one
+    #
+    # @param [Hash] sort
+    # @return [Query] self
+    def sort(sort)
+      operation.selector = { "$query" => selector, "$orderby" => sort }
+      self
+    end
+
+    # Explain the current query.
+    #
+    # @example Explain the query.
+    #   db[:people].find.explain
+    #
+    # @return [ Hash ] The explain document.
+    def explain
+      operation.selector = {
+        "$query" => selector,
+        "$orderby" => operation.selector.fetch("$orderby", {}),
+        "$explain" => true
+      } and first
+    end
+
+    # Set the fields to return from the query.
+    #
+    # @example
+    #   db[:people].find.select(name: 1).one # => { name: "John" }
+    #
+    # @param [Hash] select
+    # @return [Query] self
+    def select(select)
+      operation.fields = select
+      self
+    end
+
+    # @return [Hash] the first document that matches the selector.
+    def first
+      session.simple_query(operation)
+    end
+    alias one first
+
+    # Iterate through documents matching the query's selector.
+    #
+    # @yieldparam [Hash] document each matching document
+    def each
+      cursor = Cursor.new(session.with(retain_socket: true), operation)
+      cursor.to_enum.tap do |enum|
+        enum.each do |document|
+          yield document
+        end if block_given?
+      end
+    end
+
+    # Get the distinct values in the collection for the provided key.
+    #
+    # @example Get the distinct values.
+    #   query.distinct(:name)
+    #
+    # @param [ Symbol, String ] key The name of the field.
+    #
+    # @return [ Array<Object ] The distinct values.
+    def distinct(key)
+      result = collection.database.command(
+        distinct: collection.name,
+        key: key.to_s,
+        query: selector
+      )
+      result["values"]
+    end
+
+    # @return [Numeric] the number of documents that match the selector.
+    def count
+      result = collection.database.command(
+        count: collection.name,
+        query: selector
+      )
+
+      result["n"]
+    end
+
+    # Update a single document matching the query's selector.
+    #
+    # @example
+    #   db[:people].find(_id: 1).update(name: "John")
+    #
+    # @param [Hash] change the changes to make to the document
+    # @param [Array] flags an array of operation flags. Valid values are:
+    #   +:multi+ and +:upsert+
+    def update(change, flags = nil)
+      update = Protocol::Update.new(
+        operation.database,
+        operation.collection,
+        operation.selector,
+        change,
+        flags: flags
+      )
+
+      session.with(consistency: :strong) do |session|
+        session.execute update
+      end
+    end
+
+    # Update multiple documents matching the query's selector.
+    #
+    # @example
+    #   db[:people].find(name: "John").update_all(name: "Mary")
+    #
+    # @param [Hash] change the changes to make to the documents
+    def update_all(change)
+      update change, [:multi]
+    end
+
+    # Update an existing document with +change+, otherwise create one.
+    #
+    # @example
+    #   db[:people].find.entries # => { name: "John" }
+    #   db[:people].find(name: "John").upsert(name: "James")
+    #   db[:people].find.entries # => { name: "James" }
+    #   db[:people].find(name: "John").upsert(name: "Mary")
+    #   db[:people].find.entries # => [{ name: "James" }, { name: "Mary" }]
+    #
+    # @param [Hash] change the changes to make to the the document
+    def upsert(change)
+      update change, [:upsert]
+    end
+
+    # Remove a single document matching the query's selector.
+    #
+    # @example
+    #   db[:people].find(name: "John").remove
+    def remove
+      delete = Protocol::Delete.new(
+        operation.database,
+        operation.collection,
+        operation.selector,
+        flags: [:remove_first]
+      )
+
+      session.with(consistency: :strong) do |session|
+        session.execute delete
+      end
+    end
+
+    # Remove multiple documents matching the query's selector.
+    #
+    # @example
+    #   db[:people].find(name: "John").remove_all
+    def remove_all
+      delete = Protocol::Delete.new(
+        operation.database,
+        operation.collection,
+        operation.selector
+      )
+
+      session.with(consistency: :strong) do |session|
+        session.execute delete
+      end
+    end
+
+    private
+
+    def session
+      collection.database.session
+    end
+  end
+end