net-sftp-backports 4.0.0.backports

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

@@ -0,0 +1,315 @@
+require 'net/ssh/buffer'
+
+module Net; module SFTP; module Protocol; module V01
+
+  # 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.
+  #
+  # To specify new attributes, just pass a hash as the argument to the
+  # constructor. The following keys are supported:
+  #
+  # * :size:: the size of the file
+  # * :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)
+  # * :mtime:: the modification time of the file (integer, seconds since epoch)
+  # * :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
+
+    F_SIZE        = 0x00000001
+    F_UIDGID      = 0x00000002
+    F_PERMISSIONS = 0x00000004
+    F_ACMODTIME   = 0x00000008
+    F_EXTENDED    = 0x80000000
+
+    T_REGULAR      = 1
+    T_DIRECTORY    = 2
+    T_SYMLINK      = 3
+    T_SPECIAL      = 4
+    T_UNKNOWN      = 5
+    T_SOCKET       = 6
+    T_CHAR_DEVICE  = 7
+    T_BLOCK_DEVICE = 8
+    T_FIFO         = 9
+
+    class <<self
+      # Returns the array of attribute meta-data that defines the structure of
+      # the attributes packet as described by this version of the protocol.
+      def elements #:nodoc:
+        @elements ||= [
+          [:size,                :int64,   F_SIZE],
+          [:uid,                 :long,    F_UIDGID],
+          [:gid,                 :long,    F_UIDGID],
+          [:permissions,         :long,    F_PERMISSIONS],
+          [:atime,               :long,    F_ACMODTIME],
+          [:mtime,               :long,    F_ACMODTIME],
+          [:extended,            :special, F_EXTENDED]
+        ]
+      end
+
+      # Parses the given buffer and returns an Attributes object compsed from
+      # the data extracted from it.
+      def from_buffer(buffer)
+        flags = buffer.read_long
+        data = {}
+
+        elements.each do |name, type, condition|
+          if flags & condition == condition
+            if type == :special
+              data[name] = send("parse_#{name}", buffer)
+            else
+              data[name] = buffer.send("read_#{type}")
+            end
+          end
+        end
+
+        new(data)
+      end
+
+      # A convenience method for defining methods that expose specific
+      # attributes. This redefines the standard attr_accessor (an admittedly
+      # bad practice) because (1) I don't need any "regular" accessors, and
+      # (2) because rdoc will automatically pick up and note methods defined
+      # via attr_accessor.
+      def attr_accessor(name) #:nodoc:
+        class_eval <<-CODE
+          def #{name}
+            attributes[:#{name}]
+          end
+        CODE
+
+        attr_writer(name)
+      end
+
+      # A convenience method for defining methods that expose specific
+      # attributes. This redefines the standard attr_writer (an admittedly
+      # bad practice) because (1) I don't need any "regular" accessors, and
+      # (2) because rdoc will automatically pick up and note methods defined
+      # via attr_writer.
+      def attr_writer(name) #:nodoc:
+        class_eval <<-CODE
+          def #{name}=(value)
+            attributes[:#{name}] = value
+          end
+        CODE
+      end
+
+      private
+
+        # Parse the hash of extended data from the buffer.
+        def parse_extended(buffer)
+          extended = Hash.new
+          buffer.read_long.times do
+            extended[buffer.read_string] = buffer.read_string
+          end
+          extended
+        end
+    end
+
+    # The hash of name/value pairs that backs this Attributes instance
+    attr_reader   :attributes
+
+    # The size of the file.
+    attr_accessor :size
+
+    # The user-id of the user that owns the file
+    attr_writer   :uid
+
+    # The group-id of the user that owns the file
+    attr_writer   :gid
+
+    # The permissions on the file
+    attr_accessor :permissions
+
+    # The last access time of the file
+    attr_accessor :atime
+
+    # The modification time of the file
+    attr_accessor :mtime
+
+    # The hash of name/value pairs identifying extended information about the file
+    attr_accessor :extended
+
+    # Create a new Attributes instance with the given attributes. The
+    # following keys are supported:
+    #
+    # * :size:: the size of the file
+    # * :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)
+    # * :mtime:: the modification time of the file (integer, seconds since epoch)
+    # * :extended:: a hash of name/value pairs identifying extended info
+    def initialize(attributes={})
+      @attributes = attributes
+    end
+
+    # Returns the user-id of the user that owns the file, or +nil+ if that
+    # information is not available. If an :owner key exists, but not a :uid
+    # key, the Etc module will be used to reverse lookup the id from the name.
+    # This might fail on some systems (e.g., Windows).
+    def uid
+      if attributes[:owner] && !attributes.key?(:uid)
+        require 'etc'
+        attributes[:uid] = Etc.getpwnam(attributes[:owner]).uid
+      end
+      attributes[:uid]
+    end
+
+    # Returns the group-id of the group that owns the file, or +nil+ if that
+    # information is not available. If a :group key exists, but not a :gid
+    # key, the Etc module will be used to reverse lookup the id from the name.
+    # This might fail on some systems (e.g., Windows).
+    def gid
+      if attributes[:group] && !attributes.key?(:gid)
+        require 'etc'
+        attributes[:gid] = Etc.getgrnam(attributes[:group]).gid
+      end
+      attributes[:gid]
+    end
+
+    # Returns the username of the user that owns the file, or +nil+ if that
+    # information is not available. If the :uid is given, but not the :owner,
+    # the Etc module will be used to lookup the name from the id. This might
+    # fail on some systems (e.g. Windows).
+    def owner
+      if attributes[:uid] && !attributes[:owner]
+        require 'etc'
+        attributes[:owner] = Etc.getpwuid(attributes[:uid].to_i).name
+      end
+      attributes[:owner]
+    end
+
+    # Returns the group name of the group that owns the file, or +nil+ if that
+    # information is not available. If the :gid is given, but not the :group,
+    # the Etc module will be used to lookup the name from the id. This might
+    # fail on some systems (e.g. Windows).
+    def group
+      if attributes[:gid] && !attributes[:group]
+        require 'etc'
+        attributes[:group] = Etc.getgrgid(attributes[:gid].to_i).name
+      end
+      attributes[:group]
+    end
+
+    # Inspects the permissions bits to determine what type of entity this
+    # attributes object represents. If will return one of the T_ constants.
+    def type
+      if    permissions & 0140000 == 0140000 then 
+        T_SOCKET
+      elsif permissions & 0120000 == 0120000 then 
+        T_SYMLINK
+      elsif permissions & 0100000 == 0100000 then
+        T_REGULAR
+      elsif permissions &  060000 ==  060000 then
+        T_BLOCK_DEVICE
+      elsif permissions &  040000 ==  040000 then
+        T_DIRECTORY
+      elsif permissions &  020000 ==  020000 then
+        T_CHAR_DEVICE
+      elsif permissions &  010000 ==  010000 then
+        T_FIFO
+      else
+        T_UNKNOWN
+      end
+    end
+
+    # Returns the type as a symbol, rather than an integer, for easier use in
+    # Ruby programs.
+    def symbolic_type
+      case type
+      when T_SOCKET       then :socket
+      when T_SYMLINK      then :symlink
+      when T_REGULAR      then :regular
+      when T_BLOCK_DEVICE then :block_device
+      when T_DIRECTORY    then :directory
+      when T_CHAR_DEVICE  then :char_device
+      when T_FIFO         then :fifo
+      when T_SPECIAL      then :special
+      when T_UNKNOWN      then :unknown
+      else raise NotImplementedError, "unknown file type #{type} (bug?)"
+      end
+    end
+
+    # Returns true if these attributes appear to describe a directory.
+    def directory?
+      case type
+      when T_DIRECTORY then true
+      when T_UNKNOWN   then nil
+      else false
+      end
+    end
+
+    # Returns true if these attributes appear to describe a symlink.
+    def symlink?
+      case type
+      when T_SYMLINK then true
+      when T_UNKNOWN then nil
+      else false
+      end
+    end
+
+    # Returns true if these attributes appear to describe a regular file.
+    def file?
+      case type
+      when T_REGULAR then true
+      when T_UNKNOWN then nil
+      else false
+      end
+    end
+
+    # Convert the object to a string suitable for passing in an SFTP
+    # packet. This is the raw representation of the attribute packet payload,
+    # and is not intended to be human readable.
+    def to_s
+      prepare_serialization!
+
+      flags = 0
+
+      self.class.elements.each do |name, type, condition|
+        flags |= condition if attributes[name]
+      end
+
+      buffer = Net::SSH::Buffer.from(:long, flags)
+      self.class.elements.each do |name, type, condition|
+        if flags & condition == condition
+          if type == :special
+            send("encode_#{name}", buffer)
+          else
+            buffer.send("write_#{type}", attributes[name])
+          end
+        end
+      end
+
+      buffer.to_s
+    end
+
+    private
+
+      # Perform protocol-version-specific preparations for serialization.
+      def prepare_serialization!
+        # force the uid/gid to be translated from owner/group, if those keys
+        # were given on instantiation
+        uid
+        gid
+      end
+
+      # Encodes information about the extended info onto the end of the given
+      # buffer.
+      def encode_extended(buffer)
+        buffer.write_long extended.size
+        extended.each { |k,v| buffer.write_string k, v }
+      end
+
+  end
+
+end ; end ; end ; end

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

@@ -0,0 +1,268 @@
+require 'net/ssh/loggable'
+require 'net/sftp/constants'
+require 'net/sftp/packet'
+require 'net/sftp/protocol/base'
+require 'net/sftp/protocol/01/attributes'
+require 'net/sftp/protocol/01/name'
+
+module Net; module SFTP; module Protocol; module V01
+
+  # Wraps the low-level SFTP calls for version 1 of the SFTP protocol. Also
+  # implements the packet parsing as defined by version 1 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 < Protocol::Base
+    include Net::SFTP::Constants::OpenFlags
+
+    # Returns the protocol version implemented by this driver. (1, in this
+    # case)
+    def version
+      1
+    end
+
+    # Parses the given FXP_HANDLE packet and returns a hash with one key,
+    # :handle, which references the handle.
+    def parse_handle_packet(packet)
+      { :handle => packet.read_string }
+    end
+
+    # Parses the given FXP_STATUS packet and returns a hash with one key,
+    # :code, which references the status code returned by the server.
+    def parse_status_packet(packet)
+      { :code => packet.read_long }
+    end
+
+    # Parses the given FXP_DATA packet and returns a hash with one key,
+    # :data, which references the data returned in the packet.
+    def parse_data_packet(packet)
+      { :data => packet.read_string }
+    end
+
+    # Parses the given FXP_ATTRS packet and returns a hash with one key,
+    # :attrs, which references an Attributes object.
+    def parse_attrs_packet(packet)
+      { :attrs => attribute_factory.from_buffer(packet) }
+    end
+
+    # Parses the given FXP_NAME packet and returns a hash with one key, :names,
+    # which references an array of Name objects.
+    def parse_name_packet(packet)
+      names = []
+
+      packet.read_long.times do
+        filename = packet.read_string
+        longname = packet.read_string
+        attrs    = attribute_factory.from_buffer(packet)
+        names   << name_factory.new(filename, longname, attrs)
+      end
+
+      { :names => names }
+    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)
+
+      if flags & (IO::WRONLY | IO::RDWR) != 0
+        sftp_flags = FV1::WRITE
+        sftp_flags |= FV1::READ if flags & IO::RDWR != 0
+        sftp_flags |= FV1::APPEND if flags & IO::APPEND != 0
+      else
+        sftp_flags = FV1::READ
+      end
+
+      sftp_flags |= FV1::CREAT if flags & IO::CREAT != 0
+      sftp_flags |= FV1::TRUNC if flags & IO::TRUNC != 0
+      sftp_flags |= FV1::EXCL  if flags & IO::EXCL  != 0
+
+      attributes = attribute_factory.new(options)
+
+      send_request(FXP_OPEN, :string, path, :long, sftp_flags, :raw, attributes.to_s)
+    end
+
+    # Sends a FXP_CLOSE packet to the server for the given +handle+ (such as
+    # would be returned via a FXP_HANDLE packet). Returns the new packet id.
+    def close(handle)
+      send_request(FXP_CLOSE, :string, handle)
+    end
+
+    # Sends a FXP_READ packet to the server, requesting that +length+ bytes
+    # be read from the file identified by +handle+, starting at +offset+ bytes
+    # within the file. The handle must be one that was returned via a
+    # FXP_HANDLE packet. Returns the new packet id.
+    def read(handle, offset, length)
+      send_request(FXP_READ, :string, handle, :int64, offset, :long, length)
+    end
+
+    # Sends a FXP_WRITE packet to the server, requesting that +data+ (a string),
+    # be written to the file identified by +handle+, starting at +offset+ bytes
+    # from the beginning of the file. The handle must be one that was returned
+    # via a FXP_HANDLE packet. Returns the new packet id.
+    def write(handle, offset, data)
+      send_request(FXP_WRITE, :string, handle, :int64, offset, :string, data)
+    end
+
+    # Sends a FXP_LSTAT packet to the server, requesting a FXP_ATTR response
+    # for the file at the given remote +path+ (a string). The +flags+ parameter
+    # is ignored in this version of the protocol. #lstat will not follow
+    # symbolic links; see #stat for a version that will.
+    def lstat(path, flags=nil)
+      send_request(FXP_LSTAT, :string, path)
+    end
+
+    # Sends a FXP_FSTAT packet to the server, requesting a FXP_ATTR response
+    # for the file represented by the given +handle+ (which must have been
+    # obtained from a FXP_HANDLE packet). The +flags+ parameter is ignored in
+    # this version of the protocol.
+    def fstat(handle, flags=nil)
+      send_request(FXP_FSTAT, :string, handle)
+    end
+
+    # Sends a FXP_SETSTAT packet to the server, to update the attributes for
+    # the file at the given remote +path+ (a string). The +attrs+ parameter is
+    # a hash that defines the attributes to set.
+    def setstat(path, attrs)
+      send_request(FXP_SETSTAT, :string, path, :raw, attribute_factory.new(attrs).to_s)
+    end
+
+    # Sends a FXP_FSETSTAT packet to the server, to update the attributes for
+    # the file represented by the given +handle+ (which must have been obtained
+    # from a FXP_HANDLE packet). The +attrs+ parameter is a hash that defines
+    # the attributes to set.
+    def fsetstat(handle, attrs)
+      send_request(FXP_FSETSTAT, :string, handle, :raw, attribute_factory.new(attrs).to_s)
+    end
+
+    # Sends a FXP_OPENDIR packet to the server, to request a handle for
+    # manipulating the directory at the given remote +path+.
+    def opendir(path)
+      send_request(FXP_OPENDIR, :string, path)
+    end
+
+    # Sends a FXP_READDIR packet to the server, to request a batch of
+    # directory name entries in the directory identified by +handle+ (which
+    # must have been obtained via a FXP_OPENDIR request).
+    def readdir(handle)
+      send_request(FXP_READDIR, :string, handle)
+    end
+
+    # Sends a FXP_REMOTE packet to the server, to request that the given
+    # file be deleted from the remote server.
+    def remove(filename)
+      send_request(FXP_REMOVE, :string, filename)
+    end
+
+    # Sends a FXP_MKDIR packet to the server, to request that a new directory
+    # at +path+ on the remote server be created, and with +attrs+ (a hash)
+    # describing the attributes of the new directory.
+    def mkdir(path, attrs)
+      send_request(FXP_MKDIR, :string, path, :raw, attribute_factory.new(attrs).to_s)
+    end
+
+    # Sends a FXP_RMDIR packet to the server, to request that the directory
+    # at +path+ on the remote server be deleted.
+    def rmdir(path)
+      send_request(FXP_RMDIR, :string, path)
+    end
+
+    # Sends a FXP_REALPATH packet to the server, to request that the given
+    # +path+ be canonicalized, taking into account path segments like "..".
+    def realpath(path)
+      send_request(FXP_REALPATH, :string, path)
+    end
+
+    # Sends a FXP_STAT packet to the server, requesting a FXP_ATTR response
+    # for the file at the given remote +path+ (a string). The +flags+ parameter
+    # is ignored in this version of the protocol. #stat will follow
+    # symbolic links; see #lstat for a version that will not.
+    def stat(path, flags=nil)
+      send_request(FXP_STAT, :string, path)
+    end
+
+    # Not implemented in version 1 of the SFTP protocol. Raises a
+    # NotImplementedError if called.
+    def rename(name, new_name, flags=nil)
+      not_implemented! :rename
+    end
+
+    # Not implemented in version 1 of the SFTP protocol. Raises a
+    # NotImplementedError if called.
+    def readlink(path)
+      not_implemented! :readlink
+    end
+
+    # Not implemented in version 1 of the SFTP protocol. Raises a
+    # NotImplementedError if called.
+    def symlink(path, target)
+      not_implemented! :symlink
+    end
+
+    # Not implemented in version 1 of the SFTP protocol. Raises a
+    # NotImplementedError if called.
+    def link(*args)
+      not_implemented! :link
+    end
+
+    # Not implemented in version 1 of the SFTP protocol. Raises a
+    # NotImplementedError if called.
+    def block(handle, offset, length, mask)
+      not_implemented! :block
+    end
+
+    # Not implemented in version 1 of the SFTP protocol. Raises a
+    # NotImplementedError if called.
+    def unblock(handle, offset, length)
+      not_implemented! :unblock
+    end
+
+    protected
+
+      # A helper method for implementing wrappers for operations that are
+      # not implemented by the current SFTP protocol version. Simply raises
+      # NotImplementedError with a message based on the given operation name.
+      def not_implemented!(operation)
+        raise NotImplementedError, "the #{operation} operation is not available in the version of the SFTP protocol supported by your server"
+      end
+
+      # Normalizes the given flags parameter, converting it into a combination
+      # of IO constants.
+      def normalize_open_flags(flags)
+        if String === flags
+          case flags.tr("b", "")
+          when "r"  then IO::RDONLY
+          when "r+" then IO::RDWR
+          when "w"  then IO::WRONLY | IO::TRUNC | IO::CREAT
+          when "w+" then IO::RDWR | IO::TRUNC | IO::CREAT
+          when "a"  then IO::APPEND | IO::CREAT | IO::WRONLY
+          when "a+" then IO::APPEND | IO::CREAT | IO::RDWR
+          else raise ArgumentError, "unsupported flags: #{flags.inspect}"
+          end
+        else
+          flags.to_i
+        end
+      end
+
+      # Returns the Attributes class used by this version of the protocol
+      # (Net::SFTP::Protocol::V01::Attributes, in this case)
+      def attribute_factory
+        V01::Attributes
+      end
+
+      # Returns the Name class used by this version of the protocol
+      # (Net::SFTP::Protocol::V01::Name, in this case)
+      def name_factory
+        V01::Name
+      end
+  end
+
+end; end; end; end

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

@@ -0,0 +1,43 @@
+module Net; module SFTP; module Protocol; module V01
+
+  # Represents a single named item on the remote server. This includes the
+  # name, attributes about the item, and the "longname", which is intended
+  # for use when displaying directory data, and has no specified format.
+  class Name
+    # The name of the item on the remote server.
+    attr_reader :name
+
+    # The display-ready name of the item, possibly with other attributes.
+    attr_reader :longname
+
+    # The Attributes object describing this item.
+    attr_reader :attributes
+
+    # Create a new Name object with the given name, longname, and attributes.
+    def initialize(name, longname, attributes)
+      @name, @longname, @attributes = name, longname, attributes
+    end
+
+    # Returns +true+ if the item appears to be a directory. It does this by
+    # examining the attributes. If there is insufficient information in the
+    # attributes, this will return nil, rather than a boolean.
+    def directory?
+      attributes.directory?
+    end
+
+    # Returns +true+ if the item appears to be a symlink. It does this by
+    # examining the attributes. If there is insufficient information in the
+    # attributes, this will return nil, rather than a boolean.
+    def symlink?
+      attributes.symlink?
+    end
+
+    # Returns +true+ if the item appears to be a regular file. It does this by
+    # examining the attributes. If there is insufficient information in the
+    # attributes, this will return nil, rather than a boolean.
+    def file?
+      attributes.file?
+    end
+  end
+
+end; end; end; end

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

@@ -0,0 +1,31 @@
+require 'net/sftp/protocol/01/base'
+
+module Net; module SFTP; module Protocol; module V02
+
+  # Wraps the low-level SFTP calls for version 2 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 < V01::Base
+
+    # Returns the protocol version implemented by this driver. (2, in this
+    # case)
+    def version
+      2
+    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 is
+    # ignored in this version of the protocol.
+    def rename(name, new_name, flags=nil)
+      send_request(FXP_RENAME, :string, name, :string, new_name)
+    end
+
+  end
+
+end; end; end; end

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

@@ -0,0 +1,35 @@
+require 'net/sftp/protocol/02/base'
+
+module Net; module SFTP; module Protocol; module V03
+
+  # Wraps the low-level SFTP calls for version 3 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 < V02::Base
+
+    # Returns the protocol version implemented by this driver. (3, in this
+    # case)
+    def version
+      3
+    end
+
+    # Sends a FXP_READLINK packet to the server to request that the target of
+    # the given symlink on the remote host (+path+) be returned.
+    def readlink(path)
+      send_request(FXP_READLINK, :string, path)
+    end
+
+    # Sends a FXP_SYMLINK packet to the server to request that a symlink at the
+    # given +path+ be created, pointing at +target+..
+    def symlink(path, target)
+      send_request(FXP_SYMLINK, :string, path, :string, target)
+    end
+
+  end
+
+end; end; end; end