feat: add resolver and redirect controls for source requests (1.14.x)

[abnegate]

Backport of #229 to the 1.14.x line (PHP 8.2+, appwrite/appwrite ^26). The Appwrite SDK client is covered by overriding SDK 26 Client::call() instead of SDK 30's createHttpClient(), and the SDK is not bumped.

What

Target::call() gains three controls:

• HTTP and HTTPS only. CURLOPT_PROTOCOLS and CURLOPT_REDIR_PROTOCOLS are set to CURLPROTO_HTTP | CURLPROTO_HTTPS, so an endpoint or redirect with any other scheme (file, gopher, dict, ...) is refused by curl. The bitmask options are used because CURLOPT_PROTOCOLS_STR needs PHP 8.3.
• No redirect following by default. A 3xx response throws an exception with the status as its code instead of being returned as the body. setFollowRedirects(true) turns following back on.
• Optional resolver. setResolver(?Closure) takes a callback that receives each request URL and returns the CURLOPT_RESOLVE entries (host:port:address[,address]) the connection must use, so curl connects to addresses the consumer has already validated instead of resolving the host again. The callback can throw to refuse a URL.

Appwrite source SDK client

Most Appwrite source requests go through the Appwrite PHP SDK client rather than Target::call(). SDK 26 does its cURL work inline in Client::call(), so the source now builds its client from Sources\Appwrite\Client, a subclass that overrides call() with the SDK 26 behaviour except that:

• redirects are never followed; a 3xx raises an AppwriteException with the status as its code, as Target::call() does (responseType: 'location' still returns the Location header);
• only http and https are allowed;
• setResolver() takes the same callback as Target, called with each request URL, and its CURLOPT_RESOLVE entries apply to that request.

Sources\Appwrite::setResolver() passes the resolver to both Target::call() and the SDK client.

Why

Consumers that validate a source endpoint before running a migration need every request to reach the address they approved. Appwrite 1.9.x stays on PHP 8.3 and utopia-php/migration 1.14, so it needs these controls without the SDK 30 upgrade.

Behaviour change

Redirects are no longer followed unless a consumer opts in, so an endpoint that answers with a redirect (for example http:// to https://) now fails with that status instead of being followed. This also applies to the Appwrite source's SDK requests, which SDK 26 previously followed. Without a resolver, connections resolve exactly as before.

Tests

tests/Migration/Unit/General/TargetRequestTest.php runs against a local php -S fixture:

• a 302 is not followed by default (one request reaches the fixture), and is followed with setFollowRedirects(true);
• a followed redirect to file:// is refused;
• a resolver pins pinned.invalid to 127.0.0.1 and receives the full request URL;
• a resolver that throws stops the request before it is sent;
• gopher://, dict:// and file:// endpoints are refused.

tests/Migration/Unit/Sources/AppwriteClientTest.php uses the same fixture for the SDK client:

• a 302 raises AppwriteException with code 302, and only one request reaches the fixture;
• responseType: 'location' still returns the redirect target;
• a resolver pins pinned.invalid for every request and receives each request URL;
• a resolver that throws stops the request before it is sent;
• Sources\Appwrite::setResolver() reaches the SDK client: report() sends GET /v1/users to the pinned host.

With Target.php reverted, all 8 TargetRequestTest cases fail. With the call() override disabled, 4 of the 5 AppwriteClientTest cases fail; the location case guards existing behaviour. The unit suite passes on PHP 8.2, 8.3 and 8.5, and pint --test and phpstan --level 3 pass.

🤖 Generated with Claude Code

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.