net-ssh-multi 1.0.0

data/lib/net/ssh/multi/dynamic_server.rb

@@ -0,0 +1,71 @@
+require 'net/ssh/multi/server'
+
+module Net; module SSH; module Multi
+
+  # Represents a lazily evaluated collection of servers. This will usually be
+  # created via Net::SSH::Multi::Session#use(&block), and is useful for creating
+  # server definitions where the name or address of the servers are not known
+  # until run-time.
+  #
+  #   session.use { lookup_ip_address_of_server }
+  #
+  # This prevents +lookup_ip_address_of_server+ from being invoked unless the
+  # server is actually needed, at which point it is invoked and the result
+  # cached.
+  #
+  # The callback should return either +nil+ (in which case no new servers are
+  # instantiated), a String (representing a connection specification), an
+  # array of Strings, or an array of Net::SSH::Multi::Server instances.
+  class DynamicServer
+    # The Net::SSH::Multi::Session instance that owns this dynamic server record.
+    attr_reader :master
+
+    # The Proc object to call to evaluate the server(s)
+    attr_reader :callback
+
+    # The hash of options that will be used to initialize the server records.
+    attr_reader :options
+
+    # Create a new DynamicServer record, owned by the given Net::SSH::Multi::Session
+    # +master+, with the given hash of +options+, and using the given Proc +callback+
+    # to lazily evaluate the actual server instances.
+    def initialize(master, options, callback)
+      @master, @options, @callback = master, options, callback
+      @servers = nil
+    end
+
+    # Returns the value for the given +key+ in the :properties hash of the
+    # +options+. If no :properties hash exists in +options+, this returns +nil+.
+    def [](key)
+      (options[:properties] ||= {})[key]
+    end
+
+    # Sets the given key/value pair in the +:properties+ key in the options
+    # hash. If the options hash has no :properties key, it will be created.
+    def []=(key, value)
+      (options[:properties] ||= {})[key] = value
+    end
+
+    # Iterates over every instantiated server record in this dynamic server.
+    # If the servers have not yet been instantiated, this does nothing (e.g.,
+    # it does _not_ automatically invoke #evaluate!).
+    def each
+      (@servers || []).each { |server| yield server }
+    end
+
+    # Evaluates the callback and instantiates the servers, memoizing the result.
+    # Subsequent calls to #evaluate! will simply return the cached list of
+    # servers.
+    def evaluate!
+      @servers ||= Array(callback[options]).map do |server|
+          case server
+          when String then Net::SSH::Multi::Server.new(master, server, options)
+          else server
+          end
+        end
+    end
+
+    alias to_ary evaluate!
+  end
+
+end; end; end

data/lib/net/ssh/multi/pending_connection.rb

