Verdikty a výnimky

Dôvody

Enums\Reason je enum s reťazcovými hodnotami. Reason::retryable() vracia stĺpec nižšie; pre status vracia false a rozhoduje výnimka:

Enum má spoločné pomocné metódy z 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]);

Výnimky

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() vráti URL adresu tak, ako ju volajúci odovzdal; host() kanonického hostiteľa, ktorého sa verdikt týka (prázdny, ak URL žiadneho čitateľného nemala). Ani jedno nie je v správe.
• FetchFailed::retryAfter() je Retry-After servera v sekundách (sekundy alebo HTTP dátum, najviac 86 400), len pri opakovateľnom stave.
• UnsafeRequestOptions sa vyhodí pre voľbu, ktorá by požiadavku vyviedla mimo ochranu (pozrite Chránené požiadavky). Jej správa uvádza voľbu, len po anglicky — ide o chybu programátora, podobne ako vlastné výnimky Laravelu.

Správy, ktoré nič neprezradia

Správy sú pevné pre každý dôvod (safe-fetch::messages.<reason>, v angličtine a slovenčine) a nikdy neobsahujú URL ani adresu. blocked a unresolved znejú rovnako — „URL adresu nie je možné načítať: jej cieľ nie je povolený alebo nie je dostupný.“ — takže správu môžete bezpečne zobraziť tomu, kto URL odoslal: rozlíšenie „privátne“ od „neexistuje“ by komukoľvek, kto URL ovláda, zmapovalo vašu internú sieť.

reason(), retryable() a blockedBy() ich rozlišujú — sú pre váš kód a vašich prevádzkovateľov. Tento rozdiel sa nikdy nesmie dostať k tomu, kto URL odoslal: „skúste neskôr“ zobrazené len pri retryable() je ten istý únik informácie. Opakujte na pozadí a zobrazujte jednu správu.

blockedBy()

DestinationRejected::blockedBy() — len pre prevádzkovateľov — pomenuje pravidlo za verdiktom blocked:

Pomenované konštruktory

Cez ne ochrana vytvára svoje výnimky; sú verejné, takže testovací dvojník alebo vlastný obal môže vyhodiť presne to, čo vyhadzuje balík. $url je #[SensitiveParameter] a nikdy nie je v správe:

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.');