net-sftp 0.5.0

data/lib/net/sftp/protocol/packet-assistant.rb

@@ -0,0 +1,84 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SFTP Secure FTP 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::SFTP
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-sftp website: http://net-ssh.rubyforge.org/sftp
+# project website : http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+module Net ; module SFTP ; module Protocol
+
+  # This is the abstract base class for all packet assistant classes used by
+  # the supported SFTP protocol versions.
+  class PacketAssistant
+
+    # A helper method for defining a new packet type. The +name+ is the name
+    # of the packet (and of the corresponding method that is created), and the
+    # arguments are symbols representing the types of each element in the
+    # packet. The supported types are:
+    #
+    # * :long
+    # * :int64
+    # * :short
+    # * :byte
+    # * :string
+    # * :attrs
+    # * :write
+    #
+    # The :attrs and :write types both simply convert the argument to a string.
+    #
+    # The method that is created always supports an +id+ parameter in the
+    # first position, which if null will default to the next available request
+    # id. The method returns a tuple consisting of the request id, and a string
+    # consisting of the arguments formatted according to the packet's
+    # description.
+    def self.packet( name, *args )
+      body = ""
+      args.each do |arg|
+        body << "b.write"
+        case arg
+          when :long, :int64, :short, :byte
+            body << "_#{arg} args.shift.to_i"
+          when :string
+            body << "_#{arg} args.shift.to_s"
+          when :attrs, :write
+            body << " args.shift.to_s"
+        end
+        body << "\n"
+      end
+      class_eval <<-EOF, __FILE__, __LINE__+1
+        def #{name}( id, *args )
+          b = buffers.writer
+          id ||= driver.next_request_id
+          b.write_long id
+          #{body}
+          [ id, b.to_s ]
+        end
+      EOF
+    end
+
+    # The buffer factory in use by this packet assistant, used to build the
+    # packets.
+    attr_reader :buffers
+
+    # The protocol driver that will be used to obtain request ids.
+    attr_reader :driver
+
+    # Create a new PacketAssistant, which will use the given buffer factory and
+    # SFTP protocol driver.
+    def initialize( buffers, driver )
+      @buffers = buffers
+      @driver = driver
+    end
+
+  end
+
+end ; end ; end

data/lib/net/sftp/protocol/services.rb

@@ -0,0 +1,55 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SFTP Secure FTP 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::SFTP
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-sftp website: http://net-ssh.rubyforge.org/sftp
+# project website : http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+module Net ; module SFTP ; module Protocol
+
+  def register_services( container )
+    container.namespace_define :protocol do |ns|
+
+      # The maximum version of the SFTP protocol supported by this
+      # implementation. Clients may set this to a lower value to force the
+      # usage of a specific SFTP version. It should _not_ be set higher than
+      # the value that is given below.
+      ns.version { 5 }
+
+      # A proc object that, when invoked, returns a dispatcher object capable
+      # of handling the requested protocol version.
+      ns.dispatcher_factory do |c,|
+        lambda do |version, extensions|
+          version = "%02d" % version
+          c.require "net/sftp/protocol/#{version}/services",
+            "#{self}::V_#{version}"
+          impl = c["v_#{version}".to_sym][:impl]
+          impl.extensions = extensions
+          impl
+        end
+      end
+
+      # The driver service that manages the SFTP protocol-level communications
+      ns.driver do |c,p|
+        require 'net/sftp/protocol/driver'
+        Driver.new( c[:connection][:driver],
+                    c[:transport][:buffers],
+                    c[:version],
+                    c[:dispatcher_factory],
+                    c[:log_for, p] )
+      end
+
+    end
+  end
+  module_function :register_services
+
+end ; end ; end

data/lib/net/sftp/session.rb

