blob: 195e8448b6466e327396ce15e4acad3c9cfaf5fe [file] [log] [blame]
Holger Hildebrandtfa074992020-03-27 15:42:06 +00001/*
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// This package is EXPERIMENTAL.
23package encoding
24
25import (
26 "io"
27 "strings"
28)
29
30// Identity specifies the optional encoding for uncompressed streams.
31// It is intended for grpc internal use only.
32const Identity = "identity"
33
34// Compressor is used for compressing and decompressing when sending or
35// receiving messages.
36type Compressor interface {
37 // Compress writes the data written to wc to w after compressing it. If an
38 // error occurs while initializing the compressor, that error is returned
39 // instead.
40 Compress(w io.Writer) (io.WriteCloser, error)
41 // Decompress reads data from r, decompresses it, and provides the
42 // uncompressed data via the returned io.Reader. If an error occurs while
43 // initializing the decompressor, that error is returned instead.
44 Decompress(r io.Reader) (io.Reader, error)
45 // Name is the name of the compression codec and is used to set the content
46 // coding header. The result must be static; the result cannot change
47 // between calls.
48 Name() string
49 // EXPERIMENTAL: if a Compressor implements
50 // DecompressedSize(compressedBytes []byte) int, gRPC will call it
51 // to determine the size of the buffer allocated for the result of decompression.
52 // Return -1 to indicate unknown size.
53}
54
55var registeredCompressor = make(map[string]Compressor)
56
57// RegisterCompressor registers the compressor with gRPC by its name. It can
58// be activated when sending an RPC via grpc.UseCompressor(). It will be
59// automatically accessed when receiving a message based on the content coding
60// header. Servers also use it to send a response with the same encoding as
61// the request.
62//
63// NOTE: this function must only be called during initialization time (i.e. in
64// an init() function), and is not thread-safe. If multiple Compressors are
65// registered with the same name, the one registered last will take effect.
66func RegisterCompressor(c Compressor) {
67 registeredCompressor[c.Name()] = c
68}
69
70// GetCompressor returns Compressor for the given compressor name.
71func GetCompressor(name string) Compressor {
72 return registeredCompressor[name]
73}
74
75// Codec defines the interface gRPC uses to encode and decode messages. Note
76// that implementations of this interface must be thread safe; a Codec's
77// methods can be called from concurrent goroutines.
78type Codec interface {
79 // Marshal returns the wire format of v.
80 Marshal(v interface{}) ([]byte, error)
81 // Unmarshal parses the wire format into v.
82 Unmarshal(data []byte, v interface{}) error
83 // Name returns the name of the Codec implementation. The returned string
84 // will be used as part of content type in transmission. The result must be
85 // static; the result cannot change between calls.
86 Name() string
87}
88
89var registeredCodecs = make(map[string]Codec)
90
91// RegisterCodec registers the provided Codec for use with all gRPC clients and
92// servers.
93//
94// The Codec will be stored and looked up by result of its Name() method, which
95// should match the content-subtype of the encoding handled by the Codec. This
96// is case-insensitive, and is stored and looked up as lowercase. If the
97// result of calling Name() is an empty string, RegisterCodec will panic. See
98// Content-Type on
99// https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests for
100// more details.
101//
102// NOTE: this function must only be called during initialization time (i.e. in
103// an init() function), and is not thread-safe. If multiple Compressors are
104// registered with the same name, the one registered last will take effect.
105func RegisterCodec(codec Codec) {
106 if codec == nil {
107 panic("cannot register a nil Codec")
108 }
109 if codec.Name() == "" {
110 panic("cannot register Codec with empty string result for Name()")
111 }
112 contentSubtype := strings.ToLower(codec.Name())
113 registeredCodecs[contentSubtype] = codec
114}
115
116// GetCodec gets a registered Codec by content-subtype, or nil if no Codec is
117// registered for the content-subtype.
118//
119// The content-subtype is expected to be lowercase.
120func GetCodec(contentSubtype string) Codec {
121 return registeredCodecs[contentSubtype]
122}