mongo 1.12.5 → 2.0.0

data/lib/mongo/cluster/topology/sharded.rb

@@ -0,0 +1,132 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+  class Cluster
+    module Topology
+
+      # Defines behaviour for when a cluster is in sharded topology.
+      #
+      # @since 2.0.0
+      class Sharded
+
+        # The display name for the topology.
+        #
+        # @since 2.0.0
+        NAME = 'Sharded'.freeze
+
+        # Get the display name.
+        #
+        # @example Get the display name.
+        #   Sharded.display_name
+        #
+        # @return [ String ] The display name.
+        #
+        # @since 2.0.0
+        def display_name
+          NAME
+        end
+
+        # Elect a primary server within this topology.
+        #
+        # @example Elect a primary server.
+        #   topology.elect_primary(description, servers)
+        #
+        # @param [ Server::Description ] description The description of the
+        #   elected primary.
+        # @param [ Array<Server> ] servers The list of known servers to the
+        #   cluster.
+        #
+        # @return [ Sharded ] The topology.
+        def elect_primary(description, servers); self; end
+
+        # Initialize the topology with the options.
+        #
+        # @example Initialize the topology.
+        #   Sharded.new(options)
+        #
+        # @param [ Hash ] options The options.
+        #
+        # @since 2.0.0
+        def initialize(options)
+          @options = options
+        end
+
+        # A sharded topology is not a replica set.
+        #
+        # @example Is the topology a replica set?
+        #   Sharded.replica_set?
+        #
+        # @return [ false ] Always false.
+        #
+        # @since 2.0.0
+        def replica_set?; false; end
+
+        # Sharded topologies have no replica set name.
+        #
+        # @example Get the replica set name.
+        #   sharded.replica_set_name
+        #
+        # @return [ nil ] Always nil.
+        #
+        # @since 2.0.0
+        def replica_set_name; nil; end
+
+        # Select appropriate servers for this topology.
+        #
+        # @example Select the servers.
+        #   Sharded.servers(servers)
+        #
+        # @param [ Array<Server> ] servers The known servers.
+        #
+        # @return [ Array<Server> ] The mongos servers.
+        #
+        # @since 2.0.0
+        def servers(servers)
+          servers.select{ |server| server.mongos? }
+        end
+
+        # A sharded topology is sharded.
+        #
+        # @example Is the topology sharded?
+        #   Sharded.sharded?
+        #
+        # @return [ true ] Always true.
+        #
+        # @since 2.0.0
+        def sharded?; true; end
+
+        # A sharded topology is not standalone.
+        #
+        # @example Is the topology standalone?
+        #   Sharded.standalone?
+        #
+        # @return [ false ] Always false.
+        #
+        # @since 2.0.0
+        def standalone?; false; end
+
+        # A sharded topology is not unknown.
+        #
+        # @example Is the topology unknown?
+        #   Sharded.unknown?
+        #
+        # @return [ false ] Always false.
+        #
+        # @since 2.0.0
+        def unknown?; false; end
+      end
+    end
+  end
+end

data/lib/mongo/cluster/topology/standalone.rb

