diff --git a/AGENTS.md b/AGENTS.md index 32bbb942..3c960eea 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -126,10 +126,15 @@ SharpCompress supports multiple archive and compression formats: - See [docs/FORMATS.md](docs/FORMATS.md) for complete format support matrix ### Stream Handling Rules -- **Disposal**: As of version 0.21, SharpCompress closes wrapped streams by default -- Use `ReaderOptions` or `WriterOptions` with `LeaveStreamOpen = true` to control stream disposal +- **Disposal**: As of version 0.21, SharpCompress **closes wrapped streams by default** (`LeaveStreamOpen = false`) + - File-based overloads (e.g., `OpenArchive(string filePath)`) use `ReaderOptions.ForFilePath` automatically + - Stream-based overloads (e.g., `OpenArchive(Stream stream)`) use `ReaderOptions.ForExternalStream` by default, which sets `LeaveStreamOpen = true` +- **For caller-provided streams**: Use `ReaderOptions` with `LeaveStreamOpen = true` or the `ForExternalStream` preset to prevent automatic disposal + - Example: `var options = new ReaderOptions { LeaveStreamOpen = true };` + - Or: `var options = ReaderOptions.ForExternalStream;` +- **For file paths**: SharpCompress manages the stream lifecycle; no manual disposal needed beyond the archive/reader itself - Use `NonDisposingStream` wrapper when working with compression streams directly to prevent disposal -- Always dispose of readers, writers, and archives in `using` blocks +- Always dispose of readers, writers, and archives in `using` / `await using` blocks - For forward-only operations, use Reader/Writer APIs; for random access, use Archive APIs ### Async/Await Patterns diff --git a/src/SharpCompress/Readers/ReaderOptions.cs b/src/SharpCompress/Readers/ReaderOptions.cs index 6a063611..ed496101 100644 --- a/src/SharpCompress/Readers/ReaderOptions.cs +++ b/src/SharpCompress/Readers/ReaderOptions.cs @@ -24,9 +24,36 @@ namespace SharpCompress.Readers; public sealed record ReaderOptions : IReaderOptions { /// - /// SharpCompress will keep the supplied streams open. Default is true. + /// SharpCompress will keep the supplied streams open. + /// Default is false as of v0.21: streams are closed when the archive/reader is disposed. + /// Set to true when passing caller-owned streams that should not be disposed. /// - public bool LeaveStreamOpen { get; init; } = true; + /// + /// + /// Default behavior (LeaveStreamOpen = false): + /// When you open an archive from a file path (e.g., GZipArchive.OpenArchive(filePath)), + /// SharpCompress manages the stream lifetime and closes it on Dispose. + /// + /// + /// Caller-provided streams (LeaveStreamOpen = true): + /// When you pass a stream you created (FileStream, MemoryStream, NetworkStream, etc.), + /// set LeaveStreamOpen = true to prevent SharpCompress from disposing it. + /// Use preset for convenience. + /// + /// + /// Example: + /// + /// // File-based: stream managed by library + /// using var archive = GZipArchive.OpenArchive(filePath); // LeaveStreamOpen = false + /// + /// // Caller-provided stream: caller manages lifetime + /// using var stream = File.OpenRead(filePath); + /// var options = new ReaderOptions { LeaveStreamOpen = true }; + /// using var archive = GZipArchive.OpenArchive(stream, options); + /// + /// + /// + public bool LeaveStreamOpen { get; init; } = false; /// /// Encoding to use for archive entry names.