feat(spec-loader): resolve HTTP(S) external $refs via opt-in PSR-18 client (#108, PR 2/2)

[wadakatu]

Summary

Closes #108. Builds on PR 1/2 (#119) which added local-filesystem ref support.

The resolver now follows $ref paths to HTTP(S) URLs when the user opts in:

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;

OpenApiSpecLoader::configure(
    basePath: 'openapi/',
    httpClient: new Client(),         // any PSR-18 implementation
    requestFactory: new HttpFactory(), // any PSR-17 implementation
    allowRemoteRefs: true,
);

// Now this works:
// $ref: 'https://example.com/schemas/pet.yaml'
// $ref: 'https://example.com/schemas/pet.yaml#/Pet'
// $ref: 'https://registry.example.com/Pet'   (Schema Registry, no extension)

Design decisions (chat-confirmed)

• PSR-18 + PSR-17 directly — the two interfaces are passed as discrete typed parameters. Users wire whichever HTTP client they already have (Guzzle, Symfony HttpClient, Buzz, ...). Library stays implementation-agnostic.
• Two-knob opt-in — httpClient set without allowRemoteRefs: true triggers E_USER_WARNING at configure() time so the misconfiguration doesn't sit silent. Belt + suspenders prevents accidental network calls.
• RefResolutionContext DTO — bundled into this PR (S3 from feat(spec-loader): resolve local-filesystem external $refs (#108, PR 1/2) #119 review). The walk()/resolve() signatures already had 6 params; adding 3 more for HTTP would have crossed into unmaintainable territory.

Failure modes — all surfaced precisely

Setup	Result
allowRemoteRefs: true + missing client/factory	InvalidArgumentException at configure()
httpClient set + allowRemoteRefs: false	E_USER_WARNING at configure()
HTTP $ref + allowRemoteRefs: false	RemoteRefDisallowed
HTTP $ref + flag on + missing client/factory	HttpClientNotConfigured
HTTP $ref + opt-in + 4xx/5xx/network error	RemoteRefFetchFailed
HTTP $ref + URL has no .json/.yaml AND no JSON/YAML Content-Type	UnsupportedExtension

RemoteRefNotImplemented from PR 1/2 is @deprecated (kept for callers branching on it).

Test plan

• HttpRefLoaderTest (13 tests): URL-extension + Content-Type format detection (incl. application/*+json, application/yaml, text/yaml), per-call cache, 404/5xx/network error mapping, malformed body, non-mapping root
• OpenApiRefResolverHttpRefsTest (12 tests): opt-in success path, fragments, multi-hop HTTP chains, cross-file HTTP cycles, cross-source local↔HTTP chains, sibling fragment URL reuse, opt-in/wiring failure modes, JSON Pointer escapes (~1/~0) in remote fragments, missing fragment, trailing-hash rejection
• OpenApiSpecLoaderTest (3 new tests): configure-time InvalidArgumentException, E_USER_WARNING for wired-but-disabled, no-warning happy path
• Existing 717+ tests untouched (DTO refactor preserves backward compat via optional defaults)
• PHPUnit: 745 tests / 1481 assertions
• PHPStan level 6: 0 errors
• PHP-CS-Fixer: 0 violations
• Tests run offline — FakeHttpClient returns canned responses; no real network calls

New types / classes

• RefResolutionContext (DTO, public) — immutable carrier for sourceFile + httpClient + requestFactory + allowRemoteRefs
• Internal\HttpRefLoader — PSR-18 fetch + decode
• Internal\SpecDocumentDecoder — shared JSON/YAML decoder for both ExternalRefLoader and HttpRefLoader
• Tests\Helpers\FakeHttpClient — minimal PSR-18 test double

Dependencies

require (interface-only packages, ~zero size impact):

• psr/http-client: ^1.0
• psr/http-factory: ^1.0
• psr/http-message: ^1.0 || ^2.0

require-dev:

• guzzlehttp/psr7: ^2.0 (test PSR-7 implementations)

suggest: guzzlehttp/guzzle, symfony/http-client as concrete client examples.

README updates

• Comparison table: External $ref auto-resolution ❌ → ✅
• New section "HTTP $ref resolution (opt-in)" documents wiring, failure modes, format detection, and security stance
• Setup section rewritten: pre-bundling no longer required for internal/local refs; Redocly remains supported for users on the legacy bundled-spec workflow

Out of scope (future issues)

• Global / cross-call HTTP cache (TTL, invalidation)
• URL allowlist / SSRF defense (current trust model: allowRemoteRefs: false default + spec author trust)
• Auth headers / proxy / timeout configuration (user's PSR-18 client handles these)
• ResponseValidationContext DTO from PR feat(response-validator): validate response headers against spec (#110) #120 review (separate concern)

Closes

Closes #108

[wadakatu]

Review feedback addressed (Round 1 + 2 + 3)

Pushed commit af24bbf covering all Critical, Important, and applicable Suggestion findings from the multi-agent review. Quality gates: PHPUnit 757 tests / 1502 assertions (+12), PHPStan level 6 clean, PHP-CS-Fixer clean.

Round 1 (Critical) — fixed

#	Fix
C1	getBody()->getContents() inside try/catch surfaces stream I/O errors as RemoteRefFetchFailed instead of mis-classifying as MalformedJson
C2	Relative refs inside HTTP-loaded documents resolve against the source URL per RFC 3986 (./pet.yaml inside https://example.com/openapi.json → https://example.com/pet.yaml). Previously would have produced a confusing LocalRefNotFound. New tests pin the relative / parent-dir / absolute-path variants
C3	FakeHttpClientUnexpectedRequest moved to its own file. PSR-4-strict autoloaders now find it when imported standalone

Round 2 (Important) — fixed

#	Fix
I1	README adds composer require --dev guzzlehttp/guzzle install hint and notes Guzzle 7+ is required for PSR-18
I2	E_USER_WARNING for "client wired without flag" promoted to InvalidArgumentException. Warnings are silenceable; hard exceptions are not
I3	YAML decode catch broadened from ParseException to Throwable so malformed-Unicode \InvalidArgumentException and OOM \Error land as MalformedYaml
I4	3xx redirects produce a dedicated message including Location header + hint to enable redirect-following on the PSR-18 client
I5	ExternalRef enum @deprecated docblock points at the actual concrete cases (no longer chains to the also-deprecated RemoteRefNotImplemented)
I6	OpenApiRefResolver::resolve() docblock corrected: "non-internal" → "filesystem-relative" (HTTP refs go through resolveHttpRef)
I7	README "Schema Registry endpoints work out of the box" rewritten to avoid the third-party trademark; test prose similarly cleaned
I8	New test pins 3xx → RemoteRefFetchFailed with Location-bearing message
I9	New test confirms second resolve() call re-fetches (per-resolution cache, not per-process)
I10	New reset_clears_http_client_and_remote_flag_state test confirms reset() clears HTTP wiring (post-reset re-configure with allowRemoteRefs:true + no client correctly throws)
I11	userinfo (https://user:pass@host/...) redacted from all error messages and exception ref fields. New test pins this — credentials no longer leak into CI logs
I12	OpenApiSpecLoader::configure() evicts the spec cache so a policy change (especially flipping allowRemoteRefs) takes effect on the next load() instead of silently serving the prior resolved spec
I13	Multi-hop HTTP fetch failures wrap the message with (via $ref chain: A -> B -> C) so a 4-hops-deep failure points at the originating spec entry

Plus S5 (extension-wins-over-Content-Type), S6 (empty Content-Type), and S7 (duplicate Content-Type comma split) all got dedicated tests.

Round 3 (Type design) — fixed

#	Fix
S1	RefResolutionContext constructor made private. New named factories filesystemOnly() and withRemoteRefs($client, $factory, $sourceFile) enforce the "client + factory + flag together OR none" pairing at the type level. Constructing an invalid combo is now structurally impossible
S2	New Internal\LoadedDocument readonly DTO replaces the divergent array{absolutePath, decoded} / array{absoluteUri, decoded} shapes. Both ExternalRefLoader and HttpRefLoader return LoadedDocument(canonicalIdentifier, decoded) so the resolver's chain-key logic is uniform across filesystem and HTTP loads
S3, S4	Comment cleanup: canonicalizeUri docblock trimmed; "Schema Registry hybrid" prose neutralised

Diff stats vs first push

15 files changed, 690 insertions(+), 142 deletions(-) — production: ~150 lines net (mostly the new RFC 3986 helper + LoadedDocument DTO + redaction); tests: +250 lines; new files: LoadedDocument.php, FakeHttpClientUnexpectedRequest.php.