feat: implement download

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

lib/Client/Client.php

@@ -6,8 +6,8 @@ namespace KTXM\ProviderImap\Client;
 
 use KTXM\ProviderImap\Client\Command\CapabilityCommand;
 use KTXM\ProviderImap\Client\Command\CommandInterface;
+use KTXM\ProviderImap\Client\FetchTarget;
 use KTXM\ProviderImap\Client\Command\LoginCommand;
-use KTXM\ProviderImap\Client\Command\StatusCommand;
 use KTXM\ProviderImap\Client\Command\StartTlsCommand;
 use KTXM\ProviderImap\Client\Protocol\CommandExecutor;
 use KTXM\ProviderImap\Client\Protocol\ProtocolReader;
@@ -87,6 +87,15 @@ final class Client implements ClientInterface
         return $this->executor->perform($command, $this->session);
     }
 
+    public function download(FetchTarget $target, string $section, int $chunkSize = 8192): \Generator
+    {
+        if ($this->session === null || $this->executor === null) {
+            throw new ImapException('IMAP client is not connected.');
+        }
+
+        return $this->executor->download($target, $section, $chunkSize, $this->session);
+    }
+
     public function session(): SessionContext
     {
         if ($this->session === null) {

lib/Client/ClientInterface.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace KTXM\ProviderImap\Client;
 
 use KTXM\ProviderImap\Client\Command\CommandInterface;
+use KTXM\ProviderImap\Client\FetchTarget;
 
 interface ClientInterface
 {
@@ -21,4 +22,11 @@ interface ClientInterface
      * @return TResult
      */
     public function perform(CommandInterface $command): mixed;
+
+    /**
+     * Stream the raw bytes of a single IMAP BODY section without buffering.
+     *
+     * @return \Generator<string>  raw (transfer-encoded) bytes from the socket
+     */
+    public function download(FetchTarget $target, string $section, int $chunkSize = 8192): \Generator;
 }

lib/Client/FetchOptions.php

@@ -89,6 +89,11 @@ final class FetchOptions
         return $this->with('BODY[TEXT]');
     }
 
+    public function withBody(): self
+    {
+        return $this->with('BODY[]');
+    }
+
     public function withBodySection(string $section): self
     {
         $section = strtoupper(trim($section));

lib/Client/Message.php

@@ -156,6 +156,11 @@ final class Message
         return $this->bodySections;
     }
 
+    public function bodyRaw(): ?string
+    {
+        return $this->bodySections[''] ?? null;
+    }
+
     /**
      * @param array<string, string> $bodySections
      */

lib/Client/MessageParser.php

@@ -524,9 +524,6 @@ final class MessageParser
             }
 
             $section = strtoupper(trim($matches[1]));
-            if ($section === '') {
-                continue;
-            }
 
              if (preg_match('/^(\d+(?:\.\d+)*)\.TEXT$/', $section, $partMatches) === 1) {
                 $section = $partMatches[1];

lib/Client/MessagePart.php

@@ -167,8 +167,9 @@ final class MessagePart
     {
         $data = [
             'partId' => $this->partId,
+            'blobId' => $this->partId,
+            'cId' => $this->contentId,
             'type' => $this->mimeType,
-            'blobId' => $this->contentId,
             'charset' => $this->parameters['charset'] ?? null,
             'name' => $this->parameters['name'] ?? $this->dispositionParameters['filename'] ?? null,
             'encoding' => $this->encoding,

lib/Client/Protocol/CommandExecutor.php

@@ -6,9 +6,11 @@ namespace KTXM\ProviderImap\Client\Protocol;
 
 use Generator;
 use KTXM\ProviderImap\Client\Command\CommandInterface;
+use KTXM\ProviderImap\Client\FetchTarget;
 use KTXM\ProviderImap\Client\ImapException;
 use KTXM\ProviderImap\Client\Protocol\Response\TaggedResponse;
 use KTXM\ProviderImap\Client\Protocol\Response\UntaggedResponse;
+use KTXM\ProviderImap\Client\Protocol\RequestFrame;
 use KTXM\ProviderImap\Client\SessionContext;
 use KTXM\ProviderImap\Client\SessionState;
 use Psr\Log\LoggerInterface;
@@ -41,10 +43,42 @@ final class CommandExecutor
         $this->writer->write($tag, $frame);
 
         return $command->handle(new ResponseStream(function () use ($tag, $context): Generator {
-            yield from $this->responsesUntilCompletion($tag, $context);
+            yield from $this->processPerform($tag, $context);
         }), $context);
     }
 
+    /**
+     * Stream the raw bytes of a single IMAP BODY section without buffering.
+     *
+     * Sends a UID FETCH for the given section and yields the literal bytes
+     * directly from the socket in chunks, never assembling a full string.
+     * The caller MUST fully exhaust the returned Generator before issuing
+     * any further IMAP commands.
+     *
+     * @return \Generator<string>  raw (transfer-encoded) bytes from the socket
+     */
+    public function download(FetchTarget $target, string $section, int $chunkSize, SessionContext $context): \Generator
+    {
+        $this->assertState([SessionState::Selected], $context->state(), 'FETCH (download)');
+
+        $tag = $this->tags->next();
+        $this->writer->write($tag, new RequestFrame(sprintf(
+            'UID FETCH %s (UID BODY[%s])',
+            $target->sequenceSet()->toCommand(),
+            $section,
+        )));
+
+        $result = $this->reader->readUntilFetchLiteral($tag);
+
+        if ($result === null) {
+            return; // UID not found or empty FETCH result
+        }
+
+        yield from $this->reader->streamLiteral($result['literalLength'], $chunkSize);
+
+        $this->reader->readToEnd($tag);
+    }
+
     /**
      * @param list<SessionState> $allowedStates
      */
@@ -63,7 +97,7 @@ final class CommandExecutor
         ));
     }
 
