net-ssh 0.5.0

data/lib/net/ssh/service/forward/services.rb

@@ -0,0 +1,76 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SSH Secure Shell Client
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Net::SSH
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-ssh website : http://net-ssh.rubyforge.org
+# project website: http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+module Net
+  module SSH
+    module Service
+      module Forward
+
+        # Register the services pertaining to port forwarding.
+        def register_services( container )
+
+          # All port forwarding services go in the :forward namespace.
+          container.namespace_define :forward do |ns|
+
+            # The :driver service manages all port forwarding. It is declared
+            # as deferred so that it is not actually instantiated until it is
+            # used--otherwise, it would be instantiated as soon as it was added
+            # to the list of available services, whether it was ever used or
+            # not.
+            ns.driver :model => :singleton_deferred do |c,p|
+              require 'net/ssh/service/forward/driver'
+              Driver.new( c[:connection][:driver],
+                          c[:transport][:buffers],
+                          c[:log_for, p],
+                          :local => c[:local_network_handler],
+                          :remote => c[:remote_network_handler] )
+            end
+
+            # A constant service, used to indicate the maximum block size to be
+            # passed over a forwarded connection.
+            ns.read_block_size { 64 * 1024 }
+
+            # The :local_network_handler service returns a proc object that
+            # creates new LocalNetworkHandler instances for a given client
+            # connection. This is used for forwarding ports on the local host.
+            ns.local_network_handler :model => :singleton_deferred do |c,p|
+              require 'net/ssh/service/forward/local-network-handler'
+              log = c[:log_for, p]
+              block_size = c[:read_block_size]
+              lambda do |client|
+                LocalNetworkHandler.new( log, block_size, client )
+              end
+            end
+
+            # The :remote_network_handler service returns a proc object that
+            # creates new RemoteNetworkHandler instances for a given port and
+            # host. This is used for forwarding ports on a remote host.
+            ns.remote_network_handler :model => :singleton_deferred do |c,p|
+              require 'net/ssh/service/forward/remote-network-handler'
+              log = c[:log_for, p]
+              block_size = c[:read_block_size]
+              lambda do |port, host|
+                RemoteNetworkHandler.new( log, block_size, port, host )
+              end
+            end
+          end
+        end
+        module_function :register_services
+
+      end
+    end
+  end
+end

data/lib/net/ssh/service/process/driver.rb

