Capture HTTP/2 and gRPC

ReqRes captures HTTP/1.1 unless you turn on its HTTP/2 beta. gRPC-Web and Connect calls are decoded with the switch on or off; native gRPC needs it on.

Turn on HTTP/2 capture#

1. Open Settings ▸ Capture.
2. In the HTTP/2 section, turn on Capture HTTP/2 (beta).

The section explains the switch: "When an app and the server both speak HTTP/2, ReqRes speaks it to both and records one row per request. WebSockets stay on HTTP/1.1. Turn this off if a site misbehaves."

• The change applies to connections opened after it. A connection already open keeps its protocol. You do not need to restart capture.
• When either side does not offer HTTP/2, the request is HTTP/1.1 on both sides.
• In the app's words: "A host with an enabled Map Local rule, or an Override rule with a body, stays on HTTP/1.1 so ReqRes can answer it without contacting the server."
• The requests open at the same time on one HTTP/2 connection keep at most 64 MB of bodies between them, and each keeps at most 16 MB. Every byte is still sent on.

With the switch off, the app and the server both speak HTTP/1.1 to ReqRes. Most apps accept this without noticing. An app that offers only HTTP/2 fails instead. Its Failed row gives the reason, for example: "The app speaks only HTTP/2 and closed the connection to api.example.com because ReqRes answered it with HTTP/1.1: Capture HTTP/2 is off — turn it on in Settings ▸ Capture. This is not certificate pinning; excluding the host is not the fix." See why a request failed explains Failed rows.

See which protocol a request used#

Open the request's Metrics tab. The Protocol row, first under Connection, reads HTTP/1.1, HTTP/2, WebSocket or relay/tcp. An HTTP/2 request adds: "One stream on a connection it may share with other requests; ReqRes spoke HTTP/2 to the app and to the server."

To filter the traffic list by protocol, type one of these in the search field:

http2, websocket and tcp work as values too. A row with no recorded protocol matches none of them. Search and filter traffic covers the other tokens.

Read trailers#

Trailers are header fields sent after the body. Native gRPC puts its status there. The Headers tab lists them after the headers, under Request Trailers or Response Trailers with the caption "Sent after the body." The Summary tab counts them, as in "Response Trailers (2)".

Read a gRPC call#

gRPC-Web and Connect need no setting. Each call is one row, and a finished call gets an RPC tab on the response side. The tab shows:

• The protocol, the codec, the service and the method, as in "gRPC-Web · protobuf · helloworld.Greeter / SayHello".
• The status and where ReqRes read it, as in "Status NOT_FOUND (5) — “no such user” · from the trailer frame".
• How many request and response messages there were, and the trailers.
• Each message, such as "Request 1 · 24 B", decoded without the .proto file.

Without the .proto there are no field names. Each field shows its number and value, in the layout of protoc --decode_raw. Where a field's bytes also read as another type, that reading appears dimmed beside it.

1: 42
2: "Ann"
3 {
  1: 7
}

A gRPC-Web error arrives as HTTP 200. When the call's status says something the HTTP status does not, the traffic list shows that status, such as NOT_FOUND, at the start of the URL. The Code column keeps the 200. Hover the URL to read "HTTP 200, gRPC status NOT_FOUND" and the error message.

A call that streams is listed from its response head and grows while it runs. The RPC tab appears once it finishes. Read streaming responses covers rows that are still open.

Capture native gRPC#

Native gRPC is a beta. It needs HTTP/2 capture: with the switch off, a gRPC client fails through ReqRes.

1. Turn on Capture HTTP/2 (beta), as above.
2. Point the client at http://127.0.0.1:8034 with the environment lines from Settings ▸ Capture. Most gRPC libraries ignore the macOS system proxy, so their calls are not in the list until you do. Use your own port if you changed it.
3. Give the client the ReqRes certificate the way its TLS library reads one, usually as a file.

Capture command-line tools and agents explains the lines and the certificate file. The status comes from the response trailers, or from the response head when the server answered with trailers only. When ReqRes cannot reach the server, it answers a gRPC call with HTTP 200 and grpc-status 14 (UNAVAILABLE), with the reason as grpc-message.

Find calls by status#

The chip reads "gRPC error" or "gRPC NOT_FOUND". A row that is not an RPC matches none of them, not even grpc:error. Neither does a call whose status was never recorded, such as a stream cut before its trailers.

What an agent reads#

• list_sessions marks each request row proto=h1, h2 or ws, and each RPC row grpc= with its status. It filters by proto and grpc.
• get_session gives the HTTP version and the trailers. With view=rpc it returns the service, the method, every message decoded without a schema, 20 per page and at most 100, and the status with its source.
• diagnose_setup says whether HTTP/2 capture is on.

Redaction in view=rpc works by shape only for protobuf strings. Tokens such as JWTs and long random keys are masked, but a short secret in a protobuf string is not recognised. Control what agents see explains redaction.

Related#

• Inspect a request
• Read streaming responses
• Supported protocols