Implement ShouldDispose property for StreamFile with comprehensive tests

Co-authored-by: Arlodotexe <9384894+Arlodotexe@users.noreply.github.com>

Author: Copilot

src/OwlCore.Storage.csproj

@@ -1,6 +1,6 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
-    <TargetFrameworks>netstandard2.0</TargetFrameworks>
+    <TargetFrameworks>netstandard2.0;net9.0</TargetFrameworks>
     <Nullable>enable</Nullable>
     <LangVersion>12.0</LangVersion>
     <WarningsAsErrors>nullable</WarningsAsErrors>

src/System/IO/StreamFile.cs

@@ -7,7 +7,7 @@
 namespace OwlCore.Storage.System.IO;
 
 /// <summary>
-/// A file implementation which holds a reference to the provided <see cref="Stream"/> and returns it in a non-disposable wrapper for <see cref="OpenStreamAsync"/>.
+/// A file implementation which holds a reference to the provided <see cref="Stream"/> and returns it either wrapped in a non-disposable wrapper or directly, based on the <see cref="ShouldDispose"/> property.
 /// </summary>
 public class StreamFile : IFile
 {
@@ -16,12 +16,28 @@ public class StreamFile : IFile
     /// </summary>
     public Stream Stream { get; }
 
+    /// <summary>
+    /// Gets a value indicating whether the underlying stream should be disposed when the returned stream from <see cref="OpenStreamAsync"/> is disposed.
+    /// When true, the underlying stream is returned directly. When false, the stream is wrapped in a non-disposable wrapper.
+    /// </summary>
+    public bool ShouldDispose { get; }
+
     /// <summary>
     /// Creates a new instance of <see cref="StreamFile"/>.
     /// </summary>
     /// <param name="stream">An existing stream which is provided as the file contents.</param>
     public StreamFile(Stream stream)
-        : this(stream, $"{stream.GetHashCode()}", $"{stream.GetHashCode()}")
+        : this(stream, $"{stream.GetHashCode()}", $"{stream.GetHashCode()}", false)
+    {
+    }
+
+    /// <summary>
+    /// Creates a new instance of <see cref="StreamFile"/>.
+    /// </summary>
+    /// <param name="stream">An existing stream which is provided as the file contents.</param>
+    /// <param name="shouldDispose">When true, the underlying stream will be disposed when the returned stream from <see cref="OpenStreamAsync"/> is disposed. When false, the stream is wrapped in a non-disposable wrapper.</param>
+    public StreamFile(Stream stream, bool shouldDispose)
+        : this(stream, $"{stream.GetHashCode()}", $"{stream.GetHashCode()}", shouldDispose)
     {
     }
 
@@ -32,10 +48,23 @@ public StreamFile(Stream stream)
     /// <param name="id">A unique and consistent identifier for this file or folder.</param>
     /// <param name="name">The name of the file or folder, with the extension (if any).</param>
     public StreamFile(Stream stream, string id, string name)
+        : this(stream, id, name, false)
+    {
+    }
+
+    /// <summary>
+    /// Creates a new instance of <see cref="StreamFile"/>.
+    /// </summary>
+    /// <param name="stream">An existing stream which is provided as the file contents.</param>
+    /// <param name="id">A unique and consistent identifier for this file or folder.</param>
+    /// <param name="name">The name of the file or folder, with the extension (if any).</param>
+    /// <param name="shouldDispose">When true, the underlying stream will be disposed when the returned stream from <see cref="OpenStreamAsync"/> is disposed. When false, the stream is wrapped in a non-disposable wrapper.</param>
+    public StreamFile(Stream stream, string id, string name, bool shouldDispose)
     {
         Stream = stream;
         Id = id;
         Name = name;
+        ShouldDispose = shouldDispose;
     }
 
     /// <inheritdoc />
@@ -52,6 +81,9 @@ public Task<Stream> OpenStreamAsync(FileAccess accessMode = FileAccess.Read, Can
         if (accessMode == 0)
             throw new ArgumentOutOfRangeException(nameof(accessMode), $"{nameof(FileAccess)}.{accessMode} is not valid here.");
 
+        if (ShouldDispose)
+            return Task.FromResult(Stream);
+
         return Task.FromResult<Stream>(new NonDisposableStreamWrapper(Stream));
     }
 }

tests/OwlCore.Storage.Tests/OwlCore.Storage.Tests.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
+    <TargetFramework>net9.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
 

tests/OwlCore.Storage.Tests/StreamFileTests.cs

@@ -27,5 +27,144 @@ static byte[] GenerateRandomData(int length)
                 return b;
             }
         }
