bump: version 0.1.1

Move curl exit code descriptions from ProcessTransport into
NetworkException::fromCurlExitCode() factory method.

Author: danielhe4rt

composer.json

@@ -3,7 +3,7 @@
     "description": "PHP TLS/HTTP fingerprinting library for browser emulation",
     "keywords": ["php", "tls", "fingerprint", "http2", "curl-impersonate", "web-scraping", "browser-emulation"],
     "license": "MIT",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "authors": [
         {
             "name": "Daniel Reis",

src/Exception/NetworkException.php

@@ -18,8 +18,61 @@ public function __construct(
         parent::__construct($message, $code, $previous);
     }
 
+    /**
+     * Create from a curl_impersonate process failure.
+     */
+    public static function fromCurlExitCode(RequestInterface $request, int $exitCode, string $stderr = ''): self
+    {
+        $detail = $stderr !== '' ? $stderr : self::describeExitCode($exitCode);
+
+        return new self(
+            $request,
+            'curl_impersonate failed (exit '.$exitCode.'): '.$detail,
+            $exitCode,
+        );
+    }
+
     public function getRequest(): RequestInterface
     {
         return $this->request;
     }
+
+    /**
+     * Map libcurl exit codes to human-readable descriptions.
+     *
+     * @see https://curl.se/libcurl/c/libcurl-errors.html
+     */
+    private static function describeExitCode(int $code): string
+    {
+        return match ($code) {
+            1 => 'unsupported protocol',
+            2 => 'failed to initialize',
+            3 => 'malformed URL',
+            5 => 'could not resolve proxy',
+            6 => 'could not resolve host',
+            7 => 'connection refused',
+            9 => 'access denied (login/credentials)',
+            18 => 'partial transfer (connection closed prematurely)',
+            22 => 'HTTP error (server returned >= 400)',
+            23 => 'write error (disk full or permissions)',
+            26 => 'read error (could not read local file)',
+            27 => 'out of memory',
+            28 => 'operation timed out',
+            33 => 'range error (server does not support byte ranges)',
+            35 => 'SSL/TLS handshake failed',
+            47 => 'too many redirects',
+            51 => 'SSL certificate verification failed (peer)',
+            52 => 'empty reply from server',
+            55 => 'send error (network failure)',
+            56 => 'receive error (connection reset)',
+            58 => 'SSL client certificate error',
+            60 => 'SSL CA certificate not found or not trusted',
+            67 => 'login denied (authentication failure)',
+            77 => 'SSL CA certificate path error',
+            92 => 'HTTP/2 stream error',
+            95 => 'HTTP/2 error',
+            97 => 'HTTP/3 error',
+            default => 'unknown error (code '.$code.')',
+        };
+    }
 }

src/Transport/ProcessTransport.php

@@ -58,10 +58,10 @@ public function send(RequestInterface $request, Profile $profile, TransportOptio
         $exitCode = proc_close($process);
 
         if ($exitCode !== 0 || $stdout === false) {
-            throw new NetworkException(
+            throw NetworkException::fromCurlExitCode(
                 $request,
-                'curl_impersonate failed (exit '.$exitCode.'): '.($stderr !== false && $stderr !== '' ? $stderr : 'unknown error'),
                 $exitCode,
+                $stderr !== false && $stderr !== '' ? trim($stderr) : '',
             );
         }
 

tests/Unit/Exception/NetworkExceptionTest.php

@@ -51,3 +51,29 @@
     expect($exception->getMessage())->toBe('')
         ->and($exception->getCode())->toBe(0);
 });
+
+it('creates from curl exit code with stderr detail', function (): void {
+    $request = new Request('GET', 'https://example.com');
+    $exception = NetworkException::fromCurlExitCode($request, 7, 'Connection refused');
+
+    expect($exception)->toBeInstanceOf(NetworkException::class)
+        ->and($exception->getMessage())->toBe('curl_impersonate failed (exit 7): Connection refused')
+        ->and($exception->getCode())->toBe(7)
+        ->and($exception->getRequest())->toBe($request);
+});
+
+it('creates from curl exit code with mapped description when stderr is empty', function (): void {
+    $request = new Request('GET', 'https://example.com');
+    $exception = NetworkException::fromCurlExitCode($request, 28);
+
+    expect($exception->getMessage())->toBe('curl_impersonate failed (exit 28): operation timed out')
+        ->and($exception->getCode())->toBe(28);
+});
+
+it('creates from curl exit code with unknown code fallback', function (): void {
+    $request = new Request('GET', 'https://example.com');
+    $exception = NetworkException::fromCurlExitCode($request, 999);
+
+    expect($exception->getMessage())->toBe('curl_impersonate failed (exit 999): unknown error (code 999)')
+        ->and($exception->getCode())->toBe(999);
+});