Class: Mongo::Server::Description

Inherits:
Object
  • Object
show all
Defined in:
lib/mongo/server/description.rb,
lib/mongo/server/description/features.rb

Overview

Represents a description of the server, populated by the result of the ismaster command.

Note: Unknown servers do not have wire versions, but for legacy reasons we return 0 for min_wire_version and max_wire_version of any server that does not have them. Presently the driver sometimes constructs commands when the server is unknown, so references to min_wire_version and max_wire_version should not be nil. When driver behavior is changed (jira.mongodb.org/browse/RUBY-1805), this may no longer be necessary.

Since:

  • 2.0.0

Defined Under Namespace

Classes: Features

Constant Summary collapse

ARBITER =
Deprecated.

Constant for reading arbiter info from config.

Since:

  • 2.0.0

'arbiterOnly'.freeze
ARBITERS =

Constant for reading arbiters info from config.

Since:

  • 2.0.0

'arbiters'.freeze
HIDDEN =

Constant for reading hidden info from config.

Since:

  • 2.0.0

'hidden'.freeze
HOSTS =

Constant for reading hosts info from config.

Since:

  • 2.0.0

'hosts'.freeze
MESSAGE =
Deprecated.

Constant for the key for the message value.

Since:

  • 2.0.0

'msg'.freeze
MONGOS_MESSAGE =
Deprecated.

Constant for the message that indicates a sharded cluster.

Since:

  • 2.0.0

'isdbgrid'.freeze
REPLICA_SET =
Deprecated.

Constant for determining ghost servers.

Since:

  • 2.0.0

'isreplicaset'.freeze
MAX_BSON_OBJECT_SIZE =

Constant for reading max bson size info from config.

Since:

  • 2.0.0

'maxBsonObjectSize'.freeze
MAX_MESSAGE_BYTES =

Constant for reading max message size info from config.

Since:

  • 2.0.0

'maxMessageSizeBytes'.freeze
MAX_WIRE_VERSION =

Constant for the max wire version.

Since:

  • 2.0.0

'maxWireVersion'.freeze
MIN_WIRE_VERSION =

Constant for min wire version.

Since:

  • 2.0.0

'minWireVersion'.freeze
MAX_WRITE_BATCH_SIZE =

Constant for reading max write batch size.

Since:

  • 2.0.0

'maxWriteBatchSize'.freeze
LAST_WRITE =

Constant for the lastWrite subdocument.

Since:

  • 2.4.0

'lastWrite'.freeze
LAST_WRITE_DATE =

Constant for the lastWriteDate field in the lastWrite subdocument.

Since:

  • 2.4.0

'lastWriteDate'.freeze
ME =

Constant for reading the me field.

Since:

  • 2.1.0

'me'.freeze
DEFAULT_MAX_WRITE_BATCH_SIZE =

Default max write batch size.

Since:

  • 2.0.0

1000.freeze
LEGACY_WIRE_VERSION =
Deprecated.

Will be removed in 3.0.

The legacy wire protocol version.

Since:

  • 2.0.0

0.freeze
PASSIVE =

Constant for reading passive info from config.

Since:

  • 2.0.0

'passive'.freeze
PASSIVES =

Constant for reading the passive server list.

Since:

  • 2.0.0

'passives'.freeze
PRIMARY =
Deprecated.

Constant for reading primary info from config.

Since:

  • 2.0.0

'ismaster'.freeze
PRIMARY_HOST =

Constant for reading primary host field from config.

Since:

  • 2.5.0

'primary'.freeze
SECONDARY =
Deprecated.

Constant for reading secondary info from config.

Since:

  • 2.0.0

'secondary'.freeze
SET_NAME =

Constant for reading replica set name info from config.

Since:

  • 2.0.0

'setName'.freeze
TAGS =

Constant for reading tags info from config.

Since:

  • 2.0.0

'tags'.freeze
ELECTION_ID =

Constant for reading electionId info from config.

