minitar 1.0.2 → 1.1.0

data/lib/minitar/pax_header.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+class Minitar
+  # Implements the PAX Extended Header as a Ruby class. The header consists of following
+  # format:
+  #
+  #    <decimal-length><space><ascii-keyword>=<value><newline>
+  #
+  # Where:
+  #
+  # - +decimal-length+ is the total number of bytes for the PaxHeader record using ASCII
+  #   decimal values; this includes the terminal newline (0x10).
+  # - +space+ is a single literal ASCII space (0x20).
+  # - +ascii-keyword+ is a PAX Extended Header keyword, which may be any ASCII character
+  #   except newline (0x10) or equal sign (0x3D).
+  # - +=+ is the literal ASCII equal sign (0x3D).
+  # - +value+ is any series of bytes except newline (0x10).
+  # - +newline+ is the literal ASCII newline (0x10).
+  #
+  # There are several keywords defined in the POSIX standard; some of them are supported
+  # in this class, but may not be supported by Minitar as a whole.
+  #
+  # Primary support for PAX extended headers is for extracting size information for large
+  # file support. Other features may be added in the future.
+  class PaxHeader
+    BLOCK_SIZE = 512
+
+    attr_reader :attributes
+
+    class << self
+      # Creates a new PaxHeader from a data stream and posix header. Reads the PAX content
+      # based on the size specified in the posix header.
+      def from_stream(stream, posix_header)
+        raise ArgumentError, "Header must be a PAX header" unless posix_header.pax_header?
+
+        pax_block = (posix_header.size / BLOCK_SIZE.to_f).ceil * BLOCK_SIZE
+        pax_content = stream.read(pax_block)
+
+        raise Minitar::InvalidTarStream if pax_content.nil? || pax_content.bytesize < posix_header.size
+
+        actual_content = pax_content[0, posix_header.size]
+
+        from_data(actual_content)
+      end
+
+      # Creates a new PaxHeader from PAX content data.
+      def from_data(content) = new(parse_content(content))
+
+      private
+
+      def parse_content(content)
+        attributes = {}
+        offset = 0
+
+        while offset < content.bytesize
+          space_pos = content.index(" ", offset)
+          break unless space_pos
+
+          length_str = content[offset, space_pos - offset]
+
+          unless length_str.match?(/\A\d+\z/)
+            raise ArgumentError, "Invalid length format in PAX header: '#{length_str}'"
+          end
+
+          length = length_str.to_i
+          if offset + length > content.bytesize
+            raise ArgumentError, "Length beyond PAX header: '#{content[offset..]}'"
+          end
+          record = content[offset, length]
+
+          keyword_value = record[(space_pos - offset + 1)..-2]
+          if keyword_value.include?("=")
+            keyword, value = keyword_value.split("=", 2)
+            attributes[keyword] = value
+          end
+
+          offset += length
+        end
+        attributes
+      end
+    end
+
+    # Creates a new PaxHeader from attributes hash.
+    def initialize(attributes = {})
+      @attributes = attributes.transform_keys(&:to_s)
+    end
+
+    # The size value from PAX attributes
+    def size = @attributes["size"]&.to_i
+
+    # The path value from PAX attributes
+    def path = @attributes["path"]
+
+    # The mtime value from PAX attributes
+    def mtime = @attributes["mtime"]&.to_f
+
+    # Returns a string representation of the PAX header content.
+    def to_s
+      @attributes.map do |keyword, value|
+        keyword_value = " #{keyword}=#{value}\n"
+        record = keyword_value
+        begin
+          length = record.bytesize
+          length_str = length.to_s
+          record = "#{length_str}#{keyword_value}"
+        end while record.size != length # standard:disable Lint/Loop
+        record
+      end.join
+    end
+  end
+end

data/lib/minitar/posix_header.rb

@@ -1,34 +1,34 @@
+# frozen_string_literal: true
+
 class Minitar
   # Implements the POSIX tar header as a Ruby class. The structure of
   # the POSIX tar header is:
   #
   #   struct tarfile_entry_posix
