Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 39 ยท Getting Started

How gRPC Uses HTTP/2

See how a gRPC call maps to HTTP/2: streams, headers, the 5-byte message prefix and trailers that carry the status. Includes runnable Go stand-ins.

gRPC does not invent its own network protocol. Every call is an ordinary HTTP/2 request and response with some agreed conventions on top. Knowing those conventions makes debugging, load balancing and proxy configuration much easier, because you can read what is actually on the wire.

This lesson covers the HTTP/2 features gRPC depends on, then the exact layout of a gRPC message. The message framing described here is the real format; the Go programs reproduce it using only the standard library.

HTTP/2 in one page

HTTP/2 differs from HTTP/1.1 in ways that matter to gRPC:

  • Binary frames. Everything is split into small typed frames: HEADERS, DATA, RST_STREAM, WINDOW_UPDATE and others.
  • Streams and multiplexing. One TCP connection carries many independent streams, each with an id. Frames from different streams interleave, so a slow call does not block the others.
  • Header compression (HPACK). Repeated headers such as the method path cost almost nothing after the first call.
  • Flow control. Each stream and the whole connection have windows that limit how much unacknowledged data a sender may transmit.
  • Trailers. A response can end with a final HEADERS frame after its data. gRPC uses this to report the result.
sequenceDiagram
  participant C as Client
  participant S as Server
  C->>S: HEADERS (POST /greeter.v1.Greeter/SayHello, content-type application/grpc)
  C->>S: DATA (length-prefixed request, END_STREAM)
  S->>C: HEADERS (:status 200, content-type application/grpc)
  S->>C: DATA (length-prefixed response)
  S->>C: HEADERS trailers (grpc-status 0, END_STREAM)

A unary call: one request message, one response message, then trailers with the status.

What a gRPC request looks like

The request headers include:

Header Example Meaning
:method POST Always POST
:path /greeter.v1.Greeter/SayHello /package.Service/Method
content-type application/grpc Marks it as gRPC (+proto is optional)
te trailers The client understands trailers
grpc-timeout 2S The deadline, as a duration
grpc-encoding gzip Message compression, if used

The response carries :status 200 almost always, even when the call failed. The real outcome is in the trailers: grpc-status (a number, 0 means OK) and an optional grpc-message. This is why a gRPC failure is not an HTTP 4xx or 5xx. See gRPC vs REST for how gateways map statuses back to HTTP codes.

The length-prefixed message

Inside DATA frames, each protobuf message is wrapped in a 5-byte prefix:

Text
[ 1 byte: compressed flag ][ 4 bytes: big-endian message length ][ message bytes ]

The flag is 0 for an uncompressed message and 1 if the message was compressed with the negotiated algorithm. The length lets a reader know where one message ends and the next begins, which is what makes streaming over one HTTP/2 stream possible.

Stand-in 1: framing and unframing messages

This program implements exactly this framing. The "messages" are plain strings here, not protobuf, but the prefix logic is the real gRPC wire format.

Go Stand-in: gRPC message framing

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 reader never needs to know how many messages will arrive. It reads a prefix, reads that many bytes, and repeats until the stream ends. A streaming RPC is just this loop kept running.

Multiplexing: many calls, one connection

Because every message belongs to a numbered stream, a client can have hundreds of calls in flight on a single TCP connection. This is the reason gRPC clients keep a channel open for a long time and reuse it (see clients and channels).

Stand-in 2: interleaved streams on one connection

This simulation sends frames from three calls in an interleaved order and reassembles each call by its stream id. It is not real HTTP/2, but it shows the principle that makes multiplexing work.

Go Stand-in: multiplexed streams

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.

Client streams use odd ids (1, 3, 5, ...) in real HTTP/2, which the sample mirrors.

Status codes live in trailers

A server that fails a call still sends :status 200, then ends the stream with trailers such as:

Text
grpc-status: 5
grpc-message: book 99 not found

5 is NOT_FOUND. There are about seventeen status codes; the full list and how to choose one come in a later chapter on error handling, listed on the track page. If a server sends the trailers in the first HEADERS frame with no data (a "trailers-only" response), the call fails before any message is sent.

Why this matters in practice

  • Proxies must speak HTTP/2 end to end and support trailers. A proxy that downgrades to HTTP/1.1 breaks gRPC.
  • Load balancers that balance per connection spread load badly, because one long-lived connection carries many calls. gRPC often needs per-call balancing.
  • Timeouts are expressed with grpc-timeout and travel with the call, so a deadline can be honored across services. See deadlines.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does gRPC report whether a call succeeded?

    The HTTP status is normally 200. The real result is the grpc-status trailer (0 means OK).
  2. 2. What is the 5-byte prefix before every message?

    The flag says whether the message is compressed; the length lets a reader split a byte stream into messages.
  3. 3. What does multiplexing allow?

    Each call is a stream with its own id, so frames from many calls interleave on one connection.
  4. 4. Why can an HTTP/1.1-only proxy break gRPC?

    Without HTTP/2 framing and trailers, the status and streaming semantics cannot be carried.

Summary

  • A gRPC call is an HTTP/2 POST to /package.Service/Method with content-type: application/grpc.
  • Each message is prefixed by a compressed flag and a 4-byte length.
  • The result of the call is in the grpc-status trailer, not in the HTTP status.
  • Streams let many calls share one connection; flow control keeps senders from overwhelming receivers.
  • Proxies and load balancers must understand HTTP/2 to work with gRPC.

Next: Installing protoc and Plugins