landing-api/app/Services/Git/GitException.php

<?php

declare(strict_types=1);

namespace App\Services\Git;

use RuntimeException;
use Throwable;

class GitException extends RuntimeException
{
    public function __construct(
        string $message,
        public readonly ?int $status = null,
        /**
         * Whether retrying later might succeed. Rate limits and outages are
         * transient; a deleted repository is not, and the job should stop
         * retrying rather than hammer the provider.
         */
        public readonly bool $isTransient = false,
        ?Throwable $previous = null,
    ) {
        parent::__construct($message, $status ?? 0, $previous);
    }

    public static function notFound(string $fullName): self
    {
        return new self(
            "The repository [{$fullName}] does not exist, or the configured token cannot see it.",
            status: 404,
        );
    }

    public static function rateLimited(?int $resetsInSeconds = null): self
    {
        $when = $resetsInSeconds !== null
            ? " Try again in about {$resetsInSeconds}s."
            : '';

        return new self(
            "The provider's rate limit has been reached.{$when} ".
            'Configure GITHUB_TOKEN to raise it from 60 to 5000 requests per hour.',
            status: 429,
            isTransient: true,
        );
    }

    public static function unreachable(string $provider, ?Throwable $previous = null): self
    {
        return new self(
            "The [{$provider}] API could not be reached.",
            isTransient: true,
            previous: $previous,
        );
    }

    public static function unsupportedProvider(string $provider): self
    {
        return new self(
            "No driver is registered for the [{$provider}] provider. ".
            'Add one to config/git.php.'
        );
    }
}