@@ -0,0 +1,112 @@
+require 'net/ssh/multi/channel_proxy'
+
+module Net; module SSH; module Multi
+
+  # A PendingConnection instance mimics a Net::SSH::Connection::Session instance,
+  # without actually being an open connection to a server. It is used by
+  # Net::SSH::Multi::Session when a concurrent connection limit is in effect,
+  # so that a server can hang on to a "connection" that isn't really a connection.
+  #
+  # Any requests against this connection (like #open_channel or #send_global_request)
+  # are not actually sent, but are added to a list of recordings. When the real
+  # session is opened and replaces this pending connection, all recorded actions
+  # will be replayed against that session.
+  #
+  # You'll never need to initialize one of these directly, and (if all goes well!)
+  # should never even notice that one of these is in use. Net::SSH::Multi::Session
+  # will instantiate these as needed, and only when there is a concurrent
+  # connection limit.
+  class PendingConnection
+    # Represents a #open_channel action.
+    class ChannelOpenRecording #:nodoc:
+      attr_reader :type, :extras, :channel
+
+      def initialize(type, extras, channel)
+        @type, @extras, @channel = type, extras, channel
+      end
+
+      def replay_on(session)
+        real_channel = session.open_channel(type, *extras, &channel.on_confirm)
+        channel.delegate_to(real_channel)
+      end
+    end
+
+    # Represents a #send_global_request action.
+    class SendGlobalRequestRecording #:nodoc:
+      attr_reader :type, :extra, :callback
+
+      def initialize(type, extra, callback)
+        @type, @extra, @callback = type, extra, callback
+      end
+
+      def replay_on(session)
+        session.send_global_request(type, *extra, &callback)
+      end
+    end
+
+    # The Net::SSH::Multi::Server object that "owns" this pending connection.
+    attr_reader :server
+
+    # Instantiates a new pending connection for the given Net::SSH::Multi::Server
+    # object.
+    def initialize(server)
+      @server = server
+      @recordings = []
+    end
+
+    # Instructs the pending session to replay all of its recordings against the
+    # given +session+, and to then replace itself with the given session.
+    def replace_with(session)
+      @recordings.each { |recording| recording.replay_on(session) }
+      @server.replace_session(session)
+    end
+
+    # Records that a channel open request has been made, and returns a new
+    # Net::SSH::Multi::ChannelProxy object to represent the (as yet unopened)
+    # channel.
+    def open_channel(type="session", *extras, &on_confirm)
+      channel = ChannelProxy.new(&on_confirm)
+      @recordings << ChannelOpenRecording.new(type, extras, channel)
+      return channel
+    end
+
+    # Records that a global request has been made. The request is not actually
+    # sent, and won't be until #replace_with is called.
+    def send_global_request(type, *extra, &callback)
+      @recordings << SendGlobalRequestRecording.new(type, extra, callback)
+      self
+    end
+
+    # Always returns +true+, so that the pending connection looks active until
+    # it can be truly opened and replaced with a real connection.
+    def busy?(include_invisible=false)
+      true
+    end
+
+    # Does nothing, except to make a pending connection quack like a real connection.
+    def close
+      self
+    end
+
+    # Returns an empty array, since a pending connection cannot have any real channels.
+    def channels
+      []
+    end
+
+    # Returns +true+, and does nothing else.
+    def preprocess
+      true
+    end
+
+    # Returns +true+, and does nothing else.
+    def postprocess(readers, writers)
+      true
+    end
+
+    # Returns an empty hash, since a pending connection has no real listeners.
+    def listeners
+      {}
+    end
+  end
+
+end; end; end

data/lib/net/ssh/multi/server.rb

