From e5523bc8b74da9a65c635ec9578d0da734503996 Mon Sep 17 00:00:00 2001
From: Matthias Neid <matthias@aternos.org>
Date: Tue, 8 Apr 2025 18:16:42 +0200
Subject: [PATCH] add rewind position feature

---
 src/Exception/RewindException.php             | 15 +++++++++
 .../Features/RewindPositionInterface.php      | 23 +++++++++++++
 .../Features/SetPositionInterface.php         |  2 +-
 src/System/File/File.php                      |  2 ++
 src/System/File/TempMemoryFile.php            |  2 ++
 src/System/Link/FileLink.php                  |  9 +++++
 .../Traits/RewindSocketPositionTrait.php      | 32 ++++++++++++++++++
 .../System/File/VolatileFileTestTrait.php     | 33 +++++++++++++++++++
 test/Unit/System/Link/FileLinkTest.php        | 19 +++++++++++
 9 files changed, 136 insertions(+), 1 deletion(-)
 create mode 100644 src/Exception/RewindException.php
 create mode 100644 src/Interfaces/Features/RewindPositionInterface.php
 create mode 100644 src/System/Socket/Traits/RewindSocketPositionTrait.php

diff --git a/src/Exception/RewindException.php b/src/Exception/RewindException.php
new file mode 100644
index 0000000..18f05fb
--- /dev/null
+++ b/src/Exception/RewindException.php
@@ -0,0 +1,15 @@
+<?php
+
+namespace Aternos\IO\Exception;
+
+/**
+ * Class RewindException
+ *
+ * Thrown when a rewind operation fails
+ *
+ * @package Aternos\IO\Exception
+ */
+class RewindException extends IOException
+{
+
+}
\ No newline at end of file
diff --git a/src/Interfaces/Features/RewindPositionInterface.php b/src/Interfaces/Features/RewindPositionInterface.php
new file mode 100644
index 0000000..1320f38
--- /dev/null
+++ b/src/Interfaces/Features/RewindPositionInterface.php
@@ -0,0 +1,23 @@
+<?php
+
+namespace Aternos\IO\Interfaces\Features;
+
+use Aternos\IO\Exception\IOException;
+
+/**
+ * Interface RewindPositionInterface
+ *
+ * Allows rewinding the seek position of an element to the beginning
+ *
+ * @package Aternos\IO\Interfaces\Features
+ */
+interface RewindPositionInterface extends GetPositionInterface
+{
+    /**
+     * Rewind seek position of an element to the beginning
+     *
+     * @throws IOException
+     * @return $this
+     */
+    public function rewindPosition(): static;
+}
\ No newline at end of file
diff --git a/src/Interfaces/Features/SetPositionInterface.php b/src/Interfaces/Features/SetPositionInterface.php
index 2342709..7242b96 100644
--- a/src/Interfaces/Features/SetPositionInterface.php
+++ b/src/Interfaces/Features/SetPositionInterface.php
@@ -11,7 +11,7 @@
  *
  * @package Aternos\IO\Interfaces\Features
  */
-interface SetPositionInterface extends GetPositionInterface
+interface SetPositionInterface extends RewindPositionInterface
 {
     /**
      * Set the seek position of an element
diff --git a/src/System/File/File.php b/src/System/File/File.php
index 28b0770..79f2f82 100644
--- a/src/System/File/File.php
+++ b/src/System/File/File.php
@@ -18,6 +18,7 @@
 use Aternos\IO\System\Socket\Traits\IsEndOfFileSocketTrait;
 use Aternos\IO\System\Socket\Traits\OpenSocketTrait;
 use Aternos\IO\System\Socket\Traits\ReadSocketTrait;
+use Aternos\IO\System\Socket\Traits\RewindSocketPositionTrait;
 use Aternos\IO\System\Socket\Traits\SetSocketPositionTrait;
 use Aternos\IO\System\Socket\Traits\TruncateSocketTrait;
 use Aternos\IO\System\Socket\Traits\WriteSocketTrait;
@@ -37,6 +38,7 @@ class File extends FilesystemElement implements FileInterface
         IsEndOfFileSocketTrait,
         ReadSocketTrait,
         SetSocketPositionTrait,
+        RewindSocketPositionTrait,
         TruncateSocketTrait,
         WriteSocketTrait {
         write as traitWrite;
diff --git a/src/System/File/TempMemoryFile.php b/src/System/File/TempMemoryFile.php
index 61e0e89..db6bb42 100644
--- a/src/System/File/TempMemoryFile.php
+++ b/src/System/File/TempMemoryFile.php
@@ -10,6 +10,7 @@
 use Aternos\IO\System\Socket\Traits\IsEndOfFileSocketTrait;
 use Aternos\IO\System\Socket\Traits\OpenSocketTrait;
 use Aternos\IO\System\Socket\Traits\ReadSocketTrait;
+use Aternos\IO\System\Socket\Traits\RewindSocketPositionTrait;
 use Aternos\IO\System\Socket\Traits\SetSocketPositionTrait;
 use Aternos\IO\System\Socket\Traits\TruncateSocketTrait;
 use Aternos\IO\System\Socket\Traits\WriteSocketTrait;
@@ -32,6 +33,7 @@ class TempMemoryFile implements VolatileFileInterface
         IsEndOfFileSocketTrait,
         ReadSocketTrait,
         SetSocketPositionTrait,
+        RewindSocketPositionTrait,
         TruncateSocketTrait,
         WriteSocketTrait,
         GetSizeTrait;
diff --git a/src/System/Link/FileLink.php b/src/System/Link/FileLink.php
index f9dda7d..ce678a1 100644
--- a/src/System/Link/FileLink.php
+++ b/src/System/Link/FileLink.php
@@ -140,4 +140,13 @@ public function isEndOfFile(): bool
     {
         return $this->getTarget()->isEndOfFile();
     }
+
+    /**
+     * @inheritDoc
+     */
+    public function rewindPosition(): static
+    {
+        $this->getTarget()->rewindPosition();
+        return $this;
+    }
 }
