class Mongo::Server::Description

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

Constants

ARBITER

Constant for reading arbiter info from config.

@since 2.0.0 @deprecated

ARBITERS

Constant for reading arbiters info from config.

@since 2.0.0

CONNECTION_ID

Constant for reading connectionId info from config.

@api private

DEFAULT_MAX_WRITE_BATCH_SIZE

Default max write batch size.

@since 2.0.0

ELECTION_ID

Constant for reading electionId info from config.

@since 2.1.0

EXCLUDE_FOR_COMPARISON

Fields to exclude when comparing two descriptions.

@since 2.0.6

HIDDEN

Constant for reading hidden info from config.

@since 2.0.0

HOSTS

Constant for reading hosts info from config.

@since 2.0.0

LAST_WRITE

Constant for the lastWrite subdocument.

@since 2.4.0

LAST_WRITE_DATE

Constant for the lastWriteDate field in the lastWrite subdocument.

@since 2.4.0

LEGACY_WIRE_VERSION

The legacy wire protocol version.

@since 2.0.0 @deprecated Will be removed in 3.0.

LOCAL_TIME

Constant for reading localTime info from config.

@since 2.1.0

LOGICAL_SESSION_TIMEOUT_MINUTES

Constant for reading logicalSessionTimeoutMinutes info from config.

@since 2.5.0

MAX_BSON_OBJECT_SIZE

Constant for reading max bson size info from config.

@since 2.0.0

MAX_MESSAGE_BYTES

Constant for reading max message size info from config.

@since 2.0.0

MAX_WIRE_VERSION

Constant for the max wire version.

@since 2.0.0

MAX_WRITE_BATCH_SIZE

Constant for reading max write batch size.

@since 2.0.0

ME

Constant for reading the me field.

@since 2.1.0

MESSAGE

Constant for the key for the message value.

@since 2.0.0 @deprecated

MIN_WIRE_VERSION

Constant for min wire version.

@since 2.0.0

MONGOS_MESSAGE

Constant for the message that indicates a sharded cluster.

@since 2.0.0 @deprecated

OPERATION_TIME

Constant for reading operationTime info from config.

@since 2.5.0

PASSIVE

Constant for reading passive info from config.

@since 2.0.0

PASSIVES

Constant for reading the passive server list.

@since 2.0.0

PRIMARY

Constant for reading primary info from config.

@since 2.0.0 @deprecated

PRIMARY_HOST

Constant for reading primary host field from config.

@since 2.5.0

REPLICA_SET

Constant for determining ghost servers.

@since 2.0.0 @deprecated

SECONDARY

Constant for reading secondary info from config.

@since 2.0.0 @deprecated

SET_NAME

Constant for reading replica set name info from config.

@since 2.0.0

SET_VERSION

Constant for reading setVersion info from config.

@since 2.2.2

TAGS

Constant for reading tags info from config.

@since 2.0.0

Attributes

address[R]

@return [ Address ] address The server's address.

average_round_trip_time[R]

@return [ Float ] The moving average time the ismaster call took to complete.

config[R]

@return [ Hash ] The actual result from the ismaster command.

last_update_time[R]

Time when this server description was created.

@note This time does not indicate when a successful server check 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.

@return [ Time ] Server description creation time.

@since 2.7.0

Public Class Methods

new(address, config = {}, average_round_trip_time = nil) click to toggle source

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

@example Instantiate the new description.

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

@param [ Address ] address The server address. @param [ Hash ] config The result of the ismaster command. @param [ Float ] average_round_trip_time The moving average time (sec) the ismaster

call took to complete.

@since 2.0.0

# File lib/mongo/server/description.rb, line 212
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
    topology_version

    freeze
  end
end

Public Instance Methods

==(other) click to toggle source

Check equality of two descriptions.

@example Check description equality.

description == other

@param [ Object ] other The other description.

@return [ true, false ] Whether the objects are equal.

@since 2.0.6

# File lib/mongo/server/description.rb, line 780
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
Also aliased as: eql?
arbiter?() click to toggle source

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

@example Is the server an arbiter?

description.arbiter?

@return [ true, false ] If the server is an arbiter.

@since 2.0.0

