Class: Mongo::Protocol::Message Abstract

Inherits:
Object
  • Object
show all
Includes:
Id, Serializers
Defined in:
lib/mongo/protocol/message.rb

Overview

This class is abstract.

A base class providing functionality required by all messages in the MongoDB wire protocol. It provides a minimal DSL for defining typed fields to enable serialization and deserialization over the wire.

Examples:

class WireProtocolMessage < Message

  private

  def op_code
    1234
  end

  FLAGS = [:first_bit, :bit_two]

  # payload
  field :flags, BitVector.new(FLAGS)
  field :namespace, CString
  field :document, Document
  field :documents, Document, true
end

Direct Known Subclasses

Compressed, GetMore, KillCursors, Msg, Query, Reply

Constant Summary collapse

BATCH_SIZE =

The batch size constant.

Since:

  • 2.2.0

'batchSize'.freeze
COLLECTION =

The collection constant.

Since:

  • 2.2.0

'collection'.freeze
LIMIT =

The limit constant.

Since:

  • 2.2.0

'limit'.freeze
ORDERED =

The ordered constant.

Since:

  • 2.2.0

'ordered'.freeze
Q =

The q constant.

Since:

  • 2.2.0

'q'.freeze
MAX_MESSAGE_SIZE =

Default max message size of 48MB.

Since:

  • 2.2.1

50331648.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Id

included

Constructor Details

#initialize(*args) ⇒ Message

:nodoc:



79
80
81
 
# File 'lib/mongo/protocol/message.rb', line 79

def initialize(*args) # :nodoc:
  set_request_id
end

Instance Attribute Details

#request_id ⇒ Fixnum (readonly)

Returns the request id for the message

Returns:

  • (Fixnum) —

    The request id for this message



86
87
88
 
# File 'lib/mongo/protocol/message.rb', line 86

def request_id
  @request_id
end

Class Method Details

.deserialize(io, max_message_size = MAX_MESSAGE_SIZE, expected_response_to = nil, options = {}) ⇒ Message

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.

Deserializes messages from an IO stream.

This method returns decompressed messages (i.e. if the message on the wire was OP_COMPRESSED, this method would typically return the OP_MSG message that is the result of decompression).

Parameters:

  • max_message_size (Integer) (defaults to: MAX_MESSAGE_SIZE) —

    The max message size.

  • io (IO) —

    Stream containing a message

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

Options Hash (options):

  • :deserialize_as_bson (Boolean) —

    Whether to deserialize this message using BSON types instead of native Ruby types wherever possible.

  • :socket_timeout (Numeric) —

    The timeout to use for each read operation.

Returns:

  • (Message) —

    Instance of a Message class



238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/mongo/protocol/message.rb', line 238

def self.deserialize(io,
  max_message_size = MAX_MESSAGE_SIZE,
  expected_response_to = nil,
  options = {}
)
  # io is usually a Mongo::Socket instance, which supports the
  # timeout option. For compatibility with whoever might call this
  # method with some other IO-like object, pass options only when they
  # are not empty.
  read_options = options.slice(:timeout, :socket_timeout)

  if read_options.empty?
    chunk = io.read(16)
  else
    chunk = io.read(16, **read_options)
  end
  buf = BSON::ByteBuffer.new(chunk)
  length, _request_id, response_to, _op_code = deserialize_header(buf)

  # Protection from potential DOS man-in-the-middle attacks. See
  # DRIVERS-276.
  if length > (max_message_size || MAX_MESSAGE_SIZE)
    raise Error::MaxMessageSize.new(max_message_size)
  end

  # Protection against returning the response to a previous request. See
  # RUBY-1117
  if expected_response_to && response_to != expected_response_to
    raise Error::UnexpectedResponse.new(expected_response_to, response_to)
  end

  if read_options.empty?
    chunk = io.read(length - 16)
  else
    chunk = io.read(length - 16, **read_options)
  end
  buf = BSON::ByteBuffer.new(chunk)

  message = Registry.get(_op_code).allocate
  message.send(:fields).each do |field|
    if field[:multi]
      deserialize_array(message, buf, field, options)
    else
      deserialize_field(message, buf, field, options)
    end
  end
  if message.is_a?(Msg)
    message.fix_after_deserialization
  end
  message.maybe_inflate
