Update PROTOCOL-WEB.md

Addressed @mwitkow comments.

https://github.com/grpc/grpc-web/issues/57

1 files changed, 23 insertions, 4 deletions

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.
+