English for gRPC-Web Developers

gRPC-Web lets browser clients talk to gRPC services, but it isn’t gRPC itself — it’s a restricted protocol that needs a proxy to translate to and from true HTTP/2 gRPC, and it only supports a subset of streaming modes. Teams that assume gRPC-Web behaves identically to backend-to-backend gRPC run into confusing gaps, especially around bidirectional streaming. This guide covers the English used when discussing gRPC-Web with a team.

Key Vocabulary

Envoy proxy (translation layer) — the intermediary (commonly Envoy or a similar proxy) that sits between the browser and the gRPC backend, translating gRPC-Web’s HTTP/1.1-compatible framing into real HTTP/2 gRPC calls. “The browser can’t speak raw HTTP/2 gRPC directly — that’s why we need the Envoy translation layer in front of the backend.”

Server streaming (supported) — the one streaming mode gRPC-Web fully supports from the browser: the server can push a sequence of messages back over a single request. “Server streaming works fine here — the client opens one request and just keeps receiving chunks as they’re generated.”

Client/bidirectional streaming (unsupported) — the streaming modes gRPC-Web does not support natively in the browser; a client can’t keep a stream open and send multiple messages the way it can in backend-to-backend gRPC. “We can’t port this bidirectional chat feature to gRPC-Web as-is — the browser can’t stream requests, only receive a stream back, so we’d need WebSockets or a different pattern for the upload side.”

Codegen / stub — the generated client code (a “stub”) produced from a .proto file by the protocol buffer compiler, giving the frontend typed methods instead of hand-written fetch calls. “Regenerate the stub after you change the .proto file — the frontend is still calling a method that no longer matches the updated service definition.”

Trailer — metadata sent after the response body in a gRPC call (typically the final status code), which gRPC-Web has to smuggle differently than native gRPC since browsers can’t read HTTP trailers directly. “The status code comes through in a trailer, not a normal header — that’s why you can’t just check response.status the way you would with a plain REST call.”

Interceptor — a client-side or proxy-side hook that runs on every call (adding auth tokens, logging, retries) without modifying each generated stub method individually. “Add the auth token in a client interceptor instead of editing every generated method by hand — the codegen output shouldn’t need manual changes.”

Common Phrases

• “Is this a server-streaming call, or does it need real bidirectional streaming that gRPC-Web can’t do from the browser?”
• “Did we regenerate the stub after the last .proto change, or is the frontend still calling the old signature?”
• “Where’s the proxy translation layer sitting in this deployment — sidecar, gateway, or load balancer?”
• “Is the status code coming through correctly, or is something eating the trailer?”
• “Should this cross-cutting concern go in a client interceptor rather than every call site?”

Example Sentences

Reviewing a pull request: “This tries to open a persistent bidirectional stream from the browser — gRPC-Web can’t do that natively, so we’ll need to redesign this as request/response or server streaming.”

Explaining a design decision: “We put an Envoy proxy in front of the gRPC backend specifically to translate gRPC-Web traffic — the browser never talks HTTP/2 gRPC directly.”

Describing an incident: “The client was silently failing because it was reading response.status directly instead of parsing the trailer where gRPC-Web actually puts the real status code.”

Professional Tips

• Say “gRPC-Web doesn’t support client streaming” precisely rather than “streaming is broken” — it names the actual constraint and avoids someone chasing a bug that isn’t there.
• When proposing a new browser-facing endpoint, ask “does this need bidirectional streaming?” early — it determines whether gRPC-Web is even viable for that feature.
• Use “stub” and “codegen” deliberately when discussing generated client code — it clarifies the code shouldn’t be hand-edited, only regenerated.
• Mention the “trailer” explicitly when debugging status codes — most REST-background engineers won’t think to look there first.

Practice Exercise

1. Explain in two sentences why gRPC-Web needs a proxy translation layer in front of the backend.
2. Write a one-sentence code review comment recommending a feature be redesigned because it needs unsupported bidirectional streaming.
3. Describe, in your own words, the difference between a header and a trailer in a gRPC-Web response.