Description — Documentation by YARD 0.9.37 (original) (raw)

Class: Mongo::Server::Description

Inherits:

Object

Defined in:

lib/mongo/server/description.rb,
lib/mongo/server/description/features.rb,
lib/mongo/server/description/load_balancer.rb

Overview

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.

Defined Under Namespace

Classes: Features, LoadBalancer

Constant Summarycollapse

ARBITER =

Constant for reading arbiter info from config.

'arbiterOnly'.freeze

ARBITERS =

Constant for reading arbiters info from config.

'arbiters'.freeze

HIDDEN =

Constant for reading hidden info from config.

'hidden'.freeze

HOSTS =

Constant for reading hosts info from config.

'hosts'.freeze

MESSAGE =

Constant for the key for the message value.

'msg'.freeze

MONGOS_MESSAGE =

Constant for the message that indicates a sharded cluster.

'isdbgrid'.freeze

REPLICA_SET =

Constant for determining ghost servers.

'isreplicaset'.freeze

MAX_BSON_OBJECT_SIZE =

Constant for reading max bson size info from config.

'maxBsonObjectSize'.freeze

MAX_MESSAGE_BYTES =

Constant for reading max message size info from config.

'maxMessageSizeBytes'.freeze

MAX_WIRE_VERSION =

Constant for the max wire version.

'maxWireVersion'.freeze

MIN_WIRE_VERSION =

Constant for min wire version.

'minWireVersion'.freeze

MAX_WRITE_BATCH_SIZE =

Constant for reading max write batch size.

'maxWriteBatchSize'.freeze

LAST_WRITE =

Constant for the lastWrite subdocument.

'lastWrite'.freeze

LAST_WRITE_DATE =

Constant for the lastWriteDate field in the lastWrite subdocument.

'lastWriteDate'.freeze

ME =

Constant for reading the me field.

'me'.freeze

DEFAULT_MAX_WRITE_BATCH_SIZE =

Default max write batch size.

1000.freeze

LEGACY_WIRE_VERSION =

Deprecated.

Will be removed in 3.0.

The legacy wire protocol version.

0.freeze

PASSIVE =

Constant for reading passive info from config.

'passive'.freeze

PASSIVES =

Constant for reading the passive server list.

'passives'.freeze

PRIMARY =

Constant for reading primary info from config.

'ismaster'.freeze

PRIMARY_HOST =

Constant for reading primary host field from config.

'primary'.freeze

SECONDARY =

Constant for reading secondary info from config.

'secondary'.freeze

SET_NAME =

Constant for reading replica set name info from config.

'setName'.freeze

TAGS =

Constant for reading tags info from config.

'tags'.freeze

ELECTION_ID =

Constant for reading electionId info from config.

'electionId'.freeze

SET_VERSION =

Constant for reading setVersion info from config.

'setVersion'.freeze

LOCAL_TIME =

Constant for reading localTime info from config.

'localTime'.freeze

OPERATION_TIME =

Constant for reading operationTime info from config.

'operationTime'.freeze

LOGICAL_SESSION_TIMEOUT_MINUTES =

Constant for reading logicalSessionTimeoutMinutes info from config.

'logicalSessionTimeoutMinutes'.freeze

CONNECTION_ID =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Constant for reading connectionId info from config.

'connectionId'.freeze

EXCLUDE_FOR_COMPARISON =

Fields to exclude when comparing two descriptions.

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

Instance Attribute Summary collapse

Instance Method Summarycollapse

Constructor Details

#initialize(address, config = {}, average_round_trip_time: nil, minimum_round_trip_time: 0, load_balancer: false, force_load_balancer: false) ⇒ Description

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.

Instantiate the new server description from the result of the hello command or fabricate a placeholder description for Unknown and LoadBalancer servers.

| 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 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 | # File 'lib/mongo/server/description.rb', line 220 def initialize(address, config = {}, average_round_trip_time: nil, minimum_round_trip_time: 0, 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 @minimum_round_trip_time = minimum_round_trip_time @last_update_time = Time.now.freeze @last_update_monotime = Utils.monotonic_time if load_balancer 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? hosts arbiters passives topology_version freeze end end | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

Instance Attribute Details

#address ⇒ Address

Returns address The server’s address.

287 288 289 # File 'lib/mongo/server/description.rb', line 287 def address @address end

#average_round_trip_time ⇒ Float

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

305 306 307 # File 'lib/mongo/server/description.rb', line 305 def average_round_trip_time @average_round_trip_time end

#config ⇒ Hash

Returns The actual result from the hello command.

290 291 292 # File 'lib/mongo/server/description.rb', line 290 def config @config end

#last_update_monotime ⇒ Float

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.

Time when this server description was created according to monotonic clock.

