net-ssh 1.1.4 → 2.0.0

data/lib/net/ssh/config.rb

@@ -0,0 +1,173 @@
+module Net; module SSH
+
+  # The Net::SSH::Config class is used to parse OpenSSH configuration files,
+  # and translates that syntax into the configuration syntax that Net::SSH
+  # understands. This lets Net::SSH scripts read their configuration (to
+  # some extent) from OpenSSH configuration files (~/.ssh/config, /etc/ssh_config,
+  # and so forth).
+  #
+  # Only a subset of OpenSSH configuration options are understood:
+  #
+  # * Ciphers => maps to the :encryption option
+  # * Compression => :compression
+  # * CompressionLevel => :compression_level
+  # * ConnectTimeout => maps to the :timeout option
+  # * ForwardAgent => :forward_agent
+  # * GlobalKnownHostsFile => :global_known_hosts_file
+  # * HostBasedAuthentication => maps to the :auth_methods option
+  # * HostKeyAlgorithms => maps to :host_key option
+  # * HostKeyAlias => :host_key_alias
+  # * HostName => :host_name
+  # * IdentityFile => maps to the :keys option
+  # * Macs => maps to the :hmac option
+  # * PasswordAuthentication => maps to the :auth_methods option
+  # * Port => :port
+  # * PreferredAuthentications => maps to the :auth_methods option
+  # * RekeyLimit => :rekey_limit
+  # * User => :user
+  # * UserKnownHostsFile => :user_known_hosts_file
+  #
+  # Note that you will never need to use this class directly--you can control
+  # whether the OpenSSH configuration files are read by passing the :config
+  # option to Net::SSH.start. (They are, by default.)
+  class Config
+    class <<self
+      @@default_files = %w(~/.ssh/config /etc/ssh_config /etc/ssh/ssh_config)
+
+      # Returns an array of locations of OpenSSH configuration files
+      # to parse by default.
+      def default_files
+        @@default_files
+      end
+
+      # Loads the configuration data for the given +host+ from all of the
+      # given +files+ (defaulting to the list of files returned by
+      # #default_files), translates the resulting hash into the options
+      # recognized by Net::SSH, and returns them.
+      def for(host, files=default_files)
+        translate(files.inject({}) { |settings, file| load(file, host, settings) })
+      end
+
+      # Load the OpenSSH configuration settings in the given +file+ for the
+      # given +host+. If +settings+ is given, the options are merged into
+      # that hash, with existing values taking precedence over newly parsed
+      # ones. Returns a hash containing the OpenSSH options. (See
+      # #translate for how to convert the OpenSSH options into Net::SSH
+      # options.)
+      def load(file, host, settings={})
+        file = File.expand_path(file)
+        return settings unless File.readable?(file)
+
+        in_match = false
+        IO.foreach(file) do |line|
+          next if line =~ /^\s*(?:#.*)?$/
+
+          key, value = line.strip.split(/\s+/, 2)
+          key.downcase!
+
+          value = $1 if value =~ /^"(.*)"$/
+          value = case value.strip
+            when /^\d+$/ then value.to_i
+            when /^no$/i then false
+            when /^yes$/i then true
+            else value
+            end
+
+          if key == 'host'
+            in_match = (host =~ pattern2regex(value))
+          elsif in_match
+            if key == 'identityfile'
+              settings[key] ||= []
+              settings[key] << value
+            else
+              settings[key] = value unless settings.key?(key)
+            end
+          end
+        end
+
+        return settings
+      end
+
+      # Given a hash of OpenSSH configuration options, converts them into
+      # a hash of Net::SSH options. Unrecognized options are ignored. The
+      # +settings+ hash must have Strings for keys, all downcased, and
+      # the returned hash will have Symbols for keys.
+      def translate(settings)
+        settings.inject({}) do |hash, (key, value)|
+          case key
+          when 'ciphers' then
+            hash[:encryption] = value.split(/,/)
+          when 'compression' then
+            hash[:compression] = value
+          when 'compressionlevel' then
+            hash[:compression_level] = value
+          when 'connecttimeout' then
+            hash[:timeout] = value
+          when 'forwardagent' then
+            hash[:forward_agent] = value
+          when 'globalknownhostsfile'
+            hash[:global_known_hosts_file] = value
+          when 'hostbasedauthentication' then
+            if value
+              hash[:auth_methods] ||= []
+              hash[:auth_methods] << "hostbased"
+            end
+          when 'hostkeyalgorithms' then
+            hash[:host_key] = value.split(/,/)
+          when 'hostkeyalias' then
+            hash[:host_key_alias] = value
+          when 'hostname' then
+            hash[:host_name] = value
+          when 'identityfile' then
+            hash[:keys] = value
+          when 'macs' then
+            hash[:hmac] = value.split(/,/)
+          when 'passwordauthentication'
+            if value
+              hash[:auth_methods] ||= []
+              hash[:auth_methods] << "password"
+            end
+          when 'port'
+            hash[:port] = value
+          when 'preferredauthentications'
+            hash[:auth_methods] = value.split(/,/)
+          when 'pubkeyauthentication'
+            if value
+              hash[:auth_methods] ||= []
+              hash[:auth_methods] << "publickey"
+            end
+          when 'rekeylimit'
+            hash[:rekey_limit] = interpret_size(value)
+          when 'user'
+            hash[:user] = value
+          when 'userknownhostsfile'
+            hash[:user_known_hosts_file] = value
+          end
+          hash
+        end
+      end
+
+      private
+
+        # Converts an ssh_config pattern into a regex for matching against
+        # host names.
+        def pattern2regex(pattern)
+          pattern = "^" + pattern.gsub(/\./, "\\.").
+            gsub(/\?/, '.').
+            gsub(/\*/, '.*') + "$"
+          Regexp.new(pattern, true)
+        end
+
+        # Converts the given size into an integer number of bytes.
+        def interpret_size(size)
+          case size
+          when /k$/i then size.to_i * 1024
+          when /m$/i then size.to_i * 1024 * 1024
+          when /g$/i then size.to_i * 1024 * 1024 * 1024
+          else size.to_i
+          end
+        end
+    end
+  end
+
+end; end

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

@@ -1,504 +1,625 @@
-#--
-# =============================================================================
-# Copyright (c) 2004,2005 Jamis Buck (jamis@37signals.com)
-# 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/loggable'
 require 'net/ssh/connection/constants'
 require 'net/ssh/connection/term'
 
-module Net
-  module SSH
-    module Connection
-
-      class Channel
-        include Constants
-
-        #--
-        # ====================================================================
-        # ATTRIBUTES
-        # ====================================================================
-        #++
-
-        # The channel's local id (assigned by the connection)
-        attr_reader :local_id
-
-        # The channel's remote id (assigned by the remote server)
-        attr_reader :remote_id
-
-        # The connection driver instance that owns this channel
-        attr_reader :connection
-
-        # The type of this channel
-        attr_reader :type
-        
-        # The maximum packet size that may be sent over this channel
-        attr_reader :maximum_packet_size
-
-        # The maximum data window size for this channel
-        attr_reader :window_size
-
-        # The maximum packet size that may be sent over this channel
-        attr_reader :local_maximum_packet_size
-
-        # The maximum data window size for this channel
-        attr_reader :local_window_size
-
-        #--
-        # ====================================================================
-        # FACTORY METHODS
-        # ====================================================================
-        #++
-
-        # Requests that a new channel be opened on the remote host.
-        # This will return immediately, but the +on_confirm_open+ callback
-        # will be invoked when the remote host confirms that the channel has
-        # been successfully opened.
-        def self.open( connection, log, buffers, type, data=nil )
-          channel = new( connection, log, buffers, type )
-
-          msg = buffers.writer
-
-          msg.write_byte CHANNEL_OPEN
-          msg.write_string type
-          msg.write_long channel.local_id
-          msg.write_long channel.local_window_size
-          msg.write_long channel.local_maximum_packet_size
-          msg.write data.to_s if data
-
-          connection.send_message msg
-
-          channel
-        end
-
-        # Creates a new channel object with the given internal
-        # information. The channel is assumed to already be
-        # connected to a remote host.
-        def self.create( connection, log, buffers, type, remote_id,
-          window_size, packet_size )
-        # begin
-          channel = new( connection, log, buffers, type )
-          channel.do_confirm_open remote_id, window_size, packet_size
-          channel
-        end
-
-        private_class_method :new
-
-        #--
-        # ====================================================================
-        # CONSTRUCTOR
-        # ====================================================================
-        #++
-
-        # Create a new channel object on the given connection, and of the given
-        # type.
-        def initialize( connection, log, buffers, type )
-          @connection = connection
-          @log = log
-          @buffers = buffers
-          @type = type
-          @local_id = @connection.allocate_channel_id
-          @local_window_size = 0x20000
-          @local_maximum_packet_size = 0x10000
-        end
-
-        #--
-        # ====================================================================
-        # CALLBACK HOOKS
-        # ====================================================================
-        #++
-
-        # Set the callback to use when the channel has been confirmed
-        # to be open.
-        def on_confirm_open( &block )
-          @on_confirm_open = block
-        end
-
-        # Set the callback to use when the channel could not be opened
-        # for some reason.
-        def on_confirm_failed( &block )
-          @on_confirm_failed = block
-        end
+module Net; module SSH; module Connection
+
+  # The channel abstraction. Multiple "channels" can be multiplexed onto a
+  # single SSH channel, each operating independently and seemingly in parallel.
+  # This class represents a single such channel. Most operations performed
+  # with the Net::SSH library will involve using one or more channels.
+  #
+  # Channels are intended to be used asynchronously. You request that one be
+  # opened (via Connection::Session#open_channel), and when it is opened, your
+  # callback is invoked. Then, you set various other callbacks on the newly
+  # opened channel, which are called in response to the corresponding events.
+  # Programming with Net::SSH works best if you think of your programs as
+  # state machines. Complex programs are best implemented as objects that
+  # wrap a channel. See Net::SCP and Net::SFTP for examples of how complex
+  # state machines can be built on top of the SSH protocol.
+  #
+  #   ssh.open_channel do |channel|
+  #     channel.exec("/invoke/some/command") do |ch, success|
+  #       abort "could not execute command" unless success
+  #
+  #       channel.on_data do |ch, data|
+  #         puts "got stdout: #{data}"
+  #         channel.send_data "something for stdin\n"
+  #       end
+  #
+  #       channel.on_extended_data do |ch, type, data|
+  #         puts "got stderr: #{data}"
+  #       end
+  #
+  #       channel.on_close do |ch|
+  #         puts "channel is closing!"
+  #       end
+  #     end
+  #   end
+  #
+  #   ssh.loop
+  #
+  # Channels also have a basic hash-like interface, that allows programs to
+  # store arbitrary state information on a channel object. This helps simplify
+  # the writing of state machines, especially when you may be juggling
+  # multiple open channels at the same time.
+  #
+  # Note that data sent across SSH channels are governed by maximum packet
+  # sizes and maximum window sizes. These details are managed internally
+  # by Net::SSH::Connection::Channel, so you may remain blissfully ignorant
+  # if you so desire, but you can always inspect the current maximums, as
+  # well as the remaining window size, using the reader attributes for those
+  # values.
+  class Channel
+    include Constants, Loggable
+
+    # The local id for this channel, assigned by the Net::SSH::Connection::Session instance.
+    attr_reader :local_id
+
+    # The remote id for this channel, assigned by the remote host.
+    attr_reader :remote_id
+
+    # The type of this channel, usually "session".
+    attr_reader :type
+
+    # The underlying Net::SSH::Connection::Session instance that supports this channel.
+    attr_reader :connection
+
+    # The maximum packet size that the local host can receive.
+    attr_reader :local_maximum_packet_size
+
+    # The maximum amount of data that the local end of this channel can
+    # receive. This is a total, not per-packet.
+    attr_reader :local_maximum_window_size
+
+    # The maximum packet size that the remote host can receive.
+    attr_reader :remote_maximum_packet_size
+
+    # The maximum amount of data that the remote end of this channel can
+    # receive. This is a total, not per-packet.
+    attr_reader :remote_maximum_window_size
+
+    # This is the remaining window size on the local end of this channel. When
+    # this reaches zero, no more data can be received.
+    attr_reader :local_window_size
+
+    # This is the remaining window size on the remote end of this channel. When
+    # this reaches zero, no more data can be sent.
+    attr_reader :remote_window_size
+
+    # A hash of properties for this channel. These can be used to store state
+    # information about this channel. See also #[] and #[]=.
+    attr_reader :properties
+
+    # The output buffer for this channel. Data written to the channel is
+    # enqueued here, to be written as CHANNEL_DATA packets during each pass of
+    # the event loop. See Connection::Session#process and #enqueue_pending_output.
+    attr_reader :output #:nodoc:
+
+    # The list of pending requests. Each time a request is sent which requires
+    # a reply, the corresponding callback is pushed onto this queue. As responses
+    # arrive, they are shifted off the front and handled.
+    attr_reader :pending_requests #:nodoc:
+
+    # Instantiates a new channel on the given connection, of the given type,
+    # and with the given id. If a block is given, it will be remembered until
+    # the channel is confirmed open by the server, and will be invoked at
+    # that time (see #do_open_confirmation).
+    #
+    # This also sets the default maximum packet size and maximum window size.
+    def initialize(connection, type, local_id, &on_confirm_open)
+      self.logger = connection.logger
+
+      @connection = connection
+      @type       = type
+      @local_id   = local_id
+
+      @local_maximum_packet_size = 0x10000
+      @local_window_size = @local_maximum_window_size = 0x20000
+
+      @on_confirm_open = on_confirm_open
+
+      @output = Buffer.new
+
+      @properties = {}
+
+      @pending_requests = []
+      @on_open_failed = @on_data = @on_extended_data = @on_process = @on_close = @on_eof = nil
+      @on_request = {}
+      @closing = @eof = false
+    end
 
-        # Set the callback to be invoked when the server requests
-        # that the window size be adjusted.
-        def on_window_adjust( &block )
-          @on_window_adjust = block
-        end
+    # A shortcut for accessing properties of the channel (see #properties).
+    def [](name)
+      @properties[name]
+    end
 
-        # Set the callback to be invoked when the server sends a
-        # data packet over the channel.
-        def on_data( &block )
-          @on_data = block
-        end
+    # A shortcut for setting properties of the channel (see #properties).
+    def []=(name, value)
+      @properties[name] = value
+    end
 
-        # Set the callback to be invoked when the server sends an
-        # extended data packet over the channel.
-        def on_extended_data( &block )
-          @on_extended_data = block
-        end
+    # Syntactic sugar for executing a command. Sends a channel request asking
+    # that the given command be invoked. If the block is given, it will be
+    # called when the server responds. The first parameter will be the
+    # channel, and the second will be true or false, indicating whether the
+    # request succeeded or not. In this case, success means that the command
+    # is being executed, not that it has completed, and failure means that the
+    # command altogether failed to be executed.
+    #
+    #   channel.exec "ls -l /home" do |ch, success|
+    #     if success
+    #       puts "command has begun executing..."
+    #       # this is a good place to hang callbacks like #on_data...
+    #     else
+    #       puts "alas! the command could not be invoked!"
+    #     end
+    #   end
+    def exec(command, &block)
+      send_channel_request("exec", :string, command, &block)
+    end
 
-        # Set the callback to be invoked when the server sends an EOF
-        # packet.
-        def on_eof( &block )
-          @on_eof = block
-        end
+    # Syntactic sugar for requesting that a subsystem be started. Subsystems
+    # are a way for other protocols (like SFTP) to be run, using SSH as
+    # the transport. Generally, you'll never need to call this directly unless
+    # you are the implementor of something that consumes an SSH subsystem, like
+    # SFTP.
+    #
+    #   channel.subsystem("sftp") do |ch, success|
+    #     if success
+    #       puts "subsystem successfully started"
+    #     else
+    #       puts "subsystem could not be started"
+    #     end
+    #   end
+    def subsystem(subsystem, &block)
+      send_channel_request("subsystem", :string, subsystem, &block)
+    end
 
-        # Set the callback to be invoked when the server sends a
-        # request packet.
-        def on_request( &block )
-          @on_request = block
-        end
+    # Syntactic sugar for setting an environment variable in the remote
+    # process' environment. Note that for security reasons, the server may
+    # refuse to set certain environment variables, or all, at the server's
+    # discretion. If you are connecting to an OpenSSH server, you will
+    # need to update the AcceptEnv setting in the sshd_config to include the
+    # environment variables you want to send.
+    #
+    #   channel.env "PATH", "/usr/local/bin"
+    def env(variable_name, variable_value, &block)
+      send_channel_request("env", :string, variable_name, :string, variable_value, &block)
+    end
 
-        # Set the callback to invoked when the server sends
-        # confirmation of a successful operation.
-        def on_success( &block )
-          @on_success = block
-        end
+    # A hash of the valid PTY options (see #request_pty).
+    VALID_PTY_OPTIONS = { :term        => "xterm",
+                          :chars_wide  => 80,
+                          :chars_high  => 24,
+                          :pixels_wide => 640,
+                          :pixels_high => 480,
+                          :modes       => {} }
+
+    # Requests that a pseudo-tty (or "pty") be made available for this channel.
+    # This is useful when you want to invoke and interact with some kind of
+    # screen-based program (e.g., vim, or some menuing system).
+    #
+    # Note, that without a pty some programs (e.g. sudo, or subversion) on
+    # some systems, will not be able to run interactively, and will error
+    # instead of prompt if they ever need some user interaction.
+    #
+    # Note, too, that when a pty is requested, user's shell configuration
+    # scripts (.bashrc and such) are not run by default, whereas they are
+    # run when a pty is not present.
+    #
+    #   channel.request_pty do |ch, success|
+    #     if success
+    #       puts "pty successfully obtained"
+    #     else
+    #       puts "could not obtain pty"
+    #     end
+    #   end
+    def request_pty(opts={}, &block)
+      extra = opts.keys - VALID_PTY_OPTIONS.keys
+      raise ArgumentError, "invalid option(s) to request_pty: #{extra.inspect}" if extra.any?
+
+      opts = VALID_PTY_OPTIONS.merge(opts)
+
+      modes = opts[:modes].inject(Buffer.new) do |memo, (mode, data)|
+        memo.write_byte(mode).write_long(data)
+      end
+      # mark the end of the mode opcode list with a 0 byte
+      modes.write_byte(0)
 
-        # Set the callback to invoked when the server sends
-        # notification of a failed operation.
-        def on_failure( &block )
-          @on_failure = block
-        end
+      send_channel_request("pty-req", :string, opts[:term],
+        :long, opts[:chars_wide], :long, opts[:chars_high],
+        :long, opts[:pixels_wide], :long, opts[:pixels_high],
+        :string, modes.to_s, &block)
+    end
 
-        # Set the callback to be invoked when the channel is closed.
-        def on_close( &block )
-          @on_close = block
-        end
+    # Sends data to the channel's remote endpoint. This usually has the
+    # effect of sending the given string to the remote process' stdin stream.
+    # Note that it does not immediately send the data across the channel,
+    # but instead merely appends the given data to the channel's output buffer,
+    # preparatory to being packaged up and sent out the next time the connection
+    # is accepting data. (A connection might not be accepting data if, for
+    # instance, it has filled its data window and has not yet been resized by
+    # the remote end-point.)
+    #
+    # This will raise an exception if the channel has previously declared
+    # that no more data will be sent (see #eof!).
+    #
+    #   channel.send_data("the password\n")
+    def send_data(data)
+      raise EOFError, "cannot send data if channel has declared eof" if eof?
+      output.append(data.to_s)
+    end
 
-        #--
-        # ====================================================================
-        # CHANNEL STATE ACCESSORS
-        # ====================================================================
-        #++
+    # Returns true if the channel exists in the channel list of the session,
+    # and false otherwise. This can be used to determine whether a channel has
+    # been closed or not.
+    #
+    #   ssh.loop { channel.active? }
+    def active?
+      connection.channels.key?(local_id)
+    end
 
-        def valid?
-          not @local_id.nil?
-        end
+    # Runs the SSH event loop until the channel is no longer active. This is
+    # handy for blocking while you wait for some channel to finish.
+    #
+    #   channel.exec("grep ...") { ... }
+    #   channel.wait
+    def wait
+      connection.loop { active? }
+    end
 
-        # Retrieved a named property of the channel.
-        def property( name )
-          ( @properties ||= Hash.new )[ name ]
-        end
+    # Returns true if the channel is currently closing, but not actually
+    # closed. A channel is closing when, for instance, #close has been
+    # invoked, but the server has not yet responded with a CHANNEL_CLOSE
+    # packet of its own.
+    def closing?
+      @closing
+    end
 
-        # Set a named property on the channel.
-        def set_property( name, value )
-          ( @properties ||= Hash.new )[ name ] = value
-        end
+    # Requests that the channel be closed. If the channel is already closing,
+    # this does nothing, nor does it do anything if the channel has not yet
+    # been confirmed open (see #do_open_confirmation). Otherwise, it sends a
+    # CHANNEL_CLOSE message and marks the channel as closing.
+    def close
+      return if @closing
+      if remote_id
+        @closing = true
+        connection.send_message(Buffer.from(:byte, CHANNEL_CLOSE, :long, remote_id))
+      end
+    end
 
-        alias :[]  :property
-        alias :[]= :set_property
-
-        #--
-        # ====================================================================
-        # CHANNEL AFFECTORS
-        # ====================================================================
-        #++
-
-        # Closes the channel.
-        def close( client_initiated=true )
-          unless defined?(@already_closed) && @already_closed
-            msg = @buffers.writer
-            msg.write_byte CHANNEL_CLOSE
-            msg.write_long @remote_id
-            @connection.send_message msg
-            @already_closed = true
-          end
+    # Returns true if the local end of the channel has declared that no more
+    # data is forthcoming (see #eof!). Trying to send data via #send_data when
+    # this is true will result in an exception being raised.
+    def eof?
+      @eof
+    end
 
-          unless client_initiated
-            @connection.remove_channel( self )
-            callback :close, self
-          end
+    # Tells the remote end of the channel that no more data is forthcoming
+    # from this end of the channel. The remote end may still send data.
+    def eof!
+      return if eof?
+      @eof = true
+      connection.send_message(Buffer.from(:byte, CHANNEL_EOF, :long, remote_id))
+    end
 
-          self
-        end
+    # If an #on_process handler has been set up, this will cause it to be
+    # invoked (passing the channel itself as an argument). It also causes all
+    # pending output to be enqueued as CHANNEL_DATA packets (see #enqueue_pending_output).
+    def process
+      @on_process.call(self) if @on_process
+      enqueue_pending_output
+    end
 
-        # Send an EOF across the channel. No data should be sent from the client
-        # to the server over this channel after this, although packets may still
-        # be received from the server.
-        def send_eof
-          msg = @buffers.writer
-          msg.write_byte CHANNEL_EOF
-          msg.write_long @remote_id
-          @connection.send_message msg
-          self
-        end
+    # Registers a callback to be invoked when data packets are received by the
+    # channel. The callback is called with the channel as the first argument,
+    # and the data as the second.
+    #
+    #   channel.on_data do |ch, data|
+    #     puts "got data: #{data.inspect}"
+    #   end
+    #
+    # Data received this way is typically the data written by the remote
+    # process to its +stdout+ stream.
+    def on_data(&block)
+      old, @on_data = @on_data, block
+      old
+    end
 
-        # Send the given signal to process on the other side of the channel. The
-        # parameter should be one of the Channel::SIGxxx constants.
-        def send_signal( sig, want_reply=false )
-          send_request_string "signal", sig, want_reply
-          self
-        end
+    # Registers a callback to be invoked when extended data packets are received
+    # by the channel. The callback is called with the channel as the first
+    # argument, the data type (as an integer) as the second, and the data as
+    # the third. Extended data is almost exclusively used to send +stderr+ data
+    # (+type+ == 1). Other extended data types are not defined by the SSH
+    # protocol.
+    #
+    #   channel.on_extended_data do |ch, type, data|
+    #     puts "got stderr: #{data.inspect}"
+    #   end
+    def on_extended_data(&block)
+      old, @on_extended_data = @on_extended_data, block
+      old
+    end
 
-        # Send a channel request with the given name. It will have one data
-        # item, which will be interpreted as a string.
-        def send_request_string( request_name, data, want_reply=false )
-          msg = @buffers.writer
-          msg.write_string data.to_s
-          send_request request_name, msg, want_reply
-        end
+    # Registers a callback to be invoked for each pass of the event loop for
+    # this channel. There are no guarantees on timeliness in the event loop,
+    # but it will be called roughly once for each packet received by the
+    # connection (not the channel). This callback is invoked with the channel
+    # as the sole argument.
+    #
+    # Here's an example that accumulates the channel data into a variable on
+    # the channel itself, and displays individual lines in the input one
+    # at a time when the channel is processed:
+    #
+    #   channel[:data] = ""
+    #
+    #   channel.on_data do |ch, data|
+    #     channel[:data] << data
+    #   end
+    #
+    #   channel.on_process do |ch|
+    #     if channel[:data] =~ /^.*?\n/
+    #       puts $&
+    #       channel[:data] = $'
+    #     end
+    #   end
+    def on_process(&block)
+      old, @on_process = @on_process, block
+      old
+    end
 
-        # Send a generic channel request with the given name. The data item will
-        # be written directly into the request (after converting it to a string,
-        # as necessary).
-        def send_request( request_name, data, want_reply=false )
-          msg = @buffers.writer
-          msg.write_byte CHANNEL_REQUEST
-          msg.write_long @remote_id
-          msg.write_string request_name
-          msg.write_bool want_reply
-          msg.write data.to_s
-          @connection.send_message msg
-          self
-        end
+    # Registers a callback to be invoked when the server acknowledges that a
+    # channel is closed. This is invoked with the channel as the sole argument.
+    #
+    #   channel.on_close do |ch|
+    #     puts "remote end is closing!"
+    #   end
+    def on_close(&block)
+      old, @on_close = @on_close, block
+      old
+    end
 
-        # Send a "window adjust" message to the server for this channel,
-        # informing it that it may send this many more bytes over the
-        # channel.
-        def send_window_adjust( size )
-          msg = @buffers.writer
-          msg.write_byte CHANNEL_WINDOW_ADJUST
-          msg.write_long @remote_id
-          msg.write_long size
-          @connection.send_message msg
-        end
+    # Registers a callback to be invoked when the server indicates that no more
+    # data will be sent to the channel (although the channel can still send
+    # data to the server). The channel is the sole argument to the callback.
+    #
+    #   channel.on_eof do |ch|
+    #     puts "remote end is done sending data"
+    #   end
+    def on_eof(&block)
+      old, @on_eof = @on_eof, block
+      old
+    end
 
-        # Send a data packet to the server, over the channel.
-        def send_data( data )
-          @connection.register_data_request( self, data )
-        end
+    # Registers a callback to be invoked when the server was unable to open
+    # the requested channel. The channel itself will be passed to the block,
+    # along with the integer "reason code" for the failure, and a textual
+    # description of the failure from the server.
+    #
+    #   channel = session.open_channel do |ch|
+    #     # ..
+    #   end
+    #
+    #   channel.on_open_failed { |ch, code, desc| ... }
+    def on_open_failed(&block)
+      old, @on_open_failed = @on_open_failed, block
+      old
+    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
+    # Registers a callback to be invoked when a channel request of the given
+    # type is received. The callback will receive the channel as the first
+    # argument, and the associated (unparsed) data as the second. The data
+    # will be a Net::SSH::Buffer that you will need to parse, yourself,
+    # according to the kind of request you are watching.
+    #
+    # By default, if the request wants a reply, Net::SSH will send a
+    # CHANNEL_SUCCESS response for any request that was handled by a registered
+    # callback, and CHANNEL_FAILURE for any that wasn't, but if you want your
+    # registered callback to result in a CHANNEL_FAILURE response, just raise
+    # Net::SSH::ChannelRequestFailed.
+    #
+    # Some common channel requests that your programs might want to listen
+    # for are:
+    #
+    # * "exit-status" : the exit status of the remote process will be reported
+    #   as a long integer in the data buffer, which you can grab via
+    #   data.read_long.
+    # * "exit-signal" : if the remote process died as a result of a signal
+    #   being sent to it, the signal will be reported as a string in the
+    #   data, via data.read_string. (Not all SSH servers support this channel
+    #   request type.)
+    #
+    #   channel.on_request "exit-status" do |ch, data|
+    #     puts "process terminated with exit status: #{data.read_long}"
+    #   end
+    def on_request(type, &block)
+      old, @on_request[type] = @on_request[type], block
+      old
+    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
+    # Sends a new channel request with the given name. The extra +data+
+    # parameter must either be empty, or consist of an even number of
+    # arguments. See Net::SSH::Buffer.from for a description of their format.
+    # If a block is given, it is registered as a callback for a pending
+    # request, and the packet will be flagged so that the server knows a
+    # reply is required. If no block is given, the server will send no
+    # response to this request. Responses, where required, will cause the
+    # callback to be invoked with the channel as the first argument, and
+    # either true or false as the second, depending on whether the request
+    # succeeded or not. The meaning of "success" and "failure" in this context
+    # is dependent on the specific request that was sent.
+    #
+    #   channel.send_channel_request "shell" do |ch, success|
+    #     if success
+    #       puts "user shell started successfully"
+    #     else
+    #       puts "could not start user shell"
+    #     end
+    #   end
+    #
+    # Most channel requests you'll want to send are already wrapped in more
+    # convenient helper methods (see #exec and #subsystem).
+    def send_channel_request(request_name, *data, &callback)
+      info { "sending channel request #{request_name.inspect}" }
+      msg = Buffer.from(:byte, CHANNEL_REQUEST,
+        :long, remote_id, :string, request_name,
+        :bool, !callback.nil?, *data)
+      connection.send_message(msg)
+      pending_requests << callback if callback
+    end
 
-          max_size_less_overhead = maximum_packet_size - overhead
-          if data.length > max_size_less_overhead
-            data_to_return = data[max_size_less_overhead..-1] + ( data_to_return || "" )
-            data = data[0,max_size_less_overhead]
+    public # these methods are public, but for Net::SSH internal use only
+
+      # Enqueues pending output at the connection as CHANNEL_DATA packets. This
+      # does nothing if the channel has not yet been confirmed open (see
+      # #do_open_confirmation). This is called automatically by #process, which
+      # is called from the event loop (Connection::Session#process). You will
+      # generally not need to invoke it directly.
+      def enqueue_pending_output #:nodoc:
+        return unless remote_id
+
+        while output.length > 0
+          length = output.length
+          length = remote_window_size if length > remote_window_size
+          length = remote_maximum_packet_size if length > remote_maximum_packet_size
+
+          if length > 0
+            connection.send_message(Buffer.from(:byte, CHANNEL_DATA, :long, remote_id, :string, output.read(length)))
+            output.consume!
+            @remote_window_size -= length
+          else
+            break
           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
-          @connection.send_message msg
-
-          data_to_return
         end
+      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_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
-          @connection.send_message msg
-
-          data_to_return
-        end
-
-        VALID_PTY_OPTIONS = { :term=>"xterm",
-                              :chars_wide=>80,
-                              :chars_high=>24,
-                              :pixels_wide=>640,
-                              :pixels_high=>480,
-                              :modes=>{},
-                              :want_reply=>false }
-
-        # Request that a pty be opened for this channel. Valid options are
-        # :term, :chars_wide, :chars_high, :pixels_wide, :pixels_high, :modes,
-        # and :want_reply. :modes is a Hash, where the keys are constants from
-        # Net::SSH::Service::Term, and values are integers describing the
-        # corresponding key.
-        def request_pty( opts = {} )
-          invalid_opts = opts.keys - VALID_PTY_OPTIONS.keys
-          unless invalid_opts.empty?
-            raise ArgumentError,
-              "invalid option(s) to request_pty: #{invalid_opts.inspect}"
-          end
-
-          opts = VALID_PTY_OPTIONS.merge( opts )
+      # Invoked when the server confirms that a channel has been opened.
+      # The remote_id is the id of the channel as assigned by the remote host,
+      # and max_window and max_packet are the maximum window and maximum
+      # packet sizes, respectively. If an open-confirmation callback was
+      # given when the channel was created, it is invoked at this time with
+      # the channel itself as the sole argument.
+      def do_open_confirmation(remote_id, max_window, max_packet) #:nodoc:
+        @remote_id = remote_id
+        @remote_window_size = @remote_maximum_window_size = max_window
+        @remote_maximum_packet_size = max_packet
+        connection.forward.agent(self) if connection.options[:forward_agent] && type == "session"
+        @on_confirm_open.call(self) if @on_confirm_open
+      end
 
-          msg = @buffers.writer
-          msg.write_string opts[ :term ]
-          msg.write_long opts[ :chars_wide ]
-          msg.write_long opts[ :chars_high ]
-          msg.write_long opts[ :pixels_wide ]
-          msg.write_long opts[ :pixels_high ]
+      # Invoked when the server failed to open the channel. If an #on_open_failed
+      # callback was specified, it will be invoked with the channel, reason code,
+      # and description as arguments. Otherwise, a ChannelOpenFailed exception
+      # will be raised.
+      def do_open_failed(reason_code, description)
+        if @on_open_failed
+          @on_open_failed.call(self, reason_code, description)
+        else
+          raise ChannelOpenFailed.new(reason_code, description)
+        end          
+      end
 
-          modes = @buffers.writer
-          opts[ :modes ].each do |mode, data|
-            modes.write_byte mode
-            modes.write_long data
-          end
-          modes.write_byte Term::TTY_OP_END
+      # Invoked when the server sends a CHANNEL_WINDOW_ADJUST packet, and
+      # causes the remote window size to be adjusted upwards by the given
+      # number of bytes. This has the effect of allowing more data to be sent
+      # from the local end to the remote end of the channel.
+      def do_window_adjust(bytes) #:nodoc:
+        @remote_maximum_window_size += bytes
+        @remote_window_size += bytes
+      end
 
-          msg.write_string modes.to_s
+      # Invoked when the server sends a channel request. If any #on_request
+      # callback has been registered for the specific type of this request,
+      # it is invoked. If +want_reply+ is true, a packet will be sent of
+      # either CHANNEL_SUCCESS or CHANNEL_FAILURE type. If there was no callback
+      # to handle the request, CHANNEL_FAILURE will be sent. Otherwise,
+      # CHANNEL_SUCCESS, unless the callback raised ChannelRequestFailed. The
+      # callback should accept the channel as the first argument, and the
+      # request-specific data as the second.
+      def do_request(request, want_reply, data) #:nodoc:
+        result = true
 
-          send_request "pty-req", msg, opts[:want_reply]
+        begin
+          callback = @on_request[request] or raise ChannelRequestFailed
+          callback.call(self, data)
+        rescue ChannelRequestFailed
+          result = false
         end
 
-        # Execute the given remote command over the channel. This should be
-        # invoked in the "on_confirm" callback of a channel. This method will
-        # return immediately.
-        def exec( command, want_reply=false )
-          send_request_string "exec", command, want_reply
-        end
-
-        # Request the given subsystem. This method will return immediately.
-        def subsystem( subsystem, want_reply=true )
-          send_request_string "subsystem", subsystem, want_reply
+        if want_reply
+          msg = Buffer.from(:byte, result ? CHANNEL_SUCCESS : CHANNEL_FAILURE, :long, remote_id)
+          connection.send_message(msg)
         end
+      end
 
-        #--
-        # ====================================================================
-        # CHANNEL EVENTS
-        # ====================================================================
-        #++
-
-        # A convenience method for defining new event callbacks.
-        def self.event( event, *parameters )
-          define_method "do_#{event}" do |*args|
-            callback event, self, *args
-            self
-          end
-        end
+      # Invokes the #on_data callback when the server sends data to the
+      # channel. This will reduce the available window size on the local end,
+      # but does not actually throttle requests that come in illegally when
+      # the window size is too small. The callback is invoked with the channel
+      # as the first argument, and the data as the second.
+      def do_data(data) #:nodoc:
+        update_local_window_size(data.length)
+        @on_data.call(self, data) if @on_data
+      end
 
-        # Invoked when the server confirms the opening of a channel.
-        def do_confirm_open( remote_id, window_size, packet_size )
-          @remote_id = remote_id
-          @window_size = window_size
-          @maximum_packet_size = packet_size
-          callback :confirm_open, self
-        end
+      # Invokes the #on_extended_data callback when the server sends
+      # extended data to the channel. This will reduce the available window
+      # size on the local end. The callback is invoked with the channel,
+      # type, and data.
+      def do_extended_data(type, data)
+        update_local_window_size(data.length)
+        @on_extended_data.call(self, type, data) if @on_extended_data
+      end
 
-        # Invoked when the server failed to confirm the opening of a channel.
-        def do_confirm_failed( reason_code, description, language )
-          @local_id = nil
-          @connection = nil
-          callback :confirm_failed, self, reason_code, description, language
-        end
+      # Invokes the #on_eof callback when the server indicates that no
+      # further data is forthcoming. The callback is invoked with the channel
+      # as the argument.
+      def do_eof
+        @on_eof.call(self) if @on_eof
+      end
 
-        # Invoked when the server asks to adjust the window size. This in turn
-        # calls the "on_window_adjust" callback.
-        def do_window_adjust( bytes_to_add )
-          @window_size += bytes_to_add
-          callback :window_adjust, self, bytes_to_add
-        end
+      # Invokes the #on_close callback when the server closes a channel.
+      # The channel is the only argument.
+      def do_close
+        @on_close.call(self) if @on_close
+      end
 
-        # Invoked when the server sends a data packet. This in turn calls the
-        # "on_data" callback.
-        def do_data( data )
-          update_local_window_size data
-          callback :data, self, data
+      # Invokes the next pending request callback with +false+ as the second
+      # argument.
+      def do_failure
+        if callback = pending_requests.shift
+          callback.call(self, false)
+        else
+          error { "channel failure recieved with no pending request to handle it (bug?)" }
         end
+      end
 
-        # Invoked when the server sends an extended data packet. This in turn
-        # calls the "on_extended_data" callback.
-        def do_extended_data( type, data )
-          update_local_window_size data
-          callback :extended_data, self, type, data
+      # Invokes the next pending request callback with +true+ as the second
+      # argument.
+      def do_success
+        if callback = pending_requests.shift
+          callback.call(self, true)
+        else
+          error { "channel success recieved with no pending request to handle it (bug?)" }
         end
+      end
 
-        # Invoked when the server sends an EOF packet. This in turn calls the
-        # "on_eof" callback.
-        event :eof
-
-        # Invoked when the server sends a request packet. This in turn calls
-        # the "on_request" callback.
-        event :request, :type, :want_reply, :data
-
-        # Invoked when the server sends confirmation of a successful operation.
-        # This in turn invokes the "on_success" callback, if set.
-        event :success
-
-        # Invoked when the server sends notification of a failed operation.
-        # This in turn invokes the "on_failure" callback, if set.
-        event :failure
-
-        #--
-        # ====================================================================
-        # PRIVATE UTILITIES
-        # ====================================================================
-        #++
-
-        # Updates the window size for this channel based on the size of the
-        # data that was receieved. If no more space in the window is left,
-        # a message is sent to the server indicating that the window size
-        # is increased.
-        def update_local_window_size( data )
-          @local_window_size -= data.length
-          if @local_window_size < 4096
-            @local_window_size += 0x20000
-            send_window_adjust 0x20000
-          end
-        end
-        private :update_local_window_size
+    private
 
-        # A convenience utility method for invoking a named callback with a
-        # set of arguments.
-        def callback( which, *args )
-          block = instance_variable_get( "@on_#{which.to_s}" )
-          block.call( *args ) if block
+      # Updates the local window size by the given amount. If the window
+      # size drops to less than half of the local maximum (an arbitrary
+      # threshold), a CHANNEL_WINDOW_ADJUST message will be sent to the
+      # server telling it that the window size has grown.
+      def update_local_window_size(size)
+        @local_window_size -= size
+        if local_window_size < local_maximum_window_size/2
+          connection.send_message(Buffer.from(:byte, CHANNEL_WINDOW_ADJUST,
+            :long, remote_id, :long, 0x20000))
+          @local_window_size += 0x20000
+          @local_maximum_window_size += 0x20000
         end
-        private :callback
-
       end
-
-    end
   end
-end
+
+end; end; end