@@ -0,0 +1,132 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+  class Cluster
+    module Topology
+
+      # Defines behaviour for when a cluster is in standalone topology.
+      #
+      # @since 2.0.0
+      class Standalone
+
+        # The display name for the topology.
+        #
+        # @since 2.0.0
+        NAME = 'Standalone'.freeze
+
+        # Get the display name.
+        #
+        # @example Get the display name.
+        #   Standalone.display_name
+        #
+        # @return [ String ] The display name.
+        #
+        # @since 2.0.0
+        def display_name
+          NAME
+        end
+
+        # Elect a primary server within this topology.
+        #
+        # @example Elect a primary server.
+        #   topology.elect_primary(description, servers)
+        #
+        # @param [ Server::Description ] description The description of the
+        #   elected primary.
+        # @param [ Array<Server> ] servers The list of known servers to the
+        #   cluster.
+        #
+        # @return [ Standalone ] The topology.
+        def elect_primary(description, servers); self; end
+
+        # Initialize the topology with the options.
+        #
+        # @example Initialize the topology.
+        #   Standalone.new(options)
+        #
+        # @param [ Hash ] options The options.
+        #
+        # @since 2.0.0
+        def initialize(options)
+          @options = options
+        end
+
+        # A standalone topology is not a replica set.
+        #
+        # @example Is the topology a replica set?
+        #   Sharded.replica_set?
+        #
+        # @return [ false ] Always false.
+        #
+        # @since 2.0.0
+        def replica_set?; false; end
+
+        # Standalone topologies have no replica set name.
+        #
+        # @example Get the replica set name.
+        #   standalone.replica_set_name
+        #
+        # @return [ nil ] Always nil.
+        #
+        # @since 2.0.0
+        def replica_set_name; nil; end
+
+        # Select appropriate servers for this topology.
+        #
+        # @example Select the servers.
+        #   Standalone.servers(servers, 'test')
+        #
+        # @param [ Array<Server> ] servers The known servers.
+        #
+        # @return [ Array<Server> ] The standalone servers.
+        #
+        # @since 2.0.0
+        def servers(servers, name = nil)
+          [ servers.detect{ |server| server.standalone? } ]
+        end
+
+        # A standalone topology is not sharded.
+        #
+        # @example Is the topology sharded?
+        #   Standalone.sharded?
+        #
+        # @return [ false ] Always false.
+        #
+        # @since 2.0.0
+        def sharded?; false; end
+
+        # A standalone topology is standalone.
+        #
+        # @example Is the topology standalone?
+        #   Standalone.standalone?
+        #
+        # @return [ true ] Always true.
+        #
+        # @since 2.0.0
+        def standalone?; true; end
+
+        # An standalone topology is not unknown.
+        #
+        # @example Is the topology unknown?
+        #   Standalone.unknown?
+        #
+        # @return [ false ] Always false.
+        #
+        # @since 2.0.0
+        def unknown?; false; end
+      end
+    end
+  end
+end

data/lib/mongo/cluster/topology/unknown.rb

@@ -0,0 +1,155 @@
+# Copyright (C) 2015 MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+  class Cluster
+    module Topology
+
+      # Defines behaviour for when a cluster is in an unknown state.
+      #
+      # @since 2.0.0
+      class Unknown
+        include Loggable
+
+        # The display name for the topology.
+        #
+        # @since 2.0.0
+        NAME = 'Unknown'.freeze
+
+        # @return [ Hash ] options The options.
+        attr_reader :options
+
+        # Get the display name.
+        #
+        # @example Get the display name.
+        #   Unknown.display_name
+        #
+        # @return [ String ] The display name.
+        #
+        # @since 2.0.0
+        def display_name
+          NAME
+        end
+
+        # Elect a primary server within this topology.
+        #
+        # @example Elect a primary server.
+        #   topology.elect_primary(description, servers)
+        #
+        # @param [ Server::Description ] description The description of the
+        #   elected primary.
+        # @param [ Array<Server> ] servers The list of known servers to the
+        #   cluster.
+        #
+        # @return [ Sharded, ReplicaSet ] The new topology.
+        def elect_primary(description, servers)
+          if description.mongos?
+            log_debug([ "Mongos #{description.address.to_s} discovered." ])
+            Sharded.new(options)
+          else
+            initialize_replica_set(description, servers)
+          end
+        end
+
+        # Initialize the topology with the options.
+        #
+        # @example Initialize the topology.
+        #   Unknown.new(options)
+        #
+        # @param [ Hash ] options The options.
+        #
+        # @since 2.0.0
+        def initialize(options)
+          @options = options
+        end
+
+        # An unknown topology is not a replica set.
+        #
+        # @example Is the topology a replica set?
+        #   Unknown.replica_set?
+        #
+        # @return [ false ] Always false.
+        #
+        # @since 2.0.0
+        def replica_set?; false; end
+
+        # Unknown topologies have no replica set name.
+        #
+        # @example Get the replica set name.
+        #   unknown.replica_set_name
+        #
+        # @return [ nil ] Always nil.
+        #
+        # @since 2.0.0
+        def replica_set_name; nil; end
+
+        # Select appropriate servers for this topology.
+        #
+        # @example Select the servers.
+        #   Unknown.servers(servers)
+        #
+        # @param [ Array<Server> ] servers The known servers.
+        #
+        # @raise [ Unknown ] Cannot select servers when the topology is
+        #   unknown.
+        #
+        # @since 2.0.0
+        def servers(servers)
+        end
+
+        # An unknown topology is not sharded.
+        #
+        # @example Is the topology sharded?
+        #   Unknown.sharded?
+        #
+        # @return [ false ] Always false.
+        #
+        # @since 2.0.0
+        def sharded?; false; end
+
+        # An unknown topology is not standalone.
+        #
+        # @example Is the topology standalone?
+        #   Unknown.standalone?
+        #
+        # @return [ true ] Always false.
+        #
+        # @since 2.0.0
+        def standalone?; false; end
+
+        # An unknown topology is unknown.
+        #
+        # @example Is the topology unknown?
+        #   Unknown.unknown?
+        #
+        # @return [ true ] Always true.
+        #
+        # @since 2.0.0
+        def unknown?; true; end
+
+        private
+
+        def initialize_replica_set(description, servers)
+          log_debug([ "Server #{description.address.to_s} discovered as primary." ])
+          servers.each do |server|
+            if server.standalone? && server.address != description.address
+              server.description.unknown!
+            end
+          end
+          ReplicaSet.new(options.merge(:replica_set => description.replica_set_name))
+        end
+      end
+    end
+  end
+end