# File lib/mongo/server/description.rb, line 252
def arbiter?
  ok? &&
  config['arbiterOnly'] == true &&
  !!config['setName']
end
arbiters() click to toggle source

Get a list of all arbiters in the replica set.

@example Get the arbiters in the replica set.

description.arbiters

@return [ Array<String> ] The arbiters in the set.

@since 2.0.0

# File lib/mongo/server/description.rb, line 266
def arbiters
  @arbiters ||= (config[ARBITERS] || []).map { |s| s.downcase }
end
data_bearing?() click to toggle source

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

@return [ true, false ] Whether the description is from a data-bearing

server.

@since 2.7.0

# File lib/mongo/server/description.rb, line 726
def data_bearing?
  mongos? || primary? || secondary? || standalone?
end
election_id() click to toggle source

Get the electionId from the config.

@example Get the electionId.

description.election_id

@return [ BSON::ObjectId ] The election id.

@since 2.1.0

# File lib/mongo/server/description.rb, line 414
def election_id
  config[ELECTION_ID]
end
eql?(other)
Alias for: ==
features() click to toggle source

@return [ Features ] features The features for the server.

# File lib/mongo/server/description.rb, line 237
def features
  @features
end
ghost?() click to toggle source

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

@example Is the server a ghost?

description.ghost?

@return [ true, false ] If the server is a ghost.

@since 2.0.0

# File lib/mongo/server/description.rb, line 278
def ghost?
  ok? &&
  config['isreplicaset'] == true
end
hidden?() click to toggle source

Will return true if the server is hidden.

@example Is the server hidden?

description.hidden?

@return [ true, false ] If the server is hidden.

@since 2.0.0

# File lib/mongo/server/description.rb, line 291
def hidden?
  ok? && !!config[HIDDEN]
end
hosts() click to toggle source

Get a list of all servers in the replica set.

@example Get the servers in the replica set.

description.hosts

@return [ Array<String> ] The servers in the set.

@since 2.0.0

# File lib/mongo/server/description.rb, line 303
def hosts
  @hosts ||= (config[HOSTS] || []).map { |s| s.downcase }
end
inspect() click to toggle source

Inspect the server description.

@example Inspect the server description

description.inspect

@return [ String ] The inspection.

@since 2.0.0

# File lib/mongo/server/description.rb, line 315
def inspect
  "#<Mongo::Server:Description:0x#{object_id} config=#{config} average_round_trip_time=#{average_round_trip_time}>"
end
is_server?(server) click to toggle source

Is this description from the given server.

@example Check if the description is from a given server.

description.is_server?(server)

@return [ true, false ] If the description is from the server.

@since 2.0.6 @deprecated

# File lib/mongo/server/description.rb, line 688
def is_server?(server)
  address == server.address
end
last_write_date() click to toggle source

Get the lastWriteDate from the lastWrite subdocument in the config.

@example Get the lastWriteDate value.

description.last_write_date

@return [ Time ] The last write date.

@since 2.4.0

# File lib/mongo/server/description.rb, line 479
def last_write_date
  config[LAST_WRITE][LAST_WRITE_DATE] if config[LAST_WRITE]
end
lists_server?(server) click to toggle source

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

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

description.lists_server?(server)

@return [ true, false ] If a server is in the description's list

of servers.

@since 2.0.6 @deprecated

# File lib/mongo/server/description.rb, line 702
def lists_server?(server)
  servers.include?(server.address.to_s)
end
logical_session_timeout() click to toggle source

Get the logicalSessionTimeoutMinutes from the config.

@example Get the logicalSessionTimeoutMinutes value in minutes.

description.logical_session_timeout

@return [ Integer, nil ] The logical session timeout in minutes.

@since 2.5.0

# File lib/mongo/server/description.rb, line 491
def logical_session_timeout
  config[LOGICAL_SESSION_TIMEOUT_MINUTES] if config[LOGICAL_SESSION_TIMEOUT_MINUTES]
end
max_bson_object_size() click to toggle source

Get the max BSON object size for this server version.

@example Get the max BSON object size.

description.max_bson_object_size

@return [ Integer ] The maximum object size in bytes.

@since 2.0.0

# File lib/mongo/server/description.rb, line 327
def max_bson_object_size
  config[MAX_BSON_OBJECT_SIZE]
