gitee.com/ks-custle/core-gm@v0.0.0-20230922171213-b83bdd97b62c/grpc/Documentation/compression.md (about)

     1  # Compression
     2  
     3  The preferred method for configuring message compression on both clients and
     4  servers is to use
     5  [`encoding.RegisterCompressor`](https://godoc.org/google.golang.org/grpc/encoding#RegisterCompressor)
     6  to register an implementation of a compression algorithm.  See
     7  `grpc/encoding/gzip/gzip.go` for an example of how to implement one.
     8  
     9  Once a compressor has been registered on the client-side, RPCs may be sent using
    10  it 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
    13  calls 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
    16  not been installed, an `Internal` error will be returned to the application
    17  before the RPC is sent.
    18  
    19  Server-side, registered compressors will be used automatically to decode request
    20  messages and encode the responses.  Servers currently always respond using the
    21  same compression method specified by the client.  If the corresponding
    22  compressor has not been registered, an `Unimplemented` status will be returned
    23  to the client.
    24  
    25  ## Deprecated API
    26  
    27  There is a deprecated API for setting compression as well.  It is not
    28  recommended for use.  However, if you were previously using it, the following
    29  section may be helpful in understanding how it works in combination with the new
    30  API.
    31  
    32  ### Client-Side
    33  
    34  There are two legacy functions and one new function to configure compression:
    35  
    36  ```go
    37  func WithCompressor(grpc.Compressor) DialOption {}
    38  func WithDecompressor(grpc.Decompressor) DialOption {}
    39  func UseCompressor(name) CallOption {}
    40  ```
    41  
    42  For outgoing requests, the following rules are applied in order:
    43  1. 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.
    49  1. If `WithCompressor` is used, messages will be compressed using that
    50     compressor implementation.
    51  1. Otherwise, outbound messages will be uncompressed.
    52  
    53  For incoming responses, the following rules are applied in order:
    54  1. If `WithDecompressor` is used and it matches the message's encoding, it will
    55     be used.
    56  1. If a registered compressor matches the response's encoding, it will be used.
    57  1. Otherwise, the stream will be closed and an `Unimplemented` status error will
    58     be returned to the application.
    59  
    60  ### Server-Side
    61  
    62  There are two legacy functions to configure compression:
    63  ```go
    64  func RPCCompressor(grpc.Compressor) ServerOption {}
    65  func RPCDecompressor(grpc.Decompressor) ServerOption {}
    66  ```
    67  
    68  For incoming requests, the following rules are applied in order:
    69  1. If `RPCDecompressor` is used and that decompressor matches the request's
    70     encoding: it will be used.
    71  1. If a registered compressor matches the request's encoding, it will be used.
    72  1. Otherwise, an `Unimplemented` status will be returned to the client.
    73  
    74  For outgoing responses, the following rules are applied in order:
    75  1. If `RPCCompressor` is used, that compressor will be used to compress all
    76     response messages.
    77  1. 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.
    80  1. Otherwise, no compression will be used for the outgoing response.