mongo 1.12.5 → 2.0.0.beta

data/lib/mongo/client.rb

@@ -0,0 +1,233 @@
+# 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
+
+  # The client is the entry point to the driver and is the main object that
+  # will be interacted with.
+  #
+  # @since 2.0.0
+  class Client
+    extend Forwardable
+
+    # @return [ Mongo::Cluster ] cluster The cluster of servers for the client.
+    attr_reader :cluster
+
+    # @return [ Mongo::Database ] database The database the client is operating on.
+    attr_reader :database
+
+    # @return [ Hash ] options The configuration options.
+    attr_reader :options
+
+    # Delegate command execution to the current database.
+    def_delegators :@database, :command
+
+    # Determine if this client is equivalent to another object.
+    #
+    # @example Check client equality.
+    #   client == 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?(Client)
+      cluster == other.cluster && options == other.options
+    end
+    alias_method :eql?, :==
+
+    # Get a collection object for the provided collection name.
+    #
+    # @example Get the collection.
+    #   client[:users]
+    #
+    # @param [ String, Symbol ] collection_name The name of the collection.
+    # @param [ Hash ] options The options to the collection.
+    #
+    # @return [ Mongo::Collection ] The collection.
+    #
+    # @since 2.0.0
+    def [](collection_name, options = {})
+      database[collection_name, options]
+    end
+
+    # Get the hash value of the client.
+    #
+    # @example Get the client hash value.
+    #   client.hash
+    #
+    # @return [ Integer ] The client hash value.
+    #
+    # @since 2.0.0
+    def hash
+      [cluster, options].hash
+    end
+
+    # Instantiate a new driver client.
+    #
+    # @example Instantiate a single server or mongos client.
+    #   Mongo::Client.new([ '127.0.0.1:27017' ])
+    #
+    # @example Instantiate a client for a replica set.
+    #   Mongo::Client.new([ '127.0.0.1:27017', '127.0.0.1:27021' ])
+    #
+    # @param [ Array<String>, String ] addresses_or_uri The array of server addresses in the
+    #   form of host:port or a MongoDB URI connection string.
+    # @param [ Hash ] options The options to be used by the client.
+    #
+    # @option options [ Symbol ] :auth_mech The authentication mechanism to
+    #   use. One of :mongodb_cr, :mongodb_x509, :plain, :scram
+    # @option options [ String ] :auth_source The source to authenticate from.
+    # @option options [ Symbol ] :connect 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
+    # @option options [ String ] :database The database to connect to.
+    # @option options [ Hash ] :auth_mech_properties
+    # @option options [ Float ] :heartbeat_frequency The number of seconds for
+    #   the server monitor to refresh it's description via ismaster.
+    # @option options [ Integer ] :local_threshold
+    # @option options [ Integer ] :server_selection_timeout
+    # @option options [ String ] :password The user's password.
+    # @option options [ Integer ] :max_pool_size The maximum size of the
+    #   connection pool.
+    # @option options [ Integer ] :min_pool_size The minimum size of the
+    #   connection pool.
+    # @option options [ Float ] :wait_queue_timeout The time to wait, in
+    #   seconds, in the connection pool for a connection to be checked in.
+    # @option options [ Float ] :connect_timeout The timeout, in seconds, to
+    #   attempt a connection.
+    # @option options [ Symbol ] :read The read preference options. :mode can
+    #   be one of :secondary, :secondary_preferred, :primary,
+    #   :primary_preferred, :nearest.
+    # @option options [ Array<Hash, String> ] :roles The list of roles for the
+    #   user.
+    # @option options [ Symbol ] :replica_set The name of the replica set to
+    #   connect to. Servers not in this replica set will be ignored.
+    # @option options [ true, false ] :ssl Whether to use SSL.
+    # @option options [ Float ] :socket_timeout The timeout, in seconds, to
+    #   execute operations on a socket.
+    # @option options [ String ] :user The user name.
+    # @option options [ Hash ] :write The write concern options. Can be :w =>
+    #   Integer, :fsync => Boolean, :j => Boolean.
+    #
+    # @since 2.0.0
+    def initialize(addresses_or_uri, options = {})
+      if addresses_or_uri.is_a?(::String)
+        create_from_uri(addresses_or_uri, options)
+      else
+        create_from_addresses(addresses_or_uri, options)
+      end
+    end
+
+    # Get an inspection of the client as a string.
+    #
+    # @example Inspect the client.
+    #   client.inspect
+    #
+    # @return [ String ] The inspection string.
+    #
+    # @since 2.0.0
+    def inspect
+      "<Mongo::Client:0x#{object_id} cluster=#{cluster.addresses.join(', ')}>"
+    end
+
+    # Get the read preference from the options passed to the client.
+    #
+    # @example Get the read preference.
+    #   client.read_preference
+    #
+    # @return [ Object ] The appropriate read preference or primary if none
+    #   was provided to the client.
+    #
+    # @since 2.0.0
+    def read_preference
+      @read_preference ||= ServerSelector.get(options[:read] || {}, options)
+    end
+
+    # Use the database with the provided name. This will switch the current
+    # database the client is operating on.
+    #
+    # @example Use the provided database.
+    #   client.use(:users)
+    #
+    # @param [ String, Symbol ] name The name of the database to use.
+    #
+    # @return [ Mongo::Client ] The new client with new database.
+    #
+    # @since 2.0.0
+    def use(name)
+      with(database: name)
+    end
+
+    # Provides a new client with the passed options merged over the existing
+    # options of this client. Useful for one-offs to change specific options
+    # without altering the original client.
+    #
+    # @example Get a client with changed options.
+    #   client.with(:read => { :mode => :primary_preferred })
+    #
+    # @param [ Hash ] new_options The new options to use.
+    #
+    # @return [ Mongo::Client ] A new client instance.
+    #
+    # @since 2.0.0
+    def with(new_options = {})
+      clone.tap do |client|
+        client.options.update(new_options)
+        Database.create(client)
+        # We can't use the same cluster if authentication details have changed.
+        if new_options[:user] || new_options[:password]
+          Cluster.create(client)
+        end
+      end
+    end
+
+    # Get the write concern for this client. If no option was provided, then a
+    # default single server acknowledgement will be used.
+    #
+    # @example Get the client write concern.
+    #   client.write_concern
+    #
+    # @return [ Mongo::WriteConcern ] The write concern.
+    #
+    # @since 2.0.0
+    def write_concern
+      @write_concern ||= WriteConcern.get(options[:write])
+    end
+
+    private
+
+    def create_from_addresses(addresses, opts = {})
+      @options = Database::DEFAULT_OPTIONS.merge(opts).freeze
+      @cluster = Cluster.new(addresses, options)
+      @database = Database.new(self, options[:database], options)
+    end
+
+    def create_from_uri(connection_string, opts = {})
+      uri = URI.new(connection_string)
+      @options = Database::DEFAULT_OPTIONS.merge(uri.client_options.merge(opts)).freeze
+      @cluster = Cluster.new(uri.servers, options)
+      @database = Database.new(self, options[:database], options)
+    end
+
+    def initialize_copy(original)
+      @options = original.options.dup
+      @database = nil
+      @read_preference = nil
+      @write_concern = nil
+    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

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