Extract StreamPortal utility from Ressy into PowerKit

PowerKit.Tests/StreamPortalTests.cs

@@ -0,0 +1,59 @@
+using System.IO;
+using FluentAssertions;
+using PowerKit.Extensions;
+using Xunit;
+
+namespace PowerKit.Tests;
+
+public class StreamPortalTests
+{
+    [Fact]
+    public void CreatePortal_AtCurrentPosition_Test()
+    {
+        // Arrange
+        var data = new byte[] { 1, 2, 3, 4, 5 };
+        using var stream = new MemoryStream(data);
+        stream.Seek(2, SeekOrigin.Begin);
+
+        // Act
+        var portal = stream.CreatePortal();
+
+        // Assert
+        portal.Position.Should().Be(2);
+    }
+
+    [Fact]
+    public void CreatePortal_AtSpecifiedPosition_Test()
+    {
+        // Arrange
+        var data = new byte[] { 1, 2, 3, 4, 5 };
+        using var stream = new MemoryStream(data);
+
+        // Act
+        var portal = stream.CreatePortal(3);
+
+        // Assert
+        portal.Position.Should().Be(3);
+    }
+
+    [Fact]
+    public void Jump_SeeksToPortalPositionAndRestoresOnDispose_Test()
+    {
+        // Arrange
+        var data = new byte[] { 1, 2, 3, 4, 5 };
+        using var stream = new MemoryStream(data);
+        stream.Seek(1, SeekOrigin.Begin);
+        var portal = stream.CreatePortal(4);
+
+        // Act
+        var jump = portal.Jump();
+
+        // Assert - seeks to portal position
+        stream.Position.Should().Be(4);
+
+        jump.Dispose();
+
+        // Assert - restores original position on dispose
+        stream.Position.Should().Be(1);
+    }
+}

PowerKit/Extensions/StreamExtensions.cs

@@ -13,6 +13,16 @@ public static class StreamExtensions
 {
     extension(Stream source)
     {
+        /// <summary>
+        /// Creates a portal to the specified position in the stream.
+        /// </summary>
+        public StreamPortal CreatePortal(long position) => new(source, position);
+
+        /// <summary>
+        /// Creates a portal to the current position in the stream.
+        /// </summary>
+        public StreamPortal CreatePortal() => source.CreatePortal(source.Position);
+
 #if NET40_OR_GREATER || NETSTANDARD || NET
         /// <summary>
         /// Copies the contents of the stream to the destination stream, optionally flushing after each write.

PowerKit/StreamPortal.cs

@@ -0,0 +1,35 @@
+using System;
+using System.IO;
+
+namespace PowerKit;
+
+/// <summary>
+/// Represents a saved position in a stream that can be jumped to and returned from.
+/// </summary>
+public class StreamPortal(Stream stream, long position)
+{
+    /// <summary>
+    /// Gets the position this portal points to.
+    /// </summary>
+    public long Position { get; } =
+        stream.CanSeek
+            ? position >= 0
+                ? position
+                : throw new ArgumentOutOfRangeException(
+                    nameof(position),
+                    "Position must be non-negative."
+                )
+            : throw new ArgumentException("Stream must support seeking.", nameof(stream));
+
+    /// <summary>
+    /// Seeks the stream to the portal's position and returns a disposable that,
+    /// when disposed, seeks back to the original position.
+    /// </summary>
+    public IDisposable Jump()
+    {
+        var oldPosition = stream.Position;
+        stream.Seek(Position, SeekOrigin.Begin);
+
+        return Disposable.Create(() => stream.Seek(oldPosition, SeekOrigin.Begin));
+    }
+}