1# gRPC Web
2
3gRPC-Web provides a JS client library that supports the same API
4as gRPC-Node to access a gRPC service. Due to browser limitation,
5the Web client library implements a different protocol than the
6[native gRPC protocol](PROTOCOL-HTTP2.md).
7This protocol is designed to make it easy for a proxy to translate
8between the protocols as this is the most likely deployment model.
9
10This document lists the differences between the two protocols.
11To help tracking future revisions, this document describes a delta
12with the protocol details specified in the
13[native gRPC protocol](PROTOCOL-HTTP2.md).
14
15# Design goals
16
17For the gRPC-Web protocol, we have decided on the following design goals:
18
19* adopt the same framing as “application/grpc” whenever possible
20* decouple from HTTP/2 framing which is not, and will never, be directly
21exposed by browsers
22* support text streams (e.g. base64) in order to provide cross-browser
23support (e.g. IE-10)
24
25While the new protocol will be published/reviewed publicly, we also
26intend to keep the protocol as an internal detail to gRPC-Web.
27More specifically, we expect the protocol to
28
29* evolve over time, mainly to optimize for browser clients or support
30web-specific features such as CORS, XSRF
31* become optional (in 1-2 years) when browsers are able to speak the native
32gRPC protocol via the new [whatwg streams API](https://github.com/whatwg/streams)
33
34# Protocol differences vs [gRPC over HTTP2](PROTOCOL-HTTP2.md)
35
36Content-Type
37
381. application/grpc-web
39  * e.g. application/grpc-web+[proto, json, thrift]
40  * the sender should always specify the message format, e.g. +proto, +json
41  * the receiver should assume the default is "+proto" when the message format is missing in Content-Type (as "application/grpc-web")
422. application/grpc-web-text
43  * text-encoded streams of “application/grpc-web”
44  * e.g. application/grpc-web-text+[proto, thrift]
45
46---
47
48HTTP wire protocols
49
501. support any HTTP/*, with no dependency on HTTP/2 specific framing
512. use lower-case header/trailer names
523. use EOF (end of body) to close the stream
53
54---
55
56HTTP/2 related behavior (specified in [gRPC over HTTP2](PROTOCOL-HTTP2.md))
57
581. stream-id is not supported or used
592. go-away is not supported or used
60
61---
62
63Message framing (vs. [http2-transport-mapping](PROTOCOL-HTTP2.md#http2-transport-mapping))
64
651. Response status encoded as part of the response body
66  * Key-value pairs encoded as a HTTP/1 headers block (without the terminating newline), per https://tools.ietf.org/html/rfc7230#section-3.2
67  ```
68    key1: foo\r\n
69    key2: bar\r\n
70  ```
712. 8th (MSB) bit of the 1st gRPC frame byte
72  * 0: data
73  * 1: trailers
74  ```
75    10000000b: an uncompressed trailer (as part of the body)
76    10000001b: a compressed trailer
77  ```
783. Trailers must be the last message of the response, as enforced
79by the implementation
804. Trailers-only responses: no change to the gRPC protocol spec.
81Trailers may be sent together with response headers, with no message
82in the body.
83
84---
85
86User Agent
87
88* Do NOT use User-Agent header (which is to be set by browsers, by default)
89* Use X-User-Agent: grpc-web-javascript/0.1 (follow the same format as specified in [gRPC over HTTP2](PROTOCOL-HTTP2.md))
90
91---
92
93Text-encoded (response) streams
94
951. The client library should indicate to the server via the "Accept" header that
96the response stream needs to be text encoded e.g. when XHR is used or due
97to security policies with XHR
98  * Accept: application/grpc-web-text
992. The default text encoding is base64
100  * Note that “Content-Transfer-Encoding: base64” should not be used.
101  Due to in-stream base64 padding when delimiting messages, the entire
102  response body is not necessarily a valid base64-encoded entity
103  * While the server runtime will always base64-encode and flush gRPC messages
104  atomically the client library should not assume base64 padding always
105  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.
106
107# Other features
108
109Retries, caching
110
111* Will spec out the support after their respective gRPC spec extensions
112are finalized
113  * Safe retries: PUT
114  * Caching: header encoded request and/or a web specific spec
115
116---
117
118Keep-alive
119
120* HTTP/2 PING is not supported or used
121* Will not support send-beacon (GET)
122
123---
124
125Bidi-streaming, with flow-control
126
127* Pending on [whatwg fetch/streams](https://github.com/whatwg/fetch) to be
128finalized and implemented in modern browsers
129* gRPC-Web client will support the native gRPC protocol with modern browsers
130
131---
132
133Versioning
134
135* Special headers may be introduced to support features that may break compatibility.
136
137---
138
139Browser-specific features
140
141* For features that are unique to browser or HTML clients, check the [spec doc](https://github.com/grpc/grpc-web/blob/master/BROWSER-FEATURES.md) published in the grpc/grpc-web repo.
142