net-sftp 1.1.1 → 2.0.0

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

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

@@ -1,227 +1,152 @@
-#--
-# =============================================================================
-# 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_04
-
-  # Version 4 of the SFTP protocol made some pretty significant alterations to
-  # the File Attributes data type. This encapsulates those changes.
-  class Attributes
-
-    F_SIZE              = 0x00000001
-    F_PERMISSIONS       = 0x00000004
+require 'net/sftp/protocol/01/attributes'
+
+module Net; module SFTP; module Protocol; module V04
+
+  # 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 4 and 5 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)
+  # * :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)
+  # * :acl:: an array of ACL entries for the item
+  # * :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 < V01::Attributes
+
     F_ACCESSTIME        = 0x00000008
     F_CREATETIME        = 0x00000010
     F_MODIFYTIME        = 0x00000020
     F_ACL               = 0x00000040
     F_OWNERGROUP        = 0x00000080
     F_SUBSECOND_TIMES   = 0x00000100
-    F_EXTENDED          = 0x80000000
     
-    attr_accessor :type
-    attr_accessor :size
-    attr_accessor :owner
-    attr_accessor :group
-    attr_accessor :permissions
-    attr_accessor :atime
-    attr_accessor :atime_nseconds
-    attr_accessor :ctime
-    attr_accessor :ctime_nseconds
-    attr_accessor :mtime
-    attr_accessor :mtime_nseconds
-    attr_accessor :acl
-    attr_accessor :extended
+    # A simple struct for representing a single entry in an Access Control
+    # List. (See Net::SFTP::Constants::ACE)
+    ACL = Struct.new(:type, :flag, :mask, :who)
+
+    class <<self
+      # The list of supported elements in the attributes structure as defined
+      # by v4 of the sftp protocol.
+      def elements #:nodoc:
+        @elements ||= [
+          [:type,                :byte,    0],
+          [:size,                :int64,   V01::Attributes::F_SIZE],
+          [:owner,               :string,  F_OWNERGROUP],
+          [:group,               :string,  F_OWNERGROUP],
+          [:permissions,         :long,    V01::Attributes::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],
+          [:acl,                 :special, F_ACL],
+          [:extended,            :special, V01::Attributes::F_EXTENDED]
+        ]
+      end
 
-    ACL = Struct.new( :type, :flag, :mask, :who )
+      private
 
-    # An initializer for specifying the buffer factory that should be used by
-    # instances of this class.
-    def self.init( buffers )
-      @buffers = buffers
-      self
+        # A helper method for parsing the ACL entry in an Attributes struct.
+        def parse_acl(buffer)
+          acl_buf = Net::SSH::Buffer.new(buffer.read_string)
+          acl = []
+          acl_buf.read_long.times do
+            acl << ACL.new(acl_buf.read_long, acl_buf.read_long, acl_buf.read_long, acl_buf.read_string)
+          end
+          acl
+        end
     end
 
-    # Return a reference to the buffer factory in use by this class.
-    def self.buffers
-      @buffers
-    end
+    # The type of the item on the remote server. Must be one of the T_* constants.
+    attr_accessor :type
 
-    # A convenience for obtaining a reference to the buffer factory used by
-    # this instance's class.
-    def buffers
-      self.class.buffers
-    end
+    # The owner of the item on the remote server, as a string.
+    attr_writer   :owner
 
-    # Return an empty Attributes instance.
-    def self.empty
-      new
-    end
+    # The group of the item on the remote server, as a string.
+    attr_writer   :group
 
-    # Return an Attributes instance initialized from the given buffer.
-    def self.from_buffer( buffer )
-      flags = buffer.read_long
-
-      type = buffer.read_byte
-      size = buffer.read_int64 if ( flags & F_SIZE ) != 0
-      owner = buffer.read_string if ( flags & F_OWNERGROUP ) != 0
-      group = buffer.read_string if ( flags & F_OWNERGROUP ) != 0
-      permissions = buffer.read_long if ( flags & F_PERMISSIONS ) != 0
-      if ( flags & F_ACCESSTIME ) != 0
-        atime = buffer.read_int64
-        atime_nseconds = buffer.read_long if ( flags & F_SUBSECOND_TIMES ) != 0
-      end
-      if ( flags & F_CREATETIME ) != 0
-        ctime = buffer.read_int64
-        ctime_nseconds = buffer.read_long if ( flags & F_SUBSECOND_TIMES ) != 0
-      end
-      if ( flags & F_MODIFYTIME ) != 0
-        mtime = buffer.read_int64
-        mtime_nseconds = buffer.read_long if ( flags & F_SUBSECOND_TIMES ) != 0
-      end
-      if ( flags & F_ACL ) != 0
-        acl_buf = buffers.reader( buffer.read_string )
-        acl = []
-        acl_buf.read_long.times do
-          acl << ACL.new( acl_buf.read_long,
-                          acl_buf.read_long,
-                          acl_buf.read_long,
-                          acl_buf.read_string )
-        end
-      end
+    # The nanosecond component of the access time.
+    attr_accessor :atime_nseconds
 
