net-sftp 1.1.1 → 2.0.0

data/lib/net/sftp/protocol/04/base.rb

@@ -0,0 +1,94 @@
+require 'net/sftp/protocol/03/base'
+require 'net/sftp/protocol/04/attributes'
+require 'net/sftp/protocol/04/name'
+
+module Net; module SFTP; module Protocol; module V04
+
+  # Wraps the low-level SFTP calls for version 4 of the SFTP protocol. Also
+  # implements the updated FXP_NAME packet parsing as mandated by v4 of the
+  # protocol.
+  #
+  # None of these protocol methods block--all of them return immediately,
+  # requiring the SSH event loop to be run while the server response is
+  # pending.
+  #
+  # You will almost certainly never need to use this driver directly. Please
+  # see Net::SFTP::Session for the recommended interface.
+  class Base < V03::Base
+
+    # Returns the protocol version implemented by this driver. (4, in this
+    # case)
+    def version
+      4
+    end
+
+    # As of v4 of the SFTP protocol, the "longname" member was removed from the
+    # FXP_NAME structure. This method is essentially the same as the previous
+    # implementation, but omits longname.
+    def parse_name_packet(packet)
+      names = []
+
+      packet.read_long.times do
+        filename = packet.read_string
+        attrs    = attribute_factory.from_buffer(packet)
+        names   << name_factory.new(filename, attrs)
+      end
+
+      { :names => names }
+    end
+
+    # Sends a FXP_STAT packet to the server for the given +path+, and with the
+    # given +flags+. If +flags+ is nil, it defaults to F_SIZE | F_PERMISSIONS |
+    # F_ACCESSTIME | F_CREATETIME | F_MODIFYTIME | F_ACL | F_OWNERGROUP |
+    # F_SUBSECOND_TIMES | F_EXTENDED (see Net::SFTP::Protocol::V04::Attributes
+    # for those constants).
+    def stat(path, flags=nil)
+      send_request(FXP_STAT, :string, path, :long, flags || DEFAULT_FLAGS)
+    end
+
+    # Sends a FXP_LSTAT packet to the server for the given +path+, and with the
+    # given +flags+. If +flags+ is nil, it defaults to F_SIZE | F_PERMISSIONS |
+    # F_ACCESSTIME | F_CREATETIME | F_MODIFYTIME | F_ACL | F_OWNERGROUP |
+    # F_SUBSECOND_TIMES | F_EXTENDED (see Net::SFTP::Protocol::V04::Attributes
+    # for those constants).
+    def lstat(path, flags=nil)
+      send_request(FXP_LSTAT, :string, path, :long, flags || DEFAULT_FLAGS)
+    end
+
+    # Sends a FXP_FSTAT packet to the server for the given +path+, and with the
+    # given +flags+. If +flags+ is nil, it defaults to F_SIZE | F_PERMISSIONS |
+    # F_ACCESSTIME | F_CREATETIME | F_MODIFYTIME | F_ACL | F_OWNERGROUP |
+    # F_SUBSECOND_TIMES | F_EXTENDED (see Net::SFTP::Protocol::V04::Attributes
+    # for those constants).
+    def fstat(handle, flags=nil)
+      send_request(FXP_FSTAT, :string, handle, :long, flags || DEFAULT_FLAGS)
+    end
+
+    protected
+
+      # The default flags used if the +flags+ parameter is nil for any of the
+      # #stat, #lstat, or #fstat operations.
+      DEFAULT_FLAGS = Attributes::F_SIZE |
+                      Attributes::F_PERMISSIONS |
+                      Attributes::F_ACCESSTIME |
+                      Attributes::F_CREATETIME |
+                      Attributes::F_MODIFYTIME |
+                      Attributes::F_ACL |
+                      Attributes::F_OWNERGROUP |
+                      Attributes::F_SUBSECOND_TIMES |
+                      Attributes::F_EXTENDED
+
+      # Returns the Attributes class used by this version of the protocol
+      # (Net::SFTP::Protocol::V04::Attributes, in this case)
+      def attribute_factory
+        V04::Attributes
+      end
+
+      # Returns the Name class used by this version of the protocol
+      # (Net::SFTP::Protocol::V04::Name, in this case)
+      def name_factory
+        V04::Name
+      end
+  end
+
+end; end; end; end

