123456789_123456789_123456789_123456789_123456789_

Module: Mongo::Error::OperationFailure::Family

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In:
::Mongo::Error::OperationFailure, ::Mongo::Error::ServerTimeoutError
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Forwardable
Instance Chain:
self, ::Mongo::Error::ReadWriteRetryable, ::Mongo::Error::SdamErrorDetection
Defined in: lib/mongo/error/operation_failure.rb

Overview

Implements the behavior for an ::Mongo::Error::OperationFailure error. Other errors (e.g. ::Mongo::Error::ServerTimeoutError) may also implement this, so that they may be recognized and treated as ::Mongo::Error::OperationFailure errors.

Since:

  • 2.0.0

Constant Summary

  • CHANGE_STREAM_RESUME_ERRORS = Internal use only

    ::Mongo::Error codes and code names that should result in a failing getMore command on a change stream NOT being resumed.

    Since:

    • 2.0.0

    # File 'lib/mongo/error/operation_failure.rb', line 61 
    [
  {code_name: 'HostUnreachable', code: 6},
  {code_name: 'HostNotFound', code: 7},
  {code_name: 'NetworkTimeout', code: 89},
  {code_name: 'ShutdownInProgress', code: 91},
  {code_name: 'PrimarySteppedDown', code: 189},
  {code_name: 'ExceededTimeLimit', code: 262},
  {code_name: 'SocketException', code: 9001},
  {code_name: 'NotMaster', code: 10107},
  {code_name: 'InterruptedAtShutdown', code: 11600},
  {code_name: 'InterruptedDueToReplStateChange', code: 11602},
  {code_name: 'NotPrimaryNoSecondaryOk', code: 13435},
  {code_name: 'NotMasterOrSecondary', code: 13436},

  {code_name: 'StaleShardVersion', code: 63},
  {code_name: 'FailedToSatisfyReadPreference', code: 133},
  {code_name: 'StaleEpoch', code: 150},
  {code_name: 'RetryChangeStream', code: 234},
  {code_name: 'StaleConfig', code: 13388},
].freeze
  • CHANGE_STREAM_RESUME_MESSAGES = Internal use only

    Change stream can be resumed when these error messages are encountered.

    Since:

    • 2.6.0

    # File 'lib/mongo/error/operation_failure.rb', line 86 
    ReadWriteRetryable::WRITE_RETRY_MESSAGES

::Mongo::Error::SdamErrorDetection - Included

NODE_RECOVERING_CODES, NODE_SHUTTING_DOWN_CODES, NOT_MASTER_CODES

::Mongo::Error::ReadWriteRetryable - Included

RETRY_MESSAGES, WRITE_RETRY_ERRORS, WRITE_RETRY_MESSAGES

Instance Attribute Summary

::Mongo::Error::ReadWriteRetryable - Included

#retryable?

Whether the error is a retryable error according to the legacy read retry logic.
#write_retryable?

Whether the error is a retryable error according to the modern retryable reads and retryable writes specifications.
#write_retryable_code?

::Mongo::Error::SdamErrorDetection - Included

#node_recovering?

Whether the error is a “node is recovering” error, or one of its variants.
#node_shutting_down?

Whether the error is a “node is shutting down” type error.
#not_master?

Whether the error is a “not master” error, or one of its variants.

Instance Method Summary

Instance Attribute Details

#change_stream_resumable? ⇒ true, false (readonly)

Can the change stream on which this error occurred be resumed, provided the operation that triggered this error was a getMore?

Examples:

Is the error resumable for the change stream?

error.change_stream_resumable?

Returns:

  • (true, false) —

    Whether the error is resumable.

Since:

  • 2.6.0

[ GitHub ] 

  


# File 'lib/mongo/error/operation_failure.rb', line 97



def change_stream_resumable?
  if @result && @result.is_a?(Mongo::Operation::GetMore::Result)
    # CursorNotFound exceptions are always resumable because the server
    # is not aware of the cursor id, and thus cannot determine if
    # the cursor is a change stream and cannot add the
    # ResumableChangeStreamError label.
    return true if code == 43

    # Connection description is not populated for unacknowledged writes.
    if connection_description.max_wire_version >= 9
      label?('ResumableChangeStreamError')
    else
      change_stream_resumable_code?
    end
  else
    false
  end
end


  








  

    #change_stream_resumable_code?  ⇒ Boolean  (readonly, private)
  



  

    
  





  