-      if ( flags & F_EXTENDED ) != 0
-        extended = Hash.new
-        buffer.read_long.times do
-          extended[ buffer.read_string ] = buffer.read_string
-        end
-      end
+    # The creation time of the remote item, in seconds since the epoch.
+    attr_accessor :createtime
 
-      new( type, size, owner, group, permissions, atime, atime_nseconds,
-        ctime, ctime_nseconds, mtime, mtime_nseconds, acl, extended )
-    end
+    # The nanosecond component of the creation time.
+    attr_accessor :createtime_nseconds
 
-    # Create a new attributes object, initialized from the given hash. The
-    # :uid and :gid 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 names, and assigned (respectively)
-    # to :owner and :group.
-    def self.from_hash( hash )
-      if hash.has_key?(:uid)
-        require 'etc'
-        hash[:owner] = Etc.getpwuid( hash[:uid] ).name
-      end
+    # The nanosecond component of the modification time.
+    attr_accessor :mtime_nseconds
 
-      if hash.has_key?(:gid)
-        require 'etc'
-        hash[:group] = Etc.getgrgid( hash[:gid] ).name
-      end
+    # The array of access control entries for this item.
+    attr_accessor :acl
 
-      new hash[:type] || T_REGULAR, hash[:size], hash[:owner], hash[:group],
-        hash[:permissions], hash[:atime], hash[:atime_nseconds],
-        hash[:ctime], hash[:ctime_nseconds], hash[:mtime],
-        hash[:mtime_nseconds], hash[:acl], hash[:extended]
+    # Create a new Attributes instance with the given attributes. The
+    # following keys are supported:
+    #
+    # * :type:: the type of the item (integer, one of the T_ constants)
+    # * :size:: the size of the item (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)
+    # * :acl:: an array of ACL entries for the item
+    # * :extended:: a hash of name/value pairs identifying extended info
+    #
+    # All of them default to +nil+ if omitted, except for +type+, which defaults
+    # to T_REGULAR.
+    def initialize(attributes={})
+      super
+      attributes[:type] ||= T_REGULAR
     end
 
-    private_class_method :new
-
-    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
-
-    # Create a new Attributes instance with the given values.
-    def initialize( type=T_REGULAR, size=nil, owner=nil, group=nil,
-      permissions=nil, atime=nil, atime_nseconds=nil, ctime=nil,
-      ctime_nseconds=nil, mtime=nil, mtime_nseconds=nil, acl=nil,
-      extended=nil )
-    # begin
-      @type = type
-      @size = size
-      @owner = owner
-      @group = group
-      @permissions = permissions
-      @atime = atime
-      @atime_nseconds = atime_nseconds
-      @ctime = ctime
-      @ctime_nseconds = ctime_nseconds
-      @mtime = mtime
-      @mtime_nseconds = mtime_nseconds
-      @acl = acl
-      @extended = extended
-    end
+    private
 
-    # Convert this object to a string, suitable for inclusion in an SFTP
-    # packet (protocol version 4+).
-    def to_s
-      flags = 0
-
-      flags |= F_SIZE if @size
-      flags |= F_OWNERGROUP if @owner && @group
-      flags |= F_PERMISSIONS if @permissions
-      flags |= F_ACCESSTIME if @atime
-      flags |= F_CREATETIME if @ctime
-      flags |= F_MODIFYTIME if @mtime
-      if @atime_nseconds && @ctime_nseconds && @mtime_nseconds
-        flags |= F_SUBSECOND_TIMES
-      end
-      flags |= F_ACL if @acl
-      flags |= F_EXTENDED if @extended
-
-      buffer = buffers.writer
-      buffer.write_long flags
-      buffer.write_byte @type
-      buffer.write_int64 @size if @size
-      buffer.write_string @owner, @group if @owner && @group
-      buffer.write_long @permissions if @permissions
-
-      if @atime
-        buffer.write_int64 @atime
-        buffer.write_long @atime_nseconds if ( flags & F_SUBSECOND_TIMES != 0 )
-      end
-      if @ctime
-        buffer.write_int64 @ctime
-        buffer.write_long @ctime_nseconds if ( flags & F_SUBSECOND_TIMES != 0 )
-      end
-      if @mtime
-        buffer.write_int64 @mtime
-        buffer.write_long @mtime_nseconds if ( flags & F_SUBSECOND_TIMES != 0 )
+      # Perform protocol-version-specific preparations for serialization.
+      def prepare_serialization!
+        # force the group/owner to be translated from uid/gid, if those keys
+        # were given on instantiation
+        owner
+        group
       end
 
-      if @acl
-        acl_buf = buffers.writer
-        acl_buf.write_long @acl.length
-        @acl.each do |item|
+      # Performs protocol-version-specific encoding of the access control
+      # list, if one exists.
+      def encode_acl(buffer)
+        acl_buf = Net::SSH::Buffer.from(:long, acl.length)
+        acl.each do |item|
           acl_buf.write_long item.type, item.flag, item.mask
           acl_buf.write_string item.who
         end
-        buffer.write_string acl_buf.to_s
+        buffer.write_string(acl_buf.to_s)
       end
 
-      if @extended
-        buffer.write_long @extended.length
-        @extended.each { |k,v| buffer.write_string k, v }
-      end
-
-      buffer.to_s
-    end
-
   end
 
 end ; end ; end ; end