net-sftp 1.1.1 → 2.0.0

data/lib/net/sftp/packet.rb

@@ -0,0 +1,21 @@
+require 'net/ssh/buffer'
+
+module Net; module SFTP
+
+  # A specialization of the Net::SSH::Buffer class, which simply auto-reads
+  # the type byte from the front of every packet it represents.
+  class Packet < Net::SSH::Buffer
+    # The (intger) type of this packet. See Net::SFTP::Constants for all
+    # possible packet types.
+    attr_reader :type
+
+    # Create a new Packet object that wraps the given +data+ (which should be
+    # a String). The first byte of the data will be consumed automatically and
+    # interpreted as the #type of this packet.
+    def initialize(data)
+      super
+      @type = read_byte
+    end
+  end
+
+end; end

data/lib/net/sftp/protocol.rb

@@ -0,0 +1,32 @@
+require 'net/sftp/protocol/01/base'
+require 'net/sftp/protocol/02/base'
+require 'net/sftp/protocol/03/base'
+require 'net/sftp/protocol/04/base'
+require 'net/sftp/protocol/05/base'
+require 'net/sftp/protocol/06/base'
+
+module Net; module SFTP
+
+  # The Protocol module contains the definitions for all supported SFTP
+  # protocol versions.
+  module Protocol
+
+    # Instantiates and returns a new protocol driver instance for the given
+    # protocol version. +session+ must be a valid SFTP session object, and
+    # +version+ must be an integer. If an unsupported version is given,
+    # an exception will be raised.
+    def self.load(session, version)
+      case version
+      when 1 then V01::Base.new(session)
+      when 2 then V02::Base.new(session)
+      when 3 then V03::Base.new(session)
+      when 4 then V04::Base.new(session)
+      when 5 then V05::Base.new(session)
+      when 6 then V06::Base.new(session)
+      else raise NotImplementedError, "unsupported SFTP version #{version.inspect}"
+      end
+    end
+
+  end
+
+end; end

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

@@ -1,23 +1,26 @@
-#--
-# =============================================================================
-# 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
-# =============================================================================
-#++
-
-module Net ; module SFTP ; module Protocol ; module V_01
+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
@@ -25,122 +28,288 @@ module Net ; module SFTP ; module Protocol ; module V_01
     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
-    attr_accessor :uid
-    attr_accessor :gid
+
+    # 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
 
-    # An initialization routine, to grant the class (factory) access to a
-    # buffer factory. The buffer factory is used by the class' #to_s
-    # method to encode the object's attributes.
+    # Create a new Attributes instance with the given attributes. The
+    # following keys are supported:
     #
-    # This returns +self+, making it suitable for chaining.
-    def self.init( buffers )
-      @buffers = buffers
-      self
+    # * :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 buffer factory for this class.
-    def self.buffers
-      @buffers
+    # 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 buffer factory for the object's class.
-    def buffers
-      self.class.buffers
+    # 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
 
-    # Create a new, empty Attributes object.
-    def self.empty
-      new
+    # 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
 
-    # Create a new Attributes object, initialized from the given buffer.
-    def self.from_buffer( buffer )
-      flags = buffer.read_long
-
-      size = buffer.read_int64 if ( flags & F_SIZE ) != 0
-      uid = buffer.read_long if ( flags & F_UIDGID ) != 0
-      gid = buffer.read_long if ( flags & F_UIDGID ) != 0
-      permissions = buffer.read_long if ( flags & F_PERMISSIONS ) != 0
-      atime = buffer.read_long if ( flags & F_ACMODTIME ) != 0
-      mtime = buffer.read_long if ( flags & F_ACMODTIME ) != 0
-
-      if ( flags & F_EXTENDED ) != 0
-        extended = Hash.new
-        buffer.read_long.times do
-          extended[ buffer.read_string ] = buffer.read_string
-        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
 
-      new( size, uid, gid, permissions, atime, mtime, extended )
+    # 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
 
-    # Create a new attributes object, initialized from the given hash. The
-    # :owner and :group attributes are treated specially; they are not actually
-    # supported by this version of the protocol, but are instead converted
-    # by this method to their corresponding id numbers, and assigned
-    # (respectively) to :uid and :gid.
-    def self.from_hash( hash )
-      if hash[:owner]
-        require 'etc'
-        hash[:uid] = Etc.getpwnam( hash[:owner] ).uid
+    # 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
 
-      if hash[:group]
-        require 'etc'
-        hash[:gid] = Etc.getgrnam( hash[:group] ).gid
+    # 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
 
-      new hash[:size], hash[:uid], hash[:gid], hash[:permissions],
-        hash[:atime], hash[:mtime], hash[:extended]
+    # 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
 
-    private_class_method :new
-
-    # Create a new Attributes with the given attributes.
-    def initialize( size=nil, uid=nil, gid=nil, permissions=nil,
-      atime=nil, mtime=nil, extended=nil )
-    # begin
-      @size = size
-      @uid = uid
-      @gid = gid
-      @permissions = permissions
-      @atime = atime
-      @mtime = mtime
-      @extended = extended
+    # 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.
+    # packet. This is the raw representation of the attribute packet payload,
+    # and is not intended to be human readable.
     def to_s
-      flags = 0
+      prepare_serialization!
 
-      flags |= F_SIZE if @size
-      flags |= F_UIDGID if @uid && @gid
-      flags |= F_PERMISSIONS if @permissions
-      flags |= F_ACMODTIME if @atime && @mtime
-      flags |= F_EXTENDED if @extended
+      flags = 0
 
-      buffer = buffers.writer
-      buffer.write_long flags
-      buffer.write_int64 @size if @size
-      buffer.write_long @uid, @gid if @uid && @gid
-      buffer.write_long @permissions if @permissions
-      buffer.write_long @atime, @mtime if @atime && @mtime
+      self.class.elements.each do |name, type, condition|
+        flags |= condition if attributes[name]
+      end
 
-      if @extended
-        buffer.write_long @extended.size
-        @extended.each { |k,v| buffer.write_string k, v }
+      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