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.



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

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:



54
55
56
 
# File 'lib/mongo/crypt/status.rb', line 54

def self.from_pointer(pointer)
  self.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



90
91
92
 
# File 'lib/mongo/crypt/status.rb', line 90

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



83
84
85
 
# File 'lib/mongo/crypt/status.rb', line 83

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



97
98
99
100
 
# File 'lib/mongo/crypt/status.rb', line 97

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



105
106
107
 
# File 'lib/mongo/crypt/status.rb', line 105

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.



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

def raise_crypt_error(kms: false)
  return if ok?

  if kms || label == :error_kms
    error = Error::KmsError.new(message, code: code)
  else
    error = 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 oject



113
114
115
 
# File 'lib/mongo/crypt/status.rb', line 113

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:



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

def update(label, code, message)
  unless [: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