end
max_message_size() click to toggle source

Get the max message size for this server version.

@example Get the max message size.

description.max_message_size

@return [ Integer ] The maximum message size in bytes.

@since 2.0.0

# File lib/mongo/server/description.rb, line 339
def max_message_size
  config[MAX_MESSAGE_BYTES]
end
max_wire_version() click to toggle source

Get the maximum wire version. Defaults to zero.

@example Get the max wire version.

description.max_wire_version

@return [ Integer ] The max wire version supported.

@since 2.0.0

# File lib/mongo/server/description.rb, line 363
def max_wire_version
  config[MAX_WIRE_VERSION] || 0
end
max_write_batch_size() click to toggle source

Get the maximum batch size for writes.

@example Get the max batch size.

description.max_write_batch_size

@return [ Integer ] The max batch size.

@since 2.0.0

# File lib/mongo/server/description.rb, line 351
def max_write_batch_size
  config[MAX_WRITE_BATCH_SIZE] || DEFAULT_MAX_WRITE_BATCH_SIZE
end
me() click to toggle source

Get the me field value.

@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).

@return [ String ] The me field.

@since 2.1.0

# File lib/mongo/server/description.rb, line 390
def me
  config[ME]
end
me_mismatch?() click to toggle source

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

@example Check if there is a mismatch.

description.me_mismatch?

@return [ true, false ] If there is a mismatch between the me field and the address host.

@since 2.0.6

# File lib/mongo/server/description.rb, line 738
def me_mismatch?
  !!(address.to_s.downcase != me.downcase if me)
end
min_wire_version() click to toggle source

Get the minimum wire version. Defaults to zero.

@example Get the min wire version.

description.min_wire_version

@return [ Integer ] The min wire version supported.

@since 2.0.0

# File lib/mongo/server/description.rb, line 375
def min_wire_version
  config[MIN_WIRE_VERSION] || 0
end
mongos?() click to toggle source

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

@example Is the server a mongos?

description.mongos?

@return [ true, false ] If the server is a mongos.

@since 2.0.0

# File lib/mongo/server/description.rb, line 503
def mongos?
  ok? && config['msg'] == 'isdbgrid'
end
ok?() click to toggle source

@api private

# File lib/mongo/server/description.rb, line 662
def ok?
  config[Operation::Result::OK] &&
    config[Operation::Result::OK] == 1 || false
end
op_time() click to toggle source

opTime in lastWrite subdocument of the ismaster response.

@return [ BSON::Timestamp ] The timestamp.

@since 2.7.0

# File lib/mongo/server/description.rb, line 747
def op_time
  if config['lastWrite'] && config['lastWrite']['opTime']
    config['lastWrite']['opTime']['ts']
  end
end
other?() click to toggle source

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

@example Is the description of type other.

description.other?

@return [ true, false ] If the description is other.

@since 2.0.0

# File lib/mongo/server/description.rb, line 515
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?() click to toggle source

Will return true if the server is passive.

@example Is the server passive?

description.passive?

@return [ true, false ] If the server is passive.

@since 2.0.0

# File lib/mongo/server/description.rb, line 534
def passive?
  ok? && !!config[PASSIVE]
end
passives() click to toggle source

Get a list of the passive servers in the cluster.

@example Get the passives.

description.passives

@return [ Array<String> ] The list of passives.

@since 2.0.0

# File lib/mongo/server/description.rb, line 546
def passives
  @passives ||= (config[PASSIVES] || []).map { |s| s.downcase }
end
primary?() click to toggle source

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

@example Is the server a primary?

description.primary?

@return [ true, false ] If the server is a primary.

@since 2.0.0

# File lib/mongo/server/description.rb, line 570
def primary?
  ok? &&
  config['ismaster'] == true &&
  !!config['setName']
end
primary_host() click to toggle source

Get the address of the primary host.

@example Get the address of the primary.

description.primary_host

@return [ String | nil ] The address of the primary.

@since 2.6.0

# File lib/mongo/server/description.rb, line 558
def primary_host
  config[PRIMARY_HOST] && config[PRIMARY_HOST].downcase
end
replica_set_member?() click to toggle source

Does this description correspond to a replica set member.

@example Check if the description is from a replica set member.

description.replica_set_member?

