net-ssh-multi 1.0.0

data/CHANGELOG.rdoc

@@ -0,0 +1,13 @@
+=== 1.0.0 / 1 May 2008
+
+* (no changes since the last preview release)
+
+
+=== 1.0 Preview Release 2 (0.99.1) / 19 Apr 2008
+
+* Don't try to select on closed IO streams [Jamis Buck]
+
+
+=== 1.0 Preview Release 1 (0.99.0) / 10 Apr 2008
+
+* First release of Net::SSH::Multi

data/Manifest

@@ -0,0 +1,23 @@
+CHANGELOG.rdoc
+lib/net/ssh/multi/channel.rb
+lib/net/ssh/multi/channel_proxy.rb
+lib/net/ssh/multi/dynamic_server.rb
+lib/net/ssh/multi/pending_connection.rb
+lib/net/ssh/multi/server.rb
+lib/net/ssh/multi/server_list.rb
+lib/net/ssh/multi/session.rb
+lib/net/ssh/multi/session_actions.rb
+lib/net/ssh/multi/subsession.rb
+lib/net/ssh/multi/version.rb
+lib/net/ssh/multi.rb
+Manifest
+Rakefile
+README.rdoc
+setup.rb
+test/channel_test.rb
+test/common.rb
+test/multi_test.rb
+test/server_test.rb
+test/session_actions_test.rb
+test/session_test.rb
+test/test_all.rb

data/README.rdoc

