cubefs

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

33
// Identity specifies the optional encoding for uncompressed streams.
34
// It is intended for grpc internal use only.
35
const Identity = "identity"
36

37
// Compressor is used for compressing and decompressing when sending or
38
// receiving messages.
39
type Compressor interface {
40
	// Compress writes the data written to wc to w after compressing it.  If an
41
	// error occurs while initializing the compressor, that error is returned
42
	// instead.
43
	Compress(w io.Writer) (io.WriteCloser, error)
44
	// Decompress reads data from r, decompresses it, and provides the
45
	// uncompressed data via the returned io.Reader.  If an error occurs while
46
	// initializing the decompressor, that error is returned instead.
47
	Decompress(r io.Reader) (io.Reader, error)
48
	// Name is the name of the compression codec and is used to set the content
49
	// coding header.  The result must be static; the result cannot change
50
	// between calls.
51
	Name() string
52
	// If a Compressor implements
53
	// DecompressedSize(compressedBytes []byte) int, gRPC will call it
54
	// to determine the size of the buffer allocated for the result of decompression.
55
	// Return -1 to indicate unknown size.
56
	//
57
	// Experimental
58
	//
59
	// Notice: This API is EXPERIMENTAL and may be changed or removed in a
60
	// later release.
61
}
62

63
var registeredCompressor = make(map[string]Compressor)
64

65
// RegisterCompressor registers the compressor with gRPC by its name.  It can
66
// be activated when sending an RPC via grpc.UseCompressor().  It will be
67
// automatically accessed when receiving a message based on the content coding
68
// header.  Servers also use it to send a response with the same encoding as
69
// the request.
70
//
71
// NOTE: this function must only be called during initialization time (i.e. in
72
// an init() function), and is not thread-safe.  If multiple Compressors are
73
// registered with the same name, the one registered last will take effect.
74
func RegisterCompressor(c Compressor) {
75
	registeredCompressor[c.Name()] = c
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 interface{}) ([]byte, error)
89
	// Unmarshal parses the wire format into v.
90
	Unmarshal(data []byte, v interface{}) 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 Compressors 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