-  #   {                      //                               pack/unpack
-  #      char name[100];     // ASCII (+ Z unless filled)     a100/Z100
-  #      char mode[8];       // 0 padded, octal, null         a8  /A8
-  #      char uid[8];        // 0 padded, octal, null         a8  /A8
-  #      char gid[8];        // 0 padded, octal, null         a8  /A8
-  #      char size[12];      // 0 padded, octal, null         a12 /A12
-  #      char mtime[12];     // 0 padded, octal, null         a12 /A12
-  #      char checksum[8];   // 0 padded, octal, null, space  a8  /A8
-  #      char typeflag[1];   // see below                     a   /a
-  #      char linkname[100]; // ASCII + (Z unless filled)     a100/Z100
-  #      char magic[6];      // "ustar\0"                     a6  /A6
-  #      char version[2];    // "00"                          a2  /A2
-  #      char uname[32];     // ASCIIZ                        a32 /Z32
-  #      char gname[32];     // ASCIIZ                        a32 /Z32
-  #      char devmajor[8];   // 0 padded, octal, null         a8  /A8
-  #      char devminor[8];   // 0 padded, octal, null         a8  /A8
-  #      char prefix[155];   // ASCII (+ Z unless filled)     a155/Z155
+  #   {                      //                               pack   unpack
+  #      char name[100];     // ASCII (+ Z unless filled)     a100   Z100
+  #      char mode[8];       // 0 padded, octal, null         a8     A8
+  #      char uid[8];        // 0 padded, octal, null         a8     A8
+  #      char gid[8];        // 0 padded, octal, null         a8     A8
+  #      char size[12];      // 0 padded, octal, null         a12    A12
+  #      char mtime[12];     // 0 padded, octal, null         a12    A12
+  #      char checksum[8];   // 0 padded, octal, null, space  a8     A8
+  #      char typeflag[1];   // see below                     a      a
+  #      char linkname[100]; // ASCII + (Z unless filled)     a100   Z100
+  #      char magic[6];      // "ustar\0"                     a6     A6
+  #      char version[2];    // "00"                          a2     A2
+  #      char uname[32];     // ASCIIZ                        a32    Z32
+  #      char gname[32];     // ASCIIZ                        a32    Z32
+  #      char devmajor[8];   // 0 padded, octal, null         a8     A8
+  #      char devminor[8];   // 0 padded, octal, null         a8     A8
+  #      char prefix[155];   // ASCII (+ Z unless filled)     a155   Z155
   #   };
   #
-  # The #typeflag is one of several known values.
-  #
-  # POSIX indicates that "A POSIX-compliant implementation must treat any
-  # unrecognized typeflag value as a regular file."
+  # The #typeflag is one of several known values. POSIX indicates that "A POSIX-compliant
+  # implementation must treat any unrecognized typeflag value as a regular file."
   class PosixHeader
     BLOCK_SIZE = 512
-    MAGIC_BYTES = "ustar".freeze
+    MAGIC_BYTES = "ustar"
 
     GNU_EXT_LONG_LINK = "././@LongLink"
 
@@ -36,38 +36,33 @@ class Minitar
     REQUIRED_FIELDS = [:name, :size, :prefix, :mode].freeze
     # Fields that may be set in a POSIX tar(1) header.
     OPTIONAL_FIELDS = [
-      :uid, :gid, :mtime, :checksum, :typeflag, :linkname, :magic, :version,
-      :uname, :gname, :devmajor, :devminor
+      :uid, :gid, :mtime, :checksum, :typeflag, :linkname, :magic, :version, :uname,
+      :gname, :devmajor, :devminor
     ].freeze
 
     # All fields available in a POSIX tar(1) header.
     FIELDS = (REQUIRED_FIELDS + OPTIONAL_FIELDS).freeze
 
     FIELDS.each do |f|
-      attr_reader f.to_sym unless f.to_sym == :name
+      attr_reader f.to_sym
+    end
+
+    ##
+    def name=(value)
+      valid_name!(value)
+      @name = value
     end
 
-    # The name of the file. By default, limited to 100 bytes. Required. May be
-    # longer (up to BLOCK_SIZE bytes) if using the GNU long name tar extension.
-    attr_accessor :name
+    attr_writer :size
 
     # The pack format passed to Array#pack for encoding a header.
-    HEADER_PACK_FORMAT = "a100a8a8a8a12a12a7aaa100a6a2a32a32a8a8a155".freeze
+    HEADER_PACK_FORMAT = "a100a8a8a8a12a12a7aaa100a6a2a32a32a8a8a155"
     # The unpack format passed to String#unpack for decoding a header.
-    HEADER_UNPACK_FORMAT = "Z100A8A8A8A12A12A8aZ100A6A2Z32Z32A8A8Z155".freeze
+    HEADER_UNPACK_FORMAT = "Z100A8A8A8a12A12A8aZ100A6A2Z32Z32A8A8Z155"
 
     class << self
       # Creates a new PosixHeader from a data stream.