@@ -0,0 +1,153 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SSH Secure Shell Client
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Net::SSH
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-ssh website : http://net-ssh.rubyforge.org
+# project website: http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+require 'net/ssh/errors'
+
+module Net
+  module SSH
+    module Service
+      module Process
+      
+        # Represents a process executing on the remote machine. It also provides
+        # a simple interface for interacting with such a remote process.
+        #
+        # It may be used in either of two ways. The first allows multiple
+        # processes to be invoked on the remote machine and run in parallel
+        # over the same session. Because of this, it is a bit complicated to
+        # set up:
+        #
+        #   require 'net/ssh'
+        #
+        #   Net::SSH.start( 'host', 'user', 'passwd' ) do |session|
+        #     process = session.process.open( "bc" )
+        #     dialog = [ "5+5", "7*12", "1+2*5/(7+3)" ]
+        #
+        #     process.on_success do |p|
+        #       puts "requesting computation of '#{dialog.first}'"
+        #       p.puts dialog.shift
+        #     end
+        #
+        #     process.on_failure do |p, status|
+        #       puts "process failed to start (#{status})"
+        #     end
+        #
+        #     process.on_stdout do |p, data|
+        #       puts "--> #{data}"
+        #       if dialog.empty?
+        #         p.close_input
+        #       else
+        #         puts "requesting computation of '#{dialog.first}'"
+        #         p.puts dialog.shift
+        #       end
+        #     end
+        #
+        #     process.on_stderr do |p, data|
+        #       puts "[stderr]--> #{data}"
+        #     end
+        #
+        #     process.on_exit do |p, status|
+        #       puts "process finished with exit status: #{status}"
+        #     end
+        #
+        #     session.loop
+        #   end
+        #
+        # Naturally, not all of the callbacks used above are required. If you
+        # omit any of them, they will simply not be called. However, you
+        # *should* do something when the process is successfully started
+        # (+on_success+), and you *should* do something when data is recieved
+        # over stdout (+on_stdout+). Lastly, you *must* execute
+        # <tt>session.loop</tt> in order to process the connection.
+        #
+        # The simpler way to use this service is only available when you
+        # are not handling multiple parallel processes--you can only use it
+        # when the process you are executing is the only task you are using the
+        # SSH connection for. It is reminiscent of the popen interface: you
+        # invoke a command and get three pseudo-IO objects back--one for the
+        # command's "stdin" stream, one for it's "stdout" stream, and one for
+        # it's "stderr" stream. You may then write to the "stdin" stream, and
+        # read from the "stdout" and "stderr" streams.
+        #
+        # For example:
+        #
+        #   require 'net/ssh'
+        #
+        #   Net::SSH.start( 'host', 'user', 'passwd' ) do |session|
+        #     input, output, error = session.process.popen3( "bc" )
+        #     input.puts "5+5"
+        #     puts "5+5=#{output.read}"
+        #     input.puts "7*12"
+        #     puts "7*12=#{output.read}"
+        #     input.puts "1+2*5/(7+3)"
+        #     puts "1+2*5/(7+3)=#{output.read}"
+        #     input.puts "quit"
+        #   end
+        #
+        # One caveat with this format: the process cannot be explicitly
+        # terminated from the client side--the process must terminate on its
+        # own (for example, by recieving a "quit" command, as used above). If
+        # the command does not support any means of gracefully aborting it,
+        # then the only way to kill the command is to terminate the connection.
+        #
+        # A slightly cleaner approach uses blocks to denote the lifespan of the
+        # process. When the block terminates, the process is killed (if it is
+        # still running):
+        #
+        #   require 'net/ssh'
+        #
+        #   Net::SSH.start( 'host', 'user', 'passwd' ) do |session|
+        #     session.process.popen3( "cat" ) do |input, output, error|
+        #       input.puts "hello"
+        #       puts "echo: #{output.read}"
+        #       input.puts "world"
+        #       puts "echo: #{output.read}"
+        #     end
+        #   end
+        class Driver
+
+          # Create a new Driver instance, using the given log and handlers
+          # hash.
+          def initialize( connection, log, handlers )
+            @connection = connection
+            @log = log
+            @handlers = handlers
+          end
+
+          def open( command )
+            @log.debug "opening '#{command}'" if @log.debug?
+            process = @handlers[ :open ].call( command )
+
+            if block_given?
+              yield process
+              @connection.loop
+              return nil
+            end
+
+            process
+          end
+
+          def popen3( command, &block )
+            @log.debug "popen3 '#{command}'" if @log.debug?
+            mgr = @handlers[ :popen3 ]
+            mgr.popen3( command, &block )
+          end
+
+        end
+
+      end # module Process
+    end # module Service
+  end # module SSH
+end # module Net

data/lib/net/ssh/service/process/open.rb

