[Docs] [txt|pdf] [Tracker] [Email] [Nits]

Versions: 00

Network Working Group                                           A. Kumar
Internet-Draft                                                  J. Kolhe
Intended status: Informational                               S. Ghemawat
Expires: January 9, 2017                                         L. Ryan
                                                                  Google
                                                            July 8, 2016


                             gRPC Protocol
                   draft-kumar-rtgwg-grpc-protocol-00

Abstract

   This document presents gRPC protocol specification.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on January 9, 2017.

Copyright Notice

   Copyright (c) 2016 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.





Kumar, et al.            Expires January 9, 2017                [Page 1]


Internet-Draft         gRPC Protocol Specification             July 2016


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Outline . . . . . . . . . . . . . . . . . . . . . . . . . . .   2
   3.  Protocol Requests . . . . . . . . . . . . . . . . . . . . . .   2
   4.  Responses . . . . . . . . . . . . . . . . . . . . . . . . . .   5
   5.  Examples  . . . . . . . . . . . . . . . . . . . . . . . . . .   6
   6.  User Agents . . . . . . . . . . . . . . . . . . . . . . . . .   7
   7.  HTTP2 Transport Mapping . . . . . . . . . . . . . . . . . . .   7
   8.  Normative references  . . . . . . . . . . . . . . . . . . . .   9
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   9

1.  Introduction

   This document serves as a detailed description for an implementation
   of gRPC carried over HTTP2 draft 17 framing.  It assumes familiarity
   with the HTTP2 specification.

2.  Outline

   The following is the general sequence of message atoms in a GRPC
   request and response message stream.

   o  Request -> Request-Headers *Length-Prefixed-Message EOS

   o  Response -> (Response-Headers *Length-Prefixed-Message Trailers) /
      Trailers-Only

3.  Protocol Requests

   At a high level, the protocol has the following request and response
   fields.

   o  Request-Headers -> Call-Definition *Custom-Metadata

   o  Call-Definition -> Method Scheme Path TE [Authority] [Timeout]
      Content-Type [Message-Type] [Message-Encoding] [Message-Accept-
      Encoding] [User-Agent]

   o  Method -> ":method POST"

   o  Scheme -> ":scheme " ("http" / "https")

   o  Path -> ":path" {path identifying method within exposed API}

   o  Authority -> ":authority" {virtual host name of authority}

   o  TE -> "te" "trailers" # Used to detect incompatible proxies



Kumar, et al.            Expires January 9, 2017                [Page 2]


Internet-Draft         gRPC Protocol Specification             July 2016


   o  Timeout -> "grpc-timeout" TimeoutValue TimeoutUnit

   o  TimeoutValue -> {positive integer as ASCII string of at most 8
      digits}

   o  TimeoutUnit -> Hour / Minute / Second / Millisecond / Microsecond
      / Nanosecond

   o  Hour -> "H"

   o  Minute -> "M"

   o  Second -> "S"

   o  Millisecond -> "m"

   o  Microsecond -> "u"

   o  Nanosecond -> "n"

   o  Content-Type -> "content-type" "application/grpc" [("+proto" /
      "+json" / {custom})]

   o  Content-Coding -> "identity" / "gzip" / "deflate" / "snappy" /
      {custom}

   o  Message-Encoding -> "grpc-encoding" Content-Coding

   o  Message-Accept-Encoding -> "grpc-accept-encoding" Content-Coding
      *("," Content-Coding)

   o  User-Agent -> "user-agent" {structured user-agent string}

   o  Message-Type -> "grpc-message-type" {type name for message schema}

   o  Custom-Metadata -> Binary-Header / ASCII-Header

   o  Binary-Header -> {Header-Name "-bin" } {base64 encoded value}

   o  ASCII-Header -> Header-Name ASCII-Value

   o  Header-Name -> 1*( %x30-39 / %x61-7A / "_" / "-" / ".") ; 0-9 a-z
      _ - .

   o  ASCII-Value -> 1*( %x20-%x7E ) ; space and printable ASCII

   HTTP2 requires that reserved headers, ones starting with ":" appear
   before all other headers.  Additionally implementations should send



Kumar, et al.            Expires January 9, 2017                [Page 3]


