The SafeFetch facade

Everything goes through one facade, RoundlyConsulting\SafeFetch\Facades\SafeFetch (global alias SafeFetch), sugar over the SafeFetchManager singleton, plus the Http::safe() macro on Laravel’s HTTP client:

use Illuminate\Support\Facades\Http;
use RoundlyConsulting\SafeFetch\Facades\SafeFetch;

Http::safe()->withToken($token)->post($url, $payload);          // guard any Laravel request
SafeFetch::guard(Http::withToken($token), $policy)->post($url);  // the same, without the macro
SafeFetch::http($policy)->get($url);                             // a new guarded request

$vetted = SafeFetch::vet($url);              // VettedDestination, or DestinationRejected / DestinationUnavailable
SafeFetch::allows($url);                     // bool — never throws a verdict
SafeFetch::precheck($url);                   // CanonicalUrl — every rule except the DNS lookup

$page = SafeFetch::fetch($url, maxBytes: 1_000_000);              // a capped GET into memory
$file = SafeFetch::download($url, $path, maxBytes: 50_000_000);   // the same GET, streamed to a file
SafeFetch::truncated($response);             // was a guarded response cut at maxResponseBytes?

SafeFetch::policy();                         // the configured DestinationPolicy, to tighten or loosen per call
SafeFetch::networks()->isPrivate('169.254.169.254');                    // true — cloud metadata
SafeFetch::urls()->canonicalise('HTTPS://Example.COM.:443/a?b#frag');   // CanonicalUrl: https://example.com/a?b

Manager methods

Once SafeFetch::fake() is installed, every assertion of the fake is callable on the facade too — see Testing. vetHop() is public on the manager but internal: it is the guard middleware’s per-hop call, so the fake sees every hop. SafeFetchManager::TRUNCATED_HEADER ('Safe-Fetch-Truncated') names the truncation header.

The Http::safe() macro

PendingRequest::safe(?DestinationPolicy $policy = null): PendingRequest gives Http::safe(), Http::withToken($t)->safe() and $pool->safe(). Another package registering a safe macro after this one would replace it silently, so security-critical code calls SafeFetch::guard() or SafeFetch::http() instead.

Data objects

In RoundlyConsulting\SafeFetch\DataTransferObjects, all final readonly:

Other public types: Enums\Reason and the exceptions (Verdicts and exceptions), Contracts\HostResolver and Support\SystemHostResolver, Support\PrivateNetworks (URLs and blocked networks), Rules\SafeUrl, Commands\CheckCommand, Events\DestinationRefused, and Testing\SafeFetchFake, Testing\FakeHostResolver and Testing\RecordedVet. Everything else under Support\ and Http\ is internal.