|
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980 |
- # Compression
-
- The preferred method for configuring message compression on both clients and
- servers is to use
- [`encoding.RegisterCompressor`](https://godoc.org/google.golang.org/grpc/encoding#RegisterCompressor)
- to register an implementation of a compression algorithm. See
- `grpc/encoding/gzip/gzip.go` for an example of how to implement one.
-
- Once a compressor has been registered on the client-side, RPCs may be sent using
- it via the
- [`UseCompressor`](https://godoc.org/google.golang.org/grpc#UseCompressor)
- `CallOption`. Remember that `CallOption`s may be turned into defaults for all
- calls from a `ClientConn` by using the
- [`WithDefaultCallOptions`](https://godoc.org/google.golang.org/grpc#WithDefaultCallOptions)
- `DialOption`. If `UseCompressor` is used and the corresponding compressor has
- not been installed, an `Internal` error will be returned to the application
- before the RPC is sent.
-
- Server-side, registered compressors will be used automatically to decode request
- messages and encode the responses. Servers currently always respond using the
- same compression method specified by the client. If the corresponding
- compressor has not been registered, an `Unimplemented` status will be returned
- to the client.
-
- ## Deprecated API
-
- There is a deprecated API for setting compression as well. It is not
- recommended for use. However, if you were previously using it, the following
- section may be helpful in understanding how it works in combination with the new
- API.
-
- ### Client-Side
-
- There are two legacy functions and one new function to configure compression:
-
- ```go
- func WithCompressor(grpc.Compressor) DialOption {}
- func WithDecompressor(grpc.Decompressor) DialOption {}
- func UseCompressor(name) CallOption {}
- ```
-
- For outgoing requests, the following rules are applied in order:
- 1. If `UseCompressor` is used, messages will be compressed using the compressor
- named.
- * If the compressor named is not registered, an Internal error is returned
- back to the client before sending the RPC.
- * If UseCompressor("identity"), no compressor will be used, but "identity"
- will be sent in the header to the server.
- 1. If `WithCompressor` is used, messages will be compressed using that
- compressor implementation.
- 1. Otherwise, outbound messages will be uncompressed.
-
- For incoming responses, the following rules are applied in order:
- 1. If `WithDecompressor` is used and it matches the message's encoding, it will
- be used.
- 1. If a registered compressor matches the response's encoding, it will be used.
- 1. Otherwise, the stream will be closed and an `Unimplemented` status error will
- be returned to the application.
-
- ### Server-Side
-
- There are two legacy functions to configure compression:
- ```go
- func RPCCompressor(grpc.Compressor) ServerOption {}
- func RPCDecompressor(grpc.Decompressor) ServerOption {}
- ```
-
- For incoming requests, the following rules are applied in order:
- 1. If `RPCDecompressor` is used and that decompressor matches the request's
- encoding: it will be used.
- 1. If a registered compressor matches the request's encoding, it will be used.
- 1. Otherwise, an `Unimplemented` status will be returned to the client.
-
- For outgoing responses, the following rules are applied in order:
- 1. If `RPCCompressor` is used, that compressor will be used to compress all
- response messages.
- 1. If compression was used for the incoming request and a registered compressor
- supports it, that same compression method will be used for the outgoing
- response.
- 1. Otherwise, no compression will be used for the outgoing response.
|