mirror of https://github.com/grpc/grpc.git
Craig Tiller
9 years ago
commit
e305fdb885
60 changed files with 564 additions and 3592 deletions
@ -0,0 +1,133 @@ |
|||||||
|
# gRPC (Core) Compression Cookbook |
||||||
|
|
||||||
|
## Introduction |
||||||
|
|
||||||
|
This document describes compression as implemented by the gRPC C core. See [the |
||||||
|
full compression specification](compression.md) for details. |
||||||
|
|
||||||
|
### Intended Audience |
||||||
|
|
||||||
|
Wrapped languages developers, for the purposes of supporting compression by |
||||||
|
interacting with the C core. |
||||||
|
|
||||||
|
## Criteria for GA readiness |
||||||
|
|
||||||
|
1. Be able to set compression at [channel](#per-channel-settings), |
||||||
|
[call](#per-call-settings) and [message](#per-message-settings) level. |
||||||
|
In principle this API should be based on _compression levels_ as opposed to |
||||||
|
algorithms. See the discussion [below](#level-vs-algorithms). |
||||||
|
1. Have unit tests covering [the cases from the |
||||||
|
spec](https://github.com/grpc/grpc/blob/master/doc/compression.md#test-cases). |
||||||
|
1. Interop tests implemented and passing on Jenkins. The two relevant interop |
||||||
|
test cases are |
||||||
|
[large_compressed_unary](https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptions.md#large_compressed_unary) |
||||||
|
and |
||||||
|
[server_compressed_streaming](https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptions.md#server_compressed_streaming). |
||||||
|
|
||||||
|
## Summary Flowcharts |
||||||
|
|
||||||
|
The following flowcharts depict the evolution of a message, both _incoming_ and |
||||||
|
_outgoing_, irrespective of the client/server character of the call. Aspects |
||||||
|
still not symmetric between clients and servers (e.g. the [use of compression |
||||||
|
levels](https://github.com/grpc/grpc/blob/master/doc/compression.md#compression-levels-and-algorithms)) |
||||||
|
are explicitly marked. The in-detail textual description for the different |
||||||
|
scenarios is described in subsequent sections. |
||||||
|
|
||||||
|
## Incoming Messages |
||||||
|
|
||||||
|
 |
||||||
|
|
||||||
|
## Outgoing Messages |
||||||
|
|
||||||
|
 |
||||||
|
|
||||||
|
## Levels vs Algorithms |
||||||
|
|
||||||
|
As mentioned in [the relevant discussion on the spec |
||||||
|
document](https://github.com/grpc/grpc/blob/master/doc/compression.md#compression-levels-and-algorithms), |
||||||
|
compression _levels_ are the primary mechanism for compression selection _at the |
||||||
|
server side_. In the future, it'll also be at the client side. The use of levels |
||||||
|
abstracts away the intricacies of selecting a concrete algorithm supported by a |
||||||
|
peer, on top of removing the burden of choice from the developer. |
||||||
|
As of this writing (Q2 2016), clients can only specify compression _algorithms_. |
||||||
|
Clients will support levels as soon as an automatic retry/negotiation mechanism |
||||||
|
is in place. |
||||||
|
|
||||||
|
## Per Channel Settings |
||||||
|
|
||||||
|
Compression may be configured at channel creation. This is a convenience to |
||||||
|
avoid having to repeatedly configure compression for every call. Note that any |
||||||
|
compression setting on individual [calls](#per-call-settings) or |
||||||
|
[messages](#per-message-settings) overrides channel settings. |
||||||
|
|
||||||
|
The following aspects can be configured at channel-creation time via channel arguments: |
||||||
|
|
||||||
|
#### Disable Compression _Algorithms_ |
||||||
|
|
||||||
|
Use the channel argument key |
||||||
|
`GRPC_COMPRESSION_CHANNEL_ENABLED_ALGORITHMS_BITSET` (from |
||||||
|
[`grpc/impl/codegen/compression_types.h`](https://github.com/grpc/grpc/blob/master/include/grpc/impl/codegen/compression_types.h)), |
||||||
|
takes a 32 bit bitset value. A set bit means the algorithm with that enum value |
||||||
|
according to `grpc_compression_algorithm` is _enabled_. |
||||||
|
For example, `GRPC_COMPRESS_GZIP` currently has a numeric value of 2. To |
||||||
|
enable/disable GZIP for a channel, one would set/clear the 3rd LSB (eg, 0b100 = |
||||||
|
0x4). Note that setting/clearing 0th position, that corresponding to |
||||||
|
`GRPC_COMPRESS_NONE`, has no effect, as no-compression (a.k.a. _identity_) is |
||||||
|
always supported. |
||||||
|
Incoming messages compressed (ie, encoded) with a disabled algorithm will result |
||||||
|
in the call being closed with `GRPC_STATUS_UNIMPLEMENTED`. |
||||||
|
|
||||||
|
#### Default Compression _Level_ |
||||||
|
|
||||||
|
**(currently, Q2 2016, only applicable for server side channels. It's ignored |
||||||
|
for clients.)** |
||||||
|
Use the channel argument key `GRPC_COMPRESSION_CHANNEL_DEFAULT_LEVEL` (from |
||||||
|
[`grpc/impl/codegen/compression_types.h`](https://github.com/grpc/grpc/blob/master/include/grpc/impl/codegen/compression_types.h)), |
||||||
|
valued by an integer corresponding to a value from the `grpc_compression_level` |
||||||
|
enum. |
||||||
|
|
||||||
|
#### Default Compression _Algorithm_ |
||||||
|
|
||||||
|
Use the channel argument key `GRPC_COMPRESSION_CHANNEL_DEFAULT_ALGORITHM` (from |
||||||
|
[`grpc/impl/codegen/compression_types.h`](https://github.com/grpc/grpc/blob/master/include/grpc/impl/codegen/compression_types.h)), |
||||||
|
valued by an integer corresponding to a value from the `grpc_compression_level` |
||||||
|
enum. |
||||||
|
|
||||||
|
## Per Call Settings |
||||||
|
|
||||||
|
### Compression **Level** in Call Responses |
||||||
|
|
||||||
|
The server requests a compression level via initial metadata. The |
||||||
|
`send_initial_metadata` `grpc_op` contains a `maybe_compression_level` field |
||||||
|
with two fields, `is_set` and `compression_level`. The former must be set when |
||||||
|
actively choosing a level to disambiguate the default value of zero (no |
||||||
|
compression) from the proactive selection of no compression. |
||||||
|
|
||||||
|
The core will receive the request for the compression level and automatically |
||||||
|
choose a compression algorithm based on its knowledge about the peer |
||||||
|
(communicated by the client via the `grpc-accept-encoding` header. Note that the |
||||||
|
absence of this header means no compression is supported by the client/peer). |
||||||
|
|
||||||
|
### Compression **Algorithm** in Call Responses |
||||||
|
|
||||||
|
**Server should avoid setting the compression algorithm directly**. Prefer |
||||||
|
setting compression levels unless there's a _very_ compelling reason to choose |
||||||
|
specific algorithms (benchmarking, testing). |
||||||
|
|
||||||
|
Selection of concrete compression algorithms is performed by adding a |
||||||
|
`(GRPC_COMPRESS_REQUEST_ALGORITHM_KEY, <algorithm-name>)` key-value pair to the |
||||||
|
initial metadata, where `GRPC_COMPRESS_REQUEST_ALGORITHM_KEY` is defined in |
||||||
|
[`grpc/impl/codegen/compression_types.h`](https://github.com/grpc/grpc/blob/master/include/grpc/impl/codegen/compression_types.h)), |
||||||
|
and `<algorithm-name>` is the human readable name of the algorithm as given in |
||||||
|
[the HTTP2 spec](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md) |
||||||
|
for `Message-Encoding` (e.g. gzip, identity, etc.). See |
||||||
|
[`grpc_compression_algorithm_name`](https://github.com/grpc/grpc/blob/master/src/core/lib/compression/compression.c) |
||||||
|
for the mapping between the `grpc_compression_algorithm` enum values and their |
||||||
|
textual representation. |
||||||
|
|
||||||
|
## Per Message Settings |
||||||
|
|
||||||
|
To disable compression for a specific message, the `flags` field of `grpc_op` |
||||||
|
instances of type `GRPC_OP_SEND_MESSAGE` must have its `GRPC_WRITE_NO_COMPRESS` |
||||||
|
bit set. Refer to |
||||||
|
[`grpc/impl/codegen/compression_types.h`](https://github.com/grpc/grpc/blob/master/include/grpc/impl/codegen/compression_types.h)), |
||||||
|
After Width: | Height: | Size: 89 KiB |
|
After Width: | Height: | Size: 120 KiB |
@ -0,0 +1,130 @@ |
|||||||
|
%YAML 1.2 |
||||||
|
--- | |
||||||
|
# GRPC CocoaPods podspec |
||||||
|
# This file has been automatically generated from a template file. |
||||||
|
# Please look at the templates directory instead. |
||||||
|
# This file can be regenerated from the template by running |
||||||
|
# tools/buildgen/generate_projects.sh |
||||||
|
|
||||||
|
# Copyright 2015, Google Inc. |
||||||
|
# All rights reserved. |
||||||
|
# |
||||||
|
# Redistribution and use in source and binary forms, with or without |
||||||
|
# modification, are permitted provided that the following conditions are |
||||||
|
# met: |
||||||
|
# |
||||||
|
# * Redistributions of source code must retain the above copyright |
||||||
|
# notice, this list of conditions and the following disclaimer. |
||||||
|
# * Redistributions in binary form must reproduce the above |
||||||
|
# copyright notice, this list of conditions and the following disclaimer |
||||||
|
# in the documentation and/or other materials provided with the |
||||||
|
# distribution. |
||||||
|
# * Neither the name of Google Inc. nor the names of its |
||||||
|
# contributors may be used to endorse or promote products derived from |
||||||
|
# this software without specific prior written permission. |
||||||
|
# |
||||||
|
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
||||||
|
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
||||||
|
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
||||||
|
# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
||||||
|
# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
||||||
|
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
||||||
|
# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
||||||
|
# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
||||||
|
# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
||||||
|
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
||||||
|
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
||||||
|
|
||||||
|
<%! |
||||||
|
def grpc_files(libs): |
||||||
|
out = [] |
||||||
|
for lib in libs: |
||||||
|
if lib.name in ("grpc", "gpr"): |
||||||
|
out += lib.get('headers', []) |
||||||
|
out += lib.get('public_headers', []) |
||||||
|
out += lib.get('src', []) |
||||||
|
return out; |
||||||
|
|
||||||
|
def grpc_private_headers(libs): |
||||||
|
out = [] |
||||||
|
for lib in libs: |
||||||
|
if lib.name in ("grpc", "gpr"): |
||||||
|
out += lib.get('headers', []) |
||||||
|
return out |
||||||
|
%> |
||||||
|
Pod::Spec.new do |s| |
||||||
|
s.name = 'gRPC' |
||||||
|
version = '0.14.0' |
||||||
|
s.version = version |
||||||
|
s.summary = 'gRPC client library for iOS/OSX' |
||||||
|
s.homepage = 'http://www.grpc.io' |
||||||
|
s.license = 'New BSD' |
||||||
|
s.authors = { 'The gRPC contributors' => 'grpc-packages@google.com' } |
||||||
|
|
||||||
|
s.source = { :git => 'https://github.com/grpc/grpc.git', |
||||||
|
:tag => "release-#{version.gsub(/\./, '_')}-objectivec-#{version}", |
||||||
|
:submodules => true } |
||||||
|
|
||||||
|
|
||||||
|
s.ios.deployment_target = '7.1' |
||||||
|
s.osx.deployment_target = '10.9' |
||||||
|
s.requires_arc = true |
||||||
|
|
||||||
|
objc_dir = 'src/objective-c' |
||||||
|
|
||||||
|
# Reactive Extensions library for iOS. |
||||||
|
s.subspec 'RxLibrary' do |ss| |
||||||
|
src_dir = "#{objc_dir}/RxLibrary" |
||||||
|
ss.source_files = "#{src_dir}/*.{h,m}", "#{src_dir}/**/*.{h,m}" |
||||||
|
ss.private_header_files = "#{src_dir}/private/*.h" |
||||||
|
ss.header_mappings_dir = "#{objc_dir}" |
||||||
|
end |
||||||
|
|
||||||
|
# Core cross-platform gRPC library, written in C. |
||||||
|
s.subspec 'C-Core' do |ss| |
||||||
|
ss.source_files = ${(',\n' + 22*' ').join('\'%s\'' % f for f in grpc_files(libs))} |
||||||
|
|
||||||
|
ss.private_header_files = ${(',\n' + 30*' ').join('\'%s\'' % f for f in grpc_private_headers(libs))} |
||||||
|
|
||||||
|
ss.header_mappings_dir = '.' |
||||||
|
# This isn't officially supported in Cocoapods. We've asked for an alternative: |
||||||
|
# https://github.com/CocoaPods/CocoaPods/issues/4386 |
||||||
|
ss.xcconfig = { |
||||||
|
'USE_HEADERMAP' => 'NO', |
||||||
|
'ALWAYS_SEARCH_USER_PATHS' => 'NO', |
||||||
|
'USER_HEADER_SEARCH_PATHS' => '"$(PODS_ROOT)/Headers/Private/gRPC"', |
||||||
|
'HEADER_SEARCH_PATHS' => '"$(PODS_ROOT)/Headers/Private/gRPC/include"' |
||||||
|
} |
||||||
|
|
||||||
|
ss.requires_arc = false |
||||||
|
ss.libraries = 'z' |
||||||
|
ss.dependency 'BoringSSL', '~> 3.0' |
||||||
|
|
||||||
|
# ss.compiler_flags = '-GCC_WARN_INHIBIT_ALL_WARNINGS', '-w' |
||||||
|
end |
||||||
|
|
||||||
|
# Objective-C wrapper around the core gRPC library. |
||||||
|
s.subspec 'GRPCClient' do |ss| |
||||||
|
src_dir = "#{objc_dir}/GRPCClient" |
||||||
|
ss.source_files = "#{src_dir}/*.{h,m}", "#{src_dir}/**/*.{h,m}" |
||||||
|
ss.private_header_files = "#{src_dir}/private/*.h" |
||||||
|
ss.header_mappings_dir = "#{objc_dir}" |
||||||
|
|
||||||
|
ss.dependency 'gRPC/C-Core' |
||||||
|
ss.dependency 'gRPC/RxLibrary' |
||||||
|
|
||||||
|
# Certificates, to be able to establish TLS connections: |
||||||
|
ss.resource_bundles = { 'gRPCCertificates' => ['etc/roots.pem'] } |
||||||
|
end |
||||||
|
|
||||||
|
# RPC library for ProtocolBuffers, based on gRPC |
||||||
|
s.subspec 'ProtoRPC' do |ss| |
||||||
|
src_dir = "#{objc_dir}/ProtoRPC" |
||||||
|
ss.source_files = "#{src_dir}/*.{h,m}" |
||||||
|
ss.header_mappings_dir = "#{objc_dir}" |
||||||
|
|
||||||
|
ss.dependency 'gRPC/GRPCClient' |
||||||
|
ss.dependency 'gRPC/RxLibrary' |
||||||
|
ss.dependency 'Protobuf', '~> 3.0.0-alpha-4' |
||||||
|
end |
||||||
|
end |
||||||
@ -1 +1 @@ |
|||||||
Subproject commit 3470b6895aa659b7559ed678e029a5338e535f14 |
Subproject commit bdeb215cab2985195325fcd5e70c3fa751f46e0f |
||||||
Loading…
Reference in new issue