+
+        [TestMethod]
+        public void ShouldDispose_DefaultValue_IsFalse()
+        {
+            // Arrange
+            var memoryStream = new MemoryStream();
+
+            // Act
+            var streamFile = new StreamFile(memoryStream);
+
+            // Assert
+            Assert.IsFalse(streamFile.ShouldDispose);
+        }
+
+        [TestMethod]
+        public void ShouldDispose_Constructor_SetsCorrectValue()
+        {
+            // Arrange
+            var memoryStream = new MemoryStream();
+
+            // Act
+            var streamFileTrue = new StreamFile(memoryStream, true);
+            var streamFileFalse = new StreamFile(memoryStream, false);
+
+            // Assert
+            Assert.IsTrue(streamFileTrue.ShouldDispose);
+            Assert.IsFalse(streamFileFalse.ShouldDispose);
+        }
+
+        [TestMethod]
+        public void ShouldDispose_ConstructorWithIdAndName_SetsCorrectValue()
+        {
+            // Arrange
+            var memoryStream = new MemoryStream();
+            var id = "test-id";
+            var name = "test-name";
+
+            // Act
+            var streamFileTrue = new StreamFile(memoryStream, id, name, true);
+            var streamFileFalse = new StreamFile(memoryStream, id, name, false);
+
+            // Assert
+            Assert.IsTrue(streamFileTrue.ShouldDispose);
+            Assert.IsFalse(streamFileFalse.ShouldDispose);
+        }
+
+        [TestMethod]
+        public async Task OpenStreamAsync_ShouldDisposeTrue_ReturnsUnderlyingStream()
+        {
+            // Arrange
+            var memoryStream = new MemoryStream();
+            var streamFile = new StreamFile(memoryStream, true);
+
+            // Act
+            var resultStream = await streamFile.OpenStreamAsync();
+
+            // Assert
+            Assert.AreSame(memoryStream, resultStream);
+        }
+
+        [TestMethod]
+        public async Task OpenStreamAsync_ShouldDisposeFalse_ReturnsWrappedStream()
+        {
+            // Arrange
+            var memoryStream = new MemoryStream();
+            var streamFile = new StreamFile(memoryStream, false);
+
+            // Act
+            var resultStream = await streamFile.OpenStreamAsync();
+
+            // Assert
+            Assert.AreNotSame(memoryStream, resultStream);
+            Assert.AreEqual(typeof(OwlCore.Storage.Memory.NonDisposableStreamWrapper), resultStream.GetType());
+        }
+
+        [TestMethod]
+        public async Task OpenStreamAsync_ShouldDisposeTrue_DisposingReturnedStreamDisposesUnderlying()
+        {
+            // Arrange
+            var memoryStream = new MemoryStream();
+            var streamFile = new StreamFile(memoryStream, true);
+
+            // Act
+            var resultStream = await streamFile.OpenStreamAsync();
+            resultStream.Dispose();
+
+            // Assert
+            Assert.ThrowsException<ObjectDisposedException>(() => memoryStream.ReadByte());
+        }
+
+        [TestMethod]
+        public async Task OpenStreamAsync_ShouldDisposeFalse_DisposingReturnedStreamDoesNotDisposeUnderlying()
+        {
+            // Arrange
+            var data = new byte[] { 1, 2, 3, 4, 5 };
+            var memoryStream = new MemoryStream(data);
+            var streamFile = new StreamFile(memoryStream, false);
+
+            // Act
+            var resultStream = await streamFile.OpenStreamAsync();
+            resultStream.Dispose();
+
+            // Assert - underlying stream should still be usable
+            memoryStream.Position = 0;
+            Assert.AreEqual(1, memoryStream.ReadByte());
+        }
+
+        [TestMethod]
+        public async Task OpenStreamAsync_ShouldDisposeTrue_MultipleOpensReturnSameStream()
+        {
+            // Arrange
+            var memoryStream = new MemoryStream();
+            var streamFile = new StreamFile(memoryStream, true);
+
+            // Act
+            var stream1 = await streamFile.OpenStreamAsync();
+            var stream2 = await streamFile.OpenStreamAsync();
+
+            // Assert
+            Assert.AreSame(stream1, stream2);
+            Assert.AreSame(memoryStream, stream1);
+        }
+
+        [TestMethod]
+        public async Task OpenStreamAsync_ShouldDisposeFalse_MultipleOpensReturnDifferentWrappers()
+        {
+            // Arrange
+            var memoryStream = new MemoryStream();
+            var streamFile = new StreamFile(memoryStream, false);
+
+            // Act
+            var stream1 = await streamFile.OpenStreamAsync();
+            var stream2 = await streamFile.OpenStreamAsync();
+
+            // Assert
+            Assert.AreNotSame(stream1, stream2);
+            Assert.AreEqual(typeof(OwlCore.Storage.Memory.NonDisposableStreamWrapper), stream1.GetType());
+            Assert.AreEqual(typeof(OwlCore.Storage.Memory.NonDisposableStreamWrapper), stream2.GetType());
+        }
     }
 }