Since:

  • 2.1.0

'electionId'.freeze
SET_VERSION =

Constant for reading setVersion info from config.

Since:

  • 2.2.2

'setVersion'.freeze
LOCAL_TIME =

Constant for reading localTime info from config.

Since:

  • 2.1.0

'localTime'.freeze
OPERATION_TIME =

Constant for reading operationTime info from config.

Since:

  • 2.5.0

'operationTime'.freeze
LOGICAL_SESSION_TIMEOUT_MINUTES =

Constant for reading logicalSessionTimeoutMinutes info from config.

Since:

  • 2.5.0

'logicalSessionTimeoutMinutes'.freeze
EXCLUDE_FOR_COMPARISON =

Fields to exclude when comparing two descriptions.

Since:

  • 2.0.6

[ LOCAL_TIME,
LAST_WRITE,
OPERATION_TIME,
Operation::CLUSTER_TIME ].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(address, config = {}, average_round_trip_time = nil) ⇒ Description

Instantiate the new server description from the result of the ismaster command.

Examples:

Instantiate the new description.

Description.new(address, { 'ismaster' => true }, 0.5)

Parameters:

  • address (Address) —

    The server address.

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

    The result of the ismaster command.

  • average_round_trip_time (Float) (defaults to: nil) —

    The moving average time (sec) the ismaster call took to complete.

Since:

  • 2.0.0



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/mongo/server/description.rb', line 205

def initialize(address, config = {}, average_round_trip_time = nil)
  @address = address
  @config = config
  @features = Features.new(wire_versions, me || @address.to_s)
  @average_round_trip_time = average_round_trip_time
  @last_update_time = Time.now.dup.freeze

  if Mongo::Lint.enabled?
    # prepopulate cache instance variables
    hosts
    arbiters
    passives

    freeze
  end
end

Instance Attribute Details

#address ⇒ Address (readonly)

Returns address The server’s address.

Returns:

  • (Address) —

    address The server’s address.

Since:

  • 2.0.0



223
224
225
 
# File 'lib/mongo/server/description.rb', line 223

def address
  @address
end

#average_round_trip_time ⇒ Float (readonly)

Returns The moving average time the ismaster call took to complete.

Returns:

  • (Float) —

    The moving average time the ismaster call took to complete.

Since:

  • 2.0.0



234
235
236
 
# File 'lib/mongo/server/description.rb', line 234

def average_round_trip_time
  @average_round_trip_time
end

#config ⇒ Hash (readonly)

Returns The actual result from the ismaster command.

Returns:

  • (Hash) —

    The actual result from the ismaster command.

Since:

  • 2.0.0



226
227
228
 
# File 'lib/mongo/server/description.rb', line 226

def config
  @config
end

#last_update_time ⇒ Time (readonly)

Note:

This time does not indicate when a successful server check

Time when this server description was created.

completed, because marking a server unknown updates its description and last_update_time. Use Server#last_scan to find out when the server was last successfully checked by its Monitor.

Returns:

  • (Time) —

    Server description creation time.

Since:

  • 2.7.0



714
715
716
 
# File 'lib/mongo/server/description.rb', line 714

def last_update_time
  @last_update_time
end

Instance Method Details

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

Check equality of two descriptions.

Examples:

Check description equality.

description == other

Parameters:

  • other (Object) —

    The other description.

Returns:

  • (true, false) —

    Whether the objects are equal.

Since:

  • 2.0.6



726
727
728
729
730
731
732
733
 
# File 'lib/mongo/server/description.rb', line 726

def ==(other)
  return false if self.class != other.class
  return false if unknown? || other.unknown?

  (config.keys + other.config.keys).uniq.all? do |k|
    config[k] == other.config[k] || EXCLUDE_FOR_COMPARISON.include?(k)
  end
end

#arbiter? ⇒ true, false

Returns whether this server is an arbiter, per the SDAM spec.

Examples:

Is the server an arbiter?

description.arbiter?

