net-sftp 1.1.1 → 2.0.0

data/CHANGELOG.rdoc

@@ -0,0 +1,23 @@
+=== 2.0.0 / 1 May 2008
+
+* Make Net::SSH::Connection::Session#sftp accept an argument determining whether or not to block while the SFTP subsystem initializes (defaults to true) [Jamis Buck]
+
+* Allow Session#connect to be useful even in the open/opening states by invoking or queuing the callback block [Jamis Buck]
+
+* Allow custom properties to be set on upload/download initiation via the :properties option [Jamis Buck]
+
+* Custom properties on Download instances [Jamis Buck]
+
+* Add #abort! method to Upload and Download operations [Jamis Buck]
+
+* More complete support for file-type detection in protocol versions 1-3 [Jamis Buck]
+
+
+=== 2.0 Preview Release 2 (1.99.1) / 10 Apr 2008
+
+* Custom properties on Upload instances [Jamis Buck]
+
+
+=== 2.0 Preview Release 1 (1.99.0) / 22 Mar 2008
+
+* Rewritten! (Never, ever, do this at home.) New and improved API.

data/Manifest

@@ -0,0 +1,55 @@
+CHANGELOG.rdoc
+lib/net/sftp/constants.rb
+lib/net/sftp/errors.rb
+lib/net/sftp/operations/dir.rb
+lib/net/sftp/operations/download.rb
+lib/net/sftp/operations/file.rb
+lib/net/sftp/operations/file_factory.rb
+lib/net/sftp/operations/upload.rb
+lib/net/sftp/packet.rb
+lib/net/sftp/protocol/01/attributes.rb
+lib/net/sftp/protocol/01/base.rb
+lib/net/sftp/protocol/01/name.rb
+lib/net/sftp/protocol/02/base.rb
+lib/net/sftp/protocol/03/base.rb
+lib/net/sftp/protocol/04/attributes.rb
+lib/net/sftp/protocol/04/base.rb
+lib/net/sftp/protocol/04/name.rb
+lib/net/sftp/protocol/05/base.rb
+lib/net/sftp/protocol/06/attributes.rb
+lib/net/sftp/protocol/06/base.rb
+lib/net/sftp/protocol/base.rb
+lib/net/sftp/protocol.rb
+lib/net/sftp/request.rb
+lib/net/sftp/response.rb
+lib/net/sftp/session.rb
+lib/net/sftp/version.rb
+lib/net/sftp.rb
+Rakefile
+README.rdoc
+setup.rb
+test/common.rb
+test/protocol/01/test_attributes.rb
+test/protocol/01/test_base.rb
+test/protocol/01/test_name.rb
+test/protocol/02/test_base.rb
+test/protocol/03/test_base.rb
+test/protocol/04/test_attributes.rb
+test/protocol/04/test_base.rb
+test/protocol/04/test_name.rb
+test/protocol/05/test_base.rb
+test/protocol/06/test_attributes.rb
+test/protocol/06/test_base.rb
+test/protocol/test_base.rb
+test/test_all.rb
+test/test_dir.rb
+test/test_download.rb
+test/test_file.rb
+test/test_file_factory.rb
+test/test_packet.rb
+test/test_protocol.rb
+test/test_request.rb
+test/test_response.rb
+test/test_session.rb
+test/test_upload.rb
+Manifest

data/README.rdoc