-      def from_stream(stream)
-        from_data(stream.read(BLOCK_SIZE))
-      end
-
-      # Creates a new PosixHeader from a data stream. Deprecated; use
-      # PosixHeader.from_stream instead.
-      def new_from_stream(stream)
-        warn "#{__method__} has been deprecated; use from_stream instead."
-        from_stream(stream)
-      end
+      def from_stream(stream) = from_data(stream.read(BLOCK_SIZE))
 
       # Creates a new PosixHeader from a BLOCK_SIZE-byte data buffer.
       def from_data(data)
@@ -76,7 +71,7 @@ class Minitar
         mode = fields.shift.oct
         uid = fields.shift.oct
         gid = fields.shift.oct
-        size = strict_oct(fields.shift)
+        size = parse_numeric_field(fields.shift)
         mtime = fields.shift.oct
         checksum = fields.shift.oct
         typeflag = fields.shift
@@ -114,14 +109,30 @@ class Minitar
 
       private
 
-      def strict_oct(string)
-        return string.oct if /\A[0-7 ]*\z/.match?(string)
-        raise ArgumentError, "#{string.inspect} is not a valid octal string"
+      def parse_numeric_field(string)
+        return string.oct if /\A[0-7 \0]*\z/.match?(string) # \0 appears as a padding
+        return parse_base256(string) if string.bytes.first == 0x80 || string.bytes.first == 0xff
+        raise ArgumentError, "#{string.inspect} is not a valid numeric field"
+      end
+
+      def parse_base256(string)
+        # https://www.gnu.org/software/tar/manual/html_node/Extensions.html
+        bytes = string.bytes
+        case bytes.first
+        when 0x80 # Positive number: *non-leading* bytes, number in big-endian order
+          bytes[1..].inject(0) { |r, byte| (r << 8) | byte }
+        when 0xff # Negative number: *all* bytes, two's complement in big-endian order
+          result = bytes.inject(0) { |r, byte| (r << 8) | byte }
+          bit_length = bytes.size * 8
+          result - (1 << bit_length)
+        else
+          raise ArgumentError, "Invalid binary field format"
+        end
       end
     end
 
-    # Creates a new PosixHeader. A PosixHeader cannot be created unless
-    # +name+, +size+, +prefix+, and +mode+ are provided.
+    # Creates a new PosixHeader. A PosixHeader cannot be created unless +name+, +size+,
+    # +prefix+, and +mode+ are provided.
     def initialize(v)
       REQUIRED_FIELDS.each do |f|
         raise ArgumentError, "Field #{f} is required." unless v.key?(f)
@@ -138,22 +149,35 @@ class Minitar
       end
 
       @empty = v[:empty]
+
+      valid_name!(v[:name]) unless v[:empty]
     end
 
     # Indicates if the header was an empty header.
-    def empty?
-      @empty
-    end
+    def empty? = @empty
 
     # Indicates if the header has a valid magic value.
-    def valid?
-      empty? || @magic == MAGIC_BYTES
-    end
+    def valid? = empty? || @magic == MAGIC_BYTES
 
     # Returns +true+ if the header is a long name special header which indicates
     # that the next block of data is the filename.
-    def long_name?
-      typeflag == "L" && name == GNU_EXT_LONG_LINK
+    def long_name? = typeflag == "L" && name == GNU_EXT_LONG_LINK
+
+    # Returns +true+ if the header is a PAX extended header which contains
+    # metadata for the next file entry.
+    def pax_header? = typeflag == "x"
+
+    # Sets the +name+ to the +value+ provided and clears +prefix+.
+    #
+    # Used by Minitar::Reader#each_entry to set the long name when processing GNU long
+    # filename extensions.
+    #
+    # The +value+ must be the complete name, including leading directory components.
+    def long_name=(value)
+      valid_name!(value)
+
+      @prefix = ""
+      @name = value
     end
 
     # A string representation of the header.
@@ -163,6 +187,8 @@ class Minitar
     end
     alias_method :to_str, :to_s
 
+    # TODO: In Minitar 2, PosixHeader#to_str will be removed.
+
     # Update the checksum field.
     def update_checksum
       hh = header(" " * 8)
@@ -171,6 +197,11 @@ class Minitar
 
     private
 
+    def valid_name!(value)
+      return if value.is_a?(String) && !value.empty?
+      raise ArgumentError, "Field name must be a non-empty string"
+    end
+
     def oct(num, len)
       if num.nil?
         "\0" * (len + 1)
@@ -180,7 +211,7 @@ class Minitar
     end
 
     def calculate_checksum(hdr)