data/lib/net/sftp/protocol/04/name.rb

@@ -0,0 +1,67 @@
+module Net; module SFTP; module Protocol; module V04
+
+  # Represents a single named item on the remote server. This includes the
+  # name, and attributes about the item, and the "longname".
+  #
+  # For backwards compatibility with the format and interface of the Name
+  # structure from previous protocol versions, this also exposes a #longname
+  # method, which returns a string that can be used to display this item in
+  # a directory listing.
+  class Name
+    # The name of the item on the remote server.
+    attr_reader :name
+
+    # Attributes instance describing this item.
+    attr_reader :attributes
+
+    # Create a new Name object with the given name and attributes.
+    def initialize(name, attributes)
+      @name, @attributes = name, attributes
+    end
+
+    # Returns +true+ if the item is a directory.
+    def directory?
+      attributes.directory?
+    end
+
+    # Returns +true+ if the item is a symlink.
+    def symlink?
+      attributes.symlink?
+    end
+
+    # Returns +true+ if the item is a regular file.
+    def file?
+      attributes.file?
+    end
+
+    # Returns a string representing this file, in a format similar to that
+    # used by the unix "ls" utility.
+    def longname
+      @longname ||= begin
+        longname = if directory?
+          "d"
+        elsif symlink?
+          "l"
+        else
+          "-"
+        end
+
+        longname << (attributes.permissions & 0400 != 0 ? "r" : "-")
+        longname << (attributes.permissions & 0200 != 0 ? "w" : "-")
+        longname << (attributes.permissions & 0100 != 0 ? "x" : "-")
+        longname << (attributes.permissions & 0040 != 0 ? "r" : "-")
+        longname << (attributes.permissions & 0020 != 0 ? "w" : "-")
+        longname << (attributes.permissions & 0010 != 0 ? "x" : "-")
+        longname << (attributes.permissions & 0004 != 0 ? "r" : "-")
+        longname << (attributes.permissions & 0002 != 0 ? "w" : "-")
+        longname << (attributes.permissions & 0001 != 0 ? "x" : "-")
+
+        longname << (" %-8s %-8s %8d " % [attributes.owner, attributes.group, attributes.size])
+
+        longname << Time.at(attributes.mtime).strftime("%b %e %H:%M ")
+        longname << name
+      end
+    end
+  end
+
+end; end; end; end

data/lib/net/sftp/protocol/05/base.rb

