Refactor idle to use a generator

Author: stevebauman

src/Connection/ConnectionInterface.php

@@ -5,6 +5,7 @@
 use DirectoryTree\ImapEngine\Collections\ResponseCollection;
 use DirectoryTree\ImapEngine\Connection\Responses\TaggedResponse;
 use DirectoryTree\ImapEngine\Connection\Responses\UntaggedResponse;
+use Generator;
 
 interface ConnectionInterface
 {
@@ -66,7 +67,7 @@ public function startTls(): void;
      *
      * @see https://datatracker.ietf.org/doc/html/rfc9051#name-idle-command
      */
-    public function idle(int $timeout): void;
+    public function idle(int $timeout): Generator;
 
     /**
      * Send a "DONE" command.

src/Connection/ImapConnection.php

@@ -16,6 +16,7 @@
 use DirectoryTree\ImapEngine\Exceptions\Exception;
 use DirectoryTree\ImapEngine\Exceptions\RuntimeException;
 use DirectoryTree\ImapEngine\Support\Str;
+use Generator;
 
 class ImapConnection implements ConnectionInterface
 {
@@ -489,7 +490,7 @@ public function noop(): TaggedResponse
     /**
      * {@inheritDoc}
      */
-    public function idle(int $timeout): void
+    public function idle(int $timeout): Generator
     {
         $this->stream->setTimeout($timeout);
 
@@ -499,6 +500,10 @@ public function idle(int $timeout): void
             fn (ContinuationResponse $response) => true,
             fn (ContinuationResponse $response) => CommandFailedException::make(new ImapCommand('', 'IDLE'), $response),
         );
+
+        while ($response = $this->nextReply()) {
+            yield $response;
+        }
     }
 
     /**

src/Idle.php

@@ -3,11 +3,11 @@
 namespace DirectoryTree\ImapEngine;
 
 use Carbon\Carbon;
-use DirectoryTree\ImapEngine\Connection\Responses\Response;
 use DirectoryTree\ImapEngine\Connection\Responses\UntaggedResponse;
 use DirectoryTree\ImapEngine\Exceptions\ConnectionClosedException;
 use DirectoryTree\ImapEngine\Exceptions\ConnectionTimedOutException;
 use DirectoryTree\ImapEngine\Exceptions\Exception;
+use Generator;
 
 class Idle
 {
@@ -35,33 +35,27 @@ public function await(callable $callback): void
     {
         $this->connect();
 
-        $this->idle();
-
-        $ttl = $this->getNextTimeout();
-
-        try {
-            $this->listen($callback, $ttl);
-        } catch (ConnectionTimedOutException) {
-            $this->reidle();
-
-            $ttl = $this->getNextTimeout();
-
-            $this->listen($callback, $ttl);
-        } catch (ConnectionClosedException) {
-            $this->reconnect();
-
+        // Loop indefinitely, restarting IDLE sessions as needed.
+        while (true) {
             $ttl = $this->getNextTimeout();
 
-            $this->listen($callback, $ttl);
+            try {
+                $this->listen($callback, $ttl);
+            } catch (ConnectionTimedOutException) {
+                $this->restart();
+            } catch (ConnectionClosedException) {
+                $this->reconnect();
+            }
         }
     }
 
     /**
-     * Start listening for new messages.
+     * Start listening for new messages using the idle() generator.
      */
     protected function listen(callable $callback, Carbon $ttl): void
     {
-        while ($response = $this->getNextReply()) {
+        // Iterate over responses yielded by the idle generator.
+        foreach ($this->idle() as $response) {
             if (! $response instanceof UntaggedResponse) {
                 continue;
             }
@@ -74,77 +68,69 @@ protected function listen(callable $callback, Carbon $ttl): void
                 $ttl = $this->getNextTimeout();
             }
 
-            if (! Carbon::now()->greaterThanOrEqualTo($ttl)) {
-                continue;
-            }
+            // If we've been idle too long, break out to restart the session.
+            if (Carbon::now()->greaterThanOrEqualTo($ttl)) {
+                $this->restart();
 
-            try {
-                // If we've been idle too long, we'll send a DONE and re-IDLE.
-                // This will keep the server from killing the connection.
-                // Some Servers require this to avoid disconnection.
-                $this->done();
-            } catch (Exception) {
-                // If done fails, we're likely already disconnected.
-                // We'll attempt to reconnect and restart the IDLE.
-                $this->reconnect();
+                break;
             }
-
-            $this->idle();
-
-            $ttl = $this->getNextTimeout();
         }
     }
 
     /**
-     * Connect the client and begin IDLE.
+     * Get the folder to idle.
      */
-    protected function connect(): void
+    protected function folder(): Folder
     {
-        $this->mailbox->connect();
-
-        $this->mailbox->select($this->folder(), true);
+        return $this->mailbox->folders()->find($this->folder);
     }
 
     /**
-     * Reconnect the client and restart IDLE.
+     * Issue a done command and restart the idle session.
      */
-    protected function reconnect(): void
+    protected function restart(): void
     {
-        $this->mailbox->disconnect();
-
-        $this->connect();
+        try {
+            // Send DONE to terminate the current IDLE session gracefully.
+            $this->done();
+        } catch (Exception) {
+            $this->reconnect();
+        }
     }
 
     /**
-     * Disconnect the client.
+     * Reconnect the client and restart the idle session.
      */
-    protected function disconnect(): void
+    protected function reconnect(): void
     {
-        $this->done();
-
         $this->mailbox->disconnect();
+
+        $this->connect();
     }
 
     /**
-     * Get the folder to idle.
+     * Connect the client and select the folder to idle.
      */
-    protected function folder(): Folder
+    protected function connect(): void
     {
-        return $this->mailbox->folders()->find($this->folder);
+        $this->mailbox->connect();
+
+        $this->mailbox->select($this->folder(), true);
     }
 
     /**
-     * End the current IDLE session and start a new one.
+     * Disconnect the client.
      */
-    protected function reidle(): void
+    protected function disconnect(): void
     {
         try {
+            // Attempt to terminate IDLE gracefully.
             $this->done();
         } catch (Exception) {
-            $this->reconnect();
+            // Do nothing.
         }
 
-        $this->idle();
+        $this->mailbox->disconnect();
     }
 
     /**
@@ -156,23 +142,15 @@ protected function done(): void
     }
 
     /**
-     * Being a new IDLE session.
-     */
-    protected function idle(): void
-    {
-        $this->mailbox->connection()->idle($this->timeout);
-    }
-
-    /**
-     * Get the next reply from the connection.
+     * Begin a new IDLE session as a generator.
      */
-    protected function getNextReply(): Response
+    protected function idle(): Generator
     {
-        return $this->mailbox->connection()->nextReply();
+        yield from $this->mailbox->connection()->idle($this->timeout);
     }
 
     /**
-     * Get the next timeout.
+     * Get the next timeout as a Carbon instance.
      */
     protected function getNextTimeout(): Carbon
     {