carto
/
grpc


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131
							<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>GRPC C++: gRPC Compression</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">GRPC C++
   &#160;<span id="projectnumber">1.36.1</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">gRPC Compression </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in <a href="http://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>.</p>
<h2><a class="anchor" id="autotoc_md52"></a>
Intent</h2>
<p>Compression is used to reduce the amount of bandwidth used between peers. The compression supported by gRPC acts <em>at the individual message level</em>, taking <em>message</em> <a class="el" href="_p_r_o_t_o_c_o_l-_h_t_t_p2_8md.html">as defined in the wire format</a>document".</p>
<p>The implementation supports different compression algorithms. A <em>default compression level</em>, to be used in the absence of message-specific settings, MAY be specified for during channel creation.</p>
<p>The ability to control compression settings per call and to enable/disable compression on a per message basis MAY be used to prevent CRIME/BEAST attacks. It also allows for asymmetric compression communication, whereby a response MAY be compressed differently, if at all.</p>
<h2><a class="anchor" id="autotoc_md53"></a>
Specification</h2>
<p>Compression MAY be configured by the Client Application by calling the appropriate API method. There are two scenarios where compression MAY be configured:</p>
<ul>
<li>At channel creation time, which sets the channel default compression and therefore the compression that SHALL be used in the absence of per-RPC compression configuration.</li>
<li>At response time, via:<ul>
<li>For unary RPCs, the {Client,Server}Context instance.</li>
<li>For streaming RPCs, the {Client,Server}Writer instance. In this case, configuration is reduced to disabling compression altogether.</li>
</ul>
</li>
</ul>
<h2><a class="anchor" id="autotoc_md54"></a>
Compression Method Asymmetry Between Peers</h2>
<p>A gRPC peer MAY choose to respond using a different compression method to that of the request, including not performing any compression, regardless of channel and RPC settings (for example, if compression would result in small or negative gains).</p>
<p>If a client message is compressed by an algorithm that is not supported by a server, the message WILL result in an <code>UNIMPLEMENTED</code> error status on the server. The server will then include a <code>grpc-accept-encoding</code> response header which specifies the algorithms that the server accepts. If the client message is compressed using one of the algorithms from the <code>grpc-accept-encoding</code> header and an <code>UNIMPLEMENTED</code> error status is returned from the server, the cause of the error MUST NOT be related to compression. If a server sent data which is compressed by an algorithm that is not supported by the client, an <code>INTERNAL</code> error status will occur on the client side.</p>
<p>Note that a peer MAY choose to not disclose all the encodings it supports. However, if it receives a message compressed in an undisclosed but supported encoding, it MUST include said encoding in the response's <code>grpc-accept-encoding</code> header.</p>
<p>For every message a server is requested to compress using an algorithm it knows the client doesn't support (as indicated by the last <code>grpc-accept-encoding</code> header received from the client), it SHALL send the message uncompressed.</p>
<h2><a class="anchor" id="autotoc_md55"></a>
Specific Disabling of Compression</h2>
<p>If the user (through the previously described mechanisms) requests to disable compression the next message MUST be sent uncompressed. This is instrumental in preventing BEAST/CRIME attacks. This applies to both the unary and streaming cases.</p>
<h2><a class="anchor" id="autotoc_md56"></a>
Compression Levels and Algorithms</h2>
<p>The set of supported algorithm is implementation dependent. In order to simplify the public API and to operate seamlessly across implementations (both in terms of languages but also different version of the same one), we introduce the idea of <em>compression levels</em> (such as "low", "medium", "high").</p>
<p>Levels map to concrete algorithms and/or their settings (such as "low" mapping to "gzip -3" and "high" mapping to "gzip -9") automatically depending on what a peer is known to support. A server is always aware of what its clients support, as clients disclose it in the Message-Accept-Encoding header as part of the RPC. A client doesn't a priori (presently) know which algorithms a server supports. This issue can be addressed with an initial negotiation of capabilities or an automatic retry mechanism. These features will be implemented in the future. Currently however, compression levels are only supported at the server side, which is aware of the client's capabilities through the incoming Message-Accept-Encoding header.</p>
<h2><a class="anchor" id="autotoc_md57"></a>
Propagation to child RPCs</h2>
<p>The inheritance of the compression configuration by child RPCs is left up to the implementation. Note that in the absence of changes to the parent channel, its configuration will be used.</p>
<h2><a class="anchor" id="autotoc_md58"></a>
Test cases</h2>
<ol type="1">
<li>When a compression level is not specified for either the channel or the message, the default channel level <em>none</em> is considered: data MUST NOT be compressed.</li>
</ol>
<ol type="1">
<li>When per-RPC compression configuration isn't present for a message, the channel compression configuration MUST be used.</li>
</ol>
<ol type="1">
<li>When a compression method (including no compression) is specified for an outgoing message, the message MUST be compressed accordingly.</li>
</ol>
<ol type="1">
<li>A message compressed by a client in a way not supported by its server MUST fail with status <code>UNIMPLEMENTED</code>, its associated description indicating the unsupported condition as well as the supported ones. The returned <code>grpc-accept-encoding</code> header MUST NOT contain the compression method (encoding) used.</li>
</ol>
<ol type="1">
<li>A message compressed by a server in a way not supported by its client MUST fail with status <code>INTERNAL</code>, its associated description indicating the unsupported condition as well as the supported ones. The returned <code>grpc-accept-encoding</code> header MUST NOT contain the compression method (encoding) used.</li>
</ol>
<ol type="1">
<li>An ill-constructed message with its <a href="PROTOCOL-HTTP2.md#compressed-flag">Compressed-Flag bit</a> set but lacking a <a href="PROTOCOL-HTTP2.md#message-encoding">grpc-encoding</a> entry different from <em>identity</em> in its metadata MUST fail with <code>INTERNAL</code> status, its associated description indicating the invalid Compressed-Flag condition. </li>
</ol>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Wed Mar 3 2021 19:17:22 for GRPC C++ by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.17
</small></address>
</body>
</html>