Returns:

  • (true, false) —

    If the server is an arbiter.

Since:

  • 2.0.0



244
245
246
247
248
 
# File 'lib/mongo/server/description.rb', line 244

def arbiter?
  ok? &&
  config['arbiterOnly'] == true &&
  !!config['setName']
end

#arbiters ⇒ Array<String>

Get a list of all arbiters in the replica set.

Examples:

Get the arbiters in the replica set.

description.arbiters

Returns:

  • (Array<String>) —

    The arbiters in the set.

Since:

  • 2.0.0



258
259
260
 
# File 'lib/mongo/server/description.rb', line 258

def arbiters
  @arbiters ||= (config[ARBITERS] || []).map { |s| s.downcase }
end

#data_bearing? ⇒ true, false

Whether this description is from a data-bearing server (standalone, mongos, primary or secondary).

Returns:

  • (true, false) —

    Whether the description is from a data-bearing server.

Since:

  • 2.7.0



677
678
679
 
# File 'lib/mongo/server/description.rb', line 677

def data_bearing?
  mongos? || primary? || secondary? || standalone?
end

#election_id ⇒ BSON::ObjectId

Get the electionId from the config.

Examples:

Get the electionId.

description.election_id

Returns:

  • (BSON::ObjectId) —

    The election id.

Since:

  • 2.1.0



406
407
408
 
# File 'lib/mongo/server/description.rb', line 406

def election_id
  config[ELECTION_ID]
end

#features ⇒ Features

Returns features The features for the server.

Returns:

  • (Features) —

    features The features for the server.

Since:

  • 2.0.0



229
230
231
 
# File 'lib/mongo/server/description.rb', line 229

def features
  @features
end

#ghost? ⇒ true, false

Whether this server is a ghost, per the SDAM spec.

Examples:

Is the server a ghost?

description.ghost?

Returns:

  • (true, false) —

    If the server is a ghost.

Since:

  • 2.0.0



270
271
272
273
 
# File 'lib/mongo/server/description.rb', line 270

def ghost?
  ok? &&
  config['isreplicaset'] == true
end

#hidden? ⇒ true, false

Will return true if the server is hidden.

Examples:

Is the server hidden?

description.hidden?

Returns:

  • (true, false) —

    If the server is hidden.

Since:

  • 2.0.0



283
284
285
 
# File 'lib/mongo/server/description.rb', line 283

def hidden?
  ok? && !!config[HIDDEN]
end

#hosts ⇒ Array<String>

Get a list of all servers in the replica set.

Examples:

Get the servers in the replica set.

description.hosts

Returns:

  • (Array<String>) —

    The servers in the set.

Since:

  • 2.0.0



295
296
297
 
# File 'lib/mongo/server/description.rb', line 295

def hosts
  @hosts ||= (config[HOSTS] || []).map { |s| s.downcase }
end

#inspect ⇒ String

Inspect the server description.

Examples:

Inspect the server description

description.inspect

Returns:

  • (String) —

    The inspection.

Since:

  • 2.0.0



307
308
309
 
# File 'lib/mongo/server/description.rb', line 307

def inspect
  "#<Mongo::Server:Description:0x#{object_id} config=#{config} average_round_trip_time=#{average_round_trip_time}>"
end

#is_server?(server) ⇒ true, false

Deprecated.

Is this description from the given server.

Examples:

Check if the description is from a given server.

description.is_server?(server)

Returns:

  • (true, false) —

    If the description is from the server.

Since:

  • 2.0.6



639
640
641
 
# File 'lib/mongo/server/description.rb', line 639

def is_server?(server)
  address == server.address
end

#last_write_date ⇒ Time

Get the lastWriteDate from the lastWrite subdocument in the config.

Examples:

Get the lastWriteDate value.

description.last_write_date

Returns:

  • (Time) —

    The last write date.

Since:

  • 2.4.0



430
431
432
 
# File 'lib/mongo/server/description.rb', line 430

