Connection manager for gRPC client channels, with optional load balancing and name resolution support.

A Conn process manages one or more underlying gRPC connections (GRPC.Channel structs) and exposes a virtual channel to be used by client stubs. The orchestration process runs as a GenServer registered in a node-local Registry, so named channels are scoped to the current BEAM node.

Overview

• connect/2 – establishes a client connection (single or multi-channel).
• pick/2 – chooses a channel according to the active load-balancing policy.
• disconnect/1 – gracefully closes a connection and frees resources.

Under the hood:

• The target string is resolved using a Resolver.
• Depending on the target and service config, a load-balancing module is chosen (e.g. PickFirst, RoundRobin).
• Each call to pick/2 dispatches to the LB module, which selects a channel per request. DNS re-resolution reconciles the LB's channel list in place.

Supervised connections

For long-running clients, declare the connection in your own supervision tree instead of calling connect/2 at runtime. In that mode, establishment happens asynchronously after process start: if the backend is unreachable, the process stays alive and retries with exponential backoff instead of failing supervisor startup. Use await_ready/2 to block until the channel is usable.

children = [
  {GRPC.Client.Connection,
   name: MyApp.PaymentsConnection,
   target: "dns://payments.internal:50051",
   lb_policy: :round_robin}
]

:ok = GRPC.Client.Connection.await_ready(MyApp.PaymentsConnection, 10_000)
# use get_channel/1 for the non-raising variant
channel = GRPC.Client.Connection.get_channel!(MyApp.PaymentsConnection)
Payments.Stub.charge(channel, request)

The channel handle returned by get_channel/1 is valid as soon as the process is running, even while the connection is still being established; RPCs return {:error, :no_connection} style errors until then.

connect/2 keeps its historical fail-fast contract: it blocks until the first establishment attempt finishes and returns {:error, reason} (tearing the process down) if that attempt fails.

Supervisor memory

Connection start arguments (for example large default headers) can linger in the GRPC.Client.Supervisor process heap after children exit. That supervisor therefore hibernates when idle and runs fullsweep GCs more often. Tune via config:

config :grpc, GRPC.Client.Application,
  hibernate_after: 15_000,
  fullsweep_after: 20

• :hibernate_after – idle ms before the supervisor hibernates (default: 15_000)
• :fullsweep_after – minor GCs between fullsweeps on the supervisor (default: 20)

Target syntax

The target argument to connect/2 accepts URI-like strings that are resolved via the configured Resolver (default GRPC.Client.Resolver).

Examples of supported formats:

• "dns://example.com:50051"
• "ipv4:10.0.0.5:50051"
• "unix:/tmp/my.sock"
• "xds:///my-service"
• "127.0.0.1:50051" (implicit DNS / fallback to IPv4)

See GRPC.Client.Resolver for the full specification.

Telemetry

Connection processes emit the following events:

• [:grpc, :client, :connection, :connected] – establishment succeeded, including re-establishment after retries or a supervisor restart.
  • Measurements: :retry_attempt – failed attempts before this success
  • Metadata: :name, :target, :pid
• [:grpc, :client, :connection, :connect_error] – an establishment attempt failed and a retry was scheduled.
  • Measurements: :retry_delay – milliseconds until the next attempt
  • Metadata: :name, :target, :pid, :reason, :retry_attempt
• [:grpc, :client, :connection, :disconnected] – the connection process shut down, after its resources were released.
  • Measurements: none
  • Metadata: :name, :target, :pid, :reason
• [:grpc, :client, :connection, :await_ready, :start] – a caller started waiting in await_ready/2.
  • Measurements: :system_time
  • Metadata: :name, :target, :pid, :caller
• [:grpc, :client, :connection, :await_ready, :stop] – the wait ended.
  • Measurements: :duration – as measured through System.monotonic_time()
  • Metadata: :name, :target, :pid, :caller, :result – :ok when the connection became ready, :disconnected when it shut down while the caller was waiting, :abandoned when the caller died or timed out and re-entered the wait

The :pid metadata is the connection process, useful for correlating events with process logs and crash reports.

Examples

Basic connect and RPC

iex> opts = [adapter: GRPC.Client.Adapters.Gun]
iex> {:ok, ch} = GRPC.Client.Connection.connect("127.0.0.1:50051", opts)
iex> req = %Grpc.Testing.SimpleRequest{response_size: 42}
iex> {:ok, resp} = Grpc.Testing.TestService.Stub.unary_call(ch, req)
iex> resp.response_size
42

Using interceptors and custom adapter

iex> opts = [interceptors: [GRPC.Client.Interceptors.Logger],
...>         adapter: GRPC.Client.Adapters.Mint]
iex> {:ok, ch} = GRPC.Client.Connection.connect("dns://my-service.local:50051", opts)
iex> {:ok, channel} = GRPC.Client.Connection.pick(ch)
iex> channel.host
"127.0.0.1"

Unix socket target

iex> {:ok, ch} = GRPC.Client.Connection.connect("unix:/tmp/service.sock")
iex> Grpc.Testing.TestService.Stub.empty_call(ch, %{})

Disconnect

iex> {:ok, ch} = GRPC.Client.Connection.connect("127.0.0.1:50051")
iex> GRPC.Client.Connection.disconnect(ch)
{:ok, %GRPC.Channel{...}}