feat: implement attachement preview

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

lib/Controllers/DefaultController.php

@@ -180,6 +180,7 @@ class DefaultController extends ControllerAbstract {
             'entity.copy' => throw new InvalidArgumentException('Operation not implemented: ' . $operation),
             'entity.submit' => $this->entitySubmit($tenantId, $userId, $data),
             'entity.download' => $this->entityDownload($tenantId, $userId, $data),
+            'entity.preview' => $this->entityPreview($tenantId, $userId, $data),
             'entity.blobs' => $this->entityBlobs($tenantId, $userId, $data),
             
             default => throw new InvalidArgumentException(self::ERR_INVALID_OPERATION . $operation)
@@ -968,4 +969,39 @@ class DefaultController extends ControllerAbstract {
         return $results;
     }
 
+    private function entityPreview(string $tenantId, string $userId, array $data): Response {
+        if (!isset($data['target']) || !is_string($data['target'])) {
+            throw new InvalidArgumentException(self::ERR_MISSING_TARGET);
+        }
+        if (!isset($data['part']) || !is_array($data['part'])) {
+            throw new InvalidArgumentException('Attachment preview requires a part');
+        }
+
+        $target = ResourceIdentifier::fromString($data['target']);
+        if (!$target instanceof EntityIdentifier) {
+            throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
+        }
+        $preview = $this->manager->entityPreview(
+            $tenantId,
+            $userId,
+            $target,
+            $data['part'],
+            isset($data['variant']) && is_string($data['variant']) ? $data['variant'] : 'popover',
+        );
+        if ($preview === null) {
+            return new JsonResponse([
+                'status' => 'error',
+                'error' => ['code' => 404, 'message' => 'Preview unavailable'],
+            ], Response::HTTP_NOT_FOUND);
+        }
+
+        return new StreamedResponse($preview->result->resource->stream(), Response::HTTP_OK, [
+            'Content-Type' => $preview->result->resource->mimeType(),
+            'Content-Length' => (string) $preview->blob->size,
+            'ETag' => '"' . trim($preview->blob->etag, '"') . '"',
+            'Cache-Control' => 'private, max-age=3600',
+            'X-Content-Type-Options' => 'nosniff',
+        ]);
+    }
+
 }

lib/Manager.php

@@ -5,7 +5,10 @@ declare(strict_types=1);
 namespace KTXM\MailManager;
 
 use InvalidArgumentException;
+use KTXC\Preview\CachedPreview;
+use KTXC\Preview\PreviewManager;
 use KTXC\Resource\ProviderManager;
+use KTXF\Preview\PreviewSource;
 use KTXF\Mail\Collection\CollectionBaseInterface;
 use KTXF\Mail\Collection\CollectionPropertiesMutableInterface;
 use KTXF\Mail\Collection\ICollectionBase;
@@ -47,6 +50,7 @@ class Manager {
     public function __construct(
         private LoggerInterface $logger,
         private ProviderManager $providerManager,
+        private PreviewManager $previewManager,
     ) { }
 
     /**
@@ -934,13 +938,6 @@ class Manager {
         }
     }
 
-    public function entityDownload(string $tenantId, string $userId, EntityIdentifier $targetEntity, array|null $targetPart): BinaryResource {
-        // retrieve service
-        $service = $this->serviceFetch($tenantId, $userId, $targetEntity->provider(), $targetEntity->service());
-        // download entity
-        return $service->entityDownload($targetEntity, $targetPart);
-    }
-
     /**
      * Check if messages exist
      *
@@ -1352,4 +1349,49 @@ class Manager {
         return $service->entitySubmit($sender, $source, $message);
     }
 
+    public function entityDownload(string $tenantId, string $userId, EntityIdentifier $targetEntity, array|null $targetPart): BinaryResource {
+        // retrieve service
+        $service = $this->serviceFetch($tenantId, $userId, $targetEntity->provider(), $targetEntity->service());
+        // download entity
+        return $service->entityDownload($targetEntity, $targetPart);
+    }
+
+    /**
+     * Resolve an authorized attachment and lazily generate or retrieve its preview.
+     */
+    public function entityPreview(string $tenantId, string $userId, EntityIdentifier $targetEntity, array $part, string $variant = 'popover'): ?CachedPreview {
+        $mimeType = $part['type'] ?? null;
+        $size = $part['size'] ?? null;
+        if (!is_string($mimeType) || ($size !== null && !is_int($size))) {
+            throw new InvalidArgumentException('Attachment preview requires a MIME type and optional integer size');
+        }
+
+        $selector = array_filter([
+            'blobId' => $part['blobId'] ?? null,
+            'partId' => $part['partId'] ?? null,
+            'cid' => $part['cid'] ?? null,
+        ], static fn(mixed $value): bool => is_string($value) && $value !== '');
+        if ($selector === []) {
+            throw new InvalidArgumentException('Attachment preview requires a blob, part, or content identifier');
+        }
+
+        return $this->previewManager->fetch($tenantId, new PreviewSource(
+            sourceType: 'mail-attachment',
+            identity: (string) $targetEntity,
+            // Attachments are immutable once delivered, so there is no revision to track;
+            // existence and access are enforced by entityDownload() (via serviceFetch) below,
+            // which only runs on a cache miss.
+            signature: 'immutable',
+            mimeType: $mimeType,
+            size: $size,
+            resourceFactory: fn(): BinaryResource => $this->entityDownload(
+                $tenantId,
+                $userId,
+                $targetEntity,
+                $selector,
+            ),
+            selector: hash('sha256', json_encode($selector, JSON_THROW_ON_ERROR)),
+        ), $variant);
+    }
+
 }