mongo 2.13.0 → 2.15.0.alpha

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

@@ -19,11 +19,13 @@ module Mongo
       # Defines custom behavior of results in a parallel scan.
       #
       # @since 2.0.0
+      # @api semiprivate
       class Result < Operation::Result
 
         # The name of the cursors field in the result.
         #
         # @since 2.0.0
+        # @api private
         CURSORS = 'cursors'.freeze
 
         # Get all the cursor ids from the result.
@@ -34,6 +36,7 @@ module Mongo
         # @return [ Array<Integer> ] The cursor ids.
         #
         # @since 2.0.0
+        # @api private
         def cursor_ids
           documents.map {|doc| doc[CURSOR][CURSOR_ID]}
         end
@@ -46,6 +49,7 @@ module Mongo
         # @return [ Array<BSON::Document> ] The documents.
         #
         # @since 2.0.0
+        # @api public
         def documents
           reply.documents[0][CURSORS]
         end

data/lib/mongo/operation/result.rb

@@ -27,6 +27,7 @@ module Mongo
     # produce a reply (in which case it is assumed to have succeeded).
     #
     # @since 2.0.0
+    # @api semiprivate
     class Result
       extend Forwardable
       include Enumerable
@@ -34,41 +35,49 @@ module Mongo
       # The field name for the cursor document in an aggregation.
       #
       # @since 2.2.0
+      # @api private
       CURSOR = 'cursor'.freeze
 
       # The cursor id field in the cursor document.
       #
       # @since 2.2.0
+      # @api private
       CURSOR_ID = 'id'.freeze
 
       # The field name for the first batch of a cursor.
       #
       # @since 2.2.0
+      # @api private
       FIRST_BATCH = 'firstBatch'.freeze
 
       # The field name for the next batch of a cursor.
       #
       # @since 2.2.0
+      # @api private
       NEXT_BATCH = 'nextBatch'.freeze
 
       # The namespace field in the cursor document.
       #
       # @since 2.2.0
+      # @api private
       NAMESPACE = 'ns'.freeze
 
       # The number of documents updated in the write.
       #
       # @since 2.0.0
+      # @api private
       N = 'n'.freeze
 
       # The ok status field in the result.
       #
       # @since 2.0.0
+      # @api private
       OK = 'ok'.freeze
 
       # The result field constant.
       #
       # @since 2.2.0
+      # @api private
       RESULT = 'result'.freeze
 
       # Initialize a new result.
@@ -106,6 +115,8 @@ module Mongo
       end
 
       # @return [ Array<Protocol::Message> ] replies The wrapped wire protocol replies.
+      #
+      # @api private
       attr_reader :replies
 
       # @return [ Server::Description ] Server description of the server that
@@ -129,6 +140,7 @@ module Mongo
       # @return [ true, false ] If the result is acknowledged.
       #
       # @since 2.0.0
+      # @api public
       def acknowledged?
         !!@replies
       end
@@ -143,6 +155,7 @@ module Mongo
       # @return [ Integer ] The cursor id.
       #
       # @since 2.0.0
+      # @api private
       def cursor_id
         acknowledged? ? replies.last.cursor_id : 0
       end
@@ -153,6 +166,7 @@ module Mongo
       # @return [ Nil ]
       #
       # @since 2.0.0
+      # @api private
       def namespace
         nil
       end
@@ -165,6 +179,7 @@ module Mongo
       # @return [ Array<BSON::Document> ] The documents.
       #
       # @since 2.0.0
+      # @api public
       def documents
         if acknowledged?
           replies.flat_map(&:documents)
@@ -182,9 +197,10 @@ module Mongo
       #
       # @return [ Enumerator ] The enumerator.
       #
-      # @since 2.0.0
-      #
       # @yieldparam [ BSON::Document ] Each document in the result.
+      #
+      # @since 2.0.0
+      # @api public
       def each(&block)
         documents.each(&block)
       end
@@ -197,6 +213,7 @@ module Mongo
       # @return [ String ] The inspection.
       #
       # @since 2.0.0
+      # @api public
       def inspect
         "#<#{self.class.name}:0x#{object_id} documents=#{documents}>"
       end
@@ -209,6 +226,7 @@ module Mongo
       # @return [ Protocol::Message ] The first reply.
       #
       # @since 2.0.0
+      # @api private
       def reply
         if acknowledged?
           replies.first
@@ -225,6 +243,7 @@ module Mongo
       # @return [ Integer ] The number of documents returned.
       #
       # @since 2.0.0
