mongo 1.12.5 → 2.0.0.beta

data/lib/mongo/loggable.rb

@@ -0,0 +1,126 @@
+# 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
+
+  # Allows objects to easily log operations.
+  #
+  # @since 2.0.0
+  module Loggable
+
+    # The standard MongoDB log prefix.
+    #
+    # @since 2.0.0
+    PREFIX = 'MONGODB'.freeze
+
+    # Log the operations. If a block is provided it will be yielded to,
+    # otherwise only the logging will take place.
+    #
+    # @example Log a query operation.
+    #   loggable.log(:debug, "MONGO.query", operations)
+    #
+    # @param [ Symbol ] level The log level.
+    # @param [ String ] prefix The prefix for the log line.
+    # @param [ Array<Object> ] operations The operations to log. The must
+    #   respond to #log_message.
+    #
+    # @return [ Object ] The result of the block or nil if no block given.
+    #
+    # @since 2.0.0
+    def log(level, prefix, operations)
+      started = Time.new
+      begin
+        yield(operations) if block_given?
+      rescue Exception => e
+        raise e
+      ensure
+        runtime = ("%.4fms" % (1000 * (Time.now.to_f - started.to_f)))
+        operations.each do |operation|
+          Logger.send(level, prefix, log_inspect(operation), runtime)
+        end
+      end
+    end
+
+    # Convenience method to log debug messages with the standard prefix.
+    #
+    # @example Log a debug message.
+    #   log_debug([ 'Message' ])
+    #
+    # @param [ Array<Operation, String> ] operations The operations or messages
+    #   to log.
+    #
+    # @since 2.0.0
+    def log_debug(operations, &block)
+      log(:debug, PREFIX, operations, &block)
+    end
+
+    # Convenience method to log error messages with the standard prefix.
+    #
+    # @example Log a error message.
+    #   log_error([ 'Message' ])
+    #
+    # @param [ Array<Operation, String> ] operations The operations or messages
+    #   to log.
+    #
+    # @since 2.0.0
+    def log_error(operations, &block)
+      log(:error, PREFIX, operations, &block)
+    end
+
+    # Convenience method to log fatal messages with the standard prefix.
+    #
+    # @example Log a fatal message.
+    #   log_fatal([ 'Message' ])
+    #
+    # @param [ Array<Operation, String> ] operations The operations or messages
+    #   to log.
+    #
+    # @since 2.0.0
+    def log_fatal(operations, &block)
+      log(:fatal, PREFIX, operations, &block)
+    end
+
+    # Convenience method to log info messages with the standard prefix.
+    #
+    # @example Log a info message.
+    #   log_info([ 'Message' ])
+    #
+    # @param [ Array<Operation, String> ] operations The operations or messages
+    #   to log.
+    #
+    # @since 2.0.0
+    def log_info(operations, &block)
+      log(:info, PREFIX, operations, &block)
+    end
+
+    # Convenience method to log warn messages with the standard prefix.
+    #
+    # @example Log a warn message.
+    #   log_warn([ 'Message' ])
+    #
+    # @param [ Array<Operation, String> ] operations The operations or messages
+    #   to log.
+    #
+    # @since 2.0.0
+    def log_warn(operations, &block)
+      log(:warn, PREFIX, operations, &block)
+    end
+
+    private
+
+    def log_inspect(operation)
+      operation.respond_to?(:log_message) ? operation.log_message : operation
+    end
+  end
+end

data/lib/mongo/logger.rb