def last_write_date
  config[LAST_WRITE][LAST_WRITE_DATE] if config[LAST_WRITE]
end

#lists_server?(server) ⇒ true, false

Deprecated.

Is a server included in this description’s list of servers.

Examples:

Check if a server is in the description list of servers.

description.lists_server?(server)

Returns:

  • (true, false) —

    If a server is in the description’s list of servers.

Since:

  • 2.0.6



653
654
655
 
# File 'lib/mongo/server/description.rb', line 653

def lists_server?(server)
  servers.include?(server.address.to_s)
end

#logical_session_timeout ⇒ Integer?

Get the logicalSessionTimeoutMinutes from the config.

Examples:

Get the logicalSessionTimeoutMinutes value in minutes.

description.logical_session_timeout

Returns:

  • (Integer, nil) —

    The logical session timeout in minutes.

Since:

  • 2.5.0



442
443
444
 
# File 'lib/mongo/server/description.rb', line 442

def logical_session_timeout
  config[LOGICAL_SESSION_TIMEOUT_MINUTES] if config[LOGICAL_SESSION_TIMEOUT_MINUTES]
end

#max_bson_object_size ⇒ Integer

Get the max BSON object size for this server version.

Examples:

Get the max BSON object size.

description.max_bson_object_size

Returns:

  • (Integer) —

    The maximum object size in bytes.

Since:

  • 2.0.0



319
320
321
 
# File 'lib/mongo/server/description.rb', line 319

def max_bson_object_size
  config[MAX_BSON_OBJECT_SIZE]
end

#max_message_size ⇒ Integer

Get the max message size for this server version.

Examples:

Get the max message size.

description.max_message_size

Returns:

  • (Integer) —

    The maximum message size in bytes.

Since:

  • 2.0.0



331
332
333
 
# File 'lib/mongo/server/description.rb', line 331

def max_message_size
  config[MAX_MESSAGE_BYTES]
end

#max_wire_version ⇒ Integer

Get the maximum wire version. Defaults to zero.

Examples:

Get the max wire version.

description.max_wire_version

Returns:

  • (Integer) —

    The max wire version supported.

Since:

  • 2.0.0



355
356
357
 
# File 'lib/mongo/server/description.rb', line 355

def max_wire_version
  config[MAX_WIRE_VERSION] || 0
end

#max_write_batch_size ⇒ Integer

Get the maximum batch size for writes.

Examples:

Get the max batch size.

description.max_write_batch_size

Returns:

  • (Integer) —

    The max batch size.

Since:

  • 2.0.0



343
344
345
 
# File 'lib/mongo/server/description.rb', line 343

def max_write_batch_size
  config[MAX_WRITE_BATCH_SIZE] || DEFAULT_MAX_WRITE_BATCH_SIZE
end

#me ⇒ String

Note:

The value in me field may differ from the server description’s address. This can happen, for example, in split horizon configurations. The SDAM spec only requires removing servers whose me does not match their address in some of the situations (e.g. when the server in question is an RS member but not a primary).

Get the me field value.

Returns:

  • (String) —

    The me field.

Since:

  • 2.1.0



382
383
384
 
# File 'lib/mongo/server/description.rb', line 382

def me
  config[ME]
end

#me_mismatch? ⇒ true, false

Check if there is a mismatch between the address host and the me field.

Examples:

Check if there is a mismatch.

description.me_mismatch?

Returns:

  • (true, false) —

    If there is a mismatch between the me field and the address host.

Since:

  • 2.0.6



689
690
691
 
# File 'lib/mongo/server/description.rb', line 689

def me_mismatch?
  !!(address.to_s.downcase != me.downcase if me)
end

#min_wire_version ⇒ Integer

Get the minimum wire version. Defaults to zero.

Examples:

Get the min wire version.

description.min_wire_version

Returns:

  • (Integer) —

    The min wire version supported.

Since:

  • 2.0.0



367
368
369
 