@@ -0,0 +1,96 @@
+= Net::SFTP
+
+* http://net-ssh.rubyforge.org/sftp
+
+== DESCRIPTION:
+
+Net::SFTP is a pure-Ruby implementation of the SFTP protocol (specifically, versions 1 through 6 of the SFTP protocol). Note that this is the "Secure File Transfer Protocol", typically run over an SSH connection, and has nothing to do with the FTP protocol.
+
+== FEATURES/PROBLEMS:
+
+* Transfer files or even entire directory trees to or from a remote host via SFTP
+* Completely supports all six protocol versions
+* Asynchronous and synchronous operation
+* Read and write files using an IO-like interface
+
+== SYNOPSIS:
+
+In a nutshell:
+
+  require 'net/sftp'
+
+  Net::SFTP.start('host', 'username', :password => 'password') do |sftp|
+    # upload a file or directory to the remote host
+    sftp.upload!("/path/to/local", "/path/to/remote")
+
+    # download a file or directory from the remote host
+    sftp.download!("/path/to/remote", "/path/to/local")
+
+    # grab data off the remote host directly to a buffer
+    data = sftp.download!("/path/to/remote")
+
+    # open and write to a pseudo-IO for a remote file
+    sftp.file.open("/path/to/remote", "w") do |f|
+      f.puts "Hello, world!\n"
+    end
+
+    # open and read from a pseudo-IO for a remote file
+    sftp.file.open("/path/to/remote", "r") do |f|
+      puts f.gets
+    end
+
+    # create a directory
+    sftp.mkdir! "/path/to/directory"
+
+    # list the entries in a directory
+    sftp.dir.foreach("/path/to/directory") do |entry|
+      puts entry.longname
+    end
+  end
+
+For the full documentation, start with Net::SFTP::Session. Also see Net::SFTP::Operations::Upload, Net::SFTP::Operations::Download, Net::SFTP::Operations::FileFactory, Net::SFTP::Operations::File, and Net::SFTP::Operations::Dir.
+
+== REQUIREMENTS:
+
+* Net::SSH 2
+
+If you wish to run the tests, you'll need:
+
+* Echoe (if you want to use the Rakefile)
+* Mocha
+
+== INSTALL:
+
+* gem install net-sftp (might need sudo privileges)
+
+Or, if you prefer to do it the hard way (sans Rubygems):
+
+* tar xzf net-ssh-*.tgz
+* cd net-ssh-*
+* ruby setup.rb config
+* ruby setup.rb install (might need sudo privileges)
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Jamis Buck <jamis@37signals.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,30 @@
+$LOAD_PATH.unshift "../net-ssh/lib"
+require './lib/net/sftp/version'
+
+begin
+  require 'echoe'
+rescue LoadError
+  abort "You'll need to have `echoe' installed to use Net::SFTP's Rakefile"
+end
+
+version = Net::SFTP::Version::STRING.dup
+if ENV['SNAPSHOT'].to_i == 1
+  version << "." << Time.now.utc.strftime("%Y%m%d%H%M%S")
+end
+
+Echoe.new('net-sftp', version) do |p|
+  p.project          = "net-ssh"
+  p.changelog        = "CHANGELOG.rdoc"
+
+  p.author           = "Jamis Buck"
+  p.email            = "jamis@jamisbuck.org"
+  p.summary          = "A pure Ruby implementation of the SFTP client protocol"
+  p.url              = "http://net-ssh.rubyforge.org/sftp"
+
+  p.dependencies     = ["net-ssh >=1.99.1"]
+
+  p.need_zip         = true
+  p.include_rakefile = true
+
+  p.rdoc_pattern     = /^(lib|README.rdoc|CHANGELOG.rdoc)/
+end

data/lib/net/sftp.rb

@@ -1,45 +1,60 @@
-#--
-# =============================================================================
-# Copyright (c) 2004, Jamis Buck (jamis@37signals.com)
-# 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
-# =============================================================================
-#++
-
-begin
-  require 'rubygems'
-  gem "net-ssh", "< 1.99.0"
-rescue LoadError
-end
-
 require 'net/ssh'
 require 'net/sftp/session'
 
-module Net ; module SFTP
+module Net
 
-  # 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
+  # Net::SFTP is a pure-Ruby module for programmatically interacting with a
+  # remote host via the SFTP protocol (that's SFTP as in "Secure File Transfer
+  # Protocol" produced by the Secure Shell Working Group, not "Secure FTP"
+  # and certainly not "Simple FTP").
+  #
+  # See Net::SFTP#start for an introduction to the library. Also, see
+  # Net::SFTP::Session for further documentation.
+  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. This will block until the new SFTP is fully open
+    # and initialized before returning it.
+    #
+    #   sftp = Net::SFTP.start("localhost", "user")
+    #   sftp.upload! "/local/file.tgz", "/remote/file.tgz"
+    #
+    # If a block is given, it will be passed to the SFTP session and will be
+    # called once the SFTP session is fully open and initialized. When the
+    # block terminates, the new SSH session will automatically be closed.
+    #
+    #   Net::SFTP.start("localhost", "user") do |sftp|
+    #     sftp.upload! "/local/file.tgz", "/remote/file.tgz"
+    #   end
+    def self.start(host, user, options={}, &block)
+      session = Net::SSH.start(host, user, options)
+      sftp = Net::SFTP::Session.new(session, &block).connect!
 