Internet-Draft         gRPC Protocol Specification             July 2016


   Timeout immediately after the reserved headers and they should send
   the Call-Definition headers before sending Custom-Metadata.

   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.

   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.

   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 and decoding as headers are sent
   and received.

   Custom-Metadata header order is not guaranteed to be preserved except
   for values with duplicate header names.  Duplicate header names may
   have their values joined with "," as the delimiter and be considered
   semantically equivalent.  Implementations must split Binary-Headers
   on "," before decoding the Base64-encoded values.

   ASCII-Value should not have leading or trailing whitespace.  If it
   contains leading or trailing whitespace, it may be stripped.  The
   ASCII-Value character range defined is more strict than HTTP.
   Implementations must not error due to receiving an invalid ASCII-
   Value that's a valid field-value in HTTP, but the precise behavior is
   not strictly defined: they may throw the value away or accept the
   value.  If accepted, care must be taken to make sure that the
   application is permitted to echo the value back as metadata.  For
   example, if the metadata is provided to the application as a list in
   a request, the application should not trigger an error by providing
   that same list as the metadata in the response.  Servers may limit
   the size of Request-Headers, with a default of 8 KiB suggested.
   Implementations are encouraged to compute total header size like
   HTTP/2's SETTINGS_MAX_HEADER_LIST_SIZE: the sum of all header fields,
   for each field the sum of the uncompressed field name and value
   lengths plus 32, with binary values' lengths being post-Base64.

   Servers may limit the size of Request-Headers, with a default of 8
   KiB suggested.  Implementations are encouraged to compute total
   header size like HTTP/2's SETTINGS_MAX_HEADER_LIST_SIZE: the sum of
   all header fields, for each field the sum of the uncompressed field



Kumar, et al.            Expires January 9, 2017                [Page 4]


Internet-Draft         gRPC Protocol Specification             July 2016


   name and value lengths plus 32, with binary values' lengths being
   post-Base64.

   The repeated sequence of Length-Prefixed-Message items is delivered
   in DATA frames.

   o  Length-Prefixed-Message -> Compressed-Flag Message-Length Message

   o  Compressed-Flag -> 0 / 1 # encoded as 1 byte unsigned integer

   o  Message-Length -> {length of Message} # encoded as 4 byte unsigned
      integer

   o  Message \u002D-> *{binary octet}

   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.

   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.

4.  Responses

   o  Response -> (Response-Headers *Length-Prefixed-Message Trailers) /
      Trailers-Only

   o  Response-Headers -> HTTP-Status [Message-Encoding] [Message-
      Accept-Encoding] Content-Type *Custom-Metadata

   o  Trailers-Only -> HTTP-Status Content-Type Trailers

   o  Trailers -> Status [Status-Message] *Custom-Metadata

   o  HTTP-Status -> ":status 200"

   o  Status -> "grpc-status"

   o  Status-Message -> "grpc-message"

   Response-Headers and Trailers-Only are each delivered in a single
   HTTP2 HEADERS frame block.  Most responses are expected to have both



Kumar, et al.            Expires January 9, 2017                [Page 5]


Internet-Draft         gRPC Protocol Specification             July 2016


   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.

   For responses end-of-stream is indicated by the presence of the
   END_STREAM flag on the last received HEADERS frame that carries
   Trailers.

   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 and Status-Message.  Implementations must
   synthesize a Status and Status-Message to propagate to the
   application layer when this occurs.

   Clients may limit the size of Response-Headers, Trailers, and
   Trailers-Only, with a default of 8 KiB each suggested.

5.  Examples

   Sample unary-call showing HTTP2 framing sequence

   Request

   HEADERS (flags = END_HEADERS)
   :method = POST
   :scheme = http
   :path = /google.pubsub.v2.PublisherService/CreateTopic
   :authority = pubsub.googleapis.com
   grpc-timeout = 1S
   content-type = application/grpc+proto
   grpc-encoding = gzip
   authorization = Bearer y235.wef315yfh138vh31hv93hv8h3v

   DATA (flags = END_STREAM)
   <Length-Prefixed Message>

   Response

   HEADERS (flags = END_HEADERS)
   :status = 200
   grpc-encoding = gzip

   DATA
   <Length-Prefixed Message>

   HEADERS (flags = END_STREAM, END_HEADERS)
   grpc-status = 0 # OK
   trace-proto-bin = jher831yy13JHy3hc