-      hdr.unpack("C*").inject { |a, e| a + e }
+      hdr.unpack("C*").inject(:+)
     end
 
     def header(chksum)
@@ -192,7 +223,14 @@ class Minitar
     end
 
     ##
-    # :attr_reader: size
+    # :attr_accessor: name
+    # The name of the file. Required.
+    #
+    # By default, limited to 100 bytes, but may be up to BLOCK_SIZE bytes if using the
+    # GNU long name tar extension.
+
+    ##
+    # :attr_accessor: size
     # The size of the file. Required.
 
     ##
@@ -243,10 +281,11 @@ class Minitar
     # +5+::  Directory.
     # +6+::  FIFO node.
     # +7+::  Reserved.
+    # +L+::  GNU extension for long filenames when #name is <tt>././@LongLink</tt>.
 
     ##
     # :attr_reader: linkname
-    # The name of the link stored. Not currently used.
+    # The target of the symbolic link.
 
     ##
     # :attr_reader: magic

data/lib/minitar/reader.rb

@@ -1,28 +1,22 @@
+# frozen_string_literal: true
+
 class Minitar
-  # The class that reads a tar format archive from a data stream. The data
-  # stream may be sequential or random access, but certain features only work
-  # with random access data streams.
+  # The class that reads a tar format archive from a data stream. The data stream may be
+  # sequential or random access, but certain features only work with random access data
+  # streams.
   class Reader
     include Enumerable
 
-    # This marks the EntryStream closed for reading without closing the
-    # actual data stream.
+    # This marks the EntryStream closed for reading without closing the actual data
+    # stream.
     module InvalidEntryStream
-      def read(*)
-        raise ClosedStream
-      end
+      def read(*) = raise ClosedStream # :nodoc:
 
-      def getc
-        raise ClosedStream
-      end
+      def getc = raise ClosedStream # :nodoc:
 
-      def rewind
-        raise ClosedStream
-      end
+      def rewind = raise ClosedStream # :nodoc:
 
-      def closed?
-        true
-      end
+      def closed? = true # :nodoc:
     end
 
     # EntryStreams are pseudo-streams on top of the main data stream.
@@ -58,8 +52,8 @@ class Minitar
           end
       end
 
-      # Reads +len+ bytes (or all remaining data) from the entry. Returns
-      # +nil+ if there is no more data to read.
+      # Reads +len+ bytes (or all remaining data) from the entry. Returns +nil+ if there
+      # is no more data to read.
       def read(len = nil)
         return nil if @read >= @size
         len ||= @size - @read
@@ -69,8 +63,7 @@ class Minitar
         ret
       end
 
-      # Reads one byte from the entry. Returns +nil+ if there is no more data
-      # to read.
+      # Reads one byte from the entry. Returns +nil+ if there is no more data to read.
       def getc
         return nil if @read >= @size
         ret = @io.getc
@@ -84,10 +77,9 @@ class Minitar
         when "5"
           true
         when "0", "\0"
-          # If the name ends with a slash, treat it as a directory.
-          # This is what other major tar implementations do for
-          # interoperability and compatibility with older tar variants
-          # and some new ones.
+          # If the name ends with a slash, treat it as a directory. This is what other
+          # major tar implementations do for interoperability and compatibility with older
+          # tar variants and some new ones.
           @name.end_with?("/")
         else
           false
@@ -101,16 +93,13 @@ class Minitar
       end
       alias_method :file, :file?
 
-      # Returns +true+ if the current read pointer is at the end of the
-      # EntryStream data.
-      def eof?
-        @read >= @size
-      end
+      # Returns +true+ if the current read pointer is at the end of the EntryStream data.
+      def eof? = @read >= @size
 
       # Returns the current read pointer in the EntryStream.
-      def pos
-        @read
-      end
+      def pos = @read
+
+      alias_method :bytes_read, :pos
 
       # Sets the current read pointer to the beginning of the EntryStream.
       def rewind
@@ -121,10 +110,6 @@ class Minitar
         @read = 0
       end
 
-      def bytes_read
-        @read
-      end
-
       # Returns the full and proper name of the entry.
       def full_name
         if @prefix != ""
@@ -135,14 +120,10 @@ class Minitar
       end
 
       # Returns false if the entry stream is valid.
-      def closed?
-        false
-      end
+      def closed? = false
 
       # Closes the entry.
-      def close
-        invalidate
-      end
+      def close = invalidate
 
       private
 
@@ -151,17 +132,16 @@ class Minitar
       end
     end
 
