hrr_rb_sftp 0.1.0 → 0.2.0

data/lib/hrr_rb_sftp/protocol/common/data_types/string.rb

@@ -0,0 +1,42 @@
+module HrrRbSftp
+  class Protocol
+    module Common
+      module DataTypes
+
+        #
+        # This module provides methods to convert ::String value and binary string with its length each other.
+        #
+        module String
+
+          #
+          # Convert ::String value into binary string with its length.
+          #
+          # @param arg [::String] ::String value to be converted.
+          # @raise [::ArgumentError] When arg is not ::String value or length of arg is longer than 0xffff_ffff.
+          # @return [::String] Converted binary string with its length.
+          #
+          def self.encode arg
+            unless arg.kind_of? ::String
+              raise ArgumentError, "must be a kind of String, but got #{arg.inspect}"
+            end
+            if arg.bytesize > 0xffff_ffff
+              raise ArgumentError, "must be shorter than or equal to #{0xffff_ffff}, but got length #{arg.bytesize}"
+            end
+            [arg.bytesize, arg].pack("Na*")
+          end
+
+          #
+          # Convert binary string with its length into ::String value.
+          #
+          # @param io [::IO] ::IO instance that has buffer to be read.
+          # @return [::String] Converted UTF-8 ::String value.
+          #
+          def self.decode io
+            length = io.read(4).unpack("N")[0]
+            io.read(length).unpack("a*")[0].force_encoding(Encoding::UTF_8)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hrr_rb_sftp/protocol/common/data_types/uint32.rb

@@ -0,0 +1,40 @@
+module HrrRbSftp
+  class Protocol
+    module Common
+      module DataTypes
+
+        #
+        # This module provides methods to convert ::Integer value and 32-bit unsigned binary string each other.
+        #
+        module Uint32
+
+          #
+          # Convert ::Integer value into 32-bit unsigned binary string.
+          #
+          # @param arg [::Integer] ::Integer value to be converted.
+          # @raise [::ArgumentError] When arg is not between 0x0000_0000 and 0xffff_ffff.
+          # @return [::String] Converted 32-bit unsigned binary string.
+          #
+          def self.encode arg
+            case arg
+            when 0x0000_0000..0xffff_ffff
+              [arg].pack("N")
+            else
+              raise ArgumentError, "must be in #{0x0000_0000}..#{0xffff_ffff}, but got #{arg.inspect}"
+            end
+          end
+
+          #
+          # Convert 32-bit unsigned binary into ::Integer value.
+          #
+          # @param io [::IO] ::IO instance that has buffer to be read.
+          # @return [::Integer] Converted ::Integer value.
+          #
+          def self.decode io
+            io.read(4).unpack("N")[0]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hrr_rb_sftp/protocol/common/data_types/uint64.rb

@@ -0,0 +1,40 @@
+module HrrRbSftp
+  class Protocol
+    module Common
+      module DataTypes
+
+        #
+        # This module provides methods to convert ::Integer value and 64-bit unsigned binary string each other.
+        #
+        module Uint64
+
+          #
+          # Convert ::Integer value into 64-bit unsigned binary string.
+          #
+          # @param arg [::Integer] ::Integer value to be converted.
+          # @raise [::ArgumentError] When arg is not between 0x0000_0000_0000_0000 and 0xffff_ffff_ffff_ffff.
+          # @return [::String] Converted 64-bit unsigned binary string.
+          #
+          def self.encode arg
+            case arg
+            when 0x0000_0000_0000_0000..0xffff_ffff_ffff_ffff
+              [arg >> 32].pack("N") + [arg & 0x0000_0000_ffff_ffff].pack("N")
+            else
+              raise ArgumentError, "must be in #{0x0000_0000_0000_0000}..#{0xffff_ffff_ffff_ffff}, but got #{arg.inspect}"
+            end
+          end
+
+          #
+          # Convert 64-bit unsigned binary into ::Integer value.
+          #
+          # @param io [::IO] ::IO instance that has buffer to be read.
+          # @return [::Integer] Converted ::Integer value.
+          #
+          def self.decode io
+            (io.read(4).unpack("N")[0] << 32) + (io.read(4).unpack("N")[0])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hrr_rb_sftp/protocol/common/packets.rb

