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 Call per hop, one request per Call. A dropped pooled connection, a 407 (with its Proxy-Authenticate), a 408, a 421, a 503 with Retry-After: 0 or a 429 is 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: maxResponseBytes bounds the decoded body (TransportFailure.BodyTooLarge, with the declared length when the server declared one above the cap, decided before any byte is read); maxRedirects bounds the hops (TransportFailure.TooManyRedirects; 0 follows none); callTimeout is one deadline across every hop (TransportFailure.Timeout); connectTimeout, readTimeout and writeTimeout apply per socket operation.

  • Controlled headers. A request carrying User-Agent, Accept-Encoding, Host, Connection, Content-Length, Transfer-Encoding, Keep-Alive, Proxy-Connection, TE, Trailer, Upgrade or Expect (any case) fails with TransportFailure.InvalidRequest naming the first such header, before anything is sent. Range is allowed: on a hop that carries it the transport sends Accept-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, 307 and 308 are followed for GET and HEAD only, the method kept (HEAD stays HEAD after a 303), with no body and no Referer; 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 other 3xx (300 included), a 3xx to any other method, or one with no single usable Location, 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 304 included).

  • 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 as CancellationException.

  • close() is idempotent, non-suspending and never throws: it cancels every call in flight (each ends with Closed("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: INFO once on creation (the policy kind and its settings, numbers only) and once on close(); DEBUG per call, per followed hop and per failure; WARN once 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 Untrusted policy pins the direct route and ignores every JVM-wide proxy setting; a Trusted policy keeps OkHttp's default proxy selection, so the JVM's http.proxyHost and socksProxyHost apply.

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

Link copied to clipboard
open override fun close()

Closes the transport: every call in flight ends with Closed("transport"), the dispatcher is shut down and the idle connections are evicted. Idempotent, non-suspending, never throws.

Link copied to clipboard
open suspend override fun execute(request: HttpRequest): Result<HttpResponse>

Sends request and returns the response, following redirects as the class description says.

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

A diagnostic string for logs: the policy's kind and whether the transport is closed. Its format is not part of the API and may change.