Kumar, et al.            Expires January 9, 2017                [Page 6]


Internet-Draft         gRPC Protocol Specification             July 2016


6.  User Agents

   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 and
   platform to facilitate issue diagnosis in heterogeneous environments.
   The following structure is recommended to library developers

  User-Agent \u002D-> "grpc-" Language ?("-" Variant) "/" Version ?( " ("  *(AdditionalProperty ";") ")" )

7.  HTTP2 Transport Mapping

   All GRPC calls need to specify an internal ID.  We will use HTTP2
   stream-ids as call identifiers in this scheme.  NOTE: These id's 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.

   DATA frame boundaries have no relation to Length-Prefixed-Message
   boundaries and implementations should make no assumptions about their
   alignment.

   When an application or runtime error occurs during an RPC a Status
   and Status-Message are delivered in Trailers.  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.






















Kumar, et al.            Expires January 9, 2017                [Page 7]


Internet-Draft         gRPC Protocol Specification             July 2016


   +-----------------------+-------------------------------------------+
   |      HTTP2 Code#      |                 GRPC Code                 |
   +-----------------------+-------------------------------------------+
   |      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.                |
   |                       |                                           |
   |   PROTOCOL_ERROR(1)   |                  INTERNAL                 |
   |                       |                                           |
   |   INTERNAL_ERROR(2)   |                  INTERNAL                 |
   |                       |                                           |
   | FLOW_CONTROL_ERROR(3) |                  INTERNAL                 |
   |                       |                                           |
   |  SETTINGS_TIMEOUT(4)  |                  INTERNAL                 |
   |                       |                                           |
   |     STREAM_CLOSED     |              FRAME_SIZE_ERROR             |
   |                       |                                           |
   |     STREAM_CLOSED     |                  INTERNAL                 |
   |                       |                                           |
   |     REFUSED_STREAM    |      UNAVAILABLE - Indicates that no      |
   |                       |  processing occurred and the request can  |
   |                       |      be retried, possibly elsewhere.      |
   |                       |                                           |
   |       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.          |
   |                       |                                           |
   |   COMPRESSION_ERROR   |                  INTERNAL                 |
   |                       |                                           |
   |     CONNECT_ERROR     |                  INTERNAL                 |
   |                       |                                           |
   |   ENHANCE_YOUR_CALM   |   RESOURCE_EXHAUSTED ...with additional   |
   |                       |    error detail provided by runtime to    |
   |                       |  indicate that the exhausted resource is  |
   |                       |                 bandwidth.                |
   |                       |                                           |
   |  INADEQUATE_SECURITY  |   PERMISSION_DENIED ... with additional   |
   |                       |   detail indicating that permission was   |
   |                       |  denied as protocol is not secure enough  |
   |                       |                 for call.                 |
   +-----------------------+-------------------------------------------+

                        Table 1: Error Code Mapping




Kumar, et al.            Expires January 9, 2017                [Page 8]


Internet-Draft         gRPC Protocol Specification             July 2016


   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.

   GOAWAY Frame 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.
   Servers should send GOAWAY before terminating a connection to
   reliably inform clients which work has been accepted by the server
   and is being executed.

   PING Frame 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.

   Connection failure 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.

8.  Normative references

   [RFC7540]  Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
              Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
              DOI 10.17487/RFC7540, May 2015,
              <http://www.rfc-editor.org/info/rfc7540>.

Authors' Addresses









Kumar, et al.            Expires January 9, 2017                [Page 9]


Internet-Draft         gRPC Protocol Specification             July 2016


   Abhishek Kumar
   Google
   1600 Amphitheatre Pkwy
   Mountain View, CA  94043
   US

   Email: abhikumar@google.com


   Jayant Kolhe
   Google
   1600 Amphitheatre Pkwy
   Mountain View, CA  94043
   US

   Email: jkolhe@google.com


   Sanjay Ghemawat
   Google
   1600 Amphitheatre Pkwy
   Mountain View, CA  94043
   US

   Email: sanjay@google.com


   Louis Ryan
   Google
   1600 Amphitheatre Pkwy
   Mountain View, CA  94043
   US

   Email: lryan@google.com

















Kumar, et al.            Expires January 9, 2017               [Page 10]


Html markup produced by rfcmarkup 1.129b, available from https://tools.ietf.org/tools/rfcmarkup/