feat: implement preview mechanism

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

lib/Manager.php

@@ -5,6 +5,9 @@ declare(strict_types=1);
 namespace KTXM\DocumentsManager;
 
 use InvalidArgumentException;
+use RuntimeException;
+use KTXC\Preview\CachedPreview;
+use KTXC\Preview\PreviewManager;
 use KTXC\Resource\ProviderManager;
 use KTXF\Documents\Collection\CollectionBaseInterface;
 use KTXF\Documents\Collection\CollectionPropertiesMutableInterface;
@@ -18,6 +21,8 @@ use KTXF\Documents\Service\ServiceCollectionMutableInterface;
 use KTXF\Documents\Service\ServiceEntityMutableInterface;
 use KTXF\Documents\Service\ServiceMutableInterface;
 use KTXF\Resource\Filter\IFilter;
+use KTXF\Preview\PreviewSource;
+use KTXF\Resource\BinaryResource;
 use KTXF\Resource\Identifier\CollectionIdentifier;
 use KTXF\Resource\Identifier\EntityIdentifier;
 use KTXF\Resource\Identifier\ResourceIdentifiers;
@@ -37,6 +42,7 @@ class Manager {
     public function __construct(
         private LoggerInterface $logger,
         private ProviderManager $providerManager,
+        private PreviewManager $previewManager,
     ) { }
 
     /**
@@ -1342,4 +1348,62 @@ class Manager {
         return $this->serviceForWrite($tenantId, $userId, $target)->entityWriteChunk($target, $offset, $data);
     }
 
+    /**
+     * Resolve an authorized entity and lazily generate or retrieve its preview.
+     */
+    public function entityPreview(string $tenantId, string $userId, EntityIdentifier $target, string $variant = 'popover'): ?CachedPreview {
+        $entities = $this->entityFetchBulk($tenantId, $userId, $target);
+        $entity = $entities[$target->entity()] ?? reset($entities);
+        if (!$entity instanceof EntityBaseInterface) {
+            return null;
+        }
+
+        $properties = $entity->getProperties();
+        $mimeType = $properties->getMime();
+        $size = $properties->size();
+        $signature = $entity->signature() ?? hash('sha256', implode('|', [
+            (string) $target,
+            $entity->modified()?->format('U.u') ?? '',
+            (string) $size,
+            $mimeType,
+        ]));
+
+        $source = new PreviewSource(
+            sourceType: 'document',
+            identity: (string) $target,
+            signature: $signature,
+            mimeType: $mimeType,
+            size: $size,
+            resourceFactory: function () use ($tenantId, $userId, $target, $properties, $mimeType): BinaryResource {
+                $stream = $this->entityReadStream($tenantId, $userId, $target);
+                if (!is_resource($stream)) {
+                    throw new RuntimeException('Document content is unavailable');
+                }
+
+                return new BinaryResource(
+                    $properties->getLabel(),
+                    $mimeType,
+                    (static function () use ($stream): \Generator {
+                        try {
+                            while (!feof($stream)) {
+                                $chunk = fread($stream, 65536);
+                                if ($chunk === false) {
+                                    throw new RuntimeException('Failed to read document content');
+                                }
+                                if ($chunk !== '') {
+                                    yield $chunk;
+                                }
+                            }
+                        } finally {
+                            fclose($stream);
+                        }
+                    })(),
+                );
+            },
+        );
+
+        return $this->previewManager->fetch($tenantId, $source, $variant);
+    }
+
+
 }