net-sftp 0.5.0

data/examples/synchronous.rb

@@ -0,0 +1,120 @@
+#--
+# =============================================================================
+# 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 'net/sftp'
+
+Net::SFTP.start( 'localhost',
+  :registry_options => { :logs => { :levels => { "sftp.*" => :debug } } }
+) do |sftp|
+  puts "----------------------------------------------"
+  puts "getting handle..."
+  handle = sftp.open( "temp/out" )
+  puts "got handle: #{handle.inspect}"
+  puts "reading..."
+  data = sftp.read( handle )
+  puts "got data: #{data.length} bytes"
+  sftp.close_handle( handle )
+
+  puts "----------------------------------------------"
+  puts "opening handle for writing..."
+  handle = sftp.open( "temp/blah", IO::WRONLY | IO::CREAT )
+  puts "got handle: #{handle.inspect}"
+  data = "1234567890" * 100
+  puts "writing #{data.length} bytes..."
+  p sftp.write( handle, data ).code
+  sftp.close_handle( handle )
+
+  puts "----------------------------------------------"
+  puts "opening handle for writing..."
+  handle = sftp.open( "temp/blah", IO::WRONLY | IO::CREAT )
+  puts "got handle: #{handle.inspect}"
+  data = "1234567890" * 100000
+  puts "writing #{data.length} bytes..."
+  p sftp.write( handle, data ).code
+  sftp.close_handle( handle )
+
+  puts "----------------------------------------------"
+  puts "opening directory handle..."
+  handle = sftp.opendir( "/usr/lib" )
+  puts "got handle: #{handle.inspect}"
+  puts "reading directory..."
+  items = sftp.readdir( handle )
+  puts "got #{items.length} entries"
+  sftp.close_handle( handle )
+
+  puts "----------------------------------------------"
+  puts "removing file..."
+  p sftp.remove( "temp/blah" ).code
+
+  puts "----------------------------------------------"
+  puts "getting attributes (stat)..."
+  p sftp.stat( "temp/out" )
+
+  puts "----------------------------------------------"
+  puts "getting attributes (lstat)..."
+  p sftp.lstat( "temp/out" )
+
+  puts "----------------------------------------------"
+  puts "getting handle..."
+  handle = sftp.open( "temp/out" )
+  puts "getting attributes (fstat)..."
+  p sftp.fstat( handle )
+  sftp.close_handle( handle )
+
+  puts "----------------------------------------------"
+  puts "setting attributes (setstat)..."
+  p sftp.setstat( "temp/out", :permissions => 0777 )
+  puts "getting attributes (stat)..."
+  p sftp.stat( "temp/out" )
+
+  puts "----------------------------------------------"
+  puts "getting handle..."
+  handle = sftp.open( "temp/out" )
+  puts "setting attributes (fsetstat)..."
+  p sftp.fsetstat( handle, :permissions => 0660 )
+  sftp.close_handle( handle )
+  puts "getting attributes (stat)..."
+  p sftp.stat( "temp/out" )
+
+  puts "----------------------------------------------"
+  puts "mkdir..."
+  p sftp.mkdir( "temp/test_dir", :permissions => 0500 )
+  puts "getting attributes (stat)..."
+  p sftp.stat( "temp/test_dir" )
+
+  puts "----------------------------------------------"
+  puts "rmdir..."
+  p sftp.rmdir( "temp/test_dir" )
+
+  puts "----------------------------------------------"
+  puts "realpath..."
+  p sftp.realpath( "." )
+
+  # 'rename' is only available from protocol version 2+.
+  if sftp.support?( :rename )
+    puts "----------------------------------------------"
+    puts "rename..."
+    p sftp.rename( "temp/out", "temp/out2" )
+    puts "getting realpath..."
+    p sftp.realpath( "temp/out2" )
+    puts "restoring name..."
+    p sftp.rename( "temp/out2", "temp/out" )
+  end
+
+  puts "----------------------------------------------"
+  puts "done!"
+end

