gRPC & Protocol Buffers

Most important commands to remember

• grpcurl … list — discover exposed service names.
• grpcurl … describe — inspect reflected service and message definitions.

Commands and flags

Option or argument	Meaning
-plaintext	Use unencrypted HTTP/2 for this local lab only; grpcurl otherwise expects TLS.
-max-time 5	Set a five-second operation limit.
localhost:50051	The existing local gRPC endpoint.
list / describe	Query available symbols / print their definitions through server reflection.

Reflection must be enabled; not every production service exposes it. No business RPC is invoked.

The concepts that matter

1. An RPC presents a remote operation through a contract

gRPC lets a client invoke a method on a remote service using an explicit contract. Generated stubs can make that call look similar to a local function, but the network introduces latency, disconnection, and uncertain outcomes.

The contract names services and methods and describes request and response messages. A method name alone does not define authorization or business meaning; client and server must agree on the schema and behavior.

2. Protocol Buffers define structured messages

Protocol Buffers describe messages with typed, numbered fields and provide an efficient binary encoding. Field numbers identify data on the wire, so reusing an old number for a different meaning can break compatibility.

JSON shown by grpcurl is a human-facing representation, not proof that the wire payload is JSON. Schema evolution needs discipline: adding compatible fields differs from changing existing meaning or requiring every old client to understand a new field.

3. Calls can carry one message or streams

gRPC supports unary calls, server streaming, client streaming, and bidirectional streaming. A stream carries a sequence of messages rather than one unbounded blob. The sides need to handle pacing, cancellation, and partial progress.

Common gRPC transport uses HTTP/2, but an HTTP connection succeeding does not mean a method succeeded. gRPC status and metadata communicate the RPC result, often through trailers. Inspect those rather than relying on an HTTP 200 alone.

4. Deadlines make remote waiting explicit

A deadline limits how long the client is willing to wait. Cancellation signals that the caller no longer needs the result, but application code and downstream work must cooperate to stop useful processing.

A deadline exceeded response does not prove that the server performed no side effects. Retrying a mutating RPC can duplicate work unless the API provides an idempotency strategy. Remote calls need failure semantics that a simple local function call does not expose.

One small example

Optional: use the existing reflection-enabled local lab. No server is installed or started by these commands.

grpcurl -plaintext -max-time 5 localhost:50051 list
grpcurl -plaintext -max-time 5 localhost:50051 describe

The first command lists service names. The second prints reflected definitions, allowing you to identify RPC signatures and message fields. Read field numbers and types separately from display order.

A reflection-not-supported error means discovery is unavailable, not necessarily that ordinary RPC calls are broken. Connection refusal points to the local endpoint prerequisite; TLS errors can indicate a transport mismatch. Do not apply plaintext settings to a remote service carrying credentials.

The commands inspect the contract only. They do not establish method authorization, streaming behavior, or application success. No files or server state are created, so no cleanup is needed.

Keep this idea: A gRPC contract describes messages and methods; network failures, deadlines, and business effects still need explicit handling.