io.grpc

Interface ProxyDetector

@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/5279")
public interface ProxyDetector

A utility class to detect which proxy, if any, should be used for a given SocketAddress. This class performs network requests to resolve address names, and should only be used in places that are expected to do IO such as the NameResolver.

How Proxies work in gRPC

In order for gRPC to use a proxy, NameResolver, ProxyDetector and the underlying transport need to work together.

The NameResolver should invoke the ProxyDetector retrieved from the NameResolver.Helper.getProxyDetector(), and pass the returned ProxiedSocketAddress to NameResolver.Listener.onAddresses(java.util.List<io.grpc.EquivalentAddressGroup>, io.grpc.Attributes). The DNS name resolver shipped with gRPC is already doing so.

The default ProxyDetector uses Java's standard ProxySelector and Authenticator to detect proxies and authentication credentials and produce HttpConnectProxiedSocketAddress, which is for using an HTTP CONNECT proxy. A custom ProxyDetector can be passed to ManagedChannelBuilder.proxyDetector(io.grpc.ProxyDetector).

The ProxiedSocketAddress is then handled by the transport. The transport needs to support whatever type of ProxiedSocketAddress returned by ProxyDetector. The Netty transport and the OkHttp transport currently only support HttpConnectProxiedSocketAddress which is returned by the default ProxyDetector.

Method Summary

Modifier and Type	Method and Description
ProxiedSocketAddress	proxyFor(SocketAddress targetServerAddress) Given a target address, returns a proxied address if a proxy should be used.

Method Detail

proxyFor

@Nullable
ProxiedSocketAddress proxyFor(SocketAddress targetServerAddress)
                                 throws IOException

Given a target address, returns a proxied address if a proxy should be used. If no proxy should be used, then return value will be null.

If the returned ProxiedSocketAddress contains any address that needs to be resolved locally, it should be resolved before it's returned, and this method throws if unable to resolve it.

Parameters:

targetServerAddress - the target address, which is generally unresolved, because the proxy will resolve it.

Throws:

IOException