# File 'lib/mongo/server/description.rb', line 367

def min_wire_version
  config[MIN_WIRE_VERSION] || 0
end

#mongos? ⇒ true, false

Returns whether this server is a mongos, per the SDAM spec.

Examples:

Is the server a mongos?

description.mongos?

Returns:

  • (true, false) —

    If the server is a mongos.

Since:

  • 2.0.0



454
455
456
 
# File 'lib/mongo/server/description.rb', line 454

def mongos?
  ok? && config['msg'] == 'isdbgrid'
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.

Returns:

  • (Boolean)

Since:

  • 2.0.0



613
614
615
616
 
# File 'lib/mongo/server/description.rb', line 613

def ok?
  config[Operation::Result::OK] &&
    config[Operation::Result::OK] == 1 || false
end

#op_time ⇒ BSON::Timestamp

opTime in lastWrite subdocument of the ismaster response.

Returns:

  • (BSON::Timestamp) —

    The timestamp.

Since:

  • 2.7.0



698
699
700
701
702
 
# File 'lib/mongo/server/description.rb', line 698

def op_time
  if config['lastWrite'] && config['lastWrite']['opTime']
    config['lastWrite']['opTime']['ts']
  end
end

#other? ⇒ true, false

Returns whether the server is an other, per the SDAM spec.

Examples:

Is the description of type other.

description.other?

Returns:

  • (true, false) —

    If the description is other.

Since:

  • 2.0.0



466
467
468
469
470
471
472
473
474
475
 
# File 'lib/mongo/server/description.rb', line 466

def other?
  # The SDAM spec is slightly confusing on what "other" means,
  # but it's referred to it as "RSOther" which means a non-RS member
  # cannot be "other".
  ok? &&
  !!config['setName'] && (
    config['hidden'] == true ||
    !primary? && !secondary? && !arbiter?
  )
end

#passive? ⇒ true, false

Will return true if the server is passive.

Examples:

Is the server passive?

description.passive?

Returns:

  • (true, false) —

    If the server is passive.

Since:

  • 2.0.0



485
486
487
 
# File 'lib/mongo/server/description.rb', line 485

def passive?
  ok? && !!config[PASSIVE]
end

#passives ⇒ Array<String>

Get a list of the passive servers in the cluster.

Examples:

Get the passives.

description.passives

Returns:

  • (Array<String>) —

    The list of passives.

Since:

  • 2.0.0



497
498
499
 
# File 'lib/mongo/server/description.rb', line 497

def passives
  @passives ||= (config[PASSIVES] || []).map { |s| s.downcase }
end

#primary? ⇒ true, false

Returns whether this server is a primary, per the SDAM spec.

Examples:

Is the server a primary?

description.primary?

Returns:

  • (true, false) —

    If the server is a primary.

Since:

  • 2.0.0



521
522
523
524
525
 
# File 'lib/mongo/server/description.rb', line 521

def primary?
  ok? &&
  config['ismaster'] == true &&
  !!config['setName']
end

#primary_host ⇒ String | nil

Get the address of the primary host.

Examples:

Get the address of the primary.

description.primary_host

Returns:

  • (String | nil) —

    The address of the primary.

Since:

  • 2.6.0



509
510
511
 
# File 'lib/mongo/server/description.rb', line 509

def primary_host
  config[PRIMARY_HOST] && config[PRIMARY_HOST].downcase
end

#replica_set_member? ⇒ true, false

Does this description correspond to a replica set member.

Examples:

Check if the description is from a replica set member.

description.replica_set_member?

Returns:

  • (true, false) —

    If the description is from a replica set member.

Since:

  • 2.0.6



666
667
668
 
# File 'lib/mongo/server/description.rb', line 666

def replica_set_member?
  ok? && !(standalone? || mongos?)
end

#replica_set_name ⇒ String?

Get the name of the replica set the server belongs to, returns nil if none.

Examples:

Get the replica set name.

description.replica_set_name

