Merge pull request #7 from blendbyte/rate-limit-typed-exceptions

Add typed exceptions: AuthException, RateLimitException::getRetryAfter(), AcmeException::getSubproblems()

Author: bashgeek

README.md

@@ -49,6 +49,10 @@ The built-in curl client needs no extra dependencies. Need proxy support, custom
 
 Filesystem with file locking, PDO (MySQL, PostgreSQL, SQLite) with dialect-aware upserts, and in-memory for testing. All three share the same interface, so switching backends doesn't touch your issuance code.
 
+### Typed exceptions for every failure mode
+
+`RateLimitException` carries the CA's `Retry-After` seconds so your retry logic is precise. `AuthException` tells you credentials failed — not a transient error. `AcmeException::getSubproblems()` surfaces RFC 8555 §6.7 per-identifier errors so a multi-domain order can report exactly which domains were rejected and why. All exceptions share a common base so a single `catch` still works when you don't need the detail.
+
 ### CAA pre-check
 
 Before submitting an order, CoyoteCert queries CAA DNS records for every requested domain. If a record exists and excludes the chosen CA, you get an immediate `CaaException` naming the blocking domain — no wasted rate-limit attempt, no waiting for an ACME order to fail minutes later. The check follows RFC 8659 tree-walking, handles `issuewild` tags for wildcard domains, and respects parameter extensions (e.g. `letsencrypt.org; validationmethods=http-01`). CAA identifiers are built into every provider; `->skipCaaCheck()` opts out when DNS is internal or split-horizon.
@@ -628,6 +632,81 @@ CoyoteCert::with(new LetsEncrypt())
 
 ---
 
+## Error handling
+
+All exceptions extend `AcmeException`, so a single `catch (AcmeException $e)` covers everything. Catch the narrower types when you need to react differently to specific failure modes.
+
+### Rate limits — with Retry-After
+
+```php
+use CoyoteCert\Exceptions\RateLimitException;
+
+try {
+    $cert = CoyoteCert::with(new LetsEncrypt())
+        ->identifiers('example.com')
+        ->challenge(new Http01Handler('/var/www/html'))
+        ->issue();
+} catch (RateLimitException $e) {
+    $wait = $e->getRetryAfter(); // int seconds from Retry-After header, or null
+    echo "Rate limited. Retry" . ($wait ? " in {$wait}s." : " later.");
+}
+```
+
+`getRetryAfter()` returns the value from the CA's `Retry-After` header when present, or `null` when the header is absent. Use it to schedule a precise back-off rather than guessing.
+
+### Authentication failures
+
+```php
+use CoyoteCert\Exceptions\AuthException;
+
+try {
+    $api->account()->get();
+} catch (AuthException $e) {
+    // 401 / 403 — account key rejected or credentials revoked
+    echo $e->getMessage();
+}
+```
+
+`AuthException` is thrown on 401 and 403 responses. Distinct from a rate limit or a transient server error, so you can alert or re-provision credentials rather than retrying.
+
+### Per-identifier subproblems (RFC 8555 §6.7)
+
+When an order covering multiple domains is rejected, the CA may return a `subproblems` array with a separate error for each failing identifier:
+
+```php
+use CoyoteCert\Exceptions\AcmeException;
+
+try {
+    $cert = CoyoteCert::with(new LetsEncrypt())
+        ->identifiers(['example.com', 'bad.example.com'])
+        ->challenge(new Http01Handler('/var/www/html'))
+        ->issue();
+} catch (AcmeException $e) {
+    foreach ($e->getSubproblems() as $sub) {
+        // ['type' => '...', 'detail' => '...', 'identifier' => ['type' => 'dns', 'value' => '...']]
+        echo $sub['identifier']['value'] . ': ' . $sub['detail'] . PHP_EOL;
+    }
+}
+```
+
+`getSubproblems()` returns an empty array when the server returned a single top-level error with no per-identifier breakdown.
+
+### Exception hierarchy
+
+```
+AcmeException          — base; always safe to catch
+├── AuthException      — 401/403 (bad credentials, revoked account)
+├── RateLimitException — 429 (too many requests); carries getRetryAfter()
+├── CaaException       — CAA DNS record blocks issuance
+├── ChallengeException — challenge validation failed
+├── CryptoException    — local key or certificate operation failed
+├── DomainValidationException — pre-flight HTTP/DNS self-check failed
+├── OrderNotFoundException   — order ID not found on the CA
+└── StorageException   — storage backend error
+```
+
+---
+
 ## Wildcard and multi-domain certificates
 
 Pass an array of domains to `->identifiers()`. Wildcards require DNS-01 or dns-persist-01.

src/Endpoints/Endpoint.php

@@ -4,6 +4,8 @@
 
 use CoyoteCert\Api;
 use CoyoteCert\Exceptions\AcmeException;
