Class: Moped::Cluster

Inherits:
Object
  • Object
show all
Defined in:
lib/moped/cluster.rb

Overview

The cluster represents a cluster of MongoDB server nodes, either a single node, a replica set, or a mongos server.

Since:

  • 1.0.0

Constant Summary collapse

DOWN_INTERVAL =

The default interval that a node would be flagged as “down”.

Since:

  • 2.0.0

30
REFRESH_INTERVAL =

The default interval that a node should be refreshed in.

Since:

  • 2.0.0

300
RETRY_INTERVAL =

The default time to wait to retry an operation.

Since:

  • 2.0.0

0.25

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(hosts, options) ⇒ Cluster

Initialize the new cluster.

Examples:

Initialize the cluster.

Cluster.new([ "localhost:27017" ], down_interval: 20)

Parameters:

  • options (Hash) —

    The cluster options.

Options Hash (options):

  • :down_interval (Object) —

    number of seconds to wait before attempting to reconnect to a down node. (30)

  • :refresh_interval (Object) —

    number of seconds to cache information about a node. (300)

  • :timeout (Integer) —

    The time in seconds to wait for an operation to timeout. (5)

Since:

  • 1.0.0



102
103
104
105
106
 
# File 'lib/moped/cluster.rb', line 102

def initialize(hosts, options)
  @seeds = hosts.map{ |host| Node.new(host, options) }
  @peers = []
  @options = options
end

Instance Attribute Details

#options ⇒ Hash

Returns The refresh options.

Returns:

  • (Hash) —

    The refresh options.



33
34
35
 
# File 'lib/moped/cluster.rb', line 33

def options
  @options
end

#peers ⇒ Array<Node>

Returns The node peers.

Returns:

  • (Array<Node>) —

    The node peers.



33
 
# File 'lib/moped/cluster.rb', line 33

attr_reader :options, :peers, :seeds

#seeds ⇒ Object

Since:

  • 1.0.0



33
 
# File 'lib/moped/cluster.rb', line 33

attr_reader :options, :peers, :seeds

Instance Method Details

#add_credential(db, username, password) ⇒ Boolean

Add a credential to the cluster

Examples:

Get the applied credentials.

node.credentials

Returns:

  • (Boolean) —

    true

Since:

  • 2.0.0



43
44
45
46
47
 
# File 'lib/moped/cluster.rb', line 43

def add_credential(db, username, password)
  @credentials ||= {}
  @credentials[db] = [ username, password ]
  apply_credentials
end

#delete_credential(db) ⇒ Boolean

Remove a credential from the cluster

Examples:

Get the applied credentials.

node.delete_credential(database_name)

Returns:

  • (Boolean) —

    true

Since:

  • 2.0.0



57
58
59
60
61
 
# File 'lib/moped/cluster.rb', line 57

def delete_credential(db)
  return true unless @credentials
  @credentials.delete(db)
  apply_credentials
end

#disconnect ⇒ true

Disconnects all nodes in the cluster. This should only be used in cases where you know you’re not going to use the cluster on the thread anymore and need to force the connections to close.

Returns:

  • (true) —

    True if the disconnect succeeded.

Since:

  • 1.2.0



70
71
72
 
# File 'lib/moped/cluster.rb', line 70

def disconnect
  nodes.each { |node| node.disconnect } and true
end

#down_interval ⇒ Integer

Get the interval at which a node should be flagged as down before retrying.

Examples:

Get the down interval, in seconds.

cluster.down_interval

Returns:

  • (Integer) —

    The down interval.

Since:

  • 1.2.7



83
84
85
 
# File 'lib/moped/cluster.rb', line 83

def down_interval
  @down_interval ||= options[:down_interval] || DOWN_INTERVAL
end

#inspect ⇒ String

Provide a pretty string for cluster inspection.

Examples:

Inspect the cluster.

cluster.inspect

Returns:

  • (String) —

    A nicely formatted string.

Since:

  • 1.0.0



116
117
118
 
# File 'lib/moped/cluster.rb', line 116

def inspect
  "#<#{self.class.name}:#{object_id} @seeds=#{seeds.inspect}>"
end

#max_retries ⇒ Integer

Get the number of times an operation should be retried before raising an error.

Examples:

Get the maximum retries.

cluster.max_retries

Returns:

  • (Integer) —

    The max retries.

Since:

  • 1.2.7



129
130
131
 
# File 'lib/moped/cluster.rb', line 129

def max_retries
  @max_retries ||= options[:max_retries] || seeds.size
end

#nodes ⇒ Array<Node>

Returns the list of available nodes, refreshing 1) any nodes which were down and ready to be checked again and 2) any nodes whose information is out of date. Arbiter nodes are not returned.

