diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/PROTOCOL-WEB.md | 151 | ||||
| -rw-r--r-- | doc/core/pending_api_cleanups.md | 6 | ||||
| -rw-r--r-- | doc/cpp/pending_api_cleanups.md | 2 |
3 files changed, 155 insertions, 4 deletions
diff --git a/doc/PROTOCOL-WEB.md b/doc/PROTOCOL-WEB.md new file mode 100644 index 0000000000..7d9b9f069a --- /dev/null +++ b/doc/PROTOCOL-WEB.md @@ -0,0 +1,151 @@ +# Overview + +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](http://www.grpc.io/docs/guides/wire.html). +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](http://www.grpc.io/docs/guides/wire.html). + +# 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 fetch/streams API](https://github.com/whatwg/fetch) + +# Protocol differences vs [gRPC over HTTP2](http://www.grpc.io/docs/guides/wire.html) + +Content-Type + +1. application/grpc-web + * e.g. application/grpc-web+[proto, json, thrift] +2. application/grpc-web-text + * text-encoded streams of “application/grpc-web” + +--- + +HTTP wire protocols + +1. support any HTTP/*, with no dependency on HTTP/2 specific framing +2. use lower-case header/trailer names +3. use EOF (end of body) to close the stream + +--- + +HTTP/2 related behavior (specified in [gRPC over HTTP2](http://www.grpc.io/docs/guides/wire.html)) + +1. stream-id is not supported or used +2. go-away is not supported or used + +--- + +Message framing (vs. [http2-transport-mapping](http://www.grpc.io/docs/guides/wire.html#http2-transport-mapping)) + +1. Response status encoded as part of the response body + * Key-value pairs formatted as HTTP/1.1 headers block (without the empty + newline \r\n to terminate the block) +2. 8th (MSB) bit of the 1st gRPC frame byte + * 0: data + * 1: trailers +3. Trailers must be the last message of the response, as enforced +by the implementation +4. Trailers-only responses: no change to the gRPC protocol spec. +Trailers will be sent together with response headers, with no message +in the body. + +--- + +User Agent + +* grpc-web-javascript/0.1 + +--- + +Text-encoded (response) streams + +1. 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 +2. The default text encoding is base64 + * Text encoding may be specified with Content-Type or Accept headers as + * application/grpc-web-text-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. +3. For binary trailers, when the content-type is set to +application/grpc-web-text, the extra base64 encoding specified +in [gRPC over HTTP2](http://www.grpc.io/docs/guides/wire.html) +for binary custom metadata is skipped. + +# Other features + +Compression + +* Full-body compression is supported and expected for all unary +requests/responses. The compression/decompression will be done +by browsers, using standard Content-Encoding headers + * “grpc-encoding” header is not used + * SDCH, Brotli will be supported +* Message-level compression for streamed requests/responses is not supported +because manual compression/decompression is prohibitively expensive using JS + * Per-message compression may be feasible in future with wasm + +--- + +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 + +--- + +Security + +* XSRF, XSS etc to be specified + +--- + +CORS preflight + +* The client library may support header overwrites to avoid preflight + * https://github.com/whatwg/fetch/issues/210 +* CSP support to be specified + +--- + +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](https://github.com/whatwg/fetch) to be +finalized and implemented in modern browsers +* gRPC-Web client will support the native gRPC protocol with modern browsers diff --git a/doc/core/pending_api_cleanups.md b/doc/core/pending_api_cleanups.md index a0a960e5e2..67d587dead 100644 --- a/doc/core/pending_api_cleanups.md +++ b/doc/core/pending_api_cleanups.md @@ -13,7 +13,5 @@ number: - remove `GRPC_ARG_MAX_MESSAGE_LENGTH` channel arg from `include/grpc/impl/codegen/grpc_types.h` (commit `af00d8b`) -- remove `ServerBuilder::SetMaxMessageSize()` method from - `include/grpc++/server_builder.h` (commit `6980362`) -- remove `GRPC_INITIAL_METADATA_IGNORE_CONNECTIVITY` macro from - `include/grpc/impl/codegen/grpc_types.h` (commit `59c9f90`) + (cannot be done until after next grpc release, so that TensorFlow can + use the same code both internally and externally) diff --git a/doc/cpp/pending_api_cleanups.md b/doc/cpp/pending_api_cleanups.md index 3e77b657c6..517d503cb0 100644 --- a/doc/cpp/pending_api_cleanups.md +++ b/doc/cpp/pending_api_cleanups.md @@ -11,5 +11,7 @@ This file lists all pending backward-compatibility changes that should be cleaned up the next time we are going to bump the major version number: +- remove `ServerBuilder::SetMaxMessageSize()` method from + `include/grpc++/server_builder.h` (commit `6980362`) - remove `ClientContext::set_fail_fast()` method from `include/grpc++/impl/codegen/client_context.h` (commit `9477724`) |