feat: harmonize mailbox list and track harmonization state

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

lib/Stores/MailboxStore.php

@@ -23,6 +23,16 @@ class MailboxStore
 {
     protected const COLLECTION_NAME = 'provider_imap_mail_mailboxes';
 
+    /** Harmonization state fields and their defaults for a mailbox that was never harmonized */
+    public const STATE_DEFAULTS = [
+        'uidValidity'           => null,
+        'uidNext'               => null,
+        'highestModSeq'         => null,
+        'changeSeq'             => 0,
+        'harmonizedAt'          => null,
+        'harmonizationComplete' => false,
+    ];
+
     public function __construct(
         protected readonly DataStore $dataStore,
     ) {}
@@ -53,7 +63,8 @@ class MailboxStore
     /**
      * Insert or update the mailbox fields of a document.
      *
-     * Harmonization state on the same document is left untouched.
+     * Harmonization state on an existing document is left untouched; a new document
+     * starts with the default (never harmonized) state.
      */
     public function upsert(string $tenantId, string $serviceId, CollectionResource $collection): void
     {
@@ -61,7 +72,10 @@ class MailboxStore
 
         $this->dataStore->selectCollection(self::COLLECTION_NAME)->updateOne(
             ['sid' => $serviceId, 'name' => $document['name']],
-            ['$set' => ['tid' => $tenantId, 'sid' => $serviceId, ...$document]],
+            [
+                '$set' => ['tid' => $tenantId, 'sid' => $serviceId, ...$document],
+                '$setOnInsert' => self::STATE_DEFAULTS,
+            ],
             ['upsert' => true],
         );
     }
@@ -93,6 +107,75 @@ class MailboxStore
         return $list;
     }
 
+    // ── Harmonization state ──────────────────────────────────────────────────
+
+    /**
+     * Harmonization state of a mailbox; defaults when the mailbox is not cached.
+     *
+     * @return array{uidValidity: ?int, uidNext: ?int, highestModSeq: ?int, changeSeq: int, harmonizedAt: ?int, harmonizationComplete: bool}
+     */
+    public function state(string $serviceId, string $name): array
+    {
+        $document = $this->fetch($serviceId, $name) ?? [];
+
+        return array_replace(self::STATE_DEFAULTS, array_intersect_key($document, self::STATE_DEFAULTS));
+    }
+
+    /**
+     * Update harmonization state fields of a mailbox; keys outside the state are ignored.
+     */
+    public function updateState(string $serviceId, string $name, array $state): void
+    {
+        $state = array_intersect_key($state, self::STATE_DEFAULTS);
+        if ($state === []) {
+            return;
+        }
+
+        $this->dataStore->selectCollection(self::COLLECTION_NAME)->updateOne(
+            ['sid' => $serviceId, 'name' => $name],
+            ['$set' => $state],
+        );
+    }
+
+    /**
+     * Take the harmonization lock of a mailbox when it is free or expired.
+     *
+     * Never waits: returns false when another owner holds a valid lock or the
+     * mailbox is not cached.
+     */
+    public function acquireLock(string $serviceId, string $name, string $owner, int $ttl): bool
+    {
+        $now = time();
+
+        $result = $this->dataStore->selectCollection(self::COLLECTION_NAME)->updateOne(
+            [
+                'sid'  => $serviceId,
+                'name' => $name,
+                '$or'  => [
+                    ['lock' => null],
+                    ['lock.expiresAt' => ['$lte' => $now]],
+                    ['lock.owner' => $owner],
+                ],
+            ],
+            ['$set' => ['lock' => ['owner' => $owner, 'expiresAt' => $now + $ttl]]],
+        );
+
+        return $result->getMatchedCount() === 1;
+    }
+
+    /**
+     * Release the harmonization lock of a mailbox, if still held by the owner.
+     */
+    public function releaseLock(string $serviceId, string $name, string $owner): void
+    {
+        $this->dataStore->selectCollection(self::COLLECTION_NAME)->updateOne(
+            ['sid' => $serviceId, 'name' => $name, 'lock.owner' => $owner],
+            ['$unset' => ['lock' => '']],
+        );
+    }
+
+    // ── Deletion ─────────────────────────────────────────────────────────────
+
     /**
      * Delete the document of a mailbox.
      */