data/lib/net/sftp.rb

@@ -0,0 +1,39 @@
+#--
+# =============================================================================
+# 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/ssh'
+require 'net/sftp/session'
+
+module Net ; module SFTP
+
+  # A convenience method for starting a standalone SFTP session. It will
+  # start up an SSH session using the given arguments (see the documentation
+  # for Net::SSH::Session for details), and will then start a new SFTP session
+  # with the SSH session. If a block is given, it will be passed to the SFTP
+  # session.
+  def start( *args, &block )
+    session = Net::SSH.start( *args )
+    Net::SFTP::Session.new( session, &block )
+  ensure
+    session.close if session && block_given?
+  end
+  module_function :start
+
+end ; end
+
+Net::SSH.register_service( :sftp ) do |c,p|
+  Net::SFTP::Session.new( c[:session] )
+end

data/lib/net/sftp/errors.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
+
+  # The base exception class for the SFTP system.
+  class Exception < ::Exception; end
+
+  # An exception class representing a bug condition.
+  class Bug < Exception; end
+
+end ; end

data/lib/net/sftp/operations/abstract.rb

@@ -0,0 +1,103 @@
+#--
+# =============================================================================
+# 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/operations/errors'
+
+module Net ; module SFTP ; module Operations
+
+  # The base class for all SFTP operations. Subclasses must implement a
+  # +perform+ method, which accepts the arguments expected by the corresponding
+  # method of the driver. Subclasses _may_ also override the default
+  # implementations of +do_status+, +do_data+, +do_name+, +do_handle+, and
+  # +do_attrs+, as necessary.
+  class Abstract
+    include Constants
+
+    # A structure for reporting status information.
+    Status = Struct.new( :code, :message, :language )
+
+    # A constant for representing the commonly-used FX_OK status.
+    OK = Status.new( FX_OK, "Success", "" )
+
+    # Create a new operation with the given logger instance, which will
+    # operate atop the given session, using the given driver to format and 
+    # send the requests to the server.
+    def initialize( log, session, driver )
+      @log = log
+      @session = session
+      @driver = driver
+    end
+
+    # Execute the operation. If a callback is given, the operation will be
+    # performed asynchronously with the callback being invoked when the
+    # operation completes. If a callback is not given, the operation will
+    # be performed synchronously, with the expected value being returned.
+    def execute( *args, &callback )
+      @log.debug "executing" if @log.debug?
+
+      unless block_given?
+        callback = Proc.new do |status, *pargs|
+          @session.status = status
+          case
+            when pargs.empty? then return @session.status
+            when pargs.length == 1 then return pargs.first
+            else return pargs
+          end
+        end
+      end
+
+      @callback = callback
+      @id = perform *args
+      @log.debug "received request id #{@id}"
+      @session.register( @id, self )
+
+      @session.loop unless block_given?
+    end
+
+    # A callback for SFTP status packets. By default, raises an exception unless
+    # the status is FX_OK, in which case the registered callback is invoked.
+    def do_status( code, message, language )
+      raise StatusException.new( code, message, language ) unless code == FX_OK
+      @callback[ Status.new( code, message, language ) ]
+    end
+
+    # A callback for SFTP handle packets. By default, invokes the registered
+    # callback, passing an OK status and the handle.
+    def do_handle( handle )
+      @callback[ OK, handle ]
+    end
+
+    # A callback for SFTP data packets. By default, invokes the registered
+    # callback, passing an OK status and the data.
+    def do_data( data )
+      @callback[ OK, data ]
+    end
+
+    # A callback for SFTP name packets. By default, invokes the registered
+    # callback, passing an OK status and the list of items.
+    def do_name( items )
+      @callback[ OK, items ]
+    end
+
+    # A callback for SFTP attrs packets. By default, invokes the registered
+    # callback, passing an OK status and the attributes object.
+    def do_attrs( attributes )
+      @callback[ OK, attributes ]
+    end
+
+  end
+
+end ; end ; end

