From 59838af3db8ba7de4b176e905a3c0c838ec8b337 Mon Sep 17 00:00:00 2001 From: Sebastian Krupinski Date: Sat, 29 Aug 2026 16:20:52 -0400 Subject: [PATCH] feat: implement attachement preview Signed-off-by: Sebastian Krupinski --- lib/Controllers/DefaultController.php | 36 +++++++++++++++++ lib/Manager.php | 56 +++++++++++++++++++++++---- src/services/entityService.ts | 7 +++- src/services/transceive.ts | 19 +++++++++ src/stores/entitiesStore.ts | 6 +++ src/types/entity.ts | 8 +++- 6 files changed, 123 insertions(+), 9 deletions(-) diff --git a/lib/Controllers/DefaultController.php b/lib/Controllers/DefaultController.php index 51df929..5ce2476 100644 --- a/lib/Controllers/DefaultController.php +++ b/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', + ]); + } + } diff --git a/lib/Manager.php b/lib/Manager.php index 63664d3..c236808 100644 --- a/lib/Manager.php +++ b/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); + } + } diff --git a/src/services/entityService.ts b/src/services/entityService.ts index c5c190d..b66bf9e 100644 --- a/src/services/entityService.ts +++ b/src/services/entityService.ts @@ -2,7 +2,7 @@ * Entity management service */ -import { transceivePost, transceiveStream, transceiveDownload } from './transceive'; +import { transceivePost, transceiveStream, transceiveDownload, transceiveBlob } from './transceive'; import type { EntityFetchRequest, EntityFetchResponse, @@ -28,6 +28,7 @@ import type { EntityPatchResponse, EntityPatchRequest, EntityDownloadRequest, + EntityPreviewRequest, EntityBlobsRequest, EntityBlobsResponse, EntityBlobsWireResponse, @@ -231,6 +232,10 @@ export const entityService = { return transceiveDownload('entity.download', request); }, + async preview(request: EntityPreviewRequest): Promise { + return await transceiveBlob('entity.preview', request); + }, + /** * Fetch one or more message parts (attachments) inline for rendering. * diff --git a/src/services/transceive.ts b/src/services/transceive.ts index 4a795e0..95d6bba 100644 --- a/src/services/transceive.ts +++ b/src/services/transceive.ts @@ -188,6 +188,25 @@ export function transceiveDownload( return { transaction: request.transaction }; } +export async function transceiveBlob(operation: string, data: TRequest): Promise { + const request: ApiRequest = { + version: API_VERSION, + transaction: generateTransactionId(), + operation, + data, + }; + let blob: Blob | null = null; + await fetchWrapper.post(API_URL, request, { + headers: { 'Accept': '*/*' }, + onStream: async (response: Response) => { + blob = await response.blob(); + }, + }); + if (blob === null) throw new Error(`[${operation}] Empty preview response`); + return blob; +} + + function appendHiddenField(form: HTMLFormElement, name: string, value: string): void { const input = document.createElement('input'); input.type = 'hidden'; diff --git a/src/stores/entitiesStore.ts b/src/stores/entitiesStore.ts index 3aa466e..d824830 100644 --- a/src/stores/entitiesStore.ts +++ b/src/stores/entitiesStore.ts @@ -10,6 +10,7 @@ import type { EntityBlobSelector, EntityBlobsResponse, EntityDownloadRequest, + EntityPreviewRequest, EntityTransmitRequest, EntityTransmitResponse, } from '../types/entity' @@ -518,6 +519,10 @@ export const useEntitiesStore = defineStore('mailEntitiesStore', () => { } } + async function preview(request: EntityPreviewRequest): Promise { + return await entityService.preview(request) + } + // Return public API return { // State (readonly) @@ -540,6 +545,7 @@ export const useEntitiesStore = defineStore('mailEntitiesStore', () => { move, transmit, download, + preview, blobs, } }) diff --git a/src/types/entity.ts b/src/types/entity.ts index 0a85f99..0146159 100644 --- a/src/types/entity.ts +++ b/src/types/entity.ts @@ -227,6 +227,12 @@ export interface EntityDownloadRequest { filename?: string | null; } +export interface EntityPreviewRequest { + target: EntityIdentifier; + part: EntityBlobSelector & { type: string; size?: number | null }; + variant?: string; +} + export interface EntityBlobsRequest { target: EntityIdentifier; parts: EntityBlobSelector[]; @@ -246,4 +252,4 @@ export interface EntityBlobsResult extends Omit blob: Blob; } -export interface EntityBlobsResponse extends Array {} \ No newline at end of file +export interface EntityBlobsResponse extends Array {}