Returns:

  • (String, nil) —

    The name of the replica set.

Since:

  • 2.0.0



536
537
538
 
# File 'lib/mongo/server/description.rb', line 536

def replica_set_name
  config[SET_NAME]
end

#secondary? ⇒ true, false

Returns whether this server is a secondary, per the SDAM spec.

Examples:

Is the server a secondary?

description.secondary?

Returns:

  • (true, false) —

    If the server is a secondary.

Since:

  • 2.0.0



560
561
562
563
564
 
# File 'lib/mongo/server/description.rb', line 560

def secondary?
  ok? &&
  config['secondary'] == true &&
  !!config['setName']
end

#server_type ⇒ Symbol

Returns the server type as a symbol.

Examples:

Get the server type.

description.server_type

Returns:

  • (Symbol) —

    The server type.

Since:

  • 2.4.0



574
575
576
577
578
579
580
581
582
583
 
# File 'lib/mongo/server/description.rb', line 574

def server_type
  return :arbiter if arbiter?
  return :ghost if ghost?
  return :sharded if mongos?
  return :primary if primary?
  return :secondary if secondary?
  return :standalone if standalone?
  return :other if other?
  :unknown
end

#server_version_gte?(version) ⇒ 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.

Returns:

  • (Boolean)

Since:

  • 2.0.0



737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
 
# File 'lib/mongo/server/description.rb', line 737

def server_version_gte?(version)
  required_wv = case version
    when '4.2'
      8
    when '4.0'
      7
    when '3.6'
      6
    when '3.4'
      5
    when '3.2'
      4
    when '3.0'
      3
    when '2.6'
      2
    else
      raise ArgumentError, "Bogus required version #{version}"
    end

  required_wv >= min_wire_version && required_wv <= max_wire_version
end

#servers ⇒ Array<String>

Get a list of all servers known to the cluster.

Examples:

Get all servers.

description.servers

Returns:

  • (Array<String>) —

    The list of all servers.

Since:

  • 2.0.0



548
549
550
 
# File 'lib/mongo/server/description.rb', line 548

def servers
  hosts + arbiters + passives
end

#set_version ⇒ Integer

Get the setVersion from the config.

Examples:

Get the setVersion.

description.set_version

Returns:

  • (Integer) —

    The set version.

Since:

  • 2.2.2



418
419
420
 
# File 'lib/mongo/server/description.rb', line 418

def set_version
  config[SET_VERSION]
end

#standalone? ⇒ true, false

Returns whether this server is a standalone, per the SDAM spec.

Examples:

Is the server standalone?

description.standalone?

Returns:

  • (true, false) —

    If the server is standalone.

Since:

  • 2.0.0



593
594
595
596
597
598
 
# File 'lib/mongo/server/description.rb', line 593

def standalone?
  ok? &&
  config['msg'] != 'isdbgrid' &&
  config['setName'].nil? &&
  config['isreplicaset'] != true
end

#tags ⇒ Hash

Get the tags configured for the server.

Examples:

Get the tags.

description.tags

Returns:

  • (Hash) —

    The tags of the server.

Since:

  • 2.0.0



394
395
396
 
# File 'lib/mongo/server/description.rb', line 394

def tags
  config[TAGS] || {}
end

#unknown? ⇒ true, false

Returns whether this server is an unknown, per the SDAM spec.

Examples:

Is the server description unknown?

description.unknown?

Returns:

  • (true, false) —

    If the server description is unknown.

Since:

  • 2.0.0



608
609
610
 
# File 'lib/mongo/server/description.rb', line 608

def unknown?
  config.empty? || !ok?
end

#wire_versions ⇒ Range

Get the range of supported wire versions for the server.

Examples:

Get the wire version range.

description.wire_versions

Returns:

  • (Range) —

    The wire version range.

Since:

  • 2.0.0



626
627
628
 
# File 'lib/mongo/server/description.rb', line 626

def wire_versions
  min_wire_version..max_wire_version
end