@@ -0,0 +1,87 @@
+= Net::SSH::Multi
+
+* http://net-ssh.rubyforge.org/multi
+
+== DESCRIPTION:
+
+Net::SSH::Multi is a library for controlling multiple Net::SSH connections via a single interface. It exposes an API similar to that of Net::SSH::Connection::Session and Net::SSH::Connection::Channel, making it simpler to adapt programs designed for single connections to be used with multiple connections.
+
+This library is particularly useful for automating repetitive tasks that must be performed on multiple machines. It executes the commands in parallel, and allows commands to be executed on subsets of servers (defined by groups).
+
+== FEATURES:
+
+* Easily manage multiple connections
+* Open channels, spawn processes, etc. on multiple connections in parallel
+* Transparently limit concurrent connections when dealing with large numbers of servers (Net::SSH::Multi::Session#concurrent_connections)
+* Specify a default gateway machine through which connections should be tunneled, or even specify a different gateway machine for each server
+
+== SYNOPSIS:
+
+In a nutshell:
+
+  require 'net/ssh/multi'
+
+  Net::SSH::Multi.start do |session|
+    # access servers via a gateway
+    session.via 'gateway', 'gateway-user'
+
+    # define the servers we want to use
+    session.use 'user1@host1'
+    session.use 'user2@host2'
+
+    # define servers in groups for more granular access
+    session.group :app do
+      session.use 'user@app1'
+      session.use 'user@app2'
+    end
+
+    # execute commands on all servers
+    session.exec "uptime"
+
+    # execute commands on a subset of servers
+    session.with(:app).exec "hostname"
+
+    # run the aggregated event loop
+    session.loop
+  end
+
+See Net::SSH::Multi::Session for more documentation.
+
+== REQUIREMENTS:
+
+* net-ssh (version 2)
+* net-ssh-gateway
+
+If you want to run the tests or use any of the Rake tasks, you'll need:
+
+* Echoe (for the Rakefile)
+* Mocha (for the tests)
+
+== INSTALL:
+
+* gem install net-ssh-multi (might need sudo privileges)
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Jamis Buck <jamis@37signals.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,28 @@
+begin
+  require 'echoe'
+rescue LoadError
+  abort "You'll need to have `echoe' installed to use Net::SSH::Multi's Rakefile"
+end
+
+require './lib/net/ssh/multi/version'
+
+version = Net::SSH::Multi::Version::STRING.dup
+if ENV['SNAPSHOT'].to_i == 1
+  version << "." << Time.now.utc.strftime("%Y%m%d%H%M%S")
+end
+
+Echoe.new('net-ssh-multi', version) do |p|
+  p.changelog        = "CHANGELOG.rdoc"
+
+  p.author           = "Jamis Buck"
+  p.email            = "jamis@jamisbuck.org"
+  p.summary          = "Control multiple Net::SSH connections via a single interface"
+  p.url              = "http://net-ssh.rubyforge.org/multi"
+
+  p.dependencies     = ["net-ssh >=1.99.2", "net-ssh-gateway >=0.99.0"]
+
+  p.need_zip         = true
+  p.include_rakefile = true
+
+  p.rdoc_pattern     = /^(lib|README.rdoc|CHANGELOG.rdoc)/
+end

data/lib/net/ssh/multi.rb

@@ -0,0 +1,71 @@
+require 'net/ssh/multi/session'
+
+module Net; module SSH
+  # Net::SSH::Multi is a library for controlling multiple Net::SSH
+  # connections via a single interface. It exposes an API similar to that of
+  # Net::SSH::Connection::Session and Net::SSH::Connection::Channel, making it
+  # simpler to adapt programs designed for single connections to be used with
+  # multiple connections.
+  #
+  # This library is particularly useful for automating repetitive tasks that
+  # must be performed on multiple machines. It executes the commands in
+  # parallel, and allows commands to be executed on subsets of servers
+  # (defined by groups).
+  #
+  #   require 'net/ssh/multi'
+  # 
+  #   Net::SSH::Multi.start do |session|
+  #     # access servers via a gateway
+  #     session.via 'gateway', 'gateway-user'
+  # 
+  #     # define the servers we want to use
+  #     session.use 'user1@host1'
+  #     session.use 'user2@host2'
+  # 
+  #     # define servers in groups for more granular access
+  #     session.group :app do
+  #       session.use 'user@app1'
+  #       session.use 'user@app2'
+  #     end
+  # 
+  #     # execute commands on all servers
+  #     session.exec "uptime"
+  # 
+  #     # execute commands on a subset of servers
+  #     session.with(:app).exec "hostname"
+  # 
+  #     # run the aggregated event loop
+  #     session.loop
+  #   end
+  # 
+  # See Net::SSH::Multi::Session for more documentation.
+  module Multi
+    # This is a convenience method for instantiating a new
+    # Net::SSH::Multi::Session. If a block is given, the session will be
+    # yielded to the block automatically closed (see Net::SSH::Multi::Session#close)
+    # when the block finishes. Otherwise, the new session will be returned.
+    #
+    #   Net::SSH::Multi.start do |session|
+    #     # ...
+    #   end
+    #
+    #   session = Net::SSH::Multi.start
+    #   # ...
+    #   session.close
+    #
+    # Any options are passed directly to Net::SSH::Multi::Session.new (q.v.).
+    def self.start(options={})
+      session = Session.new(options)
+
+      if block_given?
+        begin
+          yield session
+          session.loop
+          session.close
+        end
+      else
+        return session
+      end
+    end
+  end
+end; end

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

@@ -0,0 +1,216 @@
+module Net; module SSH; module Multi
+  # Net::SSH::Multi::Channel encapsulates a collection of Net::SSH::Connection::Channel
+  # instances from multiple different connections. It allows for operations to
+  # be performed on all contained channels, simultaneously, using an interface
+  # mostly identical to Net::SSH::Connection::Channel itself.
+  #
+  # You typically obtain a Net::SSH::Multi::Channel instance via
+  # Net::SSH::Multi::Session#open_channel or Net::SSH::Multi::Session#exec,
+  # though there is nothing stopping you from instantiating one yourself with
+  # a handful of Net::SSH::Connection::Channel objects (though they should be
+  # associated with connections managed by a Net::SSH::Multi::Session object
+  # for consistent behavior).
+  #
+  #   channel = session.open_channel do |ch|
+  #     # ...
+  #   end
+  #
+  #   channel.wait
+  class Channel
+    include Enumerable
+
+    # The Net::SSH::Multi::Session instance that controls this channel collection.
+    attr_reader :connection
+
+    # The collection of Net::SSH::Connection::Channel instances that this multi-channel aggregates.
+    attr_reader :channels
+
+    # A Hash of custom properties that may be set and queried on this object.
+    attr_reader :properties
+
+    # Instantiate a new Net::SSH::Multi::Channel instance, controlled by the
+    # given +connection+ (a Net::SSH::Multi::Session object) and wrapping the
+    # given +channels+ (Net::SSH::Connection::Channel instances).
+    #
+    # You will typically never call this directly; rather, you'll get your
+    # multi-channel references via Net::SSH::Multi::Session#open_channel and
+    # friends.
+    def initialize(connection, channels)
+      @connection = connection
+      @channels = channels
+      @properties = {}
+    end
+
+    # Iterate over each component channel object, yielding each in order to the
+    # associated block.
+    def each
+      @channels.each { |channel| yield channel }
+    end
+
+    # Retrieve the property (see #properties) with the given +key+.
+    #
+    #   host = channel[:host]
+    def [](key)
+      @properties[key]
+    end
+
+    # Set the property (see #properties) with the given +key+ to the given
+    # +value+.
+    #
+    #   channel[:visited] = true
+    def []=(key, value)
+      @properties[key] = value
+    end
+
+    # Perform an +exec+ command on all component channels. The block, if given,
+    # is passed to each component channel, so it will (potentially) be invoked
+    # once for every channel in the collection. The block will receive two
+    # parameters: the specific channel object being operated on, and a boolean
+    # indicating whether the exec succeeded or not.
+    #
+    #   channel.exec "ls -l" do |ch, success|
+    #     # ...
+    #   end
+    #
+    # See the documentation in Net::SSH for Net::SSH::Connection::Channel#exec
+    # for more information on how to work with the callback.
+    def exec(command, &block)
+      channels.each { |channel| channel.exec(command, &block) }
+      self
+    end
+
+    # Perform a +request_pty+ command on all component channels. The block, if
+    # given, is passed to each component channel, so it will (potentially) be
+    # invoked once for every channel in the collection. The block will
+    # receive two parameters: the specific channel object being operated on,
+    # and a boolean indicating whether the pty request succeeded or not.
+    #
+    #   channel.request_pty do |ch, success|
+    #     # ...
+    #   end
+    #
+    # See the documentation in Net::SSH for
+    # Net::SSH::Connection::Channel#request_pty for more information on how to
+    # work with the callback.
+    def request_pty(opts={}, &block)
+      channels.each { |channel| channel.request_pty(opts, &block) }
+      self
+    end
+
+    # Send the given +data+ to each component channel. It will be sent to the
+    # remote process, typically being received on the process' +stdin+ stream.
+    #
+    #   channel.send_data "password\n"
+    def send_data(data)
+      channels.each { |channel| channel.send_data(data) }
+      self
+    end
+
+    # Returns true as long as any of the component channels are active.
+    #
+    #   connection.loop { channel.active? }
+    def active?
+      channels.any? { |channel| channel.active? }
+    end
+
+    # Runs the connection's event loop until the channel is no longer active
+    # (see #active?).
+    #
+    #   channel.exec "something"
+    #   channel.wait
+    def wait
+      connection.loop { active? }
+      self
+    end
+
+    # Closes all component channels.
+    def close
+      channels.each { |channel| channel.close }
+      self
+    end
+
+    # Tells the remote process for each component channel not to expect any
+    # further data from this end of the channel.
+    def eof!
+      channels.each { |channel| channel.eof! }
+      self
+    end
+
+    # Registers a callback on all component channels, to be invoked when the
+    # remote process emits data (usually on its +stdout+ stream). The block
+    # will be invoked with two arguments: the specific channel object, and the
+    # data that was received.
+    #
+    #   channel.on_data do |ch, data|
+    #     puts "got data: #{data}"
+    #   end
+    def on_data(&block)
+      channels.each { |channel| channel.on_data(&block) }
+      self
+    end
+
+    # Registers a callback on all component channels, to be invoked when the
+    # remote process emits "extended" data (typically on its +stderr+ stream).
+    # The block will be invoked with three arguments: the specific channel
+    # object, an integer describing the data type (usually a 1 for +stderr+)
+    # and the data that was received.
+    #
+    #   channel.on_extended_data do |ch, type, data|
+    #     puts "got extended data: #{data}"
+    #   end
+    def on_extended_data(&block)
+      channels.each { |channel| channel.on_extended_data(&block) }
+      self
+    end
+
+    # Registers a callback on all component channels, to be invoked during the
+    # idle portion of the connection event loop. The callback will be invoked
+    # with one argument: the specific channel object being processed.
+    #
+    #   channel.on_process do |ch|
+    #     # ...
+    #   end
+    def on_process(&block)
+      channels.each { |channel| channel.on_process(&block) }
+      self
+    end
+
+    # Registers a callback on all component channels, to be invoked when the
+    # remote server terminates the channel. The callback will be invoked
+    # with one argument: the specific channel object being closed.
+    #
+    #   channel.on_close do |ch|
+    #     # ...
+    #   end
+    def on_close(&block)
+      channels.each { |channel| channel.on_close(&block) }
+      self
+    end
+
+    # Registers a callback on all component channels, to be invoked when the
+    # remote server has no further data to send. The callback will be invoked
+    # with one argument: the specific channel object being marked EOF.
+    #
+    #   channel.on_eof do |ch|
+    #     # ...
+    #   end
+    def on_eof(&block)
+      channels.each { |channel| channel.on_eof(&block) }
+      self
+    end
+
+    # Registers a callback on all component channels, to be invoked when the
+    # remote server sends a channel request of the given +type+. The callback
+    # will be invoked with two arguments: the specific channel object receiving
+    # the request, and a Net::SSH::Buffer instance containing the request-specific
+    # data.
+    #
+    #   channel.on_request("exit-status") do |ch, data|
+    #     puts "exited with #{data.read_long}"
+    #   end
+    def on_request(type, &block)
+      channels.each { |channel| channel.on_request(type, &block) }
+      self
+    end
+  end
+end; end; end

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

@@ -0,0 +1,50 @@
+module Net; module SSH; module Multi
+
+  # The ChannelProxy is a delegate class that represents a channel that has
+  # not yet been opened. It is only used when Net::SSH::Multi is running with
+  # with a concurrent connections limit (see Net::SSH::Multi::Session#concurrent_connections).
+  #
+  # You'll never need to instantiate one of these directly, and will probably
+  # (if all goes well!) never even notice when one of these is in use. Essentially,
+  # it is spawned by a Net::SSH::Multi::PendingConnection when the pending
+  # connection is asked to open a channel. Any actions performed on the
+  # channel proxy will then be recorded, until a real channel is set as the
+  # delegate (see #delegate_to). At that point, all recorded actions will be
+  # replayed on the channel, and any subsequent actions will be immediately
+  # delegated to the channel.
+  class ChannelProxy
+    # This is the "on confirm" callback that gets called when the real channel
+    # is opened.
+    attr_reader :on_confirm
+
+    # Instantiates a new channel proxy with the given +on_confirm+ callback.
+    def initialize(&on_confirm)
+      @on_confirm = on_confirm
+      @recordings = []
+      @channel = nil
+    end
+
+    # Instructs the proxy to delegate all further actions to the given +channel+
+    # (which must be an instance of Net::SSH::Connection::Channel). All recorded
+    # actions are immediately replayed, in order, against the delegate channel.
+    def delegate_to(channel)
+      @channel = channel
+      @recordings.each do |sym, args, block|
+        @channel.__send__(sym, *args, &block)
+      end
+    end
+
+    # If a channel delegate has been specified (see #delegate_to), the method
+    # will be immediately sent to the delegate. Otherwise, the call is added
+    # to the list of recorded method calls, to be played back when a delegate
+    # is specified.
+    def method_missing(sym, *args, &block)
+      if @channel
+        @channel.__send__(sym, *args, &block)
+      else
+        @recordings << [sym, args, block]
+      end
+    end
+  end
+
+end; end; end