UpstreamClient

fun UpstreamClient(transport: HttpTransport, baseUrl: Url, configure: UpstreamClientConfig.() -> Unit = {}): UpstreamClient(source)

Builds an UpstreamClient over a transport the caller owns. Stable Core. The client never closes the transport. The configuration's policy is the pre-check's only; the transport enforces the policy it was built with, so build both from the same policy. Without cache(...) it uses ResponseCache.Disabled, without a budget CallBudget.Unlimited; a budget(windows) is built and owned. On the JVM, UpstreamClient(baseUrl, userAgent) builds and owns the transport, a Caffeine cache and the budget instead.

Return

the client.

Parameters

transport

the transport; the caller closes it.

baseUrl

the base URL of the upstream; no query. Every call extends its path.

configure

sets the policy, clocks, dispatcher, reader, default wait, default headers, cache and budget; the defaults when omitted.

Throws

if defaultMaxWait is negative, baseUrl has a query or is refused by the policy (the message names the RefusalReason), a default header is one the transport controls or, under an Untrusted policy, is sensitive, or a budget built from budget(windows) is refused; the message is constant and never echoes a URL, a header value or a value.

fun UpstreamClient(baseUrl: Url, userAgent: String, configure: UpstreamClientConfig.() -> Unit = {}): UpstreamClient(source)

Builds an UpstreamClient that owns what it uses: an OkHttpTransport(userAgent, policy), a CaffeineResponseCache on the configuration's clock and dispatcher (unless cache(...) was called) and, when budget(windows) was called, the WindowedCallBudget it built. Stable Core. When the budget is a WindowedCallBudget (built or supplied) both OkHttp concurrency limits are raised to at least its maxBurst, because a client talks to one host (the per-host limit binds) and a permit queued in OkHttp would wait outside the call timeout and the wait cap; they are never lowered and there is no ceiling (worst-case memory is concurrent requests × policy.settings.maxResponseBytes). close() closes the cache, the budget and the transport, in that order, and nothing it was handed. The default policy is Trusted, pinned to the base URL's host, https only.

Return

the client; the caller closes it.

Parameters

baseUrl

the upstream's base URL; no query.

userAgent

the User-Agent sent on every request: non-blank, visible ASCII, no leading or trailing space.

configure

sets the policy, clocks, dispatcher, reader, default wait, default headers, cache and budget; the defaults when omitted.

Throws

for a refusal of the common factory, a userAgent the transport refuses, or a policy.settings.maxResponseBytes above Int.MAX_VALUE - 8; what had already been built is closed first, and the message is constant.