OkHttpTransport
The supplied HttpTransport: OkHttp 5 under the outbound-URL policy's rules, with manual redirects, a capped body, and never a retry. Built with the factory OkHttpTransport(userAgent, policy); usable without any opt-in (it is a supplied default, not a seam), and final: every number comes from policy.settings, there is no builder and nothing to override.
Stable Core.
Main-safe. execute suspends; every blocking step (DNS, connect, TLS, the write, the read of the body) runs on the transport's own daemon dispatcher threads, named
webtools-http-dispatcher-<n>, never on the caller's thread or dispatcher.Never retries. One
Callper hop, one request perCall. A dropped pooled connection, a407(with itsProxy-Authenticate), a408, a421, a503withRetry-After: 0or a429is returned (as the response it is, every header untouched) or failed once; OkHttp's own re-send paths are turned off and a network interceptor refuses any second exchange of one hop with TransportFailure.RetryRefused.The caps, from
policy.settings:maxResponseBytesbounds the decoded body (TransportFailure.BodyTooLarge, with the declared length when the server declared one above the cap, decided before any byte is read);maxRedirectsbounds the hops (TransportFailure.TooManyRedirects;0follows none);callTimeoutis one deadline across every hop (TransportFailure.Timeout);connectTimeout,readTimeoutandwriteTimeoutapply per socket operation.Controlled headers. A request carrying
User-Agent,Accept-Encoding,Host,Connection,Content-Length,Transfer-Encoding,Keep-Alive,Proxy-Connection,TE,Trailer,UpgradeorExpect(any case) fails with TransportFailure.InvalidRequest naming the first such header, before anything is sent.Rangeis allowed: on a hop that carries it the transport sendsAccept-Encoding: identity, so nothing is decoded; a server that sends a content coding anyway is answered with the bytes as received.Redirects.
301,302,303,307and308are followed forGETandHEADonly, the method kept (HEADstaysHEADafter a303), with no body and noReferer; every target is resolved and judged by the policy (a foreign scheme, an unresolvable target or a refused hop is TransportFailure.RefusedByPolicy); every sensitive header (one added as sensitive,Authorization,Proxy-Authorization,Cookie,Set-Cookie) is dropped for good once the scheme, host or port changes. Any other3xx(300included), a3xxto any other method, or one with no single usableLocation, is the response. A followed redirect's body is never read, so its connection is not reused. HttpResponse.url is the last URL requested; HttpResponse.redirectChain lists each followed hop.Received entries. A header whose name is not a token is dropped; CR, LF and NUL in a value become SP; a status outside 100..599 is TransportFailure.Protocol; any status in 100..599 is a response (a
304included).Failures are returned inside the
Result, never thrown: the TransportFailure leaves, HttpFailure.Closed after close. Cancellation of the calling coroutine cancels the call, stops a body read at once, and is thrown asCancellationException.close()is idempotent, non-suspending and never throws: it cancels every call in flight (each ends withClosed("transport")), shuts the dispatcher down and evicts the idle connections. The dispatcher's threads are daemon threads, so a transport that is never closed does not keep the JVM alive;close()is still the supported stop.Thread safety. execute may be called concurrently from many coroutines on any dispatcher; the only mutable state is the closed flag.
Logging, under
com.spartanlabs.webtools.http.OkHttpTransport:INFOonce on creation (the policy kind and its settings, numbers only) and once onclose();DEBUGper call, per followed hop and per failure;WARNonce for a policy refusal and for a refused second exchange. Never a header, a body, a query string, a credential or a resolved address.Proxies. An
Untrustedpolicy pins the direct route and ignores every JVM-wide proxy setting; aTrustedpolicy keeps OkHttp's default proxy selection, so the JVM'shttp.proxyHostandsocksProxyHostapply.
The constructor that takes a guard, a base resolver and a donor client is not public: it exists for the test fixtures (LoopbackTransports) and this module's own tests. Its last two parameters, the clock of the shared deadline and the factory of each hop's Call, are for this module's tests only (a manual clock and fake calls); every other caller leaves them at their defaults, TimeSource.Monotonic and the transport's own client.
Functions
Sends request and returns the response, following redirects as the class description says.