UpstreamClient
Calls the endpoints of one upstream API from a base URL, composing a response cache, a call budget and a transport in one fixed order: the policy's pre-check, then the cache, then the budget inside the cache's loader, then the transport. A hit costs nothing and N coalesced callers cost one permit and one request. Stable Core.
Per call (
call): path segments, query pairs, headers, method, body, lane,maxWaitandmaxAge(aCallSpec); only aGETis cached. The key is the endpoint id, the full request path and the query pairs; never a header (so never a credential sent in one), the body, the lane ormaxAge. A credential passed as a query pair is part of the key, as every query pair is. A shared load runs the first caller's request: per-call headers must not change the answer for a cached endpoint, and a caller with a tighter deadline wraps its owncallinwithTimeoutOrNull.Outcome:
Found(value)(stored forttl),Missing(a declared miss status, stored formissTtl), or a failure, never stored: a throttle isRateLimited(no retry), a2xxthe decoder rejects isDecodeFailure, any other status isUpstreamError, and the transport's, budget's and cache's failures pass through. Match the groups you care about and keep anelse.What a call spends: a closed client, an
InvalidRequestthe client raises and the pre-check's policy refusal are decided before the cache: no permit, no request, nothing cached. A hit and a caller that joins a load in flight spend nothing, and a budget refusal (BudgetExhausted,Closed("budget")) sends nothing. Once a permit is granted, a response of any status spends it, and only anInvalidRequestfrom the transport gives it back, because only that proves nothing was sent. Every other failure the transport returns (a refusal the transport makes of a redirect target or a resolved address included), a cancellation and anErrorleave the permit spent, so a window that guards a bill is never under-counted.Ownership: the common factory owns only a budget built from
budget(windows); the JVM owning factory owns the transport, the cache (unlesscache(...)was called) and the budget it built.close()closes what the client built, in the order cache, budget, transport, never what it was handed; it is non-suspending, idempotent, never throws and safe from any thread. Call flush beforeclose()for the exact final write of a budget with a persistent store; utilisation, cacheStats and flush keep working afterclose().Logging, under
com.spartanlabs.webtools.http.UpstreamClient:INFOonce on creation and once onclose();DEBUGonce per call that passed the pre-check and returned (the endpoint id, method, whether this call's loader ran, lane, cost, status, byte count, timings and the outcome's name), for anInvalidRequestthe client raises (the endpoint id and its rule), for aDecodeFailure(the endpoint id and the cause's class name) and for a close step that threw;WARNfor a pre-check refusal, a throttle and a rate-signal reader orutilisation()that throws. AnInvalidRequest, a pre-check refusal, a throttle and aDecodeFailureare each logged once, where the client creates them (a throttle and aDecodeFailureonce per load, however many callers share it); anUpstreamErrorhas no line of its own and shows only as the outcome of the per-call line, andClosed("client")is not logged. Never a header value, a body, a query string or a decoded value, so never a credential sent in a header or a query pair. A URL is printed withUrl.redacted(), which shows the path and hides the query, and the endpoint id is printed as given: keep credentials out of path segments, the base URL's path and endpoint ids. The cache, the budget and the transport log under their own names.
Every member may be called concurrently from any thread and coroutine.