Merge pull request #2 from mittwald/test/dovecot-quota-integration

Integration tests: real-Dovecot OVERQUOTA + preflight quota

Author: Hermsi1337

AGENTS.md

@@ -83,7 +83,8 @@ future worker mode — must use an out-of-session store (file, DB, Roundcube cac
 │   │   └── FakeImapClient.php                # in-memory RoundcubeImapSyncClient for unit tests
 │   └── Integration/
 │       ├── bootstrap.php
-│       ├── DovecotContainer.php              # testcontainers-php wrapper for Dovecot
+│       ├── DovecotContainer.php              # testcontainers-php wrapper for Dovecot (optional quota plugin)
+│       ├── PreflightAndQuotaIntegrationTest.php  # real-Dovecot OVERQUOTA + preflight quota coverage
 │       └── SyncEngineIntegrationTest.php     # real-IMAP sync against two Dovecot containers
 ├── phpunit.xml.dist                          # unit suite (excludes tests/Integration)
 ├── phpunit.integration.xml.dist              # integration suite (Docker required)

lib/RoundcubeImapSyncClient.php

@@ -185,7 +185,8 @@ public function appendMessage(string $folder, string $rawMessage, array $flags,
         $result = $this->imap->append($folder, $message, $flags, $internalDate, false);
         if (!$result && $this->imap->error) {
             $errorMessage = $this->getErrorMessage("Could not append message to {$folder}.");
-            if (stripos($errorMessage, '[OVERQUOTA]') !== false) {
+            $resultCode = is_string($this->imap->resultcode ?? null) ? $this->imap->resultcode : null;
+            if (self::isQuotaErrorResponse($resultCode, $this->imap->error)) {
                 throw new RoundcubeImapSyncQuotaExceededException($errorMessage);
             }
 
@@ -195,6 +196,47 @@ public function appendMessage(string $folder, string $rawMessage, array $flags,
         return $result;
     }
 
+    /**
+     * Decide whether an IMAP NO/BAD response signals "destination mailbox is over quota".
+     *
+     * Three signals, any one of which is sufficient:
+     *
+     * 1. RFC 5530 / RFC 9208 IMAP response code OVERQUOTA — what stock Dovecot
+     *    >= 2.2.30 returns. rcube_imap_generic extracts response codes into
+     *    `resultcode` and removes them from the human error text, which is
+     *    why we cannot just substring-match the error.
+     * 2. RFC 3463 enhanced status code "5.2.2" ("Mailbox full") in the error
+     *    text. Operators with a custom `quota_exceeded_message` (e.g. the
+     *    Mittwald default) replace the standard response code with a sentence
+     *    keyed on 5.2.2 — we want to catch those too. Bounded with whitespace
+     *    so we don't false-positive on IP addresses or unrelated dotted-number
+     *    fragments.
+     * 3. Substring match on "OVERQUOTA" in the error text — defensive catch
+     *    for setups where the tag survives into the human message but somehow
+     *    not as a response code.
+     */
+    public static function isQuotaErrorResponse(?string $resultCode, ?string $errorText): bool
+    {
+        if ($resultCode !== null && strcasecmp($resultCode, 'OVERQUOTA') === 0) {
+            return true;
+        }
+
+        $error = (string) $errorText;
+        if ($error === '') {
+            return false;
+        }
+
+        if (preg_match('/(?:^|\s)5\.2\.2(?:\s|$)/', $error) === 1) {
+            return true;
+        }
+
+        if (stripos($error, 'OVERQUOTA') !== false) {
+            return true;
+        }
+
+        return false;
+    }
+
     private function normalizeMessageId(?string $messageId): ?string
     {
         $messageId = trim((string) $messageId);

tests/ImapSyncClientTest.php

@@ -0,0 +1,60 @@
+<?php
+
+use PHPUnit\Framework\TestCase;
+
+final class ImapSyncClientTest extends TestCase
+{
+    public function testOverquotaResultCodeIsQuotaError(): void
+    {
+        self::assertTrue(
+            RoundcubeImapSyncGenericClient::isQuotaErrorResponse('OVERQUOTA', 'APPEND: Quota exceeded (mailbox for user is full).'),
+        );
+    }
+
+    public function testOverquotaResultCodeIsDetectedCaseInsensitively(): void
+    {
+        self::assertTrue(
+            RoundcubeImapSyncGenericClient::isQuotaErrorResponse('overquota', 'whatever'),
+        );
+    }
+
+    public function testEnhancedStatusCode522IsQuotaError(): void
+    {
+        $mittwaldStyleError = '552 5.2.2 No space left in mailbox / Der Speicherplatz des Postfachs ist vollstaendig belegt';
+
+        self::assertTrue(
+            RoundcubeImapSyncGenericClient::isQuotaErrorResponse(null, $mittwaldStyleError),
+        );
+    }
+
+    public function testOverquotaSubstringIsQuotaError(): void
+    {
+        self::assertTrue(
+            RoundcubeImapSyncGenericClient::isQuotaErrorResponse(null, 'APPEND: [OVERQUOTA] Mailbox is over quota'),
+        );
+    }
+
+    public function testUnrelatedErrorIsNotQuotaError(): void
+    {
+        self::assertFalse(
+            RoundcubeImapSyncGenericClient::isQuotaErrorResponse(null, 'APPEND: Could not write to disk'),
+        );
+        self::assertFalse(
+            RoundcubeImapSyncGenericClient::isQuotaErrorResponse('TRYCREATE', 'Mailbox does not exist'),
+        );
+    }
+
+    public function testEmptyErrorWithNoResultCodeIsNotQuotaError(): void
+    {
+        self::assertFalse(RoundcubeImapSyncGenericClient::isQuotaErrorResponse(null, null));
+        self::assertFalse(RoundcubeImapSyncGenericClient::isQuotaErrorResponse(null, ''));
+    }
+
+    public function testDottedNumberSubstringDoesNotFalsePositive(): void
+    {
+        // 5.2.2 inside a larger token (e.g. an IP fragment) must not trigger.
+        self::assertFalse(
+            RoundcubeImapSyncGenericClient::isQuotaErrorResponse(null, 'APPEND: rejected by host 10.5.2.21'),
+        );
+    }
+}

tests/Integration/DovecotContainer.php

@@ -12,11 +12,27 @@ class DovecotContainer
 
     private ?StartedGenericContainer $container = null;
     private ?string $configDirectory = null;
+    private ?int $quotaKilobytes = null;
+    private ?string $quotaExceededMessage = null;
 
     public function __construct(private readonly string $imageTag = 'dovecot/dovecot:latest-root')
     {
     }
 
+    public function withQuotaKilobytes(int $kilobytes): self
+    {
+        $this->quotaKilobytes = $kilobytes;
+
+        return $this;
+    }
+
+    public function withQuotaExceededMessage(string $message): self
+    {
+        $this->quotaExceededMessage = $message;
+
+        return $this;
+    }
+
     public function start(): self
     {
         if ($this->container !== null) {
@@ -138,6 +154,52 @@ private function createConfigDirectory(): string
             throw new RuntimeException('Could not write Dovecot auth config.');
         }
 
+        if ($this->quotaKilobytes !== null) {
+            // Enable the quota plugin and set a storage limit, then let
+            // Dovecot's defaults handle the IMAP response. Since Dovecot
+            // 2.2.30, an APPEND that exceeds quota carries an [OVERQUOTA]
+            // response code (RFC 9208) automatically — we want to test
+            // against that real-world wording, not against a forced one.
+            $quotaConfig = strtr(
+                <<<'DOVECOT'
+mail_plugins {
+  quota = yes
+}
+
+protocol imap {
+  mail_plugins {
+    quota = yes
+    imap_quota = yes
+  }
+}
+
+namespace inbox {
+  inbox = yes
+}
+
+quota_storage_size = %KB%K
+
+quota "User quota" {
+}
+DOVECOT,
+                ['%KB%' => (string) $this->quotaKilobytes],
+            );
+
+            if ($this->quotaExceededMessage !== null) {
+                // Operators sometimes replace the standard [OVERQUOTA] response
+                // with a custom 5.2.2-style sentence (e.g. the Mittwald default).
+                // This option lets a test exercise that variant against real
+                // Dovecot. Escape embedded double-quotes so the value reaches
+                // Dovecot intact.
+                $escaped = str_replace('"', '\\"', $this->quotaExceededMessage);
+                $quotaConfig .= "\nquota_exceeded_message = \"{$escaped}\"\n";
+            }
+
+            if (file_put_contents($configDirectory . '/quota.conf', $quotaConfig) === false) {
+                throw new RuntimeException('Could not write Dovecot quota config.');
+            }
+        }
+
         return $configDirectory;
     }