Merge pull request #1233 from adamhathcock/adam/expose-sc-stream

Make SharpCompressStream public

Author: adamhathcock

.vscode/settings.json

@@ -25,5 +25,8 @@
   "csharpier.enableDebugLogs": false,
   "omnisharp.enableRoslynAnalyzers": true,
   "omnisharp.enableEditorConfigSupport": true,
-  "dotnet-test-explorer.testProjectPath": "tests/**/*.csproj"
+  "dotnet-test-explorer.testProjectPath": "tests/**/*.csproj",
+  "chat.tools.terminal.autoApprove": {
+    "dotnet csharpier": true
+  }
 }

src/SharpCompress/IO/SeekableSharpCompressStream.cs

@@ -16,12 +16,6 @@ internal sealed partial class SeekableSharpCompressStream : SharpCompressStream
     /// </summary>
     public override bool LeaveStreamOpen { get; }
 
-    /// <summary>
-    /// Gets or sets whether to throw an exception when Dispose is called.
-    /// Useful for testing to ensure streams are not disposed prematurely.
-    /// </summary>
-    public override bool ThrowOnDispose { get; set; }
-
     public SeekableSharpCompressStream(Stream stream, bool leaveStreamOpen = false)
         : base(Null, true, false, null)
     {

src/SharpCompress/IO/SharpCompressStream.Async.cs

@@ -5,7 +5,7 @@
 
 namespace SharpCompress.IO;
 
-internal partial class SharpCompressStream
+public partial class SharpCompressStream
 {
     public override Task<int> ReadAsync(
         byte[] buffer,

src/SharpCompress/IO/SharpCompressStream.Create.cs

@@ -4,16 +4,69 @@
 
 namespace SharpCompress.IO;
 
-internal partial class SharpCompressStream
+public partial class SharpCompressStream
 {
     /// <summary>
-    /// Creates a SharpCompressStream that acts as a passthrough wrapper.
-    /// No buffering is performed; CanSeek delegates to the underlying stream.
-    /// The underlying stream will not be disposed when this stream is disposed.
+    /// Creates a <see cref="SharpCompressStream"/> that acts as a zero-overhead passthrough wrapper
+    /// around <paramref name="stream"/> without taking ownership of it.
     /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This is a thin wrapper: all reads, writes, and seeks are forwarded directly to the underlying
+    /// stream with no ring-buffer overhead. <see cref="Stream.CanSeek"/> delegates to the underlying
+    /// stream's own value.
+    /// </para>
+    /// <para>
+    /// The resulting stream does <b>not</b> support <see cref="StartRecording"/>, <see cref="Rewind()"/>,
+    /// or <see cref="StopRecording"/>. Call <see cref="Create"/> on the passthrough stream to obtain
+    /// a recording-capable wrapper when needed.
+    /// </para>
+    /// <para>
+    /// Because the stream does not take ownership, the underlying stream is <b>never</b> disposed when
+    /// this wrapper is disposed. Use this when you need to satisfy an API that expects a
+    /// <see cref="SharpCompressStream"/> without transferring lifetime responsibility.
+    /// </para>
+    /// </remarks>
+    /// <param name="stream">The underlying stream to wrap. Must not be <see langword="null"/>.</param>
+    /// <returns>
+    /// A passthrough <see cref="SharpCompressStream"/> that does not dispose <paramref name="stream"/>.
+    /// </returns>
     public static SharpCompressStream CreateNonDisposing(Stream stream) =>
         new(stream, leaveStreamOpen: true, passthrough: true, bufferSize: null);
 
+    /// <summary>
+    /// Creates a <see cref="SharpCompressStream"/> that supports recording and rewinding over
+    /// <paramref name="stream"/>, choosing the most efficient strategy based on the stream's
+    /// capabilities.
+    /// </summary>
+    /// <remarks>
+    /// <para><b>Seekable streams</b> — wraps in a thin delegate that calls the underlying
+    /// stream's native <see cref="Stream.Seek"/> directly. No ring buffer is allocated.
+    /// <see cref="StartRecording"/> stores the current position; <see cref="Rewind()"/> seeks
+    /// back to it.</para>
+    /// <para><b>Non-seekable streams</b> (network streams, compressed streams, pipes) — allocates
+    /// a ring buffer of <paramref name="bufferSize"/> bytes. All bytes read from the underlying
+    /// stream are kept in the ring buffer so that <see cref="Rewind()"/> can replay them without
+    /// re-reading the underlying stream. If more bytes have been read than the ring buffer can hold,
+    /// a subsequent rewind will throw <see cref="InvalidOperationException"/>; increase
+    /// <paramref name="bufferSize"/> or <see cref="Common.Constants.RewindableBufferSize"/> to
+    /// avoid this.</para>
+    /// <para><b>Already-wrapped streams</b> — if <paramref name="stream"/> is already a
+    /// <see cref="SharpCompressStream"/> (or a stack that contains one), it is returned as-is to
+    /// prevent double-wrapping and double-buffering.</para>
+    /// </remarks>
+    /// <param name="stream">The underlying stream to wrap. Must not be <see langword="null"/>.</param>
+    /// <param name="bufferSize">
+    /// Size in bytes of the ring buffer allocated for non-seekable streams.
+    /// Defaults to <see cref="Common.Constants.RewindableBufferSize"/> (81 920 bytes) when
+    /// <see langword="null"/>. Has no effect when <paramref name="stream"/> is seekable, because
+    /// no ring buffer is needed in that case.
+    /// </param>
+    /// <returns>
+    /// A <see cref="SharpCompressStream"/> wrapping <paramref name="stream"/>. The returned instance
+    /// owns the stream and will dispose it unless the original source was a non-disposing passthrough
+    /// wrapper.
+    /// </returns>
     public static SharpCompressStream Create(Stream stream, int? bufferSize = null)
     {
         var rewindableBufferSize = bufferSize ?? Constants.RewindableBufferSize;
@@ -54,6 +107,6 @@ public static SharpCompressStream Create(Stream stream, int? bufferSize = null)
 
         // For non-seekable streams, create a SharpCompressStream with rolling buffer
         // to allow limited backward seeking (required by decompressors that over-read)
-        return new SharpCompressStream(stream, false, false, bufferSize);
+        return new SharpCompressStream(stream, false, false, rewindableBufferSize);
     }
 }

src/SharpCompress/IO/SharpCompressStream.cs

@@ -4,7 +4,7 @@
 
 namespace SharpCompress.IO;
 
-internal partial class SharpCompressStream : Stream, IStreamStack
+public partial class SharpCompressStream : Stream, IStreamStack
 {
     public virtual Stream BaseStream() => stream;
 
@@ -38,7 +38,7 @@ internal partial class SharpCompressStream : Stream, IStreamStack
     /// Gets or sets whether to throw an exception when Dispose is called.
     /// Useful for testing to ensure streams are not disposed prematurely.
     /// </summary>
-    public virtual bool ThrowOnDispose { get; set; }
+    internal bool ThrowOnDispose { get; set; }
 
     public SharpCompressStream(Stream stream)
     {
@@ -181,7 +181,7 @@ public virtual void StartRecording()
         // Ensure ring buffer exists
         if (_ringBuffer is null)
         {
-            _ringBuffer = new RingBuffer(Constants.BufferSize);
+            _ringBuffer = new RingBuffer(Constants.RewindableBufferSize);
         }
 
         // Mark current position as recording anchor

tests/SharpCompress.Test/packages.lock.json

@@ -309,30 +309,6 @@
         }
       }
     },
-    ".NETFramework,Version=v4.8/win-x86": {
-      "Microsoft.Win32.Registry": {
-        "type": "Transitive",
-        "resolved": "5.0.0",
-        "contentHash": "dDoKi0PnDz31yAyETfRntsLArTlVAVzUzCIvvEDsDsucrl33Dl8pIJG06ePTJTI3tGpeyHS9Cq7Foc/s4EeKcg==",
-        "dependencies": {
-          "System.Security.AccessControl": "5.0.0",
-          "System.Security.Principal.Windows": "5.0.0"
-        }
-      },
-      "System.Security.AccessControl": {
-        "type": "Transitive",
-        "resolved": "5.0.0",
-        "contentHash": "dagJ1mHZO3Ani8GH0PHpPEe/oYO+rVdbQjvjJkBRNQkX4t0r1iaeGn8+/ybkSLEan3/slM0t59SVdHzuHf2jmw==",
-        "dependencies": {
-          "System.Security.Principal.Windows": "5.0.0"
-        }
-      },
-      "System.Security.Principal.Windows": {
-        "type": "Transitive",
-        "resolved": "5.0.0",
-        "contentHash": "t0MGLukB5WAVU9bO3MGzvlGnyJPgUlcwerXn1kzBRjwLKixT96XV0Uza41W49gVd8zEMFu9vQEFlv0IOrytICA=="
-      }
-    },
     "net10.0": {
       "AwesomeAssertions": {
         "type": "Direct",
@@ -545,13 +521,6 @@
         "resolved": "8.0.0",
         "contentHash": "3WA9q9yVqJp222P3x1wYIGDAkpjAku0TMUaaQV22g6L67AI0LdOIrVS7Ht2vJfLHGSPVuqN94vIr15qn+HEkHw=="
       }
-    },
-    "net10.0/win-x86": {
-      "Microsoft.Win32.Registry": {
-        "type": "Transitive",
-        "resolved": "5.0.0",
-        "contentHash": "dDoKi0PnDz31yAyETfRntsLArTlVAVzUzCIvvEDsDsucrl33Dl8pIJG06ePTJTI3tGpeyHS9Cq7Foc/s4EeKcg=="
-      }
     }
   }
 }