ddollar-net-ssh 2.0.1

data/lib/net/ssh/test/extensions.rb

@@ -0,0 +1,152 @@
+require 'net/ssh/buffer'
+require 'net/ssh/packet'
+require 'net/ssh/buffered_io'
+require 'net/ssh/connection/channel'
+require 'net/ssh/connection/constants'
+require 'net/ssh/transport/constants'
+require 'net/ssh/transport/packet_stream'
+
+module Net; module SSH; module Test
+
+  # A collection of modules used to extend/override the default behavior of
+  # Net::SSH internals for ease of testing. As a consumer of Net::SSH, you'll
+  # never need to use this directly--they're all used under the covers by
+  # the Net::SSH::Test system.
+  module Extensions
+
+    # An extension to Net::SSH::BufferedIo (assumes that the underlying IO
+    # is actually a StringIO). Facilitates unit testing.
+    module BufferedIo
+      # Returns +true+ if the position in the stream is less than the total
+      # length of the stream.
+      def select_for_read?
+        pos < size
+      end
+
+      # Set this to +true+ if you want the IO to pretend to be available for writing
+      attr_accessor :select_for_write
+
+      # Set this to +true+ if you want the IO to pretend to be in an error state
+      attr_accessor :select_for_error
+
+      alias select_for_write? select_for_write
+      alias select_for_error? select_for_error
+    end
+
+    # An extension to Net::SSH::Transport::PacketStream (assumes that the
+    # underlying IO is actually a StringIO). Facilitates unit testing.
+    module PacketStream
+      include BufferedIo # make sure we get the extensions here, too
+
+      def self.included(base) #:nodoc:
+        base.send :alias_method, :real_available_for_read?, :available_for_read?
+        base.send :alias_method, :available_for_read?, :test_available_for_read?
+
+        base.send :alias_method, :real_enqueue_packet, :enqueue_packet
+        base.send :alias_method, :enqueue_packet, :test_enqueue_packet
+
+        base.send :alias_method, :real_poll_next_packet, :poll_next_packet
+        base.send :alias_method, :poll_next_packet, :test_poll_next_packet
+      end
+
+      # Called when another packet should be inspected from the current
+      # script. If the next packet is a remote packet, it pops it off the
+      # script and shoves it onto this IO object, making it available to
+      # be read.
+      def idle!
+        return false unless script.next(:first)
+
+        if script.next(:first).remote?
+          self.string << script.next.to_s
+          self.pos = pos
+        end
+
+        return true
+      end
+
+      # The testing version of Net::SSH::Transport::PacketStream#available_for_read?.
+      # Returns true if there is data pending to be read. Otherwise calls #idle!.
+      def test_available_for_read?
+        return true if select_for_read?
+        idle!
+        false
+      end
+
+      # The testing version of Net::SSH::Transport::PacketStream#enqueued_packet.
+      # Simply calls Net::SSH::Test::Script#process on the packet.
+      def test_enqueue_packet(payload)
+        packet = Net::SSH::Buffer.new(payload.to_s)
+        script.process(packet)
+      end
+
+      # The testing version of Net::SSH::Transport::PacketStream#poll_next_packet.
+      # Reads the next available packet from the IO object and returns it.
+      def test_poll_next_packet
+        return nil if available <= 0
+        packet = Net::SSH::Buffer.new(read_available(4))
+        length = packet.read_long
+        Net::SSH::Packet.new(read_available(length))
+      end
+    end
+
+    # An extension to Net::SSH::Connection::Channel. Facilitates unit testing.
+    module Channel
+      def self.included(base) #:nodoc:
+        base.send :alias_method, :send_data_for_real, :send_data
+        base.send :alias_method, :send_data, :send_data_for_test
+      end
+
+      # The testing version of Net::SSH::Connection::Channel#send_data. Calls
+      # the original implementation, and then immediately enqueues the data for
+      # output so that scripted sends are properly interpreted as discrete
+      # (rather than concatenated) data packets.
+      def send_data_for_test(data)
+        send_data_for_real(data)
+        enqueue_pending_output
+      end
+    end
+
+    # An extension to the built-in ::IO class. Simply redefines IO.select
+    # so that it can be scripted in Net::SSH unit tests.
+    module IO
+      def self.included(base) #:nodoc:
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def self.extended(obj) #:nodoc:
+          class <<obj
+            alias_method :select_for_real, :select
+            alias_method :select, :select_for_test
+          end
+        end
+
+        # The testing version of ::IO.select. Assumes that all readers,
+        # writers, and errors arrays are either nil, or contain only objects
+        # that mix in Net::SSH::Test::Extensions::BufferedIo.
+        def select_for_test(readers=nil, writers=nil, errors=nil, wait=nil)
+          ready_readers = Array(readers).select { |r| r.select_for_read? }
+          ready_writers = Array(writers).select { |r| r.select_for_write? }
+          ready_errors  = Array(errors).select  { |r| r.select_for_error? }
+
+          if ready_readers.any? || ready_writers.any? || ready_errors.any?
+            return [ready_readers, ready_writers, ready_errors]
+          end
+
+          processed = 0
+          Array(readers).each do |reader|
+            processed += 1 if reader.idle!
+          end
+
+          raise "no readers were ready for reading, and none had any incoming packets" if processed == 0
+        end
+      end
+    end
+  end
+
+end; end; end
+
+Net::SSH::BufferedIo.send(:include, Net::SSH::Test::Extensions::BufferedIo)
+Net::SSH::Transport::PacketStream.send(:include, Net::SSH::Test::Extensions::PacketStream)
+Net::SSH::Connection::Channel.send(:include, Net::SSH::Test::Extensions::Channel)
+IO.send(:include, Net::SSH::Test::Extensions::IO)

