Add SOZip (Seek-Optimized ZIP) support

FORMATS.md

@@ -25,7 +25,7 @@
 | 7Zip (4)               | LZMA, LZMA2, BZip2, PPMd, BCJ, BCJ2, Deflate      | Decompress          | SevenZipArchive | N/A        | N/A           |
 
 1. SOLID Rars are only supported in the RarReader API.
-2. Zip format supports pkware and WinzipAES encryption. However, encrypted LZMA is not supported. Zip64 reading/writing is supported but only with seekable streams as the Zip spec doesn't support Zip64 data in post data descriptors. Deflate64 is only supported for reading. See [Zip Format Notes](#zip-format-notes) for details on multi-volume archives and streaming behavior.
+2. Zip format supports pkware and WinzipAES encryption. However, encrypted LZMA is not supported. Zip64 reading/writing is supported but only with seekable streams as the Zip spec doesn't support Zip64 data in post data descriptors. Deflate64 is only supported for reading. SOZip (Seek-Optimized ZIP) detection is supported for reading. See [Zip Format Notes](#zip-format-notes) for details on multi-volume archives and streaming behavior.
 3. The Tar format requires a file size in the header. If no size is specified to the TarWriter and the stream is not seekable, then an exception will be thrown.
 4. The 7Zip format doesn't allow for reading as a forward-only stream so 7Zip is only supported through the Archive API. See [7Zip Format Notes](#7zip-format-notes) for details on async extraction behavior.
 5. LZip has no support for extra data like the file name or timestamp. There is a default filename used when looking at the entry Key on the archive.

src/SharpCompress/Common/Zip/Headers/LocalEntryHeaderExtraFactory.cs

@@ -15,6 +15,10 @@ internal enum ExtraDataType : ushort
     UnicodePathExtraField = 0x7075,
     Zip64ExtendedInformationExtraField = 0x0001,
     UnixTimeExtraField = 0x5455,
+
+    // SOZip (Seek-Optimized ZIP) extra field
+    // Used to link a main file to its SOZip index file
+    SOZip = 0x564B,
 }
 
 internal class ExtraData
@@ -233,6 +237,44 @@ private enum RecordedTimeFlag
     }
 }
 
+/// <summary>
+/// SOZip (Seek-Optimized ZIP) extra field that links a main file to its index file.
+/// The extra field contains the offset within the ZIP file where the index entry's
+/// local header is located.
+/// </summary>
+internal sealed class SOZipExtraField : ExtraData
+{
+    public SOZipExtraField(ExtraDataType type, ushort length, byte[] dataBytes)
+        : base(type, length, dataBytes) { }
+
+    /// <summary>
+    /// Gets the offset to the SOZip index file's local entry header within the ZIP archive.
+    /// </summary>
+    internal ulong IndexOffset
+    {
+        get
+        {
+            if (DataBytes is null || DataBytes.Length < 8)
+            {
+                return 0;
+            }
+            return BinaryPrimitives.ReadUInt64LittleEndian(DataBytes);
+        }
+    }
+
+    /// <summary>
+    /// Creates a SOZip extra field with the specified index offset
+    /// </summary>
+    /// <param name="indexOffset">The offset to the index file's local entry header</param>
+    /// <returns>A new SOZipExtraField instance</returns>
+    public static SOZipExtraField Create(ulong indexOffset)
+    {
+        var data = new byte[8];
+        BinaryPrimitives.WriteUInt64LittleEndian(data, indexOffset);
+        return new SOZipExtraField(ExtraDataType.SOZip, 8, data);
+    }
+}
+
 internal static class LocalEntryHeaderExtraFactory
 {
     internal static ExtraData Create(ExtraDataType type, ushort length, byte[] extraData) =>
@@ -246,6 +288,7 @@ internal static ExtraData Create(ExtraDataType type, ushort length, byte[] extra
             ExtraDataType.Zip64ExtendedInformationExtraField =>
                 new Zip64ExtendedInformationExtraField(type, length, extraData),
             ExtraDataType.UnixTimeExtraField => new UnixTimeExtraField(type, length, extraData),
+            ExtraDataType.SOZip => new SOZipExtraField(type, length, extraData),
             _ => new ExtraData(type, length, extraData),
         };
 }

src/SharpCompress/Common/Zip/SOZip/SOZipDeflateStream.cs

