Add partial body fetching and chunked attachment streams

Author: stevebauman

readme.md

@@ -16,3 +16,35 @@
 <p align="center">
   <a href="https://imapengine.com">View Documentation</a>
 </p>
+
+### Partial body fetching
+
+Fetch a byte range of a message section without downloading the whole section:
+
+```php
+$messages = $folder->messages()
+    ->with(MessageData::text()->partial(0, 4096)->peek())
+    ->get();
+
+$preview = $messages->first()->data()->get('BODY[TEXT]<0>');
+
+$chunk = $message->bodyPart('2', offset: 65536, length: 65536);
+```
+
+Offsets are zero-based and refer to transfer-encoded bytes. The server may return
+fewer bytes at the end of a section, or an empty string beyond its end. A missing
+message or section returns `null`. Partial data does not replace the complete body.
+
+Attachments obtained through `attachments(fetch: true)` download in 64 KiB chunks
+as their streams are read. Base64 and quoted-printable decoding continues across
+chunk boundaries. Decoded content is cached in a temporary stream that spills to
+disk beyond 2 MiB, allowing seeks and repeated reads without fetching again.
+
+```php
+$attachment = $message->attachments(fetch: true)[0];
+$attachment->save('/path/to/attachment.pdf');
+```
+
+`save()` copies stream chunks directly to the destination. Calling `contents()` or
+casting a stream to a string still allocates the requested contents in memory.
+The decoded stream size is unknown (`null`) until the section has been fully read.

src/Attachment.php

@@ -2,6 +2,7 @@
 
 namespace DirectoryTree\ImapEngine;
 
+use DirectoryTree\ImapEngine\Support\LazyBodyPartStream;
 use GuzzleHttp\Psr7\Utils;
 use Illuminate\Contracts\Support\Arrayable;
 use JsonSerializable;
@@ -63,7 +64,7 @@ public static function lazy(Message $message): array
                 $part->id(),
                 $part->contentType(),
                 $part->disposition()?->type()?->value,
-                new Support\LazyBodyPartStream($message, $part),
+                new LazyBodyPartStream($message, $part),
             );
         }
 
@@ -137,7 +138,23 @@ public function contentStream(): StreamInterface
      */
     public function save(string $path): false|int
     {
-        return file_put_contents($path, $this->contents());
+        if ($this->contentStream->isSeekable()) {
+            $this->contentStream->rewind();
+        }
+
+        if (! $resource = fopen($path, 'wb')) {
+            return false;
+        }
+
+        $destination = Utils::streamFor($resource);
+
+        try {
+            Utils::copyToStream($this->contentStream, $destination);
+
+            return $destination->tell();
+        } finally {
+            $destination->close();
+        }
     }
 
     /**

src/FileMessage.php

@@ -92,7 +92,7 @@ public function hasBodyStructure(): bool
     /**
      * {@inheritDoc}
      */
-    public function bodyPart(string $partNumber, bool $peek = true): ?string
+    public function bodyPart(string $partNumber, bool $peek = true, int $offset = 0, ?int $length = null): ?string
     {
         throw new BadMethodCallException('FileMessage does not support fetching body parts');
     }

src/Message.php

@@ -8,8 +8,10 @@
 use DirectoryTree\ImapEngine\Connection\Responses\Data\ListData;
 use DirectoryTree\ImapEngine\Connection\Responses\MessageResponseParser;
 use DirectoryTree\ImapEngine\Exceptions\ImapCapabilityException;
+use DirectoryTree\ImapEngine\Support\BodyPartDecoder;
 use DirectoryTree\ImapEngine\Support\Str;
 use Illuminate\Contracts\Support\Arrayable;
+use InvalidArgumentException;
 use JsonSerializable;
 use ZBateson\MailMimeParser\Header\DateHeader;
 use ZBateson\MailMimeParser\Header\HeaderConsts;
