Fix TarReader: implement full GNU sparse format 1.0 (PAX) reading with DataStream expansion

src/libraries/System.Formats.Tar/src/System.Formats.Tar.csproj

@@ -33,6 +33,7 @@
     <Compile Include="System\Formats\Tar\TarWriter.cs" />
     <Compile Include="System\Formats\Tar\SubReadStream.cs" />
     <Compile Include="System\Formats\Tar\SeekableSubReadStream.cs" />
+    <Compile Include="System\Formats\Tar\GnuSparseStream.cs" />
     <Compile Include="$(CommonPath)DisableRuntimeMarshalling.cs" Link="Common\DisableRuntimeMarshalling.cs" />
     <Compile Include="$(CommonPath)System\IO\Archiving.Utils.cs" Link="Common\System\IO\Archiving.Utils.cs" />
     <Compile Include="$(CommonPath)System\IO\PathInternal.cs" Link="Common\System\IO\PathInternal.cs" />

src/libraries/System.Formats.Tar/src/System/Formats/Tar/TarEntry.cs

@@ -113,7 +113,7 @@ public DateTimeOffset ModificationTime
         /// When the <see cref="EntryType"/> indicates an entry that can contain data, this property returns the length in bytes of such data.
         /// </summary>
         /// <remarks>The entry type that commonly contains data is <see cref="TarEntryType.RegularFile"/> (or <see cref="TarEntryType.V7RegularFile"/> in the <see cref="TarEntryFormat.V7"/> format). Other uncommon entry types that can also contain data are: <see cref="TarEntryType.ContiguousFile"/>, <see cref="TarEntryType.DirectoryList"/>, <see cref="TarEntryType.MultiVolume"/> and <see cref="TarEntryType.SparseFile"/>.</remarks>
-        public long Length => _header._dataStream != null ? _header._dataStream.Length : _header._size;
+        public long Length => _header._gnuSparseDataStream?.Length ?? (_header._dataStream is not null ? _header._dataStream.Length : _header._size);
 
         /// <summary>
         /// When the <see cref="EntryType"/> indicates a <see cref="TarEntryType.SymbolicLink"/> or a <see cref="TarEntryType.HardLink"/>, this property returns the link target path of such link.