-    private function responsesUntilCompletion(string $tag, SessionContext $context): Generator
+    private function processPerform(string $tag, SessionContext $context): Generator
     {
         while (true) {
             $response = $this->reader->readResponse();

lib/Client/Protocol/ProtocolReader.php

@@ -42,7 +42,14 @@ final class ProtocolReader
 
     public function readResponse(): ResponseInterface
     {
-        $raw = $this->readRawResponse();
+        $raw = $this->connection->readLine();
+
+        while (($literalLength = $this->trailingLiteralLength($raw)) !== null) {
+            $raw .= $this->connection->readBytes($literalLength);
+            $raw .= $this->connection->readLine();
+        }
+
+        $raw = $this->trimTrailingLineEnding($raw);
 
         if ($raw === '') {
             throw new ImapException('Received empty IMAP response line.');
@@ -85,16 +92,72 @@ final class ProtocolReader
         return new TaggedResponse($parts[0], $status, $parts[2] ?? '', $raw);
     }
 
-    private function readRawResponse(): string
+    /**
+     * Read responses until an untagged FETCH response containing a literal marker is found,
+     * returning the literal byte count WITHOUT consuming the literal bytes from the socket.
+     * Returns null if the tagged OK/NO/BAD for $tag arrives before any literal is detected.
+     *
+     * ⚠️ After a non-null return the literal bytes MUST be consumed (via streamLiteral())
+     * before any further reads are made on this reader.
+     *
+     * @return array{literalLength: int, prefixLine: string}|null
+     */
+    public function readUntilFetchLiteral(string $tag): ?array
     {
-        $raw = $this->connection->readLine();
+        while (true) {
+            $line = $this->connection->readLine();
+            $trimmed = $this->trimTrailingLineEnding($line);
 
-        while (($literalLength = $this->trailingLiteralLength($raw)) !== null) {
-            $raw .= $this->connection->readBytes($literalLength);
-            $raw .= $this->connection->readLine();
+            // Literal marker at the end of the line — stop before consuming the bytes
+            $literalLength = $this->trailingLiteralLength($line);
+            if ($literalLength !== null) {
+                return ['literalLength' => $literalLength, 'prefixLine' => $trimmed];
+            }
+
+            // Tagged completion for our command
+            if (str_starts_with($trimmed, $tag . ' ')) {
+                $parts = preg_split('/\s+/', $trimmed, 3) ?: [];
+                $status = strtoupper($parts[1] ?? '');
+                if ($status === 'NO' || $status === 'BAD') {
+                    throw new ImapException(sprintf('FETCH command failed: %s', $trimmed));
+                }
+                return null; // Tagged OK without ever finding a literal → UID not found
+            }
+
+            // Any other untagged response — discard and continue
         }
+    }
 
-        return $this->trimTrailingLineEnding($raw);
+    public function readToEnd(string $tag): TaggedResponse
+    {
+        while (true) {
+            $response = $this->readResponse();
+
+            if ($response instanceof TaggedResponse && $response->tag() === $tag) {
+                if (!$response->isOk()) {
+                    throw new ImapException(sprintf('FETCH failed: %s', $response->text()));
+                }
+                return $response;
+            }
+        }
+    }
+
+    /**
+     * Yield the literal bytes already waiting in the socket as chunks.
+     * After the generator is fully exhausted this method reads the one trailing
+     * line that closes the FETCH parenthesised response (e.g. ")\r\n").
+     *
+     * Contract: the caller MUST exhaust this generator before issuing any further
+     * reads on this reader.
+     *
+     * @return \Generator<string>
+     */
+    public function streamLiteral(int $length, int $chunkSize = 8192): \Generator
+    {
+        yield from $this->connection->readBytesChunked($length, $chunkSize);
+
+        // Consume the closing portion of the FETCH parenthesised list (e.g. ")\r\n")
+        $this->connection->readLine();
     }
 
     private function trailingLiteralLength(string $raw): ?int

lib/Client/Transport/ConnectionInterface.php

@@ -20,5 +20,13 @@ interface ConnectionInterface
 
     public function readBytes(int $length): string;
 
+    /**
+     * Yield the literal payload in chunks without buffering the full content.
+     * Reads exactly $length bytes from the socket, never crossing the literal boundary.
+     *
+     * @return \Generator<string>
+     */
+    public function readBytesChunked(int $length, int $chunkSize = 8192): \Generator;
+
     public function upgradeToTls(): void;
 }

lib/Client/Transport/SocketConnection.php

@@ -135,6 +135,26 @@ final class SocketConnection implements ConnectionInterface
         return $buffer;
     }
 
+    public function readBytesChunked(int $length, int $chunkSize = 8192): \Generator
+    {
+        if ($length < 0) {
+            throw new ImapException('IMAP socket cannot read a negative number of bytes.');
+        }
+
+        $remaining = $length;
+
+        while ($remaining > 0) {
+            $chunk = fread($this->stream(), min($chunkSize, $remaining));
+
+            if ($chunk === false || $chunk === '') {
+                throw new ImapException('Failed to read literal payload from IMAP socket.');
+            }
+
+            $remaining -= strlen($chunk);
+            yield $chunk;
+        }
+    }
+
     public function upgradeToTls(): void
     {
         $stream = $this->stream();