Add ImapEngine v2 support and improve mailbox watcher retries

composer.json

@@ -16,8 +16,8 @@
         }
     ],
     "require": {
-        "php": "^8.1",
-        "directorytree/imapengine": "^1.22.3",
+        "php": "^8.2",
+        "directorytree/imapengine": "2.0.x-dev",
         "illuminate/contracts": "^10.0|^11.0|^12.0|^13.0"
     },
     "require-dev": {

config/imap.php

@@ -23,7 +23,7 @@
             'password' => env('IMAP_PASSWORD'),
             'encryption' => env('IMAP_ENCRYPTION', 'ssl'),
             'validate_cert' => env('IMAP_VALIDATE_CERT', true),
-            'authentication' => env('IMAP_AUTHENTICATION', 'plain'),
+            'authentication' => env('IMAP_AUTHENTICATION', 'login'),
             'proxy' => [
                 'socket' => env('IMAP_PROXY_SOCKET'),
                 'username' => env('IMAP_PROXY_USERNAME'),

src/Commands/ConfigureIdleQuery.php

@@ -2,6 +2,7 @@
 
 namespace DirectoryTree\ImapEngine\Laravel\Commands;
 
+use DirectoryTree\ImapEngine\MessageData;
 use DirectoryTree\ImapEngine\MessageQueryInterface;
 
 class ConfigureIdleQuery
@@ -19,15 +20,15 @@ public function __construct(
     public function __invoke(MessageQueryInterface $query): MessageQueryInterface
     {
         if (in_array('flags', $this->with)) {
-            $query->withFlags();
+            $query->with(MessageData::flags());
         }
 
         if (in_array('body', $this->with)) {
-            $query->withBody();
+            $query->with(MessageData::text()->peek());
         }
 
         if (in_array('headers', $this->with)) {
-            $query->withHeaders();
+            $query->with(MessageData::headers()->peek());
         }
 
         return $query;

src/Commands/HandleMailboxEventReceived.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace DirectoryTree\ImapEngine\Laravel\Commands;
+
+use Carbon\CarbonInterface;
+use DirectoryTree\ImapEngine\Idle\Events\EventInterface;
+use DirectoryTree\ImapEngine\Idle\Events\FolderSelected;
+use DirectoryTree\ImapEngine\Laravel\Events\MailboxEventReceived;
+use Illuminate\Support\Facades\Date;
+use Illuminate\Support\Facades\Event;
+
+class HandleMailboxEventReceived
+{
+    /**
+     * Constructor.
+     */
+    public function __construct(
+        protected WatchMailbox $command,
+        protected string $mailbox,
+        protected int &$attempts = 0,
+        protected ?CarbonInterface &$lastReceivedAt = null,
+    ) {}
+
+    /**
+     * Dispatch the original typed mailbox event through Laravel.
+     */
+    public function __invoke(EventInterface $event): void
+    {
+        $this->command->info("Mailbox event received: [{$event->type()}] in [{$event->folder()}]");
+
+        // Selecting the folder after reconnecting must not reset the retry budget.
+        if (! $event instanceof FolderSelected) {
+            $this->attempts = 0;
+
+            $this->lastReceivedAt = Date::now();
+        }
+
+        Event::dispatch(new MailboxEventReceived($event, $this->mailbox));
+    }
+}

src/Commands/WatchMailbox.php

@@ -2,15 +2,18 @@
 
 namespace DirectoryTree\ImapEngine\Laravel\Commands;
 
+use DirectoryTree\ImapEngine\Exceptions\ImapConnectionException;
+use DirectoryTree\ImapEngine\Exceptions\ImapStreamException;
 use DirectoryTree\ImapEngine\FolderInterface;
+use DirectoryTree\ImapEngine\Idle\Events\EventInterface;
 use DirectoryTree\ImapEngine\Laravel\Events\MailboxWatchAttemptsExceeded;
 use DirectoryTree\ImapEngine\Laravel\Facades\Imap;
 use DirectoryTree\ImapEngine\Laravel\Support\LoopInterface;
 use DirectoryTree\ImapEngine\MailboxInterface;
-use Exception;
+use DirectoryTree\ImapEngine\MessageInterface;
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\Event;
-use Illuminate\Support\Str;
+use Illuminate\Support\Sleep;
 use Symfony\Component\Console\Exception\InvalidOptionException;
 
 class WatchMailbox extends Command
@@ -23,67 +26,81 @@ class WatchMailbox extends Command
     protected $signature = 'imap:watch
                             {mailbox : The mailbox to watch}
                             {folder? : The folder to watch}
-                            {--method=idle : The watch method (idle or poll)}
-                            {--with= : Comma-separated list of message parts to fetch}
-                            {--timeout=30 : The timeout in minutes}
-                            {--attempts=5 : Maximum number of retry attempts}
-                            {--debug=false : Enable debug mode}';
+                            {--method=idle : The watch method (idle, poll, or events)}
+                            {--with= : Comma-separated message parts to fetch with idle or poll (flags, body, headers)}
+                            {--timeout=30 : The IDLE renewal interval or polling frequency in seconds}
+                            {--attempts=5 : Maximum connection retries before a message or mailbox update is received}';
 
     /**
      * The console command description.
      *
      * @var string
      */
-    protected $description = 'Watch a mailbox for new messages.';
+    protected $description = 'Watch a mailbox for new messages or mailbox events.';
 
     /**
      * Execute the console command.
      */
     public function handle(LoopInterface $loop): void
     {
-        if (! in_array($method = $this->option('method'), ['idle', 'poll'])) {
-            throw new InvalidOptionException("Invalid method [{$method}]. Valid options are [idle, poll].");
+        if (! in_array($method = $this->option('method'), ['idle', 'poll', 'events'])) {
+            throw new InvalidOptionException("Invalid method [{$method}]. Valid options are [idle, poll, events].");
         }
 
-        $mailbox = Imap::mailbox($name = $this->argument('mailbox'));
+        $timeout = (int) $this->option('timeout');
+
+        $retries = (int) $this->option('attempts');
 
-        $with = explode(',', $this->option('with'));
+        $with = array_filter(
+            array_map('trim', explode(',', $this->option('with'))),
+            filled(...),
+        );
+
+        if ($invalid = array_diff($with, ['flags', 'body', 'headers'])) {
+            throw new InvalidOptionException('Invalid message parts ['.implode(', ', $invalid).']. Valid options are [flags, body, headers].');
+        }
+
+        $mailbox = Imap::mailbox($name = $this->argument('mailbox'));
 
         $this->info("Watching mailbox [$name]...");
 
         $attempts = 0;
 
         $lastReceivedAt = null;
 
-        $loop->run(function () use ($mailbox, $name, $with, &$attempts, &$lastReceivedAt) {
+        $handler = $method === 'events'
+            ? new HandleMailboxEventReceived($this, $name, $attempts, $lastReceivedAt)
+            : new HandleMessageReceived($this, $name, $attempts, $lastReceivedAt);
+
+        $loop->run(function () use ($mailbox, $name, $method, $with, $timeout, $retries, $handler, &$attempts, &$lastReceivedAt) {
+            $receiving = false;
+
+            $callback = function (MessageInterface|EventInterface $event) use ($handler, &$receiving) {
+                $receiving = true;
+
+                $handler($event);
+
+                $receiving = false;
+            };
+
             try {
                 $folder = $this->folder($mailbox);
 
-                match ($this->option('method')) {
-                    'idle' => $folder->idle(
-                        new HandleMessageReceived($this, $name, $attempts, $lastReceivedAt),
-                        new ConfigureIdleQuery($with),
-                        $this->option('timeout'),
-                    ),
-                    'poll' => $folder->poll(
-                        new HandleMessageReceived($this, $name, $attempts, $lastReceivedAt),
-                        new ConfigureIdleQuery($with),
-                        $this->option('timeout'),
-                    ),
-                };
-            } catch (Exception $e) {
-                if ($this->isMessageMissing($e)) {
-                    return;
+                if ($method === 'events') {
+                    $folder->events($callback, $timeout);
+                } else {
+                    $folder->{$method}($callback, new ConfigureIdleQuery($with), $timeout);
                 }
-
-                if ($this->isDisconnection($e)) {
-                    sleep(2);
-
-                    return;
+            } catch (ImapConnectionException|ImapStreamException $e) {
+                // Listener failures must not restart the watcher, even for IMAP errors.
+                if ($receiving) {
+                    throw $e;
                 }
 
-                if ($attempts >= $this->option('attempts')) {
-                    $this->info("Exception: {$e->getMessage()}");
+                $mailbox->disconnect();
+
+                if ($attempts >= $retries) {
+                    $this->error("Exception: {$e->getMessage()}");
 
                     Event::dispatch(
                         new MailboxWatchAttemptsExceeded($name, $attempts, $e, $lastReceivedAt)
@@ -93,6 +110,10 @@ public function handle(LoopInterface $loop): void
                 }
 
                 $attempts++;
+
+                $this->warn("Connection failed. Retrying [$attempts/$retries] in 2 seconds.");
+
+                Sleep::for(2)->seconds();
             }
         });
     }
@@ -106,32 +127,4 @@ protected function folder(MailboxInterface $mailbox): FolderInterface
              ? $mailbox->folders()->findOrFail($folder)
              : $mailbox->inbox();
     }
-
-    /**
-     * Determine if the exception is due to a message missing error.
-     */
-    protected function isMessageMissing(Exception $e): bool
-    {
-        return Str::contains($e->getMessage(), [
-            'no longer exist',
-        ], true);
-    }
-
-    /**
-     * Determine if the exception is caused by a disconnection.
-     */
-    protected function isDisconnection(Exception $e): bool
-    {
-        return Str::contains($e->getMessage(), [
-            'connection reset by peer',
-            'temporary system problem',
-            'failed to fetch content',
-            'connection failed',
-            'empty response',
-            'not connected',
-            'no response',
-            'broken pipe',
-            'unavailable',
-        ], true);
-    }
 }

src/Events/MailboxEventReceived.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace DirectoryTree\ImapEngine\Laravel\Events;
+
+use DirectoryTree\ImapEngine\Idle\Events\EventInterface;
+
+class MailboxEventReceived
+{
+    /**
+     * Create a new event instance.
+     */
+    public function __construct(
+        public EventInterface $event,
+        public string $mailbox,
+    ) {}
+}

src/Facades/Imap.php

@@ -32,7 +32,7 @@ public static function fake(
         /** @var ImapManager $manager */
         $manager = static::getFacadeRoot();
 
-        $fake = new FakeMailbox($config, $folders, $capabilities);
+        $fake = FakeMailbox::make($config, $folders, $capabilities);
 
         $manager->swap($mailbox, $fake);
 

src/ImapManager.php

@@ -49,7 +49,7 @@ public function mailbox(string $name): MailboxInterface
      */
     public function register(string $name, array $config): static
     {
-        $this->mailboxes[$name] = $this->build($config);
+        $this->swap($name, $this->build($config));
 
         return $this;
     }
@@ -63,20 +63,30 @@ public function build(array $config): MailboxInterface
     }
 
     /**
-     * Remove a mailbox from the in-memory cache.
+     * Disconnect a mailbox and remove it from the in-memory cache.
      */
     public function forget(string $name): static
     {
+        if (isset($this->mailboxes[$name])) {
+            $this->mailboxes[$name]->disconnect();
+        }
+
         unset($this->mailboxes[$name]);
 
         return $this;
     }
 
     /**
-     * Swap out a mailbox instance with a new one.
+     * Disconnect the previous mailbox and replace it with a new instance.
      */
     public function swap(string $name, MailboxInterface $mailbox): void
     {
+        if (($this->mailboxes[$name] ?? null) === $mailbox) {
+            return;
+        }
+
+        $this->forget($name);
+
         $this->mailboxes[$name] = $mailbox;
     }
 }

src/ImapServiceProvider.php

@@ -13,6 +13,8 @@ class ImapServiceProvider extends ServiceProvider
      */
     public function register(): void
     {
+        $this->mergeConfigFrom(__DIR__.'/../config/imap.php', 'imap');
+
         $this->app->singleton(ImapManager::class, function () {
             return new ImapManager(config('imap', []));
         });