Module: Mongo::Cluster::Topology

Extended by:
Topology
Included in:
Topology
Defined in:
build/ruby-driver-v2.19/lib/mongo/cluster/topology.rb,
build/ruby-driver-v2.19/lib/mongo/cluster/topology.rb,
build/ruby-driver-v2.19/lib/mongo/cluster/topology/base.rb,
build/ruby-driver-v2.19/lib/mongo/cluster/topology/single.rb,
build/ruby-driver-v2.19/lib/mongo/cluster/topology/sharded.rb,
build/ruby-driver-v2.19/lib/mongo/cluster/topology/unknown.rb,
build/ruby-driver-v2.19/lib/mongo/cluster/topology/load_balanced.rb,
build/ruby-driver-v2.19/lib/mongo/cluster/topology/no_replica_set_options.rb,
build/ruby-driver-v2.19/lib/mongo/cluster/topology/replica_set_no_primary.rb,
build/ruby-driver-v2.19/lib/mongo/cluster/topology/replica_set_with_primary.rb

Overview

Defines behavior for getting servers.

Topologies are associated with their clusters - for example, a ReplicaSet topology contains the replica set name. A topology object therefore cannot be used with multiple cluster objects.

At the same time, topology objects do not know anything about specific servers in a cluster, despite what their constructor may suggest. Which means, in particular, that topology change events require the application to maintain cluster references on its own if it wants to track server changes within a replica set.

Since:

  • 2.0.0

Defined Under Namespace

Modules: NoReplicaSetOptions Classes: Base, LoadBalanced, ReplicaSetNoPrimary, ReplicaSetWithPrimary, Sharded, Single, Unknown

Constant Summary collapse

OPTIONS =

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.

The various topologies for server selection.

Since:

  • 2.0.0

{
  direct: Single,
  load_balanced: LoadBalanced,
  replica_set: ReplicaSetNoPrimary,
  sharded: Sharded,
}.freeze

Instance Method Summary collapse

Instance Method Details

#initial(cluster, monitoring, options) ⇒ ReplicaSet, ...

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.

Get the initial cluster topology for the provided options.

Examples:

Get the initial cluster topology.

Topology.initial(topology: :replica_set)

Parameters:

  • cluster (Cluster) —

    The cluster.

  • monitoring (Monitoring) —

    The monitoring.

  • options (Hash) —

    The cluster options.

Options Hash (options):

  • :direct_connection (true | false) —

    Whether to connect directly to the specified seed, bypassing topology discovery. Exactly one seed must be provided.

  • :connect (Symbol) —

    Deprecated - use :direct_connection option instead of this option. The connection method to use. This forces the cluster to behave in the specified way instead of auto-discovering. One of :direct, :replica_set, :sharded, :load_balanced. If :connect is set to :load_balanced, the driver will behave as if the server is a load balancer even if it isn’t connected to a load balancer.

  • :load_balanced (true | false) —

    Whether to expect to connect to a load balancer.

  • :replica_set (Symbol) —

    The name of the replica set to connect to. Servers not in this replica set will be ignored.

Returns:

Since:

  • 2.0.0



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'build/ruby-driver-v2.19/lib/mongo/cluster/topology.rb', line 90

def initial(cluster, monitoring, options)
  connect = options[:connect]&.to_sym
  cls = if options[:direct_connection]
    if connect && connect != :direct
      raise ArgumentError, "Conflicting topology options: direct_connection=true and connect=#{connect}"
    end
    if options[:load_balanced]
      raise ArgumentError, "Conflicting topology options: direct_connection=true and load_balanced=true"
    end
    Single
  elsif options[:direct_connection] == false && connect && connect == :direct
    raise ArgumentError, "Conflicting topology options: direct_connection=false and connect=#{connect}"
  elsif connect && connect != :load_balanced
    if options[:load_balanced]
      raise ArgumentError, "Conflicting topology options: connect=#{options[:connect].inspect} and load_balanced=true"
    end
    OPTIONS.fetch(options[:connect].to_sym)
  elsif options.key?(:replica_set) || options.key?(:replica_set_name)
    if options[:load_balanced]
      raise ArgumentError, "Conflicting topology options: replica_set/replica_set_name and load_balanced=true"
    end
    ReplicaSetNoPrimary
  elsif options[:load_balanced] || connect == :load_balanced
    LoadBalanced
  else
    Unknown
  end
  # Options here are client/cluster/server options.
  # In particular the replica set name key is different for
  # topology.
  # If replica_set_name is given (as might be internally by driver),
  # use that key.
  # Otherwise (e.g. options passed down from client),
  # move replica_set to replica_set_name.
  if (cls <= ReplicaSetNoPrimary || cls == Single) && !options[:replica_set_name]
    options = options.dup
    options[:replica_set_name] = options.delete(:replica_set)
  end
  cls.new(options, monitoring, cluster)
end