feat: add CachedService with cached collections and delta

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
2026-10-07 22:02:45 -04:00
parent 4e12d41ee9
commit 852ead324f
10 changed files with 750 additions and 215 deletions
@@ -150,7 +150,7 @@ final class CacheSerializationTest extends TestCase
            ->with(
                ['sid' => 'svc', 'name' => 'INBOX'],
                $this->callback(function (array $update): bool {
-                    $this->assertSame(['tid', 'sid', 'name', 'parent', 'signature', 'properties'], array_keys($update['$set']));
+                    $this->assertSame(['tid', 'sid', 'name', 'parent', 'signature', 'properties', 'listedAt'], array_keys($update['$set']));
                    return true;
                }),
                ['upsert' => true],
@@ -0,0 +1,175 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXT\ProviderImap\Tests\Unit;
+
+use KTXC\Db\DataStore;
+use KTXF\Mail\Collection\CollectionRoles;
+use KTXM\ProviderImap\Client\Mailbox;
+use KTXM\ProviderImap\Providers\CachedService;
+use KTXM\ProviderImap\Providers\MessageProperties;
+use KTXM\ProviderImap\Service\Cache\HarmonizationService;
+use KTXM\ProviderImap\Service\Cache\MessageDeltaService;
+use KTXM\ProviderImap\Service\Cache\MessageIngestor;
+use KTXM\ProviderImap\Service\Live\LiveMailService;
+use KTXF\Resource\Identifier\EntityIdentifier;
+use KTXT\ProviderImap\Tests\Support\FakeLiveMailService;
+use KTXT\ProviderImap\Tests\Support\FakeMailboxStore;
+use KTXT\ProviderImap\Tests\Support\FakeMessageFileStore;
+use KTXT\ProviderImap\Tests\Support\FakeMessageStore;
+use PHPUnit\Framework\TestCase;
+
+final class CachedServiceTest extends TestCase
+{
+    private FakeMailboxStore $mailboxes;
+    private FakeLiveMailService $live;
+    private CachedService $service;
+
+    protected function setUp(): void
+    {
+        $dataStore = $this->createStub(DataStore::class);
+        $this->mailboxes = new FakeMailboxStore($dataStore);
+        $messages = new FakeMessageStore($dataStore);
+        $files = new FakeMessageFileStore('/nonexistent');
+
+        $harmonizer = new HarmonizationService(
+            $this->mailboxes,
+            $messages,
+            $files,
+            new MessageIngestor($files, $messages, $this->mailboxes),
+        );
+
+        $this->service = new CachedServiceTestDouble(
+            $this->mailboxes,
+            $harmonizer,
+            new MessageDeltaService($this->mailboxes, $messages),
+        );
+        $this->service->fromStore(['tid' => 'tenant', 'sid' => 'svc']);
+
+        $this->live = new FakeLiveMailService($this->service);
+        $this->live->uidValidity = 7;
+        $this->live->uidNext = 10;
+        $this->live->mailboxList = [new Mailbox('INBOX', '/', []), new Mailbox('Sent', '/', ['\\Sent'])];
+        $this->service->liveMail = $this->live;
+    }
+
+    public function testCollectionListComesFromTheCacheAfterHarmonizingTheList(): void
+    {
+        $list = $this->service->collectionList(null);
+
+        $this->assertSame(['INBOX', 'Sent'], array_keys($list));
+        $this->assertSame(CollectionRoles::Sent, $list['Sent']->getProperties()->getRole());
+        $this->assertCount(1, $this->listCalls());
+    }
+
+    public function testFreshListIsNotHarmonizedAgain(): void
+    {
+        $this->service->collectionList(null);
+        $this->service->collectionList(null);
+        $this->service->collectionFetch('INBOX');
+
+        $this->assertCount(1, $this->listCalls());
+    }
+
+    public function testStaleListIsHarmonizedAgain(): void
+    {
+        $this->mailboxes->clock = time() - CachedService::FRESHNESS_WINDOW - 1;
+        $this->service->collectionList(null);
+        $this->mailboxes->clock = null;
+
+        $this->live->mailboxList[] = new Mailbox('Archive', '/', []);
+        $list = $this->service->collectionList(null);
+
+        $this->assertSame(['INBOX', 'Sent', 'Archive'], array_keys($list));
+        $this->assertCount(2, $this->listCalls());
+    }
+
+    public function testFilteredListGoesToTheServer(): void
+    {
+        $filter = $this->service->collectionListFilter();
+        $filter->condition('role', CollectionRoles::Sent->value);
+
+        $this->service->collectionList(null, $filter);
+
+        $this->assertSame([['collectionList', [null, $filter]]], $this->live->calls);
+    }
+
+    public function testCollectionSignatureIsTheDeltaSignature(): void
+    {
+        $this->live->flags = [1 => [], 2 => []];
+        $this->service->entityDelta('INBOX', '');
+
+        $this->assertSame('7:2', $this->service->collectionFetch('INBOX')?->signature());
+    }
+
+    public function testCollectionExtantUsesTheCache(): void
+    {
+        $this->assertSame(['INBOX' => true, 'Missing' => false], $this->service->collectionExtant('INBOX', 'Missing'));
+    }
+
+    public function testDeltaHarmonizesWhenStaleOnly(): void
+    {
+        $this->live->flags = [1 => []];
+        $first = $this->service->entityDelta('INBOX', '');
+
+        $this->live->flags = [1 => [], 2 => []];
+        $second = $this->service->entityDelta('INBOX', $first->signature);
+
+        $this->assertSame('7:1', $first->signature);
+        $this->assertSame('7:1', $second->signature, 'fresh mailbox is not harmonized again');
+
+        $this->mailboxes->updateState('svc', 'INBOX', ['harmonizedAt' => time() - CachedService::FRESHNESS_WINDOW]);
+        $third = $this->service->entityDelta('INBOX', $first->signature);
+
+        $this->assertSame('7:2', $third->signature);
+        $this->assertSame(['2'], json_decode(json_encode($third->additions), true));
+    }
+
+    public function testDeltaIsAnsweredFromTheCacheWhenTheServerFails(): void
+    {
+        $this->live->flags = [1 => []];
+        $signature = $this->service->entityDelta('INBOX', '')->signature;
+
+        $this->mailboxes->updateState('svc', 'INBOX', ['harmonizedAt' => 0]);
+        $this->live->uidValidity = null; // harmonization throws
+
+        $this->assertSame($signature, $this->service->entityDelta('INBOX', $signature)->signature);
+    }
+
+    public function testWritesGoThroughTheLiveService(): void
+    {
+        $properties = new MessageProperties([]);
+        $properties->setFlag('seen', true);
+
+        $this->service->entityPatch($properties, new EntityIdentifier('imap', 'svc', 'INBOX', '5'));
+
+        $patches = array_values(array_filter($this->live->calls, static fn (array $call): bool => $call[0] === 'entityPatch'));
+        $this->assertCount(1, $patches);
+        [$collection, $added, , $uids] = $patches[0][1];
+        $this->assertSame('INBOX', $collection);
+        $this->assertContains('seen', $added);
+        $this->assertSame([5], $uids);
+    }
+
+    /**
+     * @return list<array>
+     */
+    private function listCalls(): array
+    {
+        return array_values(array_filter($this->live->calls, static fn (array $call): bool => $call[0] === 'collectionList'));
+    }
+}
+
+/**
+ * CachedService with a replaceable IMAP side.
+ */
+final class CachedServiceTestDouble extends CachedService
+{
+    public ?LiveMailService $liveMail = null;
+
+    protected function liveMail(): LiveMailService
+    {
+        return $this->liveMail;
+    }
+}
@@ -22,6 +22,10 @@ use KTXM\ProviderImap\Service\Live\LiveMailService;
 use KTXM\ProviderImap\Stores\MailboxStore;
 use KTXM\ProviderImap\Stores\MessageFileStore;
 use KTXM\ProviderImap\Stores\MessageStore;
+use KTXT\ProviderImap\Tests\Support\FakeLiveMailService;
+use KTXT\ProviderImap\Tests\Support\FakeMailboxStore;
+use KTXT\ProviderImap\Tests\Support\FakeMessageFileStore;
+use KTXT\ProviderImap\Tests\Support\FakeMessageStore;
 use PHPUnit\Framework\TestCase;

 final class MessageHarmonizationTest extends TestCase
@@ -29,7 +33,7 @@ final class MessageHarmonizationTest extends TestCase
    private FakeMailboxStore $mailboxes;
    private FakeMessageStore $messages;
    private FakeMessageFileStore $files;
-    private MessageHarmonizationLiveStub $live;
+    private FakeLiveMailService $live;
    private HarmonizationService $harmonizer;
    private MessageDeltaService $deltas;

@@ -41,7 +45,7 @@ final class MessageHarmonizationTest extends TestCase
        $this->files = new FakeMessageFileStore('/nonexistent');

        $service = (new LiveService())->fromStore(['tid' => 'tenant', 'sid' => 'svc']);
-        $this->live = new MessageHarmonizationLiveStub($service);
+        $this->live = new FakeLiveMailService($service);
        $this->live->uidValidity = 7;
        $this->live->uidNext = 100;

@@ -270,214 +274,3 @@ final class MessageHarmonizationTest extends TestCase
    }
 }

