1 /*
2 *
3 * Copyright 2024 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
20 21 import (
22 "strings"
23 24 "google.golang.org/grpc/mem"
25 )
26 27 // CodecV2 defines the interface gRPC uses to encode and decode messages. Note
28 // that implementations of this interface must be thread safe; a CodecV2's
29 // methods can be called from concurrent goroutines.
30 type CodecV2 interface {
31 // Marshal returns the wire format of v. The buffers in the returned
32 // [mem.BufferSlice] must have at least one reference each, which will be freed
33 // by gRPC when they are no longer needed.
34 Marshal(v any) (out mem.BufferSlice, err error)
35 // Unmarshal parses the wire format into v. Note that data will be freed as soon
36 // as this function returns. If the codec wishes to guarantee access to the data
37 // after this function, it must take its own reference that it frees when it is
38 // no longer needed.
39 Unmarshal(data mem.BufferSlice, v any) error
40 // Name returns the name of the Codec implementation. The returned string
41 // will be used as part of content type in transmission. The result must be
42 // static; the result cannot change between calls.
43 Name() string
44 }
45 46 // RegisterCodecV2 registers the provided CodecV2 for use with all gRPC clients and
47 // servers.
48 //
49 // The CodecV2 will be stored and looked up by result of its Name() method, which
50 // should match the content-subtype of the encoding handled by the CodecV2. This
51 // is case-insensitive, and is stored and looked up as lowercase. If the
52 // result of calling Name() is an empty string, RegisterCodecV2 will panic. See
53 // Content-Type on
54 // https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests for
55 // more details.
56 //
57 // If both a Codec and CodecV2 are registered with the same name, the CodecV2
58 // will be used.
59 //
60 // NOTE: this function must only be called during initialization time (i.e. in
61 // an init() function), and is not thread-safe. If multiple Codecs are
62 // registered with the same name, the one registered last will take effect.
63 func RegisterCodecV2(codec CodecV2) {
64 if codec == nil {
65 panic("cannot register a nil CodecV2")
66 }
67 if codec.Name() == "" {
68 panic("cannot register CodecV2 with empty string result for Name()")
69 }
70 contentSubtype := strings.ToLower(codec.Name())
71 registeredCodecs[contentSubtype] = codec
72 }
73 74 // GetCodecV2 gets a registered CodecV2 by content-subtype, or nil if no CodecV2 is
75 // registered for the content-subtype.
76 //
77 // The content-subtype is expected to be lowercase.
78 func GetCodecV2(contentSubtype string) CodecV2 {
79 c, _ := registeredCodecs[contentSubtype].(CodecV2)
80 return c
81 }
82