View Source GRPC.Client.Resolver behaviour (grpc v0.11.2)

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 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

Types

service_config()

Callbacks

resolve(t)

Functions

resolve(target)

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

Types

Link to this type

service_config()

View Source 
@type service_config() :: GRPC.Client.ServiceConfig.t() | nil

Callbacks

Link to this callback

resolve(t)

View Source 
@callback resolve(String.t()) ::
  {:ok, %{addresses: [map()], service_config: service_config()}}
  | {:error, term()}

Functions

Link to this function

resolve(target)

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

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.