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, maxWait and maxAge (a CallSpec); only a GET is 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 or maxAge. 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 own call in withTimeoutOrNull.

  • Outcome: Found(value) (stored for ttl), Missing (a declared miss status, stored for missTtl), or a failure, never stored: a throttle is RateLimited (no retry), a 2xx the decoder rejects is DecodeFailure, any other status is UpstreamError, and the transport's, budget's and cache's failures pass through. Match the groups you care about and keep an else.

  • What a call spends: a closed client, an InvalidRequest the 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 an InvalidRequest from 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 an Error leave 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 (unless cache(...) 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 before close() for the exact final write of a budget with a persistent store; utilisation, cacheStats and flush keep working after close().

  • Logging, under com.spartanlabs.webtools.http.UpstreamClient: INFO once on creation and once on close(); DEBUG once 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 an InvalidRequest the client raises (the endpoint id and its rule), for a DecodeFailure (the endpoint id and the cause's class name) and for a close step that threw; WARN for a pre-check refusal, a throttle and a rate-signal reader or utilisation() that throws. An InvalidRequest, a pre-check refusal, a throttle and a DecodeFailure are each logged once, where the client creates them (a throttle and a DecodeFailure once per load, however many callers share it); an UpstreamError has no line of its own and shows only as the outcome of the per-call line, and Closed("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 with Url.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.

Properties

Link copied to clipboard

The base URL every call is made against; it has no query.

Functions

Link copied to clipboard

Reads the cache's counts.

Link copied to clipboard
suspend fun <T : Any> call(endpoint: Endpoint<T>, configure: CallSpec.() -> Unit = {}): Result<Lookup<T>>

Calls endpoint.

Link copied to clipboard
open override fun close()

Closes what the client built, in the order cache, budget, transport; idempotent, non-suspending, never throws.

Link copied to clipboard
suspend fun flush(): Result<Unit>

Writes the budget's exact counts to its store. Call it before close for the exact final write of a budget with a persistent store; it also works after close.

Link copied to clipboard
open override fun toString(): String

A diagnostic string for logs: the baseUrl in its redacted form (Url.redacted), the policy's kind, the kinds of the cache and the budget, which components this client owns and whether it is closed. Its format is not part of the API and may change.

Link copied to clipboard

Reads the budget.