+use CoyoteCert\Exceptions\AuthException;
+use CoyoteCert\Exceptions\RateLimitException;
 use CoyoteCert\Http\Response;
 use CoyoteCert\Support\KeyId;
 
@@ -70,12 +72,45 @@ protected function isBadNonce(Response $response): bool
             && ($response->jsonBody()['type'] ?? '') === 'urn:ietf:params:acme:error:badNonce';
     }
 
-    protected function throwError(Response $response, string $defaultMessage): never
+    /** @param array<string, mixed> $additionalContext */
+    protected function throwError(Response $response, string $defaultMessage, array $additionalContext = []): never
+    {
+        $this->logResponse('error', $response->jsonBody()['detail'] ?? $defaultMessage, $response, $additionalContext);
+
+        throw $this->createException($response, $defaultMessage);
+    }
+
+    /**
+     * Build a typed exception from the response without logging.
+     * Dispatches 401/403 → AuthException, 429 → RateLimitException (with Retry-After),
+     * and attaches RFC 8555 §6.7 subproblems to any exception that carries them.
+     */
+    protected function createException(Response $response, string $defaultMessage): AcmeException
     {
-        $message = $response->jsonBody()['detail'] ?? $defaultMessage;
-        $this->logResponse('error', $message, $response);
+        $body    = $response->jsonBody();
+        $message = $body['detail'] ?? $defaultMessage;
+
+        /** @var array<int, array<string, mixed>> $subproblems */
+        $subproblems = $body['subproblems'] ?? [];
+
+        return match ($response->getHttpResponseCode()) {
+            401, 403 => new AuthException($message),
+            429      => new RateLimitException($message, $this->parseRetryAfterSeconds($response)),
+            default  => new AcmeException($message, $subproblems),
+        };
+    }
+
+    protected function parseRetryAfterSeconds(Response $response): ?int
+    {
+        $value = $response->getHeader('retry-after', '');
+
+        if (!is_string($value) || $value === '') {
+            return null;
+        }
+
+        $seconds = (int) $value;
 
-        throw new AcmeException($message);
+        return $seconds > 0 ? $seconds : null;
     }
 
     protected function getAccountPrivateKey(): string

src/Endpoints/Order.php

@@ -6,7 +6,6 @@
 use CoyoteCert\DTO\OrderData;
 use CoyoteCert\Exceptions\AcmeException;
 use CoyoteCert\Exceptions\OrderNotFoundException;
-use CoyoteCert\Exceptions\RateLimitException;
 use CoyoteCert\Support\Base64;
 
 class Order extends Endpoint
@@ -62,15 +61,7 @@ public function new(AccountData $accountData, array $domains, string $profile =
             }
         }
 
-        $this->logResponse('error', 'Creating new order failed; bad response code.', $response, ['payload' => $payload]);
-
-        $detail = $response->jsonBody()['detail'] ?? $response->rawBody();
-
-        throw new AcmeException(sprintf(
-            'Creating new order failed (HTTP %d): %s',
-            $response->getHttpResponseCode(),
-            $detail,
-        ));
+        $this->throwError($response, 'Creating new order failed.', ['payload' => $payload]);
     }
 
     public function get(string $id): OrderData
@@ -92,13 +83,11 @@ public function get(string $id): OrderData
             return OrderData::fromResponse($response, $account->url);
         }
 
-        // Always log the error.
         $this->logResponse('error', 'Getting order failed; bad response code.', $response);
 
-        match ($response->getHttpResponseCode()) {
-            404     => throw new OrderNotFoundException($response->jsonBody()['detail'] ?? 'Order cannot be found.'),
-            429     => throw new RateLimitException($response->jsonBody()['detail'] ?? 'Too many requests.'),
-            default => throw new AcmeException($response->jsonBody()['detail'] ?? 'Unknown error.'),
+        throw match ($response->getHttpResponseCode()) {
+            404     => new OrderNotFoundException($response->jsonBody()['detail'] ?? 'Order cannot be found.'),
+            default => $this->createException($response, 'Getting order failed.'),
         };
     }
 

src/Exceptions/AcmeException.php

@@ -4,4 +4,23 @@
 
 use RuntimeException;
 
-class AcmeException extends RuntimeException {}
+class AcmeException extends RuntimeException
+{
+    /** @var array<int, array<string, mixed>> */
+    private readonly array $subproblems;
+
+    /**
+     * @param array<int, array<string, mixed>> $subproblems RFC 8555 §6.7 per-identifier problems.
+     */
+    public function __construct(string $message = '', array $subproblems = [], int $code = 0, ?\Throwable $previous = null)
+    {
+        $this->subproblems = $subproblems;
+        parent::__construct($message, $code, $previous);
+    }
+
+    /** @return array<int, array<string, mixed>> */
+    public function getSubproblems(): array
+    {
+        return $this->subproblems;
+    }
+}

