com.squareup.okhttp3:okhttp-java-net-cookiejar

2026-08-16

This release introduces opt-in support for [Encrypted Client Hello (ECH)]. This new feature improves user privacy by encrypting domain names in transit. With regular TLS, your coffee shop’s Wi-Fi router can see that you’re visiting wikipedia.com, but it cannot see which page you’re looking at. With ECH, the router observes only the IP address. This additional privacy is most effective on sites hosted by big CDNs because the IP address doesn’t imply a particular website.

This requires ECH support in the platform’s TLS stack. Today this is only Android 17 (API 37, released June 2026). When other TLS stacks add ECH support, we'll integrate them.

ECH took a lot of work to implement because the encryption keys are published over DNS in the [HTTPS resource record], and we needed to write new code to fetch these records. This release includes a major update to OkHttp’s DNS API: it now supports multiple resource record types (not just IP addresses!), asynchronous streaming results, and in-memory caching.

To opt in, you can use DnsOverHttps:

// DnsOverHttps itself uses OkHttpClient. Build both clients upon the
// same bootstrap client so they share a connection pool and dispatcher.
val bootstrapClient = OkHttpClient()

// This sample uses Cloudflare's 1.1.1.1 DnsOverHttps service.
val client = bootstrapClient.newBuilder()
  .dns(DnsOverHttps.Builder()
    .client(bootstrapClient)
    .url("https://1.1.1.1/dns-query".toHttpUrl())
    .build())
  .build()

You could also opt in with our new AndroidDns API. Unfortunately, the privacy benefits of ECH are thwarted because its DNS queries are not encrypted by default.

// AndroidDns fetches the HTTPS DNS resource records necessary for ECH.
val client = OkHttpClient.Builder()
  .dns(AndroidDns())
  .build()

• New: OkHttp artifacts are now signed with our [new signing key]. This project and three sibling projects ([Retrofit], [Okio], and [SQLDelight]) recently joined [the Commonhaus Foundation].
• Fix: MockWebServer’s @StartStop annotation now supports @Nested JUnit 5 tests.
• Fix: Our default TLS hostname verifier now reject hosts that fail IP canonicalization.
• Fix: Closing a multipart part's sink no longer closes the entire request body.
• Fix: Flush HTTP/1 request bodies before detaching the timeout. We had a bug where timeouts weren’t applied correctly.
• Fix: Follow [RFC 1008]'s requirements for HTTP QUERY redirects.
• Fix: Fall back to no proxy when the system proxy selector throws. Previously this would cause the HTTP call to crash.
• Upgrade: [Okio 3.18.1][okio_3_18_1].

2026-06-08

• New: Add superpowers to interceptors. Interceptors can now override anything settable on OkHttpClient.Builder, such as the cache, connection pool, socket factory, and DNS. We expect this will allow most users to use interceptors everywhere, insted of mixing and matching interceptors with custom Call.Factory wrappers.
• Fix: Limit each HTTP/2 response to 256 KiB of total headers.
• Upgrade: [kotlinx.coroutines 1.11.0][coroutines_1_11_0]. This is used by the optional okhttp-coroutines artifact.
• Upgrade: [GraalVM 25.0.3][graalvm_25].
• Upgrade: [Okio 3.17.0][okio_3_17_0].

2025-11-18

• Fix: Don't delay triggering timeouts. In Okio 3.16.0 we introduced a regression that caused timeouts to fire later than they were supposed to.

• Upgrade: [Okio 3.16.4][okio_3_16_4].

2025-11-16

This release is the same as 5.3.0. Okio 3.16.3 didn't have a necessary fix!

• Upgrade: [Okio 3.16.3][okio_3_16_3].

2025-10-30

• New: Add tags to Call, including computable tags. Use this to attach application-specific metadata to a Call in an EventListener or Interceptor. The tag can be read in any other EventListener or Interceptor.

    override fun intercept(chain: Interceptor.Chain): Response {
      chain.call().tag(MyAnalyticsTag::class) {
        MyAnalyticsTag(...)
      }
  
      return chain.proceed(chain.request())
    }
  

• New: Support request bodies on HTTP/1.1 connection upgrades.

• New: EventListener.plus() makes it easier to observe events in multiple listeners.

• Fix: Don't spam logs with ‘Method isLoggable in android.util.Log not mocked.’ when using OkHttp in Robolectric and Paparazzi tests.