data/lib/net/ssh/test/kex.rb

@@ -0,0 +1,44 @@
+require 'openssl'
+
+require 'net/ssh/errors'
+require 'net/ssh/transport/algorithms'
+require 'net/ssh/transport/constants'
+require 'net/ssh/transport/kex'
+
+module Net; module SSH; module Test
+
+  # An implementation of a key-exchange strategy specifically for unit tests.
+  # (This strategy would never really work against a real SSH server--it makes
+  # too many assumptions about the server's response.)
+  #
+  # This registers itself with the transport key-exchange system as the
+  # "test" algorithm.
+  class Kex
+    include Net::SSH::Transport::Constants
+
+    # Creates a new instance of the testing key-exchange algorithm with the
+    # given arguments.
+    def initialize(algorithms, connection, data)
+      @connection = connection
+    end
+
+    # Exchange keys with the server. This returns a hash of constant values,
+    # and does not actually exchange keys.
+    def exchange_keys
+      result = Net::SSH::Buffer.from(:byte, NEWKEYS)
+      @connection.send_message(result)
+
+      buffer = @connection.next_message
+      raise Net::SSH::Exception, "expected NEWKEYS" unless buffer.type == NEWKEYS
+
+      { :session_id        => "abc-xyz",
+        :server_key        => OpenSSL::PKey::RSA.new(32),
+        :shared_secret     => OpenSSL::BN.new("1234567890", 10),
+        :hashing_algorithm => OpenSSL::Digest::SHA1 }
+    end
+  end
+
+end; end; end
+
+Net::SSH::Transport::Algorithms::ALGORITHMS[:kex] << "test"
+Net::SSH::Transport::Kex::MAP["test"] = Net::SSH::Test::Kex

data/lib/net/ssh/test/local_packet.rb