-final class MessageHarmonizationLiveStub extends LiveMailService
-{
-    public ?int $uidValidity = null;
-    public ?int $uidNext = null;
-    /** @var array<int, list<string>> */
-    public array $flags = [];
-    /** @var int[] */
-    public array $unfetchable = [];
-    public array $fetchBatches = [];
-    public int $selects = 0;
-    public ?int $bodyTextLimit = null;
-    /** @var Mailbox[] */
-    public array $mailboxList = [];
-    /** @var string[] */
-    public array $failing = [];
-
-    public function collectionList(?string $location = null, ?IFilter $filter = null, ?ISort $sort = null): array
-    {
-        $list = [];
-        foreach ($this->mailboxList as $mailbox) {
-            $list[$mailbox->name()] = (new CollectionResource('imap', 'svc'))->fromImap($mailbox);
-        }
-        return $list;
-    }
-
-    public function mailboxFetch(string $identifier): ?Mailbox
-    {
-        if (in_array($identifier, $this->failing, true)) {
-            return null;
-        }
-        $this->selects++;
-        return new Mailbox($identifier, '/', [], count($this->flags), 0, $this->uidValidity, 0, [], true, $this->uidNext);
-    }
-
-    public function entityFlags(string $collection): Generator
-    {
-        yield from $this->flags;
-    }
-
-    public function messageFetch(string $collection, ?FetchOptions $options = null, int ...$uids): Generator
-    {
-        $this->fetchBatches[] = $uids;
-        if (preg_match('/BODY\.PEEK\[TEXT\]<0\.(\d+)>/', (string) $options?->toCommand(), $matches) === 1) {
-            $this->bodyTextLimit = (int) $matches[1];
-        }
-
-        foreach ($uids as $uid) {
-            if (in_array($uid, $this->unfetchable, true)) {
-                continue;
-            }
-            $flags = implode(' ', $this->flags[$uid] ?? []);
-            yield $uid => FetchMessageParser::parse("* {$uid} FETCH (UID {$uid} FLAGS ({$flags}))");
-        }
-    }
-}
-
-final class FakeMailboxStore extends MailboxStore
-{
-    /** @var array<string, array> */
-    public array $documents = [];
-    public ?string $lockOwner = null;
-
-    public function upsert(string $tenantId, string $serviceId, CollectionResource $collection): void
-    {
-        $name = (string) $collection->identifier();
-        $this->documents[$name] = [
-            ...($this->documents[$name] ?? self::STATE_DEFAULTS),
-            ...$collection->toCacheMeta(),
-        ];
-    }
-
-    public function fetch(string $serviceId, string $name): ?array
-    {
-        return $this->documents[$name] ?? null;
-    }
-
-    public function list(string $serviceId): array
-    {
-        return $this->documents;
-    }
-
-    public function updateState(string $serviceId, string $name, array $state): void
-    {
-        $this->documents[$name] = array_replace($this->documents[$name], array_intersect_key($state, self::STATE_DEFAULTS));
-    }
-
-    public function acquireLock(string $serviceId, string $name, string $owner, int $ttl): bool
-    {
-        if ($this->lockOwner !== null && $this->lockOwner !== $owner) {
-            return false;
-        }
-        $this->lockOwner = $owner;
-        return true;
-    }
-
-    public function releaseLock(string $serviceId, string $name, string $owner): void
-    {
-        if ($this->lockOwner === $owner) {
-            $this->lockOwner = null;
-        }
-    }
-
-    public function reserveSequence(string $serviceId, string $name, int $count = 1): int
-    {
-        $this->documents[$name]['changeSeq'] += $count;
-        return $this->documents[$name]['changeSeq'] - $count + 1;
-    }
-
-    public function state(string $serviceId, string $name): array
-    {
-        return array_replace(self::STATE_DEFAULTS, array_intersect_key($this->documents[$name] ?? [], self::STATE_DEFAULTS));
-    }
-}
-
-final class FakeMessageStore extends MessageStore
-{
-    /** @var array<int, array<int, array{flags: list<string>, addedSeq: int, modSeq: int, removedSeq: ?int}>> by UIDVALIDITY and UID */
-    private array $documents = [];
-
-    public function upsert(string $tenantId, string $serviceId, int $uidValidity, EntityResource $entity, int $seq): void
-    {
-        $meta = $entity->toCacheMeta();
-        $existing = $this->documents[$uidValidity][$meta['uid']] ?? null;
-        $this->documents[$uidValidity][$meta['uid']] = [
-            'flags' => $meta['flags'],
-            'addedSeq' => $existing['addedSeq'] ?? $seq,
-            'modSeq' => $seq,
-            'removedSeq' => null,
-        ];
-        ksort($this->documents[$uidValidity]);
-    }
-
-    public function flags(string $serviceId, string $mailbox, int $uidValidity): array
-    {
-        $flags = [];
-        foreach ($this->documents[$uidValidity] ?? [] as $uid => $document) {
-            if ($document['removedSeq'] === null) {
-                $flags[$uid] = $document['flags'];
-            }
-        }
-        return $flags;
-    }
-
-    public function updateFlags(string $serviceId, string $mailbox, int $uidValidity, int $uid, array $flags, int $seq): void
-    {
-        $this->documents[$uidValidity][$uid]['flags'] = array_values($flags);
-        $this->documents[$uidValidity][$uid]['modSeq'] = $seq;
-    }
-
-    public function tombstone(string $serviceId, string $mailbox, int $uidValidity, int $seq, int ...$uids): void
-    {
-        foreach ($uids as $uid) {
-            $this->documents[$uidValidity][$uid]['removedSeq'] = $seq;
-            $this->documents[$uidValidity][$uid]['modSeq'] = $seq;
-            $this->documents[$uidValidity][$uid]['flags'] = [];
-        }
-    }
-
-    public function changes(string $serviceId, string $mailbox, int $uidValidity, int $since): array
-    {
-        $changes = ['additions' => [], 'modifications' => [], 'deletions' => []];
-        foreach ($this->documents[$uidValidity] ?? [] as $uid => $document) {
-            if ($document['removedSeq'] !== null) {
-                if ($document['addedSeq'] <= $since && $document['removedSeq'] > $since) {
-                    $changes['deletions'][] = $uid;
-                }
-            } elseif ($document['addedSeq'] > $since) {
-                $changes['additions'][] = $uid;
-            } elseif ($document['modSeq'] > $since) {
-                $changes['modifications'][] = $uid;
-            }
-        }
-        return $changes;
-    }
-
-    public function deleteByMailbox(string $serviceId, string $mailbox): void
-    {
-        $this->documents = [];
-    }
-}
-
-final class FakeMessageFileStore extends MessageFileStore
-{
-    /** @var array<int, array<int, array>> content by UIDVALIDITY and UID */
-    private array $files = [];
-
-    public function write(string $tenantId, string $serviceId, string $mailbox, int $uidValidity, int $uid, array $content): void
-    {
-        $this->files[$uidValidity][$uid] = $content;
-    }
-
-    public function delete(string $tenantId, string $serviceId, string $mailbox, int $uidValidity, int ...$uids): void
-    {
-        foreach ($uids as $uid) {
-            unset($this->files[$uidValidity][$uid]);
-        }
-    }
-
-    public function deleteByMailbox(string $tenantId, string $serviceId, string $mailbox): void
-    {
-        $this->files = [];
-    }
-
-    /** @return int[] */
-    public function uids(int $uidValidity): array
-    {
-        $uids = array_keys($this->files[$uidValidity] ?? []);
-        sort($uids);
-        return $uids;
-    }
-}