feat: implement content cache

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

lib/Service/Cache/MessageIngestor.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXM\ProviderImap\Service\Cache;
+
+use KTXM\ProviderImap\Providers\EntityResource;
+use KTXM\ProviderImap\Stores\MessageFileStore;
+use KTXM\ProviderImap\Stores\MessageStore;
+
+/**
+ * Writes fetched messages into the cache (content store + meta store).
+ *
+ * Shared by harmonization and by the cold list path, which caches the page it streams.
+ */
+class MessageIngestor
+{
+    /** Maximum octets of BODY[TEXT] fetched per message for the cache; text past it is completed on open */
+    public const BODY_TEXT_LIMIT = 262144; // 256 KB
+
+    public function __construct(
+        private readonly MessageFileStore $fileStore,
+        private readonly MessageStore $messageStore,
+    ) {}
+
+    /**
+     * Cache messages of one mailbox generation.
+     *
+     * The content is written before the meta document, so an interruption leaves at
+     * most an orphaned file, never a meta document without content.
+     *
+     * @return int[] UIDs that were cached
+     */
+    public function ingest(string $tenantId, string $serviceId, int $uidValidity, EntityResource ...$entities): array
+    {
+        $ingested = [];
+
+        foreach ($entities as $entity) {
+            $mailbox = (string) $entity->collection();
+            $uid = (int) $entity->identifier();
+
+            $this->fileStore->write($tenantId, $serviceId, $mailbox, $uidValidity, $uid, $entity->toCacheContent());
+            $this->messageStore->upsert($tenantId, $serviceId, $uidValidity, $entity);
+
+            $ingested[] = $uid;
+        }
+
+        return $ingested;
+    }
+}