@@ -0,0 +1,229 @@
+require 'net/ssh'
+
+module Net; module SSH; module Multi
+  # Encapsulates the connection information for a single remote server, as well
+  # as the Net::SSH session corresponding to that information. You'll rarely
+  # need to instantiate one of these directly: instead, you should use
+  # Net::SSH::Multi::Session#use.
+  class Server
+    include Comparable
+
+    # The Net::SSH::Multi::Session instance that manages this server instance.
+    attr_reader :master
+
+    # The host name (or IP address) of the server to connect to.
+    attr_reader :host
+
+    # The user name to use when logging into the server.
+    attr_reader :user
+
+    # The Hash of additional options to pass to Net::SSH when connecting
+    # (including things like :password, and so forth).
+    attr_reader :options
+
+    # The Net::SSH::Gateway instance to use to establish the connection. Will
+    # be +nil+ if the connection should be established without a gateway.
+    attr_reader :gateway
+
+    # Creates a new Server instance with the given connection information. The
+    # +master+ argument must be a reference to the Net::SSH::Multi::Session
+    # instance that will manage this server reference. The +options+ hash must
+    # conform to the options described for Net::SSH::start, with two additions:
+    #
+    # * :via => a Net::SSH::Gateway instance to use when establishing a
+    #   connection to this server.
+    # * :user => the name of the user to use when logging into this server.
+    #
+    # The +host+ argument may include the username and port number, in which
+    # case those values take precedence over similar values given in the +options+:
+    #
+    #   server = Net::SSH::Multi::Server.new(session, 'user@host:1234')
+    #   puts server.user #-> user
+    #   puts server.port #-> 1234
+    def initialize(master, host, options={})
+      @master = master
+      @options = options.dup
+
+      @user, @host, port = host.match(/^(?:([^;,:=]+)@|)(.*?)(?::(\d+)|)$/)[1,3]
+
+      user_opt, port_opt = @options.delete(:user), @options.delete(:port)
+
+      @user = @user || user_opt || master.default_user
+      port ||= port_opt
+
+      @options[:port] = port.to_i if port
+
+      @gateway = @options.delete(:via)
+      @failed = false
+    end
+
+    # Returns the value of the server property with the given +key+. Server
+    # properties are described via the +:properties+ key in the options hash
+    # when defining the Server.
+    def [](key)
+      (options[:properties] || {})[key]
+    end
+
+    # Sets the given key/value pair in the +:properties+ key in the options
+    # hash. If the options hash has no :properties key, it will be created.
+    def []=(key, value)
+      (options[:properties] ||= {})[key] = value
+    end
+
+    # Returns the port number to use for this connection.
+    def port
+      options[:port] || 22
+    end
+
+    # Gives server definitions a sort order, and allows comparison.
+    def <=>(server)
+      [host, port, user] <=> [server.host, server.port, server.user]
+    end
+
+    alias :eql? :==
+
+    # Generates a +Fixnum+ hash value for this object. This function has the
+    # property that +a.eql?(b)+ implies +a.hash == b.hash+. The
+    # hash value is used by class +Hash+. Any hash value that exceeds the
+    # capacity of a +Fixnum+ will be truncated before being used.
+    def hash
+      @hash ||= [host, user, port].hash
+    end
+
+    # Returns a human-readable representation of this server instance.
+    def to_s
+      @to_s ||= begin
+        s = "#{user}@#{host}"
+        s << ":#{options[:port]}" if options[:port]
+        s
+      end
+    end
+
+    # Returns a human-readable representation of this server instance.
+    def inspect
+      @inspect ||= "#<%s:0x%x %s>" % [self.class.name, object_id, to_s]
+    end
+
+    # Returns +true+ if this server has ever failed a connection attempt.
+    def failed?
+      @failed
+    end
+
+    # Indicates (by default) that this server has just failed a connection
+    # attempt. If +flag+ is false, this can be used to reset the failed flag
+    # so that a retry may be attempted.
+    def fail!(flag=true)
+      @failed = flag
+    end
+
+    # Returns the Net::SSH session object for this server. If +require_session+
+    # is false and the session has not previously been created, this will
+    # return +nil+. If +require_session+ is true, the session will be instantiated
+    # if it has not already been instantiated, via the +gateway+ if one is
+    # given, or directly (via Net::SSH::start) otherwise.
+    #
+    #   if server.session.nil?
+    #     puts "connecting..."
+    #     server.session(true)
+    #   end
+    #
+    # Note that the sessions returned by this are "enhanced" slightly, to make
+    # them easier to deal with in a multi-session environment: they have a
+    # :server property automatically set on them, that refers to this object
+    # (the Server instance that spawned them).
+    #
+    #   assert_equal server, server.session[:server]
+    def session(require_session=false)
+      return @session if @session || !require_session
+      @session ||= master.next_session(self)
+    end
+
+    # Returns +true+ if the session has been opened, and the session is currently
+    # busy (as defined by Net::SSH::Connection::Session#busy?).
+    def busy?(include_invisible=false)
+      session && session.busy?(include_invisible)
+    end
+
+    # Closes this server's session. If the session has not yet been opened,
+    # this does nothing.
+    def close
+      session.close if session
+    ensure
+      master.server_closed(self) if session
+      @session = nil
+    end
+
+    public # but not published, e.g., these are used internally only...
+
+      # Indicate that the session currently in use by this server instance
+      # should be replaced by the given +session+ argument. This is used when
+      # a pending session has been "realized". Note that this does not
+      # actually replace the session--see #update_session! for that.
+      def replace_session(session) #:nodoc:
+        @ready_session = session
+      end
+
+      # If a new session has been made ready (see #replace_session), this
+      # will replace the current session with the "ready" session. This
+      # method is called from the event loop to ensure that sessions are
+      # swapped in at the appropriate point (instead of in the middle of an
+      # event poll).
+      def update_session! #:nodoc:
+        if @ready_session
+          @session, @ready_session = @ready_session, nil
+        end
+      end
+
+      # Returns a new session object based on this server's connection
+      # criteria. Note that this will not associate the session with the
+      # server, and should not be called directly; it is called internally
+      # from Net::SSH::Multi::Session when a new session is required.
+      def new_session #:nodoc:
+        session = if gateway
+          gateway.ssh(host, user, options)
+        else
+          Net::SSH.start(host, user, options)
+        end
+
+        session[:server] = self
+        session
+      rescue Net::SSH::AuthenticationFailed => error
+        raise Net::SSH::AuthenticationFailed.new("#{error.message}@#{host}")
+      end
+
+      # Closes all open channels on this server's session. If the session has
+      # not yet been opened, this does nothing.
+      def close_channels #:nodoc:
+        session.channels.each { |id, channel| channel.close } if session
+      end
+
+      # Runs the session's preprocess action, if the session has been opened.
+      def preprocess #:nodoc:
+        session.preprocess if session
+      end
+
+      # Returns all registered readers on the session, or an empty array if the
+      # session is not open.
+      def readers #:nodoc:
+        return [] unless session
+        session.listeners.keys.reject { |io| io.closed? }
+      end
+
+      # Returns all registered and pending writers on the session, or an empty
+      # array if the session is not open.
+      def writers #:nodoc:
+        readers.select do |io|
+          io.respond_to?(:pending_write?) && io.pending_write?
+        end
+      end
+
+      # Runs the post-process action on the session, if the session has been
+      # opened. Only the +readers+ and +writers+ that actually belong to this
+      # session will be postprocessed by this server.
+      def postprocess(readers, writers) #:nodoc:
+        return true unless session
+        listeners = session.listeners.keys
+        session.postprocess(listeners & readers, listeners & writers)
+      end
+  end
+end; end; end