-end ; end
+      sftp.loop if block_given?
+
+      sftp
+    ensure
+      session.close if session && block_given?
+    end
+  end
 
-Net::SSH.register_service( :sftp ) do |c,p|
-  Net::SFTP::Session.new( c[:session] )
 end
+
+class Net::SSH::Connection::Session
+  # A convenience method for starting up a new SFTP connection on the current
+  # SSH session. Blocks until the SFTP session is fully open, and then
+  # returns the SFTP session.
+  #
+  #   Net::SSH.start("localhost", "user", "password") do |ssh|
+  #     ssh.sftp.upload!("/local/file.tgz", "/remote/file.tgz")
+  #     ssh.exec! "cd /some/path && tar xf /remote/file.tgz && rm /remote/file.tgz"
+  #   end
+  def sftp(wait=true)
+    @sftp ||= begin
+      sftp = Net::SFTP::Session.new(self)
+      sftp.connect! if wait
+      sftp
+    end
+  end
+end

data/lib/net/sftp/constants.rb

@@ -0,0 +1,187 @@
+module Net module SFTP
+
+  # The packet types and other general constants used by the SFTP protocol.
+  # See the specification for the SFTP protocol for a full discussion of their
+  # meaning and usage.
+  module Constants
+
+    # The various packet types supported by SFTP protocol versions 1 through 6.
+    # The FXP_EXTENDED and FXP_EXTENDED_REPLY packet types are not currently
+    # understood by Net::SFTP.
+    module PacketTypes
+      FXP_INIT           = 1
+      FXP_VERSION        = 2
+                         
+      FXP_OPEN           = 3
+      FXP_CLOSE          = 4
+      FXP_READ           = 5
+      FXP_WRITE          = 6
+      FXP_LSTAT          = 7
+      FXP_FSTAT          = 8
+      FXP_SETSTAT        = 9
+      FXP_FSETSTAT       = 10
+      FXP_OPENDIR        = 11
+      FXP_READDIR        = 12
+      FXP_REMOVE         = 13
+      FXP_MKDIR          = 14
+      FXP_RMDIR          = 15
+      FXP_REALPATH       = 16
+      FXP_STAT           = 17
+      FXP_RENAME         = 18
+      FXP_READLINK       = 19
+      FXP_SYMLINK        = 20
+      FXP_LINK           = 21
+      FXP_BLOCK          = 22
+      FXP_UNBLOCK        = 23
+                         
+      FXP_STATUS         = 101
+      FXP_HANDLE         = 102
+      FXP_DATA           = 103
+      FXP_NAME           = 104
+      FXP_ATTRS          = 105
+                         
+      FXP_EXTENDED       = 200
+      FXP_EXTENDED_REPLY = 201
+    end
+
+    # Beginning in version 5 of the protocol, Net::SFTP::Session#rename accepts
+    # an optional +flags+ argument that must be either 0 or a combination of
+    # these constants.
+    module RenameFlags
+      OVERWRITE = 0x00000001
+      ATOMIC    = 0x00000002
+      NATIVE    = 0x00000004
+    end
+
+    # When an FXP_STATUS packet is received from the server, the +code+ will
+    # be one of the following constants.
+    module StatusCodes
+      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
+
+    # The Net::SFTP::Session#open operation is one of the worst casualties of
+    # the revisions between SFTP protocol versions. The flags change considerably
+    # between version 1 and version 6. Net::SFTP tries to shield programmers
+    # from the differences, so you'll almost never need to use these flags
+    # directly, but if you ever need to specify some flag that isn't exposed
+    # by the higher-level API, these are the ones that are available to you.
+    module OpenFlags
+      # These are the flags that are understood by versions 1-4 of the the
+      # open operation.
+      module FV1
+        READ   = 0x00000001
+        WRITE  = 0x00000002
+        APPEND = 0x00000004
+        CREAT  = 0x00000008
+        TRUNC  = 0x00000010
+        EXCL   = 0x00000020
+      end
+
+      # Version 5 of the open operation totally discarded the flags understood
+      # by versions 1-4, and replaced them with these.
+      module FV5
+        CREATE_NEW         = 0x00000000
+        CREATE_TRUNCATE    = 0x00000001
+        OPEN_EXISTING      = 0x00000002
+        OPEN_OR_CREATE     = 0x00000003
+        TRUNCATE_EXISTING  = 0x00000004
+
+        APPEND_DATA        = 0x00000008
+        APPEND_DATA_ATOMIC = 0x00000010
+        TEXT_MODE          = 0x00000020
+        READ_LOCK          = 0x00000040
+        WRITE_LOCK         = 0x00000080
+        DELETE_LOCK        = 0x00000100
+      end
+
+      # Version 6 of the open operation added these flags, in addition to the
+      # flags understood by version 5.
+      module FV6
+        ADVISORY_LOCK           = 0x00000200
+        NOFOLLOW                = 0x00000400
+        DELETE_ON_CLOSE         = 0x00000800
+        ACCESS_AUDIT_ALARM_INFO = 0x00001000
+        ACCESS_BACKUP           = 0x00002000
+        BACKUP_STREAM           = 0x00004000
+        OVERRIDE_OWNER          = 0x00008000
+      end
+    end
+
+    # The Net::SFTP::Session#block operation, implemented in version 6 of
+    # the protocol, understands these constants for the +mask+ parameter.
+    module LockTypes
+      READ     = OpenFlags::FV5::READ_LOCK
+      WRITE    = OpenFlags::FV5::WRITE_LOCK
+      DELETE   = OpenFlags::FV5::DELETE_LOCK
+      ADVISORY = OpenFlags::FV6::ADVISORY_LOCK
+    end
+
+    module ACE
+      # Access control entry types, used from version 4 of the protocol,
+      # onward. See Net::SFTP::Protocol::V04::Attributes::ACL.
+      module Type
+        ACCESS_ALLOWED = 0x00000000
+        ACCESS_DENIED  = 0x00000001
+        SYSTEM_AUDIT   = 0x00000002
+        SYSTEM_ALARM   = 0x00000003
+      end
+
+      # Access control entry flags, used from version 4 of the protocol,
+      # onward. See Net::SFTP::Protocol::V04::Attributes::ACL.
+      module Flag
+        FILE_INHERIT         = 0x00000001
+        DIRECTORY_INHERIT    = 0x00000002
+        NO_PROPAGATE_INHERIT = 0x00000004
+        INHERIT_ONLY         = 0x00000008
+        SUCCESSFUL_ACCESS    = 0x00000010
+        FAILED_ACCESS        = 0x00000020
+        IDENTIFIER_GROUP     = 0x00000040
+      end
+
+      # Access control entry masks, used from version 4 of the protocol,
+      # onward. See Net::SFTP::Protocol::V04::Attributes::ACL.
+      module Mask
+        READ_DATA         = 0x00000001
+        LIST_DIRECTORY    = 0x00000001
+        WRITE_DATA        = 0x00000002
+        ADD_FILE          = 0x00000002
+        APPEND_DATA       = 0x00000004
+        ADD_SUBDIRECTORY  = 0x00000004
+        READ_NAMED_ATTRS  = 0x00000008
+        WRITE_NAMED_ATTRS = 0x00000010
+        EXECUTE           = 0x00000020
+        DELETE_CHILD      = 0x00000040
+        READ_ATTRIBUTES   = 0x00000080
+        WRITE_ATTRIBUTES  = 0x00000100
+        DELETE            = 0x00010000
+        READ_ACL          = 0x00020000
+        WRITE_ACL         = 0x00040000
+        WRITE_OWNER       = 0x00080000
+        SYNCHRONIZE       = 0x00100000
+      end
+    end
+
+  end
+
+end end