848 849 850 # File 'lib/mongo/server/description.rb', line 848 def last_update_monotime @last_update_monotime end

#last_update_time ⇒ Time

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.

839 840 841 # File 'lib/mongo/server/description.rb', line 839 def last_update_time @last_update_time end

#minimum_round_trip_time ⇒ Float

Returns The minimum time from the ten last hello calls took to complete.

309 310 311 # File 'lib/mongo/server/description.rb', line 309 def minimum_round_trip_time @minimum_round_trip_time end

Instance Method Details

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

Check equality of two descriptions.

| 872 873 874 875 876 877 878 879 | # File 'lib/mongo/server/description.rb', line 872 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.

319 320 321 322 323 # File 'lib/mongo/server/description.rb', line 319 def arbiter? ok? && config['arbiterOnly'] == true && !!config['setName'] end

#arbiters ⇒ Array

Get a list of all arbiters in the replica set.

| 333 334 335 | # File 'lib/mongo/server/description.rb', line 333 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).

| 794 795 796 | # File 'lib/mongo/server/description.rb', line 794 def data_bearing? mongos? || primary? | | secondary? | | standalone? end | | ----------- | --------------------------------------------------------------------------------------------- | ------------ | ----------------- |

#election_id ⇒ BSON::ObjectId

Get the electionId from the config.

481 482 483 # File 'lib/mongo/server/description.rb', line 481 def election_id config[ELECTION_ID] end

#features ⇒ Features

Returns features The features for the server.

300 301 302 # File 'lib/mongo/server/description.rb', line 300 def features @features end

#ghost? ⇒ true, false

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

345 346 347 348 # File 'lib/mongo/server/description.rb', line 345 def ghost? ok? && config['isreplicaset'] == true end

#hidden? ⇒ true, false

Will return true if the server is hidden.

358 359 360 # File 'lib/mongo/server/description.rb', line 358 def hidden? ok? && !!config[HIDDEN] end

#hosts ⇒ Array

Get a list of all servers in the replica set.

| 370 371 372 | # File 'lib/mongo/server/description.rb', line 370 def hosts @hosts ||= (config[HOSTS] | | []).map { | s| s.downcase } end | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------- |

#inspect ⇒ String

Inspect the server description.

382 383 384 # File 'lib/mongo/server/description.rb', line 382 def inspect "#<Mongo::Server:Description:0x#{object_id} config=#{config} average_round_trip_time=#{average_round_trip_time}>" end

#is_server?(server) ⇒ true, false

Is this description from the given server.

756 757 758 # File 'lib/mongo/server/description.rb', line 756 def is_server?(server) address == server.address end

#last_write_date ⇒ Time

Get the lastWriteDate from the lastWrite subdocument in the config.

546 547 548 # File 'lib/mongo/server/description.rb', line 546 def last_write_date config[LAST_WRITE][LAST_WRITE_DATE] if config[LAST_WRITE] end

#lists_server?(server) ⇒ true, false

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

770 771 772 # File 'lib/mongo/server/description.rb', line 770 def lists_server?(server) servers.include?(server.address.to_s) end

#load_balancer? ⇒ true | false

Returns whether this server is a load balancer.

295 296 297 # File 'lib/mongo/server/description.rb', line 295 def load_balancer? @load_balancer end

#logical_session_timeout ⇒ Integer?

Get the logicalSessionTimeoutMinutes from the config.

558 559 560 # File 'lib/mongo/server/description.rb', line 558 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.

394 395 396 # File 'lib/mongo/server/description.rb', line 394 def max_bson_object_size config[MAX_BSON_OBJECT_SIZE] end

#max_message_size ⇒ Integer

Get the max message size for this server version.

406 407 408 # File 'lib/mongo/server/description.rb', line 406 def max_message_size config[MAX_MESSAGE_BYTES] end

#max_wire_version ⇒ Integer

Get the maximum wire version. Defaults to zero.

| 430 431 432 | # File 'lib/mongo/server/description.rb', line 430 def max_wire_version config[MAX_WIRE_VERSION] || 0 end | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#max_write_batch_size ⇒ Integer

Get the maximum batch size for writes.

| 418 419 420 | # File 'lib/mongo/server/description.rb', line 418 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.

457 458 459 # File 'lib/mongo/server/description.rb', line 457 def me config[ME] end

#me_mismatch? ⇒ true, false

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

806 807 808 # File 'lib/mongo/server/description.rb', line 806 def me_mismatch? !!(address.to_s.downcase != me.downcase if me) end

#min_wire_version ⇒ Integer

Get the minimum wire version. Defaults to zero.

| 442 443 444 | # File 'lib/mongo/server/description.rb', line 442 def min_wire_version config[MIN_WIRE_VERSION] || 0 end | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#mongocryptd? ⇒ true, false