@@ -398,7 +400,7 @@ public function text(bool $fetch = false): ?string
     {
         if ($fetch && ! $this->hasBody()) {
             if ($part = $this->bodyStructure(fetch: true)?->text()) {
-                return Support\BodyPartDecoder::text($part, $this->bodyPart($part->partNumber()));
+                return BodyPartDecoder::text($part, $this->bodyPart($part->partNumber()));
             }
         }
 
@@ -416,7 +418,7 @@ public function html(bool $fetch = false): ?string
     {
         if ($fetch && ! $this->hasBody()) {
             if ($part = $this->bodyStructure(fetch: true)?->html()) {
-                return Support\BodyPartDecoder::text($part, $this->bodyPart($part->partNumber()));
+                return BodyPartDecoder::text($part, $this->bodyPart($part->partNumber()));
             }
         }
 
@@ -466,25 +468,39 @@ public function attachmentCount(): int
     }
 
     /**
-     * Fetch a specific body part by part number.
+     * Fetch a body section, optionally limited to a transfer-encoded byte range.
      */
-    public function bodyPart(string $partNumber, bool $peek = true): ?string
+    public function bodyPart(string $partNumber, bool $peek = true, int $offset = 0, ?int $length = null): ?string
     {
-        $key = "BODY[$partNumber]";
+        $item = MessageData::section($partNumber);
 
-        if ($peek && $this->data->has($key)) {
+        if ($length !== null) {
+            $item = $item->partial($offset, $length);
+        } elseif ($offset !== 0) {
+            throw new InvalidArgumentException('A partial fetch requires a length.');
+        }
+
+        $key = $item->key();
+
+        if ($length === null && $peek && $this->data->has($key)) {
             return $this->data->get($key);
         }
 
+        if ($length !== null) {
+            $this->folder->select();
+        }
+
         $response = $this->folder->mailbox()
             ->connection()
-            ->fetch($this->uid(), $peek ? "BODY.PEEK[$partNumber]" : "BODY[$partNumber]");
+            ->fetch($this->uid(), ($peek ? $item->peek() : $item)->toImap());
 
         if (! $data = $response->messages()[0] ?? null) {
             return null;
         }
 
-        $this->data = $this->data->merge($data);
+        if ($length === null) {
+            $this->data = $this->data->merge($data);
+        }
 
         return $data->get($key);
     }

src/MessageData/Body.php

@@ -2,8 +2,36 @@
 
 namespace DirectoryTree\ImapEngine\MessageData;
 
+use InvalidArgumentException;
+
 class Body implements FetchItemInterface
 {
+    /**
+     * The zero-based offset in the transfer-encoded section, or null for a full fetch.
+     */
+    protected ?int $offset = null;
+
+    /**
+     * The maximum number of transfer-encoded bytes to fetch.
+     */
+    protected ?int $length = null;
+
+    /**
+     * Fetch a byte range of the transfer-encoded section.
+     */
+    public function partial(int $offset, int $length): static
+    {
+        if ($offset < 0 || $length < 1) {
+            throw new InvalidArgumentException('Partial fetches require a non-negative offset and a positive length.');
+        }
+
+        $item = clone $this;
+        $item->offset = $offset;
+        $item->length = $length;
+
+        return $item;
+    }
+
     /**
      * Constructor.
      */
@@ -52,7 +80,7 @@ public function peek(): static
      */
     public function key(): string
     {
-        return "BODY[{$this->section}]";
+        return "BODY[{$this->section}]".(is_null($this->offset) ? '' : "<{$this->offset}>");
     }
 
     /**
@@ -62,6 +90,6 @@ public function toImap(): string
     {
         $item = $this->peek ? 'BODY.PEEK' : 'BODY';
 
-        return "{$item}[{$this->section}]";
+        return "{$item}[{$this->section}]".(is_null($this->offset) ? '' : "<{$this->offset}.{$this->length}>");
     }
 }

src/MessageInterface.php

@@ -143,9 +143,9 @@ public function bodyStructure(): ?BodyStructureCollection;
     public function hasBodyStructure(): bool;
 
     /**
-     * Fetch a specific body part by part number.
+     * Fetch a body section, optionally limited to a transfer-encoded byte range.
      */
-    public function bodyPart(string $partNumber, bool $peek = true): ?string;
+    public function bodyPart(string $partNumber, bool $peek = true, int $offset = 0, ?int $length = null): ?string;
 
     /**
      * Determine if the message is the same as another message.