Dns2, the new OkHttp DNS API by swankjesse · Pull Request #9536 · lysine-dev/okhttp

swankjesse · 2026-07-10T18:51:20Z

Big new features are support for SVCB and being async.

swankjesse

@yschimke I studied DnsOverHttps a lot in putting this together, and I’m curious about why that class makes multiple HTTP requests in order to lookup A and AAAA records, rather than making a single HTTP request with two questions. (Is that also possible?)

yschimke · 2026-07-10T19:03:44Z

I think it practice that is basically never supported in Dns. But we should check Dns over https servers in practice

yschimke · 2026-07-10T19:25:53Z

+   * @param last true if no further calls to [onRecords] will be made for this call.
+   */
+  fun onRecords(call: DnsCall, last: Boolean, records: List<DnsRecord>)
+  fun onFailure(call: DnsCall, e: IOException)


Is onFailure terminal? Or can part of the DnsCall fail?

Oooh good question. I think for the users’ benefit it should be terminal. I’ve added a note as such.

If we have a partial failure like A records failing and AAAA records succeeding, the implementation could hold back the failure until after it sends the success. That gives the application layer the opportunity to work degraded if so desired.

the implementation could hold back the failure until after it sends the success

Not sure that is ideal, why introduce delays?

I don’t expect our caller will have much to do with a partial failure. For example, if IPv6 fails after 250ms and IPv4 succeeds after 500ms, this will likely result in an ultimate success after 500 ms.

I thought you suggested the failure at 250ms was terminal?

The Dns2 implementation can withhold onFailure() calls. (Alternatively, we have a last boolean in the onFailure function?)

That's the delay I meant. I think we should signal that non-terminal failure, not hide it. Also is one failure, such as HTTPS actually an overall failure?

Maybe it's HTTPS not being found, and I want to change something when ECH not configured?

Maybe it's IPv6, and I want to use HTTPS address hints?

yschimke

I think overall, we can't predict which records will be relevant in future. And I think rather than being Dns for HTTP only, we should model something that could evolve over time.

So first questions that come to mind

a) is the scope purely A, AAAA, SVCB, HTTPS? or should we allow for more in future?
b) how do we make it safe when we add a new record, without breaking existing clients?

A few suggestions

make the result non exhaustive, I've seen this done with a private

private object Invalid: DnsRecord()

So when clauses need an else

maybe support raw queries, or rather raw responses. Should this be part of DnsRecord, so any response is available raw?
Consider whether the abstraction is focused around OkHttp usage primarily for ease of use? or focused on modelling Dns correctly first? the service path is one example since not all fit _port._service.domain.

swankjesse · 2026-07-11T12:04:17Z

And I think rather than being Dns for HTTP only, we should model something that could evolve over time.

So first questions that come to mind
a) is the scope purely A, AAAA, SVCB, HTTPS? or should we allow for more in future?

That's a decision we gotta make! I can see a few different things to possibly build...

1. A general purpose DNS API.

That's gonna expose stuff like raw queries, TXT records, MX records, and recursive resolution.

I think this would be a standalone Kotlin DNS library and it could be useful for all sorts of stuff like implementing ACME.

I would like for this to exist, but not in OkHttp! I don't want the scope increase.

2. An API to support OkHttp’s Specific Needs Only

I think this is A, AAAA, and HTTPS records. OkHttp needs to know about alpn, ech, ports, and IP addresses. It should honor the AliasMode and ServiceMode stuff, including recursively resolving those, for best connectivity.

3. Split the difference

This is what I've got in this PR. It's almost all 'what does OkHttp need' plus the protocol field will always be "https" for us.

I am torn between YAGNI and it coming at a very low cost for anyone else using other protocols. Are there other protocols?! I don't expect there's many people using SVCB for other protocols.

So under a tiny bit of reflection I think we lean hard into option 2: This is an API to provide DNS information to OkHttp, and not a general-purpose DNS thing. I will drop the protocol parameter and simplify the docs around it.

b) how do we make it safe when we add a new record, without breaking existing clients?

I think we do Dns3 at that point?!

This interface is tricky because we're building an abstraction to be potentially implemented by anyone, and also potentially called by anyone.

But I'd like to assume OkHttp is the primary caller of this interface, and other callers will be rare. (Why would you call this API? Probably to do a decorator pattern?)

I'll make the DnsRecord class non-sealed to make an exhaustive when impossible.

maybe support raw queries, or rather raw responses. Should this be part of DnsRecord, so any response is available raw?

I think raw queries makes it more difficult to implement. I'd like developers to be able to implement this interface without parsing DNS records.

To augment ECH information that's missing from the default DNS service?
To cache more aggressively

yschimke · 2026-07-11T12:27:45Z

@swankjesse sounds good. I didn't mind which way the answer went, just that it was self consistent.

yschimke · 2026-07-11T12:28:12Z

@swankjesse and you should definitely do the standalone OkDns thing :)

