# File lib/mongo/server/description.rb, line 631 def primary? ok? && (config['ismaster'] == true || config['isWritablePrimary'] == true ) && !!config['setName'] end
class Mongo::Server::Description
Represents a description of the server, populated by the result of the hello 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
@return [ Address
] address The server's address.
@return [ Float ] The moving average time the hello call took to complete.
@return [ Hash ] The actual result from the hello command.
Time when this server description was created according to monotonic clock.
@see Description::last_updated_time for more detail
@return [ Float ] Server
description creation monotonic time.
@api private
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
Instantiate the new server description from the result of the hello command or fabricate a placeholder description for Unknown and LoadBalancer
servers.
@example Instantiate the new description.
Description.new(address, { 'isWritablePrimary' => true }, 0.5)
@param [ Address
] address The server address. @param [ Hash ] config The result of the hello command. @param [ Float ] average_round_trip_time
The moving average time (sec) the hello
command took to complete.
@param [ Float ] average_round_trip_time
The moving average time (sec)
the ismaster call took to complete.
@param [ true | false ] load_balancer Whether the server is treated as
a load balancer.
@param [ true | false ] force_load_balancer Whether the server is
forced to be a load balancer.
@api private
# File lib/mongo/server/description.rb, line 220 def initialize(address, config = {}, average_round_trip_time: nil, load_balancer: false, force_load_balancer: false ) @address = address @config = config @load_balancer = !!load_balancer @force_load_balancer = !!force_load_balancer @features = Features.new(wire_versions, me || @address.to_s) @average_round_trip_time = average_round_trip_time @last_update_time = Time.now.freeze @last_update_monotime = Utils.monotonic_time if load_balancer # When loadBalanced=true URI option is set, the driver will refuse # to work if the server it communicates with does not set serviceId # in ismaster/hello response. # # At the moment we cannot run a proper load balancer setup on evergreen # # Therefore, when connect=:load_balanced Ruby option is used instead # of the loadBalanced=true URI option, if serviceId is not set in # ismaster/hello response, the driver fabricates a serviceId and # proceeds to treat a server that does not report itself as being # behind a load balancer as a server that is behind a load balancer. # # 5.0+ servers should provide topologyVersion.processId which # is specific to the particular process instance. We can use that # field as a proxy for serviceId. # # If the topologyVersion isn't provided for whatever reason, we # fabricate a serviceId locally. # # In either case, a serviceId provided by an actual server behind # a load balancer is supposed to be a BSON::ObjectId. The fabricated # service ids are strings, to distinguish them from the real ones. # In particular processId is also a BSON::ObjectId, but will be # mapped to a string for clarity that this is a fake service id. # # TODO: Remove this when https://jira.mongodb.org/browse/RUBY-2881 is done. if ok? && !service_id unless force_load_balancer raise Error::MissingServiceId, "The server at #{address.seed} did not provide a service id in handshake response" end fake_service_id = if process_id = topology_version && topology_version['processId'] "process:#{process_id}" else "fake:#{rand(2**32-1)+1}" end @config = @config.merge('serviceId' => fake_service_id) end end if Mongo::Lint.enabled? # prepopulate cache instance variables hosts arbiters passives topology_version freeze end end
Public Instance Methods
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 859 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
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 313 def arbiter? ok? && config['arbiterOnly'] == true && !!config['setName'] end
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 327 def arbiters @arbiters ||= (config[ARBITERS] || []).map { |s| s.downcase } end
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 789 def data_bearing? mongos? || primary? || secondary? || standalone? end
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 475 def election_id config[ELECTION_ID] end
@return [ Features
] features The features for the server.
# File lib/mongo/server/description.rb, line 298 def features @features end
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 339 def ghost? ok? && config['isreplicaset'] == true end
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 364 def hosts @hosts ||= (config[HOSTS] || []).map { |s| s.downcase } end
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 376 def inspect "#<Mongo::Server:Description:0x#{object_id} config=#{config} average_round_trip_time=#{average_round_trip_time}>" end
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 751 def is_server?(server) address == server.address end
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 540 def last_write_date config[LAST_WRITE][LAST_WRITE_DATE] if config[LAST_WRITE] end
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 765 def lists_server?(server) servers.include?(server.address.to_s) end
Returns whether this server is a load balancer.
@return [ true | false ] Whether this server is a load balancer.
# File lib/mongo/server/description.rb, line 293 def load_balancer? @load_balancer end
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 552 def logical_session_timeout config[LOGICAL_SESSION_TIMEOUT_MINUTES] if config[LOGICAL_SESSION_TIMEOUT_MINUTES] end
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 388 def max_bson_object_size config[MAX_BSON_OBJECT_SIZE] end
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 400 def max_message_size config[MAX_MESSAGE_BYTES] end
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 424 def max_wire_version config[MAX_WIRE_VERSION] || 0 end
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 412 def max_write_batch_size config[MAX_WRITE_BATCH_SIZE] || DEFAULT_MAX_WRITE_BATCH_SIZE end
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 451 def me config[ME] end
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 801 def me_mismatch? !!(address.to_s.downcase != me.downcase if me) end
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 436 def min_wire_version config[MIN_WIRE_VERSION] || 0 end
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 564 def mongos? ok? && config['msg'] == 'isdbgrid' end
@api private
# File lib/mongo/server/description.rb, line 725 def ok? config[Operation::Result::OK] && config[Operation::Result::OK] == 1 || false end
opTime in lastWrite subdocument of the hello response.
@return [ BSON::Timestamp ] The timestamp.
@since 2.7.0
# File lib/mongo/server/description.rb, line 810 def op_time if config['lastWrite'] && config['lastWrite']['opTime'] config['lastWrite']['opTime']['ts'] end end
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 576 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
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 595 def passive? ok? && !!config[PASSIVE] end
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 607 def passives @passives ||= (config[PASSIVES] || []).map { |s| s.downcase } end
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
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 619 def primary_host config[PRIMARY_HOST] && config[PRIMARY_HOST].downcase end
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 778 def replica_set_member? ok? && !(standalone? || mongos?) end
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 646 def replica_set_name config[SET_NAME] end
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 670 def secondary? ok? && config['secondary'] == true && !!config['setName'] end
@api experimental
# File lib/mongo/server/description.rb, line 838 def server_connection_id config['connectionId'] end
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 684 def server_type return :load_balancer if load_balancer? 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
@api private
# File lib/mongo/server/description.rb, line 870 def server_version_gte?(version) required_wv = case version when '7.0' 21 when '6.0' 17 when '5.2' 15 when '5.1' 14 when '5.0' 12 when '4.4' 9 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 if load_balancer? # If we are talking to a load balancer, there is no monitoring # and we don't know what server is behind the load balancer. # Assume everything is supported. # TODO remove this when RUBY-2220 is implemented. return true end required_wv >= min_wire_version && required_wv <= max_wire_version end
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 658 def servers hosts + arbiters + passives end
@return [ nil | Object ] The service id, if any.
@api experimental
# File lib/mongo/server/description.rb, line 845 def service_id config['serviceId'] end
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 487 def set_version config[SET_VERSION] end
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 704 def standalone? ok? && config['msg'] != 'isdbgrid' && config['setName'].nil? && config['isreplicaset'] != true end
@return [ TopologyVersion
| nil ] The topology version.
# File lib/mongo/server/description.rb, line 492 def topology_version unless defined?(@topology_version) @topology_version = config['topologyVersion'] && TopologyVersion.new(config['topologyVersion']) end @topology_version end
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 508 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
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 524 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
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 719 def unknown? return false if load_balancer? config.empty? || config.keys == %w(topologyVersion) || !ok? end
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 738 def wire_versions min_wire_version..max_wire_version end