@@ -0,0 +1,66 @@
+require 'net/sftp/protocol/04/base'
+
+module Net; module SFTP; module Protocol; module V05
+
+  # Wraps the low-level SFTP calls for version 5 of the SFTP protocol.
+  #
+  # None of these protocol methods block--all of them return immediately,
+  # requiring the SSH event loop to be run while the server response is
+  # pending.
+  #
+  # You will almost certainly never need to use this driver directly. Please
+  # see Net::SFTP::Session for the recommended interface.
+  class Base < V04::Base
+    # Returns the protocol version implemented by this driver. (5, in this
+    # case)
+    def version
+      5
+    end
+
+    # Sends a FXP_RENAME packet to the server to request that the file or
+    # directory with the given +name+ (must be a full path) be changed to
+    # +new_name+ (which must also be a path). The +flags+ parameter must be
+    # either +nil+ or 0 (the default), or some combination of the
+    # Net::SFTP::Constants::RenameFlags constants.
+    def rename(name, new_name, flags=nil)
+      send_request(FXP_RENAME, :string, name, :string, new_name, :long, flags || 0)
+    end
+
+    # Sends a FXP_OPEN packet to the server and returns the packet identifier.
+    # The +flags+ parameter is either an integer (in which case it must be
+    # a combination of the IO constants) or a string (in which case it must
+    # be one of the mode strings that IO::open accepts). The +options+
+    # parameter is a hash that is used to construct a new Attribute object,
+    # to pass as part of the FXP_OPEN request.
+    def open(path, flags, options)
+      flags = normalize_open_flags(flags)
+
+      sftp_flags, desired_access = if flags & (IO::WRONLY | IO::RDWR) != 0
+          open = if flags & (IO::CREAT | IO::EXCL) == (IO::CREAT | IO::EXCL)
+            FV5::CREATE_NEW
+          elsif flags & (IO::CREAT | IO::TRUNC) == (IO::CREAT | IO::TRUNC)
+            FV5::CREATE_TRUNCATE
+          elsif flags & IO::CREAT == IO::CREAT
+            FV5::OPEN_OR_CREATE
+          else
+            FV5::OPEN_EXISTING
+          end
+          access = ACE::Mask::WRITE_DATA | ACE::Mask::WRITE_ATTRIBUTES
+          access |= ACE::Mask::READ_DATA | ACE::Mask::READ_ATTRIBUTES if (flags & IO::RDWR) == IO::RDWR
+          if flags & IO::APPEND == IO::APPEND
+            open |= FV5::APPEND_DATA
+            access |= ACE::Mask::APPEND_DATA
+          end
+          [open, access]
+        else
+          [FV5::OPEN_EXISTING, ACE::Mask::READ_DATA | ACE::Mask::READ_ATTRIBUTES]
+        end
+
+      attributes = attribute_factory.new(options)
+
+      send_request(FXP_OPEN, :string, path, :long, desired_access, :long, sftp_flags, :raw, attributes.to_s)
+    end
+
+  end
+
+end; end; end; end

data/lib/net/sftp/protocol/06/attributes.rb