@@ -0,0 +1,51 @@
+require 'net/ssh/packet'
+require 'net/ssh/test/packet'
+
+module Net; module SSH; module Test
+
+  # This is a specialization of Net::SSH::Test::Packet for representing mock
+  # packets that are sent from the local (client) host. These are created
+  # automatically by Net::SSH::Test::Script and Net::SSH::Test::Channel by any
+  # of the sends_* methods.
+  class LocalPacket < Packet
+    attr_reader :init
+
+    # Extend the default Net::SSH::Test::Packet constructor to also accept an
+    # optional block, which is used to finalize the initialization of the
+    # packet when #process is first called.
+    def initialize(type, *args, &block)
+      super(type, *args)
+      @init = block
+    end
+
+    # Returns +true+; this is a local packet.
+    def local?
+      true
+    end
+
+    # Called by Net::SSH::Test::Extensions::PacketStream#test_enqueue_packet
+    # to mimic remote processing of a locally-sent packet. It compares the
+    # packet it was given with the contents of this LocalPacket's data, to see
+    # if what was sent matches what was scripted. If it differs in any way,
+    # an exception is raised.
+    def process(packet)
+      @init.call(Net::SSH::Packet.new(packet.to_s)) if @init
+      type = packet.read_byte
+      raise "expected #{@type}, but got #{type}" if @type != type
+
+      @data.zip(types).each do |expected, type|
+        type ||= case expected
+          when nil then break
+          when Numeric then :long
+          when String then :string
+          when TrueClass, FalseClass then :bool
+          end
+
+        actual = packet.send("read_#{type}")
+        next if expected.nil?
+        raise "expected #{type} #{expected.inspect} but got #{actual.inspect}" unless expected == actual
+      end
+    end
+  end
+
+end; end; end

data/lib/net/ssh/test/packet.rb

@@ -0,0 +1,81 @@
+require 'net/ssh/connection/constants'
+require 'net/ssh/transport/constants'
+
+module Net; module SSH; module Test
+
+  # This is an abstract class, not to be instantiated directly, subclassed by
+  # Net::SSH::Test::LocalPacket and Net::SSH::Test::RemotePacket. It implements
+  # functionality common to those subclasses.
+  #
+  # These packets are not true packets, in that they don't represent what was
+  # actually sent between the hosst; rather, they represent what was expected
+  # to be sent, as dictated by the script (Net::SSH::Test::Script). Thus,
+  # though they are defined with data elements, these data elements are used
+  # to either validate data that was sent by the local host (Net::SSH::Test::LocalPacket)
+  # or to mimic the sending of data by the remote host (Net::SSH::Test::RemotePacket).
+  class Packet
+    include Net::SSH::Transport::Constants
+    include Net::SSH::Connection::Constants
+
+    # Ceate a new packet of the given +type+, and with +args+ being a list of
+    # data elements in the order expected for packets of the given +type+
+    # (see #types).
+    def initialize(type, *args)
+      @type = self.class.const_get(type.to_s.upcase)
+      @data = args
+    end
+
+    # The default for +remote?+ is false. Subclasses should override as necessary.
+    def remote?
+      false
+    end
+
+    # The default for +local?+ is false. Subclasses should override as necessary.
+    def local?
+      false
+    end
+
+    # Instantiates the packets data elements. When the packet was first defined,
+    # some elements may not have been fully realized, and were described as
+    # Proc objects rather than atomic types. This invokes those Proc objects
+    # and replaces them with their returned values. This allows for values 
+    # like Net::SSH::Test::Channel#remote_id to be used in scripts before
+    # the remote_id is known (since it is only known after a channel has been
+    # confirmed open).
+    def instantiate!
+      @data.map! { |i| i.respond_to?(:call) ? i.call : i }
+    end
+
+    # Returns an array of symbols describing the data elements for packets of
+    # the same type as this packet. These types are used to either validate
+    # sent packets (Net::SSH::Test::LocalPacket) or build received packets
+    # (Net::SSH::Test::RemotePacket).
+    #
+    # Not all packet types are defined here. As new packet types are required
+    # (e.g., a unit test needs to test that the remote host sent a packet that
+    # is not implemented here), the description of that packet should be
+    # added. Unsupported packet types will otherwise raise an exception.
+    def types
+      @types ||= case @type
+        when KEXINIT then 
+          [:long, :long, :long, :long,
+           :string, :string, :string, :string, :string, :string, :string, :string, :string, :string,
+           :bool]
+        when NEWKEYS then []
+        when CHANNEL_OPEN then [:string, :long, :long, :long]
+        when CHANNEL_OPEN_CONFIRMATION then [:long, :long, :long, :long]
+        when CHANNEL_DATA then [:long, :string]
+        when CHANNEL_EOF, CHANNEL_CLOSE, CHANNEL_SUCCESS, CHANNEL_FAILURE then [:long]
+        when CHANNEL_REQUEST
+          parts = [:long, :string, :bool]
+          case @data[1]
+          when "exec", "subsystem" then parts << :string
+          when "exit-status" then parts << :long
+          else raise "don't know what to do about #{@data[1]} channel request"
+          end
+        else raise "don't know how to parse packet type #{@type}"
+        end
+    end
+  end
+
+end; end; end