data/lib/mongo/cluster/topology.rb

@@ -0,0 +1,60 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'mongo/cluster/topology/replica_set'
+require 'mongo/cluster/topology/sharded'
+require 'mongo/cluster/topology/standalone'
+require 'mongo/cluster/topology/unknown'
+
+module Mongo
+  class Cluster
+
+    # Defines behaviour for getting servers.
+    #
+    # @since 2.0.0
+    module Topology
+      extend self
+
+      # The 2 various topologies for server selection.
+      #
+      # @since 2.0.0
+      OPTIONS = {
+        replica_set: ReplicaSet,
+        sharded: Sharded,
+        direct: Standalone
+      }
+
+      # Get the initial cluster topology for the provided options.
+      #
+      # @example Get the initial cluster topology.
+      #   Topology.initial(topology: :replica_set)
+      #
+      # @param [ Hash ] options The cluster options.
+      #
+      # @return [ ReplicaSet, Sharded, Standalone ] The topology.
+      #
+      # @since 2.0.0
+      def initial(seeds, options)
+        if options.has_key?(:connect)
+          return OPTIONS.fetch(options[:connect]).new(options)
+        end
+        if options.has_key?(:replica_set)
+          ReplicaSet.new(options)
+        else
+          seeds.size > 1 ? Unknown.new(options) : Standalone.new(options)
+        end
+      end
+    end
+  end
+end

data/lib/mongo/cluster.rb

