From 0258444a81347d16f47cdb19445d12308184ffb9 Mon Sep 17 00:00:00 2001 From: Wenbo Zhu Date: Mon, 27 Feb 2017 14:21:42 -0800 Subject: Update PROTOCOL-WEB.md Addressed @mwitkow comments. https://github.com/grpc/grpc-web/issues/57 --- doc/PROTOCOL-WEB.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) (limited to 'doc/PROTOCOL-WEB.md') diff --git a/doc/PROTOCOL-WEB.md b/doc/PROTOCOL-WEB.md index 35448d683f..b7a930a7d4 100644 --- a/doc/PROTOCOL-WEB.md +++ b/doc/PROTOCOL-WEB.md @@ -39,6 +39,7 @@ Content-Type * e.g. application/grpc-web+[proto, json, thrift] 2. application/grpc-web-text * text-encoded streams of “application/grpc-web” + * e.g. application/grpc-web+[proto, thrift] --- @@ -61,9 +62,17 @@ Message framing (vs. [http2-transport-mapping](http://www.grpc.io/docs/guides/wi 1. Response status encoded as part of the response body * Key-value pairs encoded as a HTTP/1 headers block (without the terminating newline). + ``` + key1: foo\r\n + key2: bar\r\n + ``` 2. 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 + ``` 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. @@ -72,10 +81,9 @@ in the body. --- -User Agent and Server headers +User Agent -* U-A: grpc-web-javascript/0.1 -* Server: grpc-web-gateway/0.1 +* U-A: grpc-web-javascript --- @@ -93,7 +101,7 @@ to security policies with XHR 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. + 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. 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) @@ -131,6 +139,10 @@ Security CORS preflight +* Should follow the [CORS spec](https://developer.mozilla.org/en-US/docs/Web/HTTP/Server-Side_Access_Control) + * Access-Control-Allow-Credentials to allow Authorization headers + * Access-Control-Allow-Methods to allow POST and (preflight) OPTIONS only + * Access-Control-Allow-Headers to whatever the preflight request carries * The client library may support header overwrites to avoid preflight * https://github.com/whatwg/fetch/issues/210 * CSP support to be specified @@ -149,3 +161,10 @@ 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 + +--- + +Versioning + +* Special headers may be introduced to support features that may break compatiblity. + -- cgit v1.2.3