data/lib/net/ssh/test/remote_packet.rb

@@ -0,0 +1,38 @@
+require 'net/ssh/buffer'
+require 'net/ssh/test/packet'
+
+module Net; module SSH; module Test
+
+  # This is a specialization of Net::SSH::Test::Packet for representing mock
+  # packets that are received by the local (client) host. These are created
+  # automatically by Net::SSH::Test::Script and Net::SSH::Test::Channel by any
+  # of the gets_* methods.
+  class RemotePacket < Packet
+    # Returns +true+; this is a remote packet.
+    def remote?
+      true
+    end
+
+    # The #process method should only be called on Net::SSH::Test::LocalPacket
+    # packets; if it is attempted on a remote packet, then it is an expectation
+    # mismatch (a remote packet was received when a local packet was expected
+    # to be sent). This will happen when either your test script
+    # (Net::SSH::Test::Script) or your program are wrong.
+    def process(packet)
+      raise "received packet type #{packet.read_byte} and was not expecting any packet"
+    end
+
+    # Returns this remote packet as a string, suitable for parsing by 
+    # Net::SSH::Transport::PacketStream and friends. When a remote packet is
+    # received, this method is called and the result concatenated onto the
+    # input buffer for the packet stream.
+    def to_s
+      @to_s ||= begin
+        instantiate!
+        string = Net::SSH::Buffer.from(:byte, @type, *types.zip(@data).flatten).to_s
+        [string.length, string].pack("NA*")
+      end
+    end
+  end
+
+end; end; end

data/lib/net/ssh/test/script.rb

