# gRPC over HTTP2

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

## Protocol
Production rules are using ABNF syntax.

### Outline

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

* Request → Request-Headers *Length-Prefixed-Message EOS
* Response → (Response-Headers *Length-Prefixed-Message Trailers) / Trailers-Only


### Requests

* Request → Request-Headers *Length-Prefixed-Message EOS

Request-Headers are delivered as HTTP2 headers in HEADERS + CONTINUATION frames.

* **Request-Headers** → Call-Definition *Custom-Metadata
* **Call-Definition** → Method Scheme Path [Authority] TE [Timeout] Content-Type [Message-Type] [Message-Encoding] [Message-Accept-Encoding] [User-Agent]
* **Method** →  ":method POST"
* **Scheme** → ":scheme "  ("http" / "https")
* **Path** → ":path" "/" Service-Name "/" {method name}
* **Service-Name** → {IDL-specific service name}
* **Authority** → ":authority" {virtual host name of authority}
* **TE** → "te" "trailers"
* **Timeout** → "grpc-timeout" TimeoutValue TimeoutUnit
* **TimeoutValue** → {positive integer as ASCII string of at most 8 digits}
* **TimeoutUnit** → Hour / Minute / Second / Millisecond / Microsecond / Nanosecond
* **Content-Type** → "content-type" "application/grpc" [("+proto" / "+json" / {custom})]
* **Content-Coding** → "identity" / "gzip" / "deflate" / "snappy" / {custom}
* **Message-Encoding** → "grpc-encoding" Content-Coding
* **Message-Accept-Encoding** → "grpc-accept-encoding" Content-Coding *("," Content-Coding)
* **User-Agent** → "user-agent" {structured user-agent string}
* **Message-Type** → "grpc-message-type" {type name for message schema}
* **Custom-Metadata** → Binary-Header / ASCII-Header
* **Binary-Header** → {Header-Name "-bin" } {base64 encoded value}
* **ASCII-Header** → Header-Name ASCII-Value
* **Header-Name** → 1*( %x30-39 / %x61-7A / "_" / "-" / ".")
* **ASCII-Value** → 1*( %x20-%x7E )

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

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.

If **Content-Type** does not begin with "application/grpc", gRPC servers SHOULD respond with HTTP status of 415 (Unsupported Media Type).

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

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.

### Responses

* **Response** → (Response-Headers *Length-Prefixed-Message Trailers) / Trailers-Only
* **Response-Headers** → HTTP-Status [Message-Encoding] [Message-Accept-Encoding] Content-Type *Custom-Metadata
* **Trailers-Only** → HTTP-Status Content-Type Trailers
* **Trailers** → Status [Status-Message] [Status-Details] *Custom-Metadata
* **HTTP-Status** → ":status 200"
* **Status** → "grpc-status" 1*DIGIT
* **Status-Message** → "grpc-message" Percent-Encoded
* **Status-Details** → "grpc-status-details-bin" {base64 encoded value}
* **Percent-Encoded** → 1*(Percent-Byte-Unencoded / Percent-Byte-Encoded)
* **Percent-Byte-Unencoded** → 1*( %x20-%x24 / %x26-%x7E )
* **Percent-Byte-Encoded** → "%" 2HEXDIGIT

**Response-Headers** & **Trailers-Only** are each delivered in a single HTTP2 HEADERS frame block. Status must be sent in **Trailers** even if the status code is OK.

#### HTTP2 Transport Mapping

##### Stream Identification
All GRPC calls need to specify an internal ID. HTTP2 stream-ids are used as call identifiers.

##### Errors

The following mapping from RST_STREAM error codes to GRPC error codes is applied:

HTTP2 Code|GRPC Code
----------|-----------
NO_ERROR(0)|INTERNAL
PROTOCOL_ERROR(1)|INTERNAL
INTERNAL_ERROR(2)|INTERNAL
FLOW_CONTROL_ERROR(3)|INTERNAL
SETTINGS_TIMEOUT(4)|INTERNAL
REFUSED_STREAM|UNAVAILABLE
CANCEL(8)|Mapped to call cancellation when sent by a client. CANCELLED when sent by a server.
COMPRESSION_ERROR|INTERNAL
CONNECT_ERROR|INTERNAL
ENHANCE_YOUR_CALM|RESOURCE_EXHAUSTED
INADEQUATE_SECURITY|PERMISSION_DENIED

##### Security

The HTTP2 specification mandates the use of TLS 1.2 or higher when TLS is used with HTTP2.

##### Connection Management

###### GOAWAY Frame
Sent by servers to clients to indicate that they will no longer accept any new streams on the associated connections.

###### PING Frame
Both clients and servers can send a PING frame that the peer must respond to by precisely echoing what they received.

### Appendix A - GRPC for Protobuf

* **Service-Name** → ?( {proto package name} "." ) {service name}
* **Message-Type** → {fully qualified proto message name}
* **Content-Type** → "application/grpc+proto"
* **Status-Details** → {google.rpc.Status proto message}

---
Source: https://raw.githubusercontent.com/grpc/grpc/master/doc/PROTOCOL-HTTP2.md
Downloaded: 2026-06-07