Since:


    
  
  • 
    
    

    2.0.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 116



def change_stream_resumable_code?
  CHANGE_STREAM_RESUME_ERRORS.any? { |e| e[:code] == code }
end


  








  

    #code  ⇒ Integer  (readonly)
  



  

    
  





  
Returns:


    
  
  • 
    (Integer)
—    
    

    The error code parsed from the document.
    

    
  
    • 



Since:


    
  
  • 
    
    

    2.6.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 44



attr_reader :code


  








  

    #code_name  ⇒ String  (readonly)
  



  

    
  





  
Returns:


    
  
  • 
    (String)
—    
    

    The error code name parsed from the document.
    

    
  
    • 



Since:


    
  
  • 
    
    

    2.6.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 49



attr_reader :code_name


  








  

    #details  ⇒ String | nil  (readonly)
  



  

    
  





  
Returns:


    
  
  • 
    (String | nil)
—    
    

    The details of the error. For WriteConcernErrors this is [‘errInfo’]. For WriteErrors this is 'writeErrors'. For all other errors this is nil.
    

    
  
    • 



Since:


    
  
  • 
    
    

    2.0.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 152



attr_reader :details


  








  

    #document  ⇒ BSON::Document | nil  (readonly)
  



  

    
  





  
Returns:


    
  
  • 
    (BSON::Document | nil)
—    
    

    The server-returned error document.
    

    
  
    • 



Since:


    
  
  • 
    
    

    2.0.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 157



attr_reader :document


  








  

    #max_time_ms_expired?  ⇒ true | false  (readonly)
  



  

    

Whether the error is MaxTimeMSExpired.


  





  
Returns:


    
  
  • 
    (true | false)
—    
    

    Whether the error is MaxTimeMSExpired.
    

    
  
    • 



Since:


    
  
  • 
    
    

    2.10.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 218



def max_time_ms_expired?
  code == 50 # MaxTimeMSExpired
end


  








  

    #result  ⇒ Operation::Result  (readonly)
  

  

    This method is for internal use only.
  



  

    
  





  
Returns:



Since:


    
  
  • 
    
    

    2.0.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 162



attr_reader :result


  








  

    #server_message  ⇒ String  (readonly)
  



  

    
  





  
Returns:


    
  
  • 
    (String)
—    
    

    The server-returned error message parsed from the response.
    

    
  
    • 



Since:


    
  
  • 
    
    

    2.0.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 55



attr_reader :server_message


  








  

    #unsupported_retryable_write?  ⇒ true | false  (readonly)
  



  

    

Whether the error is caused by an attempted retryable write on a storage engine that does not support retryable writes.



retryable write on a storage engine that does not support retryable writes.


  





  
Returns:


    
  
  • 
    (true | false)
—    
    

    Whether the error is caused by an attempted
    

    
  
    • 



Since:


    
  
  • 
    
    

    2.10.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 229



def unsupported_retryable_write?
  # code 20 is IllegalOperation.
  # Note that the document is expected to be a BSON::Document, thus
  # either having string keys or providing indifferent access.
  code == 20 && server_message&.start_with?("Transaction numbers") || false
end


  








  

    #write_concern_error?  ⇒ true | false  (readonly)
  



  

    
  





  
Returns:


    
  
  • 
    (true | false)
—    
    

    Whether the failure includes a write concern error. A failure may have a top level error and a write concern error or either one of the two.
    

    
  
    • 



Since:


    
  
  • 
    
    

    2.10.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 126



def write_concern_error?
  !!@write_concern_error_document
end


  








  

    #write_concern_error_code  ⇒ Integer | nil  (readonly)
  



  

    
  





  
Returns:


    
  
  • 
    (Integer | nil)
—    
    

    The error code for the write concern error, if a write concern error is present and has a code.
    

    
  
    • 



Since:


    
  
  • 
    
    

    2.10.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 140



attr_reader :write_concern_error_code


  








  

    #write_concern_error_code_name  ⇒ String | nil  (readonly)
  



  

    
  





  
Returns:


    
  
  • 
    (String | nil)
—    
    

    The code name for the write concern error, if a write concern error is present and has a code name.
    

    
  
    • 



Since:


    
  
  • 
    
    

    2.10.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 146