-    # With no associated block, +Reader::open+ is a synonym for
-    # +Reader::new+. If the optional code block is given, it will be passed
-    # the new _writer_ as an argument and the Reader object will
-    # automatically be closed when the block terminates. In this instance,
-    # +Reader::open+ returns the value of the block.
+    # With no associated block, +Reader::open+ is a synonym for +Reader::new+. If the
+    # optional code block is given, it will be passed the new _writer_ as an argument and
+    # the Reader object will automatically be closed when the block terminates. In this
+    # instance, +Reader::open+ returns the value of the block.
     def self.open(io)
       reader = new(io)
       return reader unless block_given?
 
-      # This exception context must remain, otherwise the stream closes on open
-      # even if a block is not given.
+      # This exception context must remain, otherwise the stream closes on open even if
+      # a block is not given.
       begin
         yield reader
       ensure
@@ -169,8 +149,7 @@ class Minitar
       end
     end
 
-    # Iterates over each entry in the provided input. This wraps the common
-    # pattern of:
+    # Iterates over each entry in the provided input. This wraps the common pattern of:
     #
     #     Minitar::Input.open(io) do |i|
     #       inp.each do |entry|
@@ -178,10 +157,9 @@ class Minitar
     #       end
     #     end
     #
-    # If a block is not provided, an enumerator will be created with the same
-    # behaviour.
+    # If a block is not provided, an enumerator will be created with the same behaviour.
     #
-    # call-seq:
+    # :call-seq:
     #    Minitar::Reader.each_entry(io) -> enumerator
     #    Minitar::Reader.each_entry(io) { |entry| block } -> obj
     def self.each_entry(io)
@@ -204,19 +182,15 @@ class Minitar
       end
     end
 
-    # Resets the read pointer to the beginning of data stream. Do not call
-    # this during a #each or #each_entry iteration. This only works with
-    # random access data streams that respond to #rewind and #pos.
+    # Resets the read pointer to the beginning of data stream. Do not call this during
+    # a #each or #each_entry iteration. This only works with random access data streams
+    # that respond to #rewind and #pos.
     def rewind
       if @init_pos.zero?
-        unless Minitar.seekable?(@io, :rewind)
-          raise Minitar::NonSeekableStream
-        end
+        raise Minitar::NonSeekableStream unless Minitar.seekable?(@io, :rewind)
         @io.rewind
       else
-        unless Minitar.seekable?(@io, :pos=)
-          raise Minitar::NonSeekableStream
-        end
+        raise Minitar::NonSeekableStream unless Minitar.seekable?(@io, :pos=)
         @io.pos = @init_pos
       end
     end
@@ -237,11 +211,18 @@ class Minitar
         if header.long_name?
           name_block = (header.size / 512.0).ceil * 512
 
-          name = @io.read(name_block).rstrip
+          long_name = @io.read(name_block).rstrip
           header = PosixHeader.from_stream(@io)
 
           return if header.empty?
-          header.name = name
+          header.long_name = long_name
+        elsif header.pax_header?
+          pax_header = PaxHeader.from_stream(@io, header)
+
+          header = PosixHeader.from_stream(@io)
+          return if header.empty?
+
+          header.size = pax_header.size if pax_header.size
         end
 
         entry = EntryStream.new(header, @io)
@@ -253,7 +234,7 @@ class Minitar
 
         if Minitar.seekable?(@io, :seek)
           # avoid reading...
-          @io.seek(size - entry.bytes_read, IO::SEEK_CUR)
+          try_seek(size - entry.bytes_read)
         else
           pending = size - entry.bytes_read
           while pending > 0
@@ -271,11 +252,25 @@ class Minitar
     alias_method :each, :each_entry
 
     # Returns false if the reader is open (it never closes).
-    def closed?
-      false
-    end
+    def closed? = false
 
     def close
     end
+
+    private
+
+    def try_seek(bytes)
+      @io.seek(bytes, IO::SEEK_CUR)
+    rescue RangeError
+      # This happens when skipping the large entry and the skipping entry size exceeds
+      # maximum allowed size (varies by platform and underlying IO object).
+      max = RbConfig::LIMITS.fetch("INT_MAX", 2147483647)
+      skipped = 0
+      while skipped < bytes
+        to_skip = [bytes - skipped, max].min
+        @io.seek(to_skip, IO::SEEK_CUR)
+        skipped += to_skip
+      end
+    end
   end
 end

data/lib/minitar/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Minitar
+  VERSION = "1.1.0"
+end