TodayTools

gRPC Remote Procedure Calls

How gRPC works

Apps calling each other's functions

Donate
L7ApplicationPort 443TCP
What brings you here?

Watch it happen

How much detail

The checkout service asks the inventory service: how many of this tea are in stock?

Checkout service
Load balancer
Inventory service
CableRequestResponseControlEncrypted

4 steps, 4 packets

First up: Call starts. Press Play to watch it happen, one step at a time.

0 of 40/4

What is gRPC?

gRPC lets one program call a function in another program over the network as if it were local. You describe the functions and their data in a .proto file, a tool generates code for both sides, and each call travels as an HTTP/2 stream carrying small binary Protocol Buffers messages.

It is popular for services talking to each other inside companies and for mobile apps that need speed. Calls can be one request and one reply, or streams in either direction. Deadlines, cancellation and clear status codes are built in, which keeps large systems from piling up stuck requests.

Think of it like this. A REST API is like posting a letter in your own words and hoping the reader understands. gRPC is like filling in a printed form that both offices agreed on: every box has a number and a type, so it is quick to fill, quick to read, and nobody argues over what a field means. The deadline is the line on the form that says reply by noon or forget it.

Step by step

Normal

4 steps

The checkout service asks the inventory service: how many of this tea are in stock?

  1. 1

    Call starts

    HEADERS name the function

    Calling GetStock in code becomes an HTTP/2 POST. The path names the service and method. The connection was opened earlier and is reused for every call.

  2. 2

    Request message

    A tiny protobuf in a DATA frame

    The request is encoded with Protocol Buffers: compact binary, not text. A 5-byte prefix says how long it is.

  3. 3

    Reply

    Headers and a protobuf answer

    The server answers on the same stream with :status 200 and a DATA frame holding the reply message.

  4. 4

    Trailers

    grpc-status: 0 means OK

    The real result comes last, in trailers. HTTP 200 only means the HTTP part worked; grpc-status says whether the call itself succeeded.

Streaming

4 steps

A stock dashboard subscribes to live updates. One call, many replies, until it stops watching.

  1. 1

    Subscribe

    One request opens the stream

    WatchStock is a server streaming method. The caller sends one request and keeps the stream open.

  2. 2

    Updates flow

    Each change is a new message

    Every time stock changes, the server sends another length-prefixed message on the same stream. No polling, no new requests.

  3. 3

    Flow control

    WINDOW_UPDATE keeps it moving

    HTTP/2 flow control stops a fast sender from flooding a slow reader. The reader opens the window as it consumes messages.

  4. 4

    Stop watching

    RST_STREAM with CANCEL

    When the dashboard closes, the client cancels the call. The server sees the cancel and stops the work. The client side reports status CANCELLED.

Deadline exceeded

4 steps

The database is slow. The checkout will only wait 300 ms, so the call is cancelled instead of hanging.

  1. 1

    Call with a deadline

    grpc-timeout: 300m

    The checkout must answer the shopper quickly, so it gives the call 300 milliseconds. The deadline travels with the request.

  2. 2

    Slow database

    The inventory service is stuck waiting

    The inventory service asks the database, which is busy. Good servers pass the remaining time on, so the database query has a deadline too.

  3. 3

    Time is up

    Cancel, then DEADLINE_EXCEEDED

    At 300 ms the checkout's library cancels the stream with RST_STREAM and reports status 4, DEADLINE_EXCEEDED, to the code. No thread is left waiting forever.

  4. 4

    Work stops everywhere

    The cancel spreads

    The load balancer passes the cancel on. The inventory service sees its call was cancelled and stops the database query. The checkout shows a fallback, such as usually ships in 2 days.

Myths and mix-ups

  • An HTTP 200 means the gRPC call worked; the real result is grpc-status in the trailers.
  • gRPC only works with Protocol Buffers; protobuf is the default, but other formats can be plugged in.
  • Browsers can call gRPC services directly; they cannot read HTTP/2 trailers from page code, so they need gRPC-Web and a proxy.
  • A call without a deadline is safe; it can hang forever and tie up threads when something downstream is slow.

Try it yourself

Run these on your own computer to see gRPC at work.

  • List services on a server

    grpcurl -plaintext localhost:50051 list

    Needs grpcurl and a server with reflection turned on. Drop -plaintext for TLS servers.

  • Call a method

    grpcurl -plaintext -d '{"sku":"TEA-0042"}' localhost:50051 inventory.v1.Inventory/GetStock

    Sends JSON, grpcurl turns it into protobuf and prints the reply as JSON.

  • Set a deadline

    grpcurl -plaintext -max-time 0.3 -d '{"sku":"TEA-0042"}' localhost:50051 inventory.v1.Inventory/GetStock

    Gives up after 0.3 seconds, like the deadline scenario.

  • Check a health endpoint

    grpcurl -plaintext localhost:50051 grpc.health.v1.Health/Check

    Many servers offer the standard health check service.

gRPC at a glance

Layer
Application (7)
Runs on
HTTP/2 (stream per call)
Port
Any; often 443, or 50051 in examples
Data format
Protocol Buffers (binary)
Call types
Unary, server stream, client stream, two-way stream
Result
grpc-status in trailers (0 is OK)
First released
2015 (1.0 in 2016)

Defined ingRPC over HTTP/2 protocol specRFC 9113Protocol Buffers

Header fields

What gRPC puts in its messages, with example values from the stories above.

gRPC message

Compressed flag
00 means the message is not compressed.
Message length
15Five bytes of prefix tell the reader exactly where each message ends.
Protobuf type
inventory.v1.GetStockRequestBoth sides compiled the same .proto file, so they agree on what every byte means.

HTTP/2 HEADERS (0x1)

Type
HEADERS (0x1)
Flags
0x05 (END_STREAM, END_HEADERS)
Stream ID
1Each gRPC call is one HTTP/2 stream. Many calls share one connection.
grpc-status
0 (OK)Other common codes: 3 invalid argument, 4 deadline exceeded, 5 not found, 14 unavailable, 16 unauthenticated.
grpc-message
(none)
:path
/inventory.v1.Inventory/...The function to call: /package.Service/Method.
content-type
application/grpcTells proxies and the server this is gRPC, not a normal web request.
grpc-timeout
300mThe deadline: how long the caller is willing to wait. m means milliseconds, S seconds.

Test yourself

Question 1 of 5Score 0

What does gRPC run on?

Questions people ask

What is the difference between gRPC and REST?

REST usually sends JSON over HTTP with URLs and verbs you design yourself. gRPC uses a shared .proto contract, binary messages and HTTP/2 streams, with generated code and built-in streaming and deadlines.

What port does gRPC use?

Any port you choose. Public services often use 443. Many examples and local setups use 50051.

Can a browser call gRPC?

Not directly, because page code cannot control HTTP/2 framing or read trailers. gRPC-Web, with a proxy in front of the server, fills the gap.

Is gRPC faster than REST?

Usually its messages are smaller and quicker to encode, and one connection carries many calls. For simple public APIs the difference is often small.

What does DEADLINE_EXCEEDED mean in gRPC?

The caller's time limit ran out before a reply came. Check what is slow downstream, and make sure each service passes the remaining time on to its own calls.

Donate