@@ -0,0 +1,132 @@
+# 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.
+
+require 'logger'
+
+module Mongo
+
+  # Provides ability to log messages.
+  #
+  # @since 2.0.0
+  class Logger
+
+    class << self
+
+      # Log a debug level message.
+      #
+      # @example Log a debug level message.
+      #   Logger.debug('mongo', 'message', '10ms')
+      #
+      # @param [ String ] prefix The category prefix.
+      # @param [ String ] message The log message.
+      # @param [ String ] runtime The time of the operation.
+      #
+      # @since 2.0.0
+      def debug(prefix, message, runtime)
+        logger.debug("#{prefix} | #{message} | runtime: #{runtime}")
+      end
+
+      # Log a error level message.
+      #
+      # @example Log a error level message.
+      #   Logger.error('mongo', 'message', '10ms')
+      #
+      # @param [ String ] prefix The category prefix.
+      # @param [ String ] message The log message.
+      # @param [ String ] runtime The time of the operation.
+      #
+      # @since 2.0.0
+      def error(prefix, message, runtime)
+        logger.error("#{prefix} | #{message} | runtime: #{runtime}")
+      end
+
+      # Log a fatal level message.
+      #
+      # @example Log a fatal level message.
+      #   Logger.fatal('mongo', 'message', '10ms')
+      #
+      # @param [ String ] prefix The category prefix.
+      # @param [ String ] message The log message.
+      # @param [ String ] runtime The time of the operation.
+      #
+      # @since 2.0.0
+      def fatal(prefix, message, runtime)
+        logger.fatal("#{prefix} | #{message} | runtime: #{runtime}")
+      end
+
+      # Log a info level message.
+      #
+      # @example Log a info level message.
+      #   Logger.info('mongo', 'message', '10ms')
+      #
+      # @param [ String ] prefix The category prefix.
+      # @param [ String ] message The log message.
+      # @param [ String ] runtime The time of the operation.
+      #
+      # @since 2.0.0
+      def info(prefix, message, runtime)
+        logger.info("#{prefix} | #{message} | runtime: #{runtime}")
+      end
+
+      # Log a warn level message.
+      #
+      # @example Log a warn level message.
+      #   Logger.warn('mongo', 'message', '10ms')
+      #
+      # @param [ String ] prefix The category prefix.
+      # @param [ String ] message The log message.
+      # @param [ String ] runtime The time of the operation.
+      #
+      # @since 2.0.0
+      def warn(prefix, message, runtime)
+        logger.warn("#{prefix} | #{message} | runtime: #{runtime}")
+      end
+
+      # Get the wrapped logger. If none was set will return a default debug
+      # level logger.
+      #
+      # @example Get the wrapped logger.
+      #   Mongo::Logger.logger
+      #
+      # @return [ ::Logger ] The wrapped logger.
+      #
+      # @since 2.0.0
+      def logger
+        @logger ||= default_logger
+      end
+
+      # Set the logger.
+      #
+      # @example Set the wrapped logger.
+      #   Mongo::Logger.logger = logger
+      #
+      # @param [ ::Logger ] other The logger to set.
+      #
+      # @return [ ::Logger ] The wrapped logger.
+      #
+      # @since 2.0.0
+      def logger=(other)
+        @logger = other
+      end
+
+      private
+
+      def default_logger
+        logger = ::Logger.new($stdout)
+        logger.level = ::Logger::DEBUG
+        logger
+      end
+    end
+  end
+end

data/lib/mongo/operation.rb

@@ -0,0 +1,26 @@
+# 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.
+
+require 'mongo/operation/result'
+require 'mongo/operation/executable'
+require 'mongo/operation/specifiable'
+require 'mongo/operation/limited'
+require 'mongo/operation/read_preferrable'
+require 'mongo/operation/batchable'
+require 'mongo/operation/read'
+require 'mongo/operation/write'
+require 'mongo/operation/aggregate'
+require 'mongo/operation/command'
+require 'mongo/operation/kill_cursors'
+require 'mongo/operation/map_reduce'

data/lib/mongo/operation/aggregate.rb