@@ -0,0 +1,150 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using SharpCompress.Compressors;
+using SharpCompress.Compressors.Deflate;
+
+namespace SharpCompress.Common.Zip.SOZip;
+
+/// <summary>
+/// A Deflate stream that inserts sync flush points at regular intervals
+/// to enable random access (SOZip optimization).
+/// </summary>
+internal sealed class SOZipDeflateStream : Stream
+{
+    private readonly DeflateStream _deflateStream;
+    private readonly Stream _baseStream;
+    private readonly uint _chunkSize;
+    private readonly List<ulong> _compressedOffsets = new();
+    private readonly long _baseOffset;
+    private long _uncompressedBytesWritten;
+    private long _nextSyncPoint;
+    private bool _disposed;
+
+    /// <summary>
+    /// Creates a new SOZip Deflate stream
+    /// </summary>
+    /// <param name="baseStream">The underlying stream to write to</param>
+    /// <param name="compressionLevel">The compression level</param>
+    /// <param name="chunkSize">The chunk size for sync flush points</param>
+    public SOZipDeflateStream(Stream baseStream, CompressionLevel compressionLevel, int chunkSize)
+    {
+        _baseStream = baseStream;
+        _chunkSize = (uint)chunkSize;
+        _baseOffset = baseStream.Position;
+        _nextSyncPoint = chunkSize;
+
+        // Record the first offset (start of compressed data)
+        _compressedOffsets.Add(0);
+
+        _deflateStream = new DeflateStream(baseStream, CompressionMode.Compress, compressionLevel);
+    }
+
+    /// <summary>
+    /// Gets the array of compressed offsets recorded during writing
+    /// </summary>
+    public ulong[] CompressedOffsets => _compressedOffsets.ToArray();
+
+    /// <summary>
+    /// Gets the total number of uncompressed bytes written
+    /// </summary>
+    public ulong UncompressedBytesWritten => (ulong)_uncompressedBytesWritten;
+
+    /// <summary>
+    /// Gets the total number of compressed bytes written
+    /// </summary>
+    public ulong CompressedBytesWritten => (ulong)(_baseStream.Position - _baseOffset);
+
+    /// <summary>
+    /// Gets the chunk size being used
+    /// </summary>
+    public uint ChunkSize => _chunkSize;
+
+    public override bool CanRead => false;
+
+    public override bool CanSeek => false;
+
+    public override bool CanWrite => !_disposed && _deflateStream.CanWrite;
+
+    public override long Length => throw new NotSupportedException();
+
+    public override long Position
+    {
+        get => throw new NotSupportedException();
+        set => throw new NotSupportedException();
+    }
+
+    public override void Flush() => _deflateStream.Flush();
+
+    public override int Read(byte[] buffer, int offset, int count) =>
+        throw new NotSupportedException();
+
+    public override long Seek(long offset, SeekOrigin origin) => throw new NotSupportedException();
+
+    public override void SetLength(long value) => throw new NotSupportedException();
+
+    public override void Write(byte[] buffer, int offset, int count)
+    {
+        if (_disposed)
+        {
+            throw new ObjectDisposedException(nameof(SOZipDeflateStream));
+        }
+
+        var remaining = count;
+        var currentOffset = offset;
+
+        while (remaining > 0)
+        {
+            // Calculate how many bytes until the next sync point
+            var bytesUntilSync = (int)(_nextSyncPoint - _uncompressedBytesWritten);
+
+            if (bytesUntilSync <= 0)
+            {
+                // We've reached a sync point - perform sync flush
+                PerformSyncFlush();
+                continue;
+            }
+
+            // Write up to the next sync point
+            var bytesToWrite = Math.Min(remaining, bytesUntilSync);
+            _deflateStream.Write(buffer, currentOffset, bytesToWrite);
+
+            _uncompressedBytesWritten += bytesToWrite;
+            currentOffset += bytesToWrite;
+            remaining -= bytesToWrite;
+        }
+    }
+
+    private void PerformSyncFlush()
+    {
+        // Flush with Z_SYNC_FLUSH to create an independent block
+        var originalFlushMode = _deflateStream.FlushMode;
+        _deflateStream.FlushMode = FlushType.Sync;
+        _deflateStream.Flush();
+        _deflateStream.FlushMode = originalFlushMode;
+
+        // Record the compressed offset for this sync point
+        var compressedOffset = (ulong)(_baseStream.Position - _baseOffset);
+        _compressedOffsets.Add(compressedOffset);
+
+        // Set the next sync point
+        _nextSyncPoint += _chunkSize;
+    }
+
+    protected override void Dispose(bool disposing)
+    {
+        if (_disposed)
+        {
+            return;
+        }
+
+        _disposed = true;
+
+        if (disposing)
+        {
+            _deflateStream.Dispose();
+        }
+
+        base.Dispose(disposing);
+    }
+}