HTTPDNS:Best practices for using HTTPDNS with OkHttp in Java

How it works

OkHttp is an open source HTTP client for Java and Android. By default, it resolves domain names through the system DNS service via the InetAddress class. OkHttp also exposes a Dns interface that lets you plug in a custom resolver — use this to route resolution through HTTPDNS instead.

Implement the custom DNS interface

Implement the Dns interface to route domain resolution through HTTPDNS:

import com.alibaba.sdk.java.httpdns.HTTPDNSResult;
import com.alibaba.sdk.java.httpdns.HttpDnsClient;
import com.alibaba.sdk.java.httpdns.RequestIpType;
import okhttp3.Dns;

import java.net.InetAddress;
import java.net.UnknownHostException;
import java.util.ArrayList;
import java.util.List;

public class OkHttpDns implements Dns {
    
    private final HttpDnsClient httpDnsClient;
    
    public OkHttpDns(HttpDnsClient httpDnsClient) {
        this.httpDnsClient = httpDnsClient;
    }
    
    @Override
    public List<InetAddress> lookup(String hostname) throws UnknownHostException {
        // Resolve both IPv4 and IPv6 addresses via HTTPDNS.
        HTTPDNSResult result = httpDnsClient.getHttpDnsResultForHostSyncNonBlocking(
            hostname, 
            RequestIpType.both
        );
        
        List<InetAddress> inetAddresses = new ArrayList<>();
        
        try {
            if (result != null && result.getIps() != null) {
                for (String ip : result.getIps()) {
                    inetAddresses.add(InetAddress.getByName(ip));
                }
            }
            if (result != null && result.getIpv6s() != null) {
                for (String ip : result.getIpv6s()) {
                    inetAddresses.add(InetAddress.getByName(ip));
                }
            }
        } catch (UnknownHostException e) {
            // Ignore failures in parsing a single IP address.
        }
        
        if (!inetAddresses.isEmpty()) {
            return inetAddresses;
        }
        
        // Fall back to the system DNS.
        return Dns.SYSTEM.lookup(hostname);
    }
}

Returning both IPv4 and IPv6 addresses lets OkHttp's built-in retry mechanism try a different address when a connection fails. By returning multiple IP addresses from the lookup() method, you improve reliability when a single address is unavailable.

All requests sent through the same OkHttpClient instance go through this Dns implementation. If only a subset of your domains need HTTPDNS resolution, add a filter at the start of lookup() and fall back to Dns.SYSTEM.lookup(hostname) for other hostnames.

Configure the OkHttpClient

Create an OkHttpClient instance and pass the custom DNS resolver to it. Replace accountId with your HTTPDNS account ID, which you can find in the HTTPDNS console.

HttpDnsClient httpDnsClient = HttpDnsClient.getClient(accountId);

OkHttpClient okHttpClient = new OkHttpClient.Builder()
    .dns(new OkHttpDns(httpDnsClient))
    .build();

Summary

The main advantages of using HTTPDNS with OkHttp are:

• Simple integration: Integrate the service by implementing the Dns interface.

• Broad compatibility: Works with HTTPS, Server Name Indication (SNI), and cookie management with no extra configuration for certificate validation or hostname verification.

• Automatic retries: Returning multiple IP addresses lets OkHttp automatically retry connections with different addresses.