@@ -0,0 +1,16 @@
+module HrrRbSftp
+  class Protocol
+    module Common
+
+      #
+      # This module implements SFTP protocol version independent packet types, formats, and responders.
+      #
+      module Packets
+      end
+    end
+  end
+end
+
+require "hrr_rb_sftp/protocol/common/packets/packet"
+require "hrr_rb_sftp/protocol/common/packets/001_ssh_fxp_init"
+require "hrr_rb_sftp/protocol/common/packets/002_ssh_fxp_version"

data/lib/hrr_rb_sftp/protocol/common/packets/001_ssh_fxp_init.rb

@@ -0,0 +1,27 @@
+module HrrRbSftp
+  class Protocol
+    module Common
+      module Packets
+
+        #
+        # This class implements SFTP protocol version independent SSH_FXP_INIT packet type, format, and responder.
+        #
+        class SSH_FXP_INIT < Packet
+
+          #
+          # Represents SSH_FXP_INIT packet type.
+          #
+          TYPE = 1
+
+          #
+          # Represents SSH_FXP_INIT packet format.
+          #
+          FORMAT = [
+            [DataTypes::Byte,   :"type"   ],
+            [DataTypes::Uint32, :"version"],
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/hrr_rb_sftp/protocol/common/packets/002_ssh_fxp_version.rb

@@ -0,0 +1,28 @@
+module HrrRbSftp
+  class Protocol
+    module Common
+      module Packets
+
+        #
+        # This class implements SFTP protocol version independent SSH_FXP_VERSION packet type, format, and responder.
+        #
+        class SSH_FXP_VERSION < Packet
+
+          #
+          # Represents SSH_FXP_VERSION packet type.
+          #
+          TYPE = 2
+
+          #
+          # Represents SSH_FXP_VERSION packet format.
+          #
+          FORMAT = [
+            [DataTypes::Byte,           :"type"      ],
+            [DataTypes::Uint32,         :"version"   ],
+            [DataTypes::ExtensionPairs, :"extensions"],
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/hrr_rb_sftp/protocol/common/packets/packet.rb

@@ -0,0 +1,96 @@
+module HrrRbSftp
+  class Protocol
+    module Common
+      module Packets
+
+        #
+        # This class implements base packet operations and is to be inherited by each packet class.
+        #
+        class Packet
+          include Loggable
+
+          #
+          # Returns a new instance of a class that includes this module.
+          #
+          # @param logger [Logger] Logger.
+          #
+          def initialize logger: nil
+            self.logger = logger
+          end
+
+          #
+          # Encodes packet represented in Hash into payload represented in binary string.
+          #
+          # @param packet [Hash{Symbol=>Object}] Packets represented in Hash that key and value are field name and field value.
+          # @return [String] Encoded payload converted from packet.
+          #
+          def encode packet
+            log_debug { 'encoding packet: ' + packet.inspect }
+            format = common_format + conditional_format(packet)
+            format.map{ |data_type, field_name|
+              begin
+                field_value = packet[field_name]
+                data_type.encode field_value
+              rescue => e
+                log_debug { "'field_name', 'field_value': #{field_name.inspect}, #{field_value.inspect}" }
+                raise e
+              end
+            }.join
+          end
+
+          #
+          # Decodes payload represented in binary string into packet represented in Hash.
+          #
+          # @param payload [String] Payload of binary string.
+          # @param complementary_packet [Hash{Symbol=>Object}] Implied fields that activate conditional format. Now this is used for debug purpose.
+          # @return [String] Decoded packet represented in Hash that key and value are field name and field value.
+          #
+            def decode payload, complementary_packet={}
+            payload_io = StringIO.new payload
+            format = common_format
+            decoded_packet = decode_recursively(payload_io).inject(Hash.new){ |h, (k, v)| h.update({k => v}) }
+            if complementary_packet.any?
+              decoded_packet.merge! decode_recursively(payload_io, complementary_packet.to_a).inject(Hash.new){ |h, (k, v)| h.update({k => v}) }
+            end
+            log_debug { 'decoded packet: ' + decoded_packet.inspect }
+            decoded_packet
+          end
+
+          private
+
+          def common_format
+            self.class::FORMAT
+          end
+
+          def conditional_format packet
+            return [] unless self.class.const_defined? :CONDITIONAL_FORMAT
+            packet.inject([]){ |a, (field_name, field_value)|
+              a + ((self.class::CONDITIONAL_FORMAT[field_name] || {})[field_value] || [])
+            }
+          end
+
+          def decode_recursively payload_io, packet=nil
+            if packet.class == Array and packet.size == 0
+              []
+            else
+              format = case packet
+                       when nil
+                         common_format
+                       when Array
+                         conditional_format(packet)
+                       end
+              decoded_packet = format.map{ |data_type, field_name|
+                begin
+                  [field_name, data_type.decode(payload_io)]
+                rescue => e
+                  raise RuntimeError, "Failed decoding #{field_name.inspect} (#{e.message})"
+                end
+              }
+              decoded_packet + decode_recursively(payload_io, decoded_packet)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hrr_rb_sftp/protocol/version1.rb

@@ -1,10 +1,18 @@
 module HrrRbSftp
   class Protocol
-    class Version1
+
+    #
+    # This module implements SFTP protocol version 1 packet types, formats, and responders.
+    #
+    module Version1
+
+      #
+      # Represents SFTP protocol version 1.
+      #
       PROTOCOL_VERSION = 1
     end
   end
 end
 
-require "hrr_rb_sftp/protocol/version1/data_type"
-require "hrr_rb_sftp/protocol/version1/packet"
+require "hrr_rb_sftp/protocol/version1/data_types"
+require "hrr_rb_sftp/protocol/version1/packets"

data/lib/hrr_rb_sftp/protocol/version1/data_types.rb

@@ -0,0 +1,15 @@
+module HrrRbSftp
+  class Protocol
+    module Version1
+
+      #
+      # This module implements SFTP protocol version 1 data types to be used to encode or decode packet.
+      #
+      module DataTypes
+        include Common::DataTypes
+      end
+    end
+  end
+end
+
+require "hrr_rb_sftp/protocol/version1/data_types/attrs"

data/lib/hrr_rb_sftp/protocol/version1/data_types/attrs.rb

@@ -0,0 +1,91 @@
+module HrrRbSftp
+  class Protocol
+    module Version1
+      module DataTypes
+
+        #
+        # This module provides methods to convert file attributes represented in ::Hash and binary string each other.
+        #
+        class Attrs
+
+          #
+          # Represents SSH_FILEXFER_ATTR_SIZE.
+          #
+          SSH_FILEXFER_ATTR_SIZE        = 0x00000001
+
+          #
+          # Represents SSH_FILEXFER_ATTR_UIDGID.
+          #
+          SSH_FILEXFER_ATTR_UIDGID      = 0x00000002
+
+          #
+          # Represents SSH_FILEXFER_ATTR_PERMISSIONS.
+          #
+          SSH_FILEXFER_ATTR_PERMISSIONS = 0x00000004
+
+          #
+          # Represents SSH_FILEXFER_ATTR_ACMODTIME.
+          #
+          SSH_FILEXFER_ATTR_ACMODTIME   = 0x00000008
+
+          #
+          # Represents SSH_FILEXFER_ATTR_EXTENDED.
+          #
+          SSH_FILEXFER_ATTR_EXTENDED    = 0x80000000
+
+          #
+          # Converts file attributes represented in ::Hash into binary string.
+          #
+          # @param arg [::Hash{::Symbol=>::Object}] File attributes represented in ::Hash to be converted.
+          # @raise [::ArgumentError] When arg is not ::Hash value.
+          # @return [::String] Converted binary string.
+          #
+          def self.encode arg
+            unless arg.kind_of? ::Hash
+              raise ArgumentError, "must be a kind of Hash, but got #{arg.inspect}"
+            end
+
+            flags = 0
+            flags |= SSH_FILEXFER_ATTR_SIZE        if arg.has_key?(:"size")
+            flags |= SSH_FILEXFER_ATTR_UIDGID      if arg.has_key?(:"uid") && arg.has_key?(:"gid")
+            flags |= SSH_FILEXFER_ATTR_PERMISSIONS if arg.has_key?(:"permissions")
+            flags |= SSH_FILEXFER_ATTR_ACMODTIME   if arg.has_key?(:"atime") && arg.has_key?(:"mtime")
+            flags |= SSH_FILEXFER_ATTR_EXTENDED    if arg.has_key?(:"extensions")
+
+            payload  = DataTypes::Uint32.encode flags
+            payload += DataTypes::Uint64.encode arg[:"size"]               unless (flags & SSH_FILEXFER_ATTR_SIZE).zero?
+            payload += DataTypes::Uint32.encode arg[:"uid"]                unless (flags & SSH_FILEXFER_ATTR_UIDGID).zero?
+            payload += DataTypes::Uint32.encode arg[:"gid"]                unless (flags & SSH_FILEXFER_ATTR_UIDGID).zero?
+            payload += DataTypes::Uint32.encode arg[:"permissions"]        unless (flags & SSH_FILEXFER_ATTR_PERMISSIONS).zero?
+            payload += DataTypes::Uint32.encode arg[:"atime"]              unless (flags & SSH_FILEXFER_ATTR_ACMODTIME).zero?
+            payload += DataTypes::Uint32.encode arg[:"mtime"]              unless (flags & SSH_FILEXFER_ATTR_ACMODTIME).zero?
+            payload += DataTypes::Uint32.encode arg[:"extensions"].size    unless (flags & SSH_FILEXFER_ATTR_EXTENDED).zero?
+            payload += DataTypes::ExtensionPairs.encode arg[:"extensions"] unless (flags & SSH_FILEXFER_ATTR_EXTENDED).zero?
+            payload
+          end
+
+          #
+          # Converts binary string into file attributes represented in ::Hash.
+          #
+          # @param io [::IO] ::IO instance that has buffer to be read.
+          # @return [::Hash{::Symbol=>::Object}] Converted file attributes represented in ::Hash.
+          #
+          def self.decode io
+            attrs = Hash.new
+            flags                 = DataTypes::Uint32.decode(io)
+            attrs[:"size"]        = DataTypes::Uint64.decode(io)                                   unless (flags & SSH_FILEXFER_ATTR_SIZE).zero?
+            attrs[:"uid"]         = DataTypes::Uint32.decode(io)                                   unless (flags & SSH_FILEXFER_ATTR_UIDGID).zero?
+            attrs[:"gid"]         = DataTypes::Uint32.decode(io)                                   unless (flags & SSH_FILEXFER_ATTR_UIDGID).zero?
+            attrs[:"permissions"] = DataTypes::Uint32.decode(io)                                   unless (flags & SSH_FILEXFER_ATTR_PERMISSIONS).zero?
+            attrs[:"atime"]       = DataTypes::Uint32.decode(io)                                   unless (flags & SSH_FILEXFER_ATTR_ACMODTIME).zero?
+            attrs[:"mtime"]       = DataTypes::Uint32.decode(io)                                   unless (flags & SSH_FILEXFER_ATTR_ACMODTIME).zero?
+            extended_count        = DataTypes::Uint32.decode(io)                                   unless (flags & SSH_FILEXFER_ATTR_EXTENDED).zero?
+            attrs[:"extensions"]  = Array.new(extended_count){DataTypes::ExtensionPair.decode(io)} unless (flags & SSH_FILEXFER_ATTR_EXTENDED).zero?
+            attrs
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/hrr_rb_sftp/protocol/version1/packets.rb

@@ -0,0 +1,72 @@
+module HrrRbSftp
+  class Protocol
+    module Version1
+
+      #
+      # This class implements SFTP protocol version 1 packet types, formats, and responders.
+      #
+      class Packets
+        include Loggable
+
+        #
+        # @param context [Hash] Contextual variables.
+        #   - :version (Integer) - Negotiated protocol version.
+        #   - :handles (Hash\\{String=>File, Dir\}) - Opened handles.
+        # @param logger [Logger] Logger.
+        #
+        def initialize context, logger: nil
+          self.logger = logger
+
+          @packets = packet_classes.map{|c| {c::TYPE => c.new(context, logger: logger)}}.inject({}, :merge)
+        end
+
+        #
+        # Responds to a request.
+        #
+        # @param request_payload [String] Request payload.
+        # @return [String] Response payload that is encoded packet generated by each SFTP protocol version and each request responder.
+        # @raise [RuntimeError] When the SFTP protocol version does not support or the library does not implement the request type.
+        #
+        def respond_to request_payload
+          request_type = request_payload[0].unpack("C")[0]
+          response_packet = if @packets.has_key?(request_type)
+                              request_packet = @packets[request_type].decode request_payload
+                              @packets[request_type].respond_to request_packet
+                            else
+                              raise RuntimeError, "Unsupported type: #{request_type}"
+                            end
+          response_type = response_packet[:"type"]
+          @packets[response_type].encode response_packet
+        end
+
+        private
+
+        def packet_classes
+          self.class.constants.select{|c| c.to_s.start_with?("SSH_FXP_")}.map{|c| self.class.const_get(c)}
+        end
+      end
+    end
+  end
+end
+
+require "hrr_rb_sftp/protocol/version1/packets/packet"
+require "hrr_rb_sftp/protocol/version1/packets/003_ssh_fxp_open"
+require "hrr_rb_sftp/protocol/version1/packets/004_ssh_fxp_close"
+require "hrr_rb_sftp/protocol/version1/packets/005_ssh_fxp_read"
+require "hrr_rb_sftp/protocol/version1/packets/006_ssh_fxp_write"
+require "hrr_rb_sftp/protocol/version1/packets/007_ssh_fxp_lstat"
+require "hrr_rb_sftp/protocol/version1/packets/008_ssh_fxp_fstat"
+require "hrr_rb_sftp/protocol/version1/packets/009_ssh_fxp_setstat"
+require "hrr_rb_sftp/protocol/version1/packets/010_ssh_fxp_fsetstat"
+require "hrr_rb_sftp/protocol/version1/packets/011_ssh_fxp_opendir"
+require "hrr_rb_sftp/protocol/version1/packets/012_ssh_fxp_readdir"
+require "hrr_rb_sftp/protocol/version1/packets/013_ssh_fxp_remove"
+require "hrr_rb_sftp/protocol/version1/packets/014_ssh_fxp_mkdir"
+require "hrr_rb_sftp/protocol/version1/packets/015_ssh_fxp_rmdir"
+require "hrr_rb_sftp/protocol/version1/packets/016_ssh_fxp_realpath"
+require "hrr_rb_sftp/protocol/version1/packets/017_ssh_fxp_stat"
+require "hrr_rb_sftp/protocol/version1/packets/101_ssh_fxp_status"
+require "hrr_rb_sftp/protocol/version1/packets/102_ssh_fxp_handle"
+require "hrr_rb_sftp/protocol/version1/packets/103_ssh_fxp_data"
+require "hrr_rb_sftp/protocol/version1/packets/104_ssh_fxp_name"
+require "hrr_rb_sftp/protocol/version1/packets/105_ssh_fxp_attrs"