data/lib/net/ssh/multi/server_list.rb

@@ -0,0 +1,80 @@
+require 'net/ssh/multi/server'
+require 'net/ssh/multi/dynamic_server'
+
+module Net; module SSH; module Multi
+
+  # Encapsulates a list of server objects, both dynamic (Net::SSH::Multi::DynamicServer)
+  # and static (Net::SSH::Multi::Server). It attempts to make it transparent whether
+  # a dynamic server set has been evaluated or not. Note that a ServerList is
+  # NOT an Array, though it is Enumerable.
+  class ServerList
+    include Enumerable
+
+    # Create a new ServerList that wraps the given server list. Duplicate entries
+    # will be discarded.
+    def initialize(list=[])
+      @list = list.uniq
+    end
+
+    # Adds the given server to the list, and returns the argument. If an
+    # identical server definition already exists in the collection, the
+    # argument is _not_ added, and the existing server record is returned
+    # instead.
+    def add(server)
+      index = @list.index(server)
+      if index
+        server = @list[index]
+      else
+        @list.push(server)
+      end
+      server
+    end
+
+    # Adds an array (or otherwise Enumerable list) of servers to this list, by
+    # calling #add for each argument. Returns +self+.
+    def concat(servers)
+      servers.each { |server| add(server) }
+      self
+    end
+
+    # Iterates over each distinct server record in the collection. This will
+    # correctly iterate over server records instantiated by a DynamicServer
+    # as well, but only if the dynamic server has been "evaluated" (see
+    # Net::SSH::Multi::DynamicServer#evaluate!).
+    def each
+      @list.each do |server|
+        case server
+        when Server then yield server
+        when DynamicServer then server.each { |item| yield item }
+        else raise ArgumentError, "server list contains non-server: #{server.class}"
+        end
+      end
+      self
+    end
+
+    # Works exactly as Enumerable#select, but returns the result as a new
+    # ServerList instance.
+    def select
+      subset = @list.select { |i| yield i }
+      ServerList.new(subset)
+    end
+
+    # Returns an array of all servers in the list, with dynamic server records
+    # expanded. The result is an array of distinct server records (duplicates
+    # are removed from the result).
+    def flatten
+      result = @list.inject([]) do |aggregator, server|
+        case server
+        when Server then aggregator.push(server)
+        when DynamicServer then aggregator.concat(server)
+        else raise ArgumentError, "server list contains non-server: #{server.class}"
+        end
+      end
+
+      result.uniq
+    end
+
+    alias to_ary flatten
+  end
+
+end; end; end