Class: Mongo::Crypt::Status Private

Inherits:
Object
  • Object
show all
Defined in:
lib/mongo/crypt/status.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

A wrapper around mongocrypt_status_t, representing the status of a mongocrypt_t handle.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(pointer: nil) ⇒ Status

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

When initializing a Status object with a pointer, it is

Create a new Status object

recommended that you use the #self.from_pointer method

Parameters:

  • pointer (FFI::Pointer | nil) (defaults to: nil) —

    A pointer to an existing mongocrypt_status_t object. Defaults to nil.



33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/mongo/crypt/status.rb', line 33

def initialize(pointer: nil)
  # If a pointer is passed in, this class is not responsible for
  # destroying that pointer and deallocating data.
  #
  # FFI::AutoPointer uses a custom release strategy to automatically free
  # the pointer once this object goes out of scope
  @status = pointer || FFI::AutoPointer.new(
    Binding.mongocrypt_status_new,
    Binding.method(:mongocrypt_status_destroy)
  )
end

Class Method Details

.from_pointer(pointer) ⇒ Mongo::Crypt::Status

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initialize a Status object from an existing pointer to a mongocrypt_status_t object.

Parameters:

  • pointer (FFI::Pointer) —

    A pointer to an existing mongocrypt_status_t object

Returns:



52
53
54
 
# File 'lib/mongo/crypt/status.rb', line 52

def self.from_pointer(pointer)
  new(pointer: pointer)
end

Instance Method Details

#code ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return the integer code associated with the status

Returns:

  • (Integer) —

    The status code, defaults to 0



88
89
90
 
# File 'lib/mongo/crypt/status.rb', line 88

def code
  Binding.mongocrypt_status_code(@status)
end

#label ⇒ Symbol

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return the label of the status

Returns:

  • (Symbol) —

    The status label, either :ok, :error_kms, or :error_client, defaults to :ok



81
82
83
 
# File 'lib/mongo/crypt/status.rb', line 81

def label
  Binding.mongocrypt_status_type(@status)
end

#message ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return the status message

Returns:

  • (String) —

    The status message, defaults to empty string



95
96
97
98
 
# File 'lib/mongo/crypt/status.rb', line 95

def message
  message = Binding.mongocrypt_status_message(@status, nil)
  message || ''
end

#ok? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Checks whether the status is labeled :ok

Returns:

  • (Boolean) —

    Whether the status is :ok



103
104
105
 
# File 'lib/mongo/crypt/status.rb', line 103

def ok?
  Binding.mongocrypt_status_ok(@status)
end

#raise_crypt_error(kms: false) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

If kms parameter is false, the error may still have come from a KMS. The kms parameter simply forces all errors to be treated as KMS errors.

Raises a Mongo::Error:CryptError corresponding to the information stored in this status

Does nothing if self.ok? is true

Parameters:

  • kms (true | false) (defaults to: false) —

    Whether the operation was against the KMS.



125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/mongo/crypt/status.rb', line 125

def raise_crypt_error(kms: false)
  return if ok?

  error = if kms || label == :error_kms
            Error::KmsError.new(message, code: code)
          else
            Error::CryptError.new(message, code: code)
          end

  raise error
end

#ref ⇒ FFI::Pointer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the reference to the underlying mongocrypt_status_t object

Returns:

  • (FFI::Pointer) —

    Pointer to the underlying mongocrypt_status_t object



111
112
113
 
# File 'lib/mongo/crypt/status.rb', line 111

def ref
  @status
end

#update(label, code, message) ⇒ Mongo::Crypt::Status

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Set a label, code, and message on the Status

Parameters:

  • label (Symbol) —

    One of :ok, :error_client, or :error_kms

  • code (Integer)
  • message (String)

Returns:



63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/mongo/crypt/status.rb', line 63

def update(label, code, message)
  unless %i[ok error_client error_kms].include?(label)
    raise ArgumentError.new(
      "#{label} is an invalid value for a Mongo::Crypt::Status label. " +
      'Label must have one of the following values: :ok, :error_client, :error_kms'
    )
  end

  message_length = message ? message.bytesize + 1 : 0
  Binding.mongocrypt_status_set(@status, label, code, message, message_length)

  self
end