gRPC Web

gRPC-Web provides a JS client library that supports the same API as gRPC-Node to access a gRPC service. Due to browser limitation, the Web client library implements a different protocol than the native gRPC protocol. This protocol is designed to make it easy for a proxy to translate between the protocols as this is the most likely deployment model.

This document lists the differences between the two protocols. To help tracking future revisions, this document describes a delta with the protocol details specified in the native gRPC protocol.

Design goals

For the gRPC-Web protocol, we have decided on the following design goals:

adopt the same framing as “application/grpc” whenever possible
decouple from HTTP/2 framing which is not, and will never be, directly exposed by browsers
support text streams (e.g. base64) in order to provide cross-browser support (e.g. IE-10)

While the new protocol will be published/reviewed publicly, we also intend to keep the protocol as an internal detail to gRPC-Web. More specifically, we expect the protocol to

evolve over time, mainly to optimize for browser clients or support web-specific features such as CORS, XSRF
become optional (in 1-2 years) when browsers are able to speak the native gRPC protocol via the new whatwg streams API

Protocol differences vs gRPC over HTTP2

Content-Type

application/grpc-web

e.g. application/grpc-web+[proto, json, thrift]
the sender should always specify the message format, e.g. +proto, +json
the receiver should assume the default is "+proto" when the message format is missing in Content-Type (as "application/grpc-web")

application/grpc-web-text

text-encoded streams of “application/grpc-web”
e.g. application/grpc-web-text+[proto, thrift]

HTTP wire protocols

support any HTTP/*, with no dependency on HTTP/2 specific framing
header names may be upper- or mixed-case over HTTP/1.1, but trailers encoded in the last length-prefixed message must always use lower-case names.
use EOF (end of body) to close the stream

HTTP/2 related behavior (specified in gRPC over HTTP2)

stream-id is not supported or used
go-away is not supported or used

Message framing (vs. http2-transport-mapping)

Response status encoded as part of the response body

Key-value pairs encoded as a HTTP/1 headers block (without the terminating newline), per https://tools.ietf.org/html/rfc7230#section-3.2

  key1: foo\r\n
  key2: bar\r\n

8th (MSB) bit of the 1st gRPC frame byte

0: data
1: trailers

  10000000b: an uncompressed trailer (as part of the body)
  10000001b: a compressed trailer

Trailers must be the last message of the response, as enforced by the implementation
Trailers-only responses: no change to the gRPC protocol spec. Trailers may be sent together with response headers, with no message in the body.

User Agent

Do NOT use User-Agent header (which is to be set by browsers, by default)
Use X-User-Agent: grpc-web-javascript/0.1 (follow the same format as specified in gRPC over HTTP2)

Text-encoded (response) streams

The client library should indicate to the server via the "Accept" header that the response stream needs to be text encoded e.g. when XHR is used or due to security policies with XHR

Accept: application/grpc-web-text

The default text encoding is base64

Note that “Content-Transfer-Encoding: base64” should not be used. Due to in-stream base64 padding when delimiting messages, the entire response body is not necessarily a valid base64-encoded entity
While the server runtime will always base64-encode and flush gRPC messages atomically the client library should not assume base64 padding always happens at the boundary of message frames. That is, the implementation may send base64-encoded "chunks" with potential padding whenever the runtime needs to flush a byte buffer.

Other features

Retries, caching

Will spec out the support after their respective gRPC spec extensions are finalized
- Safe retries: PUT
- Caching: header encoded request and/or a web specific spec

Keep-alive

HTTP/2 PING is not supported or used
Will not support send-beacon (GET)

Bidi-streaming, with flow-control

Pending on whatwg fetch/streams to be finalized and implemented in modern browsers
gRPC-Web client will support the native gRPC protocol with modern browsers

Versioning

Special headers may be introduced to support features that may break compatibility.

Browser-specific features

For features that are unique to browser or HTML clients, check the spec doc published in the grpc/grpc-web repo.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!