Catalog My learning Blog
gRPC and Protobuf Tutorial: Fast Microservice APIs · Phase 3 · Lesson 19 · 3 min read

gRPC-Web: Calling gRPC from the Browser

On this page
  1. Why browsers can't call gRPC directly
  2. Option 1: gRPC-Web with a proxy
  3. Option 2: the Connect protocol
  4. Option 3: a JSON gateway with gRPC-Gateway or Envoy
  5. gRPC-Web vs Connect vs JSON gateway
  6. Protobuf JSON mapping details
  7. Check yourself

Why browsers can't call gRPC directly

gRPC depends on HTTP/2 features that browser JavaScript can't control: it needs trailers (the status arrives after the body, Day 7) and fine-grained control of HTTP/2 framing. The fetch API doesn't expose trailers. So a web app can't call a gRPC server directly, even over HTTP/2.

Option 1: gRPC-Web with a proxy

gRPC-Web is a variant protocol that browsers can speak: the status and trailers move into the response body, and it works over HTTP/1.1 or HTTP/2. A proxy translates between gRPC-Web and normal gRPC:

Code
Browser (gRPC-Web client)  --HTTP/1.1 or 2, gRPC-Web framing-->  Envoy (grpc_web filter)  --gRPC-->  OrderService

Envoy's envoy.filters.http.grpc_web filter does the translation, and some servers (grpc-dotnet, Connect-based servers) accept gRPC-Web directly without a proxy.

Limitations:

  • Unary and server streaming only. Client streaming and bidirectional streaming aren't supported from browsers.
  • An extra proxy hop and CORS configuration.

Option 2: the Connect protocol

Connect (from Buf) is a protocol, and a set of libraries, that serves the same .proto service over three protocols at once: gRPC, gRPC-Web and its own simple HTTP protocol. Connect requests are plain HTTP POSTs with JSON or binary bodies, so they're easy to call from fetch and debug with curl:

Shell
curl -H 'Content-Type: application/json' \
  -d '{"order_id":"ord_42"}' https://api.example.com/shop.v1.OrderService/GetOrder

Connect-ES generates TypeScript clients for browsers; Connect-Go servers need no translating proxy. The same streaming limits apply in browsers.

Browsers reach gRPC services through a gRPC-Web proxy, a Connect-compatible server that speaks browser-friendly protocols directly, or a gateway that transcodes REST and JSON into gRPC.
Browsers reach gRPC services through a gRPC-Web proxy, a Connect-compatible server that speaks browser-friendly protocols directly, or a gateway that transcodes REST and JSON into gRPC.

Option 3: a JSON gateway with gRPC-Gateway or Envoy

gRPC-Gateway (Go) or Envoy's gRPC-JSON transcoder expose gRPC methods as REST endpoints, using HTTP annotations in the .proto:

Protobuf
import "google/api/annotations.proto";

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (GetOrderResponse) {
    option (google.api.http) = { get: "/v1/orders/{order_id}" };
  }
}

Now GET /v1/orders/ord_42 returns JSON, generated from the same contract. Good for public REST APIs and clients that know nothing about gRPC; you also get an OpenAPI description generated from the annotations.

gRPC-Web vs Connect vs JSON gateway

NeedOption
Your own web app, typed client, streaming updatesConnect or gRPC-Web
Already running EnvoygRPC-Web filter
Public or partner REST API from the same servicesgRPC-Gateway or transcoding
Bidirectional streaming in the browserWebSockets or server-sent events alongside, since gRPC-Web can't

Protobuf JSON mapping details

Browser clients usually see JSON at some point, so remember the JSON mapping rules (Day 21): field names become lowerCamelCase, 64-bit integers become strings, enums become their names, and default values are omitted unless you ask for them.

Check yourself

Browser fetch APIs can't read HTTP trailers or control HTTP/2 framing, and gRPC relies on trailers for status and on framing for streaming. gRPC-Web and Connect move the status into the body so browsers can work with it.

Unary and server streaming. Client and bidirectional streaming don't work, because browser fetch APIs can't stream request bodies in a way gRPC-Web supports. Use WebSockets or separate calls for those patterns.

Add google.api.http annotations to RPCs, mapping each to an HTTP method and path, and use gRPC-Gateway or Envoy's transcoding filter to turn REST and JSON requests into gRPC calls.

A protocol from Buf that works over HTTP/1.1 and HTTP/2 with plain JSON or protobuf, so browsers can call services directly, while servers still speak gRPC too.