Add Connection Pooling & HTTP/2 Support

src/Fetch/Concerns/ManagesConnectionPool.php

@@ -0,0 +1,271 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Fetch\Concerns;
+
+use Fetch\Interfaces\ClientHandler;
+use Fetch\Pool\ConnectionPool;
+use Fetch\Pool\DnsCache;
+use Fetch\Pool\Http2Configuration;
+use Fetch\Pool\PoolConfiguration;
+
+/**
+ * Trait for managing connection pooling and HTTP/2 support.
+ *
+ * Note: The connection pool and DNS cache are stored as static properties
+ * to enable connection sharing across all ClientHandler instances. This is
+ * intentional to maximize connection reuse. However, be aware that:
+ * - Configuration changes affect all handlers globally
+ * - In multi-threaded environments, proper synchronization may be needed
+ * - Use resetPool() to isolate test environments
+ */
+trait ManagesConnectionPool
+{
+    /**
+     * The connection pool instance (shared across all handlers).
+     */
+    protected static ?ConnectionPool $connectionPool = null;
+
+    /**
+     * The DNS cache instance (shared across all handlers).
+     */
+    protected static ?DnsCache $dnsCache = null;
+
+    /**
+     * The HTTP/2 configuration.
+     */
+    protected ?Http2Configuration $http2Config = null;
+
+    /**
+     * Whether connection pooling is enabled for this handler.
+     */
+    protected bool $poolingEnabled = false;
+
+    /**
+     * Initialize connection pooling with default configuration.
+     *
+     * @param  PoolConfiguration|null  $config  Optional pool configuration
+     */
+    protected static function initializePool(?PoolConfiguration $config = null): void
+    {
+        if (self::$connectionPool === null) {
+            $poolConfig = $config ?? new PoolConfiguration;
+            self::$connectionPool = new ConnectionPool($poolConfig);
+            self::$dnsCache = new DnsCache($poolConfig->getDnsCacheTtl());
+        }
+    }
+
+    /**
+     * Configure connection pooling for this handler.
+     *
+     * @param  array<string, mixed>|bool  $config  Pool configuration or boolean to enable/disable
+     * @return $this
+     */
+    public function withConnectionPool(array|bool $config = true): ClientHandler
+    {
+        if (is_bool($config)) {
+            $this->poolingEnabled = $config;
+
+            return $this;
+        }
+
+        $this->poolingEnabled = true;
+
+        // Initialize or update the global pool
+        self::$connectionPool = ConnectionPool::fromArray($config);
+
+        // Always initialize DNS cache with configuration TTL (uses default if not specified)
+        $poolConfig = self::$connectionPool->getConfig();
+        self::$dnsCache = new DnsCache($poolConfig->getDnsCacheTtl());
+
+        return $this;
+    }
+
+    /**
+     * Configure HTTP/2 for this handler.
+     *
+     * @param  array<string, mixed>|bool  $config  HTTP/2 configuration or boolean to enable/disable
+     * @return $this
+     */
+    public function withHttp2(array|bool $config = true): ClientHandler
+    {
+        if (is_bool($config)) {
+            $this->http2Config = new Http2Configuration(enabled: $config);
+        } else {
+            $this->http2Config = Http2Configuration::fromArray($config);
+        }
+
+        // Apply HTTP/2 curl options to the handler options
+        if ($this->http2Config->isEnabled()) {
+            $curlOptions = $this->http2Config->getCurlOptions();
+            if (! empty($curlOptions)) {
+                $existingCurl = $this->options['curl'] ?? [];
+                // Use + operator to preserve integer keys (CURL constants)
+                // and give priority to existing options over defaults
+                $this->options['curl'] = $existingCurl + $curlOptions;
+            }
+
+            // Set HTTP version in options
+            $this->options['version'] = 2.0;
+        }
+
+        return $this;
+    }
+
+    /**
+     * Get the connection pool instance.
+     *
+     * @return ConnectionPool|null The pool instance or null if not configured
+     */
+    public function getConnectionPool(): ?ConnectionPool
+    {
+        return self::$connectionPool;
+    }
+
+    /**
+     * Get the DNS cache instance.
+     *
+     * @return DnsCache|null The DNS cache or null if not configured
+     */
+    public function getDnsCache(): ?DnsCache
+    {
+        return self::$dnsCache;
+    }
+
+    /**
+     * Get the HTTP/2 configuration.
+     *
+     * @return Http2Configuration|null The HTTP/2 config or null if not configured
+     */
+    public function getHttp2Config(): ?Http2Configuration
+    {
+        return $this->http2Config;
+    }
+
+    /**
+     * Check if connection pooling is enabled.
+     */
+    public function isPoolingEnabled(): bool
+    {
+        return $this->poolingEnabled && self::$connectionPool !== null && self::$connectionPool->isEnabled();
+    }
+
+    /**
+     * Check if HTTP/2 is enabled.
+     */
+    public function isHttp2Enabled(): bool
+    {
+        return $this->http2Config !== null && $this->http2Config->isEnabled();
+    }
+
+    /**
+     * Get connection pool statistics.
+     *
+     * @return array<string, mixed>
+     */
+    public function getPoolStats(): array
+    {
+        if (self::$connectionPool === null) {
+            return ['enabled' => false];
+        }
+
+        return self::$connectionPool->getStats();
+    }
+
+    /**
+     * Get DNS cache statistics.
+     *
+     * @return array<string, mixed>
+     */
+    public function getDnsCacheStats(): array
+    {
+        if (self::$dnsCache === null) {
+            return ['enabled' => false];
+        }
+
+        return array_merge(['enabled' => true], self::$dnsCache->getStats());
+    }
+
+    /**
+     * Clear the DNS cache.
+     *
+     * @param  string|null  $hostname  Specific hostname to clear, or null for all
+     * @return $this
+     */
+    public function clearDnsCache(?string $hostname = null): ClientHandler
+    {
+        if (self::$dnsCache !== null) {
+            self::$dnsCache->clear($hostname);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Close all pooled connections.
+     *
+     * @return $this
+     */
+    public function closeAllConnections(): ClientHandler
+    {
+        if (self::$connectionPool !== null) {
+            self::$connectionPool->closeAll();
+        }
+
+        return $this;
+    }
+
+    /**
+     * Reset the global connection pool and DNS cache.
+     *
+     * @return $this
+     */
+    public function resetPool(): ClientHandler
+    {
+        if (self::$connectionPool !== null) {
+            self::$connectionPool->closeAll();
+        }
+        self::$connectionPool = null;
+        self::$dnsCache = null;
+        $this->poolingEnabled = false;
+
+        return $this;
+    }
+
+    /**
+     * Get cURL options for HTTP/2 support.
+     *
+     * @return array<int, mixed>
+     */
+    protected function getHttp2CurlOptions(): array
+    {
+        if ($this->http2Config === null) {
+            return [];
+        }
+
+        return $this->http2Config->getCurlOptions();
+    }
+
+    /**
+     * Resolve a hostname using the DNS cache.
+     *
+     * Returns null if DNS cache is not configured or if DNS resolution fails.
+     * This method silently catches exceptions to allow fallback behavior.
+     *
+     * @param  string  $hostname  The hostname to resolve
+     * @return string|null The resolved IP address, or null if not available
+     */
+    protected function resolveHostname(string $hostname): ?string
+    {
+        if (self::$dnsCache === null) {
+            return null;
+        }
+
+        try {
+            return self::$dnsCache->resolveFirst($hostname);
+        } catch (\Throwable) {
+            return null;
+        }
+    }
+}

src/Fetch/Http/ClientHandler.php

@@ -8,6 +8,7 @@
 use Fetch\Concerns\HandlesMocking;
 use Fetch\Concerns\HandlesUris;
 use Fetch\Concerns\ManagesCache;
+use Fetch\Concerns\ManagesConnectionPool;
 use Fetch\Concerns\ManagesDebugAndProfiling;
 use Fetch\Concerns\ManagesPromises;
 use Fetch\Concerns\ManagesRetries;
@@ -31,6 +32,7 @@ class ClientHandler implements ClientHandlerInterface
         HandlesMocking,
         HandlesUris,
         ManagesCache,
+        ManagesConnectionPool,
         ManagesDebugAndProfiling,
         ManagesPromises,
         ManagesRetries,

src/Fetch/Interfaces/ClientHandler.php

@@ -595,4 +595,87 @@ public function getCache(): ?\Fetch\Cache\CacheInterface;
      * Check if caching is enabled.
      */
     public function isCacheEnabled(): bool;
+
+    /**
+     * Configure connection pooling for this handler.
+     *
+     * @param  array<string, mixed>|bool  $config  Pool configuration or boolean to enable/disable
+     * @return $this
+     */
+    public function withConnectionPool(array|bool $config = true): self;
+
+    /**
+     * Configure HTTP/2 for this handler.
+     *
+     * @param  array<string, mixed>|bool  $config  HTTP/2 configuration or boolean to enable/disable
+     * @return $this
+     */
+    public function withHttp2(array|bool $config = true): self;
+
+    /**
+     * Get the connection pool instance.
+     *
+     * @return \Fetch\Pool\ConnectionPool|null The pool instance or null if not configured
+     */
+    public function getConnectionPool(): ?\Fetch\Pool\ConnectionPool;
+
+    /**
+     * Get the DNS cache instance.
+     *
+     * @return \Fetch\Pool\DnsCache|null The DNS cache or null if not configured
+     */
+    public function getDnsCache(): ?\Fetch\Pool\DnsCache;
+
+    /**
+     * Get the HTTP/2 configuration.
+     *
+     * @return \Fetch\Pool\Http2Configuration|null The HTTP/2 config or null if not configured
+     */
+    public function getHttp2Config(): ?\Fetch\Pool\Http2Configuration;
+
+    /**
+     * Check if connection pooling is enabled.
+     */
+    public function isPoolingEnabled(): bool;
+
+    /**
+     * Check if HTTP/2 is enabled.
+     */
+    public function isHttp2Enabled(): bool;
+
+    /**
+     * Get connection pool statistics.
+     *
+     * @return array<string, mixed>
+     */
+    public function getPoolStats(): array;
+
+    /**
+     * Get DNS cache statistics.
+     *
+     * @return array<string, mixed>
+     */
+    public function getDnsCacheStats(): array;
+
+    /**
+     * Clear the DNS cache.
+     *
+     * @param  string|null  $hostname  Specific hostname to clear, or null for all
+     * @return $this
+     */
+    public function clearDnsCache(?string $hostname = null): self;
+
+    /**
+     * Close all pooled connections.
+     *
+     * @return $this
+     */
+    public function closeAllConnections(): self;
+
+    /**
+     * Reset the global connection pool and DNS cache.
+     *
+     * @return $this
+     */
+    public function resetPool(): self;
 }