1. Response status encoded as part of the response body
1. Response status encoded as part of the response body
* Key-value pairs encoded as a HTTP/1 headers block (without the terminating newline).
* Key-value pairs encoded as a HTTP/1 headers block (without the terminating newline), per https://tools.ietf.org/html/rfc7230#section-3.2
```
key1: foo\r\n
key2: bar\r\n
```
2. 8th (MSB) bit of the 1st gRPC frame byte
2. 8th (MSB) bit of the 1st gRPC frame byte
* 0: data
* 0: data
* 1: trailers
* 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
3. Trailers must be the last message of the response, as enforced
by the implementation
by the implementation
4. Trailers-only responses: no change to the gRPC protocol spec.
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
* U-A: grpc-web-javascript
* Server: grpc-web-gateway/0.1
---
---
@ -93,7 +101,7 @@ to security policies with XHR
response body is not necessarily a valid base64-encoded entity
response body is not necessarily a valid base64-encoded entity
* While the server runtime will always base64-encode and flush gRPC messages
* While the server runtime will always base64-encode and flush gRPC messages
atomically the client library should not assume base64 padding always
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
3. For binary trailers, when the content-type is set to
application/grpc-web-text, the extra base64 encoding specified
application/grpc-web-text, the extra base64 encoding specified
in [gRPC over HTTP2](http://www.grpc.io/docs/guides/wire.html)
in [gRPC over HTTP2](http://www.grpc.io/docs/guides/wire.html)
@ -131,6 +139,10 @@ Security
CORS preflight
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
* The client library may support header overwrites to avoid preflight
* https://github.com/whatwg/fetch/issues/210
* https://github.com/whatwg/fetch/issues/210
* CSP support to be specified
* 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
* Pending on [whatwg fetch/streams](https://github.com/whatwg/fetch) to be
finalized and implemented in modern browsers
finalized and implemented in modern browsers
* gRPC-Web client will support the native gRPC protocol with 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.
As a universal RPC framework, gRPC needs to be fully usable within/across different international environments.
This document describes gRPC API and behavior specifics when used in a non-english environment.
## API Concepts
While some API elements need to be able to represent non-english content, some are intentionally left as ASCII-only
for simplicity & performance reasons.
### Method name (in RPC Invocation)
Method names are ASCII-only and may only contain characters allowed by HTTP/2 text header values. That should not
be very limiting as most gRPC services will use protobuf which only allows method names from an even more restricted ASCII subset.
Also, handling method names is a very hot code path so any additional encoding/decoding step is to be avoided.
Recommended representation in language-specific APIs: string type.
### Host name (in RPC Invocation)
Host names are punycode encoded, but the user is responsible for providing the punycode-encoded string if she wishes to use an internationalized host name.
Recommended representation in language-specific APIs: string/unicode string.
NOTE: overriding host name when invoking RPCs is only supported by C-core based gRPC implementations.
### Status detail/message (accompanies RPC status code)
Status messages are expected to contain national-alphabet characters.
Allowed values are unicode strings (content will be percent-encoded on the wire).
Recommended representation in language-specific APIs: unicode string.
### Metadata key
Allowed values are defined by HTTP/2 standard (metadata keys are represented as HTTP/2 header/trailer names).
Recommended representation in language-specific APIs: string.
### Metadata value (text-valued metadata)
Allowed values are defined by HTTP/2 standard (metadata values are represented as HTTP/2 header/trailer text values).
Recommended representation in language-specific APIs: string.
Craig Tiller
8 years ago