Verdicts and exceptions

Reasons

Enums\Reason is string-backed. Reason::retryable() returns the column below; for status it returns false and the exception decides:

The enum carries the shared helpers of enums-for-laravel (values(), names(), options(), label(), is(), isIn(), fromName(), validationRule(), …):

use RoundlyConsulting\SafeFetch\Enums\Reason;

Reason::values()->all();               // ['invalid_url', 'scheme', 'credentials', …]
Reason::Unresolved->retryable();       // true
Reason::from($row->reason)->isIn([Reason::Blocked, Reason::NotAllowed]);

Exceptions

RuntimeException
└── SafeFetchException (abstract)      reason(): Reason · retryable(): bool · url(): string · host(): string
    ├── DestinationRejected            + blockedBy(): ?string
    ├── DestinationUnavailable
    └── FetchFailed                    + status(): ?int · retryAfter(): ?int
LogicException
└── UnsafeRequestOptions               a programmer error; names the option

• url() returns the URL as the caller handed it in; host() the canonical host the verdict is about (empty when the URL had none the guard could read). Neither is in the message.
• FetchFailed::retryAfter() is the server’s Retry-After in seconds (seconds or an HTTP date, capped at 86 400), only for a retryable status.
• UnsafeRequestOptions is thrown for an option that would take a request around the guard (see Guarded requests). Its message names the option, in English only — a programmer error, like Laravel’s own exceptions.

Messages that give nothing away

Messages are fixed per reason (safe-fetch::messages.<reason>, English and Slovak) and never contain the URL or an address. blocked and unresolved read the same — “The URL cannot be fetched: its destination is not allowed or cannot be reached.” — so the message is safe to show the person who submitted the URL: telling “private” from “not found” would map your internal network for whoever controls the URL.

reason(), retryable() and blockedBy() do tell them apart — they are for your code and your operators. Never let that difference reach the person who submitted the URL: a “try again later” shown only when retryable() is the same oracle again. Retry in the background, show one message.

blockedBy()

DestinationRejected::blockedBy() — operators only — names the rule behind a blocked verdict:

Named constructors

The guard builds its exceptions through these; they are public, so a test double or a wrapper of your own can throw exactly what the package throws. $url is a #[SensitiveParameter] and never in the message:

DestinationRejected::because(Reason::Blocked, $url, 'internal.example', blockedBy: 'private_address');
DestinationUnavailable::unresolved($url, 'gone.example');                 // retryable
DestinationUnavailable::timedOut($url, 'slow.example');                   // retryable
FetchFailed::forStatus($url, 'api.example', 503, retryAfter: 30);         // status() 503, retryAfter() 30
FetchFailed::because(Reason::Connection, $url, 'api.example');            // retryable
UnsafeRequestOptions::option('proxy', 'a proxy resolves the host name itself.');