+      # @api public
       def returned_count
         if acknowledged?
           reply.number_returned
@@ -245,6 +264,7 @@ module Mongo
       # @return [ true, false ] If the command was successful.
       #
       # @since 2.0.0
+      # @api public
       def successful?
         return true if !acknowledged?
         if first_document.has_key?(OK)
@@ -262,6 +282,7 @@ module Mongo
       # @return [ true, false ] If the command returned ok.
       #
       # @since 2.1.0
+      # @api public
       def ok?
         # first_document[OK] is a float, and the server can return
         # ok as a BSON int32, BSON int64 or a BSON double.
@@ -285,6 +306,7 @@ module Mongo
       # @return [ Result ] The result if verification passed.
       #
       # @since 2.0.0
+      # @api private
       def validate!
         !successful? ? raise_operation_failure : self
       end
@@ -310,6 +332,8 @@ module Mongo
           labels: parser.labels,
           wtimeout: parser.wtimeout,
           connection_description: connection_description,
+          document: parser.document,
+          server_message: parser.server_message,
         )
       end
 
@@ -317,12 +341,13 @@ module Mongo
       # error information in this result.
       #
       # @raise Error::OperationFailure
-      def raise_operation_failure
+      private def raise_operation_failure
         raise error
       end
-      private :raise_operation_failure
 
       # @return [ TopologyVersion | nil ] The topology version.
+      #
+      # @api private
       def topology_version
         unless defined?(@topology_version)
           @topology_version = first_document['topologyVersion'] &&
@@ -339,6 +364,7 @@ module Mongo
       # @return [ Integer ] The number of documents written.
       #
       # @since 2.0.0
+      # @api public
       def written_count
         if acknowledged?
           first_document[N] || 0
@@ -346,6 +372,8 @@ module Mongo
           0
         end
       end
+
+      # @api public
       alias :n :written_count
 
       # Get the operation time reported in the server response.
@@ -353,9 +381,10 @@ module Mongo
       # @example Get the operation time.
       #   result.operation_time
       #
-      # @return [ Object ] The operation time value.
+      # @return [ Object | nil ] The operation time value.
       #
       # @since 2.5.0
+      # @api public
       def operation_time
         first_document && first_document[OPERATION_TIME]
       end
@@ -365,13 +394,14 @@ module Mongo
       # @example Get the cluster time.
       #   result.cluster_time
       #
-      # @return [ nil | ClusterTime ] The cluster time document.
+      # @return [ ClusterTime | nil ] The cluster time document.
       #
       # Changed in version 2.9.0: This attribute became an instance of
       # ClusterTime, which is a subclass of BSON::Document.
       # Previously it was an instance of BSON::Document.
       #
       # @since 2.5.0
+      # @api public
       def cluster_time
         first_document && ClusterTime[first_document['$clusterTime']]
       end
@@ -384,6 +414,7 @@ module Mongo
       # @return [ Array ] labels The set of labels.
       #
       # @since 2.7.0
+      # @api private
       def labels
         @labels ||= parser.labels
       end

data/lib/mongo/operation/shared/bypass_document_validation.rb

@@ -18,6 +18,7 @@ module Mongo
     # Custom behavior for operations that support the bypassdocumentvalidation option.
     #
     # @since 2.5.2
+    # @api private
     module BypassDocumentValidation
 
       private

data/lib/mongo/operation/shared/causal_consistency_supported.rb

@@ -18,6 +18,7 @@ module Mongo
     # Custom behavior for operations that support causal consistency.
     #
     # @since 2.5.2
+    # @api private
     module CausalConsistencySupported
 
       private

data/lib/mongo/operation/shared/executable.rb

@@ -18,15 +18,16 @@ module Mongo
     # Shared executable behavior of operations.
     #
     # @since 2.5.2
+    # @api private
     module Executable
 
       include ResponseHandling
 
-      def do_execute(connection, client, options = {})
+      def do_execute(connection, context, options = {})
         unpin_maybe(session) do
-          add_error_labels(client, connection, session) do
+          add_error_labels(connection, context) do
             add_server_diagnostics(connection) do
-              get_result(connection, client, options).tap do |result|
+              get_result(connection, context, options).tap do |result|
                 process_result(result, connection)
               end
             end
@@ -34,15 +35,15 @@ module Mongo
         end
       end
 
-      def execute(connection, client:, options: {})
+      def execute(connection, context:, options: {})
         if Lint.enabled?
           unless connection.is_a?(Mongo::Server::Connection)
             raise Error::LintError, "Connection argument is of wrong type: #{connection}"
           end
         end
 
