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