Whether this description is from a mongocryptd server.

814 815 816 # File 'lib/mongo/server/description.rb', line 814 def mongocryptd? ok? && config['iscryptd'] == true end

#mongos? ⇒ true, false

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

570 571 572 # File 'lib/mongo/server/description.rb', line 570 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.

731 732 733 # File 'lib/mongo/server/description.rb', line 731 def ok? config[Operation::Result::OK] == 1 end

#op_time ⇒ BSON::Timestamp

opTime in lastWrite subdocument of the hello response.

823 824 825 826 827 # File 'lib/mongo/server/description.rb', line 823 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.

| 582 583 584 585 586 587 588 589 590 591 | # File 'lib/mongo/server/description.rb', line 582 def other? ok? && !!config['setName'] && ( config['hidden'] == true || !primary? && !secondary? && !arbiter? ) end | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

#passive? ⇒ true, false

Will return true if the server is passive.

601 602 603 # File 'lib/mongo/server/description.rb', line 601 def passive? ok? && !!config[PASSIVE] end

#passives ⇒ Array

Get a list of the passive servers in the cluster.

| 613 614 615 | # File 'lib/mongo/server/description.rb', line 613 def passives @passives ||= (config[PASSIVES] | | []).map { | s| s.downcase } end | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------- |

#primary? ⇒ true, false

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

| 637 638 639 640 641 | # File 'lib/mongo/server/description.rb', line 637 def primary? ok? && (config['ismaster'] == true || config['isWritablePrimary'] == true ) && !!config['setName'] end | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#primary_host ⇒ String | nil

Get the address of the primary host.

625 626 627 # File 'lib/mongo/server/description.rb', line 625 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.

| 783 784 785 | # File 'lib/mongo/server/description.rb', line 783 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.

652 653 654 # File 'lib/mongo/server/description.rb', line 652 def replica_set_name config[SET_NAME] end

#secondary? ⇒ true, false

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

676 677 678 679 680 # File 'lib/mongo/server/description.rb', line 676 def secondary? ok? && config['secondary'] == true && !!config['setName'] end

#server_connection_id ⇒ Object

851 852 853 # File 'lib/mongo/server/description.rb', line 851 def server_connection_id config['connectionId'] end

#server_type ⇒ Symbol

Returns the server type as a symbol.

690 691 692 693 694 695 696 697 698 699 700 # File 'lib/mongo/server/description.rb', line 690 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

#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.

883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 # File 'lib/mongo/server/description.rb', line 883 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? return true end required_wv >= min_wire_version && required_wv <= max_wire_version end

#servers ⇒ Array

Get a list of all servers known to the cluster.

664 665 666 # File 'lib/mongo/server/description.rb', line 664 def servers hosts + arbiters + passives end

#service_id ⇒ nil | Object

Returns The service id, if any.

858 859 860 # File 'lib/mongo/server/description.rb', line 858 def service_id config['serviceId'] end

#set_version ⇒ Integer

Get the setVersion from the config.

493 494 495 # File 'lib/mongo/server/description.rb', line 493 def set_version config[SET_VERSION] end

#standalone? ⇒ true, false

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

710 711 712 713 714 715 # File 'lib/mongo/server/description.rb', line 710 def standalone? ok? && config['msg'] != 'isdbgrid' && config['setName'].nil? && config['isreplicaset'] != true end

#tags ⇒ Hash

Get the tags configured for the server.

| 469 470 471 | # File 'lib/mongo/server/description.rb', line 469 def tags config[TAGS] || {} end | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |

#topology_version ⇒ TopologyVersion | nil

Returns The topology version.

498 499 500 501 502 503 504 # File 'lib/mongo/server/description.rb', line 498 def topology_version unless defined?(@topology_version) @topology_version = config['topologyVersion'] && TopologyVersion.new(config['topologyVersion']) end @topology_version end

#topology_version_gt?(other_desc) ⇒ true | false

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 whether topology version in this description is potentially newer than or equal to topology version in another description.

| 514 515 516 517 518 519 520 | # File 'lib/mongo/server/description.rb', line 514 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) ⇒ true | false

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 whether topology version in this description is potentially newer than topology version in another description.

| 530 531 532 533 534 535 536 | # File 'lib/mongo/server/description.rb', line 530 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? ⇒ true, false

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

| 725 726 727 728 | # File 'lib/mongo/server/description.rb', line 725 def unknown? return false if load_balancer? config.empty? || config.keys == %w(topologyVersion) | | !ok? end | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |

#wire_versions ⇒ Range

Get the range of supported wire versions for the server.

743 744 745 # File 'lib/mongo/server/description.rb', line 743 def wire_versions min_wire_version..max_wire_version end