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. header names may be upper- or mixed-case over HTTP/1.1, but trailers encoded in 52 the last length-prefixed message must always use lower-case names. 533. use EOF (end of body) to close the stream 54 55--- 56 57HTTP/2 related behavior (specified in [gRPC over HTTP2](PROTOCOL-HTTP2.md)) 58 591. stream-id is not supported or used 602. go-away is not supported or used 61 62--- 63 64Message framing (vs. [http2-transport-mapping](PROTOCOL-HTTP2.md#http2-transport-mapping)) 65 661. Response status encoded as part of the response body 67 * Key-value pairs encoded as a HTTP/1 headers block (without the terminating newline), per https://tools.ietf.org/html/rfc7230#section-3.2 68 ``` 69 key1: foo\r\n 70 key2: bar\r\n 71 ``` 722. 8th (MSB) bit of the 1st gRPC frame byte 73 * 0: data 74 * 1: trailers 75 ``` 76 10000000b: an uncompressed trailer (as part of the body) 77 10000001b: a compressed trailer 78 ``` 793. Trailers must be the last message of the response, as enforced 80by the implementation 814. Trailers-only responses: no change to the gRPC protocol spec. 82Trailers may be sent together with response headers, with no message 83in the body. 84 85--- 86 87User Agent 88 89* Do NOT use User-Agent header (which is to be set by browsers, by default) 90* Use X-User-Agent: grpc-web-javascript/0.1 (follow the same format as specified in [gRPC over HTTP2](PROTOCOL-HTTP2.md)) 91 92--- 93 94Text-encoded (response) streams 95 961. The client library should indicate to the server via the "Accept" header that 97the response stream needs to be text encoded e.g. when XHR is used or due 98to security policies with XHR 99 * Accept: application/grpc-web-text 1002. The default text encoding is base64 101 * Note that “Content-Transfer-Encoding: base64” should not be used. 102 Due to in-stream base64 padding when delimiting messages, the entire 103 response body is not necessarily a valid base64-encoded entity 104 * While the server runtime will always base64-encode and flush gRPC messages 105 atomically the client library should not assume base64 padding always 106 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. 107 108# Other features 109 110Retries, caching 111 112* Will spec out the support after their respective gRPC spec extensions 113are finalized 114 * Safe retries: PUT 115 * Caching: header encoded request and/or a web specific spec 116 117--- 118 119Keep-alive 120 121* HTTP/2 PING is not supported or used 122* Will not support send-beacon (GET) 123 124--- 125 126Bidi-streaming, with flow-control 127 128* Pending on [whatwg fetch/streams](https://github.com/whatwg/fetch) to be 129finalized and implemented in modern browsers 130* gRPC-Web client will support the native gRPC protocol with modern browsers 131 132--- 133 134Versioning 135 136* Special headers may be introduced to support features that may break compatibility. 137 138--- 139 140Browser-specific features 141 142* For features that are unique to browser or HTML clients, check the [spec doc](https://github.com/grpc/grpc-web/blob/master/doc/browser-features.md) published in the grpc/grpc-web repo. 143