• Upgrade: [Kotlin 2.2.21][kotlin_2_2_21].

• Upgrade: [Okio 3.16.2][okio_3_16_2].

• Upgrade: [ZSTD-KMP 0.4.0][zstd_kmp_0_4_0]. This update fixes a bug that caused APKs to fail [16 KB ELF alignment checks][elf_alignment].

2025-11-18

• Fix: Don't delay triggering timeouts. In Okio 3.16.0 we introduced a regression that caused timeouts to fire later than they were supposed to.

• Upgrade: [Okio 3.16.4][okio_3_16_4].

2025-11-16

This release is the same as 5.2.1. Okio 3.16.3 didn't have a necessary fix!

• Upgrade: [Okio 3.16.3][okio_3_16_3].

2025-10-09

• Fix: Don't crash when calling Socket.shutdownOutput() or shutdownInput() on an SSLSocket on Android API 21 through 23. This method throws an UnsupportedOperationException, so we now catch that and close the underlying stream instead.

• Upgrade: [Okio 3.16.1][okio_3_16_1].

2025-10-07

• New: Support [HTTP 101] responses with Response.socket. This mechanism is only supported on HTTP/1.1. We also reimplemented our websocket client to use this new mechanism.

• New: The okhttp-zstd module negotiates [Zstandard (zstd)][zstd] compression with servers that support it. It integrates a new (unstable) [ZSTD-KMP] library, also from Square. Enable it like this:

  val client = OkHttpClient.Builder()
    .addInterceptor(CompressionInterceptor(Zstd, Gzip))
    .build()
  

• New: Support the QUERY HTTP method. You will need to set the Request.cacheUrlOverride property to cache calls made with this method. The RequestBody.sha256() may be helpful here; use it to compose a cache URL from the query body.

• New: Publish events when calls must wait to execute. EventListener.dispatcherQueueStart() is invoked when a call starts waiting, and dispatcherQueueEnd() is invoked when it's done.

• New: Request.toCurl() returns a copy-pasteable [curl] command consistent with Chrome’s and Firefox’s ‘copy as cURL’ features.

• New: Support [JPMS]. We replaced our Automatic-Module-Name metadata with proper module-info.java files.

• Fix: Recover gracefully when worker threads are interrupted. When we introduced fast fallback in OkHttp 5.0, we started using background threads while connecting. Sadly that code didn't handle interruptions well. This is now fixed.

• Upgrade: [Kotlin 2.2.20][kotlin_2_2_20].

• Upgrade: [Okio 3.16.0][okio_3_16_0].

2025-07-07