\ No newline at end of file
diff --git a/src/System/Socket/Traits/RewindSocketPositionTrait.php b/src/System/Socket/Traits/RewindSocketPositionTrait.php
new file mode 100644
index 0000000..1317a16
--- /dev/null
+++ b/src/System/Socket/Traits/RewindSocketPositionTrait.php
@@ -0,0 +1,32 @@
+<?php
+
+namespace Aternos\IO\System\Socket\Traits;
+
+use Aternos\IO\Exception\IOException;
+use Aternos\IO\Exception\RewindException;
+use Aternos\IO\Exception\SeekException;
+
+/**
+ * Trait RewindSocketPositionTrait
+ *
+ * Trait for socket based elements implementing {@link RewindPositionInterface}
+ *
+ * @package Aternos\IO\System\Socket\Traits
+ */
+trait RewindSocketPositionTrait
+{
+    use SocketTrait;
+
+    /**
+     * @inheritDoc
+     * @throws SeekException|IOException
+     */
+    public function rewindPosition(): static
+    {
+        $file = $this->getSocketResource();
+        if (!@rewind($file)) {
+            $this->throwException("Could not rewind {type} position", RewindException::class);
+        }
+        return $this;
+    }
+}
\ No newline at end of file
diff --git a/test/Unit/System/File/VolatileFileTestTrait.php b/test/Unit/System/File/VolatileFileTestTrait.php
index 543d1dd..4847a1f 100644
--- a/test/Unit/System/File/VolatileFileTestTrait.php
+++ b/test/Unit/System/File/VolatileFileTestTrait.php
@@ -6,6 +6,7 @@
 use Aternos\IO\Exception\CreateFileException;
 use Aternos\IO\Exception\IOException;
 use Aternos\IO\Exception\ReadException;
+use Aternos\IO\Exception\RewindException;
 use Aternos\IO\Exception\SeekException;
 use Aternos\IO\Exception\StatException;
 use Aternos\IO\Exception\TruncateException;
@@ -116,6 +117,38 @@ public function testSetPositionThrowsException(): void
         $file->setPosition(-1);
     }
 
+    /**
+     * @return void
+     * @throws CreateDirectoryException
+     * @throws CreateFileException
+     * @throws IOException
+     */
+    public function testRewindPosition(): void
+    {
+        $file = $this->getVolatileFile();
+        $file->write('test');
+        $this->assertEquals(4, $file->getPosition());
+        $file->rewindPosition();
+        $this->assertEquals(0, $file->getPosition());
+    }
+
+    /**
+     * @return void
+     * @throws CreateDirectoryException
+     * @throws CreateFileException
+     * @throws IOException
+     * @throws ReflectionException
+     */
+    public function testRewindPositionThrowsException(): void
+    {
+        $file = $this->getVolatileFile();
+        $reflectionFile = new ReflectionObject($file);
+        $socketResource = $reflectionFile->getProperty('socketResource');
+        $socketResource->setValue($file, fopen('php://output', 'w'));
+        $this->expectException(RewindException::class);
+        $file->rewindPosition();
+    }
+
     /**
      * @throws CreateDirectoryException
      * @throws IOException
diff --git a/test/Unit/System/Link/FileLinkTest.php b/test/Unit/System/Link/FileLinkTest.php
index db86951..3e03e5d 100644
--- a/test/Unit/System/Link/FileLinkTest.php
+++ b/test/Unit/System/Link/FileLinkTest.php
@@ -269,6 +269,25 @@ public function testSetPosition(): void
         $this->assertEquals("3", $element->read(1));
     }
 
+    /**
+     * @return void
+     * @throws DeleteException
+     * @throws GetTargetException
+     * @throws IOException
+     * @throws SetTargetException
+     */
+    public function testRewindPosition(): void
+    {
+        $targetPath = $this->getTmpPath() . "/test-target";
+        file_put_contents($targetPath, "0123456789");
+        $element = $this->createElement($this->getTmpPath() . "/test");
+        $element->setTarget(new File($targetPath));
+        $element->setPosition(3);
+        $this->assertEquals(3, $element->getPosition());
+        $element->rewindPosition();
+        $this->assertEquals(0, $element->getPosition());
+    }
+
     /**
      * @throws GetTargetException
      * @throws SetTargetException