end

.deserialize_array(message, io, field, options = {}) ⇒ Message

Deserializes an array of fields in a message

The number of items in the array must be described by a previously deserialized field specified in the class by the field dsl under the key :multi

Parameters:

  • message (Message) —

    Message to contain the deserialized array.

  • io (IO) —

    Stream containing the array to deserialize.

  • field (Hash) —

    Hash representing a field.

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

Options Hash (options):

  • :deserialize_as_bson (Boolean) —

    Whether to deserialize each of the elements in this array using BSON types wherever possible.

Returns:

  • (Message) —

    Message with deserialized array.



432
433
434
435
436
437
 
# File 'lib/mongo/protocol/message.rb', line 432

def self.deserialize_array(message, io, field, options = {})
  elements = []
  count = message.instance_variable_get(field[:multi])
  count.times { elements << field[:type].deserialize(io, options) }
  message.instance_variable_set(field[:name], elements)
end

.deserialize_field(message, io, field, options = {}) ⇒ Message

Deserializes a single field in a message

Parameters:

  • message (Message) —

    Message to contain the deserialized field.

  • io (IO) —

    Stream containing the field to deserialize.

  • field (Hash) —

    Hash representing a field.

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

Options Hash (options):

  • :deserialize_as_bson (Boolean) —

    Whether to deserialize this field using BSON types wherever possible.

Returns:

  • (Message) —

    Message with deserialized field.



450
451
452
453
454
455
 
# File 'lib/mongo/protocol/message.rb', line 450

def self.deserialize_field(message, io, field, options = {})
  message.instance_variable_set(
    field[:name],
    field[:type].deserialize(io, options)
  )
end

.deserialize_header(io) ⇒ Array<Fixnum>

Deserializes the header of the message

Parameters:

  • io (IO) —

    Stream containing the header.

Returns:

  • (Array<Fixnum>) —

    Deserialized header.



388
389
390
 
# File 'lib/mongo/protocol/message.rb', line 388

def self.deserialize_header(io)
  Header.deserialize(io)
end

.field(name, type, multi = false) ⇒ NilClass

A method for declaring a message field

Parameters:

  • name (String) —

    Name of the field

  • type (Module) —

    Type specific serialization strategies

  • multi (true, false, Symbol) (defaults to: false) —

    Specify as true to serialize the field’s value as an array of type :type or as a symbol describing the field having the number of items in the array (used upon deserialization)

    Note: In fields where multi is a symbol representing the field
containing number items in the repetition, the field containing
that information *must* be deserialized prior to deserializing
fields that use the number.

Returns:

  • (NilClass) 


407
408
409
410
411
412
413
414
415
 
# File 'lib/mongo/protocol/message.rb', line 407

def self.field(name, type, multi = false)
  fields << {
    :name => "@#{name}".intern,
    :type => type,
    :multi => multi
  }

  attr_reader name
end

.fields ⇒ Integer

A class method for getting the fields for a message class

Returns:

  • (Integer) —

    the fields for the message class



340
341
342
 
# File 'lib/mongo/protocol/message.rb', line 340

def self.fields
  @fields ||= []
end

Instance Method Details

#==(other) ⇒ true, false Also known as: eql?

Tests for equality between two wire protocol messages by comparing class and field values.

Parameters:

Returns:

  • (true, false) —

    The equality of the messages.



295
296
297
298
299
300
301
302
 
# File 'lib/mongo/protocol/message.rb', line 295

def ==(other)
  return false if self.class != other.class
  fields.all? do |field|
    name = field[:name]
    instance_variable_get(name) ==
      other.instance_variable_get(name)
  end
end

#hash ⇒ Fixnum

Creates a hash from the values of the fields of a message.

Returns:

  • (Fixnum) —

    The hash code for the message.



308
309
310
 
# File 'lib/mongo/protocol/message.rb', line 308

def hash
  fields.map { |field| instance_variable_get(field[:name]) }.hash
end

#maybe_add_server_api(server_api) ⇒ Object

Raises:



173
174
175
 