@@ -0,0 +1,107 @@
+require 'net/sftp/protocol/04/attributes'
+
+module Net; module SFTP; module Protocol; module V06
+
+  # A class representing the attributes of a file or directory on the server.
+  # It may be used to specify new attributes, or to query existing attributes.
+  # This particular class is specific to versions 6 and higher of the SFTP
+  # protocol.
+  #
+  # To specify new attributes, just pass a hash as the argument to the
+  # constructor. The following keys are supported:
+  #
+  # * :type:: the type of the item (integer, one of the T_ constants)
+  # * :size:: the size of the item (integer)
+  # * :allocation_size:: the actual number of bytes that the item uses on disk (integer)
+  # * :uid:: the user-id that owns the file (integer)
+  # * :gid:: the group-id that owns the file (integer)
+  # * :owner:: the name of the user that owns the file (string)
+  # * :group:: the name of the group that owns the file (string)
+  # * :permissions:: the permissions on the file (integer, e.g. 0755)
+  # * :atime:: the access time of the file (integer, seconds since epoch)
+  # * :atime_nseconds:: the nanosecond component of atime (integer)
+  # * :createtime:: the time at which the file was created (integer, seconds since epoch)
+  # * :createtime_nseconds:: the nanosecond component of createtime (integer)
+  # * :mtime:: the modification time of the file (integer, seconds since epoch)
+  # * :mtime_nseconds:: the nanosecond component of mtime (integer)
+  # * :ctime:: the time that the file's attributes were last changed (integer)
+  # * :ctime_nseconds:: the nanosecond component of ctime (integer)
+  # * :acl:: an array of ACL entries for the item
+  # * :attrib_bits:: other attributes of the file or directory (as a bit field) (integer)
+  # * :attrib_bits_valid:: a mask describing which bits in attrib_bits are valid (integer)
+  # * :text_hint:: whether the file may or may not contain textual data (integer)
+  # * :mime_type:: the mime type of the file (string)
+  # * :link_count:: the hard link count of the file (integer)
+  # * :untranslated_name:: the value of the filename before filename translation was attempted (string)
+  # * :extended:: a hash of name/value pairs identifying extended info
+  #
+  # Likewise, when the server sends an Attributes object, all of the
+  # above attributes are exposed as methods (though not all will be set with
+  # non-nil values from the server).
+  class Attributes < V04::Attributes
+    F_BITS              = 0x00000200
+    F_ALLOCATION_SIZE   = 0x00000400
+    F_TEXT_HINT         = 0x00000800
+    F_MIME_TYPE         = 0x00001000
+    F_LINK_COUNT        = 0x00002000
+    F_UNTRANSLATED_NAME = 0x00004000
+    F_CTIME             = 0x00008000
+
+    # The array of elements that describe this structure, in order. Used when
+    # parsing and serializing attribute objects.
+    def self.elements #:nodoc:
+      @elements ||= [
+        [:type,                :byte,    0],
+        [:size,                :int64,   F_SIZE],
+        [:allocation_size,     :int64,   F_ALLOCATION_SIZE],
+        [:owner,               :string,  F_OWNERGROUP],
+        [:group,               :string,  F_OWNERGROUP],
+        [:permissions,         :long,    F_PERMISSIONS],
+        [:atime,               :int64,   F_ACCESSTIME],
+        [:atime_nseconds,      :long,    F_ACCESSTIME | F_SUBSECOND_TIMES],
+        [:createtime,          :int64,   F_CREATETIME],
+        [:createtime_nseconds, :long,    F_CREATETIME | F_SUBSECOND_TIMES],
+        [:mtime,               :int64,   F_MODIFYTIME],
+        [:mtime_nseconds,      :long,    F_MODIFYTIME | F_SUBSECOND_TIMES],
+        [:ctime,               :int64,   F_CTIME],
+        [:ctime_nseconds,      :long,    F_CTIME | F_SUBSECOND_TIMES],
+        [:acl,                 :special, F_ACL],
+        [:attrib_bits,         :long,    F_BITS],
+        [:attrib_bits_valid,   :long,    F_BITS],
+        [:text_hint,           :byte,    F_TEXT_HINT],
+        [:mime_type,           :string,  F_MIME_TYPE],
+        [:link_count,          :long,    F_LINK_COUNT],
+        [:untranslated_name,   :string,  F_UNTRANSLATED_NAME],
+        [:extended,            :special, F_EXTENDED]
+      ]
+    end
+
+    # The size on-disk of the file
+    attr_accessor :allocation_size
+
+    # The time at which the file's attributes were last changed
+    attr_accessor :ctime
+
+    # The nanosecond component of #ctime
+    attr_accessor :ctime_nseconds
+
+    # Other attributes of this file or directory (as a bit field)
+    attr_accessor :attrib_bits
+
+    # A bit mask describing which bits in #attrib_bits are valid
+    attr_accessor :attrib_bits_valid
+
+    # Describes whether the file may or may not contain textual data
+    attr_accessor :text_hint
+
+    # The mime-type of the file
+    attr_accessor :mime_type
+
+    # The hard link count for the file
+    attr_accessor :link_count
+
+    # The value of the file name before filename translation was attempted
+    attr_accessor :untranslated_name
+  end
+
+end; end; end; end

data/lib/net/sftp/protocol/06/base.rb

