gRPC Unary RPC Explained
On this page
What is a unary RPC?
Most gRPC methods are unary: one request message in, one response message out. It's one of four call shapes, which the next days cover in turn:
| Call type | Client sends | Server sends | Everyday picture |
|---|---|---|---|
| Unary (Day 7) | One message | One message | Asking a question and getting an answer |
| Server streaming (Day 8) | One message | Many, over time | Subscribing to delivery updates |
| Client streaming (Day 9) | Many, over time | One message | Uploading a pile of receipts, then getting one total |
| Bidirectional (Day 10) | Many | Many, independently | A phone call |
Back to unary: GetOrder and CreateOrder in the course's service are unary:
rpc GetOrder(GetOrderRequest) returns (GetOrderResponse);What a unary call looks like on HTTP/2
- The client opens a new HTTP/2 stream on its existing connection and sends headers:
:path /shop.v1.OrderService/GetOrder,content-type: application/grpc, agrpc-timeoutif there's a deadline, plus any metadata (authorization). - It sends the request as a length-prefixed protobuf message and half-closes its side.
- The server runs the handler, sends response headers, the response message, and trailers with
grpc-statusandgrpc-message.
The status travels in trailers, after the body. That's why even an error is an HTTP 200 at the HTTP level: the gRPC status is what matters.
Calling a unary method with a deadline
Every call takes a context, which carries the deadline, cancellation and metadata:
ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
defer cancel()
ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer demo-token")
resp, err := client.GetOrder(ctx, &shopv1.GetOrderRequest{OrderId: "ord_42"})
if err != nil {
switch status.Code(err) {
case codes.NotFound:
// show "no such order"
case codes.DeadlineExceeded, codes.Unavailable:
// maybe retry, if the method is safe to retry (Day 22)
default:
return err
}
}The Go call blocks until the response or an error. Other languages offer both styles: Python stubs have blocking methods and .future() variants (or the grpc.aio async API), Java has blocking, future and async stubs, and C# returns awaitable calls.
Unary call outcomes: OK, NotFound, DeadlineExceeded
Calls to the course's GetOrder, as reported by grpcurl and the Go client:
no token -> Unauthenticated: missing or invalid bearer token
ord_42 -> OK, order returned
ord_9 -> NotFound: order "ord_9" not found
empty order_id -> InvalidArgument: order_id is required (with BadRequest details)
"slow" order,
500 ms deadline -> DeadlineExceeded after 500msAnd the server's interceptor log for the same calls:
unary /shop.v1.OrderService/GetOrder code=OK took=0s
unary /shop.v1.OrderService/GetOrder code=NotFound took=0s
unary /shop.v1.OrderService/GetOrder code=InvalidArgument took=0s
unary /shop.v1.OrderService/GetOrder code=Canceled took=500msEach outcome has a distinct, standard code (Day 14) the client can act on.
Rules for every unary call
- Always set a deadline (Day 15). A call without one can hang forever if the server stalls.
- Reuse the connection and client across calls.
- Check the status code, not just whether
erris nil, and decide retry behavior by code and method (Day 22). - Keep messages reasonably small: the default maximum received message size is 4 MB in most implementations. For large data, stream it (Day 9) or use object storage.
- Use unary unless you need streaming: it's simpler to load balance, retry, cache and observe.
Check yourself
The gRPC status is sent in HTTP/2 trailers after the response body. HTTP 200 only means the stream itself worked; the real outcome is in the grpc-status trailer, which is why HTTP-level monitoring alone misses gRPC errors.
Without one, a stalled server or network can leave the call waiting forever, holding goroutines, connections and memory on both sides. Under load, those stuck calls pile up until the client itself fails.
Metadata, sent as HTTP/2 headers alongside the request, usually as authorization: Bearer <token>. Interceptors on the server read it before the handler runs.
Client streaming: the client sends many messages over one stream and the server replies once at the end with a summary. It avoids the per-call overhead of thousands of unary calls and lets the server process points as they arrive.