@@ -0,0 +1,215 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SFTP Secure FTP 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::SFTP
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-sftp website: http://net-ssh.rubyforge.org/sftp
+# project website : http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+require 'net/sftp/errors'
+require 'net/sftp/protocol/constants'
+
+module Net ; module SFTP
+
+  # Represents a single SFTP session, running atop an SSH session.
+  class Session
+    include Protocol::Constants
+
+    # The status of the last synchronously executed operation. This is either
+    # +nil+, or an object that responds to <tt>:code</tt>, <tt>:message</tt>,
+    # and <tt>:language</tt>.
+    attr_accessor :status
+
+    # Create a new SFTP session on top of the given SSH session.
+    def initialize( session )
+      @session = session
+      @log = @session.registry.log_for( "sftp.session" )
+
+      @session.registry.namespace_define :sftp do |ns|
+        ns.require "net/sftp/protocol/services", "Net::SFTP::Protocol"
+        ns.require "net/sftp/operations/services", "Net::SFTP::Operations"
+
+        # register a reference to myself for other services to be able to
+        # access me.
+        ns.session( :pipeline => [] ) { self }
+
+        @driver = ns.protocol.driver
+        @driver.on_open do |d|
+          d.on_attrs  &method( :do_attrs  )
+          d.on_data   &method( :do_data   )
+          d.on_handle &method( :do_handle )
+          d.on_name   &method( :do_name   )
+          d.on_status &method( :do_status )
+
+          if block_given?
+            begin
+              yield self
+            ensure
+              d.close
+            end
+          end
+        end
+
+        @operations = ns.operations
+      end
+
+      @requests = Hash.new
+
+      @session.loop if block_given?
+    end
+
+    #--
+    # ====================================================================
+    # QUERIES/GETTERS/SETTERS/ACTIONS
+    # ====================================================================
+    #++
+
+    # Return the state of the SFTP connection. (See
+    # Net::SFTP::Protocol::Driver#state.)
+    def state
+      @driver.state
+    end
+
+    # Closes the SFTP connection, but leaves the SSH connection open.
+    def close_channel
+      @driver.close
+    end
+
+    # Closes the underlying SSH connection.
+    def close
+      @session.close
+    end
+
+    # Registers the given handler with the given request id. This is used
+    # internally by the operations, so that the session knows who to delegate
+    # a response to that has been received from the server.
+    def register( id, handler )
+      @requests[ id ] = handler
+    end
+
+    # Delegates to Net::SSH::Session#loop. Causes the underlying SSH
+    # connection to process events as long as the given block returns +true+,
+    # or (if no block is given) until there are no more open channels.
+    def loop( &block )
+      @session.loop( &block )
+    end
+
+    # Waits for the underlying driver to reach a state of :open (or :closed).
+    # This makes it easier to use the SFTP routines synchronously without using
+    # the block form:
+    #
+    #   sftp = Net::SFTP::Session.new( ssh_session )
+    #   sftp.connect
+    #   puts sftp.realpath( "." )
+    #
+    # Without the call to #connect, the call to #realpath would fail because
+    # the SFTP protocol has not yet been negotiated and no underlying driver has
+    # been selected.
+    #
+    # If no block is given, it teturns +self+, so it can be chained easily to
+    # other method calls. If a block _is_ given, the session is yielded to the
+    # block as soon as the driver successfully reports it's state as +open+,
+    # with the session's channel being closed automatically when the block
+    # finishes.
+    #
+    #   require 'net/ssh'
+    #   require 'net/sftp'
+    #
+    #   Net::SSH.start( 'localhost' ) do |session|
+    #     session.sftp.connect do |sftp|
+    #       puts sftp.realpath( "." )
+    #     end
+    #   end
+    def connect
+      @session.loop do
+        @driver.state != :open &&
+        @driver.state != :closed
+      end
+      if @driver.state == :open && block_given?
+        begin
+          yield self
+        ensure
+          close_channel
+        end
+      else
+        self
+      end
+    end
+    
+    #--
+    # ====================================================================
+    # CALLBACKS
+    # ====================================================================
+    #++
+
+    # Invoked by the underlying SFTP protocol layer when a SFTP data packet
+    # is received.
+    def do_data( driver, id, data )
+      @requests.delete( id ).do_data( data )
+    end
+
+    # Invoked by the underlying SFTP protocol layer when a SFTP status packet
+    # is received.
+    def do_status( driver, id, code, message, language )
+      @requests.delete( id ).do_status( code, message, language )
+    end
+
+    # Invoked by the underlying SFTP protocol layer when a SFTP handle packet
+    # is received.
+    def do_handle( driver, id, handle )
+      @requests.delete( id ).do_handle( handle )
+    end
+
+    # Invoked by the underlying SFTP protocol layer when a SFTP name packet
+    # is received.
+    def do_name( driver, id, items )
+      @requests.delete( id ).do_name( items )
+    end
+
+    # Invoked by the underlying SFTP protocol layer when a SFTP attrs packet
+    # is received.
+    def do_attrs( driver, id, attributes )
+      @requests.delete( id ).do_attrs( attributes )
+    end
+
+    #--
+    # ====================================================================
+    # DELEGATION
+    # ====================================================================
+    #++
+
+    # Delegates the message to the operation that has been registered with
+    # the given name. If no such operation exists, control is passed to the
+    # superclass' implementation of #method_missing.
+    def method_missing( sym, *args, &block )
+      if @operations.has_key?( sym )
+        @operations[ sym ].execute( *args, &block )
+      else
+        super
+      end
+    end
+
+    # Returns +true+ if the object responds to the given symbol, or if there is
+    # an operation registered under the given symbol.
+    def respond_to?( sym )
+      super || @operations.has_key?( sym )
+    end
+
+    # Returns +true+ if the underlying driver responds to the given symbol. This
+    # can be used by clients to determine whether the SFTP protocol version in
+    # use supports a particular operation.
+    def support?( sym )
+      @driver.respond_to?( sym )
+    end
+
+  end
+
+end ; end

