OkHttp Admin & Architecture Guide

This guide is the deep reference for engineers, architects, and library maintainers integrating, operating, or extending OkHttp — the HTTP client for Java, Kotlin, and Android maintained by Square/Block. It documents OkHttp's architecture, its complete public configuration surface, the full module ecosystem, security posture, and internal design, all derived directly from the OkHttp 5.x source (commit 7a35098).

Where the User Guide shows how to make requests, this guide explains how OkHttp is built and how to operate it well in production.

1. Executive Summary

OkHttp is a mature, widely-deployed HTTP client distributed as a set of small, focused JVM/Android libraries under the Maven group com.squareup.okhttp3. It is the de-facto networking layer for a large share of the Android ecosystem and the transport beneath higher-level clients such as Retrofit.

Key characteristics:

• Immutable, builder-based API. OkHttpClient, Request, Response, Headers, HttpUrl, and CacheControl are immutable value types created through Builder classes. Clients are cheaply derived with newBuilder().
• Connection efficiency by default. A shared ConnectionPool reuses HTTP/1.x sockets and multiplexes HTTP/2. Transparent gzip, response caching, and Happy Eyeballs fast-fallback are built in.
• Resilience. Automatic recovery from unreachable IPs, stale pooled connections, and unreachable proxies; automatic redirect, authentication-challenge, and retry handling.
• Layered request processing. Every call flows through an ordered chain of interceptors (application then OkHttp's own then network), making behaviour observable and extensible.
• Pluggable trust & DNS. TLS configuration, certificate pinning, custom trust managers, and DNS (including DNS-over-HTTPS) are all replaceable.
• Standards-driven. Implements RFC 9110/9111/9112/9113 (HTTP semantics, caching, HTTP/1.1, HTTP/2), RFC 6455 (WebSockets), and SSE. Deliberately minimal in configurability where configuration would only serve to violate specs.

Runtime footprint: Android 5.0+ (API 21+) and Java 8+. Depends only on Okio and the Kotlin standard library. License: Apache 2.0.

2. Architecture

2.1 The request lifecycle

OkHttp models the work of satisfying one logical HTTP request — possibly involving redirects, authentication follow-ups, and retries across routes — as a single Call. A high-level request (Request) is rewritten, dispatched, connected, transmitted, and the response is read back, rewritten, and returned.

        ┌──────────────────────────────────────────────────────────────┐
        │                       OkHttpClient                            │
        │  (shared config: dispatcher, connection pool, interceptors,   │
        │   cache, dns, TLS, timeouts, protocols)                       │
        └───────────────┬───────────────────────────────────────────────┘
                        │ newCall(request)
                        ▼
                 ┌────────────┐   execute() / enqueue(Callback)
                 │    Call    │──────────────────────────────────┐
                 └────────────┘                                  │
                        │                                        ▼
                        │                                  ┌────────────┐
                        │            async path            │ Dispatcher │
                        │  ◀───────────────────────────────│ (limits +  │
                        │                                  │  executor) │
                        ▼                                  └────────────┘
        ┌──────────────────────────────────────────┐
        │            Interceptor Chain               │
        │  1. Application interceptors (your code)   │
        │  2. RetryAndFollowUpInterceptor            │
        │  3. BridgeInterceptor (cookies, gzip,      │
        │     Content-Length, User-Agent, Host…)     │
        │  4. CacheInterceptor (Cache read/write)    │
        │  5. ConnectInterceptor (pool → route →     │
        │     socket/TLS)                            │
        │  6. Network interceptors (your code)       │
        │  7. CallServerInterceptor (write request,  │
        │     read response)                         │
        └──────────────────┬─────────────────────────┘
                           ▼
        ┌──────────────────────────────────────────┐
        │  Connection  ←  Route  ←  Address  ← URL   │
        │  (ConnectionPool reuses & multiplexes)     │
        └──────────────────────────────────────────┘
                           ▼
                     Origin server

Note

The interceptor chain is the heart of OkHttp's design. Built-in behaviours (retries, header bridging, caching, connecting, transmitting) are themselves interceptors. Your application and network interceptors are inserted at the ends of this chain.

2.2 URL → Address → Route → Connection

OkHttp resolves what to connect to through four layered types (source: docs/features/connections.md):

When you request a URL, OkHttp: (1) builds an Address from the URL + client config; (2) tries to reuse a pooled Connection for that address; (3) if none, selects a Route (DNS lookup, proxy, TLS version); (4) connects (direct socket / TLS tunnel / direct TLS, with handshakes); (5) sends the request and reads the response; then returns the connection to the pool for reuse, evicting it after inactivity.

2.3 Request rewriting

OkHttp rewrites your high-level request before transmission for correctness and efficiency. It may add Content-Length, Transfer-Encoding, User-Agent, Host, Connection, Content-Type, Accept-Encoding: gzip (unless present), and a Cookie header (if a CookieJar has cookies). For stale cached responses it performs conditional GETs by adding If-Modified-Since / If-None-Match. On the response side, if transparent compression was used it drops Content-Encoding and Content-Length (they no longer describe the decompressed body), and merges network + cache responses for successful conditional GETs.

2.4 Dispatch model

• Synchronous (Call.execute()): the caller's thread blocks; the caller manages concurrency.
• Asynchronous (Call.enqueue(Callback)): the Dispatcher runs the call on its ExecutorService and invokes the callback on a dispatcher thread. The dispatcher enforces maxRequests (default 64) and maxRequestsPerHost (default 5).

2.5 Module topology

OkHttp is a multi-module Gradle/Kotlin-Multiplatform project. The core okhttp module targets commonJvmAndroid with jvmMain and androidMain source sets; feature modules layer onto it.

okhttp (core: okhttp3)
 ├── mockwebserver3              test server (+ junit4 / junit5 / deprecated mockwebserver)
 ├── logging-interceptor         okhttp3.logging
 ├── okhttp-tls                  okhttp3.tls (HeldCertificate, HandshakeCertificates)
 ├── okhttp-sse                  okhttp3.sse (EventSource)
 ├── okhttp-dnsoverhttps         okhttp3.dnsoverhttps (DnsOverHttps)
 ├── okhttp-brotli               okhttp3.brotli (BrotliInterceptor)
 ├── okhttp-zstd                 okhttp3.zstd (Zstd)
 ├── okhttp-coroutines           okhttp3.coroutines (executeAsync)
 ├── okhttp-urlconnection        JavaNetAuthenticator, JavaNetCookieJar
 ├── okhttp-java-net-cookiejar   okhttp3.java.net.cookiejar.JavaNetCookieJar
 ├── okhttp-idna-mapping-table   IDNA host-name mapping
 ├── okhttp-bom                  Bill of Materials (version alignment)
 └── okcurl                      CLI (okhttp3.curl)

Note

Each publishable module ships a checked-in api/*.api signature file (the Kotlin binary-compatibility validator output). These files are the authoritative, exhaustive list of every public class, field, and function — useful when auditing the API surface or planning an upgrade.

2.6 Repository structure

3. System Requirements

Important

The legacy 3.12.x branch supports Android 2.3+ (API 9+) and Java 7+, but those platforms lack TLS 1.2 and must not be used for production. There is no security backport guarantee for that branch.

Optional Conscrypt activation:

Security.insertProviderAt(Conscrypt.newProvider(), 1);

4. Configuration Reference — OkHttpClient.Builder

OkHttpClient is configured exclusively through OkHttpClient.Builder. The table below lists every public builder setting with its default value, taken from the source.

4.1 Timeouts

All timeout values must be 0 (off) or between 1 and Integer.MAX_VALUE when converted to milliseconds. Each method has long+TimeUnit, java.time.Duration, and Kotlin Duration overloads.

4.2 Connections & protocols

4.3 TLS & trust

Caution

If no connection spec is TLS-capable (CLEARTEXT-only client), the client has no SSL socket factory and accessing sslSocketFactory throws IllegalStateException("CLEARTEXT-only client"). The builder validates this invariant at build() time.

4.4 Behaviour & integrations

Tip

Mutating a route-affecting setting (dns, proxy, proxySelector, proxyAuthenticator, socketFactory, sslSocketFactory, connectionSpecs, protocols, hostnameVerifier, certificatePinner) on a derived builder resets the internal RouteDatabase so stale route blacklists don't leak between configurations.

5. Public API Reference

The core okhttp3 package (artifact okhttp, signatures from okhttp/api/jvm/okhttp.api) exposes the following public types. Builder/value types are immutable; interfaces are extension points.

5.1 Core request/response types

5.2 Headers, URLs, media types, bodies

5.3 Connection, TLS & negotiation types

5.4 Extension-point interfaces & callbacks

5.5 Feature-module APIs

6. Caching Internals

The optional Cache is a disk-backed, RFC-9111-aligned response store with browser-like heuristics. It is implemented as the CacheInterceptor within the chain.

Construction: Cache(File directory, long maxSize) or Cache(FileSystem, Path, long maxSize) (Okio file system). One directory per Cache; the directory is exclusively owned.

Behaviour:

• Default freshness for documents without explicit expiry is 10% of the document's age at serve time (based on Last-Modified); not applied to URLs containing a query.
• Three outcomes, observable via EventListener: Cache Hit (no network), Cache Miss (network used; uncacheable/expired/never-fetched), Conditional Hit (cacheConditionalHit then a revalidation request; the cached body is reused only on 304 Not Modified, so both cacheResponse() and networkResponse() are non-null).
• A response is stored only if its body is fully read, canceled, or stalled.

Operations & stats: evictAll(), delete(), urls() iterator (with remove()), flush(), close(), size(), maxSize(), and counters hitCount(), networkCount(), requestCount(), writeSuccessCount(), writeAbortCount().

Warning

Sharing a cache directory between two Cache instances or processes corrupts it. In multi-process apps, give each process its own directory or a single shared client.

7. Security Analysis

OkHttp's threat model centers on protecting transport confidentiality/integrity while maximizing connectivity. Security-relevant subsystems and operational guidance follow.

7.1 TLS posture

• Defaults to MODERN_TLS + CLEARTEXT; uses the platform TLS stack (or Conscrypt if installed first). TLS versions/cipher suites in each ConnectionSpec evolve per release — historically OkHttp dropped SSL 3.0 (POODLE) and RC4 as attacks emerged.
• RESTRICTED_TLS is available for stricter compliance environments.
• Hostname verification (OkHostnameVerifier) always runs in addition to certificate trust, even with custom Android trust managers.

Important

Staying current with OkHttp is itself a security control: the library tracks the TLS ecosystem and removes weak primitives. Pin your dependency to a recent 5.x release and update regularly.

7.2 Certificate pinning

CertificatePinner lets you constrain trust to specific public-key hashes, mitigating CA compromise (e.g. the 2011 DigiNotar attack). Pinning is double-edged: an uncoordinated server certificate rotation will hard-fail every pinned client.

Caution

Never deploy certificate pins without your server TLS team's sign-off and a rotation plan. Prefer pinning an intermediate/CA key over a leaf certificate to reduce rotation breakage, and ship backup pins.

7.3 Authentication & credential handling

• Authenticator callbacks must guard against retry loops by returning null when an Authorization header is already present (see community issue #9477, "Infinite Authentication Loop in Proxy CONNECT Tunnel").
• Credentials.basic Base64-encodes credentials — Basic auth offers no confidentiality without TLS.
• HttpUrl.redact() produces a credential-stripped URL safe for logs.

7.4 Logging hygiene

HttpLoggingInterceptor at HEADERS/BODY level will log sensitive headers and payloads. Use redactHeader("Authorization"), redactHeader("Cookie"), and redactQueryParams(...), and never enable BODY logging for authenticated traffic in production.

7.5 Known security-relevant issues (community-reported)

These open/closed issues from the project tracker inform hardening decisions; consult the upstream issue and your installed version before relying on a given behaviour:

Caution

When fetching attacker-controllable URLs (webhooks, link unfurling, image proxies), treat redirect following and decompression as attack surface: disable or constrain redirects, cap body sizes, and resolve/deny internal IP ranges via a custom Dns or network interceptor to prevent SSRF.

8. Operations

8.1 Lifecycle management

OkHttp requires no explicit shutdown — idle dispatcher threads and pooled connections self-release; HTTP/2 daemon threads exit when idle. For aggressive resource reclamation (CLI tools, short-lived workers):

client.dispatcher().executorService().shutdown(); // rejects future calls
client.connectionPool().evictAll();
if (client.cache() != null) client.cache().close();

Warning

After executorService().shutdown() the client rejects new calls. After cache().close(), issuing a call against that cache crashes — close the cache only during teardown.

8.2 Tuning for throughput

• Raise Dispatcher.maxRequests / maxRequestsPerHost for high-concurrency async workloads, and back the dispatcher with an executor sized to match.
• Keep one shared OkHttpClient (and thus one ConnectionPool) per process so connections are actually reused.
• Prefer HTTP/2 (the default) for many concurrent requests to one host — they multiplex over a single socket.
• Use pingInterval on long-lived connections to detect dead peers promptly.

Note

Issue #9443 notes that the dispatcher executor must actually be able to run maxRequests concurrently — a too-small thread pool silently caps real concurrency below the configured maximum.

8.3 Observability

• Metrics: an EventListener.Factory gives per-call timing for every network phase; sample (e.g. 10%) to bound overhead. Cache hit/miss/conditional events flow through the same listener.
• Logging: LoggingEventListener.Factory for phase timings, or HttpLoggingInterceptor for wire-level request/response logs (redact secrets).
• Pool inspection: connectionPool().connectionCount() / idleConnectionCount() and dispatcher().runningCallsCount() / queuedCallsCount() expose live load.

8.4 Proxy & DNS operations

• Route all traffic through a fixed proxy with proxy(...), or delegate to proxySelector(...). proxyAuthenticator(...) handles proxy 407 challenges.
• Replace name resolution wholesale with a custom Dns, or use DnsOverHttps for encrypted resolution (configure a bootstrap client and DoH endpoint).

9. Code Quality, Patterns & Conventions

• Kotlin-first, Java-friendly. Core is Kotlin with @JvmName/@JvmStatic/@JvmOverloads and Companion-object factories so Java callers get idiomatic APIs (Headers.of(...), MediaType.get(...)).
• Immutability + builders. Value types are immutable; the only mutation path is a Builder. newBuilder() enables cheap, copy-on-write derivation that shares pools.
• Deprecation discipline. Property-style getters that replaced old method-style accessors are retained as @Deprecated(level = ERROR) -deprecated_* shims (visible throughout the .api files) to preserve binary compatibility while steering callers to val accessors.
• Binary-compatibility validation. Checked-in api/*.api signature files are enforced in CI, preventing accidental public-API breakage.
• Internal encapsulation. Everything under okhttp3.internal is non-public by convention (the open issue #9435 tracks formalizing this as internal or promoting parts to API). Do not depend on internal classes.
• KMP source sets. commonJvmAndroid holds shared JVM/Android code; androidMain and jvmMain carry platform specifics, allowing one codebase to target both.
• Multiplatform value semantics. Inline-class-backed durations appear in the .api as mangled names (e.g. callTimeout-LRDsOJo) — these are Kotlin Duration overloads, not separate Java API.

10. Testing Strategy

OkHttp dogfoods its own MockWebServer and maintains an unusually broad test matrix:

Tip

For consumers, MockWebServer is the recommended test tool: it exercises the genuine network stack rather than mocking the client. Pair with okhttp-tls HeldCertificate to test HTTPS paths without external CAs.

11. Integration Patterns

• Retrofit / higher-level clients. OkHttp is the standard transport under Retrofit; share one OkHttpClient and add cross-cutting concerns (auth, logging, metrics) as interceptors.
• java.net interop. okhttp-urlconnection and okhttp-java-net-cookiejar bridge java.net.Authenticator and java.net.CookieHandler/CookieManager into OkHttp.
• JSON. Stream ResponseBody.source() into Moshi/Gson/kotlinx.serialization rather than buffering with string().
• Coroutines. okhttp-coroutines executeAsync() integrates cleanly with structured concurrency and cancellation.
• R8/ProGuard. See docs/features/r8_proguard.md; OkHttp ships consumer rules, but verify keep rules for reflective TLS/platform code on Android release builds.

12. Quick Reference

Maven coordinates: com.squareup.okhttp3:okhttp:5.x (core) · :okhttp-bom:5.x (version alignment).

Defaults at a glance:

Minimal client + request:

OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder().url("https://example.com").build();
try (Response response = client.newCall(request).execute()) {
  System.out.println(response.code());
  System.out.println(response.body().string());
}

Production-leaning client:

OkHttpClient client = new OkHttpClient.Builder()
    .connectTimeout(Duration.ofSeconds(10))
    .callTimeout(Duration.ofSeconds(30))
    .pingInterval(Duration.ofSeconds(30))
    .cache(new Cache(cacheDir, 50L * 1024 * 1024))
    .addInterceptor(authInterceptor)
    .eventListenerFactory(metricsFactory)
    .build();

Operational commands:

client.connectionPool().evictAll();                 // drop pooled sockets
client.dispatcher().cancelAll();                     // cancel all async calls
client.dispatcher().executorService().shutdown();    // stop accepting calls
client.cache().close();                              // close the cache (teardown only)