feat(http): client IP address behind trusted proxies

[osbre]

Right now, getting the IP address a request came from means digging into $_SERVER yourself. The PSR request has it in REMOTE_ADDR, but the mapper to GenericRequest throws the server params away.

This PR adds Request::$ip:

#[Get(uri: '/aircraft')]
public function index(Request $request): View
{
    $ip = $request->ip;
}

It's null when the server doesn't report an address. In tests, fromIp sets it:

$this->http
    ->fromIp('203.0.113.9')
    ->get('/aircraft')
    ->assertOk();

Trusted proxies

Behind a reverse proxy you get the proxy's address, and the client's real one sits in a header like X-Forwarded-For. Anyone can set that header, so it's only read if the request came through a proxy you've declared. Nothing is trusted by default:

use Tempest\Http\Ip\TrustedProxiesConfig;

return new TrustedProxiesConfig(
    proxies: ['10.0.0.0/8'], // or PRIVATE_RANGES, or ANY
);

Addresses and CIDR ranges both work, IPv4 and IPv6. In a chain of hops, the closest one that isn't a trusted proxy is the client. Header names are configurable too, for the likes of Cloudflare. Docs included, under routing.

Notes

• ip is now a reserved request parameter name, since it's a property on the Request interface. If a payload has a field called ip and gets mapped onto a custom request object, it'll throw RequestParametersIncludedReservedNames, same as it already does for path, query and so on. Probably worth a line in the release notes.
• Went with ip rather than clientIp to keep it short, like Laravel's $request->ip().
• The range matching lives in Tempest\Support\Ip rather than the HTTP package, since it seemed generally useful: matches(), matches_any(), is_private().

Included changes

• Request::$ip on the interface and in IsRequest
• TrustedProxiesConfig and ClientIpResolver in Tempest\Http\Ip, Tempest\Support\Ip functions and PRIVATE_RANGES
• PsrRequestToGenericRequestMapper resolves the address, RequestToPsrRequestMapper writes it back for the tester's dispatch, and RequestToObjectMapper carries it onto custom request objects
• HttpRouterTester::fromIp(), across all verb methods and makePsrRequest
• Docs and tests

[github-actions]

Benchmark Results

Comparison of feat/request-client-address against 3.x (a31bbcd4e9b619df48af987f383376a631d90f03).

Open to see the benchmark results

No benchmark changes above ±5%.

_{Generated by phpbench against commit f7a2476}

[xHeaven]

Perhaps we could make this a bit more exhaustive if we're adding it. SERVER_ADDRREMOTE_ADDR doesn't always contain the client's real IP address, especially behind Cloudflare, Docker and other services. What do you think?

[osbre]

@xHeaven You mean REMOTE_ADDR, yes. Updated to include trusted proxies and relevant IP helpers under support package, hopefully that's not too many changes for one PR.

[osbre]

Sorry, accidentally did a force-push by clicking GitHub's "Update branch via Rebase" button... wasn't expecting my commit history to go up the list again 👀 makes it look as if I did new changes ugh

That said, I renamed those functions back as requested.