@@ -252,7 +252,7 @@ public Task ExtractToFileAsync(string destinationFileName, bool overwrite, Cance
         /// <exception cref="IOException">An I/O problem occurred.</exception>
         public Stream? DataStream
         {
-            get => _header._dataStream;
+            get => (Stream?)_header._gnuSparseDataStream ?? _header._dataStream;
             set
             {
                 if (!IsDataStreamSetterSupported())
@@ -275,6 +275,8 @@ public Stream? DataStream
                     _readerOfOrigin = null;
                 }
 
+                _header._gnuSparseDataStream?.Dispose();
+                _header._gnuSparseDataStream = null;
                 _header._dataStream?.Dispose();
 
                 _header._dataStream = value;

src/libraries/System.Formats.Tar/src/System/Formats/Tar/TarHeader.Read.cs

@@ -144,6 +144,32 @@ internal void ReplaceNormalAttributesWithExtended(Dictionary<string, string>? di
                 _size = size;
             }
 
+            // GNU sparse format 1.0 (encoded via PAX) uses RegularFile type flag ('0') and stores sparse metadata in
+            // PAX extended attributes. Process all GNU sparse 1.0 attributes together in this block.
+            if (_typeFlag is TarEntryType.RegularFile or TarEntryType.V7RegularFile)
+            {
+                // 'GNU.sparse.name' overrides the placeholder path (e.g. 'GNUSparseFile.0/...') in the header's 'path' field.
+                if (ExtendedAttributes.TryGetValue(PaxEaGnuSparseName, out string? gnuSparseName))
+                {
+                    _name = gnuSparseName;
+                }
+
+                // 'GNU.sparse.realsize' is the expanded (virtual) file size; stored separately from _size so that
+                // _size retains the archive data section length needed for correct stream positioning.
+                if (TarHelpers.TryGetStringAsBaseTenLong(ExtendedAttributes, PaxEaGnuSparseRealSize, out long gnuSparseRealSize))
+                {
+                    _gnuSparseRealSize = gnuSparseRealSize;
+                }
+
+                // 'GNU.sparse.major=1' and 'GNU.sparse.minor=0' identify format 1.0, where the data section begins
+                // with an embedded text-format sparse map followed by the packed non-zero data segments.
+                if (ExtendedAttributes.TryGetValue(PaxEaGnuSparseMajor, out string? gnuSparseMajor) && gnuSparseMajor == "1" &&
+                    ExtendedAttributes.TryGetValue(PaxEaGnuSparseMinor, out string? gnuSparseMinor) && gnuSparseMinor == "0")
+                {
+                    _isGnuSparse10 = true;
+                }
+            }
+
             // The 'uid' header field only fits 8 bytes, or the user could've stored an override in the extended attributes
             if (TarHelpers.TryGetStringAsBaseTenInteger(ExtendedAttributes, PaxEaUid, out int uid))
             {
@@ -220,6 +246,17 @@ internal void ProcessDataBlock(Stream archiveStream, bool copyData)
                 case TarEntryType.TapeVolume: // Might contain data
                 default: // Unrecognized entry types could potentially have a data section
                     _dataStream = GetDataStream(archiveStream, copyData);
+
+                    // GNU sparse format 1.0 PAX entries embed a sparse map at the start of the
+                    // data section. Create a GnuSparseStream wrapper that presents the expanded
+                    // virtual file content. The sparse map is parsed lazily on first Read, so
+                    // _dataStream remains unconsumed here — TarWriter can copy the raw condensed
+                    // data, and AdvanceDataStreamIfNeeded can advance past it normally.
+                    if (_isGnuSparse10 && _gnuSparseRealSize > 0 && _dataStream is not null)
+                    {
+                        _gnuSparseDataStream = new GnuSparseStream(_dataStream, _gnuSparseRealSize);
+                    }
+
                     if (_dataStream is SeekableSubReadStream)
                     {
                         TarHelpers.AdvanceStream(archiveStream, _size);
@@ -282,9 +319,15 @@ private async Task ProcessDataBlockAsync(Stream archiveStream, bool copyData, Ca
                 case TarEntryType.TapeVolume: // Might contain data
                 default: // Unrecognized entry types could potentially have a data section
                     _dataStream = await GetDataStreamAsync(archiveStream, copyData, _size, cancellationToken).ConfigureAwait(false);
+
+                    if (_isGnuSparse10 && _gnuSparseRealSize > 0 && _dataStream is not null)
+                    {
+                        _gnuSparseDataStream = new GnuSparseStream(_dataStream, _gnuSparseRealSize);
+                    }
+
                     if (_dataStream is SeekableSubReadStream)
                     {
-                        await TarHelpers.AdvanceStreamAsync(archiveStream, _size, cancellationToken).ConfigureAwait(false);
+                        TarHelpers.AdvanceStream(archiveStream, _size);
                     }
                     else if (_dataStream is SubReadStream)
                     {

src/libraries/System.Formats.Tar/src/System/Formats/Tar/TarHeader.cs

@@ -39,6 +39,12 @@ internal sealed partial class TarHeader
         private const string PaxEaDevMajor = "devmajor";
         private const string PaxEaDevMinor = "devminor";
 
+        // Names of GNU sparse extended attributes (used with GNU sparse format 1.0 encoded via PAX)
+        private const string PaxEaGnuSparseName = "GNU.sparse.name";
+        private const string PaxEaGnuSparseRealSize = "GNU.sparse.realsize";
+        private const string PaxEaGnuSparseMajor = "GNU.sparse.major";
+        private const string PaxEaGnuSparseMinor = "GNU.sparse.minor";
+
         internal Stream? _dataStream;
         internal long _dataOffset;
 
@@ -77,6 +83,21 @@ internal sealed partial class TarHeader
         private Dictionary<string, string>? _ea;
         internal Dictionary<string, string> ExtendedAttributes => _ea ??= new Dictionary<string, string>();
 
+        // When a GNU sparse 1.0 PAX entry is read, the real (expanded) file size is stored here.
+        // This is separate from _size which holds the archive data size and is used for data stream reading.
+        internal long _gnuSparseRealSize;
+
+        // Set to true when GNU.sparse.major=1 is present in the PAX extended attributes,
+        // indicating this is a GNU sparse format 1.0 entry whose data section contains an
+        // embedded sparse map followed by the packed data segments.
+        internal bool _isGnuSparse10;
+
+        // When _isGnuSparse10 is true, this wraps _dataStream and presents the expanded virtual
+        // file content. _dataStream remains the raw (condensed) stream so that TarWriter can
+        // round-trip the original sparse data and AdvanceDataStreamIfNeeded works without
+        // special-casing.
+        internal GnuSparseStream? _gnuSparseDataStream;
+
         // GNU attributes
 
         internal DateTimeOffset _aTime;
@@ -106,6 +127,9 @@ internal TarHeader(TarEntryFormat format, TarEntryType typeFlag, TarHeader other
             _checksum = other._checksum;
             _linkName = other._linkName;
             _dataStream = other._dataStream;
+            _gnuSparseRealSize = other._gnuSparseRealSize;
+            _isGnuSparse10 = other._isGnuSparse10;
+            _gnuSparseDataStream = other._gnuSparseDataStream;
         }
 
         internal void AddExtendedAttributes(IEnumerable<KeyValuePair<string, string>> existing)

src/libraries/System.Formats.Tar/tests/System.Formats.Tar.Tests.csproj

@@ -48,6 +48,7 @@
     <Compile Include="TarReader\TarReader.TarEntry.ExtractToFile.Tests.cs" />
     <Compile Include="TarReader\TarReader.File.Tests.cs" />
     <Compile Include="TarReader\TarReader.GetNextEntry.Tests.cs" />
+    <Compile Include="TarReader\TarReader.SparseFile.Tests.cs" />
     <Compile Include="TarReader\TarReader.Tests.cs" />
     <Compile Include="TarTestsBase.cs" />
     <Compile Include="TarTestsBase.Gnu.cs" />