feat: append command

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>

lib/Client/Protocol/ResponseStream.php

@@ -6,6 +6,7 @@ namespace KTXM\ProviderImap\Client\Protocol;
 
 use Generator;
 use IteratorAggregate;
+use KTXM\ProviderImap\Client\ImapException;
 use Traversable;
 
 final class ResponseStream implements IteratorAggregate
@@ -13,16 +14,39 @@ final class ResponseStream implements IteratorAggregate
     /** @var \Closure():Generator */
     private readonly \Closure $generatorFactory;
 
+    /** @var (\Closure(string):void)|null */
+    private readonly ?\Closure $continuationWriter;
+
     /**
-     * @param \Closure():Generator $generatorFactory
+     * @param \Closure():Generator        $generatorFactory
+     * @param (\Closure(string):void)|null $continuationWriter writes raw bytes
+     *        back to the server in response to a command continuation request
      */
-    public function __construct(\Closure $generatorFactory)
+    public function __construct(\Closure $generatorFactory, ?\Closure $continuationWriter = null)
     {
         $this->generatorFactory = $generatorFactory;
+        $this->continuationWriter = $continuationWriter;
     }
 
     public function getIterator(): Traversable
     {
         return ($this->generatorFactory)();
     }
-}
+
+    /**
+     * Send raw bytes to the server after a command continuation request (a "+"
+     * response) — e.g. the literal payload of an APPEND.
+     *
+     * Must only be called while iterating this stream, in response to a
+     * {@see \KTXM\ProviderImap\Client\Protocol\Response\ContinuationResponse};
+     * the next pulled response then reflects the server's reaction to the data.
+     */
+    public function respond(string $payload): void
+    {
+        if ($this->continuationWriter === null) {
+            throw new ImapException('This response stream does not support continuation replies.');
+        }
+
+        ($this->continuationWriter)($payload);
+    }
+}