@@ -0,0 +1,193 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SSH Secure Shell Client
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Net::SSH
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-ssh website : http://net-ssh.rubyforge.org
+# project website: http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+require 'net/ssh/errors'
+
+module Net
+  module SSH
+    module Service
+      module Process
+      
+        # A delegate class to manage the processing for a single executed
+        # process on the remote host. It opens a channel, executes the process
+        # on it, and manages the various callbacks.
+        #
+        # This service is typically used like this:
+        #
+        #   Net::SSH.start( 'host', 'user' ) do |session|
+        #     session.process.open( "bc" ) do |process|
+        #       ...
+        #     end
+        #   end
+        class OpenManager
+
+          # Create a new OpenManager instance on the given connection. It will
+          # attempt to execute the given command. If a block is given, the
+          # manager will be yielded to the block, and the constructor will not
+          # return until all channels are closed.
+          def initialize( connection, log, command )
+            @log = log
+            @command = command
+            @channel = connection.open_channel(
+              "session", &method( :do_confirm ) )
+
+            if block_given?
+              yield self
+              connection.loop
+            end
+          end
+
+          # Register the given block to be invoked when the command has been
+          # confirmed to have been successfully started. The block should
+          # accept a single parameter, the process instance that was created
+          # (+self+).
+          def on_success( &block )
+            @on_success = block
+          end
+
+          # Register the given block to be invoked when the command could not
+          # be started. The block should accept two parameters: the process
+          # instance (+self+) and a status string. (The status string is
+          # currently always +nil+, since SSH itself does not indicate why the
+          # program failed to start.)
+          def on_failure( &block )
+            @on_failure = block
+          end
+
+          # Register the given block to be invoked when data is recieved from
+          # the invoked command's +stdout+ stream. The block should accept two
+          # parameters: the process instance (+self+) and the data string. Note
+          # that if the process sends large amounts of data, this method may be
+          # invoked multiple times, each time with a portion of the command's
+          # output.
+          def on_stdout( &block )
+            @on_stdout = block
+          end
+
+          # Register the given block to be invoked when data is recieved from
+          # the invoked command's +stderr+ stream. The block should accept two
+          # parameters: the process instance (+self+) and the data string. Note
+          # that if the process sends large amounts of data, this method may be
+          # invoked multiple times, each time with a portion of the command's
+          # error output.
+          def on_stderr( &block )
+            @on_stderr = block
+          end
+
+          # Register the given block to be invoked when the process terminates
+          # normally. The block should accept two parameters: the process
+          # instance (+self+) and the exit status of the process.
+          def on_exit( &block )
+            @on_exit = block
+          end
+
+          # Send the given data to the process. It will be sent via the
+          # process's +stdin+ stream. This method returns immediately.
+          def write( data )
+            @channel.send_data data
+          end
+
+          # Send the given data to the process, appending a newline. As with
+          # Kernel::puts, this will not append a newline if the string already
+          # has one. See #write.
+          def puts( data )
+            @channel.send_data data.chomp + "\n"
+          end
+
+          # Indicate that no more data will be sent to the process (sends an
+          # EOF to the process). The process may continue to send data, but
+          # the +stdin+ stream is effectively closed. This will return
+          # immediately.
+          def close_input
+            @channel.send_eof
+          end
+
+          # Close the process. All streams (+stdin+, +stdout+, +stderr+) will
+          # be closed. Any output that the process had already produced will
+          # still be sent, but it will be shut down as soon as possible. This
+          # will return immediately.
+          def close
+            @channel.close
+          end
+
+          # Invoked when the channel's opening has been confirmed by the
+          # server. This is where the command to execute will be sent to the
+          # server.
+          def do_confirm( channel )
+            channel.on_success &method(:do_exec_success)
+            channel.on_failure &method(:do_exec_failure)
+            channel.exec @command, true
+          end
+
+          # Invoked when the invocation of the command has been successful.
+          # This registers various callbacks, and then calls the +on_success+
+          # callback (if registered).
+          def do_exec_success( channel )
+            channel.on_data &method(:do_data)
+            channel.on_extended_data &method(:do_extended_data)
+            channel.on_close &method(:do_close)
+            channel.on_request &method(:do_request)
+            @on_success.call( self ) if @on_success
+          end
+
+          # Invoked when the invocation of the command failed. This will call
+          # the +on_failure+ callback, if registered, or will otherwise raise
+          # an exception.
+          def do_exec_failure( channel )
+            if @on_failure
+              @on_failure.call( self, nil )
+            else
+              raise Net::SSH::Exception,
+                "could not execute process (#{@command})"
+            end
+          end
+
+          # Invoked when data arrives over the channel. This simply delegates to
+          # the +on_stdout+ callback, if registered.
+          def do_data( channel, data )
+            @on_stdout.call( self, data ) if @on_stdout
+          end
+
+          # Invoked when extended data arrives over the channel. This simply
+          # delegates to the +on_stderr+ callback, if registered, if the type
+          # is 1; otherwise it does nothing.
+          def do_extended_data( channel, type, data )
+            case type
+              when 1
+                @on_stderr.call( self, data ) if @on_stderr
+            end
+          end
+
+          # Invoked when the channel is closed. This simply delegates to
+          # the +on_exit+ callback, if registered.
+          def do_close( channel )
+            @on_exit.call( self, @exit_status ) if @on_exit
+          end
+
+          # Invoked when a channel request is received.
+          def do_request( channel, type, want_reply, data )
+            case type
+              when "exit-status"
+                @exit_status = data.read_long
+            end
+          end
+
+        end
+
+      end # module Process
+    end # module Service
+  end # module SSH
+end # module Net

