GRPC.Client.Resolver behaviour (gRPC Client v1.0.4)

Copy Markdown View Source

Behaviour for gRPC client resolvers.

A gRPC resolver is responsible for translating a target string into a list of connection endpoints (addresses) and an optional GRPC.Client.ServiceConfig.

gRPC supports multiple naming schemes, allowing clients to connect to servers via DNS, fixed IPs, Unix domain sockets, or through service discovery/control planes like xDS.

Target Syntax

The gRPC target string uses URI-like syntax:

<scheme>://<authority>/<path>   or   <scheme>:<path>

Supported schemes

  • dns://[authority/]host[:port] – resolves via DNS, including:
    • A/AAAA records for IP addresses
    • Optional TXT record _grpc_config.<host> containing JSON ServiceConfig
  • ipv4:addr[:port][,addr[:port],...] – fixed list of IPv4 addresses
  • ipv6:[addr][:port][,[addr][:port],...] – fixed list of IPv6 addresses
  • unix:/absolute_path – Unix domain socket
  • unix-abstract:name – abstract Unix socket (Linux only)
  • vsock:cid:port – VSOCK endpoint (Linux only)
  • xds:///name – resolve via xDS control plane (Envoy/Istio/Traffic Director)

If no scheme is specified, dns is assumed.

Default ports

  • dns, ipv4, ipv6 → 50051
  • xds → 443

Resolver Output

Returns:

  • {:ok, %{addresses: list(map()), service_config: GRPC.Client.ServiceConfig.t() | nil}}

    • addresses – list of endpoint maps containing the keys:
      • :address – host, IP, or socket path
      • :port – TCP port (if applicable)
      • may include additional scheme-specific fields, e.g., :cid for vsock
    • service_config – optional ServiceConfig parsed from DNS TXT or xDS

  • {:error, reason} on failure

Purpose

The resolver abstracts the underlying naming and service discovery mechanisms, allowing the gRPC client to obtain endpoints and service configuration consistently, regardless of whether the target is DNS, static IPs, a socket, or xDS.

Reference

For the official gRPC naming and resolver specification, see:

gRPC Naming Documentation

Summary

Callbacks

init(target, opts)
resolve(target)
shutdown(state)
update(state, event)

Functions

init(target, opts)

Initializes background re-resolution for target, delegating to the scheme-specific resolver when it implements the optional init/2 callback (e.g. GRPC.Client.Resolver.DNS for periodic DNS refresh).

resolve(target)

Resolves a gRPC target string into a list of connection endpoints and an optional ServiceConfig.

shutdown(arg1)

Shuts down background re-resolution started by init/2.

update(state, event)

Forwards an event (e.g. :resolve_now) to the underlying resolver's update/2 callback.

Callbacks

init(target, opts)

(optional) 
@callback init(target :: String.t(), opts :: keyword()) ::
  {:ok, state :: any()} | {:error, term()}

resolve(target)

@callback resolve(target :: String.t()) ::
  {:ok,
   %{addresses: [map()], service_config: GRPC.Client.ServiceConfig.t() | nil}}
  | {:error, term()}

shutdown(state)

(optional) 
@callback shutdown(state :: any()) :: :ok

update(state, event)

(optional) 
@callback update(state :: any(), event :: any()) :: {:ok, state :: any()}

Functions

init(target, opts)

Initializes background re-resolution for target, delegating to the scheme-specific resolver when it implements the optional init/2 callback (e.g. GRPC.Client.Resolver.DNS for periodic DNS refresh).

Returns {:ok, state} where state is nil when the scheme has no background resolution. The state must be passed back to update/2 and shutdown/1.

resolve(target)

Resolves a gRPC target string into a list of connection endpoints and an optional ServiceConfig.

The target string can use one of the supported URI schemes:

  • dns://[authority/]host[:port] – resolves via DNS; looks up both A/AAAA records and optional _grpc_config.<host> TXT record.
  • ipv4:addr[:port][,addr[:port],...] – uses a fixed list of IPv4 addresses.
  • ipv6:[addr][:port][,[addr][:port],...] – uses a fixed list of IPv6 addresses.
  • unix:/absolute_path – connects via Unix domain socket.
  • unix-abstract:name – connects via abstract Unix socket (Linux only).
  • vsock:cid:port – connects via VSOCK (Linux only).
  • xds:///name – resolves via xDS control plane (Envoy/Istio/Traffic Director).

If no scheme is specified, dns is assumed. Default ports:

  • dns, ipv4, ipv6 → 50051
  • xds → 443

Returns:

  • {:ok, %{addresses: list(map()), service_config: GRPC.Client.ServiceConfig.t() | nil}} on success

  • {:error, reason} on failure

Each address map includes at least:

  • :address – host, IP, or socket path
  • :port – TCP port (if applicable)
  • additional fields may be present depending on the scheme (e.g., :socket, :cid for vsock).

This function abstracts the resolution mechanism, allowing the gRPC client to obtain endpoints and service configuration regardless of the underlying target type.

shutdown(arg1)

Shuts down background re-resolution started by init/2.

update(state, event)

Forwards an event (e.g. :resolve_now) to the underlying resolver's update/2 callback.