src/Exceptions/AuthException.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace CoyoteCert\Exceptions;
+
+class AuthException extends AcmeException {}

src/Exceptions/RateLimitException.php

@@ -2,4 +2,18 @@
 
 namespace CoyoteCert\Exceptions;
 
-class RateLimitException extends AcmeException {}
+class RateLimitException extends AcmeException
+{
+    public function __construct(string $message, private readonly ?int $retryAfter = null)
+    {
+        parent::__construct($message);
+    }
+
+    /**
+     * Seconds the server asked us to wait, or null when the header was absent.
+     */
+    public function getRetryAfter(): ?int
+    {
+        return $this->retryAfter;
+    }
+}

tests/Unit/Endpoints/EndpointsTest.php

@@ -7,6 +7,7 @@
 use CoyoteCert\Enums\AuthorizationChallengeEnum;
 use CoyoteCert\Enums\KeyType;
 use CoyoteCert\Exceptions\AcmeException;
+use CoyoteCert\Exceptions\AuthException;
 use CoyoteCert\Exceptions\OrderNotFoundException;
 use CoyoteCert\Exceptions\RateLimitException;
 use CoyoteCert\Http\Response;
@@ -429,7 +430,7 @@ function makeTestCerts(): array
     ), withKeyStorage());
 
     expect(fn() => $api->order()->new(makeAccountData(), ['example.com']))
-        ->toThrow(AcmeException::class, 'Creating new order failed');
+        ->toThrow(AcmeException::class, 'Bad Request');
 });
 
 it('Order::new() returns OrderData on 201 response', function () {
@@ -583,6 +584,78 @@ function makeTestCerts(): array
         ->toThrow(AcmeException::class, 'Internal error');
 });
 
+it('Order::get() throws RateLimitException with parsed Retry-After seconds', function () {
+    $storage = withKeyStorage();
+
+    $mock = closureMock(
+        getHandler: fn($url) => new Response([], $url, 200, directoryBody()),
+        postHandler: fn($url) => str_contains($url, 'new-account')
+            ? new Response(['location' => 'https://acme.example/account/1'], $url, 200, accountBody())
+            : new Response(['retry-after' => '30'], $url, 429, ['detail' => 'Rate limited']),
+    );
+
+    $caught = null;
+    try {
+        makeEndpointApi($mock, $storage)->order()->get('spam');
+    } catch (RateLimitException $e) {
+        $caught = $e;
+    }
+
+    expect($caught)->toBeInstanceOf(RateLimitException::class);
+    expect($caught->getRetryAfter())->toBe(30);
+});
+
+it('Order::get() throws AuthException on 401', function () {
+    $storage = withKeyStorage();
+
+    $mock = closureMock(
+        getHandler: fn($url) => new Response([], $url, 200, directoryBody()),
+        postHandler: fn($url) => str_contains($url, 'new-account')
+            ? new Response(['location' => 'https://acme.example/account/1'], $url, 200, accountBody())
+            : new Response([], $url, 401, ['detail' => 'Unauthorized']),
+    );
+
+    expect(fn() => makeEndpointApi($mock, $storage)->order()->get('auth-fail'))
+        ->toThrow(AuthException::class, 'Unauthorized');
+});
+
+it('Order::new() throws RateLimitException on 429', function () {
+    $api = makeEndpointApi(endpointMock(
+        getBody: directoryBody(),
+        postBody: ['detail' => 'Too many certificates already issued'],
+        postCode: 429,
+    ), withKeyStorage());
+
+    expect(fn() => $api->order()->new(makeAccountData(), ['example.com']))
+        ->toThrow(RateLimitException::class, 'Too many certificates already issued');
+});
+
+it('Order::new() attaches RFC 8555 §6.7 subproblems to the thrown exception', function () {
+    $subproblems = [
+        [
+            'type'       => 'urn:ietf:params:acme:error:rejectedIdentifier',
+            'detail'     => 'This CA will not issue for "bad.example.com"',
+            'identifier' => ['type' => 'dns', 'value' => 'bad.example.com'],
+        ],
+    ];
+
+    $api = makeEndpointApi(endpointMock(
+        getBody: directoryBody(),
+        postBody: ['detail' => 'Some identifiers were rejected', 'subproblems' => $subproblems],
+        postCode: 400,
+    ), withKeyStorage());
+
+    $caught = null;
+    try {
+        $api->order()->new(makeAccountData(), ['example.com', 'bad.example.com']);
+    } catch (AcmeException $e) {
+        $caught = $e;
+    }
+
+    expect($caught)->toBeInstanceOf(AcmeException::class);
+    expect($caught->getSubproblems())->toBe($subproblems);
+});
+
 it('Order::get() returns OrderData on success', function () {
     $storage = withKeyStorage();