Chránené požiadavky
Http::safe() chráni akúkoľvek HTTP požiadavku Laravelu. URL adresa sa prestavia z prísneho parsovania, posúdi sa každá adresa, na ktorú sa hostiteľ preloží, spojenie sa cez curl pripne na tieto adresy bez proxy a bez opätovne použitého spojenia a skontroluje sa adresa, na ktorú sa curl skutočne pripojil:
Http::safe()->post($url, $payload); // the configured policy
Http::safe(SafeFetch::policy()->followRedirects())->post($url, $payload); // a policy for this call
Http::withToken($token)->safe()->post($url, $payload); // chains either way
SafeFetch::guard(Http::withToken($token)->timeout(10), $policy)->post($url); // the manager, no macro
SafeFetch::http($policy)->get($url); // a new guarded requestČo ochrana s požiadavkou urobí
- Bez curl ju odmietne (cannot_pin, ešte pred zostavením — fail closed).
- Odmietne požiadavku, ktorá už má vlastného klienta (setClient()), Guzzle voľbu handler (Http::globalOptions(), withOptions() pred alebo po safe()) alebo ktorá už je chránená — UnsafeRequestOptions.
- Nastaví vlastný pripnutý handler — vždy curl, nikdy stream handler (ten by pripnutie ignoroval), nikdy handler aplikácie. stream => true streamuje cez tento handler curl (pozrite Streamované odpovede).
- Vypne vlastné presmerovania Guzzle; presmerovania riadi ochrana.
- Pridá middleware ochrany, ktorý si overenie každého kroku vyžiada od manažéra, takže SafeFetch::fake() vidí všetky kroky.
- Odosiela cez vlastného klienta, ktorý vidí konečné voľby každej požiadavky skôr než Guzzle — handler pridaný po safe() sa odmietne pri odoslaní.
Pri každom kroku
- URL adresa sa overí (rovnako ako SafeFetch::vet()) — odmietnutie požiadavku zamietne a nič sa neodošle.
- Požiadavka ide na prestavanú URL; pri kroku na iný origin, než bol prvý, sa zahodia prihlasovacie údaje (pozrite Presmerovania).
- Pridajú sa voľby pripnutia, ktoré majú prednosť pred voľbami volajúceho (nižšie). Ak z rozpočtu zostáva menej než milisekunda: DestinationUnavailable (timeout).
- Pripnutý handler tesne pred curl požiadavku znovu skontroluje: schéma, hostiteľ a port sú overené, hlavička Host uvádza toho istého hostiteľa a port, proxy je vypnutá, presmerovania sú vypnuté, pripnutia aj kontrola pred odoslaním sú nedotknuté a nepribudla žiadna voľba curl mimo zoznamu povolených. Čokoľvek iné je cannot_pin a nič sa nevytočí.
- Kontrola pred odoslaním (CURLOPT_PREREQFUNCTION): keď sa curl pripojí, a ešte pred odoslaním prvého bajtu, musí byť pripojená adresa a port v overenej množine; inak curl spojenie preruší → cannot_pin. Server uvidí spojenie, ale nič v ňom.
- Kontrola po odoslaní: primary_ip zo štatistík prenosu musí byť v overenej množine; inak cannot_pin, nahlásené a oznámené ako DestinationRefused. Štatistiky z Http::fake() sa nekontrolujú. Váš vlastný on_stats sa zavolá aj tak.
- Presmerovanie, ktoré pravidlá sledujú, sa stane ďalším krokom.
[
'proxy' => '', // no proxy at all, environment proxies included
'allow_redirects' => false, // redirects are the guard's
'protocols' => [$scheme], // Guzzle 7.11+; older 7.x ignore it (the scheme is vetted)
'curl' => [
CURLOPT_RESOLVE => ['host:port:a.b.c.d,[v6::1]'], // every vetted address, one entry; none for a literal
CURLOPT_FRESH_CONNECT => true,
CURLOPT_FORBID_REUSE => true,
CURLOPT_PREREQFUNCTION => $preSendCheck, // libcurl 7.80+, not Guzzle 7.12.x
],
'timeout' => <what is left of the budget>,
]Voľby, ktoré ochrana odmietne
UnsafeRequestOptions — chyba programátora, vyhodená výnimkou s názvom voľby — pre čokoľvek, čo by požiadavku vyviedlo mimo ochranu:
- allow_redirects s inou hodnotou než false (->maxRedirects() po safe()) — presmerovania zapnite v pravidlách.
- Proxy zvolená volajúcim (withOptions(['proxy' => …]), Http::globalOptions()). Proxy, ktoré len opakujú prostredie (HTTP_PROXY, HTTPS_PROXY, NO_PROXY), sa obídu, neodmietnu: proxy si meno prekladá sama.
- transport_sharing na úrovni požiadavky.
- Surová voľba curl mimo zoznamu povolených: CURLOPT_ENCODING, HTTPAUTH, USERPWD, SSL_CIPHER_LIST, TLS13_CIPHERS, SSL_EC_CURVES, CERTINFO, LOW_SPEED_LIMIT, LOW_SPEED_TIME, TCP_KEEPALIVE, TCP_KEEPIDLE, TCP_KEEPINTVL, TCP_KEEPCNT, TCP_NODELAY, TCP_FASTOPEN, HAPPY_EYEBALLS_TIMEOUT_MS, MAXAGE_CONN a MAXLIFETIME_CONN. Všetko ostatné — RESOLVE, CONNECT_TO, UNIX_SOCKET_PATH, INTERFACE, DNS_*, PROXY*, PRE_PROXY, SSL_VERIFYPEER … — zlyhá bezpečne.
- sink spolu s maxResponseBytes.
- Vlastný klient (setClient()), Guzzle voľba handler alebo požiadavka, ktorá už je chránená.
Odmietnutia ochrany (DestinationRejected, DestinationUnavailable) prídu nezabalené — Laravel z nich nespraví RequestException ani ConnectionException. Výnimka z kódu vnútri ochrany (StrayRequestException z Http::fake(), rate limiter pridaný po safe(), uvoľnenie úlohy vo fronte) sa k volajúcemu dostane tak, ako bola vyhodená. Chyba prenosu chránenej požiadavky je vlastná ConnectionException Laravelu, ktorej správa obsahuje URL adresu — nikdy ju nezobrazujte koncovému používateľovi.
Pooly
Ochrana nahradí handler poolu svojím pripnutým handlerom — jedným na pool, spoločným pre jeho chránené požiadavky — takže pool zostane súbežný, pričom nové spojenia a kontrola pred odoslaním pri každom kroku udržia každú požiadavku v jej vlastnej overenej množine. Dve požiadavky na rovnakého hostiteľa a port s rôznymi overenými množinami sa odmietnu, nezmiešajú. Výsledkom odmietnutej požiadavky je výnimka:
use Illuminate\Http\Client\Pool;
$responses = Http::pool(fn (Pool $pool): array => [
$pool->safe()->get('https://hooks.example/a'),
$pool->safe()->get('https://inward.example/b'),
]);
$responses[0]->body(); // the answer
$responses[1]; // a DestinationRejected when the guard refused that memberOpakovanie
retry() prechádza zásobníkom znovu, takže sa overí každý pokus. Laravel opakuje pri každej výnimke, ak callback when nepovie inak — aj pri odmietnutí — preto skončite pri prvom:
Http::safe()->retry(3, 100, fn (Throwable $e) => ! $e instanceof SafeFetchException)->post($url, $payload);Ďalší middleware
Poradie je na vás. Obmedzovač pridaný pred ochranu beží raz na volanie, ešte pred prekladom DNS; pridaný po safe() beží pri každom kroku. Uprednostnite prvé:
// Runs once per call, before any DNS lookup — prefer this order
Http::withMiddleware($throttle)->safe()->post($url, $payload);
// http-client-rate-limits-for-laravel's macro works the same way
Http::rateLimit(30)->safe()->post($url, $payload);Limit odpovede — maxResponseBytes
Bez stream => true curl stiahne celé telo skôr, než ho uvidíte (2 MB telo príde ako 2 MB v pamäti). Na obmedzenie odpovede nastavte limit v pravidlách:
$response = Http::safe(SafeFetch::policy()->maxResponseBytes(4096))->post($url, $payload);
$response->status(); // the real status
$response->body(); // at most 4 096 bytes
SafeFetch::truncated($response); // true when the body was cut
$response->handlerStats()['primary_ip'] ?? null; // the address it connected to, truncated or not- Telo dlhšie než limit sa oreže a prenos preruší — nech ho server posiela akokoľvek (bez Content-Length, po častiach, komprimované: počítajú sa dekódované bajty).
- Odpoveď si ponechá stav aj hlavičky a pribudne jej Safe-Fetch-Truncated: 1. Telo presne vo veľkosti limitu značku nedostane.
- Ochrana z každej odpovede odstráni hlavičku Safe-Fetch-Truncated poslanú serverom, s limitom aj bez neho, takže ju nastaví len vlastné orezanie ochrany.
- Sink patrí ochrane: sink volajúceho spolu s limitom sa odmietne. fetch() a download() majú vlastný limit, ktorý namiesto orezania zlyhá.
Ak chcete obmedziť každú chránenú požiadavku bez pravidiel pre každé volanie, nastavte request.max_bytes (SAFE_FETCH_REQUEST_MAX_BYTES): SafeFetch::policy() — predvolené pravidlá za Http::safe() — ho potom nesie. Kým je nastavený, vlastný sink požiadavky sa odmietne, preto ho pre volanie, ktoré do sinku zapisuje, zrušte.
Pri stream => true limit namiesto orezania zlyhá — pozrite Streamované odpovede.
Streamované odpovede
Od verzie 1.2.0. Požiadavka odoslaná so stream => true sa vráti hneď, ako prídu hlavičky posledného kroku, a jej telo je stream PSR-7, ktorý sa číta tak, ako ho server posiela — server-sent events, prúd tokenov od poskytovateľa LLM, dlhý export. Funguje z každého vstupného bodu: Http::withOptions(['stream' => true])->safe(), SafeFetch::guard() / http(), SafeFetch::handlerStack() a SafeFetch::guzzleClient():
$body = Http::withOptions(['stream' => true])
->safe(SafeFetch::policy()->maxResponseBytes(10_000_000)->readTimeout(30))
->post($llmUrl, $payload)
->toPsrResponse()->getBody();
while (! $body->eof()) {
$chunk = $body->read(1024); // what has arrived; waits only when nothing has
}
$body->close(); // stop early: the transfer ends and its curl handles are freedVšetky ochrany zostávajú zapnuté. Každý krok sa overí, pripne cez CURLOPT_RESOLVE a skontroluje pred odoslaním prvého bajtu (CURLOPT_PREREQFUNCTION). Presmerovania sa sledujú a overujú pri každom kroku a streamuje sa len telo posledného kroku — telo presmerovania sa nikdy nečíta. Platia pravidlá pre porty, schémy a rozsahy aj časový limit: timeout pokrýva celý stream od hlavičiek po posledný bajt. Pod kapotou je to stále curl z Guzzle; každá streamovaná požiadavka má vlastný multi handle, ktorý beží, len kým čakáte na odpoveď alebo čítate jej telo.
| Streamované (stream => true) | Nestreamované | |
|---|---|---|
| Odpoveď sa vráti | pri hlavičkách posledného kroku | po celom tele |
maxResponseBytes | zlyhá: deklarovaný Content-Length nad limitom ešte pred telom, iné telo pri čítaní za limit (FetchFailed, too_large) | oreže telo, pridá Safe-Fetch-Truncated: 1 |
| Limit nečinnosti | readTimeout / read_timeout: FetchFailed (timeout) | ochrana vlastný nemá |
| Prerušenie uprostred tela | vyhodí read() ako typovaný FetchFailed (timeout, connection, tls, …) | vyhodí požiadavka |
on_stats / handlerStats() | po prečítaní tela do konca | s odpoveďou |
- Limit nečinnosti: DestinationPolicy::readTimeout(int $seconds) — alebo request.read_timeout (SAFE_FETCH_REQUEST_READ_TIMEOUT) — ukončí stream, ktorý toľko času nič nepošle, pred hlavičkami alebo medzi dvoma časťami tela. Platí aj vlastný read_timeout požiadavky a kratší má prednosť. Celkový timeout platí navyše. Oba sú vypnuté, kým ich nenastavíte, a týkajú sa len streamovaných požiadaviek.
- Voľby volajúceho: progress, on_headers, on_stats a read_timeout prejdú ďalej. sink sa v režime streamu ignoruje, rovnako ako ho ignoruje stream handler z Guzzle. Výnimka, ktorú vyhodí niektorý váš callback, sa z read() vráti presne tak, ako bola vyhodená.
- Predčasné ukončenie: $body->close(), alebo jednoducho uvoľnenie odpovede, zastaví prenos a uvoľní jeho curl handles. Server uvidí zatvorenie spojenia.
- body() a (string) stále fungujú: prečítajú stream do konca a vyhodia rovnaký FetchFailed ako read().
- Http::fake() odpovedá na streamované požiadavky ako na každé iné, keďže fake sa k handleru nikdy nedostane. Telo stubu sa číta cez rovnaký limit bajtov, takže test uvidí rovnaké too_large ako skutočný stream.
- Pooly a async: streamovaná požiadavka pri odoslaní počká na hlavičky, takže v Http::pool() alebo getAsync() sa streamovaní členovia dovtedy neprekrývajú. Ich telá sa potom čítajú nezávisle.
- Kde sa streamuje: len tam, kde beží kontrola pred odoslaním — PHP 8.4 s libcurl 7.80+, na akomkoľvek Guzzle okrem 7.12.x. Bez tejto kontroly by skôr vydané hlavičky mohli prísť z adresy, ktorú ešte nikto neoveril, preto sa taká požiadavka prijme celá a skontroluje dodatočne, presne ako bez stream (limit potom oreže).
Časový limit — timeout
Laravel dáva každej požiadavke časový limit 30 sekúnd, no volajúci ho môže zvýšiť alebo vypnúť (timeout(0)) a klient Guzzle, ktorý si zostaví knižnica, nemá žiadny. timeout v pravidlách je nad tým strop: SafeFetch::policy()->timeout(10), alebo request.timeout (SAFE_FETCH_REQUEST_TIMEOUT) pre každú chránenú požiadavku. Ochrana potom dá požiadavke min(jej vlastný limit, strop) — strop, ak vlastný nemá — ako jeden rozpočet pre všetky kroky; krok, ktorému by zostala menej než milisekunda, zlyhá ako timeout, ktorý sa dá zopakovať (DestinationUnavailable). Predvolene vypnuté; timeout(null) ho pre jedno volanie zruší a fetch() a download() majú vlastný fetch.timeout:
// Every guarded request — Http::safe(), guard(), http() and the guarded Guzzle stack
// SAFE_FETCH_REQUEST_MAX_BYTES=1048576
// SAFE_FETCH_REQUEST_TIMEOUT=20
// Or per call: a ceiling of 10 s over every hop, a 1 MB body cap
Http::safe(SafeFetch::policy()->timeout(10)->maxResponseBytes(1_048_576))->get($url);
// Lift them for one call — a sink is refused while a body cap is set
Http::safe(SafeFetch::policy()->maxResponseBytes(null))->sink($path)->get($url);
Http::safe(SafeFetch::policy()->timeout(null))->timeout(120)->get($url);Pripnutie požiadavky, ktorú si zostavíte sami
$vetted = SafeFetch::vet($url);
Http::withOptions($vetted->pinningOptions())->get($vetted->url);pinningOptions() je pole volieb vyššie bez kontroly pred odoslaním; spolieha sa, že handler voľby curl dodrží, a žiadny krok sa znovu nekontroluje. Uprednostnite SafeFetch::guard().
Kompatibilita s Guzzle
illuminate/http 13 povoľuje guzzlehttp/guzzle ^7.8.2 || ^8.0. Voľby pripnutia používajú len to, čo prijíma každá z týchto verzií:
| Guzzle | Poznámky |
|---|---|
7.8.2 | Spodná hranica, testovaná vo vetve prefer-lowest. Bez voľby protocols (ignoruje sa; schéma sa aj tak overuje). Composer predvolene blokuje vydania Guzzle s bezpečnostnými upozorneniami — na takom Guzzle odporúčame aktualizovať. |
7.12.0–7.12.3 | CURLOPT_PREREQFUNCTION je tam označená ako zastaraná (opravené v 7.13.0), preto sa kontrola pred odoslaním preskočí; kontrola primary_ip po požiadavke zostáva a stream => true sa prijme celý. |
7.16.x | Testované; testy zlyhajú pri akomkoľvek upozornení na zastaranie, aj potlačenom cez @. |
8.x | Testované na každej verzii PHP (8.4, 8.5, 8.6). |
Vlastný klient Guzzle knižnice sa na tú istú ochranu dostane cez SafeFetch::guzzleClient() a SafeFetch::handlerStack() — pozrite Klienti tretích strán.
Prejavte lásku k open source
Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.
Ďalšie spôsoby podpory vrátane kryptomienOdoslaním daru súhlasíte s našimi podmienkami prijímania darov.
Chcete to zabudovať do svojho produktu?
Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.