idnits 2.17.1 draft-kumar-rtgwg-grpc-protocol-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There is 1 instance of too long lines in the document, the longest one being 34 characters in excess of 72. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 158: '...c4648#section-4. Implementations MUST...' RFC 2119 keyword, line 218: '... implementations MUST send an empty DA...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 8, 2016) is 2842 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'Authority' is mentioned on line 83, but not defined == Missing Reference: 'Timeout' is mentioned on line 83, but not defined == Missing Reference: 'Message-Type' is mentioned on line 84, but not defined == Missing Reference: 'Message-Encoding' is mentioned on line 225, but not defined == Missing Reference: 'User-Agent' is mentioned on line 85, but not defined == Missing Reference: 'Status-Message' is mentioned on line 230, but not defined == Unused Reference: 'RFC7540' is defined on line 403, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) Summary: 5 errors (**), 0 flaws (~~), 9 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Kumar 3 Internet-Draft J. Kolhe 4 Intended status: Informational S. Ghemawat 5 Expires: January 9, 2017 L. Ryan 6 Google 7 July 8, 2016 9 gRPC Protocol 10 draft-kumar-rtgwg-grpc-protocol-00 12 Abstract 14 This document presents gRPC protocol specification. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on January 9, 2017. 33 Copyright Notice 35 Copyright (c) 2016 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Outline . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 52 3. Protocol Requests . . . . . . . . . . . . . . . . . . . . . . 2 53 4. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 5 54 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6 55 6. User Agents . . . . . . . . . . . . . . . . . . . . . . . . . 7 56 7. HTTP2 Transport Mapping . . . . . . . . . . . . . . . . . . . 7 57 8. Normative references . . . . . . . . . . . . . . . . . . . . 9 58 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 60 1. Introduction 62 This document serves as a detailed description for an implementation 63 of gRPC carried over HTTP2 draft 17 framing. It assumes familiarity 64 with the HTTP2 specification. 66 2. Outline 68 The following is the general sequence of message atoms in a GRPC 69 request and response message stream. 71 o Request -> Request-Headers *Length-Prefixed-Message EOS 73 o Response -> (Response-Headers *Length-Prefixed-Message Trailers) / 74 Trailers-Only 76 3. Protocol Requests 78 At a high level, the protocol has the following request and response 79 fields. 81 o Request-Headers -> Call-Definition *Custom-Metadata 83 o Call-Definition -> Method Scheme Path TE [Authority] [Timeout] 84 Content-Type [Message-Type] [Message-Encoding] [Message-Accept- 85 Encoding] [User-Agent] 87 o Method -> ":method POST" 89 o Scheme -> ":scheme " ("http" / "https") 91 o Path -> ":path" {path identifying method within exposed API} 93 o Authority -> ":authority" {virtual host name of authority} 95 o TE -> "te" "trailers" # Used to detect incompatible proxies 96 o Timeout -> "grpc-timeout" TimeoutValue TimeoutUnit 98 o TimeoutValue -> {positive integer as ASCII string of at most 8 99 digits} 101 o TimeoutUnit -> Hour / Minute / Second / Millisecond / Microsecond 102 / Nanosecond 104 o Hour -> "H" 106 o Minute -> "M" 108 o Second -> "S" 110 o Millisecond -> "m" 112 o Microsecond -> "u" 114 o Nanosecond -> "n" 116 o Content-Type -> "content-type" "application/grpc" [("+proto" / 117 "+json" / {custom})] 119 o Content-Coding -> "identity" / "gzip" / "deflate" / "snappy" / 120 {custom} 122 o Message-Encoding -> "grpc-encoding" Content-Coding 124 o Message-Accept-Encoding -> "grpc-accept-encoding" Content-Coding 125 *("," Content-Coding) 127 o User-Agent -> "user-agent" {structured user-agent string} 129 o Message-Type -> "grpc-message-type" {type name for message schema} 131 o Custom-Metadata -> Binary-Header / ASCII-Header 133 o Binary-Header -> {Header-Name "-bin" } {base64 encoded value} 135 o ASCII-Header -> Header-Name ASCII-Value 137 o Header-Name -> 1*( %x30-39 / %x61-7A / "_" / "-" / ".") ; 0-9 a-z 138 _ - . 140 o ASCII-Value -> 1*( %x20-%x7E ) ; space and printable ASCII 142 HTTP2 requires that reserved headers, ones starting with ":" appear 143 before all other headers. Additionally implementations should send 144 Timeout immediately after the reserved headers and they should send 145 the Call-Definition headers before sending Custom-Metadata. 147 If Timeout is omitted a server should assume an infinite timeout. 148 Client implementations are free to send a default minimum timeout 149 based on their deployment requirements. 151 Custom-Metadata is an arbitrary set of key-value pairs defined by the 152 application layer. Header names starting with "grpc-" but not listed 153 here are reserved for future GRPC use and should not be used by 154 applications as Custom-Metadata. 156 Note that HTTP2 does not allow arbitrary octet sequences for header 157 values so binary header values must be encoded using Base64 as per 158 https://tools.ietf.org/html/rfc4648#section-4. Implementations MUST 159 accept padded and un-padded values and should emit un-padded values. 160 Applications define binary headers by having their names end with 161 "-bin". Runtime libraries use this suffix to detect binary headers 162 and properly apply base64 encoding and decoding as headers are sent 163 and received. 165 Custom-Metadata header order is not guaranteed to be preserved except 166 for values with duplicate header names. Duplicate header names may 167 have their values joined with "," as the delimiter and be considered 168 semantically equivalent. Implementations must split Binary-Headers 169 on "," before decoding the Base64-encoded values. 171 ASCII-Value should not have leading or trailing whitespace. If it 172 contains leading or trailing whitespace, it may be stripped. The 173 ASCII-Value character range defined is more strict than HTTP. 174 Implementations must not error due to receiving an invalid ASCII- 175 Value that's a valid field-value in HTTP, but the precise behavior is 176 not strictly defined: they may throw the value away or accept the 177 value. If accepted, care must be taken to make sure that the 178 application is permitted to echo the value back as metadata. For 179 example, if the metadata is provided to the application as a list in 180 a request, the application should not trigger an error by providing 181 that same list as the metadata in the response. Servers may limit 182 the size of Request-Headers, with a default of 8 KiB suggested. 183 Implementations are encouraged to compute total header size like 184 HTTP/2's SETTINGS_MAX_HEADER_LIST_SIZE: the sum of all header fields, 185 for each field the sum of the uncompressed field name and value 186 lengths plus 32, with binary values' lengths being post-Base64. 188 Servers may limit the size of Request-Headers, with a default of 8 189 KiB suggested. Implementations are encouraged to compute total 190 header size like HTTP/2's SETTINGS_MAX_HEADER_LIST_SIZE: the sum of 191 all header fields, for each field the sum of the uncompressed field 192 name and value lengths plus 32, with binary values' lengths being 193 post-Base64. 195 The repeated sequence of Length-Prefixed-Message items is delivered 196 in DATA frames. 198 o Length-Prefixed-Message -> Compressed-Flag Message-Length Message 200 o Compressed-Flag -> 0 / 1 # encoded as 1 byte unsigned integer 202 o Message-Length -> {length of Message} # encoded as 4 byte unsigned 203 integer 205 o Message \u002D-> *{binary octet} 207 A Compressed-Flag value of 1 indicates that the binary octet sequence 208 of Message is compressed using the mechanism declared by the Message- 209 Encoding header. A value of 0 indicates that no encoding of Message 210 bytes has occurred. Compression contexts are NOT maintained over 211 message boundaries, implementations must create a new context for 212 each message in the stream. If the Message-Encoding header is 213 omitted then the Compressed-Flag must be 0. 215 For requests, EOS (end-of-stream) is indicated by the presence of the 216 END_STREAM flag on the last received DATA frame. In scenarios where 217 the Request stream needs to be closed but no data remains to be sent 218 implementations MUST send an empty DATA frame with this flag set. 220 4. Responses 222 o Response -> (Response-Headers *Length-Prefixed-Message Trailers) / 223 Trailers-Only 225 o Response-Headers -> HTTP-Status [Message-Encoding] [Message- 226 Accept-Encoding] Content-Type *Custom-Metadata 228 o Trailers-Only -> HTTP-Status Content-Type Trailers 230 o Trailers -> Status [Status-Message] *Custom-Metadata 232 o HTTP-Status -> ":status 200" 234 o Status -> "grpc-status" 236 o Status-Message -> "grpc-message" 238 Response-Headers and Trailers-Only are each delivered in a single 239 HTTP2 HEADERS frame block. Most responses are expected to have both 240 headers and trailers but Trailers-Only is permitted for calls that 241 produce an immediate error. Status must be sent in Trailers even if 242 the status code is OK. 244 For responses end-of-stream is indicated by the presence of the 245 END_STREAM flag on the last received HEADERS frame that carries 246 Trailers. 248 Implementations should expect broken deployments to send non-200 HTTP 249 status codes in responses as well as a variety of non-GRPC content- 250 types and to omit Status and Status-Message. Implementations must 251 synthesize a Status and Status-Message to propagate to the 252 application layer when this occurs. 254 Clients may limit the size of Response-Headers, Trailers, and 255 Trailers-Only, with a default of 8 KiB each suggested. 257 5. Examples 259 Sample unary-call showing HTTP2 framing sequence 261 Request 263 HEADERS (flags = END_HEADERS) 264 :method = POST 265 :scheme = http 266 :path = /google.pubsub.v2.PublisherService/CreateTopic 267 :authority = pubsub.googleapis.com 268 grpc-timeout = 1S 269 content-type = application/grpc+proto 270 grpc-encoding = gzip 271 authorization = Bearer y235.wef315yfh138vh31hv93hv8h3v 273 DATA (flags = END_STREAM) 274 276 Response 278 HEADERS (flags = END_HEADERS) 279 :status = 200 280 grpc-encoding = gzip 282 DATA 283 285 HEADERS (flags = END_STREAM, END_HEADERS) 286 grpc-status = 0 # OK 287 trace-proto-bin = jher831yy13JHy3hc 289 6. User Agents 291 While the protocol does not require a user-agent to function it is 292 recommended that clients provide a structured user-agent string that 293 provides a basic description of the calling library, version and 294 platform to facilitate issue diagnosis in heterogeneous environments. 295 The following structure is recommended to library developers 297 User-Agent \u002D-> "grpc-" Language ?("-" Variant) "/" Version ?( " (" *(AdditionalProperty ";") ")" ) 299 7. HTTP2 Transport Mapping 301 All GRPC calls need to specify an internal ID. We will use HTTP2 302 stream-ids as call identifiers in this scheme. NOTE: These id's are 303 contextual to an open HTTP2 session and will not be unique within a 304 given process that is handling more than one HTTP2 session nor can 305 they be used as GUIDs. 307 DATA frame boundaries have no relation to Length-Prefixed-Message 308 boundaries and implementations should make no assumptions about their 309 alignment. 311 When an application or runtime error occurs during an RPC a Status 312 and Status-Message are delivered in Trailers. In some cases it is 313 possible that the framing of the message stream has become corrupt 314 and the RPC runtime will choose to use an RST_STREAM frame to 315 indicate this state to its peer. RPC runtime implementations should 316 interpret RST_STREAM as immediate full-closure of the stream and 317 should propagate an error up to the calling application layer. 319 +-----------------------+-------------------------------------------+ 320 | HTTP2 Code# | GRPC Code | 321 +-----------------------+-------------------------------------------+ 322 | NO_ERROR(0) | INTERNAL - An explicit GRPC status of OK | 323 | | should have been sent but this might be | 324 | | used to aggressively lameduck in some | 325 | | scenarios. | 326 | | | 327 | PROTOCOL_ERROR(1) | INTERNAL | 328 | | | 329 | INTERNAL_ERROR(2) | INTERNAL | 330 | | | 331 | FLOW_CONTROL_ERROR(3) | INTERNAL | 332 | | | 333 | SETTINGS_TIMEOUT(4) | INTERNAL | 334 | | | 335 | STREAM_CLOSED | FRAME_SIZE_ERROR | 336 | | | 337 | STREAM_CLOSED | INTERNAL | 338 | | | 339 | REFUSED_STREAM | UNAVAILABLE - Indicates that no | 340 | | processing occurred and the request can | 341 | | be retried, possibly elsewhere. | 342 | | | 343 | CANCEL(8) | Mapped to call cancellation when sent by | 344 | | a client.Mapped to CANCELLED when sent by | 345 | | a server. Note that servers should only | 346 | | use this mechanism when they need to | 347 | | cancel a call but the payload byte | 348 | | sequence is incomplete. | 349 | | | 350 | COMPRESSION_ERROR | INTERNAL | 351 | | | 352 | CONNECT_ERROR | INTERNAL | 353 | | | 354 | ENHANCE_YOUR_CALM | RESOURCE_EXHAUSTED ...with additional | 355 | | error detail provided by runtime to | 356 | | indicate that the exhausted resource is | 357 | | bandwidth. | 358 | | | 359 | INADEQUATE_SECURITY | PERMISSION_DENIED ... with additional | 360 | | detail indicating that permission was | 361 | | denied as protocol is not secure enough | 362 | | for call. | 363 +-----------------------+-------------------------------------------+ 365 Table 1: Error Code Mapping 367 The HTTP2 specification mandates the use of TLS 1.2 or higher when 368 TLS is used with HTTP2. It also places some additional constraints 369 on the allowed ciphers in deployments to avoid known-problems as well 370 as requiring SNI support. It is also expected that HTTP2 will be 371 used in conjunction with proprietary transport security mechanisms 372 about which the specification can make no meaningful recommendations. 374 GOAWAY Frame Sent by servers to clients to indicate that they will no 375 longer accept any new streams on the associated connections. This 376 frame includes the id of the last successfully accepted stream by the 377 server. Clients should consider any stream initiated after the last 378 successfully accepted stream as UNAVAILABLE and retry the call 379 elsewhere. Clients are free to continue working with the already 380 accepted streams until they complete or the connection is terminated. 381 Servers should send GOAWAY before terminating a connection to 382 reliably inform clients which work has been accepted by the server 383 and is being executed. 385 PING Frame Both clients and servers can send a PING frame that the 386 peer must respond to by precisely echoing what they received. This 387 is used to assert that the connection is still live as well as 388 providing a means to estimate end-to-end latency. If a server 389 initiated PING does not receive a response within the deadline 390 expected by the runtime all outstanding calls on the server will be 391 closed with a CANCELLED status. An expired client initiated PING 392 will cause all calls to be closed with an UNAVAILABLE status. Note 393 that the frequency of PINGs is highly dependent on the network 394 environment, implementations are free to adjust PING frequency based 395 on network and application requirements. 397 Connection failure If a detectable connection failure occurs on the 398 client all calls will be closed with an UNAVAILABLE status. For 399 servers open calls will be closed with a CANCELLED status. 401 8. Normative references 403 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 404 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 405 DOI 10.17487/RFC7540, May 2015, 406 . 408 Authors' Addresses 409 Abhishek Kumar 410 Google 411 1600 Amphitheatre Pkwy 412 Mountain View, CA 94043 413 US 415 Email: abhikumar@google.com 417 Jayant Kolhe 418 Google 419 1600 Amphitheatre Pkwy 420 Mountain View, CA 94043 421 US 423 Email: jkolhe@google.com 425 Sanjay Ghemawat 426 Google 427 1600 Amphitheatre Pkwy 428 Mountain View, CA 94043 429 US 431 Email: sanjay@google.com 433 Louis Ryan 434 Google 435 1600 Amphitheatre Pkwy 436 Mountain View, CA 94043 437 US 439 Email: lryan@google.com