@@ -0,0 +1,203 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'mongo/cluster/topology'
+
+module Mongo
+
+  # Represents a group of servers on the server side, either as a single server, a
+  # replica set, or a single or multiple mongos.
+  #
+  # @since 2.0.0
+  class Cluster
+    extend Forwardable
+    include Event::Subscriber
+    include Loggable
+
+    # @return [ Array<String> ] The provided seed addresses.
+    attr_reader :addresses
+
+    # @return [ Hash ] The options hash.
+    attr_reader :options
+
+    # @return [ Object ] The cluster topology.
+    attr_reader :topology
+
+    def_delegators :topology, :replica_set?, :replica_set_name, :sharded?, :standalone?, :unknown?
+
+    # Determine if this cluster of servers is equal to another object. Checks the
+    # servers currently in the cluster, not what was configured.
+    #
+    # @example Is the cluster equal to the object?
+    #   cluster == other
+    #
+    # @param [ Object ] other The object to compare to.
+    #
+    # @return [ true, false ] If the objects are equal.
+    #
+    # @since 2.0.0
+    def ==(other)
+      return false unless other.is_a?(Cluster)
+      addresses == other.addresses && options == other.options
+    end
+
+    # Add a server to the cluster with the provided address. Useful in
+    # auto-discovery of new servers when an existing server executes an ismaster
+    # and potentially non-configured servers were included.
+    #
+    # @example Add the server for the address to the cluster.
+    #   cluster.add('127.0.0.1:27018')
+    #
+    # @param [ String ] host The address of the server to add.
+    #
+    # @return [ Server ] The newly added server, if not present already.
+    #
+    # @since 2.0.0
+    def add(host)
+      address = Address.new(host)
+      unless addresses.include?(address)
+        log_debug([ "Adding #{address.to_s} to the cluster." ])
+        addresses.push(address)
+        server = Server.new(address, event_listeners, options)
+        @servers.push(server)
+        server
+      end
+    end
+
+    # Instantiate the new cluster.
+    #
+    # @example Instantiate the cluster.
+    #   Mongo::Cluster.new(["127.0.0.1:27017"])
+    #
+    # @param [ Array<String> ] seeds The addresses of the configured servers.
+    # @param [ Hash ] options The options.
+    #
+    # @since 2.0.0
+    def initialize(seeds, options = {})
+      @addresses = []
+      @servers = []
+      @event_listeners = Event::Listeners.new
+      @options = options.freeze
+      @topology = Topology.initial(seeds, options)
+
+      subscribe_to(Event::SERVER_ADDED, Event::ServerAdded.new(self))
+      subscribe_to(Event::SERVER_REMOVED, Event::ServerRemoved.new(self))
+      subscribe_to(Event::PRIMARY_ELECTED, Event::PrimaryElected.new(self))
+
+      seeds.each{ |seed| add(seed) }
+    end
+
+    # Get the nicer formatted string for use in inspection.
+    #
+    # @example Inspect the cluster.
+    #   cluster.inspect
+    #
+    # @return [ String ] The cluster inspection.
+    #
+    # @since 2.0.0
+    def inspect
+      "#<Mongo::Cluster:0x#{object_id} servers=#{servers} topology=#{topology.display_name}>"
+    end
+
+    # Get the next primary server we can send an operation to.
+    #
+    # @example Get the next primary server.
+    #   cluster.next_primary
+    #
+    # @return [ Mongo::Server ] A primary server.
+    #
+    # @since 2.0.0
+    def next_primary
+      ServerSelector.get({ mode: :primary }, options).select_server(self)
+    end
+
+    # Elect a primary server from the description that has just changed to a
+    # primary.
+    #
+    # @example Elect a primary server.
+    #   cluster.elect_primary!(description)
+    #
+    # @param [ Server::Description ] description The newly elected primary.
+    #
+    # @return [ Topology ] The cluster topology.
+    #
+    # @since 2.0.0
+    def elect_primary!(description)
+      @topology = topology.elect_primary(description, @servers)
+    end
+
+    # Removed the server from the cluster for the provided address, if it
+    # exists.
+    #
+    # @example Remove the server from the cluster.
+    #   server.remove('127.0.0.1:27017')
+    #
+    # @param [ String ] host The host/port or socket address.
+    #
+    # @since 2.0.0
+    def remove(host)
+      log_debug([ "#{host} being removed from the cluster." ])
+      address = Address.new(host)
+      removed_servers = @servers.reject!{ |server| server.address == address }
+      removed_servers.each{ |server| server.disconnect! } if removed_servers
+      addresses.reject!{ |addr| addr == address }
+    end
+
+    # Force a scan of all known servers in the cluster.
+    #
+    # @example Force a full cluster scan.
+    #   cluster.scan!
+    #
+    # @note This operation is done synchronously. If servers in the cluster are
+    #   down or slow to respond this can potentially be a slow operation.
+    #
+    # @return [ true ] Always true.
+    #
+    # @since 2.0.0
+    def scan!
+      @servers.each{ |server| server.scan! } and true
+    end
+
+    # Get a list of server candidates from the cluster that can have operations
+    # executed on them.
+    #
+    # @example Get the server candidates for an operation.
+    #   cluster.servers
+    #
+    # @return [ Array<Server> ] The candidate servers.
+    #
+    # @since 2.0.0
+    def servers
+      topology.servers(@servers)
+    end
+
+    # Create a cluster for the provided client, for use when we don't want the
+    # client's original cluster instance to be the same.
+    #
+    # @api private
+    #
+    # @example Create a cluster for the client.
+    #   Cluster.create(client)
+    #
+    # @param [ Client ] client The client to create on.
+    #
+    # @return [ Cluster ] The cluster.
+    #
+    # @since 2.0.0
+    def self.create(client)
+      cluster = Cluster.new(client.cluster.addresses.map(&:to_s), client.options)
+      client.instance_variable_set(:@cluster, cluster)
+    end
+  end
+end