attr_reader :write_concern_error_code_name


  








  

    #write_concern_error_document  ⇒ Hash | nil  (readonly)
  



  

    

Returns the write concern error document as it was reported by the server, if any.


  





  
Returns:


    
  
  • 
    (Hash | nil)
—    
    

    Write concern error as reported to the server.
    

    
  
    • 



Since:


    
  
  • 
    
    

    2.0.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 134



attr_reader :write_concern_error_document


  








  

    #wtimeout?  ⇒ true | false  (readonly)
  



  

    

Whether the error is a write concern timeout.


  





  
Returns:


    
  
  • 
    (true | false)
—    
    

    Whether the error is a write concern timeout.
    

    
  
    • 



Since:


    
  
  • 
    
    

    2.7.1
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 209



def wtimeout?
  @wtimeout
end


  







Instance Method Details



  

    #append_details(message, details)  ⇒ String  (private)
  



  

    

Append the details to the message


  





  
Returns:


    
  
  • 
    (String)
—    
    

    the message with the details appended to it
    

    
  
    • 



Since:


    
  
  • 
    
    

    2.0.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 253



def append_details(message, details)
  return message unless details && message
  message + " -- #{details.to_json}"
end


  








  

    #connection_description  ⇒ Server::Description 
  



  

    
  





  
Returns:





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 39



def_delegator :@result, :connection_description


  








  

    #initialize(message = nil, result = nil, options = {})  
  



  

    

Create the operation failure.


  





  
Parameters:


    
  
  • 
    message
    (String)
    (defaults to: nil)
—    
    

    The error message.
    

    
  
    • 
  
  • 
    result
    (Operation::Result)
    (defaults to: nil)
—    
    

    The result object.
    

    
  
    • 
  
  • 
    options
    (Hash)
    (defaults to: {})
—    
    

    Additional parameters.
    

    
  
    • 


    
Options Hash (options):

    
    
        
  • 
          :code
          (Integer)
            — 
    

    ::Mongo::Error code.
    

            
    • 
        
  • 
          :code_name
          (String)
            — 
    

    ::Mongo::Error code name.
    

            
    • 
        
  • 
          :document
          (BSON::Document)
            — 
    

    The server-returned error document.
    

            
    • 
        
  • 
          server_message
          (String)
            — 
    

    The server-returned error message parsed from the response.
    

            
    • 
        
  • 
          :write_concern_error_document
          (Hash)
            — 
    

    The server-supplied write concern error document, if any.
    

            
    • 
        
  • 
          :write_concern_error_code
          (Integer)
            — 
    

    ::Mongo::Error code for write concern error, if any.
    

            
    • 
        
  • 
          :write_concern_error_code_name
          (String)
            — 
    

    ::Mongo::Error code name for write concern error, if any.
    

            
    • 
        
  • 
          :write_concern_error_labels
          (Array<String>)
            — 
    

    ::Mongo::Error labels for the write concern error, if any.
    

            
    • 
        
  • 
          :labels
          (Array<String>)
            — 
    

    The set of labels associated with the error.
    

            
    • 
        
  • 
          :wtimeout
          (true | false)
            — 
    

    Whether the error is a wtimeout.
    

            
    • 
    


Since:


    
  
  • 
    
    

    2.0.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 187



def initialize(message = nil, result = nil, options = {})
  @details = retrieve_details(options[:document])
  super(append_details(message, @details))

  @result = result
  @code = options[:code]
  @code_name = options[:code_name]
  @write_concern_error_document = options[:write_concern_error_document]
  @write_concern_error_code = options[:write_concern_error_code]
  @write_concern_error_code_name = options[:write_concern_error_code_name]
  @write_concern_error_labels = options[:write_concern_error_labels] || []
  @labels = options[:labels] || []
  @wtimeout = !!options[:wtimeout]
  @document = options[:document]
  @server_message = options[:server_message]
end


  








  

    #retrieve_details(document)  ⇒ Hash | nil  (private)
  



  

    

Retrieve the details from a document


  





  
Returns:


    
  
  • 
    (Hash | nil)
—    
    

    the details extracted from the document
    

    
  
    • 



Since:


    
  
  • 
    
    

    2.0.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/error/operation_failure.rb', line 241



def retrieve_details(document)
  return nil unless document
  if wce = document['writeConcernError']
    return wce['errInfo']
  elsif we = document['writeErrors']&.first
    return we['errInfo']
  end
end