1# Compression
2
3The preferred method for configuring message compression on both clients and
4servers is to use
5[`encoding.RegisterCompressor`](https://godoc.org/google.golang.org/grpc/encoding#RegisterCompressor)
6to register an implementation of a compression algorithm.  See
7`grpc/encoding/gzip/gzip.go` for an example of how to implement one.
8
9Once a compressor has been registered on the client-side, RPCs may be sent using
10it via the
11[`UseCompressor`](https://godoc.org/google.golang.org/grpc#UseCompressor)
12`CallOption`.  Remember that `CallOption`s may be turned into defaults for all
13calls from a `ClientConn` by using the
14[`WithDefaultCallOptions`](https://godoc.org/google.golang.org/grpc#WithDefaultCallOptions)
15`DialOption`.  If `UseCompressor` is used and the corresponding compressor has
16not been installed, an `Internal` error will be returned to the application
17before the RPC is sent.
18
19Server-side, registered compressors will be used automatically to decode request
20messages and encode the responses.  Servers currently always respond using the
21same compression method specified by the client.  If the corresponding
22compressor has not been registered, an `Unimplemented` status will be returned
23to the client.
24
25## Deprecated API
26
27There is a deprecated API for setting compression as well.  It is not
28recommended for use.  However, if you were previously using it, the following
29section may be helpful in understanding how it works in combination with the new
30API.
31
32### Client-Side
33
34There are two legacy functions and one new function to configure compression:
35
36```go
37func WithCompressor(grpc.Compressor) DialOption {}
38func WithDecompressor(grpc.Decompressor) DialOption {}
39func UseCompressor(name) CallOption {}
40```
41
42For outgoing requests, the following rules are applied in order:
431. If `UseCompressor` is used, messages will be compressed using the compressor
44   named.
45   * If the compressor named is not registered, an Internal error is returned
46     back to the client before sending the RPC.
47   * If UseCompressor("identity"), no compressor will be used, but "identity"
48     will be sent in the header to the server.
491. If `WithCompressor` is used, messages will be compressed using that
50   compressor implementation.
511. Otherwise, outbound messages will be uncompressed.
52
53For incoming responses, the following rules are applied in order:
541. If `WithDecompressor` is used and it matches the message's encoding, it will
55   be used.
561. If a registered compressor matches the response's encoding, it will be used.
571. Otherwise, the stream will be closed and an `Unimplemented` status error will
58   be returned to the application.
59
60### Server-Side
61
62There are two legacy functions to configure compression:
63```go
64func RPCCompressor(grpc.Compressor) ServerOption {}
65func RPCDecompressor(grpc.Decompressor) ServerOption {}
66```
67
68For incoming requests, the following rules are applied in order:
691. If `RPCDecompressor` is used and that decompressor matches the request's
70   encoding: it will be used.
711. If a registered compressor matches the request's encoding, it will be used.
721. Otherwise, an `Unimplemented` status will be returned to the client.
73
74For outgoing responses, the following rules are applied in order:
751. If `RPCCompressor` is used, that compressor will be used to compress all
76   response messages.
771. If compression was used for the incoming request and a registered compressor
78   supports it, that same compression method will be used for the outgoing
79   response.
801. Otherwise, no compression will be used for the outgoing response.
81