1 # gRPC over HTTP2 2 3 ## Introduction 4 This document serves as a detailed description for an implementation of gRPC carried over <a href="https://tools.ietf.org/html/rfc7540">HTTP2 framing</a>. It assumes familiarity with the HTTP2 specification. 5 6 ## Protocol 7 Production rules are using <a href="http://tools.ietf.org/html/rfc5234">ABNF syntax</a>. 8 9 ### Outline 10 11 The following is the general sequence of message atoms in a GRPC request & response message stream 12 13 * Request Request-Headers \*Length-Prefixed-Message EOS 14 * Response (Response-Headers \*Length-Prefixed-Message Trailers) / Trailers-Only 15 16 17 ### Requests 18 19 * Request Request-Headers \*Length-Prefixed-Message EOS 20 21 Request-Headers are delivered as HTTP2 headers in HEADERS + CONTINUATION frames. 22 23 * **Request-Headers** Call-Definition \*Custom-Metadata 24 * **Call-Definition** Method Scheme Path TE [Authority] [Timeout] Content-Type [Message-Type] [Message-Encoding] [Message-Accept-Encoding] [User-Agent] 25 * **Method** ":method POST" 26 * **Scheme** ":scheme " ("http" / "https") 27 * **Path** ":path" "/" Service-Name "/" {_method name_} # But see note below. 28 * **Service-Name** {_IDL-specific service name_} 29 * **Authority** ":authority" {_virtual host name of authority_} 30 * **TE** "te" "trailers" # Used to detect incompatible proxies 31 * **Timeout** "grpc-timeout" TimeoutValue TimeoutUnit 32 * **TimeoutValue** {_positive integer as ASCII string of at most 8 digits_} 33 * **TimeoutUnit** Hour / Minute / Second / Millisecond / Microsecond / Nanosecond 34 * **Hour** "H" 35 * **Minute** "M" 36 * **Second** "S" 37 * **Millisecond** "m" 38 * **Microsecond** "u" 39 * **Nanosecond** "n" 40 * **Content-Type** "content-type" "application/grpc" [("+proto" / "+json" / {_custom_})] 41 * **Content-Coding** "identity" / "gzip" / "deflate" / "snappy" / {_custom_} 42 * <a name="message-encoding"></a>**Message-Encoding** "grpc-encoding" Content-Coding 43 * **Message-Accept-Encoding** "grpc-accept-encoding" Content-Coding \*("," Content-Coding) 44 * **User-Agent** "user-agent" {_structured user-agent string_} 45 * **Message-Type** "grpc-message-type" {_type name for message schema_} 46 * **Custom-Metadata** Binary-Header / ASCII-Header 47 * **Binary-Header** {Header-Name "-bin" } {_base64 encoded value_} 48 * **ASCII-Header** Header-Name ASCII-Value 49 * **Header-Name** 1\*( %x30-39 / %x61-7A / "\_" / "-" / ".") ; 0-9 a-z \_ - . 50 * **ASCII-Value** 1\*( %x20-%x7E ) ; space and printable ASCII 51 52 53 HTTP2 requires that reserved headers, ones starting with ":" appear before all other headers. Additionally implementations should send **Timeout** immediately after the reserved headers and they should send the **Call-Definition** headers before sending **Custom-Metadata**. 54 55 Some gRPC implementations may allow the **Path** format shown above 56 to be overridden, but this functionality is strongly discouraged. 57 gRPC does not go out of its way to break users that are using this kind 58 of override, but we do not actively support it, and some functionality 59 (e.g., service config support) will not work when the path is not of 60 the form shown above. 61 62 If **Timeout** is omitted a server should assume an infinite timeout. Client implementations are free to send a default minimum timeout based on their deployment requirements. 63 64 **Custom-Metadata** is an arbitrary set of key-value pairs defined by the application layer. Header names starting with "grpc-" but not listed here are reserved for future GRPC use and should not be used by applications as **Custom-Metadata**. 65 66 Note that HTTP2 does not allow arbitrary octet sequences for header values so binary header values must be encoded using Base64 as per https://tools.ietf.org/html/rfc4648#section-4. Implementations MUST accept padded and un-padded values and should emit un-padded values. Applications define binary headers by having their names end with "-bin". Runtime libraries use this suffix to detect binary headers and properly apply base64 encoding & decoding as headers are sent and received. 67 68 **Custom-Metadata** header order is not guaranteed to be preserved except for 69 values with duplicate header names. Duplicate header names may have their values 70 joined with "," as the delimiter and be considered semantically equivalent. 71 Implementations must split **Binary-Header**s on "," before decoding the 72 Base64-encoded values. 73 74 **ASCII-Value** should not have leading or trailing whitespace. If it contains 75 leading or trailing whitespace, it may be stripped. The **ASCII-Value** 76 character range defined is more strict than HTTP. Implementations must not error 77 due to receiving an invalid **ASCII-Value** that's a valid **field-value** in 78 HTTP, but the precise behavior is not strictly defined: they may throw the value 79 away or accept the value. If accepted, care must be taken to make sure that the 80 application is permitted to echo the value back as metadata. For example, if the 81 metadata is provided to the application as a list in a request, the application 82 should not trigger an error by providing that same list as the metadata in the 83 response. 84 85 Servers may limit the size of **Request-Headers**, with a default of 8 KiB 86 suggested. Implementations are encouraged to compute total header size like 87 HTTP/2's `SETTINGS_MAX_HEADER_LIST_SIZE`: the sum of all header fields, for each 88 field the sum of the uncompressed field name and value lengths plus 32, with 89 binary values' lengths being post-Base64. 90 91 The repeated sequence of **Length-Prefixed-Message** items is delivered in DATA frames 92 93 * **Length-Prefixed-Message** Compressed-Flag Message-Length Message 94 * <a name="compressed-flag"></a>**Compressed-Flag** 0 / 1 # encoded as 1 byte unsigned integer 95 * **Message-Length** {_length of Message_} # encoded as 4 byte unsigned integer 96 * **Message** \*{binary octet} 97 98 A **Compressed-Flag** value of 1 indicates that the binary octet sequence of **Message** is compressed using the mechanism declared by the **Message-Encoding** header. A value of 0 indicates that no encoding of **Message** bytes has occurred. Compression contexts are NOT maintained over message boundaries, implementations must create a new context for each message in the stream. If the **Message-Encoding** header is omitted then the **Compressed-Flag** must be 0. 99 100 For requests, **EOS** (end-of-stream) is indicated by the presence of the END_STREAM flag on the last received DATA frame. In scenarios where the **Request** stream needs to be closed but no data remains to be sent implementations MUST send an empty DATA frame with this flag set. 101 102 ### Responses 103 104 * **Response** (Response-Headers \*Length-Prefixed-Message Trailers) / Trailers-Only 105 * **Response-Headers** HTTP-Status [Message-Encoding] [Message-Accept-Encoding] Content-Type \*Custom-Metadata 106 * **Trailers-Only** HTTP-Status Content-Type Trailers 107 * **Trailers** Status [Status-Message] \*Custom-Metadata 108 * **HTTP-Status** ":status 200" 109 * **Status** "grpc-status" 1\*DIGIT ; 0-9 110 * **Status-Message** "grpc-message" Percent-Encoded 111 * **Percent-Encoded** 1\*(Percent-Byte-Unencoded / Percent-Byte-Encoded) 112 * **Percent-Byte-Unencoded** 1\*( %x20-%x24 / %x26-%x7E ) ; space and VCHAR, except % 113 * **Percent-Byte-Encoded** "%" 2HEXDIGIT ; 0-9 A-F 114 115 **Response-Headers** & **Trailers-Only** are each delivered in a single HTTP2 HEADERS frame block. Most responses are expected to have both headers and trailers but **Trailers-Only** is permitted for calls that produce an immediate error. Status must be sent in **Trailers** even if the status code is OK. 116 117 For responses end-of-stream is indicated by the presence of the END_STREAM flag on the last received HEADERS frame that carries **Trailers**. 118 119 Implementations should expect broken deployments to send non-200 HTTP status codes in responses as well as a variety of non-GRPC content-types and to omit **Status** & **Status-Message**. Implementations must synthesize a **Status** & **Status-Message** to propagate to the application layer when this occurs. 120 121 Clients may limit the size of **Response-Headers**, **Trailers**, and 122 **Trailers-Only**, with a default of 8 KiB each suggested. 123 124 The value portion of **Status** is a decimal-encoded integer as an ASCII string, 125 without any leading zeros. 126 127 The value portion of **Status-Message** is conceptually a Unicode string 128 description of the error, physically encoded as UTF-8 followed by 129 percent-encoding. Percent-encoding is specified in [RFC 3986 130 2.1](https://tools.ietf.org/html/rfc3986#section-2.1), although the form used 131 here has different restricted characters. When decoding invalid values, 132 implementations MUST NOT error or throw away the message. At worst, the 133 implementation can abort decoding the status message altogether such that the 134 user would received the raw percent-encoded form. Alternatively, the 135 implementation can decode valid portions while leaving broken %-encodings as-is 136 or replacing them with a replacement character (e.g., '?' or the Unicode 137 replacement character). 138 139 #### Example 140 141 Sample unary-call showing HTTP2 framing sequence 142 143 **Request** 144 145 ``` 146 HEADERS (flags = END_HEADERS) 147 :method = POST 148 :scheme = http 149 :path = /google.pubsub.v2.PublisherService/CreateTopic 150 :authority = pubsub.googleapis.com 151 grpc-timeout = 1S 152 content-type = application/grpc+proto 153 grpc-encoding = gzip 154 authorization = Bearer y235.wef315yfh138vh31hv93hv8h3v 155 156 DATA (flags = END_STREAM) 157 <Length-Prefixed Message> 158 ``` 159 **Response** 160 ``` 161 HEADERS (flags = END_HEADERS) 162 :status = 200 163 grpc-encoding = gzip 164 content-type = application/grpc+proto 165 166 DATA 167 <Length-Prefixed Message> 168 169 HEADERS (flags = END_STREAM, END_HEADERS) 170 grpc-status = 0 # OK 171 trace-proto-bin = jher831yy13JHy3hc 172 ``` 173 174 #### User Agents 175 176 While the protocol does not require a user-agent to function it is recommended that clients provide a structured user-agent string that provides a basic description of the calling library, version & platform to facilitate issue diagnosis in heterogeneous environments. The following structure is recommended to library developers 177 ``` 178 User-Agent "grpc-" Language ?("-" Variant) "/" Version ?( " (" *(AdditionalProperty ";") ")" ) 179 ``` 180 E.g. 181 182 ``` 183 grpc-java/1.2.3 184 grpc-ruby/1.2.3 185 grpc-ruby-jruby/1.3.4 186 grpc-java-android/0.9.1 (gingerbread/1.2.4; nexus5; tmobile) 187 ``` 188 189 #### Idempotency and Retries 190 191 Unless explicitly defined to be, gRPC Calls are not assumed to be idempotent. Specifically: 192 193 * Calls that cannot be proven to have started will not be retried. 194 * There is no mechanism for duplicate suppression as it is not necessary. 195 * Calls that are marked as idempotent may be sent multiple times. 196 197 198 #### HTTP2 Transport Mapping 199 200 ##### Stream Identification 201 All GRPC calls need to specify an internal ID. We will use HTTP2 stream-ids as call identifiers in this scheme. NOTE: These ids are contextual to an open HTTP2 session and will not be unique within a given process that is handling more than one HTTP2 session nor can they be used as GUIDs. 202 203 ##### Data Frames 204 DATA frame boundaries have no relation to **Length-Prefixed-Message** boundaries and implementations should make no assumptions about their alignment. 205 206 ##### Errors 207 208 When an application or runtime error occurs during an RPC a **Status** and **Status-Message** are delivered in **Trailers**. 209 210 In some cases it is possible that the framing of the message stream has become corrupt and the RPC runtime will choose to use an **RST_STREAM** frame to indicate this state to its peer. RPC runtime implementations should interpret RST_STREAM as immediate full-closure of the stream and should propagate an error up to the calling application layer. 211 212 The following mapping from RST_STREAM error codes to GRPC error codes is applied. 213 214 HTTP2 Code|GRPC Code 215 ----------|----------- 216 NO_ERROR(0)|INTERNAL - An explicit GRPC status of OK should have been sent but this might be used to aggressively lameduck in some scenarios. 217 PROTOCOL_ERROR(1)|INTERNAL 218 INTERNAL_ERROR(2)|INTERNAL 219 FLOW_CONTROL_ERROR(3)|INTERNAL 220 SETTINGS_TIMEOUT(4)|INTERNAL 221 STREAM_CLOSED|No mapping as there is no open stream to propagate to. Implementations should log. 222 FRAME_SIZE_ERROR|INTERNAL 223 REFUSED_STREAM|UNAVAILABLE - Indicates that no processing occurred and the request can be retried, possibly elsewhere. 224 CANCEL(8)|Mapped to call cancellation when sent by a client.Mapped to CANCELLED when sent by a server. Note that servers should only use this mechanism when they need to cancel a call but the payload byte sequence is incomplete. 225 COMPRESSION_ERROR|INTERNAL 226 CONNECT_ERROR|INTERNAL 227 ENHANCE_YOUR_CALM|RESOURCE_EXHAUSTED ...with additional error detail provided by runtime to indicate that the exhausted resource is bandwidth. 228 INADEQUATE_SECURITY| PERMISSION_DENIED with additional detail indicating that permission was denied as protocol is not secure enough for call. 229 230 231 ##### Security 232 233 The HTTP2 specification mandates the use of TLS 1.2 or higher when TLS is used with HTTP2. It also places some additional constraints on the allowed ciphers in deployments to avoid known-problems as well as requiring SNI support. It is also expected that HTTP2 will be used in conjunction with proprietary transport security mechanisms about which the specification can make no meaningful recommendations. 234 235 ##### Connection Management 236 237 ###### GOAWAY Frame 238 Sent by servers to clients to indicate that they will no longer accept any new streams on the associated connections. This frame includes the id of the last successfully accepted stream by the server. Clients should consider any stream initiated after the last successfully accepted stream as UNAVAILABLE and retry the call elsewhere. Clients are free to continue working with the already accepted streams until they complete or the connection is terminated. 239 240 Servers should send GOAWAY before terminating a connection to reliably inform clients which work has been accepted by the server and is being executed. 241 242 ###### PING Frame 243 Both clients and servers can send a PING frame that the peer must respond to by precisely echoing what they received. This is used to assert that the connection is still live as well as providing a means to estimate end-to-end latency. If a server initiated PING does not receive a response within the deadline expected by the runtime all outstanding calls on the server will be closed with a CANCELLED status. An expired client initiated PING will cause all calls to be closed with an UNAVAILABLE status. Note that the frequency of PINGs is highly dependent on the network environment, implementations are free to adjust PING frequency based on network and application requirements. 244 245 ###### Connection failure 246 If a detectable connection failure occurs on the client all calls will be closed with an UNAVAILABLE status. For servers open calls will be closed with a CANCELLED status. 247 248 249 ### Appendix A - GRPC for Protobuf 250 251 The service interfaces declared by protobuf are easily mapped onto GRPC by 252 code generation extensions to protoc. The following defines the mapping 253 to be used. 254 255 * **Service-Name** ?( {_proto package name_} "." ) {_service name_} 256 * **Message-Type** {_fully qualified proto message name_} 257 * **Content-Type** "application/grpc+proto" 258 259 260
