1 /* 2 * 3 * Copyright 2017 gRPC authors. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 */ 18 19 // Package encoding defines the interface for the compressor and codec, and 20 // functions to register and retrieve compressors and codecs. 21 // 22 // # Experimental 23 // 24 // Notice: This package is EXPERIMENTAL and may be changed or removed in a 25 // later release. 26 package encoding 27 28 import ( 29 "io" 30 "strings" 31 32 "google.golang.org/grpc/internal/grpcutil" 33 ) 34 35 // Identity specifies the optional encoding for uncompressed streams. 36 // It is intended for grpc internal use only. 37 const Identity = "identity" 38 39 // Compressor is used for compressing and decompressing when sending or 40 // receiving messages. 41 // 42 // If a Compressor implements `DecompressedSize(compressedBytes []byte) int`, 43 // gRPC will invoke it to determine the size of the buffer allocated for the 44 // result of decompression. A return value of -1 indicates unknown size. 45 type Compressor interface { 46 // Compress writes the data written to wc to w after compressing it. If an 47 // error occurs while initializing the compressor, that error is returned 48 // instead. 49 Compress(w io.Writer) (io.WriteCloser, error) 50 // Decompress reads data from r, decompresses it, and provides the 51 // uncompressed data via the returned io.Reader. If an error occurs while 52 // initializing the decompressor, that error is returned instead. 53 Decompress(r io.Reader) (io.Reader, error) 54 // Name is the name of the compression codec and is used to set the content 55 // coding header. The result must be static; the result cannot change 56 // between calls. 57 Name() string 58 } 59 60 var registeredCompressor = make(map[string]Compressor) 61 62 // RegisterCompressor registers the compressor with gRPC by its name. It can 63 // be activated when sending an RPC via grpc.UseCompressor(). It will be 64 // automatically accessed when receiving a message based on the content coding 65 // header. Servers also use it to send a response with the same encoding as 66 // the request. 67 // 68 // NOTE: this function must only be called during initialization time (i.e. in 69 // an init() function), and is not thread-safe. If multiple Compressors are 70 // registered with the same name, the one registered last will take effect. 71 func RegisterCompressor(c Compressor) { 72 registeredCompressor[c.Name()] = c 73 if !grpcutil.IsCompressorNameRegistered(c.Name()) { 74 grpcutil.RegisteredCompressorNames = append(grpcutil.RegisteredCompressorNames, c.Name()) 75 } 76 } 77 78 // GetCompressor returns Compressor for the given compressor name. 79 func GetCompressor(name string) Compressor { 80 return registeredCompressor[name] 81 } 82 83 // Codec defines the interface gRPC uses to encode and decode messages. Note 84 // that implementations of this interface must be thread safe; a Codec's 85 // methods can be called from concurrent goroutines. 86 type Codec interface { 87 // Marshal returns the wire format of v. 88 Marshal(v any) ([]byte, error) 89 // Unmarshal parses the wire format into v. 90 Unmarshal(data []byte, v any) error 91 // Name returns the name of the Codec implementation. The returned string 92 // will be used as part of content type in transmission. The result must be 93 // static; the result cannot change between calls. 94 Name() string 95 } 96 97 var registeredCodecs = make(map[string]Codec) 98 99 // RegisterCodec registers the provided Codec for use with all gRPC clients and 100 // servers. 101 // 102 // The Codec will be stored and looked up by result of its Name() method, which 103 // should match the content-subtype of the encoding handled by the Codec. This 104 // is case-insensitive, and is stored and looked up as lowercase. If the 105 // result of calling Name() is an empty string, RegisterCodec will panic. See 106 // Content-Type on 107 // https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests for 108 // more details. 109 // 110 // NOTE: this function must only be called during initialization time (i.e. in 111 // an init() function), and is not thread-safe. If multiple Codecs are 112 // registered with the same name, the one registered last will take effect. 113 func RegisterCodec(codec Codec) { 114 if codec == nil { 115 panic("cannot register a nil Codec") 116 } 117 if codec.Name() == "" { 118 panic("cannot register Codec with empty string result for Name()") 119 } 120 contentSubtype := strings.ToLower(codec.Name()) 121 registeredCodecs[contentSubtype] = codec 122 } 123 124 // GetCodec gets a registered Codec by content-subtype, or nil if no Codec is 125 // registered for the content-subtype. 126 // 127 // The content-subtype is expected to be lowercase. 128 func GetCodec(contentSubtype string) Codec { 129 return registeredCodecs[contentSubtype] 130 } 131