[2.x] Add incremental mailbox synchronization

composer.json

@@ -17,7 +17,7 @@
         }
     ],
     "require": {
-        "php": "^8.1",
+        "php": "^8.2",
         "symfony/mime": ">=6.0",
         "nesbot/carbon": ">=2.0",
         "illuminate/collections": ">=9.0",

src/Authentication.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace DirectoryTree\ImapEngine;
+
+use DirectoryTree\ImapEngine\Connection\ConnectionInterface;
+use DirectoryTree\ImapEngine\Connection\Responses\TaggedResponse;
+use Throwable;
+
+class Authentication
+{
+    /**
+     * Constructor.
+     */
+    public function __construct(
+        protected ConnectionInterface $connection,
+        protected AuthenticatorInterface $authenticator,
+    ) {}
+
+    /**
+     * Authenticate the connection.
+     */
+    public function authenticate(bool $initial = false): TaggedResponse
+    {
+        $response = $this->authenticator->initial();
+        $sent = $initial && $response !== null;
+
+        $exchange = $this->connection->authenticate(
+            $this->authenticator->mechanism(),
+            $sent ? $response : null,
+        );
+
+        foreach ($exchange as $challenge) {
+            try {
+                if (! $sent && $response !== null) {
+                    $answer = $response;
+                    $sent = true;
+                } else {
+                    $answer = $this->authenticator->respond($challenge);
+                }
+            } catch (Throwable $e) {
+                $this->connection->disconnect();
+
+                throw $e;
+            }
+
+            $this->connection->respond($answer);
+        }
+
+        return $exchange->getReturn();
+    }
+}

src/Authentication/XOAuth2.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace DirectoryTree\ImapEngine\Authentication;
+
+use DirectoryTree\ImapEngine\AuthenticatorInterface;
+
+class XOAuth2 implements AuthenticatorInterface
+{
+    /**
+     * Constructor.
+     */
+    public function __construct(
+        protected string $user,
+        protected string $token,
+    ) {}
+
+    /**
+     * {@inheritDoc}
+     */
+    public function mechanism(): string
+    {
+        return 'XOAUTH2';
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function initial(): string
+    {
+        return "user=$this->user\1auth=Bearer $this->token\1\1";
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function respond(string $challenge): string
+    {
+        return '';
+    }
+}

src/AuthenticatorInterface.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace DirectoryTree\ImapEngine;
+
+interface AuthenticatorInterface
+{
+    /**
+     * Get the SASL mechanism name.
+     */
+    public function mechanism(): string;
+
+    /**
+     * Get the unencoded initial data, or null to await a challenge.
+     */
+    public function initial(): ?string;
+
+    /**
+     * Respond to a decoded challenge. Return null to cancel authentication.
+     */
+    public function respond(string $challenge): ?string;
+}

src/Capabilities.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace DirectoryTree\ImapEngine;
+
+readonly class Capabilities
+{
+    /**
+     * The mailbox capabilities.
+     *
+     * @var array<string, Capability>
+     */
+    protected array $items;
+
+    /**
+     * Constructor.
+     *
+     * @param  array<string, Capability>  $items
+     */
+    protected function __construct(array $items)
+    {
+        $this->items = $items;
+    }
+
+    /**
+     * Create a capability collection from the given items.
+     */
+    public static function from(Capability ...$capabilities): static
+    {
+        $items = [];
+
+        foreach ($capabilities as $capability) {
+            $items[$capability->name()] = $capability;
+        }
+
+        return new static($items);
+    }
+
+    /**
+     * Get the capability items.
+     *
+     * @return array<string, Capability>
+     */
+    public function items(): array
+    {
+        return $this->items;
+    }
+
+    /**
+     * Get all supported capabilities.
+     */
+    public function all(): array
+    {
+        return array_keys($this->items);
+    }
+
+    /**
+     * Determine if the exact capability exists.
+     */
+    public function has(string $capability): bool
+    {
+        return isset($this->items[strtoupper($capability)]);
+    }
+
+    /**
+     * Determine if the capability is supported.
+     */
+    public function supports(string $capability): bool
+    {
+        return (bool) $this->find($capability);
+    }
+
+    /**
+     * Determine if the capability is enabled.
+     */
+    public function enabled(string $capability): bool
+    {
+        return ($this->items[strtoupper($capability)] ?? null)?->enabled() ?? false;
+    }
+
+    /**
+     * Find a supported capability.
+     */
+    protected function find(string $capability): ?Capability
+    {
+        foreach ($this->items as $item) {
+            if ($item->matches($capability)) {
+                return $item;
+            }
+        }
+
+        return null;
+    }
+}

src/Capability.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace DirectoryTree\ImapEngine;
+
+readonly class Capability
+{
+    /**
+     * Constructor.
+     */
+    protected function __construct(
+        protected string $name,
+        protected bool $enabled = false,
+    ) {}
+
+    /**
+     * Make a new capability instance.
+     */
+    public static function make(string $name, bool $enabled = false): static
+    {
+        return new static(strtoupper($name), $enabled);
+    }
+
+    /**
+     * Get the capability name.
+     */
+    public function name(): string
+    {
+        return $this->name;
+    }
+
+    /**
+     * Determine if the capability matches the given name.
+     */
+    public function matches(string $capability): bool
+    {
+        $capability = strtoupper($capability);
+
+        return $this->name === $capability
+            || str_starts_with($this->name, "{$capability}=");
+    }
+
+    /**
+     * Determine if the capability is enabled.
+     */
+    public function enabled(): bool
+    {
+        return $this->enabled;
+    }
+}