data/lib/net/ssh/service/process/popen3.rb

@@ -0,0 +1,160 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SSH Secure Shell Client
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Net::SSH
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-ssh website : http://net-ssh.rubyforge.org
+# project website: http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+require 'net/ssh/errors'
+
+module Net
+  module SSH
+    module Service
+      module Process
+      
+        # A delegate class for managing popen3 requests for remote processes.
+        class POpen3Manager
+
+          # Create a new POpen3Manager instance on the given connection.
+          def initialize( connection, log )
+            @connection = connection
+            @log = log
+          end
+
+          # Invokes the given command synchronously on the current connection.
+          # (This means that parallel commands and operations cannot be
+          # executed when this method is used.) This will return +nil+ if the
+          # method could not be executed. If the command is successfully
+          # invoked, and a block is given, the block is then invoked with the
+          # input, output, and error streams of the command as parameters, and
+          # the channel is closed as soon as the block terminates. If a block
+          # is not given, the input, output, and error channels are returned
+          # and the process *might* not terminate until the session itself
+          # terminates.
+          def popen3( command )
+            @connection.open_channel( "session" ) do |chan|
+
+              chan.on_success do |ch|
+                input  = SSHStdinPipe.new( ch )
+                output = SSHStdoutPipe.new( ch )
+                error  = SSHStderrPipe.new( ch )
+
+                if block_given?
+                  yield input, output, error
+                  chan.close
+                else
+                  return [ input, output, error ]
+                end
+              end
+
+              chan.on_failure do |ch|
+                chan.close
+              end
+
+              chan.exec command, true
+            end
+
+            @connection.loop
+            return nil
+          end
+
+          # A specialized class for use by the Net::SSH "popen3" service.
+          # An instance of this class represents a means of writing data to an
+          # SSH channel. This class should never be instantiated directly; use
+          # the popen3 method instead.
+          class SSHStdinPipe
+
+            # Create a new +stdin+ pipe on the given channel.
+            def initialize( channel )
+              @channel = channel
+            end
+
+            # Write the given data as channel data to the underlying channel.
+            def write( data )
+              @channel.send_data data
+            end
+
+            # Write the given data as channel data to the underlying channel,
+            # appending a newline character (if one isn't already appended).
+            def puts( data )
+              write data.chomp + "\n"
+            end
+
+          end
+
+          # An abstract class representing a writable stream on a channel. This
+          # is subclassed by SSHStdoutPipe and SSHStderrPipe.
+          class SSHOutputPipe
+            
+            # Create a new output pipe on the given channel.
+            def initialize( channel )
+              @channel = channel
+              @data = ""
+            end
+
+            # Read all available bytes from the pipe. If there are no available
+            # bytes, then this will block until data becomes available.
+            def read
+              if @data.length < 1
+                @channel.connection.loop { @data.length < 1 }
+              end
+
+              data, @data = @data, ""
+              return data
+            end
+
+          end
+
+          # A specialization of SSHOutputPipe that represents specifically the 
+          # +stdout+ stream of a process. It should only be used by popen3.
+          class SSHStdoutPipe < SSHOutputPipe
+
+            # Create a new +stdout+ stream on the given channel. Only one such
+            # pipe should ever be associated with a channel.
+            def initialize( channel )
+              super( channel )
+              channel.on_data &method(:do_data)
+            end
+
+            # Invoked when data is recieved from the channel. It simply
+            # accumulates all data until a +read+ is invoked.
+            def do_data( channel, data )
+              @data << data
+            end
+
+          end
+
+          # A specialization of SSHOutputPipe that represents specifically the
+          # +stderr+ stream of a process. It should only be used by popen3.
+          class SSHStderrPipe < SSHOutputPipe
+
+            # Create a new +stderr+ stream on the given channel. Only one such
+            # pipe should ever be associated with a channel.
+            def initialize( channel )
+              super( channel )
+              channel.on_extended_data &method(:do_data)
+            end
+
+            # Invoked when data is recieved from the channel. It simply
+            # accumulates all data until a +read+ is invoked.
+            def do_data( channel, type, data )
+              @data << data if type == 1
+            end
+
+          end
+
+        end
+
+      end # module Process
+    end # module Service
+  end # module SSH
+end # module Net