@return [ true, false ] If the description is from a replica set

member.

@since 2.0.6

# File lib/mongo/server/description.rb, line 715
def replica_set_member?
  ok? && !(standalone? || mongos?)
end
replica_set_name() click to toggle source

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

@example Get the replica set name.

description.replica_set_name

@return [ String, nil ] The name of the replica set.

@since 2.0.0

# File lib/mongo/server/description.rb, line 585
def replica_set_name
  config[SET_NAME]
end
secondary?() click to toggle source

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

@example Is the server a secondary?

description.secondary?

@return [ true, false ] If the server is a secondary.

@since 2.0.0

# File lib/mongo/server/description.rb, line 609
def secondary?
  ok? &&
  config['secondary'] == true &&
  !!config['setName']
end
server_connection_id() click to toggle source

@api experimental

# File lib/mongo/server/description.rb, line 766
def server_connection_id
  config['connectionId']
end
server_type() click to toggle source

Returns the server type as a symbol.

@example Get the server type.

description.server_type

@return [ Symbol ] The server type.

@since 2.4.0

# File lib/mongo/server/description.rb, line 623
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) click to toggle source

@api private

# File lib/mongo/server/description.rb, line 791
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() click to toggle source

Get a list of all servers known to the cluster.

@example Get all servers.

description.servers

@return [ Array<String> ] The list of all servers.

@since 2.0.0

# File lib/mongo/server/description.rb, line 597
def servers
  hosts + arbiters + passives
end
set_version() click to toggle source

Get the setVersion from the config.

@example Get the setVersion.

description.set_version

@return [ Integer ] The set version.

@since 2.2.2

# File lib/mongo/server/description.rb, line 426
def set_version
  config[SET_VERSION]
end
standalone?() click to toggle source

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

@example Is the server standalone?

description.standalone?

@return [ true, false ] If the server is standalone.

@since 2.0.0

# File lib/mongo/server/description.rb, line 642
def standalone?
  ok? &&
  config['msg'] != 'isdbgrid' &&
  config['setName'].nil? &&
  config['isreplicaset'] != true
end
tags() click to toggle source

Get the tags configured for the server.

@example Get the tags.

description.tags

@return [ Hash ] The tags of the server.

@since 2.0.0

# File lib/mongo/server/description.rb, line 402
def tags
  config[TAGS] || {}
end
topology_version() click to toggle source

@return [ TopologyVersion | nil ] The topology version.

# File lib/mongo/server/description.rb, line 431
def topology_version
  unless defined?(@topology_version)
    @topology_version = config['topologyVersion'] &&
      TopologyVersion.new(config['topologyVersion'])
  end
  @topology_version
end
topology_version_gt?(other_desc) click to toggle source

Returns whether topology version in this description is potentially newer than or equal to topology version in another description.

@param [ Server::Description ] other_desc The other server description.

@return [ true | false ] Whether topology version in this description

is potentially newer or equal.

@api private

# File lib/mongo/server/description.rb, line 447
def topology_version_gt?(other_desc)
  if topology_version.nil? || other_desc.topology_version.nil?
    true
  else
    topology_version.gt?(other_desc.topology_version)
  end
end
topology_version_gte?(other_desc) click to toggle source

Returns whether topology version in this description is potentially newer than topology version in another description.

@param [ Server::Description ] other_desc The other server description.

@return [ true | false ] Whether topology version in this description

is potentially newer.

@api private

# File lib/mongo/server/description.rb, line 463
def topology_version_gte?(other_desc)
  if topology_version.nil? || other_desc.topology_version.nil?
    true
  else
    topology_version.gte?(other_desc.topology_version)
  end
end
unknown?() click to toggle source

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

@example Is the server description unknown?

description.unknown?

@return [ true, false ] If the server description is unknown.

@since 2.0.0

# File lib/mongo/server/description.rb, line 657
def unknown?
  config.empty? || config.keys == %w(topologyVersion) || !ok?
end
wire_versions() click to toggle source

Get the range of supported wire versions for the server.

@example Get the wire version range.

description.wire_versions

@return [ Range ] The wire version range.

@since 2.0.0

# File lib/mongo/server/description.rb, line 675
def wire_versions
  min_wire_version..max_wire_version
end