NovinkaZverejnili sme 50+ Laravel balíkov ako open source
Custom AI apps, agents and automation — Roundly ConsultingRoundly
Všetky balíky
Safe Fetch for Laravel

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 member

Opakovanie

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 freed

Vš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átipri hlavičkách posledného krokupo celom tele
maxResponseByteszlyhá: 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činnostireadTimeout / read_timeout: FetchFailed (timeout)ochrana vlastný nemá
Prerušenie uprostred telavyhodí read() ako typovaný FetchFailed (timeout, connection, tls, …)vyhodí požiadavka
on_stats / handlerStats()po prečítaní tela do koncas 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í:

GuzzlePoznámky
7.8.2Spodná 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.3CURLOPT_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.xTestované; testy zlyhajú pri akomkoľvek upozornení na zastaranie, aj potlačenom cez @.
8.xTestované 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 kryptomien

Odoslaní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.