net-ssh 0.6.0 → 0.9.0

data/doc/manual/stylesheets/ruby.css

@@ -0,0 +1,17 @@
+.ruby .normal {}
+.ruby .comment { color: #005; font-style: italic; }
+.ruby .keyword { color: #A00; font-weight: bold; }
+.ruby .method { color: #077; }
+.ruby .class { color: #074; }
+.ruby .module { color: #050; }
+.ruby .punct { color: #447; font-weight: bold; }
+.ruby .symbol { color: #099; }
+.ruby .string { color: #944; }
+.ruby .char { color: #F07; }
+.ruby .ident { color: #004; }
+.ruby .constant { color: #07F; }
+.ruby .regex { color: #B66; }
+.ruby .number { color: #D55; }
+.ruby .attribute { color: #377; }
+.ruby .global { color: #3B7; }
+.ruby .expr { color: #227; }

data/examples/channel-demo.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================
-# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# Copyright (c) 2004,2005 Jamis Buck (jamis_buck@byu.edu)
 # All rights reserved.
 #
 # This source file is distributed as part of the Net::SSH Secure Shell Client

data/examples/port-forward.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================
-# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# Copyright (c) 2004,2005 Jamis Buck (jamis_buck@byu.edu)
 # All rights reserved.
 #
 # This source file is distributed as part of the Net::SSH Secure Shell Client

data/examples/process-demo.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================
-# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# Copyright (c) 2004,2005 Jamis Buck (jamis_buck@byu.edu)
 # All rights reserved.
 #
 # This source file is distributed as part of the Net::SSH Secure Shell Client

data/examples/remote-net-port-forward.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================
-# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# Copyright (c) 2004,2005 Jamis Buck (jamis_buck@byu.edu)
 # All rights reserved.
 #
 # This source file is distributed as part of the Net::SSH Secure Shell Client

data/examples/remote-port-forward.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================
-# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# Copyright (c) 2004,2005 Jamis Buck (jamis_buck@byu.edu)
 # All rights reserved.
 #
 # This source file is distributed as part of the Net::SSH Secure Shell Client

data/examples/shell-demo.rb

@@ -0,0 +1,46 @@
+#--
+# =============================================================================
+# Copyright (c) 2004,2005 Jamis Buck (jamis_buck@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
+# =============================================================================
+#++
+
+$:.unshift "../lib"
+require 'net/ssh'
+
+Net::SSH.start( 'localhost' ) do |session|
+
+  shell = session.shell.open
+
+  # script what we want to do
+  shell.pwd
+  shell.cd "/"
+  shell.pwd
+  shell.test "-e foo"
+  shell.ls "-laZ"
+  shell.cd "/really/bogus/directory"
+  shell.send_data "/sbin/ifconfig\n"
+  shell.pwd
+  shell.ruby "-v"
+  shell.cd "/usr/lib"
+  shell.pwd
+  shell.exit
+
+  # give the above commands sufficient time to terminate
+  sleep 0.5
+
+  # display the output
+  $stdout.print shell.stdout while shell.stdout?
+  $stderr.puts "-- stderr: --"
+  $stderr.print shell.stderr while shell.stderr?
+
+end

data/examples/ssh-client.rb

@@ -0,0 +1,67 @@
+#--
+# =============================================================================
+# Copyright (c) 2004,2005 Jamis Buck (jamis_buck@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
+# =============================================================================
+#++
+
+# This is a (very) simple, but capable, SSH terminal client. It DOES NOT send
+# the size of the terminal window, or handle resizing of the terminal window.
+
+$:.unshift "../lib"
+require 'net/ssh'
+
+begin
+  require 'termios'
+rescue LoadError
+end
+
+def stdin_buffer( enable )
+  return unless defined?( Termios )
+  attr = Termios::getattr( $stdin )
+  if enable
+    attr.c_lflag |= Termios::ICANON | Termios::ECHO
+  else
+    attr.c_lflag &= ~(Termios::ICANON|Termios::ECHO)
+  end
+  Termios::setattr( $stdin, Termios::TCSANOW, attr )
+end
+
+host = ARGV.shift or abort "You must specify the [user@]host to connect to"
+if host =~ /@/
+  user, host = host.match( /(.*?)@(.*)/ )[1,2]
+else
+  user = ENV['USER'] || ENV['USER_NAME']
+end
+
+Net::SSH.start( host, user ) do |session|
+
+  begin
+    stdin_buffer false
+
+    shell = session.shell.open( :pty => true )
+
+    loop do
+      break unless shell.open?
+      if IO.select([$stdin],nil,nil,0.01)
+        data = $stdin.sysread(1)
+        shell.send_data data
+      end
+
+      $stdout.print shell.stdout while shell.stdout?
+      $stdout.flush
+    end
+  ensure
+    stdin_buffer true
+  end
+
+end

data/examples/sync-shell-demo.rb

@@ -0,0 +1,69 @@
+#--
+# =============================================================================
+# Copyright (c) 2004,2005 Jamis Buck (jamis_buck@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
+# =============================================================================
+#++
+
+$:.unshift "../lib"
+require 'net/ssh'
+
+Net::SSH.start( 'localhost' ) do |session|
+
+  shell = session.shell.sync
+
+  out = shell.pwd
+  p out.stdout
+
+  out = shell.cd "/"
+
+  out = shell.pwd
+  p out.stdout
+
+  out = shell.test "-e foo"
+  p out.status
+
+  out = shell.ls "-laZ"
+  p out.stderr
+  p out.status
+
+  out = shell.cd "/really/bogus/directory"
+  p out.stderr
+  p out.status
+
+  out = shell.send_command "/sbin/ifconfig"
+  p out.stdout
+  p out.status
+
+  out = shell.pwd
+  p out.stdout
+
+  out = shell.ruby "-v"
+  p out.stdout
+
+  out = shell.cd "/usr/lib"
+
+  out = shell.pwd
+  p out.stdout
+
+  out = shell.send_command( "bc", <<CMD )
+5+5
+10*2
+scale=5
+3/4
+quit
+CMD
+  p out.stdout
+
+  p shell.exit
+
+end

data/examples/tail-demo.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================
-# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# Copyright (c) 2004,2005 Jamis Buck (jamis_buck@byu.edu)
 # All rights reserved.
 #
 # This source file is distributed as part of the Net::SSH Secure Shell Client

data/lib/net/ssh.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================
-# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# Copyright (c) 2004,2005 Jamis Buck (jamis_buck@byu.edu)
 # All rights reserved.
 #
 # This source file is distributed as part of the Net::SSH Secure Shell Client

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

@@ -1,6 +1,6 @@
 #--
 # =============================================================================
-# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# Copyright (c) 2004,2005 Jamis Buck (jamis_buck@byu.edu)
 # All rights reserved.
 #
 # This source file is distributed as part of the Net::SSH Secure Shell Client
@@ -15,6 +15,7 @@
 #++
 
 require 'net/ssh/connection/constants'
+require 'net/ssh/connection/term'
 
 module Net
   module SSH
@@ -256,23 +257,78 @@ module Net
 
         # Send a data packet to the server, over the channel.
         def send_data( data )
+          @connection.register_data_request( self, data )
+        end
+
+        # Send an extended data packet to the server, over the channel.
+        # Extended data always has a numeric type associated with it. The
+        # only predefined type is 1, whic corresponds to +stderr+ data.
+        def send_extended_data( type, data )
+          @connection.register_data_request( self, data, type )
+        end
+
+        # Splits the given data so that it will fit in a data packet, taking
+        # into consideration the current window size and maximum packet size.
+        # The +overhead+ parameter is the number of additional bytes added by
+        # the packet itself.
+        #
+        # This returns a tuple, <tt>[data,data_to_return]</tt>, where the first
+        # element is the data to include in the packet, and the second element
+        # is the data remaining that would not fit in the packet.
+        def split_data_for_packet( data, overhead )
+          data_to_return = nil
+
+          if data.length > window_size 
+            data_to_return = data[window_size..-1]
+            data = data[0,window_size]
+          end
+
+          if data.length + overhead > maximum_packet_size
+            data_to_return = data[maximum_packet_size..-1] + 
+              ( data_to_return || "" )
+            data = data[0,maximum_packet_size]
+          end
+
+          [ data, data_to_return ]
+        end
+        private :split_data_for_packet
+
+        # Send a data packet to the server, over the channel. Only sends as
+        # much of that data as the channel is currently capable of sending
+        # (based on window size and maximum packet size), and returns any
+        # data that could not be sent. Returns +nil+ if all the data that
+        # was requested to be sent, was sent.
+        def send_data_packet( data )
+          # overhead is ( byte.length + id.length + strlen.length ) = 9
+          data, data_to_return = split_data_for_packet( data.to_s, 9 )
+          @window_size -= data.length
+
           msg = @buffers.writer
           msg.write_byte CHANNEL_DATA
           msg.write_long @remote_id
-          msg.write_string data.to_s
+          msg.write_string data
           @connection.send_message msg
+
+          data_to_return
         end
 
         # Send an extended data packet to the server, over the channel.
         # Extended data always has a numeric type associated with it. The
         # only predefined type is 1, whic corresponds to +stderr+ data.
-        def send_extended_data( type, data )
+        def send_extended_data_packet( type, data )
+          # overhead is
+          #   ( byte.length + id.length + type.length + strlen.length ) = 13
+          data, data_to_return = split_data_for_packet( data.to_s, 13 )
+          @window_size -= data.length
+
           msg = @buffers.writer
           msg.write_byte CHANNEL_EXTENDED_DATA
           msg.write_long @remote_id
           msg.write_long type
-          msg.write_string data.to_s
+          msg.write_string data
           @connection.send_message msg
+
+          data_to_return
         end
 
         VALID_PTY_OPTIONS = { :term=>"xterm",
@@ -295,9 +351,7 @@ module Net
               "invalid option(s) to request_pty: #{invalid_opts.inspect}"
           end
 
-          VALID_PTY_OPTIONS.keys.each do |opt|
-            opts[ opt ] ||= VALID_PTY_OPTIONS[ opt ]
-          end
+          opts = VALID_PTY_OPTIONS.merge( opts )
 
           msg = @buffers.writer
           msg.write_string opts[ :term ]

data/lib/net/ssh/connection/constants.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================
-# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# Copyright (c) 2004,2005 Jamis Buck (jamis_buck@byu.edu)
 # All rights reserved.
 #
 # This source file is distributed as part of the Net::SSH Secure Shell Client

data/lib/net/ssh/connection/driver.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================
-# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# Copyright (c) 2004,2005 Jamis Buck (jamis_buck@byu.edu)
 # All rights reserved.
 #
 # This source file is distributed as part of the Net::SSH Secure Shell Client
@@ -29,6 +29,10 @@ module Net
         # #global_request method.
         Request = Struct.new( :type, :data, :callback )
 
+        # A structure for representing a data buffer that must be sent
+        # across a channel.
+        DataRequest = Struct.new( :channel, :data, :type )
+
         #--
         # ====================================================================
         # CONSTRUCTOR
@@ -51,6 +55,7 @@ module Net
           @channel_map = Hash.new
           @request_queue = Array.new
           @channel_open_handlers = Hash.new
+          @data_requests = Array.new
         end
 
         #--
@@ -100,6 +105,21 @@ module Net
           end
         end
 
+        # Register a data buffer (of an optional type) to be sent across the
+        # given channel at the next available opportunity.
+        #
+        # This is used internally by channels to hide the window size and
+        # maximum packet size from the client. Clients should not call this
+        # method directly.
+        def register_data_request( channel, data, type=nil )
+          @data_requests << DataRequest.new( channel, data, type )
+
+          # make sure the new data request has a chance to be sent to the
+          # server... Otherwise, it cannot be sent until the next time #process
+          # is invoked, which can be unexpected in synchronous situations.
+          process_data_requests
+        end
+
         #--
         # ====================================================================
         # CONNECTION PROCESSING
@@ -114,16 +134,23 @@ module Net
           process while block.call
         end
 
-        # Wait for and dispatch a single event.
-        def process
-          type, response = @session.wait_for_message
+        # Wait for and dispatch a single event. If +nonblock+ is false (the
+        # default) this will block until a message has been received. Otherwise,
+        # it will return immediately.
+        def process( nonblock=false )
+          process_data_requests
 
-          unless ( dispatcher = MESSAGES[ type ] )
-            raise Net::SSH::Exception,
-              "Unexpected response type '#{type}', (#{response.inspect})"
+          if !nonblock || reader_ready?
+            type, response = @session.wait_for_message
+
+            unless ( dispatcher = MESSAGES[ type ] )
+              raise Net::SSH::Exception,
+                "Unexpected response type '#{type}', (#{response.inspect})"
+            end
+
+            dispatcher[:method].bind( self ).call( response )
           end
 
-          dispatcher[:method].bind( self ).call( response )
           self
         end
 
@@ -153,6 +180,11 @@ module Net
           self
         end
 
+        # Delegates the the #reader_ready method of the transport session.
+        def reader_ready?
+          @session.reader_ready?
+        end
+
         #--
         # ====================================================================
         # MESSAGE HANDLERS
@@ -316,6 +348,27 @@ module Net
           request.callback.call( success, response ) if request.callback
         end
 
+        # Process all pending data requests.
+        def process_data_requests
+          @data_requests.map! do |req|
+            while req && req.channel.window_size > 0
+              remaining = if req.type
+                  req.channel.send_extended_data_packet( req.type, req.data )
+                else
+                  req.channel.send_data_packet( req.data )
+                end
+              if remaining
+                req.data = remaining
+              else
+                req = nil
+              end
+            end
+
+            req
+          end
+          @data_requests.compact!
+        end
+
         #--
         # ====================================================================
         # MESSAGE DISPATCHER SETUP