Fix cache-key asymmetry, cache TOCTOU, response decode robustness, encoding leak

[fabcocco]

Four robustness fixes in BaseApi, found during an adversarial audit of a consuming application (the data-hub ERPlus gateway). All are backwards compatible — no signature changes, suggested as a patch release (v2.0.1).

1. Cache-key asymmetry — keyed-endpoint cache could never hit

getCacheKey() built the key from the raw endpoint (with :param placeholders) plus the request data. getEndpoint() consumes :param entries from $this->requestData while resolving the URL, so:

• the lookup key (computed in loadResponseFromCache(), before resolution) contained the placeholder endpoint + the param in the data, while
• the store key (computed in cacheResponse(), after resolution) contained the same raw endpoint but without the consumed param.

The two keys never match for keyed endpoints (modelFind-style entity/:id calls), so their responses were written to the cache but never read back. The key is now built from the resolved endpoint (getEndpoint() is idempotent via $endpointCache), making lookup and store symmetric.

2. Cache TOCTOU → TypeError

loadResponseFromCache() used Cache::has() followed by Cache::get(). An entry expiring between the two calls assigns null to the typed array|object $response property → uncaught TypeError. Now a single get() with a sentinel default (plus a type guard on the cached value).

3. Response decode robustness — scalar/invalid/empty bodies crashed

setResponse() assigned json_decode($response->body()) directly to the typed array|object property:

• invalid JSON / empty body → null → opaque TypeError;
• JSON scalar bodies (e.g. a bare string returned by RPC-style actions — ERPlus' getnxtposnr / getnextworkordernumber declare 200 → {"type": "string"}) → TypeError on every successful call.

Now: invalid JSON throws a descriptive Exception, an empty body becomes an empty stdClass (e.g. 204 on DELETE), and scalars are wrapped as (object) ['value' => …] so the array|object contract keeps holding.

4. Temporary request-encoding leak on transport failure

setTemporaryRequestEncoding() is only restored inside setResponse(). If the request itself throws before a response exists (connection refused/timeout), the temporary encoding leaked into the subsequent call on the same instance — relevant for singletons. executeCall() now restores it on any throw (restoreRequestEncoding() is a no-op when nothing is pending).

---

Also casts $requestEncoding for strtolower() to avoid the PHP 8.4 passing null to non-nullable deprecation (the property is ?string and defaults to null).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR improves BaseApi robustness around caching, request encoding handling, and JSON response decoding to prevent cache misses, TOCTOU-related type errors, and response-body decoding crashes.

Changes:

• Makes cache keys symmetric by basing them on the resolved endpoint (so keyed endpoints can actually hit the cache).
• Eliminates cache has()/get() TOCTOU by using a single Cache::get() with a sentinel and validating cached types.
• Adds resilient response decoding (decodeResponseBody) to handle empty bodies, invalid JSON (with a descriptive exception), and JSON scalars (wrapped to preserve the array|object contract), and ensures temporary request encoding is restored even when the transport throws.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.