Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 39 ยท Load Balancing and Gateways

gRPC-Web, Envoy and Proxies

Learn why browsers cannot speak native gRPC, how the gRPC-Web protocol and framing work, how Envoy or Connect bridge them, with a runnable Go frame encoder and decoder.

A browser cannot make a native gRPC call. The reasons are technical, not political: gRPC needs control over HTTP/2 framing and trailers (the final status travels there), and the fetch and XMLHttpRequest APIs hide both. So a web page cannot connect directly to a plain gRPC server.

There are three common ways around it: gRPC-Web (a slightly modified protocol plus a translating proxy), REST transcoding (previous lesson) and Connect (a protocol that works over plain HTTP and is directly browser friendly). This lesson explains gRPC-Web and what proxies sit in the path.

The proxies and the gRPC-Web JavaScript client cannot run on this site, so their configuration is shown read-only. The framing format of gRPC-Web is simple enough to implement in a few lines of Go, and that code does run here.

How gRPC-Web differs from gRPC

  • The status and trailers are sent inside the response body as a final special frame, since a browser cannot read HTTP trailers.
  • Content types are application/grpc-web+proto (binary) and application/grpc-web-text (base64 text, which can stream in old browsers).
  • Only unary and server streaming calls are supported. Client streaming and bidirectional streaming are not possible over fetch in browsers today.
  • It works over HTTP/1.1 and HTTP/2, which also makes it friendly to older proxies.
flowchart LR
    B["Browser<br/>gRPC-Web client"] -->|"HTTP + grpc-web frames"| E["Envoy or<br/>gRPC-Web proxy"]
    E -->|"native gRPC (HTTP/2, trailers)"| S["gRPC server"]

The proxy converts gRPC-Web framing to native gRPC and back.

The wire format

A gRPC message, in native gRPC and in gRPC-Web, is wrapped in a length-prefixed frame:

TEXT
+--------+----------------------+------------------+
| flag   | length (4 bytes, BE) | payload          |
| 1 byte |                      | (protobuf bytes) |
+--------+----------------------+------------------+
  • The flag is 0x00 for a data frame (bit 0 would mean "compressed").
  • In gRPC-Web, a frame with the high bit set (0x80) holds the trailers, encoded as HTTP header text (grpc-status: 0\r\n).

So a unary gRPC-Web response body is: one data frame with the protobuf response, then one trailer frame with the status.

Runnable: encode and decode frames

Go gRPC-Web message and trailer frames

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.

A real client does exactly this: read frames from the response stream, decode data frames as protobuf and read the final trailer frame for the status. Because frames carry their own length, server streaming works naturally: the server just keeps appending data frames.

Base64 text mode

For grpc-web-text, the whole stream is base64-encoded. The decoder reads four characters at a time, so frames can be consumed as they arrive. It is slightly bigger (about 33 percent) but works where binary streaming does not.

Go Text mode is just base64 of the same frames

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.

Using it from the browser (read-only)

With the official grpc-web package or the newer @connectrpc/connect-web, the generated client looks like an ordinary async API:

TypeScript
import { createPromiseClient } from "@connectrpc/connect";
import { createGrpcWebTransport } from "@connectrpc/connect-web";
import { UserService } from "./gen/users/v1/users_connect";

const transport = createGrpcWebTransport({ baseUrl: "https://api.example.com" });
const client = createPromiseClient(UserService, transport);

const user = await client.getUser({ id: "42" });
console.log(user.name);

The same generated service definition can use the Connect protocol or gRPC-Web as the transport, so you can switch without touching call sites.

Envoy configuration (read-only)

Envoy ships a grpc_web HTTP filter that does the translation, and a cors filter because browsers will send cross-origin requests:

YAML
http_filters:
  - name: envoy.filters.http.grpc_web
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.grpc_web.v3.GrpcWeb
  - name: envoy.filters.http.cors
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.cors.v3.Cors
  - name: envoy.filters.http.router
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

The route forwards to a cluster configured with http2_protocol_options (the upstream is native gRPC). CORS must allow the headers x-grpc-web, content-type and x-user-agent and expose grpc-status and grpc-message. Most "gRPC-Web does not work" problems are missing CORS settings or a proxy that buffers streaming responses.

Choosing an approach

Need Pick
Browser app that already has a gRPC API, simple setup gRPC-Web through Envoy
Public REST/JSON API plus curl-friendly docs grpc-gateway or Envoy JSON transcoding
One server that browsers, curl and gRPC clients all call directly Connect (Go connect-go), no proxy needed
Bidirectional streaming in the browser WebSocket or WebTransport, outside gRPC-Web

Remember that every proxy hop must forward HTTP/2 and trailers correctly for the native side, and must not buffer streamed responses. Check load balancing for the interaction with balancing.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why can browsers not make native gRPC calls?

    gRPC relies on HTTP/2 control and trailers, which fetch and XMLHttpRequest do not expose.
  2. 2. Where does gRPC-Web put the final status?

    Because browsers cannot read trailers, gRPC-Web sends them as a frame with the high bit set.
  3. 3. Which call types does gRPC-Web support?

    Browsers cannot stream request bodies with fetch in a portable way, so client and bidirectional streaming are unsupported.
  4. 4. What is the first byte of a gRPC length-prefixed frame?

    The frame starts with one flag byte, followed by a four-byte big-endian length and then the payload.

Summary

  • Browsers cannot speak native gRPC, so use gRPC-Web (with a proxy such as Envoy), REST transcoding, or Connect.
  • gRPC-Web wraps messages in the same length-prefixed frames and sends trailers in a final frame with the 0x80 flag.
  • Only unary and server-streaming calls work; text mode base64-encodes the same bytes.
  • Envoy needs the grpc_web filter, correct CORS headers and an HTTP/2 upstream.
  • Pick the simplest option that fits: gRPC-Web for existing gRPC APIs, REST for public APIs, Connect for one server for all clients.

Next: Testing gRPC Services