We can't use data classes in public APIs without making backwards-compatibility more difficult.

swankjesse

Next steps:

Change DnsSystem to implement this, in a very basic way that doesn’t actually add any new ServiceMetadata. It will still implement Dns. Use TaskQueue for callback concurrency.

Build a not-public-API adapter that turns a Dns instance into a Dns2 instance. It should also use TaskQueue for concurrency.

Change OkHttpClient to use Dns2 internally instead of Dns. Use the adapter to make Dns2 the canonical implementation. This will want a breaking change in Address, which expects a Dns. Can we avoid that? This may be difficult!

Implement Dns2 in DnsOverHttps. It will still implement Dns.

Build an implementation of Dns2 on Android’s DnsResolver. Enable that implementation by default on Android where it is available.

yschimke · 2026-07-13T06:13:33Z

This will want a breaking change in Address, which expects a Dns

OkHttp 6?

Dns2 extends Dns, and we keep identifying as Dns.

Add an extra dns2 field?

yschimke · 2026-07-13T06:18:09Z

+    /**
+     * This is a terminal event and no further calls to this callback will be made for this call.
+     */
+    fun onFailure(call: Call, e: IOException)


Do we chain these via suppressions? Let's say HTTPS works with hints, but A and AAAA fai?

Probably.

I don't like situations where I'm digging through suppressed exceptions programmatically. So if there's some useful data exposed that way, I'm inclined to expose it in a different way.

yschimke · 2026-07-13T06:22:52Z

+ *
+ * Implementations of this interface must be safe for concurrent use.
+ */
+interface Dns2 {


Should we use an experimental annotation for a couple of releases?

I'm unsure. If we make it opt-in that makes it more difficult for us to use it in types like OkHttpClient and Address.

The impossible challenge is "what will we regret?" and I think you've come up with a few possibilities! Partial failure for example.

swankjesse · 2026-07-13T11:35:21Z

Add an extra dns2 field?

That's where I intend to start. And if/when we do OkHttp6 we might be able to drop the old dns field.

WIP: New DNS API

625def8

Big new features are support for SVCB and being async.

swankjesse commented Jul 10, 2026

View reviewed changes

Comment thread okhttp/src/commonJvmAndroid/kotlin/okhttp3/dns/Dns2.kt Outdated

Comment thread okhttp/src/commonJvmAndroid/kotlin/okhttp3/dns/Dns2.kt Outdated

Comment thread okhttp/src/commonJvmAndroid/kotlin/okhttp3/dns/Dns2.kt Outdated

yschimke reviewed Jul 10, 2026

View reviewed changes

Comment thread okhttp/src/commonJvmAndroid/kotlin/okhttp3/dns/Dns2.kt Outdated

yschimke reviewed Jul 10, 2026

View reviewed changes

Comment thread okhttp/src/commonJvmAndroid/kotlin/okhttp3/dns/Dns2.kt Outdated

Fixup docs

61b16cc

yschimke reviewed Jul 11, 2026

View reviewed changes

More API feedback

b0ccc2a

yschimke reviewed Jul 12, 2026

View reviewed changes

Comment thread okhttp/src/commonJvmAndroid/kotlin/okhttp3/dns/Dns2.kt Outdated

swankjesse added 2 commits July 12, 2026 14:03

Replace data classes with manual equals/hashCode/toString things

2048381

We can't use data classes in public APIs without making backwards-compatibility more difficult.

apiDump

ac1e195

swankjesse changed the title ~~WIP: New DNS API~~ Dns2, the new OkHttp DNS API Jul 12, 2026

swankjesse marked this pull request as ready for review July 12, 2026 18:06

swankjesse commented Jul 12, 2026

View reviewed changes

yschimke reviewed Jul 13, 2026

View reviewed changes

Comment thread okhttp/src/commonJvmAndroid/kotlin/okhttp3/Dns2.kt

yschimke approved these changes Jul 13, 2026

View reviewed changes

yschimke reviewed Jul 13, 2026

View reviewed changes

Spotless

f0d8041

swankjesse merged commit 6a237f7 into master Jul 13, 2026
28 checks passed

swankjesse deleted the jwilson.0710.sketch_out_dns2 branch July 13, 2026 12:55

Uh oh!

Conversation

swankjesse commented Jul 10, 2026

Uh oh!

swankjesse left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yschimke commented Jul 10, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yschimke left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

swankjesse commented Jul 11, 2026

1. A general purpose DNS API.

2. An API to support OkHttp’s Specific Needs Only

3. Split the difference

Uh oh!

yschimke commented Jul 11, 2026

Uh oh!

yschimke commented Jul 11, 2026

Uh oh!

Uh oh!

swankjesse left a comment

Choose a reason for hiding this comment

Uh oh!

yschimke commented Jul 13, 2026

Uh oh!

yschimke Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

swankjesse commented Jul 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

yschimke left a comment •

edited

Loading

yschimke Jul 13, 2026 •

edited

Loading