data/lib/net/sftp/version.rb

@@ -0,0 +1,25 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SFTP Secure FTP 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::SFTP
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-sftp website: http://net-ssh.rubyforge.org/sftp
+# project website : http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+module Net ; module SFTP ; module Version
+
+  MAJOR = 0
+  MINOR = 5
+  TINY  = 0
+
+  STRING = [MAJOR,MINOR,TINY].join('.')
+
+end ; end ; end

data/test/ALL-TESTS.rb

@@ -0,0 +1,21 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SFTP Secure FTP 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::SFTP
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-sftp website: http://net-ssh.rubyforge.org/sftp
+# project website : http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+$:.unshift "../lib"
+
+$run_integration_tests = ARGV.include?( "-i" )
+
+Dir["**/tc_*.rb"].each { |f| load f }

data/test/operations/tc_abstract.rb

@@ -0,0 +1,124 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SFTP Secure FTP 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::SFTP
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-sftp website: http://net-ssh.rubyforge.org/sftp
+# project website : http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+$:.unshift "../../lib"
+
+require 'test/unit'
+require 'net/sftp/operations/abstract'
+require 'flexmock'
+
+class TC_Operations_Abstract < Test::Unit::TestCase
+
+  class Subclass < Net::SFTP::Operations::Abstract
+    attr_reader :args
+
+    def perform( *args )
+      @args = args
+      14
+    end
+  end
+
+  def setup
+    @log = FlexMock.new
+    @log.mock_handle( :debug )
+    @log.mock_handle( :debug? )
+
+    @session = FlexMock.new
+    @session.mock_handle( :status= )
+    @session.mock_handle( :register )
+    @session.mock_handle( :loop )
+
+    @driver = FlexMock.new
+
+    @operation = Subclass.new( @log, @session, @driver )
+  end
+
+  def test_execute_no_block
+    reg_args = nil
+    @session.mock_handle( :register ) { |*a| reg_args = a }
+
+    @operation.execute( :foo, :bar )
+
+    assert_equal 1, @session.mock_count( :register )
+    assert_equal 1, @session.mock_count( :loop )
+    assert_equal [ 14, @operation ], reg_args
+    assert_equal [ :foo, :bar ], @operation.args
+  end
+
+  def test_execute_with_block
+    reg_args = nil
+    @session.mock_handle( :register ) { |*a| reg_args = a }
+
+    @operation.execute( :foo, :bar )  { }
+
+    assert_equal 1, @session.mock_count( :register )
+    assert_equal 0, @session.mock_count( :loop )
+    assert_equal [ 14, @operation ], reg_args
+    assert_equal [ :foo, :bar ], @operation.args
+  end
+
+  def test_do_status_bad
+    assert_raise( Net::SFTP::Operations::StatusException ) do
+      @operation.do_status( 5, nil, nil )
+    end
+  end
+
+  def test_status_ok
+    status = nil
+    @operation.execute( :foo, :bar ) { |s| status = s }
+    assert_nothing_raised { @operation.do_status( 0, "hello", "world" ) }
+    assert_equal 0, status.code
+    assert_equal "hello", status.message
+    assert_equal "world", status.language
+  end
+
+  def test_do_handle
+    status = nil
+    handle = nil
+    @operation.execute( :foo, :bar ) { |s,h| status, handle = s, h }
+    @operation.do_handle( "foo" )
+    assert_equal 0, status.code
+    assert_equal "foo", handle
+  end
+
+  def test_do_data
+    status = nil
+    data = nil
+    @operation.execute( :foo, :bar ) { |s,d| status, data = s, d }
+    @operation.do_data( "foo" )
+    assert_equal 0, status.code
+    assert_equal "foo", data
+  end
+
+  def test_do_name
+    status = nil
+    name = nil
+    @operation.execute( :foo, :bar ) { |s,n| status, name = s, n }
+    @operation.do_name( "foo" )
+    assert_equal 0, status.code
+    assert_equal "foo", name
+  end
+
+  def test_do_attrs
+    status = nil
+    attrs = nil
+    @operation.execute( :foo, :bar ) { |s,a| status, attrs = s, a }
+    @operation.do_attrs( "foo" )
+    assert_equal 0, status.code
+    assert_equal "foo", attrs
+  end
+
+end