feat: append command

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

lib/Client/Protocol/CommandExecutor.php

@@ -42,9 +42,14 @@ final class CommandExecutor
         $frame = $command->encode($tag, $context);
         $this->writer->write($tag, $frame);
 
-        return $command->handle(new ResponseStream(function () use ($tag, $context): Generator {
-            yield from $this->processPerform($tag, $context);
-        }), $context);
+        return $command->handle(new ResponseStream(
+            function () use ($tag, $context): Generator {
+                yield from $this->processPerform($tag, $context);
+            },
+            function (string $payload): void {
+                $this->writer->writeRaw($payload);
+            },
+        ), $context);
     }
 
     /**

lib/Client/Protocol/ProtocolWriter.php

@@ -27,6 +27,21 @@ final class ProtocolWriter
         $this->connection->write($wire);
     }
 
+    /**
+     * Write raw bytes to the connection without tagging or logging the payload.
+     *
+     * Used to send literal data (e.g. an APPEND message body) after the server
+     * has issued a command continuation request.
+     */
+    public function writeRaw(string $payload): void
+    {
+        $this->logger?->debug('IMAP literal sent (bytes={bytes})', [
+            'bytes' => strlen($payload),
+        ]);
+
+        $this->connection->write($payload);
+    }
+
     private function sanitizeWire(string $wire): string
     {
         $trimmed = rtrim($wire, "\r\n");

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);
+    }
+}