@@ -0,0 +1,63 @@
+require 'net/sftp/protocol/05/base'
+require 'net/sftp/protocol/06/attributes'
+
+module Net; module SFTP; module Protocol; module V06
+
+  # Wraps the low-level SFTP calls for version 6 of the SFTP protocol.
+  #
+  # None of these protocol methods block--all of them return immediately,
+  # requiring the SSH event loop to be run while the server response is
+  # pending.
+  #
+  # You will almost certainly never need to use this driver directly. Please
+  # see Net::SFTP::Session for the recommended interface.
+  class Base < V05::Base
+
+    # Returns the protocol version implemented by this driver. (6, in this
+    # case)
+    def version
+      6
+    end
+
+    # Sends a FXP_LINK packet to the server to request that a link be created
+    # at +new_link_path+, pointing to +existing_path+. If +symlink+ is true, a
+    # symbolic link will be created; otherwise a hard link will be created.
+    def link(new_link_path, existing_path, symlink)
+      send_request(FXP_LINK, :string, new_link_path, :string, existing_path, :bool, symlink)
+    end
+
+    # Provided for backwards compatibility; v6 of the SFTP protocol removes the
+    # older FXP_SYMLINK packet type, so this method simply calls the #link
+    # method.
+    def symlink(path, target)
+      link(path, target, true)
+    end
+
+    # Sends a FXP_BLOCK packet to the server to request that a byte-range lock
+    # be obtained on the given +handle+, for the given byte +offset+ and
+    # +length+. The +mask+ parameter is a bitfield indicating what kind of
+    # lock to acquire, and must be a combination of one or more of the
+    # Net::SFTP::Constants::LockTypes constants.
+    def block(handle, offset, length, mask)
+      send_request(FXP_BLOCK, :string, handle, :int64, offset, :int64, length, :long, mask)
+    end
+
+    # Sends a FXP_UNBLOCK packet to the server to request that a previously
+    # acquired byte-range lock be released on the given +handle+, for the
+    # given byte +offset+ and +length+. The +handle+, +offset+, and +length+
+    # must all exactly match the parameters that were given when the lock was
+    # originally acquired (see #block).
+    def unblock(handle, offset, length)
+      send_request(FXP_UNBLOCK, :string, handle, :int64, offset, :int64, length)
+    end
+
+    protected
+
+      # Returns the Attributes class used by this version of the protocol
+      # (Net::SFTP::Protocol::V06::Attributes, in this case)
+      def attribute_factory
+        V06::Attributes
+      end
+  end
+
+end; end; end; end

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

@@ -0,0 +1,50 @@
+require 'net/ssh/loggable'
+require 'net/sftp/constants'
+
+module Net; module SFTP; module Protocol
+
+  # The abstract superclass of the specific implementations for each supported
+  # SFTP protocol version. It implements general packet parsing logic, and
+  # provides a way for subclasses to send requests.
+  class Base
+    include Net::SSH::Loggable
+    include Net::SFTP::Constants
+    include Net::SFTP::Constants::PacketTypes
+
+    # The SFTP session object that acts as client to this protocol instance
+    attr_reader :session
+
+    # Create a new instance of a protocol driver, servicing the given session.
+    def initialize(session)
+      @session = session
+      self.logger = session.logger
+      @request_id_counter = -1
+    end
+
+    # Attept to parse the given packet. If the packet is of an unsupported
+    # type, an exception will be raised. Returns the parsed data as a hash
+    # (the keys in the hash are packet-type specific).
+    def parse(packet)
+      case packet.type
+      when FXP_STATUS then parse_status_packet(packet)
+      when FXP_HANDLE then parse_handle_packet(packet)
+      when FXP_DATA   then parse_data_packet(packet)
+      when FXP_NAME   then parse_name_packet(packet)
+      when FXP_ATTRS  then parse_attrs_packet(packet)
+      else raise NotImplementedError, "unknown packet type: #{packet.type}"
+      end
+    end
+
+    private
+
+      # Send a new packet of the given type, and with the given data arguments.
+      # A new request identifier will be allocated to this request, and will
+      # be returned.
+      def send_request(type, *args)
+        @request_id_counter += 1
+        session.send_packet(type, :long, @request_id_counter, *args)
+        return @request_id_counter
+      end
+  end
+
+end; end; end