1## gRPC Compression 2 3The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 4"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 5interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt). 6 7### Intent 8 9Compression is used to reduce the amount of bandwidth used between peers. The 10compression supported by gRPC acts _at the individual message level_, taking 11_message_ [as defined in the wire format 12document](PROTOCOL-HTTP2.md). 13 14The implementation supports different compression algorithms. A _default 15compression level_, to be used in the absence of message-specific settings, MAY 16be specified for during channel creation. 17 18The ability to control compression settings per call and to enable/disable 19compression on a per message basis MAY be used to prevent CRIME/BEAST attacks. 20It also allows for asymmetric compression communication, whereby a response MAY 21be compressed differently, if at all. 22 23### Specification 24 25Compression MAY be configured by the Client Application by calling the 26appropriate API method. There are two scenarios where compression MAY be 27configured: 28 29+ At channel creation time, which sets the channel default compression and 30 therefore the compression that SHALL be used in the absence of per-RPC 31 compression configuration. 32+ At response time, via: 33 + For unary RPCs, the {Client,Server}Context instance. 34 + For streaming RPCs, the {Client,Server}Writer instance. In this case, 35 configuration is reduced to disabling compression altogether. 36 37### Compression Method Asymmetry Between Peers 38 39A gRPC peer MAY choose to respond using a different compression method to that 40of the request, including not performing any compression, regardless of channel 41and RPC settings (for example, if compression would result in small or negative 42gains). 43 44If a client message is compressed by an algorithm that is not supported 45by a server, the message WILL result in an `UNIMPLEMENTED` error status on the 46server. The server will then include a `grpc-accept-encoding` response 47header which specifies the algorithms that the server accepts. If the client 48message is compressed using one of the algorithms from the `grpc-accept-encoding` header 49and an `UNIMPLEMENTED` error status is returned from the server, the cause of the error 50MUST NOT be related to compression. If a server sent data which is compressed by an algorithm 51that is not supported by the client, an `INTERNAL` error status will occur on the client side. 52 53Note that a peer MAY choose to not disclose all the encodings it supports. 54However, if it receives a message compressed in an undisclosed but supported 55encoding, it MUST include said encoding in the response's `grpc-accept-encoding` 56header. 57 58For every message a server is requested to compress using an algorithm it knows 59the client doesn't support (as indicated by the last `grpc-accept-encoding` 60header received from the client), it SHALL send the message uncompressed. 61 62### Specific Disabling of Compression 63 64If the user (through the previously described mechanisms) requests to disable 65compression the next message MUST be sent uncompressed. This is instrumental in 66preventing BEAST/CRIME attacks. This applies to both the unary and streaming 67cases. 68 69### Compression Levels and Algorithms 70 71The set of supported algorithm is implementation dependent. In order to simplify 72the public API and to operate seamlessly across implementations (both in terms 73of languages but also different version of the same one), we introduce the idea 74of _compression levels_ (such as "low", "medium", "high"). 75 76Levels map to concrete algorithms and/or their settings (such as "low" mapping 77to "gzip -3" and "high" mapping to "gzip -9") automatically depending on what a 78peer is known to support. A server is always aware of what its clients support, 79as clients disclose it in the Message-Accept-Encoding header as part of the 80RPC. A client doesn't a priori (presently) know which algorithms a 81server supports. This issue can be addressed with an initial negotiation of 82capabilities or an automatic retry mechanism. These features will be implemented 83in the future. Currently however, compression levels are only supported at the 84server side, which is aware of the client's capabilities through the incoming 85Message-Accept-Encoding header. 86 87### Propagation to child RPCs 88 89The inheritance of the compression configuration by child RPCs is left up to the 90implementation. Note that in the absence of changes to the parent channel, its 91configuration will be used. 92 93### Deflate Compression 94 95Like HTTP implementations, gRPC implementations MUST use the "deflate" 96compression to mean the zlib structure (defined in 97[RFC 1950](https://datatracker.ietf.org/doc/html/rfc1950)) 98with the deflate compression algorithm (defined in 99[RFC 1951](https://datatracker.ietf.org/doc/html/rfc1951)). 100Servers and clients MUST NOT send raw deflate data. 101 102### Test cases 103 1041. When a compression level is not specified for either the channel or the 105message, the default channel level _none_ is considered: data MUST NOT be 106compressed. 1071. When per-RPC compression configuration isn't present for a message, the 108channel compression configuration MUST be used. 1091. When a compression method (including no compression) is specified for an 110outgoing message, the message MUST be compressed accordingly. 1111. A message compressed by a client in a way not supported by its server MUST 112fail with status `UNIMPLEMENTED`, its associated description indicating the 113unsupported condition as well as the supported ones. The returned 114`grpc-accept-encoding` header MUST NOT contain the compression method 115(encoding) used. 1161. A message compressed by a server in a way not supported by its client MUST 117fail with status `INTERNAL`, its associated description indicating the 118unsupported condition as well as the supported ones. The returned 119`grpc-accept-encoding` header MUST NOT contain the compression method 120(encoding) used. 1211. An ill-constructed message with its [Compressed-Flag 122bit](PROTOCOL-HTTP2.md#compressed-flag) 123set but lacking a 124[grpc-encoding](PROTOCOL-HTTP2.md#message-encoding) 125entry different from _identity_ in its metadata MUST fail with `INTERNAL` 126status, its associated description indicating the invalid Compressed-Flag 127condition. 128