@@ -0,0 +1,157 @@
+require 'net/ssh/test/channel'
+require 'net/ssh/test/local_packet'
+require 'net/ssh/test/remote_packet'
+
+module Net; module SSH; module Test
+
+  # Represents a sequence of scripted events that identify the behavior that
+  # a test expects. Methods named "sends_*" create events for packets being
+  # sent from the local to the remote host, and methods named "gets_*" create
+  # events for packets being received by the local from the remote host.
+  #
+  # A reference to a script. is generally obtained in a unit test via the
+  # Net::SSH::Test#story helper method:
+  #
+  #   story do |script|
+  #     channel = script.opens_channel
+  #     ...
+  #   end
+  class Script
+    # The list of scripted events. These will be Net::SSH::Test::LocalPacket
+    # and Net::SSH::Test::RemotePacket instances.
+    attr_reader :events
+
+    # Create a new, empty script.
+    def initialize
+      @events = []
+    end
+
+    # Scripts the opening of a channel by adding a local packet sending the
+    # channel open request, and if +confirm+ is true (the default), also
+    # adding a remote packet confirming the new channel.
+    #
+    # A new Net::SSH::Test::Channel instance is returned, which can be used
+    # to script additional channel operations.
+    def opens_channel(confirm=true)
+      channel = Channel.new(self)
+      channel.remote_id = 5555
+
+      events << LocalPacket.new(:channel_open) { |p| channel.local_id = p[:remote_id] }
+
+      if confirm
+        events << RemotePacket.new(:channel_open_confirmation, channel.local_id, channel.remote_id, 0x20000, 0x10000)
+      end
+
+      channel
+    end
+
+    # A convenience method for adding an arbitrary local packet to the events
+    # list.
+    def sends(type, *args, &block)
+      events << LocalPacket.new(type, *args, &block)
+    end
+
+    # A convenience method for adding an arbitrary remote packet to the events
+    # list.
+    def gets(type, *args)
+      events << RemotePacket.new(type, *args)
+    end
+
+    # Scripts the sending of a new channel request packet to the remote host.
+    # +channel+ should be an instance of Net::SSH::Test::Channel. +request+
+    # is a string naming the request type to send, +reply+ is a boolean
+    # indicating whether a response to this packet is required , and +data+
+    # is any additional request-specific data that this packet should send.
+    # +success+ indicates whether the response (if one is required) should be
+    # success or failure.
+    #
+    # If a reply is desired, a remote packet will also be queued, :channel_success
+    # if +success+ is true, or :channel_failure if +success+ is false.
+    #
+    # This will typically be called via Net::SSH::Test::Channel#sends_exec or
+    # Net::SSH::Test::Channel#sends_subsystem.
+    def sends_channel_request(channel, request, reply, data, success=true)
+      events << LocalPacket.new(:channel_request, channel.remote_id, request, reply, data)
+      if reply
+        if success
+          events << RemotePacket.new(:channel_success, channel.local_id)
+        else
+          events << RemotePacket.new(:channel_failure, channel.local_id)
+        end
+      end
+    end
+
+    # Scripts the sending of a channel data packet. +channel+ must be a
+    # Net::SSH::Test::Channel object, and +data+ is the (string) data to
+    # expect will be sent.
+    #
+    # This will typically be called via Net::SSH::Test::Channel#sends_data.
+    def sends_channel_data(channel, data)
+      events << LocalPacket.new(:channel_data, channel.remote_id, data)
+    end
+
+    # Scripts the sending of a channel EOF packet from the given
+    # Net::SSH::Test::Channel +channel+. This will typically be called via
+    # Net::SSH::Test::Channel#sends_eof.
+    def sends_channel_eof(channel)
+      events << LocalPacket.new(:channel_eof, channel.remote_id)
+    end
+
+    # Scripts the sending of a channel close packet from the given
+    # Net::SSH::Test::Channel +channel+. This will typically be called via
+    # Net::SSH::Test::Channel#sends_close.
+    def sends_channel_close(channel)
+      events << LocalPacket.new(:channel_close, channel.remote_id)
+    end
+
+    # Scripts the reception of a channel data packet from the remote host by
+    # the given Net::SSH::Test::Channel +channel+. This will typically be
+    # called via Net::SSH::Test::Channel#gets_data.
+    def gets_channel_data(channel, data)
+      events << RemotePacket.new(:channel_data, channel.local_id, data)
+    end
+
+    # Scripts the reception of a channel request packet from the remote host by
+    # the given Net::SSH::Test::Channel +channel+. This will typically be
+    # called via Net::SSH::Test::Channel#gets_exit_status.
+    def gets_channel_request(channel, request, reply, data)
+      events << RemotePacket.new(:channel_request, channel.local_id, request, reply, data)
+    end
+
+    # Scripts the reception of a channel EOF packet from the remote host by
+    # the given Net::SSH::Test::Channel +channel+. This will typically be
+    # called via Net::SSH::Test::Channel#gets_eof.
+    def gets_channel_eof(channel)
+      events << RemotePacket.new(:channel_eof, channel.local_id)
+    end
+
+    # Scripts the reception of a channel close packet from the remote host by
+    # the given Net::SSH::Test::Channel +channel+. This will typically be
+    # called via Net::SSH::Test::Channel#gets_close.
+    def gets_channel_close(channel)
+      events << RemotePacket.new(:channel_close, channel.local_id)
+    end
+
+    # By default, removes the next event in the list and returns it. However,
+    # this can also be used to non-destructively peek at the next event in the
+    # list, by passing :first as the argument.
+    #
+    #   # remove the next event and return it
+    #   event = script.next
+    #
+    #   # peek at the next event
+    #   event = script.next(:first)
+    def next(mode=:shift)
+      events.send(mode)
+    end
+
+    # Compare the given packet against the next event in the list. If there is
+    # no next event, an exception will be raised. This is called by
+    # Net::SSH::Test::Extensions::PacketStream#test_enqueue_packet.
+    def process(packet)
+      event = events.shift or raise "end of script reached, but got a packet type #{packet.read_byte}"
+      event.process(packet)
+    end
+  end
+
+end; end; end