@@ -0,0 +1,100 @@
+# 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.
+
+require 'mongo/operation/aggregate/result'
+
+module Mongo
+  module Operation
+
+    # A MongoDB aggregate operation.
+    #
+    # @note An aggregate operation can behave like a read and return a 
+    #   result set, or can behave like a write operation and
+    #   output results to a user-specified collection.
+    #
+    # @example Create the aggregate operation.
+    #   Aggregate.new({
+    #     :selector => {
+    #       :aggregate => 'test_coll', :pipeline => [{ '$out' => 'test-out' }]
+    #     },
+    #     :db_name => 'test_db'
+    #   })
+    #
+    # @param [ Hash ] spec The specifications for the operation.
+    #
+    # @option spec :selector [ Hash ] The aggregate selector.
+    # @option spec :db_name [ String ] The name of the database on which
+    #   the operation should be executed.
+    # @option spec :options [ Hash ] Options for the aggregate command.
+    #
+    # @since 2.0.0
+    class Aggregate
+      include Executable
+      include Specifiable
+      include Limited
+
+      # The need primary error message.
+      #
+      # @since 2.0.0
+      ERROR_MESSAGE = "The pipeline contains the '$out' operator so the primary must be used.".freeze
+
+      # Execute the operation.
+      # The context gets a connection on which the operation
+      # is sent in the block.
+      # If the aggregation will be written to an output collection and the
+      # server is not primary, the operation will be rerouted to the primary
+      # with a warning.
+      #
+      # @params [ Mongo::Server::Context ] The context for this operation.
+      #
+      # @return [ Result ] The operation response, if there is one.
+      #
+      # @since 2.0.0
+      def execute(context)
+        unless context.standalone? || context.primary? || secondary_ok?
+          raise Error::NeedPrimaryServer.new(ERROR_MESSAGE)
+        end
+        execute_message(context)
+      end
+
+      private
+
+      def execute_message(context)
+        context.with_connection do |connection|
+          Result.new(connection.dispatch([ message(context) ]))
+        end
+      end
+
+      # Whether this operation can be executed on a replica set secondary server.
+      # The aggregate operation may not be executed on a secondary if the user has specified
+      # an output collection to which the results will be written.
+      #
+      # @return [ true, false ] Whether the operation can be executed on a secondary.
+      #
+      # @since 2.0.0
+      def secondary_ok?
+        selector[:pipeline].none? { |op| op.key?('$out') || op.key?(:$out) }
+      end
+
+      def filter(context)
+        return selector if context.features.write_command_enabled?
+        selector.reject{ |option, value| option.to_s == 'cursor' }
+      end
+
+      def message(context)
+        Protocol::Query.new(db_name, Database::COMMAND, filter(context), options)
+      end
+    end
+  end
+end

data/lib/mongo/operation/aggregate/result.rb

@@ -0,0 +1,84 @@
+# 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 Operation
+    class Aggregate
+
+      # Defines custom behaviour of results in an aggregation context.
+      #
+      # @since 2.0.0
+      class Result < Operation::Result
+
+        # The field name for the cursor document in an aggregation.
+        #
+        # @since 2.0.0
+        CURSOR = 'cursor'.freeze
+
+        # The cursor id field in the cursor document.
+        #
+        # @since 2.0.0
+        CURSOR_ID = 'id'.freeze
+
+        # The field name for the first batch of a cursor.
+        #
+        # @since 2.0.0
+        FIRST_BATCH = 'firstBatch'.freeze
+
+        # The field name for a result without a cursor.
+        #
+        # @since 2.0.0
+        RESULT = 'result'.freeze
+
+        # Get the cursor id for the result.
+        #
+        # @example Get the cursor id.
+        #   result.cursor_id
+        #
+        # @note Even though the wire protocol has a cursor_id field for all
+        #   messages of type reply, it is always zero when using the
+        #   aggregation framework and must be retrieved from the cursor
+        #   document itself. Wahnsinn!
+        #
+        # @return [ Integer ] The cursor id.
+        #
+        # @since 2.0.0
+        def cursor_id
+          cursor_document ? cursor_document[CURSOR_ID] : super
+        end
+
+        # Get the documents for the aggregation result. This is either the
+        # first document's 'result' field, or if a cursor option was selected
+        # it is the 'firstBatch' field in the 'cursor' field of the first
+        # document returned.
+        #
+        # @example Get the documents.
+        #   result.documents
+        #
+        # @return [ Array<BSON::Document> ] The documents.
+        #
+        # @since 2.0.0
+        def documents
+          reply.documents[0][RESULT] || cursor_document[FIRST_BATCH]
+        end
+
+        private
+
+        def cursor_document
+          @cursor_document ||= reply.documents[0][CURSOR]
+        end
+      end
+    end
+  end
+end