-        do_execute(connection, client, options).tap do |result|
-          validate_result(result, client, connection)
+        do_execute(connection, context, options).tap do |result|
+          validate_result(result, connection, context)
         end
       end
 
@@ -52,20 +53,30 @@ module Mongo
         Result
       end
 
-      def get_result(connection, client, options = {})
-        result_class.new(*dispatch_message(connection, client, options))
+      def get_result(connection, context, options = {})
+        result_class.new(*dispatch_message(connection, context, options))
       end
 
       # Returns a Protocol::Message or nil as reply.
-      def dispatch_message(connection, client, options = {})
-        message = build_message(connection)
-        message = message.maybe_encrypt(connection, client)
-        reply = connection.dispatch([ message ], operation_id, client, options)
+      def dispatch_message(connection, context, options = {})
+        message = build_message(connection, context)
+        message = message.maybe_encrypt(connection, context)
+        reply = connection.dispatch([ message ], context, options)
         [reply, connection.description]
       end
 
-      def build_message(connection)
-        message(connection)
+      # @param [ Mongo::Server::Connection ] connection The connection on which
+      #   the operation is performed.
+      # @param [ Mongo::Operation::Context ] context The operation context.
+      def build_message(connection, context)
+        msg = message(connection)
+        if (server_api = context.server_api) &&
+          # Commands in a transaction do not allow API parameters.
+          !(context.in_transaction? && !context.starting_transaction?)
+        then
+          msg = msg.maybe_add_server_api(server_api)
+        end
+        msg
       end
 
       def process_result(result, connection)

data/lib/mongo/operation/shared/executable_no_validate.rb

@@ -21,8 +21,8 @@ module Mongo
     # @api private
     module ExecutableNoValidate
 
-      def execute(connection, client:)
-        do_execute(connection, client)
+      def execute(connection, context:)
+        do_execute(connection, context)
       end
     end
   end

data/lib/mongo/operation/shared/idable.rb

@@ -18,6 +18,7 @@ module Mongo
     # Shared behavior of operations that require its documents to each have an id.
     #
     # @since 2.5.2
+    # @api private
     module Idable
 
       def documents
@@ -61,4 +62,4 @@ module Mongo
       end
     end
   end
-end
+end

data/lib/mongo/operation/shared/limited.rb

@@ -18,6 +18,7 @@ module Mongo
     # Shared behavior of operations that require its documents to each have an id.
     #
     # @since 2.5.2
+    # @api private
     module Limited
 
       private

data/lib/mongo/operation/shared/object_id_generator.rb

@@ -18,6 +18,7 @@ module Mongo
     # The default generator of ids for documents.
     #
     # @since 2.2.0
+    # @api private
     class ObjectIdGenerator
 
       # Generate a new id.

data/lib/mongo/operation/shared/op_msg_or_command.rb

@@ -20,15 +20,9 @@ module Mongo
     #
     # @api private
     module OpMsgOrCommand
+      include PolymorphicOperation
       include PolymorphicLookup
 
-      def execute(server, client:, options: {})
-        server.with_connection do |connection|
-          operation = final_operation(connection)
-          operation.execute(connection, client: client, options: options)
-        end
-      end
-
       private
 
       def final_operation(connection)

data/lib/mongo/operation/shared/op_msg_or_find_command.rb

@@ -21,15 +21,9 @@ module Mongo
     #
     # @api private
     module OpMsgOrFindCommand
+      include PolymorphicOperation
       include PolymorphicLookup
 
-      def execute(server, client:)
-        server.with_connection do |connection|
-          operation = final_operation(connection)
-          operation.execute(connection, client: client)
-        end
-      end
-
       private
 
       def final_operation(connection)

data/lib/mongo/operation/shared/polymorphic_operation.rb

@@ -0,0 +1,39 @@
+# Copyright (C) 2021 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
+
+    # Shared behavior of implementing an operation differently based on
+    # the server that will be executing the operation.
+    #
+    # @api private
+    module PolymorphicOperation
+
+      # Execute the operation.
+      #
+      # @param [ Mongo::Server ] server The server to send the operation to.
+      # @param [ Operation::Context ] context The operation context.
+      # @param [ Hash ] options Operation execution options.
+      #
+      # @return [ Mongo::Operation::Result ] The operation result.
+      def execute(server, context:, options: {})
+        server.with_connection do |connection|
+          operation = final_operation(connection)
+          operation.execute(connection, context: context, options: options)
+        end
+      end
+    end
+  end
+end