Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 39 ยท Services and RPC Types

gRPC Clients, Channels and Stubs

Learn how gRPC clients work: channels, stubs, connection reuse, dial options, retry policies and backoff. Real Go code is read-only; runnable Go stand-ins model reuse and retries.

A gRPC client has two main objects. The channel (called ClientConn in Go) represents a long-lived connection to a server or a set of servers, including name resolution, load balancing and reconnection. The stub is a lightweight generated object that gives you typed methods and sends calls over a channel. Understanding the difference prevents the most common client mistake: creating a new connection for every call.

The real library cannot run on this site, so real code is read-only; the stand-ins are plain Go programs that model the behavior.

Creating a channel and stub (Go, read-only)

Go
conn, err := grpc.NewClient("catalog.internal:50051",
	grpc.WithTransportCredentials(creds),
)
if err != nil {
	log.Fatal(err)
}
defer conn.Close()

client := pb.NewCatalogClient(conn)

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

p, err := client.GetProduct(ctx, &pb.GetProductRequest{Id: 1})
if err != nil {
	st, _ := status.FromError(err)
	log.Printf("call failed: %s: %s", st.Code(), st.Message())
	return
}
log.Println(p.GetName())

What happens here:

  • grpc.NewClient creates the channel lazily: it does not connect until the first call (older code used grpc.Dial, which has options to block until connected).
  • The target string is parsed by a resolver: dns:///catalog.internal:50051, passthrough:///host:port, or a custom scheme from a service-discovery system.
  • NewCatalogClient(conn) is cheap and holds no connection of its own. Create as many stubs as you like from one channel.
  • The context carries the deadline. Always set one, as discussed in deadlines and cancellation.

Reuse the channel

A channel multiplexes many calls on one HTTP/2 connection (see how gRPC uses HTTP/2). Creating a channel per call wastes a TCP handshake, a TLS handshake and an HTTP/2 setup every time, and can exhaust ports. The rule:

Create one channel per target at startup, share it everywhere, close it at shutdown.

Channels are thread-safe in every official language implementation.

Stand-in 1: connection reuse versus reconnecting

This stand-in counts how many "connections" are opened when a client makes 20 calls, once with a new connection per call and once with a shared one.

Go Stand-in: shared channel vs one per call

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Dial options you will use

Option Purpose
WithTransportCredentials TLS (or insecure.NewCredentials() for local tests only)
WithDefaultServiceConfig Retry, timeout and load-balancing policy as JSON
WithKeepaliveParams Pings that detect dead connections
WithUnaryInterceptor Client-side cross-cutting code (see the interceptors chapter on the track page)
WithDefaultCallOptions Max message size, compression, wait-for-ready

Wait for ready. By default a call fails fast with UNAVAILABLE if the channel is not connected. grpc.WaitForReady(true) makes the call wait until the connection is ready (bounded by the deadline), which smooths over server restarts.

Retries

Networks drop calls. gRPC supports automatic retries configured in a service config (JSON) rather than code:

Go
const serviceConfig = `{
  "methodConfig": [{
    "name": [{"service": "shop.v1.Catalog", "method": "GetProduct"}],
    "timeout": "2s",
    "retryPolicy": {
      "maxAttempts": 4,
      "initialBackoff": "0.1s",
      "maxBackoff": "1s",
      "backoffMultiplier": 2,
      "retryableStatusCodes": ["UNAVAILABLE"]
    }
  }]
}`

conn, _ := grpc.NewClient(target,
	grpc.WithTransportCredentials(creds),
	grpc.WithDefaultServiceConfig(serviceConfig),
)

Rules for safe retries:

  1. Only retry idempotent methods (see defining services).
  2. Retry only transient codes such as UNAVAILABLE; never retry INVALID_ARGUMENT or NOT_FOUND.
  3. Use exponential backoff with jitter, so that thousands of clients do not retry in lockstep and overload a recovering server.
  4. Respect the overall deadline. Retries share the one deadline of the original call.

Stand-in 2: retry with exponential backoff and jitter

This program calls a flaky function that fails twice with UNAVAILABLE and then succeeds. The delays are computed with a fixed random seed so output is reproducible.

Go Stand-in: retries with backoff

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The invalid-argument call is attempted exactly once: retrying a request that is wrong would be pointless. The always-failing call gives up after three attempts and returns the last error. (The actual wait values depend on the random generator, so we do not print them in the lesson text.)

Python and Java clients

The concepts carry over unchanged:

Python
channel = grpc.insecure_channel("localhost:50051")   # long-lived, share it
stub = catalog_pb2_grpc.CatalogStub(channel)
product = stub.GetProduct(catalog_pb2.GetProductRequest(id=1), timeout=2.0)
Java
ManagedChannel channel = ManagedChannelBuilder.forTarget("localhost:50051").usePlaintext().build();
CatalogGrpc.CatalogBlockingStub stub = CatalogGrpc.newBlockingStub(channel);
Product p = stub.withDeadlineAfter(2, TimeUnit.SECONDS).getProduct(GetProductRequest.newBuilder().setId(1).build());

Java and C# offer blocking, async (future) and asynchronous stub flavors; Go uses one synchronous-looking stub with goroutines for concurrency.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the recommended number of channels per target in a process?

    Channels are cheap to share and expensive to create; they multiplex many calls.
  2. 2. Which status codes are typically safe to retry?

    UNAVAILABLE signals a transient failure. The others are caller or logic errors that will repeat.
  3. 3. Why add jitter to backoff?

    Synchronized retries create load spikes against a recovering server.
  4. 4. Where is a gRPC retry policy usually configured?

    Service config describes retry, timeout and balancing per method.

Summary

  • A channel is the long-lived connection layer; a stub is a cheap typed facade over it.
  • Share one channel per target; never dial per call.
  • Always set deadlines; consider wait-for-ready for restart tolerance.
  • Retry only idempotent methods and transient codes, with exponential backoff and jitter.
  • The same model applies in Go, Java, Python and every other language.

Next: Deadlines and Cancellation