Examples:

Get the available nodes.

cluster.nodes

Returns:

  • (Array<Node>) —

    the list of available nodes.

Since:

  • 1.0.0



143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/moped/cluster.rb', line 143

def nodes
  # Find the nodes that were down but are ready to be refreshed, or those
  # with stale connection information.
  needs_refresh, available = seeds.partition do |node|
    refreshable?(node)
  end

  # Refresh those nodes.
  available.concat(refresh(needs_refresh))

  # Now return all the nodes that are available and participating in the
  # replica set.
  available.reject{ |node| node.down? }
end

#refresh(nodes_to_refresh = seeds) ⇒ Array<Node>

Refreshes information for each of the nodes provided. The node list defaults to the list of all known nodes.

If a node is successfully refreshed, any newly discovered peers will also be refreshed.

Examples:

Refresh the nodes.

cluster.refresh

Parameters:

  • nodes_to_refresh (Array<Node>) (defaults to: seeds) —

    The nodes to refresh.

Returns:

  • (Array<Node>) —

    the available nodes

Since:

  • 1.0.0



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/moped/cluster.rb', line 172

def refresh(nodes_to_refresh = seeds)
  refreshed_nodes = []
  seen = {}
  # Set up a recursive lambda function for refreshing a node and it's peers.
  refresh_node = ->(node) do
    unless node.address.resolved
      begin
        node.refresh
      rescue Errors::ConnectionFailure
      end
    end
    unless seen[node] || !node.address.resolved
      seen[node] = true
      # Add the node to the global list of known nodes.
      seeds.push(node) unless seeds.include?(node)
      begin
        node.refresh
        # This node is good, so add it to the list of nodes to return.
        refreshed_nodes.push(node) unless refreshed_nodes.include?(node)
        # Now refresh any newly discovered peer nodes - this will also
        # remove nodes that are not included in the peer list.
        refresh_peers(node, &refresh_node)
      rescue Errors::ConnectionFailure
        # We couldn't connect to the node.
      end
    end
  end

  nodes_to_refresh.each(&refresh_node)
  refreshed_nodes
end

#refresh_interval ⇒ Integer

Get the interval in which the node list should be refreshed.

Examples:

Get the refresh interval, in seconds.

cluster.refresh_interval

Returns:

  • (Integer) —

    The refresh interval.

Since:

  • 1.2.7



212
213
214
 
# File 'lib/moped/cluster.rb', line 212

def refresh_interval
  @refresh_interval ||= options[:refresh_interval] || REFRESH_INTERVAL
end

#retry_interval ⇒ Integer

Get the operation retry interval - the time to wait before retrying a single operation.

Examples:

Get the retry interval, in seconds.

cluster.retry_interval

Returns:

  • (Integer) —

    The retry interval.

Since:

  • 1.2.7



225
226
227
 
# File 'lib/moped/cluster.rb', line 225

def retry_interval
  @retry_interval ||= options[:retry_interval] || RETRY_INTERVAL
end

#with_primary(&block) ⇒ Object

Yields the replica set’s primary node to the provided block. This method will retry the block in case of connection errors or replica set reconfiguration.

Examples:

Yield the primary to the block.

cluster.with_primary do |node|
  # ...
end

Parameters:

  • retries (Integer) —

    The number of times to retry.

Returns:

  • (Object) —

    The result of the yield.

Raises:

Since:

  • 1.0.0



245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/moped/cluster.rb', line 245

def with_primary(&block)
  if node = nodes.find(&:primary?)
    begin
      node.ensure_primary do
        return yield(node)
      end
    rescue Errors::ConnectionFailure, Errors::ReplicaSetReconfigured
    end
  end
  raise Errors::ConnectionFailure, "Could not connect to a primary node for replica set #{inspect}"
end

#with_secondary(&block) ⇒ Object

Yields a secondary node if available, otherwise the primary node. This method will retry the block in case of connection errors.

Examples:

Yield the secondary to the block.

cluster.with_secondary do |node|
  # ...
end

Parameters:

  • retries (Integer) —

    The number of times to retry.

Returns:

  • (Object) —

    The result of the yield.

Raises:

Since:

  • 1.0.0



272
273
274
275
276
277
278
279
280
281
282
 
# File 'lib/moped/cluster.rb', line 272

def with_secondary(&block)
  available_nodes = available_secondary_nodes
  while node = available_nodes.shift
    begin
      return yield(node)
    rescue Errors::ConnectionFailure, Errors::ReplicaSetReconfigured => e
      next
    end
  end
  raise Errors::ConnectionFailure, "Could not connect to a secondary node for replica set #{inspect}"
end