# File 'lib/mongo/protocol/message.rb', line 173

def maybe_add_server_api(server_api)
  raise Error::ServerApiNotSupported, "Server API parameters cannot be sent to pre-3.6 MongoDB servers. Please remove the :server_api parameter from Client options or use MongoDB 3.6 or newer"
end

#maybe_compress(compressor, zlib_compression_level = nil) ⇒ self

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.

Compress the message, if supported by the wire protocol used and if the command being sent permits compression. Otherwise returns self.

Parameters:

  • compressor (String, Symbol) —

    The compressor to use.

  • zlib_compression_level (Integer) (defaults to: nil) —

    The zlib compression level to use.

Returns:

  • (self) —

    Always returns self. Other message types should override this method.

Since:

  • 2.5.0



112
113
114
 
# File 'lib/mongo/protocol/message.rb', line 112

def maybe_compress(compressor, zlib_compression_level = nil)
  self
end

#maybe_decrypt(context) ⇒ Mongo::Protocol::Msg

Possibly decrypt this message with libmongocrypt.

Parameters:

Returns:

  • (Mongo::Protocol::Msg) —

    The decrypted message, or the original message if decryption was not possible or necessary.



152
153
154
155
156
157
158
 
# File 'lib/mongo/protocol/message.rb', line 152

def maybe_decrypt(context)
  # TODO determine if we should be decrypting data coming from pre-4.2
  # servers, potentially using legacy wire protocols. If so we need
  # to implement decryption for those wire protocols as our current
  # encryption/decryption code is OP_MSG-specific.
  self
end

#maybe_encrypt(connection, context) ⇒ Mongo::Protocol::Msg

Possibly encrypt this message with libmongocrypt.

Parameters:

Returns:

  • (Mongo::Protocol::Msg) —

    The encrypted message, or the original message if encryption was not possible or necessary.



168
169
170
171
 
# File 'lib/mongo/protocol/message.rb', line 168

def maybe_encrypt(connection, context)
  # Do nothing if the Message subclass has not implemented this method
  self
end

#maybe_inflate ⇒ Protocol::Message

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.

Inflate a message if it is compressed.

Returns:

  • (Protocol::Message) —

    Always returns self. Subclasses should override this method as necessary.

Since:

  • 2.5.0



142
143
144
 
# File 'lib/mongo/protocol/message.rb', line 142

def maybe_inflate
  self
end

#number_returned ⇒ 0

Default number returned value for protocol messages.

Returns:

  • (0) —

    This method must be overridden, otherwise, always returns 0.

Since:

  • 2.5.0



326
 
# File 'lib/mongo/protocol/message.rb', line 326

def number_returned; 0; end

#replyable? ⇒ false

The default for messages is not to require a reply after sending a message to the server.

Examples:

Does the message require a reply?

message.replyable?

Returns:

  • (false) —

    The default is to not require a reply.

Since:

  • 2.0.0



97
98
99
 
# File 'lib/mongo/protocol/message.rb', line 97

def replyable?
  false
end

#serialize(buffer = BSON::ByteBuffer.new, max_bson_size = nil, bson_overhead = nil) ⇒ String Also known as: to_s

Serializes message into bytes that can be sent on the wire

Parameters:

  • buffer (String) (defaults to: BSON::ByteBuffer.new) —

    buffer where the message should be inserted

Returns:

  • (String) —

    buffer containing the serialized message



201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/mongo/protocol/message.rb', line 201

def serialize(buffer = BSON::ByteBuffer.new, max_bson_size = nil, bson_overhead = nil)
  max_size =
    if max_bson_size && bson_overhead
      max_bson_size + bson_overhead
    elsif max_bson_size
      max_bson_size
    else
      nil
    end

  start = buffer.length
  serialize_header(buffer)
  serialize_fields(buffer, max_size)
  buffer.replace_int32(start, buffer.length - start)
end

#set_request_id ⇒ Fixnum

Generates a request id for a message

Returns:

  • (Fixnum) —

    a request id used for sending a message to the server. The server will put this id in the response_to field of a reply.



317
318
319
 
# File 'lib/mongo/protocol/message.rb', line 317

def set_request_id
  @request_id = self.class.next_id
end