• New: Response.peekTrailers(). When we changed Response.trailers() to block instead of throwing in 5.0.0, we inadvertently removed the ability for callers to peek the trailers (by catching the IllegalStateException if they weren't available). This new API restores that capability.

• Fix: Don't crash on trailers() if the response doesn't have a body. We broke [Retrofit] users who read the trailers on the raw() OkHttp response, after its body was decoded.

2025-07-02

This is our first stable release of OkHttp since 2023. Here's the highlights if you're upgrading from OkHttp 4.x:

OkHttp is now packaged as separate JVM and Android artifacts. This allows us to offer platform-specific features and optimizations. If your build system handles [Gradle module metadata], this change should be automatic.

MockWebServer has a new coordinate and package name. We didn’t like that our old artifact depends on JUnit 4 so the new one doesn’t. It also has a better API built on immutable values. (We intend to continue publishing the old okhttp3.mockwebserver artifact so there’s no urgency to migrate.)

OkHttp now supports Happy Eyeballs ([RFC 8305]) for IPv4+IPv6 networks. It attempts both IPv6 and IPv4 connections concurrently, keeping whichever connects first.

We’ve improved our Kotlin APIs. You can skip the builder:

val request = Request(
  url = "https://cash.app/".toHttpUrl(),
)

OkHttp now supports [GraalVM].

Here’s what has changed since 5.0.0-alpha.17:

• Upgrade: [Okio 3.15.0][okio_3_15_0].
• Upgrade: [Kotlin 2.2.0][kotlin_2_2_0].
• Fix: Don't crash with a NoSuchMethodError when using OkHttp with the Sentry SDK.
• Fix: Retain the query data in the old okhttp3.mockwebserver.RecordedRequest.path property. We inadvertently changed this behavior when we introduced the mockwebserver3 API.

2025-06-29

This release stabilizes many APIs for the imminent OkHttp 5.0.0 release.

• New: TrailersSource, a public API for HTTP trailers. Production callers shouldn't need this as the API to read response trailers is unchanged. Testers may use this new stable API to supply trailers for a Response.

• New: Path.asRequestBody() is now a non-experimental API.

• New: FileDescriptor.toRequestBody() is now a non-experimental API.

• New: Stop using experimental coroutines APIs in our okhttp-coroutines artifact.

• Breaking: Move gzip from RequestBody to Request.Builder. This new API handles both compressing the request body and also adding the corresponding Content-Encoding header. Note that this function is sensitive to when it is called: the response body must be supplied before it can be compressed.

• Breaking: Remove AddressPolicy, AsyncDns, and ConnectionListener from the public API. We intend to ship a public API for these features, but we don't want to hold OkHttp 5.0.0 until those APIs are stable.

• Fix: Change MockWebServer.close() to cancel ongoing calls that are blocked on a delay.

• Upgrade: [Okio 3.13.0][okio_3_13_0].

This release also stabilizes many APIs in the mockwebserver3 artifact that's new in 5.0.

• Breaking: RecordedRequest.body is now nullable. Null is used when the request does not have a body.

• Breaking: RecordedRequest.chunkSizes is now nullable. Null is used when the request does not use chunked encoding. This is different from an empty list - that indicates the request is chunked but has no data.

• Breaking: Replace SocketPolicy with a new type, SocketEffect. It splits triggers (request start, response body, etc.) from effects (closing the socket, closing the stream, etc.).

• Breaking: Rename RecordedRequest.sequenceNumber to exchangeIndex and introduce connectionIndex on that type. These properties may be useful when testing features like connection reuse.

• Breaking: Replace our parameters-based JUnit 5 extension with a new annotation, @StartStop. Put this annotation on a MockWebServer property and the extension will start it before your test executes and stop it after it completes. No further configuration is required.

  @StartStop val server = MockWebServer()
  

• Breaking: Don't automatically start MockWebServer after calls to accessors like port. Now these accessors will throw an IllegalStateException if the service has not yet been started.

• Breaking: Rename RecordedRequest.path to RecordedRequest.target. (This property is sometimes a path, but it can also be a path and query, or a full URL.)

• Breaking: Decompose the RecordedRequest.requestLine into three properties, method, target, and version. This better suits HTTP/2 where the request line had to be synthesized from component headers.

• Breaking: Change RecordedRequest.body from a mutable Buffer to an immutable ByteString.

• Breaking: Adopt Okio's new Socket interface for MockResponse.socketHandler.

Note that any Breaking changes above impact only APIs introduced in earlier 5.0.0-alpha releasees. We don't break binary compatibility with non-alpha APIs.

2025-05-29

• Fix: The previous release would crash when running on Robolectric. We didn't anticipate running our Android artifact on the JVM platform!

2025-05-28

This release introduces separate JVM and Android artifacts. Until now, we've distributed OkHttp as a JVM library that detects Android capabilities at runtime, but that doesn't offer Android-specific APIs. With this release we're starting to publish OkHttp as an AAR for Android users in addition to our existing JAR for JVM users.

This first Android-specific artifact adopts Android's assets mechanism to embed the public suffix data. We will build more Android integration in future releases.

The okhttp-android artifact first introduced in 5.0.0-alpha.7 is no longer available:

• The AndroidAsyncDns class moved to the okhttp artifact.
• The AndroidLogging class is no longer necessary. LoggingEventListener and HttpLoggingInterceptor write to logcat by default.

The rest of this release is our highest-quality release yet. Though we continue to use the word alpha in the version name, the only unstable thing in it is some non-final APIs tagged @ExperimentalOkHttpApi. You can safely use this release in production.

• Fix: Attempt to read the response even if sending the request failed. This makes it possible to handle response statuses like HTTP/1.1 431 "Request Header Fields Too Large.

• Fix: Handle multiple 1xx responses.

• Fix: Address a performance bug in our internal task runner. We had a race condition that could result in it OkHttp starting a thread for each queued task, even when a single thread could run all of them.

• Fix: Address a performance bug in MultipartReader. We were scanning the entire input stream for a delimiter when we only needed to scan enough to return a result.

• Fix: Don't double-compress the public suffix database. OkHttp is usually distributed in a compressed file (like a JAR or APK), so compressing its internal data was redundant.

• Fix: Call ProxySelector.connectFailed() when a connection's initial TCP handshake fails.

• Fix: Change the signature of Dispatcher to accept a nullable ExecutorService. Changing this parameter to be non-null was an unintended signature change in OkHttp 4.0.

• New: EventListener.retryDecision() is called each time a request fails with an IOException. It notifies your listener if OkHttp will retry.

• New: EventListener.followUpDecision() is called each time a response is received. It notifies your listener if OkHttp has decided to make a follow-up request. Some common follow-ups are authentication challenges and redirects.

• New: Handy constants for Headers.EMPTY, RequestBody.EMPTY, and ResponseBody.EMPTY.

• New: OkHttp now calls StrictMode.noteSlowCall() when initializing TLS on Android. Use StrictMode to detect if your OkHttpClient is being initialized on the main thread.

• Upgrade: [Okio 3.12.0][okio_3_12_0].

• Upgrade: [Kotlin 2.1.21][kotlin_2_1_21].

• Upgrade: [kotlinx.coroutines 1.10.2][coroutines_1_10_2]. This is used by the optional okhttp-coroutines artifact.

• Upgrade: [AndroidX Startup 1.2.0][startup_1_2_0]. The Android variant of the okhttp artifact now depends on this. This is a new dependency.

• Upgrade: [AndroidX Annotation 1.9.1][annotation_1_9_1]. As above, the Android variant of the okhttp artifact now depends on this. This is also a new dependency.

2024-04-17

• Breaking: Move coroutines extensions to okhttp3.coroutines. Previously this artifact shared the okhttp3 package name with our core module, which is incompatible with the Java Platform Module System.

• Fix in okhttp-coroutines: Publish a valid artifact. The coroutines JAR file in 5.0.0-alpha.13 was corrupt and should not be used.

2024-04-16

• Breaking: Tag unstable new APIs as @ExperimentalOkHttpApi. We intend to release OkHttp 5.0 without stabilizing these new APIs first.

  Do not use these experimental APIs in modules that may be executed using a version of OkHttp different from the version that the module was compiled with. Do not use them in published libraries. Do not use them if you aren't willing to track changes to them.

• Breaking: Drop support for Kotlin Multiplatform.

  We planned to support multiplatform in OkHttp 5.0, but after building it, we weren't happy with the implementation trade-offs. We can't use our HTTP client engine on Kotlin/JS, and we weren't prepared to build a TLS API for Kotlin/Native.

  We'd prefer a multiplatform HTTP client API that's backed by OkHttp on Android and JVM, and other engines on other platforms. [Ktor] does this pretty well today!

• Breaking: Use kotlin.time.Duration in APIs like OkHttpClient.Builder.callTimeout(). This update also drops support for the DurationUnit functions introduced in earlier alpha releases of OkHttp 5.

• Breaking: Reorder the parameters in the Cache constructor that was introduced in 5.0.0-alpha.3.

• New: Request.Builder.cacheUrlOverride() customizes the cache key used for a request. This can be used to make canonical URLs for the cache that omit insignificant query parameters or other irrelevant data.

  This feature may be used with POST requests to cache their responses. In such cases the request body is not used to determine the cache key, so you must manually add cache-relevant data to the override URL. For example, you could add a request-body-sha256 query parameter so requests with the same POST data get the same cache entry.

• New: HttpLoggingInterceptor.redactQueryParams() configures the query parameters to redact in logs. For best security, don't put sensitive information in query parameters.

• New: ConnectionPool.setPolicy() configures a minimum connection pool size for a target address. Use this to proactively open HTTP connections.

  Connections opened to fulfill this policy are subject to the connection pool's keepAliveDuration but do not count against the pool-wide maxIdleConnections limit.

  This feature increases the client's traffic and the load on the server. Talking to your server's operators before adopting it.

• New in okhttp-android: HttpLoggingInterceptor.androidLogging() and LoggingEventListener.androidLogging() write HTTP calls or events to Logcat.

• New: OkHttpClient.webSocketCloseTimeout configures how long a web socket connection will wait for a graceful shutdown before it performs an abrupt shutdown.

• Fix: Honor RequestBody.isOneShot() in MultipartBody

• Fix in okhttp-coroutines: Don't leak response bodies in executeAsync(). We had a bug where we didn't call Response.close() if the coroutine was canceled before its response was returned.

• Upgrade: [Okio 3.9.0][okio_3_9_0].

• Upgrade: [Kotlin 1.9.23][kotlin_1_9_23].

• Upgrade: [Unicode® IDNA 15.1.0][idna_15_1_0]

2023-12-17

We took too long to cut this release and there's a lot of changes in it. We've been busy.

Although this release is labeled alpha, the only unstable thing in it is our new APIs. This release has many critical bug fixes and is safe to run in production. We're eager to stabilize our new APIs so we can get out of alpha.

• New: Support Java 21's virtual threads (‘OpenJDK Project Loom’). We changed OkHttp's internals to use Lock and Condition instead of synchronized for best resource utilization.

• New: Switch our Internationalized Domain Name (IDN) implementation to [UTS #46 Nontransitional Processing][uts46]. With this fix, the ß code point no longer maps to ss. OkHttp now embeds its own IDN mapping table in the library.

• New: Prefer the client's configured precedence order for TLS cipher suites. (OkHttp used to prefer the JDK’s precedence order.) This change may cause your HTTP calls to negotiate a different cipher suite than before! OkHttp's defaults cipher suites are selected for good security and performance.

• New: ConnectionListener publishes events for connects, disconnects, and use of pooled connections.

• Fix: Immediately update the connection's flow control window instead of waiting for the receiving stream to process it.

  This change may increase OkHttp's memory use for applications that make many concurrent HTTP calls and that can receive data faster than they can process it. Previously, OkHttp limited HTTP/2 to 16 MiB of unacknowledged data per connection. With this fix there is a limit of 16 MiB of unacknowledged data per stream and no per-connection limit.

• Fix: Don't close a Deflater while we're still using it to compress a web socket message. We had a severe bug where web sockets were closed on the wrong thread, which caused NullPointerException crashes in Deflater.

• Fix: Don't crash after a web socket fails its connection upgrade. We incorrectly released the web socket's connections back to the pool before their resources were cleaned up.

• Fix: Don't infinite loop when a received web socket message has self-terminating compressed data.

• Fix: Don't fail the call when the response code is ‘HTTP 102 Processing’ or ‘HTTP 103 Early Hints’.

• Fix: Honor interceptors' changes to connect and read timeouts.

• Fix: Recover gracefully when a cached response is corrupted on disk.

• Fix: Don't leak file handles when a cache disk write fails.

• Fix: Don't hang when the public suffix database cannot be loaded. We had a bug where a failure reading the public suffix database would cause subsequent reads to hang when they should have crashed.

• Fix: Avoid InetAddress.getCanonicalHostName() in MockWebServer. This avoids problems if the host machine's IP address has additional DNS registrations.

• New: Create a JPMS-compatible artifact for JavaNetCookieJar. Previously, multiple OkHttp artifacts defined classes in the okhttp3 package, but this is forbidden by the Java module system. We've fixed this with a new package (okhttp3.java.net.cookiejar) and a new artifact, com.squareup.okhttp3:okhttp-java-net-cookiehandler. (The original artifact now delegates to this new one.)

  implementation("com.squareup.okhttp3:okhttp-java-net-cookiehandler:5.0.0-alpha.12")
  

• New: Cookie.sameSite determines whether cookies should be sent on cross-site requests. This is used by servers to defend against Cross-Site Request Forgery (CSRF) attacks.

• New: Log the total time of the HTTP call in HttpLoggingInterceptor.

• New: OkHttpClient.Builder now has APIs that use kotlin.time.Duration.

• New: mockwebserver3.SocketPolicy is now a sealed interface. This is one of several backwards-incompatible API changes that may impact early adopters of this alpha API.

• New: mockwebserver3.Stream for duplex streams.

• New: mockwebserver3.MockResponseBody for streamed response bodies.

• New: mockwebserver3.MockResponse is now immutable, with a Builder.

• New: mockwebserver3.RecordedRequest.handshakeServerNames returns the SNI (Server Name Indication) attribute from the TLS handshake.

• Upgrade: [Kotlin 1.9.21][kotlin_1_9_21].

• Upgrade: [Okio 3.7.0][okio_3_7_0].