data/lib/net/sftp/operations/close.rb

@@ -0,0 +1,31 @@
+#--
+# =============================================================================
+# 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/operations/abstract'
+
+module Net ; module SFTP ; module Operations
+
+  # The implementation of the close operation, for closing an open handle.
+  class Close < Abstract
+
+    # Closes the given handle.
+    def perform( handle )
+      @driver.close_handle( nil, handle )
+    end
+
+  end
+
+end ; end ; end

data/lib/net/sftp/operations/errors.rb

@@ -0,0 +1,76 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::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'
+
+module Net ; module SFTP ; module Operations
+
+  module Constants
+    FX_OK                     = 0
+    FX_EOF                    = 1
+    FX_NO_SUCH_FILE           = 2
+    FX_PERMISSION_DENIED      = 3
+    FX_FAILURE                = 4
+    FX_BAD_MESSAGE            = 5
+    FX_NO_CONNECTION          = 6
+    FX_CONNECTION_LOST        = 7
+    FX_OP_UNSUPPORTED         = 8
+    FX_INVALID_HANDLE         = 9
+    FX_NO_SUCH_PATH           = 10
+    FX_FILE_ALREADY_EXISTS    = 11
+    FX_WRITE_PROTECT          = 12
+    FX_NO_MEDIA               = 13
+    FX_NO_SPACE_ON_FILESYSTEM = 14
+    FX_QUOTA_EXCEEDED         = 15
+    FX_UNKNOWN_PRINCIPLE      = 16
+    FX_LOCK_CONFlICT          = 17
+    FX_DIR_NOT_EMPTY          = 18
+    FX_NOT_A_DIRECTORY        = 19
+    FX_INVALID_FILENAME       = 20
+    FX_LINK_LOOP              = 21
+  end
+
+  # A exception class for reporting a non-success result of an operation.
+  class StatusException < Net::SFTP::Exception
+
+    # The error code (numeric)
+    attr_reader :code
+
+    # The description of the error
+    attr_reader :description
+
+    # The language in which the description is being reported (usually the
+    # empty string)
+    attr_reader :language
+
+    # Create a new status exception that reports the given code and
+    # description.
+    def initialize( code, description, language )
+      @code = code
+      @description = description
+      @language = language
+    end
+
+    # Override the default message format, to include the code and
+    # description.
+    def message
+      m = super
+      m << " (#{code}, #{description.inspect})"
+    end
+
+  end
+
+end ; end ; end

data/lib/net/sftp/operations/fsetstat.rb

@@ -0,0 +1,36 @@
+#--
+# =============================================================================
+# 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/operations/abstract'
+
+module Net ; module SFTP ; module Operations
+
+  # The implementation of the +fsetstat+ operation.
+  class Fsetstat < Abstract
+
+    # Performs the fsetstat operation on the given handle. The +hash+
+    # parameter is a Hash of attribute name/value pairs, from which an
+    # attributes object will be created and sent to the server. It
+    # represents the attributes to set on the file/directory represented
+    # by the handle.
+    def perform( handle, hash )
+      attrs = @driver.attr_factory.from_hash( hash )
+      @driver.fsetstat( nil, handle, attrs )
+    end
+
+  end
+
+end ; end ; end

data/lib/net/sftp/operations/fstat.rb

@@ -0,0 +1,32 @@
+#--
+# =============================================================================
+# 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/operations/abstract'
+
+module Net ; module SFTP ; module Operations
+
+  # The implementation of the +fstat+ operation.
+  class Fstat < Abstract
+
+    # Ask the server for the attributes of the file/directory represented by
+    # the given handle.
+    def perform( handle )
+      @driver.fstat( nil, handle )
+    end
+
+  end
+
+end ; end ; end